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:

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"]
      }

      • 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") ).

    • 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* EXA-CON-BUS-WOR Default value to include by Customer, relates to the Domain
      incident, task workspace* WOR 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





Back to top