XMLMC API Quickstart

Home > Integration > XMLMC API Quickstart Guide

Related Articles FAQ:Hornbill API's & Webhooks Essential Integrations Advanced Integrations API Keys Application Entity Viewer

Please note that there is now NEW documentation via these links:

• Platform API Reference
• Service Manager API Reference
• Documentation Library

Communication

One needs to POST a payload to a https endpoint with the HTTP headers containing the Authorisation. One can read up on other technical considerations in the FAQ:Hornbill API's & Webhooks.

Transmission

Endpoint obtained from Hornbill Administration

Data is to be sent over https (port: 443) to a given endpoint. The endpoint is different for each method you call. One can find the endpoint BASE URL for your particular instance by either viewing the About-section in Hornbill Administration or by looking at the response of https://files.hornbill.com/instances/<instance_name>/zoneinfo

The endpoint for the methods will then be followed by "xmlmc" before the "service" and the "method" within that service. This in turn is followed by a query string referencing the method. e.g. BASE URL / xmlmc / service?op=method

Documentation

Please also refer to: API Documentation

The endpoint base obtained, with the addition of "xmlmc/", will lead to the documentation on what methods are available (https://api.hornbill.com/xmlmc/ API). Your xmlmc base endpoint might look like: https://mdh-p01-api.hornbill.com/INSTANCE/xmlmc/.

The main page is grouped into two sections: Services and Applications.

Services are overall methods that the platform provides, whereas Applications define the functionality particular to the listed Applications. For instance: sending an email is a platform operation and logging a request is particular to Service Manager.

The documentation for each operation contains the following:

• General Description - what the operation does
• Operation Notes - any (specific) permissions required
• Request Message - Input Parameters - all items listed in bold are mandatory parameters - others are optional. Parameters must be added to the XML in the same sequence as given.
• Response Message - Output Parameters - any items listed in bold will be returned - others might be returned.
• Code Generation & Samples - this will give a code sample in some languages we have provided a library for PHP, .Net/C# in addition to a few we use internally (sorry). We do on occassion publish a library for other languages (Rust & Powershell) which can be found here.

Service

Within Hornbill platform there are various overall services with each a set of subsidiary operations.

The one listed as activity::activityChangeStatus will have the endpoint https://api.hornbill.com/INSTANCE/xmlmc/activity/?op=activityChangeStatus.

Application

Each application, which you have installed on your instance (including core), will be listed here. Within each Application, you will find two lists: Entities and Operations (at the bottom). These are the actions that are specific to the particular application.

Each Entity might also have "Operations" associated to it see further.

As of this writing, in com.hornbill.core, the first entity::operation combination is Achievement::addAchievement. The first Operation listed is addEveryoneToRole.

The endpoint for Achievement::addAchievement is https://api.hornbill.com/INSTANCE/xmlmc/apps/com.hornbill.core/Achievement?op=addAchievement

The endpoint for addEveryoneToRole is https://api.hornbill.com/INSTANCE/xmlmc/apps/com.hornbill.core/?op=addEveryoneToRole

Authorisation

The HTTP-header will need to contain the API Key which must be generated in the user's profile within the Hornbill Administration.

We will be using the Authorization -header with ESP-APIKEY prefixing the API key which can be obtained from the Hornbill Administration (API Keys).

The API key generated, belongs to the account under which it was generated. It takes on the permissions of that account. IF the account is not allowed to do something (via the GUI; eg access a particular call), then the API key will not be able to access that call either.

XMLMC

The default payload is expected to be XMLMC, so we will set the Content-Type-header accordingly.

Content-Type: text/xmlmc
Authorization: ESP-APIKEY ###32 hexadecimal characters####

The default response payload will be of in XML (text/xmlmc).

It is important to note that, when using XMLMC, all XML element names are CASE SENSITIVE, and input parameters MUST be passed to the operation in the same order as they appear in their definitions in order to satisfy the requirement of the input validation checks.

JSON

It is also possible to handle both payloads in JSON. The guidance given above on how to read the documentation regarding input and output parameters has not changed, except that the parameter ordering is not a requirement here. In order to be able to send JSON, one needs to set the Content-Type-header to application/json. By setting the Accept-header to application/json the response will be in JSON.

The JSON response payload will contain an @ sign as the first character in a property name. Not all JSON decoders will accept this.

Please take note that JSON is now the PREFERRED way to communicate to our API, there WAS a time when it was NOT Forum Entry

Samples

XMLMC Sample

XML Payload to add an entry to the Timeline of a Request (please note that both the request must exist as well as the account (of which the API Key is used) must be able to see the Request (i.e. via Service visibility etc) else errors will occur).

Content-Type: text/xmlmc
Authorization: ESP-APIKEY ...

<methodCall service="apps/com.hornbill.servicemanager/Requests" method="updateReqTimeline">
<params>
  <requestId>IN00001234</requestId>
  <content>Hello Service Manager XMLMC World</content>
  <visibility>trustedGuest</visibility>
</params>
</methodCall>

Resulting payload:

<methodCallResult status="ok">
<params>
  <activityId>urn:buzz:activity:...</activityId>
  <flowCodeDebugState>
    <executionId>...</executionId>
  </flowCodeDebugState>
</params>
</methodCallResult>

The flowCodeDebugState-structure can be ignored - it is useful for debugging in the log files.

JSON Sample

The JSON below is the SAME as the XML Request payload given above.

Content-Type: application/json
Authorization: ESP-APIKEY ...
Accept: application/json

{
  "@service": "apps/com.hornbill.servicemanager/Requests",
  "@method": "updateReqTimeline",
  "params": {
    "requestId": "IN00001234",
    "entity":"Hello Service Manager JSON World",
    "visibility": "trustedGuest"
  }
}

Resulting payload:

{
  "@status": true,
  "params": {
    "activityId": "urn:buzz:activity:..."
  },
  "flowCodeDebugState": {
    "executionId": "..."
  }
}

Please take note that JSON is now the PREFERRED way to communicate to our API, there WAS a time when it was NOT Forum Entry

Entities

From a programming perspective, an Entity is effecively an Object type behind the scenes. The Operations associated to these entities are effectively functions operating on entities of the given type (eg creation, changing status etc).

Technically a Service Manager Request is an Entity, BUT it is NOT advised/recommended/supported to modify Requests with the low-level data::entity* operations; Please use the more specific Requests operations instead (those operations wrap the necessary entity activity with relevant actions (i.e. BP triggers)).

To find out which fields are contained within an entity, and how it interlinks with other entities, one can find the "Application Entity Viewer" within each application (Application Entity Viewer). Please refer to the "Database Schema Viewer" within this for field definitions (types & lengths).

What Now?

Please also refer to: API Documentation

If any of the utility scripts we have created does what you want to do (eg User/Asset Creation/Update), then we recommend to inspect/reverse-engineer the scipts to find out which endpoints are invoked - and work your way from there. All the source code is freely downloadable from our github repository - very specifically, the PowerShell Runbooks might be the most useful

FAQs

If you have navigated through our documentation, you might have noticed that there are quite a few endpoints to choose from and it is sometimes difficult to find the exact operation you are looking for. The NEW API Documentation provides a subsection of those API endpoints which are more suitable to use. The list below are the few ones which most come up in conversation:

• apps/com.hornbill.servicemanager/Incidents::logIncident - to log an incident
• apps/com.hornbill.servicemanager/Requests::smGetRequests - listing of requests available to user - please also look at this article
• apps/com.hornbill.servicemanager/Requests::getRequestRecord - to get all request details
• apps/com.hornbill.servicemanager/Requests::smGetReqDetails2 - similar as above, but different
• apps/com.hornbill.servicemanager/Requests::updateReqTimeline - to add an entry to a given request's timeline
• activity::activityStreamQuery - to get the full timelime (<activityStreamID>urn:buzz:activityStream:{{GUID}}</activityStreamID>)
• apps/com.hornbill.servicemanager/Requests::smUpdateStatus - to set a Request's (Sub-)Status (using text)
• apps/com.hornbill.servicemanager/Requests::smUpdateSubstatus - to set a Request's SubStatus (using the h_status_id of the sub-status record in h_itsm_statuses)

https://api.hornbill.com/data/?op=entityBrowseRecords2

• data::entityBrowseRecords2 - querying Entities
  • Requests
  • Services
  • Site
  • Organizations
  • UserAccount
  • Contact
  • Asset

Looking to upload files?