External System Integration for 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.

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.

Create Incident (or ~~Task~~Task)

The external system sends a PUT request using a predefined message structure.
~~The~~
{
~~request~~"todoType" ~~contains~~: "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 ~~information~~following ~~required~~should be considered (*Mandatory, Italic - User input,

Todo Type	Fields	Input	Comments
incident, task	todoType*	INCIDENT	Impala option to ~~create~~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 ~~Incident~~Domain orfor ~~Task~~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

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.~~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.

Example Integration Flow

~~Step 1 – Authentication Request~~

POST /api/authenticate  {   "username": "api_user",   "password": "********" }

Example Authentication Response

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Step 2 – Create Incident or Task

Example PUT Request

PUT /api/task

{
  "type": "Incident",
  "title": "Incorrect customs status identified",
  "description": "Mismatch detected during goods receipt",
  "workspace": "Inbound Control",
  "priority": "High"
}

Step 3 – Response from BzCtrl.

Example Response

{
  "status": "Success",
  "reference": "INC-2026-00125",
  "url": "https://app.bzctrl.com/incidents/INC-2026-00125"
}

~~The returned URL provides direct access to the Details Page of the created Incident or Task within BzCtrl.~~

Typical Use Cases

~~Registering operational incidents directly from ERP or WMS systems~~
~~Creating follow-up Tasks from external compliance applications~~
~~Linking operational activities with compliance monitoring in BzCtrl.~~
~~Providing users direct access from the external system to the corresponding item in BzCtrl.~~

~~[Insert screenshots of API requests, responses, and Details Page here]~~