HaloITSM
- Overview
- Setup
- Data & mappings
- Operations & API
- Changelog
The HaloITSM Connector integrates with the HaloITSM platform to synchronize ticket and CMDB report data. It connects to the HaloITSM API using OAuth2 authentication and retrieves:
- Tickets — full ticket attributes (status, priority, client, site, user, custom fields, etc.), with incremental sync via a
sincetimestamp. - Reports — rows from one or more configured HaloITSM CMDB reports, mapped to the Brinqa
HostUDM. Multiple report IDs can be configured as a comma-separated list.
Key features:
- Connects securely to the HaloITSM API using OAuth2 credentials.
- Fetches and maps all ticket attributes, including optional custom fields.
- Syncs one or more reports identified by Halo report IDs and maps each row to a
Hostrecord. - Supports incremental ticket sync via a timestamp parameter.
- Handles paging and retry logic for reliability.
- Provides configuration for API endpoint, credentials, paging, parallelism, retries, and report selection.
- Validates configuration and ensures all required parameters are set.
- Can be extended to support additional HaloITSM resources as needed.
Data retrieved from HaloITSM
| Connector Object | Required | Maps to Data Model |
|---|---|---|
| Ticket | Yes | Not mapped |
| Report | Yes | Host |
Model relationships
note
For detailed steps on how to view the data retrieved from HaloITSM in the Brinqa Platform, see How to view your data.
Connection settings
When setting up a data integration, select HaloITSM from the Connector dropdown and provide the following:
| Setting | Required | Default | Description |
|---|---|---|---|
| API URL | Yes | https://<server>/ | HaloITSM API URL |
| Client ID | Yes | (required, user-supplied) | HaloITSM client ID |
| Client secret | Yes | (required, user-supplied) | HaloITSM client secret |
| Page size | No | 100 | Maximum number of records to get per API request |
| Parallel requests | No | min(4, available processors) | Maximum number of parallel API requests |
| Maximum retries | No | 5 | Maximum number of retry attempts before giving up a request |
| Include custom fields | No | false | Flag to include custom fields as attributes on the Ticket model |
| Ticket type | No | (none) | Valid ticket type in the HaloITSM, such as "Incident" or "Problem" |
| Report IDs | No | — | HaloITSM report ID(s) to sync, comma-separated for multiple; when blank, no reports are synced |
Authentication
The connector authenticates with the HaloITSM API using OAuth 2.0 Client Credentials grant.
Endpoint
| Method | URL |
|---|---|
POST | https://{url}/auth/token |
Request Headers
| Header | Value |
|---|---|
Content-Type | application/x-www-form-urlencoded |
Request Body
{
"grant_type": "client_credentials",
"client_id": "your-client-id",
"client_secret": "your-client-secret",
"scope": "all"
}
Sample Response
{
"token_type": "Bearer",
"access_token": "Yrv-wS92nU2hHTFZE0T4NfCqQldz-WzJIrYcqcg0Wlc",
"expires_in": 3600
}
Response Fields
| Field | Type | Description |
|---|---|---|
token_type | String | Type of the token (Bearer) |
access_token | String | The access token to be used in subsequent requests |
expires_in | Integer | Token expiration time in seconds |
Usage
Once authenticated, all subsequent API requests include the bearer token:
Authorization: Bearer <access_token>
Sync Behavior
The connector supports incremental (delta) syncs. It maintains a sync token between runs and applies it as an incremental timestamp filter, so each run re-processes only the records that changed after the previous sync. The initial run retrieves the complete data set; later runs are incremental. The specific timestamp field applied to each object is documented under that object's Sync Duration Parameter.
How to obtain HaloITSM credentials
Obtain the required credentials (url, clientId, clientSecret) from your HaloITSM administrator or the HaloITSM admin console, then enter them in the connection settings above.
Attribute mappings
Expand the sections below to view the mappings between the source and the Brinqa data model attributes:
Ticket
| Source Field Name | SDM Attribute |
|---|---|
| Sync timestamp | LAST_CAPTURED |
ticket.agentId() | AGENT_ID |
ticket.appointmentType() | APPOINTMENT_TYPE |
ticket.attachmentCount() | ATTACHMENT_COUNT |
ticket.category1() | CATEGORY_1 |
ticket.category1Display() | CATEGORY_1_DISPLAY |
ticket.category2() | CATEGORY_2 |
ticket.category2Display() | CATEGORY_2_DISPLAY |
ticket.category3() | CATEGORY_3 |
ticket.category3Display() | CATEGORY_3_DISPLAY |
ticket.category4() | CATEGORY_4 |
ticket.category4Display() | CATEGORY_4_DISPLAY |
ticket.childCount() | CHILD_COUNT |
ticket.clientId() | CLIENT_ID |
ticket.clientName() | CLIENT_NAME |
ticket.cost() | COST |
ticket.createdFromAutomationStdId() | CREATED_FROM_AUTOMATION_STD_ID |
ticket.dateOccurred() | SOURCE_CREATED_DATE |
ticket.deadlineDate() | DEADLINE_DATE |
ticket.departmentId() | DEPARTMENT_ID |
ticket.details() | DESCRIPTION |
ticket.emailToList() | EMAIL_TO_LIST |
ticket.endUserStatus() | END_USER_STATUS |
ticket.estimate() | ESTIMATE |
ticket.estimateDays() | ESTIMATE_DAYS |
ticket.excludeFromSla() | EXCLUDE_FROM_SLA |
ticket.fixByDate() | FIX_BY_DATE |
ticket.flagged() | FLAGGED |
ticket.guid() | GUID |
ticket.id() | UID |
ticket.idSummary() | ID_SUMMARY |
ticket.impact() | IMPACT |
ticket.impactLevel() | IMPACT_LEVEL |
ticket.inactive() | INACTIVE |
ticket.invoiceSeperatelyOverride() | INVOICE_SEPERATELY_OVERRIDE |
ticket.isImportantContact() | IS_IMPORTANT_CONTACT |
ticket.isVip() | IS_VIP |
ticket.itilRequestTypeId() | ITIL_REQUEST_TYPE_ID |
ticket.lastActionDate() | LAST_ACTION_DATE |
ticket.lastIncomingEmail() | LAST_INCOMING_EMAIL |
ticket.lastUpdate() | SOURCE_LAST_MODIFIED |
ticket.matchedKbId() | MATCHED_KB_ID |
ticket.maximumRestrictedPriority() | MAXIMUM_RESTRICTED_PRIORITY |
ticket.mergedIntoId() | MERGED_INTO_ID |
ticket.notUsefulCount() | NOT_USEFUL_COUNT |
ticket.onHold() | ON_HOLD |
ticket.openSearchScore() | OPEN_SEARCH_SCORE |
ticket.oppCompanyName() | OPP_COMPANY_NAME |
ticket.oppValueAdjusted() | OPP_VALUE_ADJUSTED |
ticket.organisationId() | ORGANISATION_ID |
ticket.pipelineStageId() | PIPELINE_STAGE_ID |
ticket.priorityId() | PRIORITY_ID |
ticket.productId() | PRODUCT_ID |
ticket.projectInternalTask() | PROJECT_INTERNAL_TASK |
ticket.purchaseOrderNumber() | PURCHASE_ORDER_NUMBER |
ticket.quantity() | QUANTITY |
ticket.read() | READ |
ticket.release2Id() | RELEASE2_ID |
ticket.release3Id() | RELEASE3_ID |
ticket.releaseId() | RELEASE_ID |
ticket.releaseImportant() | RELEASE_IMPORTANT |
ticket.releaseNoteGroupId() | RELEASE_NOTE_GROUP_ID |
ticket.reportedBy() | REPORTED_BY |
ticket.respondByDate() | RESPOND_BY_DATE |
ticket.reviewed() | REVIEWED |
ticket.sectionTimezone() | SECTION_TIMEZONE |
ticket.serviceStatusNote() | SERVICE_STATUS_NOTE |
ticket.siteId() | SITE_ID |
ticket.siteName() | SITE_NAME |
ticket.siteTimezone() | SITE_TIMEZONE |
ticket.slaHoldTime() | SLA_HOLD_TIME |
ticket.slaId() | SLA_ID |
ticket.source() | SOURCE |
ticket.startTime() | START_TIME |
ticket.startTimeSlot() | START_TIME_SLOT |
ticket.statusId() | STATUS |
ticket.statusId() | STATUS_ID |
ticket.summary() | NAME |
ticket.supplierStatus() | SUPPLIER_STATUS |
ticket.table() | TABLE |
ticket.targetDate() | TARGET_DATE |
ticket.targetTime() | TARGET_TIME |
ticket.targetTimeSlot() | TARGET_TIME_SLOT |
ticket.team() | TEAM |
ticket.teamId() | TEAM_ID |
ticket.ticketAge() | TICKET_AGE |
ticket.ticketTags() | TICKET_TAGS |
ticket.ticketTypeId() | TICKETTYPE_ID |
ticket.updateServiceStatus() | UPDATE_SERVICE_STATUS |
ticket.urgency() | URGENCY |
ticket.use() | USE |
ticket.usefulCount() | USEFUL_COUNT |
ticket.userDef1() | USER_DEF_1 |
ticket.userDef2() | USER_DEF_2 |
ticket.userDef3() | USER_DEF_3 |
ticket.userDef4() | USER_DEF_4 |
ticket.userDef5() | USER_DEF_5 |
ticket.userEmail() | USER_EMAIL |
ticket.userId() | USER_ID |
ticket.userName() | USER_NAME |
ticket.workflowId() | WORKFLOW_ID |
ticket.workflowSeq() | WORKFLOW_SEQ |
ticket.workflowStep() | WORKFLOW_STEP |
Report
| Source Field Name | SDM Attribute |
|---|---|
(constant "Host") | CATEGORIES |
(sync timestamp) | LAST_CAPTURED |
| App Instance Name | BUSINESS_APPLICATION_INSTANCE_NAME |
| App Name | BUSINESS_APPLICATION_NAME |
| BA Owner | BUSINESS_APPLICATION_OWNER |
| BAI Owner | BUSINESS_APPLICATION_INSTANCE_OWNER |
| Device ID | UID |
| Device Status Name | DEVICE_STATUS_NAME |
| Device Status Name | STATUS |
| IP Address | IP_ADDRESSES |
| ITS Owner | IT_SERVICE_OWNER |
| Name | NAME |
| Operating System | OPERATING_SYSTEM |
| OS Version | OS_VERSION |
Owning BA ID (Calculated) | BUSINESS_APPLICATION_ID |
| Owning BAI ID | BUSINESS_APPLICATION_INSTANCE_ID |
Owning ITS ID (Calculated) | IT_SERVICE_ID |
| Routing TOM L1 INC | ROUTING_L1_INC |
| Routing TOM L1 REQ | ROUTING_L1_REQ |
| Routing TOM L2 INC | ROUTING_L2_INC |
| Routing TOM L2 REQ | ROUTING_L2_REQ |
| Routing TOM L3 INC | ROUTING_L3_INC |
| Routing TOM L3 REQ | ROUTING_L3_REQ |
| Serial Number | SERIAL_NUMBER |
| Service Name | IT_SERVICE_NAME |
| Service Organization | SERVICE_ORGANIZATION |
Operations & API
Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).
Ticket
Operation options
This object does not support any operation options.
Delta sync
Supported. The connector performs an incremental (delta) sync via the since sync token, filtering on last_update.
API
- Type: REST endpoint · Endpoint:
GET /api/tickets - Default filters:
datesearch=last_updatewithstartdate/enddatewhensinceis present;requesttype_idwhenticketTypeis configured;status_idwhen astatusoperation option is supplied
Report
Operation options
This object does not support any operation options.
Delta sync
Not supported. The connector performs a full sync of Report on every run and applies no incremental date filter.
API
- Type: REST endpoint · Endpoint:
GET /api/Report/{reportId} - Default filters:
includedetails=true&loadreport=true&dontloadsystemreport=false
Changelog
The HaloITSM connector has undergone the following changes:
| Version | Description | Migration Steps |
|---|---|---|
| 3.0.2 | New Features - Added support for syncing one or more HaloITSM CMDB reports as Host records. Configure the new Report IDs field (comma-separated) to choose which CMDB reports to ingest; when left blank, no reports are synced. Report columns Device ID, Name, Service Organization, IP Address, Device Status Name, Operating System, OS Version, Serial Number, Owning BAI ID, App Instance Name, BAI Owner, Owning BA ID (Calculated), App Name, BA Owner, Owning ITS ID (Calculated), Service Name, ITS Owner, Routing TOM L1 INC, Routing TOM L2 INC, Routing TOM L3 INC, Routing TOM L1 REQ, Routing TOM L2 REQ, and Routing TOM L3 REQ are mapped to Host attributes (Device ID is used as the record UID). Improvements - Documentation: Updated README to comply with modern Brinqa documentation standards. - Added a comprehensive Authentication guide for OAuth 2.0, detailed Model Mapping (Ticket to Incident), and a Model Relationship Diagram. Bug Fixes - Corrected the display title for the Ticket Exclude from SLA attribute (previously rendered as "Exclude from sLA"). - Corrected the Page size configuration help text to refer to "records" instead of "hosts". | N/A |
| 3.0.1 | New Features - Custom field synchronization: Added an optional setting to include HaloITSM custom fields as additional attributes on the Ticket model, so organization-specific data captured in HaloITSM is now available in Brinqa. - Ticket type filtering: Added a configuration option to restrict synchronization to a specific HaloITSM ticket type (for example, "Incident" or "Problem"), letting you sync only the tickets relevant to your workflow. Improvements - Expanded the set of Ticket attributes synchronized from HaloITSM, providing richer detail for each ticket. | N/A |
| 3.0.0 | Overview The HaloITSM connector integrates with the HaloITSM IT service management platform to synchronize ticket data, including status, priority, and related metadata. It connects securely using OAuth 2.0 and supports incremental synchronization to keep ticket data current. Category: IT Service Management Models | N/A |