POST /integration/workforce/r2/resources

BPMN Diagram

Business Logic

This Integration API inserts or updates a Resource with his addresses.

Insert Only Validations

System verifies that if startAddressFromOperationCenter or endAddressFromOperationCenter has been provided (value=true), then operationCenterCode must have been provided.

Upsert Validations

System verifies that if startAddressFromOperationCenter or endAddressFromOperationCenter has been provided, then operationCenterCode must have been provided.

System verifies that endDate is greater than startDate and sysdate.

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

System takes Input fields and checks their existence.

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 4 - Resource Type Validation

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

System takes Input fields and checks their existence. System verifies also the validity of the Vehicle.

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 - User Type Validation

System takes Input fields and checks their existence.

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 7 - Operation Center Address Retrieval

System takes Input fields and retrieve the address.

This step is skipped if startAddressFromOperationCenter is false and endAddressFromOperationCenter is false.

STEP 7a- Operation Center Start Address Retrieval

System takes Input fields and retrieve the start address.

• If startAddressCode is not provided:

  • The system will retrieve the default address from the operating center.

    • main=true and description=null

• If startAddressCode is provided:

  • The system searches for the operating center address that matches that specific code.

    • main=null and description=startAddressCode

This step is skipped if startAddressFromOperationCenter is false.

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 7b - Operation Center End Address Retrieval

System takes Input fields and retrieve the end address.

• If endAddressCode is not provided:

  • The system will retrieve the default address from the operating center.

    • main=true and description=null

• If endAddressCode is provided:

  • The system searches for the operating center address that matches that specific code.

    • main=null and description=endAddressCode

This step is skipped if endAddressFromOperationCenter is false.

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 - Address Validation

The following steps are executed for each Address in Input.

STEP 8a - 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 8b - District 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 9 - Resource Existence

System takes Input fields and checks their existence.

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

If System can obtain the Output fields → system evaluates the operationCenterId in Input:

• if operationCenterId in Input is not present, system takes only the resource in output with loan=false → Update → continue to next step.

• if operationCenterId in Input is present, System verifies that in output

  • if resource not exist → Creation → continue to step Resource Creation

  • If a resource exists, the system verify if exist a resource with same operationCenter

    • if exists selects the one with loan=false→ Update → continue to step next step.

    • if not exist → responds with error. Elaboration is stopped.

STEP 10 - Resource’s Address - Start Address Validation

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

This step is skipped if Input fields are absent or if the startAddressFromOperationCenter field is set to true or if the startAddressCode appears also in ‘Addresses’ object.

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 - Resource’s Address - End Address Validation

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

This step is skipped if Input fields are absent or if the endAddressFromOperationCenter field is set to true or if the endAddressCode appears also in ‘Addresses’ object.

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 - Resource Creation

System takes Input fields and creates the entity (only not on loan).

If Response State is SUCCESS → continue to step User Update.

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

STEP 13 - Resource Update

System takes Input fields and updates the entity (only not on loan).

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

System takes Input fields and updates the entity.

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 Management

The following steps are executed for each Address in Input.

This step is skipped if addresses are absent.

STEP 15a - Address Existence

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

The system filters the records to be processed based on these two filters:

• startAddressCode if they appear in ‘Addresses’ object and the startAddressFromOperationCenter field is not true

• endAddressCode if they appear in ‘Addresses’ object and the endAddressFromOperationCenter field is not true

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

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

STEP 15b - Address Creation

System takes Input fields and creates the entity.

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

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

STEP 15c - 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 15d - Address Normalization

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

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 15e - Address Resource Relationship Existence

System takes Input fields and retrieve the addresses related with the resource.

If System can obtain the Output fields → Update → continue to step Address Resource Relationship Update.

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

STEP 15f - Address Resource Relationship Creation

System takes Input fields and creates the entity.

If Response State is SUCCESS → continue to step Route Addresses

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

STEP 15g - Address Resource Relationship Update

System takes Input fields and retrieve the address.

If Response State is SUCCESS → continue to next step.

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

STEP 16 - Start/End Address Validation

This step is executed if one or both of the following variable startAddressId and endAddressId are null.

STEP 16a - Resource’s Address - Start Address Validation

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

This step is skipped if the startAddressId variable is already populated or if Input fields are absent or if the startAddressFromOperationCenter field is set to true

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 16b - Resource’s Address - End Address Validation

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

This step is skipped if the endAddressId variable is already populated or if Input fields are absent or if the endAddressFromOperationCenter field is set to true

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 17 - Route Addresses

System takes Input fields and creates/update the entity.

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

Insert

{
  "extension": {},
  "resource": {
    "extension": {
        "myFieldName": "myValue"
    },
    "externalSystemCode": "SAP",
    "surname": "Rossi",
    "name": "Mario",
    "birthDate": "1970-01-01",
    "email": "mario.rossi@gmail.com",
    "mobilePhone": "34111",
    "identificationNumber": "mario.rossi",
    "typeCode": "RESTYPE",
    "color": "#FF990C",
    "vehicleId": 
    "order": 10,
    "operationCenterCode": "OPCODE",
    "workCenterCode": "WRKCNTCODE",
    "startAddressCode": "HOUSE1",
    "endAddressCode": "HOUSE2",
    "startAddressFromOperationCenter": false,
    "endAddressFromOperationCenter": false
  },
  "addresses": [
    {
      "extension": {
         "myFieldName": "myValue"
      },
      "code": "HOUSE1",
      "countryIsoAlphaCode": "IT",
      "districtAcronym": "PN",
      "municipality": "Fiume Veneto",
      "postalCode": "33080",
      "toponym": "via",
      "street": "Bassi",
      "streetNumber": 101,
      "resourceAddressDescription": "mario.rossi Primary HOUSE"
    }
  ]
}

Update

{
  "extension": {},
  "resource": {
    "extension": {
        "myFieldName": "myValue"
    },
    "externalSystemCode": "SAP",
    "identificationNumber": "mario.rossi",
    "startAddressCode": "mario.rossi HOUSE 2",
    "endAddressCode": "mario.rossi HOUSE 2",
    "startAddressFromOperationCenter": false,
    "endAddressFromOperationCenter": false
  },
  "addresses": [
    {
      "extension": {
         "myFieldName": "myValue"
      },
      "code": "HOUSE3",
      "countryIsoAlphaCode": "IT",
      "districtAcronym": "RM",
      "municipality": "Roma",
      "toponym": "via",
      "street": "Roma",
      "streetNumber": 50,
      "resourceAddressDescription": "mario.rossi Third HOUSE"
    }
  ]
}

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