POST /integration/workforce/r1/resources

BPMN Diagram

Business Logic

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

Insert Only Validations

System verifies that startAddressCode or startAddressFromOperationCenter must have been provided (if both provided, startAddressCode prevails).

System verifies that endAddressCode or endAddressFromOperationCenter must have been provided (if both provided, endAddressCode prevails).

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.

System evaluates if Operation Center has one and only one main address.

This step is skipped if startAddressFromOperationCenter is false and 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 - Start Address Validation

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

System uses a calculated Code for the Address ('RESOURCE_' + startAddressCode) to manage the retry of the request.

System excludes addresses yet linked with an Asset or an Account (by targetId).

This step is skipped if Input fields are absent 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 10 - End Address Validation

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

System uses a calculated Code for the Address ('RESOURCE_' + endAddressCode) to manage the retry of the request.

System excludes addresses yet linked with an Asset or an Account (by targetId).

This step is skipped if Input fields are absent 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 11 - Resource Existence

System takes Input fields and checks their existence.

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

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 step Resource Update

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

  • if resource not exist → Creation → continue to next step.

  • 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 Resource Update

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

Error Type:

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.

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

System excludes addresses yet linked with an Asset or an Account (by targetId).

System checks also startAddressCode and endAddressCode if they appear in ‘Addresses’ object.

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.

System uses a calculated Code for the Address ('RESOURCE_' + address.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 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 for Resource Creation.

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 - Route Addresses for Resource Creation

System takes Input fields and creates 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