Skip to main content

api auth

BzCtrl.📌 providesExposed aTask featureEndpoint thatPOST allows· externalupdate systems to create tagsIncidents https://acc.bzctrl.com/bzctrl-core-api/api/v1/task/add-exposed-task/ad9c8ff9-6f58-4a1f-9a40-1ea9ede919ff 🔖 Example tags body: {"tags":["urgent","bug-fix","frontend"]}

🔐 ACC OAuth Token endpoint and (POST)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: grant_type=password

    🌍 PROD OAuth Token endpoint (POST) https://bzctrl.com/bzctrl-core-api/oauth/token

     production

    • The external🔑 systemGenerate authenticatesOAuth usingToken aCredentials: dedicatedadmin@bzctrl.de 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 IncidentInspire#82 (orPOST Task)

    • The external system sends a x-www-form-urlencoded)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)
      incidentfinancialImpactNumbersCustomerGet ACC Token - For User ​ it

      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 aToken response messagefields
      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"🔑 Latest Access Token
      :—       "https://www.bzctrl.com/app/#/todo/IMP-NLD-EXA-SWA-03",

      ​
      "tags":
      "SOCopy 777",
      ]
      ​​
      ​
      }

    • ThisAccess URLToken can 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