Skip to main content

ORP API Reference

API docs by Redocly

Operational Route Planner API (1)

Download OpenAPI specification:Download

The Operational Route Planner takes in as input tasks, work shifts and some additional data and finds the best plan for doing these tasks by providing routes of tasks for each work shift. The planner takes travel time, time windows, visit history and employee priority into account, and can be configured to prioritize the objectives based on the users' preference. The Operational Route Planner is for example used in Home Nursing Care to create daily routes for the health care employees.

Supported features

The ORP is highly flexible and supports multiple use cases. The most common ones are:

  • The possibility to configure individual employees shift and rules for potential overtime, their means of travel and so on using the employee work shift and shift overtime elements
  • The possibility to configure individual tasks and the potential relation between them using the task, time dependent task pair and incompatible task list elements
  • The possibility to specify which employees can perform a task using the task shifts compatibility matrix row element
  • The possibility to specify which employees are preferred to be assigned specific tasks using the shift penalty matrix row
  • The possibility to configure certain tasks to either be forced or preferred to the same employee during a single day using the internal visit history group element
  • The possibility to support multiple transport modes for travel between tasks (such as walk, bicycle and car) by using the travel time matrix element
  • The possibility to configure the route planner objectives to suit a team's specific preferences for routes using the configuration element

The time definition

The term time is used in this API. For instance, the start and end of a task are defined by a time. Time should always be defined as seconds. It is important that the time metric seconds is consistent in all places where time is defined. The user of the API has to define times based on a zero point. As an example the zero point could be set to be 0 and let it represent 01.01.2021 00:00. Let's say you would like to send in a task with a time window which is from 01.01.2021 07:00 to 01.01.2021 08:00. Then this time window should be referred to like this:

  • fromTime = 25200, toTime = 28800 (seconds)

This means that you also could use epoch time if you want. Keep in mind that seconds should be used as time unit when defining work shifts for employees, tasks and travel times.

Authentication

Authentication uses OAuth tokens from *Visma Connect*. Authorization is done on tenant level, so one OAuth token is needed per tenant. This can be tested by using the Authorize button on the right. To use the API you have to register a user on the *Visma Developer Portal* and request access to the API along with the required scopes. The scopes required are documented under each endpoint. If you don't have an application registered on Visma Connect you have to do it by:

1. Log into https://oauth.developers.stagaws.visma.com 2. Click on My applications 3. Create a new Service Application (machine-to-machine) 4. Set a name, client id and description of the application 5. Create a client secret under the section Credentials

When you have an application registered in Visma Connect you are now able to apply for an integration against the Optimization Factory APIs:

  1. Navigate to integrations for the selected application
  2. Search for the API called optimization-factory-api-prod
  3. Apply for the scope you would like access to
  4. The Optimization Factory team will now receive a notification and approve the scope requested

To use the Optimization Factory API you need an access token generated by Visma Connect's API. This could be done by either using the integrated Authorize-functionality in this website or you could generate it by following these steps:

  1. Send a POST request to https://connect.identity.stagaws.visma.com/connect/token
  2. Include the follwoing parameter in the body (the parameters must be in the payload (body) of the request and should be in form-urlencoded format. Not as querystring parameters)
    • client_id:
    • client_secret:
    • grant_type: client_credentials
  3. The token received should be used to request the Optimization Factory API by including the following header
    • Authorization: Bearer

For more information about Visma Connect OAuth 2.0 Bearer Token Authentication see https://confluence.visma.com/display/PROV/Visma+Connect+OAuth+2.0+Bearer+Token+Authentication

Status codes

  • 200 OK
  • 202 Accepted - The request has been accepted for processing, but the processing has not been completed
  • 400 Bad request/Data validation error
  • 403 Forbidden
  • 404 Not found
  • 429 Too Many Requests
  • 500 Internal Error - Unexpected condition was encountered and no more specific message is suitable

Handling 5XX errors

Sometimes 5XX errors might occur due to network issues such as delays or connection timeouts. Therefore we encourage our clients to always do one retry if the API returns a 5XX error.

Throttling levels

Rate limiting is performed on the API calls for an employee for each API consumer. Status regarding the rate limit is returned as headers. Once the rate limit is hit, all requests will return HTTP status code 429 for the remainder of the current period.

The user context

Each endpoint require the headers customer_id and user_id. The customer_id header should represent specific customer (company/municipality) that is using API and the user_id header should represent and identify unique user or region of that customer. The client implementing integration with the API is responsible for distinguishing between its customers and users by using these header fields. Header values allow us to track usage statistics and understand how different groups of end-users are using the service. That helps improve the optimization service offering and respond to any incidents faster.

Slack channel for communications

If you have any questions regarding the service. Please reach out to us in the slack channel #optimization-factory-community.

Operational Route Planner

Services for the operational route planner

Starts the solver

Authorizations:
visma_connect
header Parameters
user_id
required
string

Id of the user requesting the optimization job

Request Body schema: application/json
required

Starts the operational route planner solver. The body should represent the necessary data to solve the route optimization problem. The solver starts the process in finding the allocation of tasks to employees and the order of the tasks. The result can be fetched via the /result endpoint.

required
Array of objects (Employee Work Shift)

List of employee work shifts.

required
Array of objects (Task)

List of tasks.

Array of objects (Time Dependent Task Pair)

List of time dependent task pairs. These pairs can be used to determine time dependencies between tasks, for example if task with id=2 needs to be done minimum 2 hours and maximum 3 hours after task with id=1. They can then be performed by the same or different employees. If the tasks need to be synchronized and done by different employees at the same time, the tasks can also be listed in incompatibleTaskList to ensure that the tasks are performed by different employees.

Array of objects (Incompatible Task List Row)

List of tasks that cannot be performed by the same employee, i.e. should not be scheduled in the same route. incompatibleTaskList can also be used in combination with timeDependentTaskPairs to ensure two or more tasks are synchronized in time and performed by different employees.

required
Array of objects (Task to Shifts Compatibility Matrix Row)

Matrix that defines the compatibility between shifts and tasks, i.e. it lists for each task to which shifts it can be assigned.

Array of objects (Internal Visit History Group)

List of internal visit history groups. Tasks within the same internal visit history group are prioritized to be performed by the same employee, or as few distinct employees as possible.

required
Array of objects (Transport Travel Time Matrix)

Travel time matrix that defines the travel time between all locations for (optionally) different transport modes.

Array of objects (Transport Travel Distance Matrix)

Travel distance matrix that defines the travel distance between all locations for (optionally) different transport modes.

Array of objects (Shift Overtime)

List of shift overtime information. If no information is given a shift can have overtime and it is penalized with the maximum penalty possible. However, in that case there is no limit as to how much overtime can be assigned.

required
object (Configuration)

The solver can be configured with double weights for objectives and boolean values for constraints. The sum of the weights (in double format) cannot be greater than 1.0.

Array of objects (Shift Penalty Matrix)

List of shift penalty matrices that defines the penalty of conducting a task during a shift. The taskShiftCompatibilityMatrix dominates penalty matrices. This list can contain multiple penalty matrices, each of which consists of numbers between 0 and 1 reflecting the penalty incurred when conducting a specific task during a specific shift. A penalty of 1 means that the route planner should highly try to avoid allocating the task to the shift. All of these matrices are summarized and normalized before optimization process. The shift penalty matrices could for instance be used to (1) create penalties for doing overqualified work (i.e. nurses should not do assistant work), (2) visit history reasons (i.e. employees that have been few times to a location should get a high penalty), (3) giving penalties to shifts that are conducted by employees working for a separate organization (i.e. when two organizations have merged the planning to utilize employees/resources across organizations). Default values for all the penalties is 0. When using this field, it is required to also submit shiftPenaltyWeights in the solverConfiguration object.

object (Ride-Sharing Configuration)

Responses

Request samples

Content type
application/json
{
  • "employeeWorkShifts": [
    ],
  • "tasks": [
    ],
  • "timeDependentTaskPairs": [
    ],
  • "incompatibleTaskList": [
    ],
  • "taskShiftsCompatabilityMatrix": [
    ],
  • "internalVisitHistoryGroups": [
    ],
  • "travelTimeMatrix": [
    ],
  • "travelDistanceMatrix": [
    ],
  • "shiftOvertimeLists": [
    ],
  • "solverConfiguration": {
    },
  • "shiftPenaltyMatrices": [
    ],
  • "rideSharingConfiguration": {
    }
}

Response samples

Content type
application/json
{
  • "job": {
    }
}

Returns a solution

Authorizations:
visma_connect
path Parameters
job_id
required
string

Id of the job to return result for.

header Parameters
user_id
required
string

Id of the user requesting the result.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Returns the status for a job

Authorizations:
visma_connect
path Parameters
job_id
required
string

ID of job to return status for

header Parameters
user_id
required
string

ID of the user requesting the status

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Stop the solver job

Authorizations:
visma_connect
path Parameters
job_id
required
string

ID of job to stop

header Parameters
user_id
required
string

ID of the user requesting the stop service

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Solver Service Availability

Healthcheck

Authorizations:
visma_connect

Responses