XMLMC API InDepth

From Hornbill
Jump to navigation Jump to search

Home > Integration > XMLMC API Quickstart Guide

Related Articles

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

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" and then the "service". e.g. BASE URL / xmlmc / service

Documentation

Please also refer to: API Documentation

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:

  • Operation Information - some general information on where the operation technically fits and whether any (specific) permissions required
  • Description - what the operation does
  • Request Parameters
  • Response Parameters
  • Code Examples - this will give a code sample in some languages we have provided a library for PHP, .Net/C#. We do on occasion 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/.

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

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

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).

Information
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.

JSON

Payloads should be in JSON. The property names are case-sensitive. 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.

Content-Type: application/json
Authorization: ESP-APIKEY ###32 hexadecimal characters####


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

JSON Sample

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": "..."
  }
}


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


Entities

From a programming perspective, an Entity is effectively 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 scripts 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:

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

Looking to upload files?