GET /integration/work-orders/r1/work-orders

BPMN Diagram

Business Logic

This Integration API gets a Work Order with all its Operations.

One of code or externalCode must be present. If code is provided it has the precedence among the other fields. TypeCode, if present, is used with externalSystemCode (If present) and externalCode for filtering.

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 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 3 - Work Order Retrieve

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 4 - Work Order Operation Retrieve

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

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

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

STEP 5 - Parent Work Order Transcode

System takes Input fields and checks their existence.

This step is skipped if Input field is absent or value is -1.

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 - Address Transcode

System takes Input fields and gets the resource.

In the request there are the address inside Work Order and all the addresses and activityAddress inside the Operations' array.

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 - Country Transcode

System takes Input fields and gets the resource.

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 - District Transcode

System takes Input fields and gets the resource.

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 - Asset Transcode

System takes Input fields and gets the resource.

If System can obtain the Output fields → continue to step Work Order Type Transcode.

If System can’t obtain the Output fields → continue to next step because it is possible that the Work Order is associated to an Account.

STEP 10 - Asset Types Retrieve

System takes Input fields and gets the resource..

This step is skipped if step Asset Transcode didn’t retrieve any assetCode

If System can obtain the Output fields → continue to step Work Order Type Transcode.

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

STEP 11 - Linear Asset Locations Retrieve

System takes Input fields and gets the resource.

System performs a call for each assetId associated with a linearAsset=true belonging to work order header and work order operations .

This step is skipped if step Asset Transcode didn’t retrieve any assetCode

If System can obtain the Output fields → continue to step Work Order Type Transcode.

If System can’t obtain the Output fields → continue to step Work Order Type Transcode.

STEP 12 - Account Transcode

System takes Input fields and gets the resource.

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 13 - Work Order Type Transcode

System takes Input fields and gets the resource.

This step is skipped if step Work Order Type Validation was done.

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 14 - Status Transcode

System takes Input fields and gets the resource.

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 15 - Operation Center Transcode

System takes Input fields and gets the resource.

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 16 - Team Cardinality Transcode

System takes Input fields and gets the resource.

This step is done only if operationsAssignment='AGGREGATED' and System uses Cardinality taken from Work Order header.

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 17 - Urgency Type Transcode

System takes Input fields and gets the resource.

This step is skipped if Input fields are null.

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 18 - Work Center Transcode

System takes Input fields and gets the resource.

This step is skipped if Input fields are null.

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 19 - Work Cycle Transcode

System takes Input fields and gets the resource.

This step is skipped if Input fields are null.

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 20 - Operations Transcode

The following steps are executed for each Operations retrieved.

STEP 20a - Operation Status Transcode

System takes Input fields and gets the resource.

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 20b - Operation Type Transcode

System takes Input fields and gets the resource.

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 20c - Team Cardinality Transcode

System takes Input fields and gets the resource.

This step is done only if operationsAssignment='DISTINCT' and System uses Cardinality taken from Work Order operations.

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 20d - Activity Transcode

System takes Input fields and gets the resource.

If System can obtain the Output fields → elaboration is stopped. See Response payload fields

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

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 &.

Filter

Fields

The parameter _fields allows to choose output fields. More info here How to use APIs: Output fields selection.

Header Parameters

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

Default.

Request example

{baseUrl}/integration/work-orders/r1/work-orders?externalSystemCode=SAP&externalCode=N008965

Response documentation

Response payload fields

urgencyObject

workCenterObject

cardinalityObject

operationCenterObject

externalSystemObject

statusObject

typeObject

workCycleObject

addressObject

operationStatusObject

operationTypeObject

activityObject

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

Extension fields:

Response example

{
      "extension": {
        "myFieldName": "myValue"
      },
      "id": 9007199254740991,
      "code": "string",
      "externalSystem": {
        "code": "SAP",
        "description": "SAP"
      },
      "startDate": "2024-02-07T10:16:34.196Z",
      "endDate": "2024-02-07T10:16:34.196Z",
      "description": "string",
      "releaseDate": "2024-02-07T10:16:34.196Z",
      "closingDate": "2024-02-07T10:16:34.196Z",
      "creationDate": "2024-02-07T10:16:34.196Z",
      "externalCode": "string",
      "operationsAssignment": "AGGREGATED",
      "notes": "string",
      "appointmentStartDate": "2024-02-07T10:16:34.196Z",
      "appointmentEndDate": "2024-02-07T10:16:34.196Z",
      "address": {
        "extension": {},
        "countryCode": "string",
        "districtCode": "string",
        "street": "string",
        "streetNumber": 9007199254740991,
        "yCoordinate": 0.1,
        "xCoordinate": 0.1,
        "postalCode": "string",
        "toponym": "string",
        "municipality": "string",
      },
    "activityAddress": {
        "extension": {},
        "countryCode": "string",
        "districtCode": "string",
        "street": "string",
        "streetNumber": 9007199254740991,
        "yCoordinate": 0.1,
        "xCoordinate": 0.1,
        "postalCode": "string",
        "toponym": "string",
        "municipality": "string",
      },
      "type": {
        "extension": {},
        "code": "EXT-EXCAV-IELBT",
        "description": [
          {
            "lang": "en",
            "value": "Extraordinary maintenance / Excavation / Electrical system LV"
          }
        ]
      },
      "status": {
        "extension": {},
        "code": "5",
        "description": "Schedulable"
      },
      "operationCenter": {
        "extension": {},
        "code": "OCGAS",
        "description": [
          {
            "lang": "en",
            "value": "Center Gass OC"
          }
        ]
      },
      "aggregateDuration": 9007199254740991,
      "aggregateCardinality": {
           "extension": {},
            "code": "1",
            "description": "SINGOLA"
      },
      "aggregateResidualDuration": 9007199254740991,
      "urgency": {
        "extension": {},
        "code": "BLOCK",
        "description": [
          {
            "lang": "en",
            "value": "Blocking"
          }
        ]
      },
      "workCycle": {
        "code": "WC_001",
        "description": "Work Cycle 001"
      },
      "accountCode": "ACC_001",
      "assetCode": "",
      "operations":[
        {
          "extension": {
            "myFieldName": "myValue"
          },
          "id": 9007199254740991,
          "defaultDuration": 9007199254740991,
          "executionOrder": 9007199254740991,
          "description": "string",
          "currentDuration": 9007199254740991,
          "code": "string",
          "startDate": "2024-02-07T10:20:12.344Z",
          "endDate": "2024-02-07T10:20:12.344Z",
          "outcomeStartDate": "2024-02-07T10:20:12.344Z",
          "outcomeEndDate": "2024-02-07T10:20:12.344Z",
          "note": "string",
          "status": {
            "code": "2",
            "description": "Schedulabile"
          },
          "type": {
            "extension": {},
            "code": "ING-INT-DEF-EPOM",
            "description": [
              {
                "lang": "en",
                "value": "Generic inspection/Internal/Default"
              }
            ]
          },
          "assetCode": "ACC_001",
          "accountCode": "",
          "address": {
            "extension": {},
            "description": "INITIAL ADDRESS",
            "countryIsoAlphaCode": "IT",
            "districtAcronym": "MI",
            "municipality": "MILANO",
            "municipalityCode": "015146",
            "locality": "MILANO",
            "postalCode": "20161",
            "street": "FRATELLI BELTRAMI",
            "streetNumber": 21,
            "streetNumberExtension": "A",
            "yCoordinate": 0.1,
            "xCoordinate": 0.1,
            "toponym": "VIA"
         },
          "cardinality": {
            "extension": {},
            "code": "1",
            "description": "SINGOLA"
          },
          "activity": {
            "extension": {},
            "code": "01",
            "description": "Activity 1"
          }
        }
      ]
}

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