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.
Authentication
Endpoint
ACC: https://acc.bzctrl.com/bzctrl-core-api/oauth/token
PROD:https://bzctrl.com/bzctrl-core-api/oauth/tokenRequest Method: POST
Request Body (x-www-form-urlencoded)
grant_type=password
username=example@example.com
password=Ex@mpl3!Sample Response
{
"access_token":"xxxxxxxxxx",
"refresh_token":"xxxxxxxxxx",
"token_type":"Bearer",
"expires_in":3600,
"scope":"*",
"jti":"xxxxxxxxxx"
}A successful authentication returns the token or authorization required for further communication.
Create Incident (or Task)
After receiving the access token from the OAuth API, use the Add Task API to create a new Task or Incident.
EndPont
ACC: https://acc.bzctrl.com/bzctrl-core-api/api/v1/task/add-task
PROD:https://www.bzctrl.com/bzctrl-core-api/api/v1/task/add-taskRequest Method: POST
Required Headers
Content-Type: application/json
Authorization: Bearer {access_token}Sample Request Body
{
"todoType":"TASK",
"domainWorkSpace":"VTT-NLD-TML-FIN",
"title":"title",
"description":"description",
"result":"result",
"financialImpact":"123",
"impact":"HIGH",
"likelihood":"MEDIUM",
"status":"TODO",
"priority":"HIGH",
"assignee":"rge@vtti.com",
"reporter":"user@vtti.com",
"category":["Customs","Fetsa"],
"subCategory":["high"],
"lrn":"test",
"orderID":"tag",
"reminderDate":"2024-09-27"
}Allowed Values
domainWorkspace:Workspace value from URL (Example: VTT-BEL-ATP)
todoType: TASK, INCIDENT
status: TODO, INPROGRESS, DONE
priority: LOW, MEDIUM, HIGH
impact: LOW, MEDIUM, HIGH
likelihood: LOW, MEDIUM, HIGH
reminderDate: Format YYYY-MM-DD
assignee: Valid email address (Example: rge@vtti.com)
reporter: Valid email address (Example: rge@vtti.com)Sample Response
{
"title":"Potential Customs claim",
"taskType":"INCIDENT",
"description":"Operation started without proper approvals",
"taskLink":"https://www.bzctrl.com/app/#/todo/IMP-NLD-EXA-SWA-03",
"tags":["SO 777"]
}Note: The access token received from the OAuth Token API must be included in the Authorization header using the Bearer scheme.
- {"todoType" : "INCIDENT""domain" : "IMP-NLD-EXA-SWA""workspace" : "SWA""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@example.com""reporter" : "username@example.com""category" : """orderID" : """LRN" : """reminderDate" : ""}
- From a UI/UX perspective the following should be considered (* Mandatory, Italic - User input, CAPITOL - System generated Values)
Todo Type Fields Input Comments incident, task todoType* INCIDENT Customer - option to change to Task (or in case only used for Incidents default value) incident, task domain* IMP-NLD-EXA-SWA Default value to include by Customer, relates to the Domain incident, task workspace* SWA Default value to include by Customer, relates to the Workspace under the Domain incident, task title* Free text field Customer, allow user to provide Title/Subject incident, task description* Free text field Customer, allow user to provide Description task result Free text field Customer, allow user to provide Results (optional) incident financialImpact Numbers field Customer - 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 Customer, allow user to select out of these three options (optional) incident likelihood High, Medium, Low Customer, 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. Customer - 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 Customer, allow user to select out of these three options (optional) incident, task assignee* User@example.com Customer, Same as Reporter. E-mail address of the User. incident, task reporter* User@example.com Customer, E-mail address of the User. incident, task category n/a incident, task orderID* ServiceOrder Number Customer - BzCrtrl. - Set as Tag incident, task LRN LRN Customer - 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).
- {"title": "Potential Customs claim","taskType": "INCIDENT","description": "Operation started without proper approvals","taskLink": "https://www.bzctrl.com/app/#/todo/IMP-NLD-EXA-SWA-03","tags": ["SO 777",]}
This URL can be stored in the external system for direct access and traceability. Or you can open this URL in the browser by the JavaScript function(window.open("URL") ).