Automatic Rostering (json_alpha)

Download OpenAPI specification:Download

Visma Connect Token Retrieval

Create a POST request to the Visma Connect API:
- For the stage environment, use: https://connect.identity.stagaws.visma.com/connect/token
- For the production environment, use: https://connect.visma.com/connect/token
In the header of your request, specify Content-Type: application/x-www-form-urlencoded.
In the request body, specify the following parameters:
- grant_type: client_credentials
- client_id: YOUR_ID_FROM_STEP_1.3
- client_secret: YOUR_SECRET_FROM_STEP_1.9
- scope: SCOPE_FROM_STEP_1.7
Send the request and retrieve the access_token from the response.
Include the Authorization header with the Bearer YOUR_ACCESS_TOKEN for all your requests to the Automatic Rostering API.
You are now ready to make requests to the Automatic Rostering API.

For more information about Visma Connect OAuth 2.0 Bearer Token Authentication, refer to Visma Connect Confluence.

Create roster

Endpoints for starting, stopping, and retrieving scheduling jobs

Start job

Creates and immediately starts a new job for the solver.

Authorizations:

vismaConnectBearer

header Parameters

CUSTOMER_ID required	string Example: resolve
USER_ID required	string Example: dev_team

Request Body schema: application/json
required

required	object (jobInfo) Details about the job that the solver will solve.
	Array of objects (shift) List of shifts that employees can be assigned to.
	Array of objects (shiftTemplate) List of shift templates that the solver can use to generate shifts.
required	Array of objects (employee) non-empty List of employees to be used in this roster.
	Array of objects (taskGroup) List of task groups used in this roster.
	Array of objects (task) List of tasks used in this roster.
	Array of objects (timeSlot) List of time slots for which demand can be specified (only if using TIME_DEMAND)
required	Array of objects (demand) List of demands used in this roster.
	object Constraints that should be active for this solver run. Used to specify all sorts of preferences, rules and restrictions.
required	object (configuration) Configurations for this solver run.

Responses

Request samples

Payload

Content type

application/json

{"jobInfo": {"id": "123",
"organisationId": "456",
"scheduleType": "CALENDAR",
"demandType": "TIME_DEMAND",
"planningHorizon": {"startDate": "2023-02-27",
"endDate": "2023-04-02",
"fteStartDay": {"date": "2023-03-01"
},
"fteEndDay": {"date": "2023-03-31"
}
}
},
"shifts": [{"id": "shift1",
"intervals": [{"startTime": "08:00",
"endTime": "16:00",
"dayIndicator": 1,
"workTypeId": "1"
}
]
}
],
"employees": [{"id": "1"
}
],
"timeSlots": [{"id": "timeSlot1"
},
{"startTime": "00:00"
},
{"endTime": "00:00"
},
{"workTypeId": "1"
}
],
"demands": [{"days": null,
"dates": ["2023-03-01",
"2023-03-02",
"2023-03-03",
"2023-03-04",
"2023-03-05",
"2023-03-06",
"2023-03-07"
],
"timeDemands": [{"timeSlotId": "timeSlot1",
"min": 1,
"ideal": 2,
"max": 3
}
]
}
],
"constraints": { },
"configuration": {"workTypes": [{"id": "1",
"name": "WORK",
"factor": 1
}
],
"weekend": {"startWeekDay": 5,
"startTime": "00:00",
"endWeekDay": 1,
"endTime": "00:00"
}
}
}

Response samples

202
400
406
415

Content type

application/json

{"jobId": "78f0aawf13a0436f916cd6gf468afc61",
"statusCode": "starting",
"link": {"rel": "request",
"href": "/jobs/78f0aawf13a0436f916cd6gf468afc61/request"
}
}

Get job status

Returns the current state of the specified solver job, including whether it is still running or has stopped.

Authorizations:

vismaConnectBearer

path Parameters

id

required

string

Job ID

Responses

Response samples

200
406

Content type

application/json

{"jobId": "78f0bb4312a04d6f906bd6afe68afa61",
"statusCode": "stopped",
"duration": 7274,
"links": [{"rel": "request",
"href": "/jobs/78f0bb4312a04d6f906bd6afe68afa61/request"
},
{"rel": "full_schedule",
"href": "/jobs/78f0bb4312a04d6f906bd6afe68afa61/result/?full_schedule=True"
},
{"rel": "statistics",
"href": "/jobs/78f0bb4312a04d6f906bd6afe68afa61/result/?full_schedule=False"
}
]
}

Stop job

Stops a running solver job.

Authorizations:

vismaConnectBearer

path Parameters

id

required

string

Job ID

Responses

Get result

Returns the current best solution produced by the solver for the specified job.

Authorizations:

vismaConnectBearer

path Parameters

id

required

string

Job ID

Responses

Response samples

200

Content type

application/json

{"jobInfo": {"id": "string",
"organisationId": "string",
"scheduleType": "CALENDAR",
"demandType": "SHIFT_DEMAND",
"planningHorizon": {"startDate": {"example_1": {"value": "2023-12-24",
"summary": "The 24th of December 2023."
}
},
"endDate": {"example_1": {"value": "2023-12-24",
"summary": "The 24th of December 2023."
}
},
"nrOfWeeks": 1,
"fteStartDay": {"dayIndex": {"example_1": {"value": 9,
"summary": "The 10th day of the planning horizon."
}
}
},
"fteEndDay": {"dayIndex": {"example_1": {"value": 9,
"summary": "The 10th day of the planning horizon."
}
}
}
}
},
"solution": {"score": {"hard": 0,
"soft": 0
},
"missingDemands": [{"scheduleDay": {"dayIndex": {"example_1": {"value": 9,
"summary": "The 10th day of the planning horizon."
}
}
},
"startTime": "14:15:22Z",
"endTime": "14:15:22Z",
"demands": [{"nbrOfMissingEmployees": 0,
"assignmentId": "string",
"taskId": "string",
"attributeRequirements": [{"category": "string",
"values": ["string"
],
"matchType": "NONE",
"id": "string"
}
]
}
]
}
],
"wallDemandOutcome": {"lessThanMin": 0,
"min": 0,
"minIdeal": 0,
"ideal": 0,
"maxIdeal": 0,
"max": 0
},
"fteDemandOutcome": {"min": {"target": 0,
"planned": 0
},
"ideal": {"target": 0,
"planned": 0
},
"max": {"target": 0,
"planned": 0
}
},
"shiftDemandFulfillment": {"totalFulfillmentStatistics": {"requestedHours": 0,
"requestedShiftAssignments": 0,
"plannedHours": 0,
"plannedShiftAssignments": 0
}
},
"userDefinedShifts": [{"id": "string",
"fteHours": 0,
"shiftTypeIds": ["string"
]
}
],
"generatedShifts": [{"id": "string",
"shiftTypeIds": ["string"
],
"shiftTemplateId": "string",
"intervals": [{"startTime": "14:15:22Z",
"endTime": "14:15:22Z",
"dayIndicator": -1,
"breakMinutes": 0,
"workTypeId": "string",
"assignmentId": "string",
"taskId": "string"
}
]
}
],
"employeeOutcomes": [{"employeeId": "string",
"maxAvailableHours": 0,
"totalPlannedHours": 0,
"plannedDays": [{"shiftId": "string",
"scheduleDay": {"dayIndex": {"example_1": {"value": 9,
"summary": "The 10th day of the planning horizon."
}
}
},
"roleId": "string",
"preAssigned": true
}
],
"softConstraintViolations": [{"id": "string",
"softPenalty": 0,
"hardPenalty": 0
}
],
"hardConstraintViolations": [{"id": "string",
"violation": "string"
}
]
}
]
},
"infeasibleConstraints": [{"id": "string",
"employeeIds": ["string"
]
}
],
"id": "string",
"organisationId": "string",
"scheduleType": {"weekRecurring": {"nrOfWeeks": 1,
"fteCountStartDayIndex": 0,
"fteCountEndDayIndex": 0,
"fullScheduleStartDate": "2019-08-24"
}
}
}

Get request

Returns the payload that was sent to the API when starting the job.

Authorizations:

vismaConnectBearer

path Parameters

id

required

string

Job ID

Responses

Response samples

200

Content type

application/json

{"jobInfo": {"id": "123",
"organisationId": "456",
"scheduleType": "CALENDAR",
"demandType": "TIME_DEMAND",
"planningHorizon": {"startDate": "2023-02-27",
"endDate": "2023-04-02",
"fteStartDay": {"date": "2023-03-01"
},
"fteEndDay": {"date": "2023-03-31"
}
}
},
"shifts": [{"id": "shift1",
"intervals": [{"startTime": "08:00",
"endTime": "16:00",
"dayIndicator": 1,
"workTypeId": "1"
}
]
}
],
"employees": [{"id": "1"
}
],
"timeSlots": [{"id": "timeSlot1"
},
{"startTime": "00:00"
},
{"endTime": "00:00"
},
{"workTypeId": "1"
}
],
"demands": [{"days": null,
"dates": ["2023-03-01",
"2023-03-02",
"2023-03-03",
"2023-03-04",
"2023-03-05",
"2023-03-06",
"2023-03-07"
],
"timeDemands": [{"timeSlotId": "timeSlot1",
"min": 1,
"ideal": 2,
"max": 3
}
]
}
],
"constraints": { },
"configuration": {"workTypes": [{"id": "1",
"name": "WORK",
"factor": 1
}
],
"weekend": {"startWeekDay": 5,
"startTime": "00:00",
"endWeekDay": 1,
"endTime": "00:00"
}
}
}

Analyze (WIP)

Endpoint for analyzing job requests

Analyze

WIP - Analyze a job request. Currently returns a dummy response.

Authorizations:

vismaConnectBearer

header Parameters

CUSTOMER_ID required	string Example: resolve
USER_ID required	string Example: dev_team
ACCEPT_LANGUAGE	string Default: en-US Example: no-NO Language code for localizing warning messages

Request Body schema: application/json
required

required	object (jobInfo) Details about the job that the solver will solve.
	Array of objects (shift) List of shifts that employees can be assigned to.
	Array of objects (shiftTemplate) List of shift templates that the solver can use to generate shifts.
required	Array of objects (employee) non-empty List of employees to be used in this roster.
	Array of objects (taskGroup) List of task groups used in this roster.
	Array of objects (task) List of tasks used in this roster.
	Array of objects (timeSlot) List of time slots for which demand can be specified (only if using TIME_DEMAND)
required	Array of objects (demand) List of demands used in this roster.
	object Constraints that should be active for this solver run. Used to specify all sorts of preferences, rules and restrictions.
required	object (configuration) Configurations for this solver run.

Responses

Request samples

Payload

Content type

application/json

{"jobInfo": {"id": "123",
"organisationId": "456",
"scheduleType": "CALENDAR",
"demandType": "TIME_DEMAND",
"planningHorizon": {"startDate": "2023-02-27",
"endDate": "2023-04-02",
"fteStartDay": {"date": "2023-03-01"
},
"fteEndDay": {"date": "2023-03-31"
}
}
},
"shifts": [{"id": "shift1",
"intervals": [{"startTime": "08:00",
"endTime": "16:00",
"dayIndicator": 1,
"workTypeId": "1"
}
]
}
],
"employees": [{"id": "1"
}
],
"timeSlots": [{"id": "timeSlot1"
},
{"startTime": "00:00"
},
{"endTime": "00:00"
},
{"workTypeId": "1"
}
],
"demands": [{"days": null,
"dates": ["2023-03-01",
"2023-03-02",
"2023-03-03",
"2023-03-04",
"2023-03-05",
"2023-03-06",
"2023-03-07"
],
"timeDemands": [{"timeSlotId": "timeSlot1",
"min": 1,
"ideal": 2,
"max": 3
}
]
}
],
"constraints": { },
"configuration": {"workTypes": [{"id": "1",
"name": "WORK",
"factor": 1
}
],
"weekend": {"startWeekDay": 5,
"startTime": "00:00",
"endWeekDay": 1,
"endTime": "00:00"
}
}
}

Response samples

200

Content type

application/json

{"jobId": "2b74",
"warnings": [{"message": "No one can work {{0}} on {{1}} as the shift requires {{2}} that no one meets",
"entities": [{"property": "shiftId",
"value": "e461"
}
]
}
]
}

Feasibility

Endpoints for checking feasibility of jobs

Feasibility Check

Check jobs feasibility.

Authorizations:

vismaConnectBearer

header Parameters

CUSTOMER_ID required	string Example: resolve
USER_ID required	string Example: dev_team

Request Body schema: application/json
required

required	object (jobInfo) Details about the job that the solver will solve.
	Array of objects (shift) List of shifts that employees can be assigned to.
	Array of objects (shiftTemplate) List of shift templates that the solver can use to generate shifts.
required	Array of objects (employee) non-empty List of employees to be used in this roster.
	Array of objects (taskGroup) List of task groups used in this roster.
	Array of objects (task) List of tasks used in this roster.
	Array of objects (timeSlot) List of time slots for which demand can be specified (only if using TIME_DEMAND)
required	Array of objects (demand) List of demands used in this roster.
	object Constraints that should be active for this solver run. Used to specify all sorts of preferences, rules and restrictions.
required	object (configuration) Configurations for this solver run.

Responses

Request samples

Payload

Content type

application/json

{"jobInfo": {"id": "123",
"organisationId": "456",
"scheduleType": "CALENDAR",
"demandType": "TIME_DEMAND",
"planningHorizon": {"startDate": "2023-02-27",
"endDate": "2023-04-02",
"fteStartDay": {"date": "2023-03-01"
},
"fteEndDay": {"date": "2023-03-31"
}
}
},
"shifts": [{"id": "shift1",
"intervals": [{"startTime": "08:00",
"endTime": "16:00",
"dayIndicator": 1,
"workTypeId": "1"
}
]
}
],
"employees": [{"id": "1"
}
],
"timeSlots": [{"id": "timeSlot1"
},
{"startTime": "00:00"
},
{"endTime": "00:00"
},
{"workTypeId": "1"
}
],
"demands": [{"days": null,
"dates": ["2023-03-01",
"2023-03-02",
"2023-03-03",
"2023-03-04",
"2023-03-05",
"2023-03-06",
"2023-03-07"
],
"timeDemands": [{"timeSlotId": "timeSlot1",
"min": 1,
"ideal": 2,
"max": 3
}
]
}
],
"constraints": { },
"configuration": {"workTypes": [{"id": "1",
"name": "WORK",
"factor": 1
}
],
"weekend": {"startWeekDay": 5,
"startTime": "00:00",
"endWeekDay": 1,
"endTime": "00:00"
}
}
}

Response samples

200
400
406
415

Content type

application/json

{"version": "string",
"status": ["string"
],
"warnings": [{"title": "Employee-availability-check",
"category": "string",
"description": "string",
"violations": [{"day": 0,
"date": "2019-08-24",
"demandSegment": {"startTime": 0,
"endTime": 0,
"minDemand": 0,
"timestamp": "string"
},
"shift": {"name": "string"
},
"weekendNumber": 0,
"requiredEmployees": 0,
"missingEmployees": 0,
"missingEmployeesDueToWeekendDistribution": 0,
"employeeNumber": "string",
"requiredMinutes": 0,
"achievableMinutes": 0,
"startTime": "string",
"endTime": "string",
"personnelGroup": "string",
"assignment": "string",
"taskId": "string",
"competencies": ["string"
],
"workType": "string",
"numberOfEmployees": 0,
"missingMinutes": 0,
"totalMinutes": 0,
"constraintId": "string",
"lockedShiftName": "string",
"employeeId": "string",
"violatedProperties": ["MIN"
]
}
]
}
],
"infeasibilities": [{"title": "Cyclic-connected-shifts-Check",
"category": "string",
"description": "string",
"violations": [{"day": 0,
"date": "2019-08-24",
"demandSegment": {"startTime": 0,
"endTime": 0,
"minDemand": 0,
"timestamp": "string"
},
"shift": {"name": "string"
},
"weekendNumber": 0,
"requiredEmployees": 0,
"missingEmployees": 0,
"missingEmployeesDueToWeekendDistribution": 0,
"employeeNumber": "string",
"requiredMinutes": 0,
"achievableMinutes": 0,
"startTime": "string",
"endTime": "string",
"personnelGroup": "string",
"assignment": "string",
"taskId": "string",
"competencies": ["string"
],
"workType": "string",
"numberOfEmployees": 0,
"missingMinutes": 0,
"totalMinutes": 0,
"constraintId": "string",
"lockedShiftName": "string",
"employeeId": "string",
"violatedProperties": ["MIN"
]
}
]
}
],
"errors": ["string"
],
"timeouts": ["string"
]
}

Roster request

required	object (jobInfo) Details about the job that the solver will solve.
	Array of objects (shift) List of shifts that employees can be assigned to.
	Array of objects (shiftTemplate) List of shift templates that the solver can use to generate shifts.
required	Array of objects (employee) non-empty List of employees to be used in this roster.
	Array of objects (taskGroup) List of task groups used in this roster.
	Array of objects (task) List of tasks used in this roster.
	Array of objects (timeSlot) List of time slots for which demand can be specified (only if using TIME_DEMAND)
required	Array of objects (demand) List of demands used in this roster.
	object Constraints that should be active for this solver run. Used to specify all sorts of preferences, rules and restrictions.
required	object (configuration) Configurations for this solver run.

{"jobInfo": {"id": "123",
"organisationId": "456",
"scheduleType": "CALENDAR",
"demandType": "TIME_DEMAND",
"planningHorizon": {"startDate": "2023-02-27",
"endDate": "2023-04-02",
"fteStartDay": {"date": "2023-03-01"
},
"fteEndDay": {"date": "2023-03-31"
}
}
},
"shifts": [{"id": "shift1",
"intervals": [{"startTime": "08:00",
"endTime": "16:00",
"dayIndicator": 1,
"workTypeId": "1"
}
]
}
],
"employees": [{"id": "1"
}
],
"timeSlots": [{"id": "timeSlot1"
},
{"startTime": "00:00"
},
{"endTime": "00:00"
},
{"workTypeId": "1"
}
],
"demands": [{"days": null,
"dates": ["2023-03-01",
"2023-03-02",
"2023-03-03",
"2023-03-04",
"2023-03-05",
"2023-03-06",
"2023-03-07"
],
"timeDemands": [{"timeSlotId": "timeSlot1",
"min": 1,
"ideal": 2,
"max": 3
}
]
}
],
"constraints": { },
"configuration": {"workTypes": [{"id": "1",
"name": "WORK",
"factor": 1
}
],
"weekend": {"startWeekDay": 5,
"startTime": "00:00",
"endWeekDay": 1,
"endTime": "00:00"
}
}
}

Automatic Rostering (json_alpha)

Visma Connect Token Retrieval

Create roster

Start job

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get job status

Authorizations:

path Parameters

Responses

Response samples

Stop job

Authorizations:

path Parameters

Responses

Get result

Authorizations:

path Parameters

Responses

Response samples

Get request

Authorizations:

path Parameters

Responses

Response samples

Analyze (WIP)

Analyze

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Feasibility

Feasibility Check

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Roster request

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required