A guide detailing the configuration and use of the 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.
Create a connected app in order to connect your Halo to your Salesforce:
Give the connected app an arbitrary name, the API Name will auto populate based on the connected apps name.
Under API (Enable OAuth Settings), check the box to enable OAuth settings, which should give you an extra set of options:
The callback URL which is found above the OAuth Scopes must be in the following format:
https://{Your Halo Domain}/oauth/callback
e.g. https://test.haloservicedesk.com/oauth/callback
For the selected OAuth scopes, the following scopes are required:
- Full access (full)
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 find your new managed app, then edit it:
Set the following options for your managed app:
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.
Then in the "Allowed Origins List" add in the URL of your Halo instance:
Halo Configuration
These steps outline the Halo configuration that must be completed in order for the Salesforce integration to work. T
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 by clicking the "+" sign.
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 consume 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. The access token will expire if you do not use the integration. In other words the Halo Integrator needs to be turned on to ensure the API key refreshes, otherwise you will need to login constantly again.
In the Managed Connected App, a new "Initial Access Token" can be generated if any issues are experienced during connection:
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
NB: If mapping the account manager field (Halo) the field you map this to in Salesforce must contain the account manager email address. This can then match on the user with that email in Halo and mark them as the account manager.
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.
Below is a list of all default synchronized Salesforce fields for tickets and clients
Client -> Account
Name
BillingStreet
BillingCity
BillingState
BillingPostalCode
User -> Contact
FirstName
LastName
Phone
MobilePhone
Ticket -> Case
Name/Subject
Description
AccountID
ContactID
Amount
Probability
CloseDate
StageName
Case Comment
Commentbody
IsPublished
Additional fields that can be synced to salesforce
The 'Potential Value' fields can also be synced to salesforce, this field has three types:
- Annual
- Monthly
- One-off
