NextGen APIs
NextGen APIs
Breadcrumbs

POST /integration/configurations/r1/asset-type-characteristics

Http Verb

POST

Url

/integration/configurations/r1/asset-type-characteristics

Permissions required

Core Additional Parameters: Edit (fsm.core.additionalparameter.edit)

Facility Configuration: Edit (fsm.core.technicalobject.configuration.edit)

Last Modified Version

r1

Tech Tags


Available Async

No

BPMN Diagram

diagram (27).svg

Business Logic

This Integration API creates or updates an Asset Type characteristic.

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.

API Verb: GET

Resource: External Systems

Input: externalSystemCode, active=true

Output: externalSystemId

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.

Error Type:

STEP 2 - Asset Type Validation

System takes Input fields and checks their existence.

API Verb: GET

Resource: Asset Types

Input: assetType.code, active=true

Output: assetTypeId, assetTypeCode, assetTypeDescription

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.

Error Type:

STEP 3 - Characteristics Validation

The following steps are executed for each Characteristic in Input.

STEP 3a - Characteristic Class Validation

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

System uses a specific typeId for FACILITIES.

API Verb: GET

Resource: Characteristic Classes

Input: classCode, typeId=1, active=true

Output: characteristicClassId

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.

Error Type:

STEP 3b - Characteristic Validation

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

API Verb: GET

Resource: Characteristic

Input: characteristic.code, characteristicClassId, active=true

Output: characteristicId

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.

Error Type:

STEP 4 - Asset Type Template Existence

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

API Verb: GET

Resource: Templates

Input: assetTypeId, isDefault=true

Output: assetTypeTemplateId

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

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

Error Type:

STEP 5 - Asset Type Template Creation

System takes Input fields and creates the entity.

API Verb: POST

Resource: Templates

Input: description=<assetTypeDescription>, code=<assetTypeCode>, active=true, isDefault=true

Output: Response State, assetTypeTemplateId (only for SUCCESS)

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

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

Error Type:

  • Others - see link in Resource

STEP 6 - Characteristics Upsert

The following steps are executed for each Characteristic in Input.

STEP 6a - Asset Type Characteristic Relationship Existence

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

API Verb: GET

Resource: Asset Type Template Characteristic

Input: assetTypeId, assetTypeTemplateId, characteristicId

Output: characteristicId

If System can obtain the Output fields → Update → continue to step Asset Type Characteristic Relationship Update.

If System can’t obtain the Output fields → Creation → continue to next step Asset Type Characteristic Relationship Creation.

Error Type:

  • Others - see link in Resource

STEP 6b - Asset Type Characteristic Relationship Creation

System takes Input fields and creates the entity.

API Verb: POST

Resource: Create Asset Type Template Characteristic in Batch

Input: assetTypeId, assetTypeTemplateId, [{characteristicId, value, mandatory, readOnly, order}]

Output: Response State

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

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

Error Type:

  • Others - see link in Resource

STEP 6c - Asset Type Characteristic Relationship Update

System takes Input fields and updates the entity.

API Verb: PATCH

Resource: Update Asset Type Template Characteristic in Batch

Input: assetTypeId, assetTypeTemplateId, [{characteristicId, value, mandatory, readOnly, order}]

Output: Response State

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

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

Error Type:

  • Others - see link in Resource

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.

 

Field

Description

Mandatory

Constraint

1

assetType

externalSystemCode

External System Code

Y

Not Blank

2

code

Asset Type Code

Y

Not Blank

3

characteristics

(minOccurs=1,
maxOccurs=N)

code

Characteristic Code

Y

Not Blank

4

value

Characteristic Value

N


5

mandatory

Characteristic Mandatory Flag

N

Absent or Not Null

6

readOnly

Characteristic ReadOnly Flag

N

Absent or Not Null

7

order

Characteristic Order

N


8

classCode

Characteristic Class Code

Y

Not Blank

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

JSON
{
  "extension": {},
  "assetType": {
    "extension": {
        "myFieldName": "myValue"
    },
    "externalSystemCode": "SAP",
    "code": "TRASF"
  },
  "characteristics": [ 
    {
      "extension": {
         "myFieldName": "myValue"
      },
      "code": "OILLEV",
      "value": "5",
      "mandatory": true,
      "readOnly": true,
      "order": 1,
      "classCode": "POW-METER"
    }
  ]
}

 

Response documentation

Response payload fields

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

Extension fields:

Field

Description

Note

code

Extension member of a Problem Details Object that contains the error code

Only for ERROR

Response example

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

 Response error codes