Accelerator Customers Process API - Implementation Template

(0 reviews)

home

This API implementation template is a shared 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

This integration template implements the Accelerator Customers Process API specification to orchestrate the Customer, Individual, Organization, and Household creation and update to/from the Salesforce FSC Banking, Salesforce FSC Insurance, Salesforce FSC Wealth, Salesforce Core, Salesforce Marketing, LOS, SAP S/4HANA, and Core Banking systems.

This API uses the Accelerator Global Party System API to maintain a global representation of a customer, which can provide a 360 degree view of the customer by storing identifiers representing the customer in various systems. A unique global ID is generated for each customer to uniquely identify the profiles being synchronized across all target systems.

The Cloud Information Model (CIM) is leveraged to interact with each of the System APIs that have been developed for Customer sync use cases.

This integration template can be easily configured to sync to any other systems easily with inclusion of appropriate properties in the config files and do not require any changes to code. The default systems and configurations applicable for each accelerators are provided with the template.

Processing

The following diagram describes how this application processes an update to a Customer entity from Anypoint MQ to Global Data System and other target systems. Processing an update from an API request follows a similar process.

accel-activity-customer-process.png

It should be noted that this process is depicted as using "upserts" for persisting objects in target systems. While our System APIs have separate endpoints for the creation and update of objects, which allows for a wider range of use cases, support for upserts has been added to reduce the number of API calls required for this process.

* The Global Party System can be MariaDB or Salesforce. If the source system is the same as Global Data System then the Record Global ID call depicted in the diagram is not required, as this is taken care of by Global Data Management services.

** Updates can be sent to multiple target systems.

Getting started

bulb.png 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:

API dependencies

The following table lists the endpoint dependencies that are enabled by default in this API.

API nameEndpointAction
Accelerator Global Party System APIget:/customersSearch a customer party role
Accelerator Global Party System APIput:/customersCreate or update a customer party role
Accelerator Global Party System APIput:/parties/{partyId}/contactPointsUpdate contact points for a party
Accelerator Global Party System APIput:/parties/{partyId}/externalIdsUpdate external IDs for a party
Accelerator Global Party System APIput:/partyRoles/{partyRoleId}/externalIdsUpdate external IDs for a party role
Accelerator Global Party System APIget:/customers/{customerId}Retrieve an existing customer party role

Anypoint MQ destinations

In addition to the Anypoint MQ client application credentials, the following destinations must be created and made accessible to this API:

  1. accel-partyrole-update-queue
  2. accel-partyrole-update-dl-queue
  3. accel-party-update-queue
  4. accel-party-update-dl-queue

The Accelerator Common Resources asset contains a Postman collection, which can be used to create the destinations and client application required for use by accelerator applications.

Process configuration properties

The systems involved in the sync process can be configured based on organization needs and the accelerator use case that is being implemented. The dependent systems and configurations used is based on the config files corresponding to the global.cloudhub.appPrefix property, which is usually set in the global Maven settings.xml file. For example, the src/main/resources/config/fins-config folder contains the configuration settings required to deploy the application for use cases described by the MuleSoft Accelerator for Financial Services.

Variations of these files have been provided for each of the different accelerators that make use of this process. It is recommended that you make a copy of the desired configuration files under a different application prefix (e.g., myorg-config) and customize them as needed. Be sure to set the global.cloudhub.appPrefix property accordingly.

Below is a list of important configurations that are to be reviewed before deploying the application.

Property nameExampleAction
systems-configured-property-namessalesforce-fsc-insurance-sys,salesforce-fscThis property holds list of systems that are involved in sync process as a CSV. Each of the systems is identified by the root property configured for each system API.
systems-common-params.sync-enabled-objectsCustomer,Individual,HouseholdDefault list of objects (Names as per CIM) supported by the sync process to be provided as a CSV. The defaults can be can be overridden for each system API configurations involved in the sync process
systems-common-params.enabledtrueThis property is to enable the system in sync process. If false, this system is ignored in sync process. This property should be overridden for each system API configurations involved in sync process
systems-common-params.http-client-id"Client Id overridden at deploy time"Default Client Id to access the API. The defaults can be overridden for each system API configurations involved in the sync process
systems-common-params.http-client-secret"Client secret overridden at deploy time"Default Client Secret to access the API. The defaults can be overridden for each system API configurations involved in the sync process
systems-common-params.http-resourcesdefauls provided in configDefault list of resources with resource method, resource path to access the API. The defaults can be can be overridden for each system API configurations involved in the sync process

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. In particular, make sure the common properties for your environment have been provided in the CloudHub-DEV profile (e.g., Anypoint Platform client ID and secret).

For additional details, please refer to the Application Deployment section of the Getting Started Guide.

Required property overrides

Many templates can also be run from Anypoint Studio without having to customize the Run/Debug profiles. However, some templates make use of hidden deployment properties to protect sensitive information (e.g., passwords and secret keys). These properties must be supplied to the runtime by updating the configuration profile and adding them as VM arguments. At a minimum, the following properties must be customized to reflect the target deployment environment.

Property NameDescription
api.autodiscoveryIDRequired if using API Manager to secure this API
anypoint-mq.server-urlAnypoint MQ URL where the message Exchange, Topics, queues have been created
anypoint-mq.partyrole-queue-nameAnypoint MQ queue name for receiving Party Role events
anypoint-mq.partyrole-dl-queue-nameAnypoint MQ dead letter queue name for Party Role events
anypoint-mq.party-queue-nameAnypoint MQ queue name for receiving Party events
anypoint-mq.party-dl-queue-nameAnypoint MQ dead letter queue name for Party events
anypoint-mq.client-idAnypoint MQ Client Id to access messages from MQ
anypoint-mq.client-secretAnypoint MQ Client Secret to access messages from MQ
global-party-sys.hostAccelerator Global Party System API Hostname
global.cloudhub.appPrefixThe App Prefix that is used to determine the config files needed for the accelerator
systems-common-params.http-client-idClient Id to access other system APIs
systems-common-params.http-client-secretClient Secret to other system APIs

Implementation notes

  1. It is assumed that all the system APIs configured for sync process will accept CIM objects.
  2. All the default configurations needed for sync to target systems are read from configuration yaml files in the config folder. The systems-common-params property defines the default list of properties that are used by the sync process to invoke target System APIs and they can be overridden for each target system APIs.
  3. The property global.cloudhub.appPrefix property is used to determine the configurations specific to target System APIs involved in the sync process. The default value for global.cloudhub.appPrefix property is set as accel- and the configuration yaml files under the accel-config are used for identifying the target systems involved in the sync process and their corresponding configurations for each target system API. If a different value is provided, ensure the config files that hold details of system APIs are available under the appropriate folder that matches ${global.cloudhub.appPrefix}-config.
  4. The property systems-configured-property-names holds the comma separated values of property names of each target System API mentioned in the same configuration yaml file. This property is used to dynamically determine the number of systems involved in the sync process and read the configurations related to each of the target system API. If there are any specific properties mentioned specifically for the system API they are used as overriding values instead of values mentioned under systems-common-params property.
  5. The sync to a specific target system can be enabled/disabled using the property enabled under the System API's Configuration in the properties file. For example, setting core-banking-sys-api.enabled to true enables the sync to Core Banking System API.
  6. The property sync-enabled-objects can be configured for each target System APIs with Object types as a comma separated values string. The object types follow CIM Standards. For example if you do not wish to sync Individual to a specific target system exclude it from the comma separated values string.
  7. The Party Role and Party events processing can be enabled/disabled by using the property party-role-listener-state and party-listener-state under the customers-prc-api configuration in the properties file. The allowed values are started and stopped. By default, Party Role events processing is enabled.
  8. The current implementation does not support syncing of Organizations with other systems as they do not provide support to create/update Organizations without a Customer. When a GET of an organization is made, it's returned from Global Data if it exists.
  9. The current implementation does not automatically relate a Household to any other Party, but this can be accomplished using the put:/parties/{partyId}/relatedParties endpoint in the Accelerator Global Party Process API.
  10. It is expected that the payload sent to put:\customers includes a customerNumber property. If the property is not present, a sequence number (maintained in an object store) is used. The start value of the sequence is specified by the property start-sequence.customer-number, with a default value of 100000. If the object store is deleted, or if a different sequence number needs to be used, update the property accordingly before starting the application.
  11. The property name source-identifier holds the External Id Type value of each System involved in the sync process. This is a mandatory field to be provided for each system.

Additional resources


Reviews

TypeTemplate
OrganizationMulesoft
Published by
MuleSoft Organization
Published onDec 13, 2023
Asset overview

Asset versions for 3.1.x

Asset versions
VersionActions
3.1.5