Skip to main content

External System Integration - Incidents & Tasks

BzCtrl. provides a feature that allows external systems to create Incidents and Tasks directly through REST API communication. This enables operational systems to register issues or actions directly within their own workflows while ensuring follow-up and tracking take place in BzCtrl.

The main value of this feature is that it allows Incidents and Tasks to be created directly from specific screens or processes within an external operational system, without requiring users to manually enter data into BzCtrl.

Integration Flow

The integration process consists of the following steps:

  • The request contains the information required to create the Incident (or Task) in BzCtrl.

  1. Authentication

    • The external system authenticates using a dedicated API Username and Password.

      • Username: OpenTAS@Impala.com

      • Password: Get1tdone!

    • Authentication is performed through a separate API request.

    • A successful authentication returns the token or authorization required for further communication.

  2. Create Incident (or Task)

    • The external system sends a PUT request using a predefined message structure.

    • {
      "todoType" : "INCIDENT"
      "domain" : "IMP-NLD-ITR-OPD"
      "workspace" : "OPD"
      "title" : "Free text field for User"
      "description" : "Free text field for User"
      "result" : "Free text field for User"
      "financialImpact" : "Numbers field for User (should be clear to User that it concerns a value in EUR)"
      "impact" : "Dropdown for User with options "High", "Medium", "Low""
      "likelihood" : "Dropdown for User with options "High", "Medium", "Low""
      "status" : "IN PROGRESS"
      "priority" : "Dropdown for User with options "High", "Medium", "Low""
      "assignee" : "username@impala.com"
      "reporter" : "username@impala.com"
      "category" : ""
      "orderID" : ""
      "LRN" : ""
      "reminderDate" : ""
      }
    • From a UI/UX perspective the following should be considered (*Mandatory, Italic - User input, 
    • Todo Type Fields Input Comments
      incident, task todoType* INCIDENT Impala  option to change to Task (or in case only used for Incidents default value)
      incident, task domain* IMP-NLD-ITR-OPD Default value to include by Impala, relates to the Domain for Impala Terminals Rotterdam B.V.
      incident, task workspace* OPD Default value to include by Impala, relates to the Workspace OpenTAS/Descartes under the Domain  Impala Terminals Rotterdam B.V.
      incident, task title* Free text field Impala, allow user to provide Title/Subject
      incident, task description* Free text field Impala, allow user to provide Description
      task result Free text field Impala, allow user to provide Results  (optional)
      incident financialImpact Numbers field Impala - For User  it should be clear this is a EUR amount. Only Number is provided. BzCtrl. - This should be included in the Field "Potential financial impact of the incident" set as EUR.
      incident impact High, Medium, Low Impala, allow user to select out of these three options (optional)
      incident likelihood High, Medium, Low Impala, allow user to select out of these three options (optional)
      incident, task status* In Progress Options BzCtrl. are To do, In Progress, Done and Expired. Impala - default when sending on In Progress, with option to change by User to Done. BzCrtrl. - If status - Done, set due date to date transaction.
      incident, task priority High, Medium, Low Impala, allow user to select out of these three options (optional)
      incident, task assignee* User@impala.com Impala, Same as Reporter. E-mail address of the User.
      incident, task reporter* User@impala.com Impala, E-mail address of the User.
      incident, task category   n/a
      incident, task orderID* ServiceOrder Number Impala - BzCrtrl. - Set as Tag
      incident, task LRN LRN Impala - BzCrtrl. - Set as Tag (if available handy reference)
      incident, task reminderDate Calendar selection n/a


  3. Response from BzCtrl.

    • BzCtrl. returns a response message confirming successful creation.

    • The response includes the direct URL to the Details Page of the created Incident (or Task).

    • {
      "title": "Potential Customs claim",
      "taskType": "INCIDENT",
      "description": "Operation started without proper apporvals",
      "taskKey": "OPD-03",
      "status": "INPROGRESS",
      "priority": null,
      "dueDate": null,
      "reminderDate": null,
      "completionDate": null,
      "taskLink": "https://www.bzctrl.com/impala/#/todo/IMP-NLD-ITR-OPD-03",
      "priorityLevel": 0,
      "assigneeUserGroupId": null,
      "creatorUserId": 1,
      "deleted": false,
      "isPrivate": false,
      "showResult": false,
      "tags": [
      "SO 777",
      ],
      "assignee": "Nazra Enait",
      "reporter": "Nazra Enait",
      "taskAttributes": [],
      "watchers": [],
      "todoList": [],
      "categoryList": [],
      "subCategoryList": [],
      "company": "Impala Terminals B.V.",
      "project": "OpenTAS/Descartes"
      }

    • This URL can be stored in the external system for direct access and traceability.




Back to top