POST /integration/assets/r1/notifications

BPMN Diagram (TBD)

Business Logic

This Integration API creates or updates a Notification for Asset.

One of code or externalCode must be present. If code is provided it has the precedence among the other fields.

One of statusCode or externalSystemStatusCode must be present. If statusCode is provided it has the precedence among the other fields.

One of (workOrderCode or workOrderExternalCode) or neither must be present. If workOrderCode is provided, it has the precedence among the other field.

If the input specifies these objects:

• Failure Mode Catalog → Then system verifies that the triplet failureModeType, failureModeGroup, failureModeCode is provided.

• Failure Effect Catalog → Then system verifies that the triplet failureEffectType, failureEffectGroup, failureEffectCode is provided.

• Asset Catalog → Then system verifies that the triplet assetCatalogType, assetCatalogGroup, assetCatalogCode is provided.

• Breakdown Catalog → Then system verifies that the triplet breakdownCatalogType, breakdownCatalogGroup, breakdownCatalogCode is provided.

• Fault Catalog → Then system verifies that the triplet faultCatalogType, faultCatalogGroup, faultCatalogCode is provided.

• Activity Catalog → Then system verifies that the triplet activityCatalogType, activityCatalogGroup, activityCatalogCode is provided.

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 in internal configuration.

This step is skipped if Input fields are null or 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 - Notification 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 - Notification Status Retrieval

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

STEP 5a - Notification Status Validation

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

These steps are skipped if externalStatusCode is provided in Input.

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 5b - External Status Validation

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

These steps are skipped if statusCode is provided in Input.

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 5c - Status from External Status Retrieval

System takes Input fields and checks the existence of status conversion rules in internal configuration.

These steps are skipped if statusCode is provided in Input.

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 - Asset 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 - Notification Priority 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 8 - Catalog Profile 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 - Catalog Retrieve

These steps are the same for all “object” Catalog provided in Input:

• Failure Mode Catalog

• Failure Effect Catalog

• Object Catalog

• Breakdown Catalog

• Fault Catalog

• Activity Catalog

These steps are skipped if one of the “object” Catalog is not provided.

STEP 9a - Catalog Type Validation

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

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

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

STEP 9b - Catalog Group Validation

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

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

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

STEP 9c - Catalog Code Validation

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

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

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

STEP 10 - Work Order 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 11 - User 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 12 - Notification Existence

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

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

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

STEP 13 - Notification Creation

System takes Input fields and creates a Notification and its dependencies.

STEP 13a - Notification Creation

System takes Input fields and creates a Notification.

If Response State is SUCCESS → continue to next step.

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

STEP 13b - Notification Position Creation

System takes Input fields and creates Notification Positions.

If Response State is SUCCESS → continue to next step.

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

STEP 13c - Notification Position Cause Creation

System takes Input fields and creates Notification Causes.

If Response State is SUCCESS → continue to next step.

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

STEP 13d - Notification Position Activity Creation

System takes Input fields and creates Notification Activities.

If Response State is SUCCESS → continue to next step.

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

STEP 13e - Relationship Notification and Work Order Creation

System takes Input fields and creates the relationship between Notification and Work Order.

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

System takes Input fields and modifies a Notification and its dependencies.

STEP 14a - Notification Update

System takes Input fields and updates the Notification.

This step is used also to logically cancel the Notification by updating the StatusCode to E0006.

If Response State is SUCCESS and StatusCode <> E0006→ continue to next step.

If Response State is SUCCESS and StatusCode = E0006→ elaboration is stopped. See Response payload fields.

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

STEP 14b - Notification Position Retrieve

System takes Input fields and checks their existence.

If System can obtain the Output fields, compares the positionExternalCode list in output with positionExternalCode list in input body:

• If there are positionExternalCode in output not present in input body → Delete → go to step Notification Position Deletion.

• If there are positionExternalCode in output present also in input body → Update → go to next step Notification Position Update.

• If there are positionExternalCode in input body not present in output → Create → go to step Notification Position Creation in Notification Creation case.

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

STEP 14c - Notification Position Deletion

System takes Input fields and sets status ‘Logically deleted' for Notification Positions. It is not a physical deletion.

This step is skipped if Input fields are null or absent.

If Response State is SUCCESS → continue to next step.

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

STEP 14d - Notification Position Update

System takes Input fields and updates Notification Positions.

This step is skipped if Input fields are null or absent.

If Response State is SUCCESS → continue to next step.

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

STEP 14e - Notification Position Activity Retrieve

System takes Input fields and checks their existence.

If System can obtain the Output fields, compares the catalogCodeId list in output with catalogCodeId list in input body for “Activities” object:

• If there are catalogCodeId in output not present in input body → Delete → go to step Notification Position Activity Deletion.

• If there are catalogCodeId in output present also in input body → Update → go to next step Notification Position Activity Update.

• If there are catalogCodeId in input body not present in output → Create → go to step Notification Position Activity Creation in Notification Creation case.

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

STEP 14f - Notification Position Activity Deletion

System takes Input fields and deletes Position Activities.

This step is skipped if Input fields are null or absent.

If Response State is SUCCESS → continue to next step.

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

STEP 14g - Notification Position Activity Update

System takes Input fields and updates Position Activities.

This step is skipped if Input fields are null or absent.

If Response State is SUCCESS → continue to next step.

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

STEP 14h- Notification Position Cause Retrieve

System takes Input fields and checks their existence.

If System can obtain the Output fields, compares the catalogCodeId list in output with catalogCodeId list in input body for “Faults” object:

• If there are catalogCodeId in output not present in input body → Delete → go to step Notification Position Cause Deletion.

• If there are catalogCodeId in output present also in input body → Update → go to next step Notification Position Cause Update.

• If there are catalogCodeId in input body not present in output → Create → go to step Notification Position Cause Creation in Notification Creation case.

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

STEP 14i - Notification Position Cause Deletion

System takes Input fields and deletes Position Causes.

This step is skipped if Input fields are null or absent.

If Response State is SUCCESS → continue to next step.

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

STEP 14l - Notification Position Cause Update

System takes Input fields and updates Position Causes.

This step is skipped if Input fields are null or absent.

If Response State is SUCCESS → continue to next step.

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

STEP 14m - Relationship Notification and Work Order Deletion

System takes Input fields and deletes the relationship between Notification and the old Work Order. It is not a physical deletion.

This step is skipped if Input fields are null or absent.

If Response State is SUCCESS → continue to next step.

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

STEP 14n - Relationship Notification and Work Order Creation

System takes Input fields and creates the relationship between Notification and the new Work Order.

This step is skipped if Input fields are null or absent.

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

{
  "externalSystemCode": "SAP_S4",
  "externalCode": "NOTIF-00123",
  "operationCenterCode": "OC_NORTH_WEST",
  "workCenterCode": "WC_ELECTRIC_01",
  "typeCode": "M1",
  "description": "Electrical fault detected on transformer unit",
  "externalSystemStatusCode": "OPEN",
  "assetCode": "ASSET-TRANSF-042",
  "priorityCode": "H1",
  "username": "john.doe",
  "downtime": true,
  "breakdownStartDate": "2026-06-28T08:30:00Z",
  "breakdownEndDate": "2026-06-28T14:00:00Z",
  "expectedStartDate": "2026-06-28T09:00:00Z",
  "expectedEndDate": "2026-06-29T17:00:00Z",
  "generationDate": "2026-06-28T08:35:00Z",
  "catalogProfileCode": "ELEC-FAULT-PROFILE",
  "workOrderExternalCode": "WO-EXT-98765",
  "failureCatalogType": "fc_type_1",
  "failureCatalogGroup": "fc_group_1",
  "failureCatalogCode": "failure_1",
  "notificationPositions": [
    {
      "positionExternalCode":"EXTPOSITION-001",
      "positionDescription": "Main coil winding failure",
      "assetCatalogType": "B",
      "assetCatalogGroup": "ELEC-OBJ",
      "assetCatalogCode": "E001",
      "assetDescription": "High voltage coil",
      "breakdownCatalogType": "B",
      "breakdownCatalogGroup": "ELEC-OBJ",
      "breakdownCatalogCode": "E001",
      "breakdownDescription": "Note",
      "faults": [
        {
          "faultCatalogType": "C",
          "faultCatalogGroup": "ELEC-CAUSE",
          "faultCatalogCode": "C-INSUL-01",
          "faultDescription": "Insulation degradation over time"
        }
      ],
      "activity": [
        {
          "activityCatalogType": "A",
          "activityCatalogGroup": "MAINT-ACT",
          "activityCatalogCode": "ACT-REPL",
          "activityDescription": "Replace coil winding unit"
        }
      ]
    }
  ]
}

Response documentation

Response payload fields

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

Extension fields:

Response example

{
  "id": 1010
}

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

Response error codes