POST /integration/documents/r1/dynamic-forms/sheets

BPMN Diagram

Business Logic

This Integration API creates or updates a Dynamic Form Sheet.

System verifies that only one between workOrderOperation, resource, asset and account object is present, because it is not possibile to have a sheet associated to multiple entities:

• If workOrder is populated: system verifies that at least one of the fields workOrder.code or workOrder.externalCode is present.

• If resource is populated: system verifies that at least one of the fields resource.identificationNumber or resource.secondaryIdentificationNumber is present.

• If asset is populated: system verifies that at least one of the fields asset.externalCode or asset.code is present.

• If account is populated: system verifies that at least one of the fields account.externalCode or account.code is present.

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 - Operation Center 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 3 - Work Order Validation

System takes Input fields and checks their existence.

This step is skipped if workOrder 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 3b- Work Order Operation Validation

System takes Input fields and checks the existence of the operation. If workOrderOperation is absent system checks if input work order has only one operation.

If System can obtain the Output fields and workOrderOperation.operationExecutionOrder is not null OR workOrderOperation.operationCode is not null → continue to next step.

If System can obtain the Output fields and both workOrderOperation.operationExecutionOrder and workOrderOperation.operationCode are null, checks if the number of workOrderOperationId is equal to one → continue to next step.

If System can’t obtain the Output fields or the number of workOrderOperationId is not equal to one→ responds with error. Elaboration is stopped.

STEP 4 - Resource Validation

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

This step is skipped if resource 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 5 - Asset Validation

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

This step is skipped if asset 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 6 - Account Validation

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

This step is skipped if account 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 7 - Dynamic Form Template Validation

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 - Dynamic Form Template Structure Validation

System verifies that list of node.code in input matches correctly with dynamic form template nodes codes.

System takes Input fields and checks their existence.

This step is skipped if node field is absent.

If System can obtain the Output fields and all children.node.properties.code match with input nodes.code fields → continue to next step.

If System can obtain the Output fields and not all children.node.properties.code match with input nodes.code fields → responds with error. Elaboration is stopped.

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

STEP 9 - Dynamic Form Sheet Existence

System takes Input fields and checks their existence.

This step is skipped if sheet.code is absent.

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

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

STEP 10 - Dynamic Form Sheet Creation

System takes Input fields and checks their existence.

If Response State is SUCCESS → continue to next step.

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

STEP 11 - Sheet Code Retrieval

System takes Input fields and retrieve the sheet code to be returned in response payload.

This step is skipped if sheet.code is present.

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 12 - Nodes Valorization

System updates the Dynamic Form Sheet structure.

If Response State is SUCCESS → continue to next step.

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

STEP 13 - Entity Association

System compares the entity currently associated to sheet with the entity provided in the input payload and determines if a swap or removal is required.

• Current Entity: Can be resourceId (step Dynamic Form Sheet Existence), assetId (step Dynamic Form Sheet Existence), accountId (step Dynamic Form Sheet Existence) or workOrderOperationId (step Dynamic Form Sheet Existence).

• Target Entity: Can be resourceId (step Resource Validation), assetId (step Asset Validation), accountId (step Account Validation) or workOrderOperationId (step Work Order Operation Validation)

STEP 13a - Work Order Operation Removal

System takes Input fields and deletes current Work Order Operation association to Sheet.

This step is skipped if current workOrderOperationId is absent or current workOrderOperationId is equal to target workOrderOperationId

If Response State is SUCCESS → continue to next step.

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

STEP 13b - Resource Removal

System takes Input fields and deletes current Resource association to Sheet.

This step is skipped if current resourceId is absent or current resourceId is equal to target resourceId

If Response State is SUCCESS → continue to next step.

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

STEP 13c - Asset Removal

System takes Input fields and deletes current Asset association to Sheet.

This step is skipped if current assetId is absent or current assetId is equal to target assetId

If Response State is SUCCESS → continue to next step.

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

STEP 13d - Account Removal

System takes Input fields and deletes current Account association to Sheet.

This step is skipped if current accountId is absent or current accountId is equal to target accountId

If Response State is SUCCESS → continue to next step.

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

STEP 13e - Work Order Operation Association

System takes Input fields and associate the target Work Order Operation to Sheet.

This step is skipped if target workOrderOperationId is absent or current workOrderOperationId is equal to target workOrderOperationId

If Response State is SUCCESS → continue to next step.

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

STEP 13f - Resource Association

This step is skipped if target resourceId is absent or current resourceId is equal to target resourceId

If Response State is SUCCESS → continue to next step.

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

STEP 13g - Asset Association

System takes Input fields and associate the target Asset to Sheet.

This step is skipped if target assetId is absent or current assetId is equal to target assetId

If Response State is SUCCESS → continue to next step.

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

STEP 13h - Account Association

System takes Input fields and associate the target Account to Sheet.

This step is skipped if target accountId is absent or current accountId is equal to target accountId

If Response State is SUCCESS → continue to next step.

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

STEP 14 - Sheet Unlock Management

These steps are skipped if lockManagement is absent or lockManagement value is ‘LOCK’.

STEP 14a - Sheet Unlock Request

System takes Input fields to request the Unlock of the Sheet.

If Response State is SUCCESS → continue to next step.

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

STEP 14b - Sheet Unlock

System takes Input fields to Unlock the Sheet.

If Response State is SUCCESS → continue to next step.

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

STEP 15 - Sheet Lock Management

System takes Input fields to Lock the Sheet.

These steps are skipped if lockManagement is absent or lockManagement value is ‘UNLOCK’.

If Response State is SUCCESS → continue to next step.

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.

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

Creation example - Work Order Case

{   
  "extension":{
      "myFieldName":"myValue"
   },
    "sheet": {
        "extension":{
            "myFieldName":"myValue"
        },
        "externalSystemCode": "SAP",
        "operationCenterCode": "OCENW",
        "templateCode": "INT_API",
        "code": "OCENW-2602100902292753038",
        "description": [
            {
                "lang": "en",
                "value": "Sheet Test"
            }
        ]
    },
    "nodes": [
        {
            "code": "INFO",
            "value": "Test String"
        },
        {
            "code": "VALUE",
            "value": 123
        },
        {
            "code": "MULTI",
            "value": "OPT1"
        }
    ],
    "workOrder": {  
      "extension":{
        "myFieldName":"myValue"
       },
        "code": "OCENW00001",
        "workOrderOperation": {
            "operationExecutionOrder": 4
        }
    }
}

Response documentation

Response payload fields

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

Extension fields:

Response example

{
  "code": "OCENE-26010716253545645"
}

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "External system string does not exist",
  "instance": "/integration/work-orders/r1/documents",
  "instanceCode": "DCS001",
  "code": "IA001_001"
} 

Response error codes