Step account-creation

BPMN Diagram

Business Logic

This Integration API creates a new Customer/Account.

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

System checks the presence of meter.brandCode then:

• If meter.brandCode is present: The system evaluates the uniqueness of the combined couple (meter.serialNumber, meter.brandCode), as it is forbidden to have multiple pairs with the same values.

• If meter.brandCode is NOT present: The system evaluates the uniqueness of the meter.serialNumber property alone, as it is forbidden to have multiple serial numbers with the same value.

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 in internal configuration because it’s forbidden to have multiple Accounts with the same code.

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 3 - Address Existence

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

System uses a calculated Code for the Address ('ACCOUNT_' + account.code) to manage the retry of the request.

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

If System can obtain the Output fields and targetId is absent → continue to next step.

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

STEP 4 - Account Type 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 5 - Operation Center Validation

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

This step is skipped if Input fields are absent so Account will be not related with an Operation Center.

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 - Country 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 7 - 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 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 Brand Validation

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

This step is repeated for each Account’s Meters and skipped when meter.brandCode 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 10 - Meter Existence

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

System checks the presence of meter.brandCode then:

• If meter.brandCode is present: The system evaluates the uniqueness of the combined couple (meter.serialNumber, meter.brandCode), as it is forbidden to have multiple pairs with the same values.

• If meter.brandCode is NOT present: The system evaluates the uniqueness of the meter.serialNumber property alone, as it is forbidden to have multiple serial numbers with the same value.

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 11 - 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 12 - 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 13 - 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 14 - Address Evaluation

System evaluates the response obtained from Address Existence STEP.

If addressId exists but targetId is absent → continue to step Address Update.

If addressId doesn’t exist → continue to step Address Creation.

STEP 14a - Address Creation

System takes Input fields and creates an Address in internal configuration.

System uses a calculated Code for the Address ('ACCOUNT_' + account.code) to manage the retry of the request.

If Response State is SUCCESS → continue to step Address Normalization.

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

STEP 14b - Address Update

System takes Input fields and updates the entity.

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.

If Response State is SUCCESS → continue to next step.

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

STEP 16 - Account Creation

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

Furthermore system creates the link between Account and its Address.

If Response State is SUCCESS → continue to next step.

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

STEP 17 - Mandatory Contact Creation

System takes Input fields, validate them and creates one mandatory Account’s Contact. This contact has the fixed contactTypeId='PHONE'.

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 - Not Mandatory 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 next step.

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

STEP 19 - Meter Creation

The following steps are executed for each Meters in Input.

System takes Input fields, validate them and creates 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 Validation.

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

STEP 20 - 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 21 - 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.

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"
    },
    "code": "ADR_ACCOUNT_07",
    "description": "account description",
    "typeCode": "GAS-DIG",
    "externalSystemCode": "SAP",
    "phoneNumberContact": "32455656",
    "operationCenterCode": "1606",
    "fiscalCode": "RFEGTTY",
    "note": "NOTE OF THE ACCOUNT",
    "externalCode": "ext_adr_00",
    "phoneNumberCode": "CELL"
  },
  "address": {
    "extension": {
        "myFieldName": "myValue"
    },
    "streetNumber": 10,
    "toponym": "via",
    "street": "Roma",
    "countryIsoAlphaCode": "IT",
    "postalCode": "33080",
    "municipality": "Fiume Veneto",
    "districtAcronym": "PN"
  },
  "contacts": [
    {
      "extension": {
        "myFieldName": "myValue"
      },
      "contact": "account_00@gmail.com",
      "typeCode": "EMAIL",
      "code": "E-MAIL"
    }
  ],
  "meters": [
    {
      "extension": {
        "myFieldName": "myValue"
      },
      "serialNumber": "ADR_0123456",
      "classCode": "1",
      "productionYear": "2021",
      "digitNumber": 2,
      "acronym": "MTR_12345",
      "converter":{
            "serialNumber":"124123",
            "typeCode": "AT",
            "confirmDigitNumber": 1
         },
    }
  ]
}

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