<style>p { margin: 0; }span.fr-emoticon.fr-emoticon-img { background-repeat: no-repeat !important; font-size: inherit; height: 1em; width: 1em; min-height: 20px; min-width: 20px; display: inline-block; margin: -0.1em 0.1em 0.1em; line-height: 1; vertical-align: middle; } span.fr-emoticon { font-weight: normal; font-family: "Apple Color Emoji", "Segoe UI Emoji", "NotoColorEmoji", "Segoe UI Symbol", "Android Emoji", "EmojiSymbols"; display: inline; line-height: 0; } blockquote { border-left: solid 2px #5e35b1; color: #5e35b1; margin-left:0; padding-left:5px;}blockquote blockquote{ border-color: #00bcd4; color: #00bcd4;}blockquote blockquote blockquote{ border-color: #43a047; color: #43a047;} table.grid{ border-collapse: collapse;} table.grid td, table.grid th { border: 1px solid #ddd;} .fr-fic.fr-dib{ display: block; margin: 5px auto;}.fr-fic.fr-dib.fr-fir{ text-align: right; margin: 5px 0 5px auto;}.fr-fic.fr-dib.fr-fil{ text-align: left; margin: 5px auto 5px 0;}.fr-fic.fr-dii{ float: none; margin: 5px auto;}.fr-fic.fr-dii.fr-fil{ float: left; margin: 5px auto;}.fr-fic.fr-dii.fr-fir{ float: right; margin: 5px auto;}img.fr-dib.fr-fir { margin-right: 0; text-align: right;}img.fr-dib.fr-fil { margin-left: 0; text-align: left;}img.fr-dib { margin: 5px auto; display: block; float: none;}img.fr-bordered { box-sizing: content-box; border: solid 5px #CCC;}img.fr-shadow { box-shadow: 10px 10px 5px 0px #cccccc;}img.fr-rounded { border-radius: 10px; -moz-border-radius: 10px; -webkit-border-radius: 10px; -moz-background-clip: padding; -webkit-background-clip: padding-box; background-clip: padding-box;}</style><p><strong>In this guide we will cover:</strong></p><p><strong>- What are Custom Integrations?</strong></p><p><strong>- Creating a Custom Integration</strong></p><p><strong>- Custom Integration Methods </strong></p><p><strong>- Executing Custom Integration Methods - Runbooks</strong></p><p><br></p><p><br></p><p><strong><span style="font-size: 14pt;">What are Custom Integrations?</span></strong></p><p>Custom Integrations in Halo are used to authenticate access and execute requests to other APIs. This allows you to integrate your Halo instance with another tool as requests can be passed between tools via the API. In this guide we will cover how to setup a custom integration, how to setup a custom integration method and how to execute these methods.</p><p><br></p><p><strong><span style="font-size: 14pt;">Creating a Custom Integration</span></strong></p><p>To setup a custom integration head to Configuration > Integrations > Custom Integrations > Custom Integrations. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNhNWEwMGI0LTdiNTYtNGE0Yi05ZTY1LTE4NjMzODE5MmI3NCJ9.Hu-RorCOHOWQYZZrNR1bHmBqkrrK5XLacMf2fNYOE4c" class="fr-fic fr-fil fr-dib" width="1748" style="width: 1750px; height: 519.355px;" height="519"></p><p><strong><span style="font-size: 10pt;">Fig 1. Custom Integrations </span></strong></p><p><br></p><p>Here you will notice there are already some custom integrations available out of the box. These integrations have been pre-built out to allow certain functionalities in your Halo instance. You can use these existing custom integrations as reference however, we do not recommend editing these as this may impact existing functionality in your Halo instance. </p><p><br></p><p>Use the 'New' button to create a new custom integration. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY3NjE1ZjhlLWVhZGQtNDk3Yi05MTQ0LWFhODJmM2QxOGMwYyJ9.0PZJ8pLB-40wCl2IDP4fu3bnLANsR-yqxFr-PgCShPY" class="fr-fic fr-fil fr-dib" width="1411" style="width: 1413px; height: 769.043px;" height="769"></p><p><strong><span style="font-size: 10pt;">Fig 2. New custom integration</span></strong></p><p><strong><br></strong></p><p><strong>Name</strong> - Give the custom integration a sensible name. </p><p><strong>System Integration</strong> - Contains options for pre-built custom integrations. See the section on 'System Integrations' on how to use these. To integrate with an application not in this list, select 'None'. </p><p><strong>Version </strong>- Enter the version the custom integration is on. Useful when changes are made to the integration and a new version of the integration is created. </p><p><strong>Notes</strong> - Enter any notes you have about the custom integration. These will only be visible on this page. </p><p><strong>Base Resource URL</strong> - Here enter the base URL of the application you will be making requests to. This should be the root API endpoint the tool uses before specific paths or parameters are added. This will be pre-pended to the endpoint used in methods to send requests to. </p><p><strong>Authorization</strong> - Here choose the authorization method you would like to use for the custom integration. More information on this in the section 'Authorization methods'. </p><p><br></p><p><strong>API Accessibility</strong> - Here, choose if the API you are connecting to is externally accessible or internally accessible only, requiring a proxy to be used. APIs are typically only internally accessible when they are hosted on a private server. If 'Internally accessible only, use a proxy' is chosen you will be provided with options to enter the details of the proxy you have setup to connect to the API along with the certificate to authenticate connection.</p><p><br></p><p><strong><span style="font-size: 12pt;">System Integrations</span></strong></p><p>System integrations are typically used when you are already using the system integration Halo has built with the application, therefore have already authenticated the connection between Halo and the other application (using the dedicated integration module). But you would like to configure custom requests to be sent to this application, to achieve some custom integration functionality. </p><p><br></p><p>As authentication has already been set up for the application, choosing a system integration to use within a custom integration allows you to configure requests to be sent to the application without having to setup the authorization method again. Just keep in mind the authentication credentials required for the application, will need to be entered within the integration module for the integration. </p><p><br></p><p>The system integrations you have available to choose from will depend on which integration modules you have enabled in your Halo instance.</p><p><br></p><p><strong><em>Note: </em></strong><a href="https://usehalo.com/haloitsm/guides/2245/" target="_blank" rel="noopener noreferrer"><strong><em>SharePoint</em></strong></a><strong><em> is available as a system integration here from v2.238+. Only SharePoint connections using the authorization code authentication method can be used in custom integrations. </em></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">Authorization</span></strong></p><p>When creating a custom integration you will need to choose how you would like to authenticate Halo's access to this application using the 'Authorization' field. Once an authorization method is chosen you will be provided with the relevant fields to enter authorization credentials in. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImI0YjY4NTg2LTY5MDYtNDE1YS1hM2M4LTVhZTQxNzMzYjgxMiJ9.dAvSEB0YW_qIdNm-hn4RoTCkLdFF9dx-pryGG2MeDY0" class="fr-fic fr-fil fr-dib" width="748" height="290"></p><p><strong><span style="font-size: 10pt;">Fig 3. Authorization Methods</span></strong></p><p><br></p><p>Current authorization methods include:</p><ul><li>None - Used when the API you are sending requests to does not require authentication to be able to access. </li><li>API Key</li><li>Bearer Token</li><li>Basic Auth</li><li>OAuth 2.0 - Supports Client Credentials, Password Credentials, Authorization Code and Authorization Code (with PKCE) grant types</li><li>Sign Request Body with a X.509 Certificate</li><li>Sign Request Body with a Secret Key</li><li>JWT Assertion - Supports HS256, RS256 and PS256 algorithms </li><li>mTLS (Mutual TLS)</li></ul><p data-pasted="true">From v2.234.1+, if using OAuth 2.0, you will be able to set a token expiry date for when the OAuth token received does not contain an expires_in or expiry_date property. Leave this field blank for tokens which do not expire. </p><p><br></p><p><strong>JWT Assertion</strong></p><p data-pasted="true">The JWT assertion authentication method generates a signed JWT and uses it to fetch an access token from the token endpoint. </p><p><br></p><p>For PS256 you can choose an existing pfx certificate that is stored in Halo, or manually enter the private key and certificate id of the certificate you need to sign the JWT with. To store a certificate in Halo, head to Configuration > Advanced Settings > Certificates. </p><p><br></p><p>You can also specify additional claims to be included inside the JWT body. Some claims are automatically included by default.</p><p><br></p><p>For all algorithms the application/x-www-form-urlencoded content type can also be used for fetching the access token with the JWT, as well as application/json using bearer authentication.</p><p><br></p><p><strong>Creating instance specific Authorization</strong></p><p>If you have multiple linked Halo instances (Prod/UAT/Dev), multiple authorization credentials can be setup against a custom integration, linked to each of your instances. This allows a single custom integration to be used in multiple instances. Useful when syncing changes made to the custom integration between instances.</p><p><br></p><p>This functionality is available when using the authorization method OAuth 2.0 with the grant type Client Credentials. To use this enable the option 'Enable linked instance Client Credentials' under the authorization details. Once enabled, a 'Client Credentials' table will become available.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImZmMzI5ZWJiLWQ0ZGMtNDg4NC1hNWIwLWUzMGUyYTJmYWNkYyJ9.-ZEvAvceRvN6GMuPP4U0Bj8RMBoPLBKFCKOll5DQhhs" class="fr-fic fr-fil fr-dib" width="1451" style="width: 1453px; height: 709.159px;" height="709"></p><p><strong><span style="font-size: 10pt;">Fig 4. Enable linked instance Client Credentials</span></strong></p><p><br></p><p data-pasted="true">When using OAuth 2.0 you will see a button to clear tokens on this page. This button should be clicked if any permissions are changed in order to update the tokens.</p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijk5NDk1MGNhLTE5MmYtNDRjOC1hNGU1LTAwNjBjZDkxMjRlMiJ9.YKLIfV3LTOYps1JuLgv-lK1BtIgv7OrHDRlprmizq28" class="fr-fic fr-fil fr-dib" width="837" height="106"></p><p data-pasted="true"><strong><span style="font-size: 10pt;">Fig 5. Clear Tokens option</span></strong></p><p><br></p><p><strong data-pasted="true"><em>Note: This button will only show when the page has been saved.</em></strong></p><p><br></p><p>Use the Client Credentials table to add a client ID and Secret per instance. When adding an entry you will need to select which instance the credentials should be used for.</p><p> </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImY0ZTE0MjZkLWZmYmItNDg4NC1hZWY5LWUxZmUzYWJlYjZlYyJ9.wd5wVrVtJRg2aq0_v81yP9g_bLrw-SBDytTSd5VizxE" class="fr-fic fr-fil fr-dib" width="618" style="width: 620px; height: 285.781px;" height="286"></p><p><strong><span style="font-size: 10pt;">Fig 6. Add instance specific credentials</span></strong></p><p><br></p><p><strong><span style="color: rgb(235, 107, 86);">Important: When using instance specific credentials you must ensure the variable <<halo_url>> is used in all parts of the integration method in which your Halo instance URL is required. This ensures the instance URL changes dynamically based on the Halo instance it is being executed in. </span></strong></p><p><br></p><p>Once your authorization setup is complete you are ready to create methods for your custom integration. </p><p><br></p><p><strong><span style="font-size: 12pt;">Integrating with your own Halo Instance</span></strong></p><p>A custom integration can be setup to make requests to your own Halo instance, from your Halo instance. Useful for building custom functionality in your instance. On versions prior to v2.234.6 you will need to setup an API application to generate authentication credentials that can then be plugged into a custom integration. </p><p><br></p><p>On versions v2.234.6+ you can use a Halo Automation Identity to authorise access to your own instance. This simplifies how integrations with your own instance are built. </p><p><br></p><p><strong><em>Note: A Halo Automation Identity will authenticate the integration's methods using an implementation of JWT assertion flow which automatically manages and rotates rsa keys, or utilises one-time use tokens depending on the scenario.</em></strong></p><p><br></p><p>To do this create a new API application with the authorisation method "Halo Automation Identity". </p><p><br></p><p>Then to use the API application to authenticate a custom integration set the "Connection" for the custom integration to be "Connect to your Halo". Then, in the "Run-as Application" field you can choose a Halo Automation Identity application. No further authorisation for the integration needs to be configured. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ijg0NTExMjIxLTJlZGEtNDg5OS1hODIyLWZlNDA5NzUzYmYyOSJ9.-Z66gtdPzECzjmvt55jSWfvY6ryo7CdoLrdoAskwQSk" class="fr-fic fr-fil fr-dib" width="1298" style="width: 1300px; height: 738.123px;" height="738"></p><p><strong><span style="font-size: 10pt;">Fig 7. Custom Integration to integrate with your own Halo instance</span></strong></p><p><br></p><p>Methods made for this custom integration will have their base URL for the method set automatically to be the URL of your Halo instance. Making methods easier to create. </p><p><br></p><p><strong><span style="font-size: 14pt;">Custom Integration Methods </span></strong></p><p id="isPasted">Methods define a series of different API requests that can be made for a given custom integration. This controls what information is obtained from, or sent to the integrated application. Each Method allows you to:</p><ul><li>Specify a HTTP Method (GET, POST, DELETE etc.) </li><li>Send requests to a particular endpoint.</li><li>Include Query Parameters for the requested resource.</li><li>Include request headers, and a request body (if the HTTP method permits).</li><li>Specify Output variables, which can be used further on down the road.</li></ul><p>Methods can either be setup from within the custom integration or from a runbook. </p><p><br></p><p>To create a new method from within the custom integration head to the 'Methods' tab and use the 'new' button. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjE2YWJjNTRkLTIyY2UtNGYxYy04MzllLWNkMmEyYmU5OTJjNyJ9.TX8YtxZ4ExzlTK6ohmbE3kwaRtJQy4-7muKLjXyuazI" class="fr-fic fr-fil fr-dib" width="1503" style="width: 1505px; height: 532.09px;" height="532"></p><p><strong><span style="font-size: 10pt;">Fig 8. Create new custom integration method</span></strong></p><p><br></p><p>When a new method is added you will be provided with the popup shown in figure 8, here you can configure what request is being sent and where to.</p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjllMWZkMGVmLTQwOGUtNGI5Zi1hYzFjLTc4NmYyMmU0NzA2YSJ9.xlRR2egSM4RntGKpno9ptu2xfWoDctiy4GtkuJFB1bY" class="fr-fil fr-dib" width="1525" style="width: 1527px; height: 698.67px;" height="699"></p><p><br></p><p><strong><span style="font-size: 10pt;">Fig 9. New Method</span></strong></p><p><br></p><p><strong>HTTP Method</strong> - Choose the HTTP method you would like the request to execute in the field highlighted in orange (1). </p><p><strong>Base URL</strong> - The field highlighted in green (2) will automatically pull through the 'Base Resource URL' set against the custom integration. </p><p><strong>Integration</strong> - The field highlighted in pink (3) will automatically be populated with the custom integration you have created this method from/for. This is used to populate the base URL for the method and provide authorisation to the request. </p><p><strong>Endpoint</strong> - The endpoint you would like to send the request to should be entered in the field highlighted in purple (4). </p><p><br></p><p><strong><span style="font-size: 12pt;">Query Params</span></strong></p><p>Within the 'Query Params' tab of the method you can add key value pairs to be appended to the request endpoint. These are usually used to sort and filter the results of the request for GET requests. </p><p><br></p><p>The 'Description' column in the query parameters table can be used to provide a description of the parameter; this will not be used in the request. </p><p><br></p><p>Path parameters such as /users/{id} will need to be added to the endpoint in order to be used. </p><p><br></p><p><strong><span style="font-size: 12pt;">Authorization</span></strong></p><p>Under this tab set how you would like the request to be authorised. To ensure the authorisation setup against the custom integration is used, under the 'Authorization' tab make sure 'Authorization' is set to be 'Inherit from integration settings'. However, this will be set by default.</p><p><img data-fr-image-pasted="true" src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNkNDMzNmRkLTNjZTMtNDU1My05MmFlLWM1YjE5NTFmMGVkOCJ9.mmTeM3N9ogDLjSh_o-6Audqh8tVPE0WW_QlR2SSUTEE" width="1005" height="415" style="box-sizing: inherit; border-style: none; cursor: pointer; padding: 0px 1px; user-select: none; text-align: left; color: rgb(0, 0, 0); font-family: sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial; width: 1007px; height: 415.364px; max-width: none !important;" id="isPasted" class="fr-fil fr-dib"></p><p><strong><span style="font-size: 10pt;">Fig 10. Authorization used for method</span></strong></p><p><br></p><p><strong><span style="font-size: 12pt;">Headers</span></strong></p><p>Under this tab enter the key value pairs for any headers that you would like to be included in the request. For example, if you are using a bearer token to authenticate the integration you will need an authorization header.</p><p><br></p><p><strong><span style="font-size: 12pt;">Body</span></strong></p><p>Under this tab you can add the body of the request to be sent to your chosen endpoint. You will need to choose what format the body will be sent in. </p><p><br></p><p><strong><span style="font-size: 12pt;">Output Variables </span></strong></p><p>Under this tab you can extract data from the response returned by this request and store this data in a variable. This variable can then be used in other requests in the same runbook. Runbooks are used to execute custom integration requests and will be covered in the next section. </p><p><br></p><p><strong><span style="font-size: 14pt;">Executing Custom Integration Methods - Runbooks</span></strong></p><p>Custom Integration Methods are used to configure requests you would like to be sent to another application. In order for these requests to be run you will need to setup an Integration Runbook, this will control which requests are sent and when. </p><p><br></p><p>Runbooks contain steps, with each step executing a different request. When creating a runbook, you will need to configure what request is executed at each step and the 'flow' of the steps. The flow controls the order in which requests are made, and which step should be executed next based on the outcome of a previous step. Therefore, a runbook step will need to be configured to execute the custom integration method created earlier.</p><p><br></p><p>To create a runbook head to Configuration > Integrations > Custom Integrations > Integration Runbooks > New. </p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjlhMjkwMThjLTgyYWItNDNjZi05NTcwLTAyZjcyMjg5OGY3NyJ9.V8C_x1k9V7BBVRExv1PWAqLl81-GWIvW-VQAMA50X0k" class="fr-fic fr-fil fr-dib" style="width: 1527px; height: 658.076px;" width="1852" height="799"></p><p><strong><span style="font-size: 10pt;">Fig 11. Create new integration runbook</span></strong></p><p><br></p><p>After giving the runbook a name and saving, head to the 'Flow Chart' tab. Here you will need to add a new step using the 'Add Step' button. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjBmMGI0MzYyLTZhMjAtNDBkMy1hNjY3LWVkMDU0NmNhMzY1NSJ9.EcxAjugliGBgXu8TNE0erP3P6qfIdQchQI--u_KKj_4" class="fr-fic fr-fil fr-dib" width="775" style="width: 777px; height: 451.832px;" height="452"></p><p><strong><span style="font-size: 10pt;">Fig 12. Add runbook step</span></strong></p><p><br></p><p>Set the step 'Type' to be 'Action' and the 'Action type' to be 'Execute an Integration Method'. Then in the 'Method' field you can select the custom integration method created earlier. </p><p><br></p><p><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFkOTdhYTZmLTUzODYtNGFlNi1iYzhlLTk2ZjhiOTQxZmVkZCJ9.Jf9tTzVcFc7R84gidzv8FNYcD2EtQyQUm1EYI7VmH1w" class="fr-fic fr-fil fr-dib" width="1456" style="width: 1458px; height: 711.673px;" height="712"></p><p><strong><span style="font-size: 10pt;">Fig 13. Runbook step to execute custom integration method. </span></strong></p><p><br></p><p><strong><em>Note: The 'Edit Method' button can be used to edit the custom integration method from within the runbook. Just keep in mind any edits will not be specific to this runbook, they will impact all runbooks the custom integration method is used in. </em></strong></p><p><br></p><p>Now you have a step to execute the custom integration method you will need to setup the rest of the runbook, including any other steps the runbook needs to execute and when the runbook itself is triggered. For information on creating runbooks in Halo checkout <a data-fr-linked="true" href="https://usehalo.com/haloitsm/guides/1630" id="isPasted" target="_blank" rel="noopener noreferrer">Custom Integrations/Runbooks</a>.</p><p><br></p><p><br></p>
