NextGen APIs
NextGen APIs
Breadcrumbs

POST /integration/assets/r1/assets

Http Verb

POST

Url

/integration/assets/r1/assets

Permissions required

Technical Object: Edit (fsm.core.technicalobject.facility.edit)

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

Organizational Structure Entities: View (fsm.core.structure.view)

or

Organizational Structure Entities: Edit (fsm.core.structure.edit)

Last Modified Version

r1

Tech Tags


Available Async

Yes

BPMN Diagram

diagram (13).svg

Business Logic

This Integration API creates or updates an 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.

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 Existence

System takes Input fields and checks their existence.

API Verb: GET

Resource: Assets

Input: code

Output: assetId, typeId

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

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

Error Type:

STEP 3 - Asset Creation

Go to Step asset-creation

STEP 4 - Country Validation

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

This step is skipped if Input fields are absent.

API Verb: GET

Resource: Countries

Input: countryIsoAlphaCode

Output: countryCode

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 5 - District Validation

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

This step is skipped if districtAcronym and districtCode are both absent.

API Verb: GET

Resource: Districts

Input: [districtAcronym] OR [districtCode], countryCode

Output: districtCode

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 6 - Asset Status Validation

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

This step is skipped if Input fields are absent.

API Verb: GET

Resource: Asset Status

Input: statusCode, active=true

Output: assetStatusId

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 7 - Operation Center Validation

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

This step is skipped if Input fields are absent.

API Verb: GET

Resource: Operation Centers

Input: operationCenterCode, active=true

Output: operationCenterId

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 8 - Work Center Validation

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

This step is skipped if Input fields are absent.

API Verb: GET

Resource: Work Centers

Input: workCenterCode, active=true

Output: workCenterId

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 9 - Asset Type Retrieval (from Asset)

System retrieves the Asset type from Asset in order to get the flag linear that is used in step Additional Information Providing.

API Verb: GET

Resource: Asset Types

Input: asset.typeId

Output: linear

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 10 - Parent Asset Validation

System takes Input fields and checks if Parent Asset exists.

This step is skipped if Input fields are absent.

API Verb: GET

Resource: Assets

Input: parentAssetCode

Output: parentAssetId

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 11 - Characteristic Class Validation

System takes Input fields and checks if characteristic class exists.

System transcode optional input field classType in classTypeId 1 for ASSET and classTypeId 2 for MATERIAL. Default value of classTypeId is 1.

This step is skipped if input fields are absent.

API Verb: GET

Resource: Classes

Input: list of [classCode, classTypeId]

Output: list of classId

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 12 - Characteristics Validation

System takes Input fields and checks if all characteristics in input exist.

This step is skipped if Input fields are absent.

API Verb: GET

Resource: Characteristics

Input: list of [characteristicCode, classId]

Output: list of [characteristicId, dataTypeId, valueDomainId]

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 13 - Characteristics Value Validation

System takes Input fields and checks if characteristic value exists.

This step is skipped if “dataTypeId“ fields retrieve from the STEP Characteristics Validation is absent or different from 7 (Combobox or characteristic.value is absent or null.

API Verb: GET

Resource: Value Domain Items

Input: list of [valueDomainId, code = characteristic.value]

Output: list of [valueDomainItemId]

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 14 - Address Validation (from Asset)

System takes Input fields and retrieve the Address of the Asset.

This step is skipped if Input fields are absent.

API Verb: GET

Resource: Addresses

Input: targetId=<assetId>

Output: addressId

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 15 - Address Update

System takes Input fields and update the Address of the Asset.

This step is skipped if Input fields are absent.

API Verb: PATCH

Resource: Addresses

Input: addressId, countryCode, districtCode, municipality, municipalityCode, postalCode, locality, toponym, street, streetNumber, streetNumberExtension, floor, lot, staircase, apartment, directions, xCoordinate, yCoordinate, description

Output: Response State

If Response State is SUCCESS → continue to next step.

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

Error Type:

  •  Others - see link in Resource

STEP 16 - Address Normalization

System evaluates input fields xCoordinate and yCoordinate to decide if Address Normalization is necessary.

This step is skipped if xCoordinate and yCoordinate are present or both NULL.

API Verb: POST

Resource: Addresses/{addressId}/geocoding

Input: addressId

Output: Response State

If Response State is SUCCESS → continue to next step.

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

Error Type:

  •  Others - see link in Resource

STEP 17 - Asset Update

System takes Input fields, validate them and creates the Asset.

API Verb: PATCH

Resource: Assets

Input: assetId, operationCenterId, description, statusId, note, workCenterId

Output: assetId, Response State

If Response State is SUCCESS → continue to next step.

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

Error Type:

  •  Others - see link in Resource

STEP 18 - Asset-Parent Asset Relationship Deletion

System takes Input fields and deletes the relationship between Asset and his Parent.

This step is skipped if parentAssetId == asset.parentId or asset.parentId is absent.

API Verb: DELETE

Resource: Assets/{assetId}/children/{assetChildId}

Input: assetId, asset.parentId

Output: Response State

If Response State is SUCCESS → continue to next step.

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

Error Type:

  •  Others - see link in Resource

STEP 19 - Asset-Parent Asset Relationship Creation

System takes Input fields and creates the relationship between Asset and his Parent.

This step is skipped if parentAssetId == asset.parentId or parentAssetId is absent.

API Verb: POST

Resource: Assets/{assetId}/children

Input: assetId, parentAssetId

Output: Response State

If Response State is SUCCESS → continue to next step.

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

Error Type:

  •  Others - see link in Resource

STEP 20 - Additional Information Providing

System uses field linear, obtained as Output from ‘Asset Type Validation’ STEP, to evaluate if Asset is Linear.

The step is skipped if linear=false.

API Verb: PATCH

Resource: linear-asset-locations

Input: assetId, endPointXCoordinate, endPointYCoordinate, accessTime, accessXCoordinate, accessYCoordinate, accessEndPointXCoordinate, accessEndPointYCoordinate, accessEndPointAccessTime, invertible

Output: Linear Asset Location Id, 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 21 - Relationship Asset and Characteristics Retrieve

System retrieves the list of Asset Characteristics to check if there are already characteristics associated to the asset.

API Verb: GET

Resource: {assetId}/characteristics

Input: assetId

Output: list of characteristicId

If Response State is SUCCESS → elaboration is stopped. Continue to next step.

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

Error Type:

  • Others - see link in Resource

STEP 22 - Asset Characteristics Compare

System compares the list of characteristics obtained in STEP Characteristics Validation with those obtained in STEP Relationship Asset and Characteristics Retrieve.

This step is skipped if Input Characteristics fields are absent.

STEP 22a - Relationship Asset and Characteristics Cancellation

System deletes the relationship between assets and the characteristics present in Relationship Asset and Characteristics Retrieve but no more in Characteristics Validation.

API Verb: DELETE

Resource: {assetId}/characteristic/{characteristicId}

Input: assetId, characteristicId

Output: Response State

If Response State is SUCCESS → elaboration is stopped. Continue to next step.

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

Error Type:

STEP 22b - Relationship Asset and Characteristics Cancellation Update

System updates the relationship between assets and the characteristics present both in Relationship Asset and Characteristics Retrieve and in Characteristics Validation.

API Verb: PATCH

Resource: {assetId}/characteristics/batch

Input: { assetId, list of [characteristicId, value] } OR { assetId, list of [characteristicId, value = valueDomainItemId] }

Output: Response State

If Response State is SUCCESS → elaboration is stopped. See Continue to next step.

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

Error Type:

STEP 22c - Relationship Asset and Characteristics Cancellation Creation

System creates the relationship between assets and the characteristics present in Characteristics Validation and not already present in Relationship Asset and Characteristics Retrieve.

API Verb: POST

Resource: {assetId}/characteristics/batch

Input: { assetId, list of [characteristicId, value] } OR { assetId, list of [characteristicId, value = valueDomainItemId] }

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:

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

asset

externalSystemCode

External System Code

Y

Not Blank

2

code

Asset Code

Y

Not Blank

3

typeCode

Asset Type Code

N

Absent or Not Blank

4

operationCenterCode

Operation Center Code

N

Absent or Null or Not Blank

5

description

Description

N


6

statusCode

Asset Status code

N

Absent or Null or Not Blank

7

parentAssetCode

Parent Asset Code

N

Absent or Null or Not Blank

8

note

Asset Note

N


9

endPointXCoordinate

End point X coordinate

N


10

endPointYCoordinate

End point Y coordinate

N


11

accessTime

Access time

N


12

accessXCoordinate

Access X coordinate

N


13

accessYCoordinate

Access Y coordinate

N


14

accessEndPointXCoordinate

Access end point X coordinate

N


15

accessEndPointYCoordinate

Access end point Y coordinate

N


16

accessEndPointAccessTime

End point access time

N


17

invertible

Invertible flag

N


18

externalCode

Asset External Code

N


19

workCenterCode

Work Center Code

N


20

address

countryIsoAlphaCode

Acronym of Nation (2 or 3 letters acronym)

N

Absent or Not Blank

21

districtAcronym

Acronym of District

N

Absent or Null or Not Blank

22

districtCode

Code of District

N

Absent or Not Blank

23

municipality

Municipality

N

Absent or Not Blank

24

municipalityCode

Municipality code

N


25

locality

Locality

N


26

postalCode

PostalCode

N


27

toponym

Toponym

N


28

street

Street

N


29

streetNumber

StreetNumber

N


30

streetNumberExtension

Street number extension

N


31

floor

Floor

N


32

lot

Lot

N


33

staircase

Staircase

N


34

apartment

Apartment

N


35

directions

Directions

N


36

description

Address Description

N


37

yCoordinate

Latitude

N


38

xCoordinate

Longitude

N


39

characteristics

(minOccurs=0,

maxOccurs=N)

code

Code

Y


40

classCode

Class Code

N


41

classType

Characteristic Class Type

Default ‘ASSET’

N

Possible Values:

ASSET, MATERIAL

42

value

Value

N


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": {},
  "asset": {
    "extension": {
    },
    "externalSystemCode": "SAP",
    "code": "asset",
    "typeCode": "customer",
    "operationCenterCode": "NextGenOperationCenter",
    "parentAssetCode": "parentAsset",
    "description": "description of the asset",
    "note": "note of the asset",
    "statusCode": "OPEN",
    "externalCode": "EXT-01"
  },
  "address": {
    "extension": {
    },
    "streetNumber": 2,
    "street": "VIA PUINTAT",
    "countryIsoAlphaCode": "IT",
    "postalCode": "33100",
    "municipality": "UDINE",
    "districtAcronym": "UD",
    "yCoordinate": 46.0948035,
    "xCoordinate": 13.2298188
  },
    "characteristics": [
      {    
        "extension": {},
        "code": "BRAND",
        "classCode": "CL_A",
        "value": "VALUE_202502271299"
      }
    ]
}

 Update description and address

JSON
{
  "extension": {},
  "asset": {
    "extension": {},
    "externalSystemCode": "SAP",
    "code": "assetCode",
    "typeCode": "1709199625981",
    "operationCenterCode": "OCENW",
    "description": "new description of the asset"
  },
  "address": {
    "extension": {},
    "streetNumber": 83,
    "toponym": "via",
    "street": "Bassi",
    "countryIsoAlphaCode": "IT",
    "postalCode": "33080",
    "municipality": "Fiume Veneto",
    "districtAcronym": "PN"
  }
}

Response documentation

Response payload fields

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

Extension fields:

Field

Description

Note

id

Id of the resource created

Only for SUCCESS

code

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

Only for ERROR

Response example

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

 

Response error codes