## External System Integration BzCtrl provides a native API ecosystem allowing external operational systems to create **Incidents** and **Tasks** seamlessly. This guarantees that issues and required actions are flagged automatically right within internal workflows, ensuring seamless lifecycle tracking and audit readiness directly inside BzCtrl.

**🎯 Key Value:** Eliminates manual human data entry by automating object instantiation via native background triggers contextually context-linked to upstream third-party user interfaces.

### Integration Lifecycle Architecture

1 **Identity Authentication & Authorization Request** POST

ACC (Staging)	https://acc.bzctrl.com/bzctrl-core-api/oauth/token
Production	https://bzctrl.com/bzctrl-core-api/oauth/token

Payload Schema (x-www-form-urlencoded) ``` grant_type=password&username=example@example.com&password=Ex@mpl3! ```

Response Identity Metadata (200 OK) ``` { "access_token": "xxxxxxxxxx", "token_type": "Bearer", "expires_in": 3600 } ```

2 **Object Instantiation (Create Incident or Task)** POST

ACC (Staging)	https://acc.bzctrl.com/bzctrl-core-api/api/v1/task/add-task
Production	https://www.bzctrl.com/bzctrl-core-api/api/v1/task/add-task

⚠️ Authentication Guard: You must supply the token received from step 1 inside the HTTP Request Header as: `Authorization: Bearer {access_token}`

Application JSON Payload ``` { "todoType": "TASK", "domainWorkSpace": "VTT-NLD-TML-FIN", "title": "Sample Title", "description": "Detailed tracking logs", "impact": "HIGH", "likelihood": "MEDIUM", "status": "TODO", "priority": "HIGH", "assignee": "user@vtti.com", "reporter": "user@vtti.com", "orderID": "SO-777" } ```

Response Payload ``` { "title": "Potential Customs claim", "taskType": "INCIDENT", "description": "Process non-conformance", "taskLink": "https://www.bzctrl.com/app/#/todo/IMP", "tags": ["SO 777"] } ```

💡 **Deep Linking Strategy:** The generated `taskLink` value should be saved into your custom relational databases or mapped directly to actions via inline UI redirection workflows like `window.open(response.taskLink)`.

### UI/UX Configuration & Business Requirements

**\*** Mandatory Field Italic - End User Input CAPITAL - Immutable System Generated Values

Context Scope	Payload Key	Value / Format	Functional Rules & Integration Comments
INCIDENT, TASK	todoType\*	INCIDENT	System type flag. Consumers may toggle manually to `TASK` or leave fixed as an explicit constant.
INCIDENT, TASK	domain\*	IMP-NLD-EXA-SWA	The overarching functional domain route assigned to the integrated customer client portfolio.
INCIDENT, TASK	workspace\*	SWA	Target workspace configuration context mapped securely underneath the organizational master domain profile.
INCIDENT, TASK	title\*	Free text input	Explicit user-facing text field. Defines the summary header of the target issue or event item.
INCIDENT, TASK	description\*	Free text input	Rich operational notes detailing context logs. Allows external users to offer clear scope narratives.
TASK	result	Free text input	Optional. Capture resolution details or expected metric outcomes when running actions explicitly.
INCIDENT	financialImpact	Numeric format	Evaluated in EUR (€) currency. Raw integer values are automatically mapped inside the dashboard.
INCIDENT	impact	High, Medium, Low	Optional. Dropdown matrix mapping determining risk classifications inside the enterprise architecture.
INCIDENT	likelihood	High, Medium, Low	Optional. Probability index calculation variable used to define priority sort orders.
INCIDENT, TASK	status\*	In Progress	Defaults to `In Progress`. If marked as `Done`, due date triggers match runtime transactions automatically.
INCIDENT, TASK	priority	High, Medium, Low	Optional. Escalation index classification used by teams to structure internal workflows.
INCIDENT, TASK	assignee\*	user@example.com	Target action worker identity address. Usually identical to the reporting manager account parameters.
INCIDENT, TASK	reporter\*	user@example.com	Active communication email address of the authenticated authoring agent who opened the file.
INCIDENT, TASK	orderID\*	ServiceOrder #	Mapped directly into BzCtrl metadata engines as an searchable Index Tag attribute flag.
INCIDENT, TASK	LRN	LRN String	Optional. If accessible, provides secondary lookup search capabilities in internal trace tables.
INCIDENT, TASK	reminderDate	YYYY-MM-DD	Optional. Sets a date for a tracking alert event or task push notification trigger.