Introduction
Profile Integrations can be used in conjunction with the Customer Service Hub to
- Create a new customer
- Update an existing customer record
- Pull through information from a customer record (into a Form, for example)
A common use case is when a CSA using the Customer Service Hub is raising an anonymous case.
- A Create profile integration can be used to create the customer profile as the CSA fills in the customer details on the relevant form. This avoids the need to create the record again separately once the call has ended, though it will not link the case being created to the new customer profile.
- It only removes the requirement to create the customer record once the call has ended, potentially requiring the customer to remain on the phone longer than necessary whilst creating the customer profile record.
- The custom create a customer functionality in the Customer Service Hub will require a profile integration.
- Profile Integrations are only supported by V2 Integrations.
Note: Custom profile forms that are added to Customer Portal do not require profile integrations. They will integrate user data automatically. Further Information on how to add a custom profile form to Customer Portal can be found here.
Using the ‘Get’ Profile Integration
The ‘Get’ profile integration will pull through data from a customer record upon input of the customer’s UCRN. For security reasons, the integration will only run if the entered UCRN is either the same as that of the form filler (i.e the user who is trying to run the integration) or if the form filler/user is a registered CSA on the Customer Service Hub. In order to display the information in a form, you will need to have the integration run on a lookup within the form and have fields whose datanames match the following (whichever ones you require):
- ‘name’ - This displays the customer’s full name including any prefixes or suffixes
- ‘sort_name’ - This displays the name in the format [Last name, First name]
- ‘prefix_id’
- ‘last_name’
- ‘first_name’
- ‘contact_id’ - This is not relevant and should not be used
- ‘birth_date’
- ‘ucrn’
- ‘status’
- ‘location’ - This pulls through a unique number that identifies the location of the customer (1=in council area, 2=out of council, 3=unknown, 4= no fixed abode, 5=overseas)
- ‘search_for_street_postcode’
- ‘house’
- ‘street’
- ‘locality’
- ‘town’
- ‘post_town’
- ‘county’
- ‘postcode’
- ‘uprn’
- ‘ward’
- ‘start_date’
- ‘end_date’
- ‘country_id’- This is a unique 4 digit number that identifies the country - a file is available listing each country’s ID
- ‘country’
- ‘flat’
- ‘lat’
- ‘lng’
- ‘address_type’ - This is not relevant and should not be used
- ‘contact_type’ - This displays either ‘Individual’ or ‘Organization’
- ‘consent_to_share’ - This displays either 0 or 1 depending on the value against the customer record (0=no, 1=yes)
- ‘preferred_contact_method’ - This displays a unique number from 1 to 4 (1 = Phone, 2 = Mobile, 3 = Email and 4 = Post)
- ‘notification_preference’ - allows you to configure a list of preferred contact methods without the restrictions imposed by using {Preferred_Contact_Method}
- ‘data_location’ - This is only for our customers using Connected Index
- ‘region’ - This is only for our customers using Connected Index
- ‘alternative_email’
- ‘email_address’ - This cannot be used to update the customer's email.
- ‘phone_number’
Create and Update Profile Integration
The Create profile integration can be used to create a new customer, and the Update profile integration can be used to update an existing customer record (with the exception of the email). The former requires the customer’s contact type (either Individual or Organization) and their Preferred Contact Method. In addition to these 2 mandatory fields, the Update profile integration also requires the customer’s UCRN (so that it knows which customer to update). Ensure, therefore, that any form fields that obtain the information for these are mandatory.
There are a range of fields that can be passed through using the profile integration. Most of them require strings of text; if something else is required this is specified in the help text next to the field. It should be noted that:
- Title requires the prefix_id
- Suffix requires the suffix_id
- Country ID requires the country’s unique 4 digit identifier
- Preferred Language requires the language’s unique ID (a list of language IDs are attached at the bottom of this document)
- Fields that require dates, such as Birth Date, can be given values from regular date fields within forms - but if supplying the value as a text string, it must be given in American format (i.e mm/dd/yyyy). The Data Location and Region fields are only applicable for our Connected Index customers.
- A new field is available in the integration which takes either 0 or 1 and allows the user to choose whether they would like the existing, primary address to be updated or a brand new address record to be created altogether. This can be mapped to a token for a custom user experience.
If updating an existing record, the start date will not revert to today’s date automatically, but it will if creating a new record (unless a start date has been explicitly provided by the user).
Help text exists on the End Date field to encourage users not to enter dates in the past for primary addresses Improvements to ‘location’ parameter The parameter, which must take a value from 1 to 5, will stay the same if a value is not entered and the user is updating an existing record, rather than reverting to 1 as it does currently. We look to add an end date to all old addresses, but if the user specifies their new address is not primary then we no longer automatically add an end date to the existing primary address
When using the integration on a form, you should enter tokens into the integration fields which reference the data names of the fields in the form from where you want to pass over the values. However, because you are storing these values into the customer’s profile, you should use the relevant system data names so that these values can be referenced in other forms (ensure these data names match the ones used on your Customer Portal profile form). For example, the field in which the user’s first name is entered should have data name ‘First_Name’, and the field in the integration should be {First_Name}. Please see the full list of system tokens available to use. It is recommended to return lists from the Customer Service Hub for some elements of the profile as it saves you having to build the select fields again. Further information on returning lists from the Customer Service Hub.
‘Ignore Empty Entries’ is a checkbox available on ‘update’ profile integrations. The function of the ‘Ignore Empty Entries’ checkbox is intended to allow users to update only certain aspects of a profile at a time, i.e. if ‘Ignore Empty Entries’ is ticked, updating Street address only will not result in, e.g., postcode being blanked out. Conversely, if ‘Ignore Empty Entries’ is unticked, entries left blank should be cleared on the address once saved. If an entry is blank in an update call and ‘Ignore Empty Entries’ is not ticked, the field will be cleared in the updated address.
Updating an address using an Update profile integration will add the new address to the customer record in addition to the previous address (see the end of this paragraph for the prevention of this). The address’ start and end dates are given as follows: for the old address, the start date stays the same; the end date stays the same if it wasn’t blank. If it was previously blank then it either stays empty or is set as today’s date, depending on the configuration of the checkbox in the integration named Keep empty end dates. As for the new address, the start date is set as the date set (via the field in the integration) or today’s date and time if nothing was given. The end date is configured by the field in the integration, and is blank if nothing was specified.
Addresses could be duplicated if a user checked ignore empty entries and left addresses blank. We have added conditional statements to the code to ensure that, when addresses are left blank, empty entries are ignored as intended.
When running an update call in a profile integration, Twitter accounts can now be updated or removed without issue.
Note: When the CSA edits a profile after submitting in the Customer Service Hub, then clicks to reopen it and edit again, the previously-changed values will repopulate the edit form when loaded again. In order for this functionality to operate, a pre-submission create/edit profile integration is required.
Custom Profile Fields
Additional support is provided for custom fields to store additional profile data (specifically in respect of MyGovScot) . These fields are numbered, appearing as custom_1 through to custom_28. These custom fields do not display in the customer record in the Customer Service Hub but can be pulled through into form fields.
Additionally support is provided for {Notification_Preference}. Using this field in your form allows you to configure a list of preferred contact methods without the restrictions imposed by using {Preferred_Contact_Method}
Further useful reading:
top of page
