PATCH /integration/work-orders/r1/work-orders (WIP)

BPMN Diagram (TBD)

Business Logic

This Integration API updates a Work Order.

One of code or externalCode must be present. If code is provided it has the precedence among the other fields.

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.

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.

STEP 2 - Work Order Existence

System takes Input fields and checks their existence.

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.

STEP 3 - Parent Work Order Existence

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

System checks the existence of a Parent Work Order.

This step is skipped if externalParentCode is absent.

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.

STEP 4 - Work Order Type Validation

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

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.

STEP 5 - Urgency Type Validation

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

This step is skipped if Input fields are absent.

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.

STEP 6 - Work Center Validation

System takes Input fields and checks their existence.

This step is skipped if Input fields are absent.

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.

STEP 7 - Team Cardinality Validation

This step is skipped if every field inside workOrder is absent. Continue to step Work Order Operations Validation

System evaluates input field woOperationsAssignment to decide the WO’s typology. If woOperationsAssignment is DISTINCT this step is skipped.

System takes Input fields and checks their existence.

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.

STEP 8 - Work Order Operations Validation

The following steps are executed for each WO Operations in Input.

STEP 7a - Team Cardinality Validation

System evaluates input field woOperationsAssignment to decide the WO’s typology. If woOperationsAssignment is AGGREGATED this step is skipped.

System takes Input fields and checks their existence.

This step is skipped if Input fields are absent.

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.

STEP 8b - Account Validation

System takes Input fields and checks their existence.

This step is skipped if Input fields are absent.

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.

STEP 8c - Address Validation (from Account)

System takes Input fields and retrieve the address of the asset.

This step is skipped if Input fields are absent.

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.

STEP 8d - Operation Type Validation

System takes Input fields and retrieve the operation type.

This step is skipped if Input fields are absent.

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.

STEP 8e - Asset Validation

System takes Input fields and checks their existence.

This step is skipped if Input fields are absent.

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.

STEP 8f - Address Validation (from Asset)

System takes Input fields and retrieve the address of the asset.

This step is skipped if Input fields are absent.

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.

STEP 9 - Work Order Update

This step is skipped if every field inside workOrder is absent.

System takes Input fields and creates the Work Order.

If Response State is SUCCESS → continue to next step.

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

STEP 10 - Work Order Operation Existence

System takes Input fields and checks the existence of the operation.

If System can obtain the Output fields → continue with step “Work Order Operations Update”.

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

STEP 11 - Activity Address Creation

System takes Input fields and creates an Activity Address.

This step is skipped if object operations.activityAddress is absent.

If Response State is SUCCESS → continue to step Work Order Operation Creation.

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

STEP 12 - Work Order Operations Creation

This step is executed one time, as a batch operation, passing the list of WO Operations in Input.

System performs a validation about addressId → this validation is executed only if both assetCode and accountCode input fields are absent. Therefore, it was unable to derive the addressId from steps Address Validation (from Account) and Address Validation (from Asset), so system takes addressId from Step Work Order Existence.

System takes Input fields and creates the work order operations.

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

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

STEP 13 - Work Order Operations Update

This step is executed one time, as a batch operation, passing the list of WO Operations in Input.

System takes Input fields and updates the work order operations.

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

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

Path Parameters

As their name suggests, they are included in the URL path of the endpoint.

Not applicable.

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.

addressObject

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

Update one field of Work Order

{
  "workOrder": {
    "extension": {
        "myFieldName": "myValue"
    },
    "code": "WO00223",
    "notes": "new note of the wo"
  }
}

 Update two fields of an operation

{
  "workOrder": {
    "extension": {
        "myFieldName": "myValue"
    },
    "code": "WO00223"
  },
  "operations":[
    {
      "extension": {
         "myFieldName": "myValue"
      },
      "code": "operation1",
      "startDate": "2023-12-20T14:44:47.106Z",
      "endDate": "2023-12-20T14:54:47.106Z",
    }
  ]
}

Add an Operation to a Work Order

{
  "workOrder": {
    "extension": {
        "myFieldName": "myValue"
    },
    "code": "WO00223"
  },
  "operations":[
    {
      "extension": {
          "myFieldName": "myValue"
      },
      "cardinalityCode": "cardinality1",
      "accountCode": "account_4",
      "typeCode": "opType1",
      "defaultDuration": 60,
      "executionOrder": 1,
      "description": "description of the operation",
      "currentDuration": 10,
      "code": "newOperation",
      "startDate": "2023-11-20T14:44:47.106Z",
      "endDate": "2023-11-20T14:54:47.106Z",
      "operationNote": "note of the operation"
    }
  ]
}

Response documentation

Response payload fields

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

Extension fields:

Response example

{
  "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