<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><span style="font-size: 11pt;"><strong>In this guide we will cover:</strong></span></p><p><span style="font-size: 11pt;"><strong>- Downloading the Cove Usage Runbook</strong></span></p><p><span style="font-size: 11pt;"><strong>- Configuring the Runbook</strong></span></p><p><br></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">An Integration is now available for enabling device-level usage invoiced in Cove to be synced directly into Halo. This data can then be used to update the quantity of Recurring Invoice lines automatically.</span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 14pt;"><strong>Downloading The Cove Usage Runbook</strong></span></p><p><span style="font-size: 11pt;">To be able to use the integration, it must be downloaded from Halo's Runbook Online Repository. To do this, navigate to Configuration > Integrations > Custom Integrations > Integration Runbooks. Once on this page, select the globe icon in the top right corner of the page to enter the Online Repository. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImE4YWQ2ODE1LTlmMmItNDVkMC04MmRmLTFjYzFiMGVhODJkMSJ9.8Zv-l4Xbyai28cRZWh76AM3qFNabl3pxwemdys6z7W4" class="fr-fic fr-fil fr-dib" width="997" style="width: 999px; height: 551.889px;" height="552"></span></p><p><span style="font-size: 10pt;"><strong>Fig 1. Entering the Runbook Online Repository in Halo</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Once in the Online Repository, locate and select the "Cove Usage Billing Sync" Runbook (Figure 2a), and select the "Install to Halo" button (Figure 2b). </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImY4NDMzODY0LWJkOTUtNGRmNC1hNTZiLTk0OTQ2OTkyNTMzMSJ9.W7E-XSv2xGez3-78frnrMy9fd057MMgFkv2t7ToAITM" class="fr-fic fr-fil fr-dib" width="1052" style="width: 1054px; height: 772.82px;" height="773"></span></p><p><span style="font-size: 10pt;"><strong>Fig 2a. The Cove Usage Billing Sync Runbook available in the Online Repository</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjNkNWNkNGQ1LTQ3ZWEtNDk2ZS05ZDFjLTlkOTY4M2FiMTdhNCJ9.L_PsgGz37o3V2L3pNMRjspkxlQCQlQUkgAwZYfqyqiw" class="fr-fic fr-fil fr-dib" width="1017" height="651"></span></p><p><span style="font-size: 10pt;"><strong>Fig 2b. Installing the Cove Usage Billing Sync Runbook</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Once the Runbook has been installed locally onto your Halo, it can be found in Configuration > Integrations > Custom Integrations > Integration Runbooks. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 14pt;"><strong>Configuring The Runbook</strong></span></p><p><span style="font-size: 11pt;">Now that the Runbook has been downloaded, navigate to the Runbook and locate the "Runbook Level Variables" section in the Details tab. </span></p><p><br></p><p><span style="font-size: 11pt;">There are two ID variables located here that you need to supply with your relevant IDs - the "sfdcid" variable (Salesforce Accounts ID) and the "ContractID" variable. To supply your IDs for each of the variables edit the Runbook, select the pencil icon on each variable to edit them (Figure 3a), and enter the relevant ID in the empty value field (Figure 3b). </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImJhYTYyNTFkLTY2NzAtNDUxYS04ZDYxLTI1NmRiMzZmYTMzMCJ9.P62ERWfddOSx0X9_sGS_ufJABucWS2Pb4zmBDLs9B5U" class="fr-fic fr-fil fr-dib" width="1168" style="width: 1170px; height: 455.733px;" height="456"></span></p><p><span style="font-size: 10pt;"><strong>Fig 3a. Editing the Runbook variables</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjIxYTdiOGU2LTBjY2MtNGYyNy05MjMzLTk2YmY4YTNiNmEyMiJ9.rb_pf5_uDCA77abYLJQXdQwiapIghhMGu0Der4lxQLw" class="fr-fic fr-fil fr-dib" width="1163" style="width: 1165px; height: 828.552px;" height="829"></span></p><p><span style="font-size: 10pt;"><strong>Fig 3b. The value field for the Runbook variables</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Once the IDs are supplied for the two variables, save the Runbook and navigate to Configuration > Custom Objects > Custom Fields on a separate tab. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Create a new Customer-level <a href="https://usehalo.com/halopsa/guides/1938" target="_blank" rel="noopener noreferrer" style="font-size: 11pt;">Custom Field</a> - this will be used for storing the Cove Customer ID. Set the type to "Text" and the Input Type to "integer", take note of the Custom Field's Field Name and save. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjljODFmMmY5LWYwYjktNDEzNS04NjRhLTAxZjJkOGVlZmIzNiJ9.h1BTAyvti20j8udNF9ZFQbhO2ph6TdhLU02G3qxe32A" class="fr-fic fr-fil fr-dib" width="951" style="width: 953px; height: 606.534px;" height="607"></span></p><p><span style="font-size: 10pt;"><strong>Fig 4. Creating the new Custom Field for the Cove Customer ID</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Once created, this Custom Field will show against every Customer in the Custom Fields tab by default. You will need to ensure that this field is populated for all relevant Customers.</span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFiMTFjYTUyLTc1N2ItNGQ2Mi05MWFjLTI5MGJkNDVkNTRmNCJ9.VqnmAes77yR7BeXcdgwNXyFhNCaBueR8LuN8TP6mONI" class="fr-fic fr-fil fr-dib" width="866" style="width: 868px; height: 292.819px;" height="293"></span></p><p><span style="font-size: 10pt;"><strong>Fig 5. The new Customer level Custom Field will be visible by default against every Customer once created</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Once this is done, navigate back to the Runbook and into the Flow Chart tab. </span></p><p><br></p><p><span style="font-size: 11pt;">Edit the Runbook, edit the "Search Halo Clients" step (Figure 6a), and enter the Field Name of your new Custom Field in the where clause of the SQL query (Figure 6b).</span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImYwNjRlMGIwLTNjNjktNGU0NS1hN2EzLTlmOGNhMjIxNDM1NSJ9.sxLOd7qAbYJc6-OWdtwarCbhk8HKnjAaE9YBePHgv6U" class="fr-fic fr-fil fr-dib" width="755" style="width: 757px; height: 589.704px;" height="590"></span><br></p><p><span style="font-size: 10pt;"><strong>Fig 6a. Editing the Runbook step</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjM3MDBhZDNjLWIyNTMtNDQzNi05ZmU4LTY1MjIzYzAxNDZlNSJ9.HLY9zm5M67KWojzHXUv90RkmULEOIDKEontBlLHNNlQ" class="fr-fic fr-fil fr-dib" width="754" style="width: 756px; height: 370.7px;" height="371"></span></p><p><span style="font-size: 10pt;"><strong>Fig 6b. Entering the new Custom Field Field Name into the SQL query</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><strong><em>Note: Remember that the Custom Field's Field Name will have the letters "CF" prepended to it once saved in the system - ensure that these two letters are included when entering the Field Name into the SQL query, as illustrated in Figure 6b.</em></strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Once this is completed, save the step and then save the Runbook. You now need to create a Custom Integration for your Runbook with the correct permissions, this integration will be used for a Method in the Runbook that you will create later on.</span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Start by creating the API Application that the new Custom Integration will use. </span></p><p><br></p><p><span style="font-size: 11pt;">In a new tab, navigate to Configuration > Integrations > HaloPSA API > View Applications and select the "+ New" button in the top right corner to create a new API Application. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjIxMjVmYmQ0LTVhYTAtNDNhMS1iNGUzLWZkMDVlY2U0ZGJkYiJ9.Cpc6PyZvR5XTJDMg5w2TMh2hPvzqyfRhGW9eSHGlB1I" class="fr-fic fr-fil fr-dib" width="1328" style="width: 1330px; height: 498.84px;" height="499"></span></p><p><span style="font-size: 10pt;"><strong>Fig 7. Creating a new API Application in Halo</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Give the Application an appropriate name and set the Authentication Method to "Client ID and Secret". Select an appropriate administrator Agent profile for the "Agent to log in as" (Figure 8a). Then, in the Permissions tab of the Application, select the "all:standard" permission (Figure 8b). </span></p><p><br></p><p><span style="font-size: 11pt;"><em><strong>Note: It is best practice to not use an actual Agent for the "Agent to log in as" and instead use an Application Identity and apply the relevant permissions via its role. For more information on this, please refer to the </strong></em></span><span style="font-size: 11pt;"><em><strong><a href="https://halo.haloservicedesk.com/article?text=api%20application&entity=articles&id=1823" target="_blank" rel="noopener noreferrer">Creating API Applications</a></strong></em></span><span style="font-size: 11pt;"><strong><em> guide. </em></strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjlhNmM1Yjg5LWFmMjAtNDU3ZS04YzljLTcxZGFhNDY3ODU4ZCJ9.MBj0QAlnYopMzTle7v8KNpx7qN57thmU_kXnzVUefAc" class="fr-fic fr-fil fr-dib" width="933" style="width: 935px; height: 501.387px;" height="501"></span></p><p><span style="font-size: 10pt;"><strong>Fig 8a. Setting the Authentication Method and Agent for the API Application</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjEwNDBjMjE5LTVlNTgtNDAxZS1hZjYxLWIyY2UyZTFkMTY3YSJ9.mMRYZOS2Qc6TIOlv9NSXyn-iT1aRefZAncd4zu6n4Xc" class="fr-fic fr-fil fr-dib" width="913" style="width: 915px; height: 474.353px;" height="474"></span></p><p><span style="font-size: 10pt;"><strong>Fig 8b. The permission required for the API Application</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Copy your secret before saving the application and also take note of the Client ID. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">You can now create the Custom Integration. To do this, navigate to Configuration > Integrations > Custom Integrations > Custom Integrations. Create a new Custom Integration by selecting the "+ New" button in the top right corner. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Name the Integration "HaloPSA" and provide it with the following specifications: </span></p><ul><li style="font-size: 11pt;"><strong>Base resource URL: </strong>https://YOURHALODOMAIN.com/api</li><li style="font-size: 11pt;"><strong>Authorization:</strong> OAuth 2.0</li><li style="font-size: 11pt;"><strong>Grant Type:</strong> Client Credentials</li><li style="font-size: 11pt;"><strong>Access Token URL:</strong> {Your HaloPSA URL}/auth/token</li><li style="font-size: 11pt;"><strong>Client ID and Secret:</strong> The values that you copied from the new API Application</li><li style="font-size: 11pt;"><strong>Scope:</strong> all</li></ul><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImI0ZjY2OTc2LTMzYWItNDNhZC1iMjM5LTNkMGIwODMwOTE2ZCJ9.-N7hL9h5wNAXiyLXjqXB2zrOvQGH7vlCD9dw5e2uADY" class="fr-fic fr-fil fr-dib" width="768" style="width: 770px; height: 723.314px;" height="723"></span></p><p><span style="font-size: 10pt;"><strong>Fig 9. Custom Integration setup</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Save the Custom Integration and return to the Runbook. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Edit the Runbook, navigate to the Flow Chart tab and edit the "POST Subscription" step. Change the Action Type of this step to "Execute an Integration Method" and create a new method by selecting the "New Method" button.</span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImIwM2NlYjUzLTkyMjYtNGNkZC1iNTE1LWY1MWRkM2NhMWQxYSJ9.3oba-9yc8C2bKWZ323ZDJAiK1DDmHiJ17k1yT9oqAgo" class="fr-fic fr-fil fr-dib" width="1026" style="width: 1028px; height: 595.117px;" height="595"></span><span style="font-size: 10pt;"><strong>Fig 10. Editing the "POST Subscription" step of the Runbook</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Give the method an appropriate name, change the Integration to "HaloPSA", change it to a POST step, and set the endpoint to "/softwarelicence". </span></p><p><br></p><p><span style="font-size: 11pt;">In the Body tab, set the body type to JSON and enter the following JSON:</span></p><p><span style="font-size: 11pt;"><br></span></p><div data-pasted="true"><span style="font-size: 11pt;">[</span></div><div><span style="font-size: 11pt;"> {</span></div><div><span style="font-size: 11pt;"> "client_id": <<HaloClientID>>,</span></div><div><span style="font-size: 11pt;"> "Name": <<BillingServiceName>>,</span></div><div><span style="font-size: 11pt;"> "count": <<ServiceQuantityIntParsed!>>,</span></div><div><span style="font-size: 11pt;"> "type": 1</span></div><div><span style="font-size: 11pt;"> }</span></div><div><span style="font-size: 11pt;">]</span></div><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjExMmM0NTczLWM2Y2QtNDkxNC1iMmYxLTIxNTJkYWQyNTdiYSJ9.Xvjd2MLz47GlAw4KcnqbfqBZl-sDj_jRIitNLtNkHQ0" class="fr-fic fr-fil fr-dib" width="912" style="width: 914px; height: 423.817px;" height="424"></span></p><p><span style="font-size: 10pt;"><strong>Fig 11. The new method setup for the "POST Subscription" step</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Save the method, ensure the method is set for the Runbook step, then save the step and the Runbook and navigate back the Details tab.</span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Now that your Runbook has been configured, you need to set the schedule on which you want the Runbook to operate. To do this, scroll to the Schedule section of the Details tab and select "Set Schedule". </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImU2ODUxYTkxLTRhOTktNDhiMC1hNDhhLWRiMzRmODQ3NDFhMyJ9.2ZVpkf0JQ6u9sVofUz9UnkPGAzshXolFFNS6zjFddMo" class="fr-fic fr-fil fr-dib" width="732" style="width: 734px; height: 460.549px;" height="461"></span></p><p><span style="font-size: 10pt;"><strong>Fig 12. Setting the schedule for the Runbook - you can set whatever schedule you like here</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">Once the schedule is set, the configuration of your integration is complete. </span></p><p><br></p><p><span style="font-size: 11pt;">Now, on your chosen schedule, the Runbook will fetch the usage data from the Cove API and, for each Subscription, iterate through to identify the Customer associated with the Subscription using the Customer ID Custom Field for matching. When it matches to a Customer it will create the Subscription under the "Subscriptions" tab of that Customer. </span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;"><img src="https://halo.haloservicedesk.com/api/attachment/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjRjMDI5YzM0LWE5YzEtNDRkOS1hNjdjLThmNDg0ZGIzZjIxOSJ9.M6b4eo1F9FasCvixwTCudkN8K5ky4tfg8DeT5fp4Mg8" class="fr-fic fr-fil fr-dib" width="1003" style="width: 1005px; height: 334.146px;" height="334"></span></p><p><span style="font-size: 10pt;"><strong>Fig 13. A Subscription added against a Customer by the Cove Usage Billing Sync Runbook</strong></span></p><p><span style="font-size: 11pt;"><br></span></p><p><span style="font-size: 11pt;">These Subscriptions can then be tied to a Recurring Invoice Quantity count for that Customer - for information on this functionality please refer to the this guide: <a href="https://usehalo.com/halopsa/guides/1970/" target="_blank" rel="noopener noreferrer" style="font-size: 11pt;">Automating Quantities in Recurring Invoices</a>.</span></p><p><br></p>
