Crew Shell Integration API | OverIT Knowledge Hub

Overview

Next-Gen FSM comes with two Crew Shell Integration APIs available at these URLs:

/api/integration/workforce/crew-shells/r1/crew-shells/members-allocation
/api/integration/workforce/crew-shells/r1/crew-shells/members-deallocation

Members-Allocation API

Use this integration API to declare that a specified crew shell is “on service” on a specific day.

To define the availability hours, specify the workshift. If you omit the workshift specification, NextGen FSM uses the Integration API Base Workshift parameter defined in the crew shell configuration.

You can also define the crew shell members' composition use and whether the composition is a draft composition or a validated one.

In 2024 Wave One, the API manages only technicians who belong to the same operation center of the crew shell, but from 2024 Wave Two, the API also manages technicians who belong to other operation centers that have been lent to the crew shell’s operation center for the requested period of time.

Request Payload

{
  "extension": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  },
  "operationCenterCode": "string",
  "crewShellCode": "string",
  "day": "2024-01-17T10:33:24.350Z",
  "workshiftCode": "string",
  "validate": true,
  "members": [
    {
      "extension": {
        "additionalProp1": {},
        "additionalProp2": {},
        "additionalProp3": {}
      },
      "operationCenter": "string",
      "serialNumber": "string",
      "foreman": true
    }
  ]
}

Request Body Parameters

Request body parameters are used when clients send data to the API. They are shipped in a JSON Object only in POST, PUT, or PATCH requests.

		Field	Description	Mandatory
1		`operationCenterCode`	Operation Center Code of the Crew Shell. Must exist. With crew shell code is an unique identifier for the Crew Shell in Next-Gen FSM	Y
2		`crewShellCode`	Crew Shell Code. Must exist in the operation center specified. With operation center code is an unique identifier for the Crew Shell in Next-Gen FSM.	Y
3		`day`	Day in format `"yyyy-mm-dd"`. It is the day in which the crew shell should be in service. Should not be in the past.	Y
4		`workshiftCode`	Work-shift code. If specified, must exist Use to declare the availability hours of the crew shell. If omitted, NextGen FSM uses the `Integration API Base Workshift` parameter defined in the crew shell configuration	N
5		`validate`	true or false value. If false, the allocation sent is intended as a draft crew shell composition. If true, the allocation sent is intended as a confirmed crew shell composition. If omitted, a true value is assumed.	N
6	members (list of)	`operationCenter`	Operation Center Code of the scheduling resource. Must exist. With crew serial number, a unique identifier for the Scheduling Resource in NextGen FSM	Y
7		`serialNumber`	Serial Number of the scheduling resource to allocate. Must exist in the Operation Center specified. Must exist in the specified operation center. With operation center code, a unique identifier for the Scheduling Resource in NextGen FSM	Y
8		`foreman`	true or false value. If false, the scheduling resource is intended as an assistant for the crew shell composition. If true, the scheduling resource is intended to be the foreman for the crew shell composition. If omitted, a true value is assumed. Only one member in the list can be the foreman. If no one member in the list is the foreman, the first scheduling resource in the list is promoted to be the foreman.	N

Request Example

Change the composition of the shell crew code INEXISTENT_CREW belonging to the operation center with code OCENE for April 1 with shift REG from an external system. The crew shell composition should go in a confirmed status and allocate the two members belonging to the OCENE operation center, with serial number 500750 and MI0037, scheduling resource 500750 is the foreman.

Example of “Members-Allocation” request payload

{
  "operationCenter": "OCENE",
  "crewShellCode": "INEXISTENT_CREW",
  "day": "2024-04-01",
  "validate": true,
  "members": [
    {
      "operationCenter": "OCENE",
      "serialNumber": "500750",
      "foreman": true
    },
    {
      "operationCenter": "OCENE",
      "serialNumber": "MI0037",
      "foreman": false
    }
  ]
}

Example of “Allocate” response payload

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "The crew shell with code INEXISTENT_CREW not exists",
    "instance": "/fsmdev/api/integration/crew-shells/r1/members-allocation",
    "code": "ERR004"
}

Response payload fields

Compliant with RFC Standard RFC 9457: Problem Details for HTTP APIs

Extension fields:

Field	Description	Note
type	Extension member of a Problem Details Object that contains the error code	Only for ERROR
title	Title of the error	Only for ERROR
status	Error status	Only for ERROR
detail	Details about the error occurred	Only for ERROR
instance	Instance	Only for ERROR
code	Error code	Only for ERROR

Response examples

For OK responses.

{
}

For KO responses.

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "External system string does not exist",
  "instance": "/integration/assets/r1/asset-creation",
  "code": "IA001_001"
}

Members-Deallocation API

Use this integration API to declare that a specified crew shell composition is not on service on a specific day.

You can define whether to remove the availability of the crew shell. You can also define which the crew shell members composition to useand if the composition is a draft composition or a validated one.

Request Payload

{
  "extension": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  },
  "operationCenter": "string",
  "crewShellCode": "string",
  "day": "2024-01-17T10:29:31.397Z",
  "validate": true,
  "removeWorkshift": true
}

Request Body Parameters

Request body parameters are used when clients send data to the API. They are shipped in a JSON Object only in POST, PUT, or PATCH requests.

	Field	Description	Mandatory
1	`operationCenterCode`	Operation Center Code of the Crew Shell. Must exist. With crew shell code is an unique identifier for the Crew Shell in NextGen FSM.	Y
2	`crewShellCode`	Crew Shell Code. Must exist in the operation center specified. With operation center code is an unique identifier for the Crew Shell in NextGen FSM.	Y
3	`day`	Day in format `yyyy-mm-dd`. The day in which the crew shell should composition should be deallocated. Should not be in the past.	Y
4	`validate`	true or false value. If false, the allocation sent is intended as a draft crew shell composition If true, the de-allocation sent is intended as a confirmed crew shell composition. If omitted, a true value is assumed.	N
5	`removeWorkshift`	true or false value. If true, the deallocation sent is intended to remove the crew shell availability defined. If false, the de-allocation sent is intended to remove only crew members and leave the crew shell availability. If omitted, a true value is assumed.	N

Request Example

Deallocate the composition of the shell crew code INEXISTENT_CREW belonging to the operation center with code OCENE for April 1 with shift REG from an external system. The new crew shell composition should go in a confirmed status deallocating all the members and removing also the availability of the crew shell INEXISTENT_CREW for that day so the crew shell is not on service.

Example of “Members-Deallocation” request payload

{
  "operationCenter": "OCENE",
  "crewShellCode": "INEXISTENT_CREW",
  "day": "2024-04-01",
  "validate": true,
  "removeWorkshift": true,
}