NextGen APIs
NextGen APIs
Breadcrumbs

POST /integration/work-orders/multistages/r1/groups

Http Verb

POST

Url

/integration/work-orders/multistages/r1/groups

Permissions required

Core Additional Parameters: Edit (fsm.core.additionalparameter.edit)

Organizational Structure Entities: View (fsm.core.structure.view)

or

Organizational Structure Entities: Edit (fsm.core.structure.edit)

WorkOrder: View (fsm.core.workorder.view)

or

WorkOrder: Edit (fsm.core.workorder.edit)

WO Configuration: View (fsm.core.workorder.configuration.view)

or

WO Configuration: Edit (fsm.core.workorder.configuration.edit)

Last Modified Version

r1

Tech Tags


Available Async

No

BPMN Diagram (TBD)


Business Logic

This Integration API creates or updates a multistage relationship group between Work Order Operations.

For both sourceOperation and targetOperation object, one of workOrderCode or workOrderExternalCode must be present. If workOrderCode is provided it has the precedence among the other fields.

The system validates the 'source operation – target operation' pairs in the request body and throws an error if duplicates are detected.

System verifies Permission Required and starts the elaboration that is organized in steps.

STEP 1 - External System Validation

System takes Input fields and checks their existence in internal configuration.

API Verb: GET

Resource: External Systems

Input: externalSystemCode, active=true

Output: externalSystemId

If System can obtain the Output fields → continue to next step.

If System can’t obtain the Output fields → responds with error. Elaboration is stopped.

Error Type:

STEP 2 - Operation Center Validation

System takes Input fields and checks their existence in internal configuration.

API Verb: GET

Resource: Operation Centers

Input: operationCenterCode, active=true

Output: operationCenterId

If System can obtain the Output fields → continue to next step.

If System can’t obtain the Output fields → responds with error. Elaboration is stopped.

Error Type:

STEP 3 - Dependency Type Validation

System takes Input fields and checks their existence in internal configuration.

API Verb: GET

Resource: Dependency Types

Input: typeCode

Output: typeId

If System can obtain the Output fields → continue to next step.

If System can’t obtain the Output fields → responds with error. Elaboration is stopped.

Error Type:

STEP 4 - Work Order Validation

System takes sourceOperation and targetOperation input fields for each dependency item and checks their existence.

API Verb: GET

Resource: Work Orders

Input: workOrderCode OR [externalSystemId, workOrderExternalCode]

Output: workOrderId

If System can obtain the Output fields for all input fields → continue to next step.

If System can’t obtain the Output fields for at least one input field → responds with error. Elaboration is stopped.

Error Type:

STEP 5 - Work Order Operation Validation

System takes sourceOperation and targetOperation input fields for each dependency item and checks their existence.

API Verb: GET

Resource: Work Order Operations

Input: workOrderId, list of [workOrderOperationCode]

Output: list of [workOrderOperationId]

If System can obtain the Output fields for all input fields → continue to next step.

If System can’t obtain the Output fields for at least one input field → responds with error. Elaboration is stopped.

Error Type:

STEP 6 - Multistage Group Retrieve

System takes Input fields and checks their existence. The system also verifies whether the state of the multistage group is consistent with its update → if status NOT IN (‘SCHEDULED’, ‘CLOSED’, ‘CANCELLED’).

API Verb: GET

Resource: Groups

Input: externalSystemId, externalCode

Output: groupId, groupStatusId

If System can obtain the Output fields and status is consistent → Update → continue to next step Multistage Group Update.

If System can obtain the Output fields and status is not consistent → responds with error. Elaboration is stopped.

If System can’t obtain the Output fields → Create → continue to step Multistage Group Creation.

Error Type:

STEP 7 - Multistage Group Update

System takes Input fields and modifies a Multistage Group and its dependencies.

STEP 7a - Multistage Group Update

System takes Input fields and updates Multistage Group.

API Verb: PATCH

Resource: Group

Input: groupId, description, color

Output: Response State, groupId, groupCode

If Response State is SUCCESS → continue to next step.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

Error Type:

  • Others - see link in Resource

STEP 7b - Multistage Group Operation Retrieve

System takes Input fields and checks their existence.

API Verb: GET

Resource: /{groupId}/operations

Input: groupId

Output: list of [multistageGroupOperationId, workOrderOperationId]

If System can obtain the Output fields, compares the workOrderOperationId list in output with workOrderOperationId list in input body:

  • If there are workOrderOperationId in output not present in input body → Delete → go to next step Multistage Group Operation Deletion.

  • If there are workOrderOperationId in output present also in input body → go to step Multistage Group Dependencies Retrieve.

  • If there are workOrderOperationId in input body not present in output → Create → go to step Multistage Group Operation Creation.

If System can’t obtain the Output fields → responds with error. Elaboration is stopped.

Error Type:

  • Others - see link in Resource

STEP 7c - Multistage Group Operation Deletion

System takes Input fields and deletes Group Operations.

The private API automatically deletes also the Group Dependency linked to the Group Operation, if allowed. If not allowed, the Private API blocks both Group Operation deletion than Group Dependency deletion.

This step is skipped if Input fields are null or absent.

API Verb: DELETE

Resource: /{groupId}/operations/{multistageGroupOperationId}

Input: groupId, multistageGroupOperationId

Output: Response State

If Response State is SUCCESS → continue to next step.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

Error Type:

  • Others - see link in Resource

STEP 7d - Multistage Group Operation Creation

System takes Input fields and creates Group Operations.

This step is skipped if Input fields are null or absent.

API Verb: POST

Resource: /{groupId}/operations

Input: groupId, workOrderOperationId

Output: Response State, multistageGroupOperationId

If Response State is SUCCESS → continue to next step.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

Error Type:

  • Others - see link in Resource

STEP 7e - Multistage Group Dependency Retrieve

System takes Input fields and checks their existence.

API Verb: GET

Resource: /{groupId}/dependencies

Input: groupId

Output: list of [multistageGroupId, sourceOperationId, targetOperationId]

If System can obtain the Output fields, compares the list of ‘sourceOperationId-targetOperationId’ pairs in output with the list of ‘sourceOperationId-targetOperationId’ pairs in input body:

  • If there are pairs in output not present in input body → Delete → go to next step Multistage Group Dependency Deletion.

  • If there are pairs in output present also in input body → Update → go to step Multistage Group Dependency Update.

  • If there are pairs in input body not present in output → Create → go to step Multistage Group Dependency Creation.

If System can’t obtain the Output fields → responds with error. Elaboration is stopped.

Error Type:

  • Others - see link in Resource

STEP 7f - Multistage Group Dependency Deletion

System takes Input fields and deletes Group Dependencies.

This step is skipped if Input fields are null or absent.

API Verb: DELETE

Resource: /{groupId}/dependencies/{dependencyId}

Input: groupId, dependencyId

Output: Response State

If Response State is SUCCESS → continue to next step.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

Error Type:

  • Others - see link in Resource

STEP 7g - Multistage Group Dependency Update

System takes Input fields and updates Group Dependencies.

This step is skipped if Input fields are null or absent.

API Verb: PATCH

Resource: /{groupId}/dependencies/{dependencyId}

Input: groupId, dependencyId, minOffset, maxOffset, critical

Output: Response State

If Response State is SUCCESS → continue to next step.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

Error Type:

  • Others - see link in Resource

STEP 7h - Multistage Group Dependency Creation

System takes Input fields and creates Group Dependencies.

This step is skipped if Input fields are null or absent.

API Verb: POST

Resource: /{groupId}/dependencies

Input: groupId, typeId, sourceOperationId, targetOperationId, minOffset, maxOffset, critical

Output: Response State

If Response State is SUCCESS → continue to next step.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

Error Type:

  • Others - see link in Resource

STEP 8 - Multistage Group Creation

System takes Input fields and creates a Multistage Group and its dependencies.

STEP 8a - Multistage Group Creation

System takes Input fields and creates a Multistage Group.

API Verb: POST

Resource: Group

Input: externalSystemId, operationCenterId, externalCode, description, color

Output: Response State, groupId, groupCode

If Response State is SUCCESS → continue to next step.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

Error Type:

  • Others - see link in Resource

STEP 8b - Multistage Group Operation Creation

System takes Input fields and creates Multistage Group Operations.

API Verb: POST

Resource: /{groupId}/operations

Input: groupId, workOrderOperationId

Output: Response State, operationId

If Response State is SUCCESS → continue to next step.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

Error Type:

  • Others - see link in Resource

STEP 8c - Multistage Group Dependency Creation

System takes Input fields and creates Multistage Group Dependencies.

API Verb: POST

Resource: /{groupId}/dependencies

Input: groupId, typeId, sourceOperationId, targetOperationId, minOffset, maxOffset, critical

Output: Response State, groupId, groupCode

If Response State is SUCCESS → elaboration is stopped. See Response payload fields.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

Error Type:

  • Others - see link in Resource

Query String Parameters

Start with a ? and includes parameters listed one after the another separated by &.

Not applicable.

Header Parameters

Parameters included in the request headers. Generally, request headers are used to keep authorization parameters.

Default.

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

Constraint

externalSystemCode



External System Code

Y

Not Blank

operationCenterCode



Operations Center Code

Y

Not Blank

externalCode



External Code

Y

Not Blank

description



Description

N


dependencies

(minOccurs=0, maxOccurs=N)

typeCode


Relationship Type Code

Value: SS, FS, SD

Y

Not Blank

minOffset


Min Offset Tolerance (minutes)

N


maxOffset


Max Offset Tolerance (minutes)

N


critical


Flag critical

N


sourceOperation

workOrderCode

Work Order Code

N


workOrderExternalCode

Work Order External Code

N


workOrderOperationCode

WO Operation Code

Y


targetOperation

workOrderCode

Work Order Code

N


workOrderExternalCode

Work Order External Code

N


workOrderOperationCode

WO Operation Code

Y


The objects in input could have also the extension object that allows to add additional, customized data to this API. More info here How to use APIs: Custom data via Extension.

Request example

JSON
{
  "extension": {
    "myFieldName": "myValue"
  },
  "externalSystemCode": "SAP",
  "operationCenterCode": "OC_PGE_BAYAREA",
  "externalCode": "PRJ-2026-XYZ",
  "description": "North Area Phase 1",
  "dependencies": [
    {
      "extension": {
        "myFieldName": "myValue"
      },
      "typeCode": "FS",
      "minOffset": 10,
      "maxOffset": 30,
      "critical": true,
      "sourceOperation": {
        "workOrderExternalCode": "400012345",
        "workOrderOperationCode": "0010"
      },
      "targetOperation": {
        "workOrderExternalCode": "400012346",
        "workOrderOperationCode": "0020"
      }
    },
    {
      "typeCode": "SS",
      "minOffset": 0,
      "maxOffset": 15,
      "critical": false,
      "sourceOperation": {
        "workOrderCode": "WO-00045871",
        "workOrderOperationCode": "0030"
      },
      "targetOperation": {
        "workOrderExternalCode": "400012347",
        "workOrderOperationCode": "0010"
      }
    }
  ]
}

Response documentation

Response payload fields

Compliant with RFC Standard https://www.rfc-editor.org/rfc/rfc9457.html

Extension fields:

Field

Description

Note

id

Id of the resource created

Only for SUCCESS

code

String Code of the resource created

Only for SUCCESS

code

Extension member of a Problem Details Object that contains the error code

Only for ERROR

Response example

JSON
{
  "id": 1,
  "code": "PRJ-2026-XYZ"
}
JSON
{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "External system string does not exist",
  "instance": "/integration/work-orders/r1/work-orders",
  "code": "IA001_001"
}


Response error codes