Skip to main content

api auth

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

    ACC: https://acc.bzctrl.com/bzctrl-core-api/oauth/token
    PROD: https://bzctrl.com/bzctrl-core-api/oauth/token

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

      • Username: example@example.com

      • Password: Ex@mpl3!

    • 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-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 TypeFieldsInputComments
      incident, tasktodoType*INCIDENTCustomer - option to change to Task (or in case only used for Incidents default value)
      incident, taskdomain*IMP-NLD-EXA-SWADefault value to include by Customer, relates to the Domain
      incident, taskworkspace*SWADefault value to include by Customer, relates to the Workspace under the Domain
      incident, tasktitle*Free text fieldCustomer, allow user to provide Title/Subject
      incident, taskdescription*Free text fieldCustomer, allow user to provide Description
      taskresultFree text fieldCustomer, allow user to provide Results  (optional)
      incidentfinancialImpactNumbers fieldCustomer - 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.
      incidentimpactHigh, Medium, LowCustomer, allow user to select out of these three options (optional)
      incidentlikelihoodHigh, Medium, LowCustomer, allow user to select out of these three options (optional)
      incident, taskstatus*In ProgressOptions 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, taskpriorityHigh, Medium, LowCustomer, allow user to select out of these three options (optional)
      incident, taskassignee*User@example.comCustomer, Same as Reporter. E-mail address of the User.
      incident, taskreporter*User@example.comCustomer, E-mail address of the User.
      incident, taskcategory n/a
      incident, taskorderID*ServiceOrder NumberCustomer - BzCrtrl. - Set as Tag
      incident, taskLRNLRNCustomer - BzCrtrl. - Set as Tag (if available handy reference)
      incident, taskreminderDateCalendar selectionn/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 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") ).




Back to top