Test new page
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.
Step 1 - Authentication
Before an ApiForm can be called, the external application must authenticate with BzCtrl. Authentication is performed by sending a
POST
request to the appropriate authentication endpoint using credentials provided for API communication.
Endpoints
Acceptance Environment (ACC)
https://acc.bzctrl.com/bzctrl-core-api/oauth/token
Production Environment (PROD)
https://bzctrl.com/bzctrl-core-api/oauth/token
Request Method
POST
Request Body (x-www-form-urlencoded)
grant_type=passwordusername=example@example.compassword=Ex@mpl3!
Sample Response
{"access_token":"xxxxxxxxxx","refresh_token":"xxxxxxxxxx","token_type":"Bearer","expires_in":3600,"scope":"*","jti":"xxxxxxxxxx"}
Result
Upon successful authentication, BzCtrl. returns an
access token
that must be included in subsequent API requests. The token serves as proof of authentication and authorizes communication with the BzCtrl. API. The token remains valid for the period specified in the
expires_in
field.
Step 2 - Create Incident (or Task)
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-task
Note: The access token received from the OAuth Token API must be included in the Authorization header using the Bearer scheme.
Request Method :
POST
Required Headers
Content-Type: application/json
Authorization: Bearer {access_token}
Sample Request Body
{
"todoType":"INCIDENT",
"domainWorkSpace":"EXA-CON-BUS-WOR",
"title":"
Potential Customs claim
",
"description":"
Operation started without proper approvals
",
"financialImpact":"123577",
"impact":"HIGH",
"likelihood":"MEDIUM",
"status":"IN PROGRESS",
"priority":"HIGH",
"assignee":"Example@example.com",
"reporter":"Example@example.com",
"category":["Customs"],
"subCategory":["IT"],
"lrn":"725462",
"orderID":"ORDER 777",
"reminderDate":"2024-09-27"
}
Sample Response
{
"title":"Potential Customs claim",
"taskType":"INCIDENT",
"description":"Operation started without proper approvals",
"taskLink":"https://www.bzctrl.com/app/#/todo/
EXA-CON-BUS-WOR
-03",
"tags":["ORDER 777"]
}