Integrating with third-party applications by using the REST API
BMC Helix Knowledge Management by ComAround integrates with third-party applications such as contact center software, service management tools, and incident management systems by using the ComAround Connect APIs. For more information about how to use the APIs and code samples, see ComAround Connect.
Learn how BMC Helix Knowledge Management by ComAround can be used as a knowledge provider for BMC applications in Leveraging knowledge articles from BMC Helix Knowledge Management by ComAround in other BMC applications. For more information about using BMC Helix Knowledge Management by ComAround as a knowledge source for BMC HelixGPT, see Leveraging knowledge articles as a data source for BMC HelixGPT.
To obtain the subscription key
To begin using the ComAround Connect APIs, you must obtain an API subscription key by completing the following steps:
- Navigate to https://connect.comaround.com and click Sign up.
- Specify the fields on the Sign up form, and click Sign up.
An email is sent to your registered email address for you to confirm your new account. - Verify your account from the email you received.
- Sign in to https://connect.comaround.com and navigate to Products.
- On the Products page, click Default.
If you want to get the Extended API access, please contact BMC Helix Support. - On the Default page, enter your company's name in the Subscription name field, then click Subscribe.
Your profile opens automatically. - In the Subscriptions section of the user profile, click Show next to the Primary key and copy the key.
Access requirements and authorization
You can use only the local BMC Helix Knowledge Management by ComAround user account to call ComAround Connect APIs. Authentication via external identity providers, such as BMC Helix Single Sign-On or Microsoft Entra ID, is not supported.
Authorization is performed by requesting a bearer token from the /token endpoint. To request this token, you must send a POST request by using the subscription key together with the username and password of a local user:
tokenOcp-Apim-Subscription-Key: <subscription key from connect.comaround.com>
{
"username":"<local user username>",
"password":"<local user password>"
}
The response includes a bearer token and its lifetime. You must cache the token and reuse it until it expires. All subsequent API calls must include this token by using the Authorization: Bearer <token> header.
Required API call headers
ComAround Connect API calls must include several standard headers to authenticate and authorize the request. The following headers are required for every API call:
- Authorization: Bearer <token> — The bearer token retrieved from the /token endpoint.
- Ocp-Apim-Subscription-Key: <subscription key> — The subscription key from connect.comaround.com.
- Content-Type: application/json
Some headers apply only when specific conditions exist:
- Accept-Language: <language> — Use this header when retrieving content that must be returned in a specific portal language. The language must be one of the configured languages for the portal.
- X-Current-Portal-Id: <portal ID> — Use this header only when the local user has access to multiple portals, so the request can target the correct portal.
The following request example includes all mandatory and conditional headers:
Authorization: Bearer <token from above>
Ocp-Apim-Subscription-Key: <subscription key from connect.comaround.com>
Content-Type: application/json
X-Current-Portal-Id: 213
Accept-Language: en-us <- one of the configured languages for the selected portal
External content and media management
If you want to maintain your articles in an external database or other storage system, you must synchronize content by using the /changes endpoint:
This endpoint returns the IDs of all content that has changed since the specified timestamp, so that you can synchronize only these changes instead of reloading the entire dataset.
The Content API returns HTML content in some of its response fields. This HTML content includes links to images, videos, or attachments that are hosted by BMC Helix Knowledge Management by ComAround. These links are protected by using Shared Access Signatures (SAS), which expire after 60 minutes. If you host your content outside BMC Helix Knowledge Management by ComAround, you must download these media files and host them externally. You must also rewrite the embedded URLs in the HTML content so they point to the externally hosted copies.