POST /integration/documents/r1/documents

BPMN Diagram

Business Logic

This integration API proceeds to deposit a file to the system. The file can be linked to a master entity or be stand-alone.

FSM must have imported the Docshare module.

Master entity can be: a Work Order or a WO Operation or an Asset or an Account.

System verifies these rules to validate Master entity codes in Input:

• for Asset: must be filled only assetCode or assetExternalCode

• for Account: must be filled only accountCode or accountExternalCode

• for Work Order: must be filled only workOrderCode or workOrderExternalCode

• for Work Order Operation: must be filled both (workOrderOperationCode or workOrderOperationExecutionOrder) and (workOrderCode or workOrderExternalCode)

• any other combination of codes will be blocked during Input validation

For file not related to a Master entity, must be filled directory’s uuid or directory’s name.

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 - Master Entity Retrieve

The system checks the existence of the master entity: Work Order, Work Order Operation, Asset, Account.

STEP 2a - Work Order Retrieve

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 the next step.

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

STEP 2b - Work Order Operation Retrieve

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 the next step.

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

 STEP 2c - Asset Retrieve

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 the next step.

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

STEP 2d - Account Retrieve

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 the next step.

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

STEP 3 - Document Category Retrieve

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 4 - Origin Existence

System takes Input field fileOriginCode and decodes it by own.

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 - Directory

System checks Input fields, in the order described below, to evaluate the step to follow:

• parentUuid or uuid present → go to step Directory ‘with Uuid’ Retrieve

• otherwise, name present → go to step Directory ‘only by name’ Retrieve

• otherwise → go to step Root Directory Retrieve and then Standard Directory Retrieve

STEP 5a - Directory ‘with Uuid’ Retrieve

System takes Input fields and checks their existence.

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

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

STEP 5b - Directory ‘only by name’ Retrieve

System takes Input fields and checks their existence.

If System can obtain a unique Output field → continue to the step File Creation.

If System can obtain more than one Output fields → responds with error. Elaboration is stopped.

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

STEP 5c - Root Directory Retrieve

System takes Input fields and checks their existence.

If System can obtain a unique Output field → continue to the step Standard Directory Retrieve.

If System can obtain more than one Output fields → responds with error. Elaboration is stopped.

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

STEP 5d - Standard Directory Retrieve

System takes Input fields and checks their existence.

Based on the Master Entity to which file is related, the System follows one of these cases:

• for Work Order → set name=Odl

• for Work Order Operation → set name=Odl

• for Asset → set name=Impianti

• for Account → set name=Impianti

This step is used only for files related to a master entity.

Input filed parentUuid corresponds to the uuid output retrieved in the step Root Directory Retrieve.

If System can obtain a unique Output field → continue to the step File Creation.

If System can obtain more than one Output fields → responds with error. Elaboration is stopped.

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

STEP 6 - Directory Creation

System takes Input fields and creates the Directory.

Input field name is filled with the value in Input body for name field or with the fixed value 'Odl' / 'Impianti'.

Input filed parentUuid corresponds to the uuid output retrieved in the step Root Directory Retrieve.

If Response State is SUCCESS → continue to next step.

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

STEP 7 - File Creation

System takes Input fields and creates the File record

If Response State is SUCCESS → continue to next step.

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

STEP 8 - Upload URL Retrieve

System takes Input fields and retrieves the Presigned URL.

If System can obtain the Output fields, it automatically uploads the file → continue to next step.

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

STEP 9 - Metadata Creation or Update

System checks whether there is any metadata in the request.

This step is skipped if the input Metadata fields are absent.

STEP 9a - Resource Id Retrieve (perhaps to be eliminated in the future)

System takes uuid created in step File Creation and uses it as Input Field.

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

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

STEP 9b - Metadata Retrieve

System takes Input fields and checks their existence.

Input filed resourceId corresponds to the id output retrieved in the step Resource Id Retrieve.

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

If System can’t obtain the Output fields → continue to the step Metadata Creation

STEP 9c - Metadata Update

System takes Input fields and updates the metadata record.

If Response State is SUCCESS → continue to the step File activation.

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

STEP 9d - Metadata Creation

System takes Input fields and creates the Metadata record.

If Response State is SUCCESS → continue to next step.

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

STEP 10 - File Activation

System uploads file on the presignedURL and then activates it.

If Response State is SUCCESS → continue to next step.

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

STEP 11 - Attachment Association

System takes input fields and creates the association with the Master Entity.

This step if skipped if input file is not related to a Master entity.

Based on the Master Entity to which file is related, the System follow one of this cases:

• for Work Order → continue to the step Attachment to Work Order Association

• for Work Order Operation → continue to the step Attachment to Operation Association

• for Asset → continue to the step Attachment to Asset Association

• for Account → continue to the step Attachment to Account Association

STEP 11a - Attachment to Work Order Association

The system takes the input fields and creates the association with the document.

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 11b - Attachment to Operation Association

The system takes the input fields and creates the association with the document.

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 11c - Attachment to Asset Association

The system takes the input fields and creates the association with the document.

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 11d - Attachment to Account Association

The system takes the input fields and creates the association with the document.

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.

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"
  },
  "externalSystemCode": "SAP",
  "workOrderCode": "WO00629",
  "fileOriginCode": "EXTERNAL_SYSTEM",
  "directory": {
    "extension": {
      "myFieldName": "myValue"
    },
    "name": "INT001",
    "draft": true,
    "uuid": "c89fsea8-7ef5-4f3f-bd37-d11fc50088c1",
    "startValidityDate": "2025-05-06T07:24:57.698Z",
    "endValidityDate": "2025-05-06T07:24:57.698Z"
  },
  "file": {
    "extension": {
      "myFieldName": "myValue"
    },
    "name": "broken_meter",
    "fileExtension": ".png",
    "draft": true,
    "startValidityDate": "2025-05-06T07:24:57.698Z",
    "endValidityDate": "2025-05-06T07:24:57.698Z"
    "metadata": {
      "extension": {
        "myFieldName": "myValue"
      },
      "description":"broken meter report 1",
      "number":"2",
      "notes":"To be replaced"
    }
  }
}

Response documentation

Response payload fields

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

Extension fields:

Response example

{
  "uuid": "c89f7ea8-7ef5-4f3f-bd37-d11fc50088c1"
}

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

Response error codes