API Reference
/
Optimization

Augmented Operations Management API (1.0.0)

Overview

This API provides backend services for the Augmented Decision Making application, focusing on the efficient scheduling and assignment of tasks Operations to a given Resources.

The system models the following key entities:

  • Locations: Representing physical areas
  • Resources: Specific assignable assets within a location.
  • Tasks: Represent individual events, jobs. Tasks include detailed time information (planned, expected, actual) and model uncertainty using statistical parameters (sigma, skew factor, distribution mean/earliest/latest). Tasks also support versioning to track updates.
  • Operations: Represent a complete operation, linking an inbound task to an outbound task. Operations contain relevant metadata.
  • Assignments: Link an Operation to a specific Resource for a given time period.
  • Tags: Can be used to restrict possible assignments as well as indicate preferences or penalties.
  • Rules: Can be used to specify preferences or penalties in conjunction with the tagging mechanism.

Core Functionality

The API enables users and automated systems to:

  1. Manage Data: Perform CRUD operations on Locations, Resources, Tasks, Operations, and Assignments.
  2. Track Operations Times: Handle various time representations and update task details, including imposing delays. Task updates create new versions, preserving history.
  3. Assignments: Assign or reassign operation to resources.
  4. Detect Conflicts: Identify situations where an assigned conflicting (overlapping) with another based on their expected time windows.
  5. Resolve Conflicts: Offer mechanisms to resolve individual scheduling conflicts through AI.
  6. Optimize Globally: Offer global optimization of the schedule using various solvers to minimize conflicts and reassignments while optimizing for rules.
  7. AI Assistance: Interact with an AI agent (via the /agent/ endpoint) using natural language to query the schedule, identify conflicts, request moves, or trigger conflict resolution processes. The agent utilizes specialized tools to interact with the system's state.
  8. Real-time Updates: Delivers real-time notifications about changes to Assignments and Operations via WebSockets to subscribed clients.
  9. Virtual State Management: Allows temporary modifications to the schedule (virtual assignments) for "what-if" scenarios or agent-driven planning before potentially persisting changes.
Download OpenAPI description
schema.json
schema.yaml
Languages
Servers
Acceptance Environment

https://api.acc.adm.wearetransformers.nl/

Users

User management (authentication, current user details).

Operations

Locations

Managing locations and viewing their associated resources.

Operations

Resources

Managing resources (CRUD, listing).

Operations

Operations

Managing operations. Includes CRUD and listing with time/version filters.

Operations

Tasks

Updating details (time, uncertainty) of individual tasks within operations.

Operations

Assignments

Managing the assignment of operations to resources (CRUD, bulk operations, deactivation, listing per operation).

Operations

Conflict Resolution

Resolving specific scheduling conflicts using heuristic search methods (streaming and non-streaming).

Operations

Optimization

Globally optimizing the schedule using one of the solvers to minimize conflicts and reassignments while optimizing for rules.

Operations

Get all tasks for a planning

Request

Get all tasks for a planning.

Security
tokenAuth
Path
idstring(uuid)required
Query
dayintegerrequired

Start time for filtering operations (Unix timestamp).

curl -i -X GET \
  'https://api.acc.adm.wearetransformers.nl/v1/plannings/{id}/optimizationTaskResults/?day=0' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Task status and result (if ready)

Bodyapplication/jsonArray [
Any of:
taskIdstring(Taskid)required
discardedboolean(Discarded)required
dateStartedstring(date-time)(Datestarted)required
dateDonestring(date-time)(Datedone)required
virtualStateAviationVirtualStateInput (object) or MaritimeBerthVirtualStateInput (object) or VirtualStateInput (object)(Virtualstate)required
Any of:

This is a placeholder for the AviationStandPlanningAdapter's virtual state input.

virtualState.​virtual_assignmentsArray of objects(Virtual Assignments)required
virtualState.​virtual_assignments[].​idstring(uuid4)(Id)required
virtualState.​virtual_assignments[].​operationstring(uuid4)(Operation)required
virtualState.​virtual_assignments[].​planningstring(uuid4)(Planning)required
virtualState.​virtual_assignments[].​resourcestring(uuid4)(Resource)required
virtualState.​virtual_assignments[].​metadataMetadata (object) or Metadata (null)(Metadata)
Any of:
object(Metadata)
virtualState.​virtual_assignments[].​activeboolean(Active)required
virtualState.​display_window_startinteger(Display Window Start)required
virtualState.​display_window_endinteger(Display Window End)required
virtualState.​selected_timeinteger(Selected Time)required
virtualState.​backward_windowinteger(Backward Window)required
virtualState.​forward_windowinteger(Forward Window)required
virtualState.​current_timeinteger(Current Time)required
virtualState.​experimental_tools_enabledboolean(Experimental Tools Enabled)required
virtualState.​controlsobject(AviationControlPanelState)required
virtualState.​controls.​resolution_balancenumber(Resolution Balance)required

0 strives for minimal conflicts whereas 1 strives for minimal overlap

virtualState.​controls.​rule_adherencenumber(Rule Adherence)required

0 strives for the goal of the strategy, while 1 strives for optimal rule value

virtualState.​controls.​max_runtimeinteger(Max Runtime)

Maximum runtime in seconds for the solver, default is 90 seconds

Default 60
virtualState.​controls.​strategystring(AviationSolutionStrategy)required
Enum"least_moves""standard""minimal_resources"
virtualState.​timezonestring(Timezone)
Default "UTC"
virtualState.​gateGate (string) or Gate (null)(Gate)
Default null
Any of:
string(Gate)
Default null
statusstring(Status)required
Enum"PENDING""STARTED""EXPIRED"
optimizationResultnull(Optimizationresult)
Default null
optimizationStatusstring(Optimizationstatus)required
Value "UNKNOWN"
]
Response
application/json
[
  {
    "taskId": "string",
    "discarded": true,
    "dateStarted": "2019-08-24T14:15:22Z",
    "dateDone": "2019-08-24T14:15:22Z",
    "virtualState": { … },
    "status": "PENDING",
    "optimizationResult": null,
    "optimizationStatus": "UNKNOWN"
  }
]

Get task status

Request

Get the status of a background optimization task.

Security
tokenAuth
Path
idstring(uuid)required
task_idstringrequired
curl -i -X DELETE \
  'https://api.acc.adm.wearetransformers.nl/v1/plannings/{id}/optimizationTaskResults/{task_id}/' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Task status and result (if ready)

Bodyapplication/json
Any of:
taskIdstring(Taskid)required
discardedboolean(Discarded)required
dateStartedstring(date-time)(Datestarted)required
dateDonestring(date-time)(Datedone)required
virtualStateAviationVirtualStateInput (object) or MaritimeBerthVirtualStateInput (object) or VirtualStateInput (object)(Virtualstate)required
Any of:

This is a placeholder for the AviationStandPlanningAdapter's virtual state input.

virtualState.​virtual_assignmentsArray of objects(Virtual Assignments)required
virtualState.​virtual_assignments[].​idstring(uuid4)(Id)required
virtualState.​virtual_assignments[].​operationstring(uuid4)(Operation)required
virtualState.​virtual_assignments[].​planningstring(uuid4)(Planning)required
virtualState.​virtual_assignments[].​resourcestring(uuid4)(Resource)required
virtualState.​virtual_assignments[].​metadataMetadata (object) or Metadata (null)(Metadata)
Any of:
object(Metadata)
virtualState.​virtual_assignments[].​activeboolean(Active)required
virtualState.​display_window_startinteger(Display Window Start)required
virtualState.​display_window_endinteger(Display Window End)required
virtualState.​selected_timeinteger(Selected Time)required
virtualState.​backward_windowinteger(Backward Window)required
virtualState.​forward_windowinteger(Forward Window)required
virtualState.​current_timeinteger(Current Time)required
virtualState.​experimental_tools_enabledboolean(Experimental Tools Enabled)required
virtualState.​controlsobject(AviationControlPanelState)required
virtualState.​controls.​resolution_balancenumber(Resolution Balance)required

0 strives for minimal conflicts whereas 1 strives for minimal overlap

virtualState.​controls.​rule_adherencenumber(Rule Adherence)required

0 strives for the goal of the strategy, while 1 strives for optimal rule value

virtualState.​controls.​max_runtimeinteger(Max Runtime)

Maximum runtime in seconds for the solver, default is 90 seconds

Default 60
virtualState.​controls.​strategystring(AviationSolutionStrategy)required
Enum"least_moves""standard""minimal_resources"
virtualState.​timezonestring(Timezone)
Default "UTC"
virtualState.​gateGate (string) or Gate (null)(Gate)
Default null
Any of:
string(Gate)
Default null
statusstring(Status)required
Enum"PENDING""STARTED""EXPIRED"
optimizationResultnull(Optimizationresult)
Default null
optimizationStatusstring(Optimizationstatus)required
Value "UNKNOWN"
Response
application/json
{
  "taskId": "string",
  "discarded": true,
  "dateStarted": "2019-08-24T14:15:22Z",
  "dateDone": "2019-08-24T14:15:22Z",
  "virtualState": {
    "virtual_assignments": [ … ],
    "display_window_start": 0,
    "display_window_end": 0,
    "selected_time": 0,
    "backward_window": 0,
    "forward_window": 0,
    "current_time": 0,
    "experimental_tools_enabled": true,
    "controls": { … },
    "timezone": "UTC",
    "gate": null
  },
  "status": "PENDING",
  "optimizationResult": null,
  "optimizationStatus": "UNKNOWN"
}

Optimize a plan

Request

Start a task to optimize all assignments in a planning.

Security
tokenAuth
Path
idstring(uuid)required
Bodyapplication/jsonrequired
virtual_assignmentsArray of objects(Virtual Assignments)required
virtual_assignments[].​idstring(uuid4)(Id)required
virtual_assignments[].​operationstring(uuid4)(Operation)required
virtual_assignments[].​planningstring(uuid4)(Planning)required
virtual_assignments[].​resourcestring(uuid4)(Resource)required
virtual_assignments[].​metadataMetadata (object) or Metadata (null)(Metadata)
Any of:
object(Metadata)
virtual_assignments[].​activeboolean(Active)required
display_window_startinteger(Display Window Start)required
display_window_endinteger(Display Window End)required
selected_timeinteger(Selected Time)required
backward_windowinteger(Backward Window)required
forward_windowinteger(Forward Window)required
current_timeinteger(Current Time)required
experimental_tools_enabledboolean(Experimental Tools Enabled)required
controlsobject(ControlPanelState)required
controls.​resolution_balancenumber(Resolution Balance)required

0 strives for minimal conflicts whereas 1 strives for minimal overlap

controls.​rule_adherencenumber(Rule Adherence)required

0 strives for the goal of the strategy, while 1 strives for optimal rule value

controls.​max_runtimeinteger(Max Runtime)

Maximum runtime in seconds for the solver, default is 90 seconds

Default 60
controls.​strategystring(SolutionStrategy)required
Value"standard"
timezonestring(Timezone)
Default "UTC"
curl -i -X POST \
  'https://api.acc.adm.wearetransformers.nl/v1/plannings/{id}/optimize/' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "virtual_assignments": [
      {
        "id": "string",
        "operation": "string",
        "planning": "string",
        "resource": "string",
        "metadata": {},
        "active": true
      }
    ],
    "display_window_start": 0,
    "display_window_end": 0,
    "selected_time": 0,
    "backward_window": 0,
    "forward_window": 0,
    "current_time": 0,
    "experimental_tools_enabled": true,
    "controls": {
      "resolution_balance": 0,
      "rule_adherence": 0,
      "max_runtime": 60,
      "strategy": "standard"
    },
    "timezone": "UTC"
  }'

Responses

Returns task ID for polling

Bodyapplication/json
task_idstring(Task Id)required
Response
application/json
{
  "task_id": "abc123"
}

Organizations & Planning

Managing the plannings and organizations you have access to.

Operations

AI Agent

Interacting with the conversational AI assistant for planning and queries.

Operations

Utility

Utility endpoints, such as generating schedule visualizations.

Operations

Token

API authentication token management (e.g., obtaining auth tokens).

Operations

Tags

Our mechanism for indicating constraints, penalties or preferences.

Operations

Rules

Can be used together with Tags to specify preferences or penalties.

Operations

Dependencies

Operations

Operation Groups

Operations
Copyright © Transformers Group