Summary
Our integration with Xplan provides a seamless flow of data between systems, keeping your clients in sync, along with their critical financial information. Data moves in both directions, making it simple to keep your business management and financial planning platforms up-to-date. Here's a breakdown of how information is shared between systems:
NB:
Real Time = Automatic sync only on creation of that record. Updates need manual intervention either by pressing the 'Send to Xplan' button or via a nightly feed which requires a Professional Services engagement and development work in your organization.
|
|
|
|
|
Client |
Real-time 🠞 🠜 Scheduled
|
Client |
|
Primary Contact |
Client |
|
|
Partner Contact |
Partner |
|
|
Dependent |
Dependent |
|
|
Goal |
Goal |
|
|
Income |
Income |
|
|
Expense |
Expense |
|
|
Asset |
Asset |
|
|
Asset |
Superannuation Details |
|
|
Liability |
Liability | |
|
Feed Post |
Real-time 🠞 | Document Note |
|
Interaction |
Document Note | |
|
Service |
Document Note | |
|
Investment Asset |
🠜 Scheduled
|
Portfolio |
|
Insurance |
Policies |
How are records synchronized?
This integration creates a direct connection between the client records in both Practifi and Xplan, which causes all related child records - People, Income, Expenses, Assets & Liabilities - to be shared between systems. This means that if a Practifi record is linked to a client indirectly, e.g. an asset that's linked to a service that's linked to a client, then that record will not be in sync.
If your Practifi client contains primary and partner contacts, they will initially appear in Xplan as unlinked contacts which can cause some data accuracy issues, e.g. if income is owned by the partner, then upon initial sync it will appear to be owned by the primary. You can resolve this by linking the contacts in Xplan, then resyncing from Practifi.
Once clients are in sync, any updates to existing child records will be shared, as well as newly created ones. Changes made in Practifi are sent to Xplan in real-time, while changes made in Xplan are sent to Practifi on a scheduled basis; this schedule can be configured by your System Administrator.
IMPORTANT NOTE: Interactions will be auto-synced in near real-time. Feed Posts under interactions needed to be synced manually. All Feed Posts can be synced manually by using the 'Send to Xplan' button and also by a scheduled job for Feed Post.
Script to add a scheduled job for Feed Posts:
"cloupra.XPlanIntegrationInvocable xplan = new cloupra.XPlanIntegrationInvocable('pushFeedPost');
String sch = '00 30 02 * * ?';
String jobID = System.schedule('XPlan Push FeedPosts', sch, xplan);"
The default time is 2:30 am and can be changed as required.
Considerations before enabling
In order to use the integration effectively, the way in which you use Practifi should closely match the way you use Xplan. These behavior changes are summarized below. Ensure your users understand the implications before enabling the integration.
General
- Client ID field: The Xplan Client ID is stored on the Client External ID (cloupra__ExternalId__c) field, which is treated as the source of truth for tracking integration status per Client. This means that before integrating you should make sure this field is blank across all Client records, and by default, you cannot use the Xplan integration with other integrations that make use of this field. If you're unsure whether this affects you, please contact your Customer Success Manager.
- Linking existing Clients: When linking two existing Clients from both systems, child records will not be deduplicated, i.e. if the same Asset has been created in both systems, and then the Clients are linked, both Practifi and Xplan will have two copies of the same Asset. To resolve this, delete the duplicate records from one system or the other prior to establishing the sync.
- Value mapping: For fields with picklist/drop-down menus, values have to be mapped between systems to ensure they correspond. We provide a suite of standard value mappings, however you should check these prior to upload as values can differ between Xplan instances.
Data management
- Asset and Liability ownership
- Practifi allows you to allocate Asset and Liability ownership to Clients, People or Client Entities. Xplan only allows ownership to be allocated to People and requires that ownership percentages between People add up to 100% in order to sync successfully. As such, you cannot assign ownership to Clients or Client Entities for synced Assets and Liabilities.
- Xplan currently does not accept updates to Assets or Liabilities made from Practifi that only change ownership information. If you wish to update these values, either do so in Xplan or make the change alongside another one to the Asset, e.g. editing the Description field.
- Xplan requires that both Primary and Partner People have their ownership percentages defined, even if one of those is zero. Attempting to create an Asset or Liability in Practifi without both People defined will cause a sync error. Also, when viewing Assets and Liabilities in a table in Practifi, the Ownership column will show a Person's name even if their ownership percentage is zero.
- Practifi allows you to allocate Asset and Liability ownership to Clients, People or Client Entities. Xplan only allows ownership to be allocated to People and requires that ownership percentages between People add up to 100% in order to sync successfully. As such, you cannot assign ownership to Clients or Client Entities for synced Assets and Liabilities.
- Partner-only insurance and superannuation policies: Xplan has the ability to assign ownership of an insurance or superannuation policy to a partner exclusively, i.e. without any ownership on behalf of the primary client. Practifi will not sync insurance policies owned in this way, however defining the primary client as an owner with a 0% ownership level will enable policy sync.
- Income & Expense ownership
- In Practifi client ownership of these records is denoted in a picklist with the name of the owner (if the income/expense is jointly held, the value is left blank). In Xplan, this is captured in a picklist with the values "Client", "Partner" or "Joint".
- Upon initial sync, if your Practifi client contains primary and partner contacts, income and expenses owned by the partner will appear to be owned by the primary. You can resolve this by linking the primary and partner contacts in Xplan, then resyncing from Practifi.
- In Practifi client ownership of these records is denoted in a picklist with the name of the owner (if the income/expense is jointly held, the value is left blank). In Xplan, this is captured in a picklist with the values "Client", "Partner" or "Joint".
- Expense frequencies: Xplan contains values with no Practifi equivalent, which may cause some inaccuracies with summary calculations. We've addressed these as below:
- Twice a month: Mapped to Fortnightly
- Four weekly: Mapped to Monthly
- Bi-Monthly: Unmapped; selecting this value will exclude the expense from calculations
- Goal frequency: Goals sent from Xplan to Practifi do not support frequencies, however this is a required field in Practifi, so the value is set to 'Annual'.
Unsupported behavior and items
- Deleting records: Record deletion events aren't synced between systems; if you need to delete a record, it will need to be carried out in both systems separately. Because Practifi sync in real-time and Xplan syncs on a schedule, deleting from Practifi first removes the risk of the record being resynced before it's deleted in Xplan.
- Record owners: Modifying user ownership of records that are already synced is currently not supported. Changes to record ownership will need to be carried out in both systems.
- Relationship types: Modifying relationship types on records that are already synced is currently not supported. Changes to a relationship will need to be carried out in both systems.
- Premium, Life and TPD-specific information: Practifi currently only synchronizes data shared across all insurance types, which means fields specific to a policy type will not be shared.
- Beneficiaries on insurance policies: Both systems track policy beneficiaries separately to each other.
Enabling the integration
Configure settings and credentials for Oauth2 based authentication
- In order to set up an Oauth2 based integration, the first step is to create an Auth. Provider. In the Quick Find/Search bar, search for and click on Auth. Provider. Click New, then select the provider type as StaticOAuthProvider
- Fill out the details as shown below.
- The following fields should be completed:
- Authorize endpoint URL -> This refers to your Xplan domain URL followed by /oauth2/auth
- Token Endpoint URL -> Similarly, this refers to the user's Xplan domain URL followed by /oauth2/token
- Consumer Key and Consumer Secret -> Please reach out to your contact person in Practifi to procure both the keys. These keys are specific to Xplan's integration with Practifi.
- Execute As -> Can be the running user who is doing the integration or a system admin.
- Once the details have been entered, click Save.
- In the Quick Find/Search bar, search for and click on Named Credentials. Click on New Named Credential. For the URL, it needs to be pointed to https://api.iressopen.com.au (please note this used to point https://api.uat.iressopen.
com.au as the PRD end point was unavailable when this integration was first launched in 2019).
- Authentication provider refers to the Auth. Provider record created in the previous step. Complete the form as shown above, then click Save. Upon clicking Save, you will be taken to your Xplan site to authenticate. Enter your Xplan username, password and security code if applicable.
- If the authentication is successful, the Authentication Status in the Named Credential page will change from Pending to Authenticated.
- In the Quick Find/Search bar, search for and click on Custom Settings.
- Click Manage next to the Xplan Integration Settings record, then click the New button next to the Default Organization Level Value section.
- Complete the form as shown above, then click Save.
- For the Endpoint, it needs to be pointed to https://api.iressopen.com.au (please note this used to point https://api.uat.iressopen.
com.au as the PRD endpoint was unavailable when this integration was first launched in 2019). - The Forwarded Host field should contain the domain of your Xplan site, e.g. samplesite.xplan.iress.com.au.
- The Named_Credentials field should contain the name of the credentials you set previously. If you followed the steps above, the name should be Xplan_Oauth.
- App Id will be the same as the consumer key used previously.
- For the Endpoint, it needs to be pointed to https://api.iressopen.com.au (please note this used to point https://api.uat.iressopen.
- Create Records in remote site settings. Settings-> Remote Site Settings -> Click on New Remote Site. Create two records with the following details including your org Xplan URL. For the Remote Site URL, in the Xplan_Oauth record, it needs to be pointed to https://api.iressopen.com.au (please note this used to point https://api.uat.iressopen.com.au as the PRD end point was unavailable when this integration was first launched in 2019).
- In the left hand side menu, under Build, click on Create -> Objects -> Data Feed Mapping as shown below.
Under the Type picklist, create new values with "Adviser" and "Dependent Relation Type".
After completing these steps, you can proceed to the Add menu item tabs step.
Configure settings and credentials for basic authentication
- Complete the form as shown above, then click Save. The username and password should be those of an Xplan Administrator user.
- In the left hand side menu, under Build, click on Create -> Objects -> Data Feed Mapping as shown below:
Under the Type picklist, create new values with "Adviser" and "Dependent Relation Type".
Add menu item tabs
New tabs are required to support the new menu items in the integration, so you'll need to update the picklist value set, which is the global list of menu item tabs used across Practifi.
- In the Quick Find/Search bar, search for and click on Picklist Value Sets, then click on Menu Item Tabs.
- Click New, add values named "xplan" and "logs" separated by a new line, then click Save.
Import reference data
Four sheets of reference data need to be imported into Practifi in order to enable the integration:
- A data feed mapping file that includes mappings between Practifi and Xplan's picklist/drop-down menu fields (These may need to be modified refer https://api.uat.iressopen.com.au/swagger/index.html# for external ID and name, please see the Considerations section above for more information)
- A list of insurance and investment providers
- Data feed mapping to link the above providers between systems
- Menu items for the Xplan Settings and Data Management pages, as well as the error log (Requires the tabs from step 2)
To upload these files we've used Workbench but other tools such as the Salesforce Data Loader or dataloader.io can also be used.
- Start a new Upsert operation by selecting it from the Data menu. Complete the page as below, uploading this file: Xplan_Data_Feed_Mapping.csv. Click Next.
- Complete the field mapping as below, then click Map Fields, then Confirm. The import operation should complete successfully.
- Repeat the process for the Xplan_Providers.csv file, selecting an Object Type of Account and using the mapping defined below:
- cloupra__External_Id__c: External ID
- cloupra__Orgn_Type__c: Orgn Type
- cloupra__Provider_Type__c: Provider Type (Smart Lookup: cloupra__Category__c.cloupra__Code__c)
- Name: Name
- Repeat the process for the Xplan_Provider_Data_Feed_Mapping.csv file, selecting an Object Type of cloupra__Data_Feed_Mapping__c and using the mapping table below.
- Repeat the process for the XPLAN Menu Items.csv file, selecting an Object Type of cloupra__Menu_Item__c and using the mapping table below.
Link users between systems
In order to keep client ownership information consistent across systems, Xplan IDs must be provided for advisers. To discover a user's Xplan ID, go to My Preferences from their account and select My Details. The Xplan ID is the part of the URL in bold:
https://samplesite.xplan.iress.com.au/factfind/view/9999?role=user_self_edit&page=userselfedit
From Practifi Settings, go to the Xplan page, select the Mappings tab, then filter the table by the Adviser mapping type to see the existing list of mapped users.
- To add a new user, click the plus icon in the column heading row. Place the adviser's Xplan ID in the External Key field, and search for their Practifi user record in the User Value field. Add or edit more users if necessary, then click Save.
- To edit an existing user, click the pencil icon next to their table row and change the relevant fields. Add or edit more users if necessary, then click Save.
Comments
Please sign in to leave a comment.