POST /integration/assets/r1/accounts

BPMN Diagram

Business Logic

This Integration API creates or updates an Account.

System evaluates the uniqueness of property contacts.typeCode because it’s forbidden to have multiple Contacts with same type.

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 - Account Existence

System takes Input fields and checks their existence.

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.

STEP 3 - Account Creation

Go to Step account-creation

STEP 4 - Link between Meter and other Account Existence

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

System compares accountId in Output with the one obtained from ‘Account Existence’ STEP because it’s forbidden to have the same Meter related to multiple accounts.

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

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

STEP 5 - Country Validation

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

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

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

This step is skipped if districtAcronym and districtCode are both 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 - Operation Center Validation

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

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 8 - Contact Type Validation

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

This step is repeated for each Account’s Contacts.

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 9 - Meter Type Validation

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

System verifies also the validity of the type.

This step is repeated for each Account’s Meters.

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 10 - Meter Brand Validation

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

This step is repeated for each Account’s Meters.

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 11 - Meter Location Validation

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

This step is repeated for each Account’s Meters.

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 12 - Meter Class Validation

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

This step is repeated for each Account’s Meters.

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 13 - Address Validation (from Account)

System takes Input fields and retrieve the address of the asset.

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

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

This step is skipped if Input fields are absent.

If Response State is SUCCESS → continue to next step.

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

STEP 15 - 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.

If Response State is SUCCESS → continue to next step.

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

STEP 16 - Account Update

System takes Input fields and updates the Account.

If Response State is SUCCESS → continue to next step.

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

STEP 17 - Contacts Creation or Update

The following steps are executed for each Contact in Input.

STEP 17a - Contact Existence

System takes Input fields to check Contact existence and creates or updates the Account’s Contacts.

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

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

STEP 17b - Contact Creation

The following steps are executed for each Contacts in Input.

System takes Input fields, validate them and creates the Account’s Contacts.

Furthermore system creates the link between Account, Account Address and its Contacts.

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

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

STEP 17c - Contact Update

The following steps are executed for each Contacts in Input.

System takes Input fields, validate them and creates the Account’s Contacts.

Furthermore system creates the link between Account, Account Address and its Contacts.

If Response State is SUCCESS → continue to next step.

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

STEP 18 - Meters Creation or Update

The following steps are executed for each Meters in Input.

STEP 18a - Meter Existence

System takes Input fields to check Meter existence and creates or updates the Account’s Meters.

System checks the presence of meter.brandCode then:

• If meter.brandCode is present: The system evaluates the existence of a unique combined couple (meter.serialNumber, meter.brandCode), as it is forbidden to manage updates of multiple records with pairs with the same values.

• If meter.brandCode is NOT present: The system evaluates the existence of a unique meter.serialNumber property alone, as it is forbidden to manage updates of multiple records with serial numbers with the same value.

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

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

STEP 18b - Meter Creation

System takes Input fields and creates the Account’s Meters.

Furthermore system creates the link between Account, Account Address and its Meters.

If Response State is SUCCESS → continue to step Converter Type.

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

STEP 18c - Converter Type Validation

System takes Input fields and updates the Account’s Converter Type.

This step is skipped if converter object inside meter is null or typeCode is null.

If Response State is SUCCESS → elaboration is stopped. See Converter Creation.

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

STEP 18d - Converter Creation

System takes Input fields and creates the Account’s Meter’s Converter.

This step is skipped if converter object inside meter is null.

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 18e - Meter Update

System takes Input fields and updates the Account’s Meters.

Furthermore system creates the link between Account, Account Address and its Meters.

If Response State is SUCCESS → elaboration is stopped. See Converter Type.

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

STEP 18f - Converter Type

System takes Input fields and updates the Account’s Converter Type.

This step is skipped if converter object inside meter is null.

If Response State is SUCCESS → elaboration is stopped. See Converter Existence.

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

STEP 18g - Converter Existence

System takes Input fields and checks if converter already exists.

This step is skipped if converter object inside meter is null.

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

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

STEP 18h - Converter Creation

System takes Input fields and creates the Account’s Meter’s Converter.

This step is skipped if converter object inside meter is null.

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 18i - Converter Update

System takes Input fields and updates the Account’s Meter’s Converter.

This step is skipped if converter object inside meter is null.

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 19 - Meter Deactivation

System checks the system property integrationlayer.integration-api.account.meter.disable-not-in-request to decide which path to follow regarding the treatment of the meters:

• integrationlayer.integration-api.account.meter.disable-not-in-request=false → elaboration is stopped

• integrationlayer.integration-api.account.meter.disable-not-in-request=true → go to nest Step

STEP 19a - Meter List Comparison

System takes the list of Account’s Meters active and compares this list with the meters in input.

If System can obtain the Output fields and some serialNumber is not present in input → continue to step Meter Deactivation

If System can obtain the Output fields and all serialNumber is present in input → elaboration is stopped

If System can’t obtain the Output fields → elaboration is stopped

STEP 19b - Meter Deactivation

System takes Input fields and updates the Account’s Meters not present in input.

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": {},
   "account":{
      "extension":{
         "myFieldName":"myValue"
      },
      "externalSystemCode":"SAP",
      "code":"ADR_ACCOUNT_05"
   },
   "address":{
      "extension":{
         "myFieldName":"myValue"
      },
      "streetNumber":10,
      "toponym":"via",
      "street":"Trieste",
      "countryIsoAlphaCode":"IT",
      "postalCode":"33080",
      "municipality":"Fiume Veneto",
      "districtAcronym":"PN"
   },
   "contacts":[{
      "extension": {},
       "typeCode":"EMAIL",
       "code": "String",
       "contact": "test@gmail.com"
     }
   ],
   "meters":[
      {  
        "extension": {},
         "converter":{
           "extension": {},
            "serialNumber":"124123"
         },
         "typeCode":"TYPE1"
      }
   ]
}

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

Response error codes