POST /integration/configurations/r1/characteristics

BPMN Diagram

Business Logic

This Integration API creates or updates a Characteristic for Asset.

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 - Data Type 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 3 - Measurement Unit 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 4 - Usage 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 5 - Characteristic Class Type 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 6 - Characteristic Class 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 → continue to step Characteristic Class Creation.

STEP 7 - Value Domain Validation

System takes Input fields and checks their existence.

This step is skipped if Input fields is absent.

If System can obtain the Output fields → continue to step Value Domain Items Existence

If System can’t obtain the Output fields → System verifies if valueDomain.description is present.

• If yes → continue to next step.

• If not → responds with error. Elaboration is stopped.

STEP 7a - Value Domain Creation

System takes input fields and creates the Value Domain.

If Response State is SUCCESS → continue to next step.

If Response State is ERROR → responds with error. Elaboration is stopped.

STEP 7b - Value Domain Items 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 → continue to next step.

STEP 7c - Value Domain Items Compare

System compare input characteristicValueDomain.code items with the code of Value Domain Items retrieved in STEP Value Domain Items Existence.

If codes are already existing → Value Domain Items Update

If codes are not present → Value Domain Items Creation

STEP 7e - Value Domain Items Update

System updates value of items already present

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 7f - Value Domain Items Creation

System creates Value Domain Items.

If Response State is SUCCESS → continue to next step.

If Response State is ERROR → responds with error. Elaboration is stopped.

STEP 10 - Characteristic Existence

System takes Input fields and checks their existence.

If System can obtain the Output fields → continue to step Characteristic Class Update and then to step Characteristic Update.

If System can’t obtain the Output fields → continue to step Characteristic Class Update and then to step Characteristic Creation.

STEP 10a - Characteristic Class Creation

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

If Response State is SUCCESS → continue to step Characteristic Creation.

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

STEP 10b - Characteristic Class Update

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

If Response State is SUCCESS → continue to step Characteristic Creation or to step Characteristic Update.

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

STEP 11a - Characteristic Creation

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

If Response State is SUCCESS → see Response payload fields.

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

STEP 11b - Characteristic Update

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

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

{
  "extension": {},
  "characteristic": {
    "extension": {
        "myFieldName": "myValue"
    },
    "externalSystemCode": "SAP",
    "code": "CODE_01",
    "description": [ 
     {
       "lang": "en",
       "value": "Description of Characteristic 01"
     }
    ],
   "format": "Text",
   "size": 5,
   "maxLength": 10,
   "notNull": true,
   "active": true,
   "order": 10 
  },
  "characteristicClassType": {
    "extension": {
        "myFieldName": "myValue"
    },
    "code": "CT01"
  },
  "characteristicClass": {
    "extension": {
        "myFieldName": "myValue"
    },
    "code": "CL01",
    "description": [
     {
       "lang": "it",
       "value": "Classe 01"
     },
     {
       "lang": "en",
       "value": "Class 01"
     }
    ],
    "active": true
  }
}

Response documentation

Response payload fields

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

Extension fields:

Response example

{
  "id": 123456
}

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

Response error codes