POST /integration/assets/r1/asset-measuring-elements

BPMN Diagram

Business Logic

This integration API creates or update a measuring element for an existing assets.

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

One of catalogGroupCode or characteristicCode must be present.

If measurementUnitCode, maxLength, counterDirectionCode or counterOverflowValue are provided, then characteristicCode must be 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 - Asset 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 - Measuring Element Status 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 - Characteristic Class Validation

System takes Input fields and checks if characteristic class exists.

System transcode optional input field characteristicClassType in characteristicClassTypeId 1 for ASSET or IMPIANTI and classTypeId 2 for MATERIAL or MATERIALI. Default value of characteristicClassTypeId is 1.

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 - Characteristics Retrieve

System takes Input fields and checks their existence.

This step is skipped if characteristicCode 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 - Measurement Unit Retrieve

System takes Input fields and checks their existence.

This step is skipped if characteristicCode 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 - Counter Direction Retrieve

System takes Input fields and checks their existence.

This step is skipped if counterDirectionCode 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 - Catalog Group Retrieve

System takes Input fields and checks their existence.

This step is skipped if catalogGroupCode is absent or characteristicCode is 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 8 - Measuring Element Existence

System takes Input fields and checks their existence.

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

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

STEP 9 - Measuring Element Update

System updates the Measuring Element

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 10 - Measuring Element Creation

System takes Input fields and creates the Measuring Element record

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

{
  "extension": {
    "myFieldName": "value"
  },
  "externalSystemCode": "SAP",
  "assetCode": "ASSET-XYZ-001",
  "assetExternalCode": "EXT-ASSET-456",
  "measuringElement": {
    "extension": {
      "myFieldName": "myfieldValue"
    },
    "code": "MEAS-ELEM-001",
    "description": "Temperature Sensor 1",
    "order": 1,
    "statusCode": "WORKING",
    "characteristicUsageCode": "USAGE-TEMP",
    "characteristicCode": "CHAR-TEMP-001",
    "measurementUnitCode": "CEL",
    "maxLength": 10,
    "counterDirectionCode": "INCREMENTAL",
    "counterOverflowValue": 99999,
    "catalogGroupCode": "CAT-SENS-TEMP",
    "targetValue": 25.5
  }
}

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/workforce/r1/resources",
  "code": "IA001_001"
}

Response error codes