HaloPSA

HaloPSA Guides

Documentation to assist with the setup and configuration of the HaloPSA platform

Guides > Halo Integrator

Halo Integrator

Overview


The Halo Integrator is a separate application from the Halo Web tool, designed specifically for executing integration imports on a regular schedule. As new integrations are developed and integrated into the Halo Web Application, they become available for configuration and execution within the Halo Integrator. This division ensures efficient and timely handling of data integrations. Halo provides hosting of the Halo Integrator for hosted customers only.


Configuring the Halo Integrator


The Halo Integrator Module 


To access the Halo Integrator module in the Halo Web Application, go to Configuration > Integrations > Halo Integrator. Here, you can download the latest version from the link provided at the top of the page. The setup involves inputting an agent profile for the Integrator to log in as during integrations and generating a client secret for the application. The page also notes which integrations are enabled to run with the Halo Integrator. 




Lastly, you are also able to view various logs in the backend service monitoring regarding your cloud hosted Halo Integrator. 





Setting Up an "API-only" Agent Profile


When the Halo Integrator executes synchronization processes for your integrations, it acts as an Agent within your Halo instance. For certain integrations, the system maintains records of changes to entities handled by the integration. To ensure clear attribution of actions or uploads, it's recommended to create an "API-only" agent with Administrator access. Follow these steps to create an "API-only" agent:


  1. Navigate to Configuration > Teams & Agents > Agents.
  2. Click "New" in the top right corner.
  3. Assign a sensible username for this agent; it will be visible on records related to this agent's work.
  4. Grant the agent a system administrator-level role. In this example, using the "HaloITSM Administrator" role ensures proper access.
  5. Check the "is an API-only Agent" checkbox to avoid consuming a license for this agent profile.
  6. Click "Save" to complete the setup.

By creating an "API-only" agent, you ensure that integration-related activities are clearly associated with this dedicated agent, streamlining record-keeping and accountability.


Configuring Halo Integrator Agent Error Notifications

Released in Version: 2.100.1


Agents can receive notifications for Outgoing and Incoming Halo Integrator errors by using this setting located at Agent > Preferences > Notifications:



These email notifications will be sent from notifications@haloservicedesk.com


Note for Hosted Customers


For customers hosted by Halo Service Solutions, the client secret generated in Configuration > Integrations > Halo Integrator is always used for connecting your cloud-hosted integrator. Thus, generating a new secret will disconnect the cloud-hosted integrator. If you accidentally disconnect it and need to reconnect, contact Halo Support with the new secret. 


For hosted customers of Halo Service Solutions opting for a web-hosted Halo Integrator to manage integrations, your configuration is now complete! However, if you plan to host your own Halo Integrator, please proceed with the instructions outlined in this guide.


 Hosting Your Own Halo Integrator


 Some organizations may need to host their own Halo Integrator. This can be when an organization hosts their own Halo Web Application in which case the regular Halo Integrator Module setup can be used. In many cases however, a hosted customer may need to keep their cloud hosted Halo Integrator (to run integrations with applications accessible via the web) alongside locally hosted one (to run integrations with applications accessible ONLY locally). In this case, credentials from a separate Halo application are used to connect the locally hosted Halo Integrator. To assist with setting up a distinct Halo application to make the additional connection, guides can be found below:

Creating a new application for API connections (ITSM)

Creating a new application for API connections (PSA)


Downloading and Placing into your File Directory


  1. Access the download link located in Configuration > Integrations > Halo Integrator within the Halo Web Application.
  2. Initiate the download of the zip file, which contains the Halo Integrator version corresponding to your Halo Web App version.
  3. After the download completes, extract the files to your chosen hosting location for the Halo Integrator on your machine.
  4. In the extracted files, you'll find two versions of the Halo Integrator: a standard executable and a 64-bit version. Choose the appropriate version based on your machine's requirements.
  5. Once you've placed the selected executable in your desired location, run the executable.

 

Configuring the Windows Application


Upon running the executable, you will be met by the Halo Integrator UI. You’ll be navigated to the “Basic Configuration” tab by default. Here you can configure the basic connection credentials:

  • “Halo URL” is simply your Agent URL.
  • “Client ID” will default to a value in case you are using the default configuration method configured in Configuration > Integrations > Halo Integrator. In the case you are using a separate Halo application to connect this integrator, you will find that credential in the configuration of that application.
  • “Client Secret” can be found in the Configuration > Integrations > Halo Integrator page if you are using the default configuration method. In the case you are using a separate Halo application to connect this integrator, you will find that credential in the configuration of that application.




Once these credentials have been input, you can click “Validate” to test the connection. Once you ensure the credentials are correct, you may hit “Save” which will create the file, “appsettings.json” in the directory that your Halo Integrator is located in. This file stores the input credential information and any other configuration in the Halo Integrator application itself.


Integrations Tab


The “Integrations” tab allows you to configure exactly which integrations will be synced when this instance of the Halo Integrator is run. 


Note that integrations must be checked on to be synced with the Halo Integrator on both the Halo Integrator’s side AND on Halo’s side. This guide will cover how to enable integrations on Halo’s side to be synced with the Halo Integrator at a later point.



Processes Tab


The “Processing” tab is where all integration imports can be run. When the “Start” button is pressed, any integration that is enabled on Halo’s side and on the Halo Integrator’s side will be processed. All details from Sync will be logged into the text box provided. It is recommended that before setting up a recurring import, the process is started manually at least once to confirm that there are no configuration issues.



Setting Up a Recurring Sync


To run syncs automatically on recurring schedule, you must create a scheduled task in the “Task Scheduler” Windows app. This task must point to the Halo Integrator application and runs at your desired schedule. 


Task Configuration:

  1. Once You’ve opened “Task Scheduler”, click “Create Task…”.
  2. Within the “General” tab…
    1. Input a sensible name for your task.
    2. Set the task to “Run whether user is logged on or not”.
  3. Within the “Triggers” tab…
    1. Click “New…” to create a new trigger.
    2. Configure this trigger with your desired schedule.
      • The schedule can be set to as often as you wish as long as the integrator has enough time between scans to finish one scan. This schedule is most often set to once a day out of the Help Desk’s working hours.
  4. Within the “Actions” tab…
    1. Click “New…” to create a new action.
    2. Set “Action” to “Start a program”.
    3. Input the full file directory pointing at your Halo Integrator in the “Program/script” field.
    4. Input “AUTO” into the “Add arguments“ field.
      • This argument opens and runs the Halo Integrator without any user interaction and closes the application once a run is complete.
    5. Input the file path previous to the actual Halo Integrator executable into the “Start in” field.
      • This ensures that Halo Integrator logs are stored in the correct folder.


Available Integrations


Any integration that is compatible with the Halo Integrator will have a Halo Integrator section on the configuration screen. The layout of this section is consistent through all integrations. An option to enable the integration in the integrator is available, which when enabled, will reveal some additional options.


The above is taken from the new Azure Active Directory integration. The Last Sync and Last Error fields display the last successful run time of the corresponding integrations import, and the last error that occurred during that sync (if there was one). In some integrations, you will also have the option to choose which imports are included when running the Halo Integrator, as shown above for Azure Active Directory.


When running a sync via the Halo Integrator, all active integrations that have been enabled will be included. You should therefore ensure that you only enable an integration for the Halo Integrator once you are happy with the configuration, to avoid any unsuspected outcomes. The entities to sync over can often be specified per integration.

Popular Guides