Accelerator Salesforce Party Event Listener - Implementation Template
home
This API implementation template is a component of MuleSoft Accelerators, which accelerate the implementation of essential integration use cases.
The solution includes pre-built APIs, connectors, and integration templates that help unlock business-critical data from external systems and guide you in adopting best practices synthesized from thousands of customer implementations. Use these assets as is or extend them to meet your company’s unique needs.
Overview
The following functionality is supported by the Accelerator Salesforce Party Event Listener application.
CIM to Salesforce Objects Mapping
| Salesforce Object - Record Type | CIM Type |
|---|---|
| Account - Person Accounts | Customer with PartyType as Individual |
| Account - Account | Customer with PartyType as Organization |
| Account - Household | Household |
| Lead - Lead | Lead |
| Contact | Individual |
Customer event listener
This event listener is subscribed to the Platform Event channel configured in Salesforce with API Name as Account__e. A Trigger generates an Event based on changes in Account Object. This event listener can be started/stopped using the customer-event-listener-state property in the configuration file.
The fields including customer and contact information are part of this Platform Event. These fields are received as JSON Object from Salesforce and transformed to CIM data type and published to Anypoint MQ. In case of any failures, the incoming original payload is published to dead letter queue by the exception handler.
Customer Address event listener
This event listener is subscribed to the Platform Event channel configured in Salesforce with API Name as AccountAddresses__e. A Trigger generates an Event based on changes to a Postal Address on Account (Record Type as Person Account) Object. This event listener can be started/stopped using the customer-addresses-event-listener-state property in the configuration file.
The fields including the address information are part of this Platform Event. These fields are received as JSON Object from Salesforce and transformed to CIM data type and published to Anypoint MQ. In case of any failures, the incoming original payload is published to the dead letter queue by the exception handler.
Contact event listener
This event listener is subscribed to the Platform Event channel configured in Salesforce with API Name as Contact__e. A Trigger generates an Event based on changes in Account Object. This event listener can be started/stopped using the contact-event-listener-state property in the configuration file.
The fields in the Platform Event include contact information. These fields are received as JSON Object from Salesforce and transformed to CIM data type (Party as Individual) and published to Anypoint MQ. In case of any failures, the incoming original payload is published to the dead letter queue by the exception handler.
Household event listener
This event listener is subscribed to the Platform Event channel configured in Salesforce with API Name as Household__e. A Trigger generates an Event based on changes in Account Object. This event listener can be started/stopped using the household-event-listener-state property in the configuration file.
The fields in the Platform Event include household account information. These fields are received as JSON Object from Salesforce and transformed to CIM data type (Party as Household) and published to Anypoint MQ. In case of any failures, the incoming original payload is published to the dead letter queue by the exception handler.
Lead event listener
This event listener is subscribed to the Platform Event channel configured in Salesforce with API Name as Lead__e. A Trigger generates an Event based on changes in Account Object. This event listener can be started/stopped using the lead-event-listener-state property in the configuration file.
The fields in the Platform Event include lead information. These fields are received as JSON Object from Salesforce and transformed to CIM data type (Party as Individual) and published to Anypoint MQ. In case of any failures, the incoming original payload is published to the dead letter queue by the exception handler.
Opportunities event listener
This event listener is subscribed to the Platform Event channel configured in Salesforce with API Name as Opportunity__e. A Trigger generates an Event based on changes in Account Object.This event listener can be started/stopped using the opportunity-event-listener-state property in the configuration file.
The fields in the Platform Event include Opportunity information. These fields are received as JSON Object from Salesforce and transformed to CIM data type (Party as Opportunity) and published to Anypoint MQ. As Opportunity is always related to Account in Salesforce, a call is made to accel-salesforce-customers-sys-api opportunities endpoint to get the Account details. In case of any failure the incoming original payload is published to the dead letter queue by the exception handler.
Getting started
|
The Getting Started with MuleSoft Accelerators guide provides general information on getting started with the accelerator components. This includes instructions on setting up your local workstation for configuring and deploying the applications. |
Once your workstation has been set up and the application template imported into Anypoint Studio, proceed with the Prerequisites section.
Prerequisites
This implementation template has the following dependencies:
- Anypoint MQ Destinations
- Salesforce Platform Events
- Salesforce Apex Triggers
Please review the use cases described on the MuleSoft Accelerators solution pages for more information about dependencies on other APIs and services.
Anypoint MQ destinations
In addition to the Anypoint MQ client application credentials, the following destinations must be created and made accessible to this API:
- accel-partyrole-update-exchange
- accel-partyrole-update-dl-queue
- accel-address-update-exchange
- accel-address-update-dl-queue
- accel-party-update-exchange
- accel-party-update-dl-queue
- accel-lead-update-exchange
- accel-lead-update-dl-queue
- accel-opportunity-update-exchange
- accel-opportunity-update-dl-queue
Salesforce Platform Events
This implementation requires creation of Platform Events in Salesforce. To create a Platform event Object following the below steps:
- Login to Salesforce.
- Click Setup to search for
Platform Eventsin Quick Find Box. Platform Events Page under Integrations section appears with list of available Platform Events. - Click New Platform Event button to create an Object and enter Platform Information Details fields like Label, Plural Label and Object. Click Save.
- Enter Custom Fields & RelationShips to create an Event with specific defintions.
Platform Event Definition for Account PlatformEvent
Create a Platform Event with Label as AccountPlatformEvent, Object Name as Account and Custom Fields & RelationShips as per below table. These Custom fields can also be created via Apex script - instructions are included in the "Create Custom Fields via Apex script" section, below.
| Field Label | API Name | Data Type |
|---|---|---|
| AccountNumber | AccountNumber__c | Text(80) |
| BillingCity | BillingCity__c | Text(80) |
| BillingCountry | BillingCountry__c | Text(80) |
| BillingGeocodeAccuracy | BillingGeocodeAccuracy__c | Text(18) |
| BillingLatitude | BillingLatitude__c | Text(80) |
| BillingLongitude | BillingLongitude__c | Text(80) |
| BillingPostalCode | BillingPostalCode__c | Text(80) |
| BillingState | BillingState__c | Text(80) |
| BillingStreet | BillingStreet__c | Text(80) |
| CreatedDate | CreatedDate__c | Date/Time |
| Fax | Fax__c | Text(80) |
| FirstName | FirstName__c | Text(80) |
| Global_BillingAddress_Id | Global_BillingAddress_Id__c | Text(36) |
| Global_Customer_Id | Global_Customer_Id__c | Text(36) |
| Global_EmailAddress_Id | Global_EmailAddress_Id__c | Text(36) |
| Global_FaxNumber_Id | Global_FaxNumber_Id__c | Text(36) |
| Global_MailingAddress_Id | Global_MailingAddress_Id__c | Text(36) |
| Global_MobileNumber_Id | Global_MobileNumber_Id__c | Text(36) |
| Global_PhoneNumber_Id | Global_PhoneNumber_Id__c | Text(36) |
| Global_ShippingAddress_Id | Global_ShippingAddress_Id__c | Text(36) |
| Id | Id__c | Text(36) |
| IsDeleted | IsDeleted__c | Checkbox |
| IsPersonAccount | IsPersonAccount__c | Checkbox |
| LastModifiedDate | LastModifiedDate__c | Date/Time |
| LastName | LastName__c | Text(80) |
| Name | Name__c | Text(80) |
| PersonEmail | PersonEmail__c | Text(80) |
| PersonMailingCity | PersonMailingCity__c | Text(80) |
| PersonMailingCountry | PersonMailingCountry__c | Text(80) |
| PersonMailingGeocodeAccuracy | PersonMailingGeocodeAccuracy__c | Text(18) |
| PersonMailingLatitude | PersonMailingLatitude__c | Text(80) |
| PersonMailingLongitude | PersonMailingLongitude__c | Text(80) |
| PersonMailingPostalCode | PersonMailingPostalCode__c | Text(80) |
| PersonMailingState | PersonMailingState__c | Text(80) |
| PersonMailingStreet | PersonMailingStreet__c | Text(80) |
| PersonMobilePhone | PersonMobilePhone__c | Text(80) |
| Phone | Phone__c | Text(80) |
| ShippingCity | ShippingCity__c | Text(80) |
| ShippingCountry | ShippingCountry__c | Text(80) |
| ShippingGeocodeAccuracy | ShippingGeocodeAccuracy__c | Text(18) |
| ShippingLatitude | ShippingLatitude__c | Text(80) |
| ShippingLongitude | ShippingLongitude__c | Text(80) |
| ShippingPostalCode | ShippingPostalCode__c | Text(80) |
| ShippingState | ShippingState__c | Text(80) |
| ShippingStreet | ShippingStreet__c | Text(80) |
Platform Event Definition for Account Address PlatformEvent
Create a Platform Event with Label as AccountAddressPlatformEvent, Object Name as AccountAddresses and Custom Fields & RelationShips as per below table. As mentioned above, these Custom fields can also be created via Apex script.
| Field Label | API Name | Data Type |
|---|---|---|
| BillingCity | BillingCity__c | Text(80) |
| BillingCountry | BillingCountry__c | Text(80) |
| BillingGeocodeAccuracy | BillingGeocodeAccuracy__c | Text(10) |
| BillingLatitude | BillingLatitude__c | Text(10) |
| BillingLongitude | BillingLongitude__c | Text(10) |
| BillingPostalCode | BillingPostalCode__c | Text(10) |
| BillingState | BillingState__c | Text(80) |
| BillingStreet | BillingStreet__c | Text(80) |
| Global_BillingAddress_Id | Global_BillingAddress_Id__c | Text(36) |
| Global_MailingAddress_Id | Global_MailingAddress_Id__c | Text(36) |
| Id | Id__c | Text(36) |
| IsDeleted | IsDeleted__c | Checkbox |
| PersonMailingCity | PersonMailingCity__c | Text(80) |
| PersonMailingCountry | PersonMailingCountry__c | Text(80) |
| PersonMailingGeocodeAccuracy | PersonMailingGeocodeAccuracy__c | Text(10) |
| PersonMailingLatitude | PersonMailingLatitude__c | Text(10) |
| PersonMailingLongitude | PersonMailingLongitude__c | Text(10) |
| PersonMailingPostalCode | PersonMailingPostalCode__c | Text(10) |
| PersonMailingState | PersonMailingState__c | Text(80) |
| PersonMailingStreet | PersonMailingStreet__c | Text(80) |
Platform Event Definition for Contact PlatformEvent
Create a Platform Event with Label as ContactPlatformEvent, API Name as Contact and Custom Fields & RelationShips as per below table. As mentioned above, these Custom fields can also be created via Apex script.
| Field Label | API Name | Data Type |
|---|---|---|
| Birthdate | Birthdate__c | Date |
| CreatedDate | CreatedDate__c | Date/Time |
| Email__c | Text(80) | |
| FirstName | FirstName__c | Text(80) |
| Global_EmailAddress_Id | Global_EmailAddress_Id__c | Text(36) |
| Global_Individual_Id | Global_Individual_Id__c | Text(36) |
| Global_PhoneNumber_Id | Global_PhoneNumber_Id__c | Text(36) |
| Global_PostalAddress_Id | Global_PostalAddress_Id__c | Text(36) |
| Id | Id__c | Text(36) |
| IsDeleted | IsDeleted__c | Checkbox |
| LastModifiedDate | LastModifiedDate__c | Date/Time |
| LastName | LastName__c | Text(80) |
| MailingCity | MailingCity__c | Text(80) |
| MailingPostalCode | MailingPostalCode__c | Text(36) |
| MailingState | MailingState__c | Text(36) |
| MailingStreet | MailingStreet__c | Text(255) |
| Name | Name__c | Text(80) |
| Phone | Phone__c | Text(80) |
| Salutation | Salutation__c | Text(80) |
Platform Event Definition for Household PlatformEvent
Create a Platform Event with Label as HouseholdPlatformEvent, Object Name as Household and Custom Fields & RelationShips as per below table. As mentioned above, these Custom fields can also be created via Apex script.
| Field Label | API Name | Data Type |
|---|---|---|
| CreatedDate | CreatedDate__c | Date/Time |
| Global_Party_Id | Global_Party_Id__c | Text(36) |
| Id | Id__c | Text(36) |
| IsDeleted | IsDeleted__c | Checkbox |
| IsPersonAccount | IsPersonAccount__c | Checkbox |
| LastModifiedById | LastModifiedById__c | Text(36) |
| LastModifiedDate | LastModifiedDate__c | Date/Time |
| Name | Name__c | Text(80) |
| RecordTypeId | RecordTypeId__c | Text(36) |
Platform Event Definition for Opportunity PlatformEvent
Create a Platform Event with Label as OpportunityPlatformEvent, Object Name as Opportunity and Custom Fields & RelationShips as per below table. As mentioned above, these Custom fields can also be created via Apex script.
| Field Label | API Name | Data Type |
|---|---|---|
| AccountId | AccountId__c | Text(36) |
| Ach_Transfer_Auth_Document_Id | Ach_Transfer_Auth_Document_Id__c | Text(36) |
| Asset_Transfer_Auth_Document_Id | Asset_Transfer_Auth_Document_Id__c | Text(36) |
| CloseDate | CloseDate__c | Date/Time |
| CreatedDate | CreatedDate__c | Date/Time |
| Document_Signatures_Received | Document_Signatures_Received__c | Checkbox |
| Id | Id__c | Text(18) |
| IsClosed | IsClosed__c | Checkbox |
| IsDeleted | IsDeleted__c | Checkbox |
| IsWon | IsWon__c | Checkbox |
| KYC_Completed | KYC_Completed__c | Checkbox |
| LastModifiedDate | LastModifiedDate__c | Date/Time |
| Name | Name__c | Text(80) |
| StageName | StageName__c | Text(80) |
| Type | Type__c | Text(80) |
Platform Event Definition for Lead PlatformEvent
Create a Platform Event with Label as LeadPlatformEvent, Object Name as Lead and Custom Fields & RelationShips as per below table. As mentioned above, these Custom fields can also be created via Apex script.
| Field Label | API Name | Data Type |
|---|---|---|
| City | City__c | Text(80) |
| ConvertedAccountId | ConvertedAccountId__c | Text(36) |
| ConvertedDate | ConvertedDate__c | Date |
| Country | Country__c | Text(80) |
| CreatedDate | CreatedDate__c | Date/Time |
| Description | Description__c | Text(255) |
| Email__c | Text(80) | |
| FirstName | FirstName__c | Text(80) |
| Id | Id__c | Text(36) |
| IsConverted | IsConverted__c | Checkbox |
| IsDeleted | IsDeleted__c | Checkbox |
| LastModifiedDate | LastModifiedDate__c | Date/Time |
| LastName | LastName__c | Text(80) |
| LeadSource | LeadSource__c | Text(255) |
| Name | Name__c | Text(80) |
| Phone | Phone__c | Text(80) |
| PostalCode | PostalCode__c | Text(10) |
| Salutation | Salutation__c | Text(80) |
| State | State__c | Text(80) |
| Status | Status__c | Text(80) |
| Street | Street__c | Text(255) |
Create Custom Fields via Apex script
An Apex class called CustomFieldUtility can be used to create custom fields programmatically. The source for this class can be found in the Common Resources project. Download this project and follow the steps below.
- Click on Salesforce Setup icon and select
Developer Consoleto open a new console window - Go to
File -> New -> Apex classand create a new class namedCustomFieldUtility - Copy the code from
accelerator-common-resources/salesforce/CustomFieldUtility.apxcto the script editor - Select the
File -> Savemenu option to compile and save the class - Select
Debug -> Open Execute Anonymous Window - Copy and paste the contents of
accelerator-common-resources/salesforce/CreatePlatformEventsCustomFields.txtinto the window. - Enable the
Open Logoption and click the Execute button.
Once the script completes, select the Debug Only filter option to show just the results of each create request. Verify that all fields have been successfully created.
Note: Do not execute all the content in the CreatePlatformEventsCustomFields.txt file at once as the console might throw a timeout error. Instead execute it in batches.
Salesforce Apex Triggers
This implementation requires creation of Apex Triggers for the Platform Events to be generated on changes to records in Salesforce.
| Salesforce Object | Apex script location | Trigger name |
|---|---|---|
| Account | /src/test/resources/scripts/accounts-event-publisher.apxt | AccountEventsPub |
| Account | /src/test/resources/scripts/account-addresses-event-publisher.apxt | AccountAddressEventsPub |
| Account | /src/test/resources/scripts/households-event-publisher.apxt | HouseholdEventsPub |
| Contact | /src/test/resources/scripts/contacts-event-publisher.apxt | ContactEventsPub |
| Opportunity | /src/test/resources/scripts/opportunities-event-publisher.apxt | OpportunityEventsPub |
| Lead | /src/test/resources/scripts/leads-event-publisher.apxt | LeadEventsPub |
Follow the below steps to create the Apex Triggers
- Login to Salesforce.
- Click Setup to search for Object Manager in Quick Find Box.
- Search for the Salesforce Object. A page appears with Details of the Object.
- Click Triggers unders the Details section to see list of available triggers on the Object. Click New.
- Copy the Script from the location specified in the above table .
- Obtain the
LastModifiedByIdandRecordTypeId(if it exists) by running the queries mentioned in the trigger from Developer Console. - Replace the values in the script
- Click Save and ensure isActive checkbox is ticked.
- Repeat the steps for all the Salesforce objects in the above table
Deployment
Each Accelerator implementation template in Exchange includes Bash and Windows scripts for building and deploying the APIs to CloudHub. These scripts depend on repositories, global settings, deployment profiles, and associated properties configured in the Maven settings.xml file.
For additional details, please refer to the Application Deployment section of the Getting Started Guide.
Preparation
Ensure the Maven profile CloudHub-FINS-DEV has been properly configured in your settings.xml file. In particular, make sure the common properties for your environment have been provided (e.g., Anypoint Platform client ID and secret).
Required property overrides
At a minimum, the following properties must be customized to reflect the target deployment environment.
| Property Name | Description |
|---|---|
| anypoint-mq.client-id | Anypoint MQ Client Id |
| anypoint-mq.client-secret | Anypoint MQ Client Id |
| sfdc.username | Salesforce Instance client user Name |
| sfdc.token | Salesforce Instance client token |
| sfdc.password | Salesforce Instance client password |
| sfdc.client-id | The Consumer Id of the Connected App in Salesforce |
| sfdc.client-secret | The Consumer secret of the Connected App in Salesforce |
| sfdc.update-source | Name of the Source Salesforce Instance from where the Events are triggered |
Implementation notes
- All the triggers filter records based on
LastModifiedBy <> Service Account User IDto avoid cyclical updates. - The Mule idempotent message validator is used to ensure that only unique messages are published to Anypoint MQ. The Salesforce ID with an expiration interval and time-to-live (ttl) of 30 seconds (configurable) is used as the unique ID to filter out duplicate Mule messages.
- The current implementation does not support replay of Platform Events that were missed when the Mule application is down.
Additional resources
- The Data mappings tab describes how the request and response data structures are mapped between the API interfaces.
- Refer to the Accelerators documentation home for more information about the MuleSoft Accelerators.