HaloITSM Guides
Documentation to assist with the setup and configuration of the HaloITSM platform
Salesforce Integration
Salesforce Configuration
Before making any configuration changes in Halo, there are some required configuration steps that must be completed in Salesforce.
Create Managed Application
The first requirement is to create a managed application. To do this, you need to access the setup screen in Salesforce by using the following toolbar option:
Once in the Setup view, in the tree view on the left-hand side, go to Platform Tools > Apps > App Manager, and choose “New Connected App” in the top right of the screen. Fill in the required fields under basic information, and any additional fields that you wish.
Under API (Enable OAuth Settings), check the box to enable OAuth settings, which should give you an extra set of options:
The callback URL must be in the following format:
https://{Your Halo URL}/oauth/callback
e.g. https://test.haloservicedesk.com/salesforce/callback
For the selected OAuth scopes, the following scopes are required:
- Access and Manage your data (api)
- Perform requests on your behalf at any time (refresh_token,offline_access)
If happy to, you may grant the “Full Access” permission, which gives you access to all scopes.
Please also check the following options:
Please also ensure that the option for 'Require Proof Key for Code Exchange (PKCE)' setting is turned off as below.
Once completed, you can save the new managed application. Your changes can take anywhere between 2-10 minutes to be processed.
Now go to the manage app page and set the following:
Add CORS Exceptions
The second requirement is to add any URL’s that require whitelisting for cross-origin resource sharing. Again, in the setup area of Salesforce, in the tree view on the left-hand side, go to Settings > Security > CORS. Add your Halo URL to the list of whitelisted origins.
Halo Configuration
These steps outline the Halo configuration that must be completed in order for the Salesforce integration to work.
General Setup
Once the Salesforce configuration has been completed, you can start to configure the integration in Halo. Firstly, to enable the Salesforce integration, go to Configuration > Integrations > Salesforce, and enable the module.
Once the module has been enabled, click into the module to access the configuration screen. The first steps are to input your Salesforce URL and application consumer key. Whilst the Salesforce URL you should be familiar with, the Consumer Key will need to be copied from the Managed Application you created in the previous steps.
It can be obtained by going to the settings view - Apps > App Manager > *Click "view" from the dropdown on your connected app* > *Click the Manage Consumer Details Button*. The Consumer Key will be visible under the API settings header. TO help with these steps, here are images to explain this:
Then click the dropdown to get the view option:
You can now copy your consure details to connect the App to Halo:
Finally add the URL, Consumer Key and Consumer Secret in Halo:
Access Tokens
Once you have completed the first three configuration boxes, you can try to retrieve an access token. This will require you to authenticate with Salesforce.
If successful, the Access Token will be displayed as a hidden password field. Note that this value cannot be copied or obtained.
You will not be able to continue until this step has been completed.
Imports
Now that an access token has been obtained, you will be able to open the importer screens for customers, users and opportunities. Before doing this, there are a few extra configuration options that require your attention.
First, you need to choose which ticket type new opportunities should be created as. The second option asks you to specify a default site. In some circumstances, you may not have imported the Users account/site from Salesforce before importing the user. If this case applies to you, then the user will be assigned to the default site you choose here.
The final option is an option that helps match users to opportunities. You should create a custom field for tickets that is going to hold the Opportunities associated user’s ID. As part of the mapping process which is covered later in this guide, you will need to map the user ID into this field, which means during the import of Opportunities, users can be assigned to opportunities if they exist in the system.
Once you’re happy with your choices, you can press any of the import buttons to retrieve your data from Salesforce (don’t worry, you have a chance to review the data before importing). Each importer will have fields mapped from Salesforce by default.
The final default mapped field is AttachmentCount. This displays the number of attachments found in Salesforce against the object, and indicates how many attachments will be retrieved during the import process. If this number is displaying 0 for an entity that you believe has attachments in Salesforce, then you will need to revisit permissions in Salesforce, and refresh your access token.
You may deselect any objects that you do not wish to import. Once ready, hit the start button, and the data will begin importing. The result column will display any results of the import.
NB: When mapping Salesforce Accounts to Halo Customers, you must type into the respective dropdowns to return records.
Field Mappings
Alongside the default fields, there may be additional information that you would like to bring into Halo. At the bottom of the configuration screen are three tables allowing you to map Salesforce Fields to Halo custom fields for each import entity.
To add a new mapping, find the relevant table and press the add button. You can choose the name of the Halo field from the drop down. The Salesforce field is a free text entry, and there are a few key points to consider:
- All fields must be capitalised, for example, “StageName” or “AccountId”.
- You can map both system and custom fields from Salesforce, but be careful not to map the same field twice.
- Custom fields have a suffix of __c, which must be included in the field name, e.g. “TaskType__c”.
For a full list of available system fields on each entity in Salesforce, please visit the following URLs:
- Customers - https://developer.salesforce.com/docs/atlas.en-us.sfFieldRef.meta/sfFieldRef/salesforce_field_reference_Account.htm
- Users - https://developer.salesforce.com/docs/atlas.en-us.sfFieldRef.meta/sfFieldRef/salesforce_field_reference_Contact.htm
- Opportunities - https://developer.salesforce.com/docs/atlas.en-us.sfFieldRef.meta/sfFieldRef/salesforce_field_reference_Opportunity.htm
Once you have added your field mapping, if you re-open the import screen, you will see your additional fields displayed to the right of the AttachmentCount column. If you have made a mistake with your field entries, an error message from the Salesforce API will be displayed in the middle of the import screen:
Remember, if you’d like to associate users with opportunities, you need to add a mapping to bring user ID’s into your designated custom field like so:
Custom field names can be found as below,
Syncing to Salesforce
You can now sync accounts, contacts, opportunities, cases, and case comments to salesforce.
Any fields mapped in the import from Salesforce can be marked as 'Include this field when syncing back to Salesforce' to sync them back to salesforce. All fields that are synced from Salesforce by default are also included in the sync back.
Accounts
This can be enabled for creation, updates, or both. You can also enable the syncing of the main site address back to salesforce. The setting 'Don't sync to Salesforce' allows you to disable the sync on a per customer basis.
Contacts
This can be enabled for creation, updates, or both. The setting 'Don't sync to Salesforce' allows you to disable the sync on a per-user basis. The user must be at a customer who has already been synced to salesforce in order for this sync to occur.
Opportunities
To sync opportunities you must configure the 'Opportunity Stage Names' and specify a default stage. These names should match the stages in Salesforce. You can override this at ticket type level or at individual ticket level by adding the 'Salesforce Stage' field to the opportunity ticket type.
The syncing of opportunities is enabled at ticket type level with the 'Sync to Salesforce' setting in the ticket type defaults tab. This can be overridden by adding 'Sync to Salesforce' as a field to the ticket type. This field will default to the value set at ticket type level.
Cases
The syncing of cases is enabled at ticket type level with the 'Sync to Salesforce' setting in the ticket type defaults tab. This can be overridden by adding 'Sync to Salesforce' as a field to the ticket type. This field will default to the value set at ticket type level.
To sync the case comment can be configured at action level 'Sync to Salesforce' setting in the action defaults tab. This can be overridden by adding 'Sync to Salesforce' as a field to the action. This field will default to the value set at action level.
This will sync the note on the action and also whether or not it is visible. Edits to actions will not be synced to salesforce.
Popular Guides
- Asset Import - CSV/XLS/Spreadsheet Method
- Call Management in Halo
- Creating a New Application for API Connections
- Creating Agents and Editing Agent Details
- Departments, Teams and Roles
- Halo Integrator
- Importing Data
- Multiple New Portals with different branding for one customer [Hosted]
- NHServer Deprecation User Guide
- Organisation Basics
- Organising Teams of Agents
- Step-by-Step Configuration Walk Through
- Suppliers