Accelerator SalesOrders Process API
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 Sales Order Sync Process API specification to orchestrate the Sales Order updates from Point Of Sale (POS) system to SAP S/4HANA, Oracle EBS, Loyalty Management Cloud, and Data Cloud systems.
This API uses the Accelerator Global Sales Order System API to maintain a global representation of a sales order, which can provide a 360 degree view of the order by storing identifiers representing the order in various systems. A unique global ID is generated for each order 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 Order 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 Order entity from Anypoint MQ to Global Data System and other target systems. Processing an update from an API request follows a similar process.
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 Sales Order System is Salesforce.
** Updates can be sent to multiple target systems.
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
- Process configuration properties
- Accelerator Global Sales Order System API
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-order-update-retail-queue
- accel-order-update-retail-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/rcg-config folder contains the configuration settings required to deploy the application for use cases described by the MuleSoft Accelerator for Retail.
Variations of these files have been provided for few 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 name | Example | Action |
|---|---|---|
| systems-configured-property-names | salesforce-lm-sys,saphana-sys | This 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.enabled | true | This 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-resources | defaults provided in config | Default 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 |
API dependencies
The following table lists the endpoint dependencies that are enabled by default in this API.
| API name | Endpoint | Action |
|---|---|---|
| Accelerator Global Sales Order System API | get:/orders | Search sales orders |
| Accelerator Global Sales Order System API | put:/orders | Create or update a sales order |
| Accelerator Global Sales Order System API | put:/orders/{orderId}/externalIds | Update external IDs for a sales order |
| Accelerator Global Sales Order System API | get:/orders/{orderId}/externalIds | Retrieve external IDs for a sales order |
| Accelerator Global Sales Order System API | get:/orders/{orderId} | Retrieve an existing sales order |
| Accelerator Global Sales Order System API | put:/orders/{orderId}/productItems | Create order line items for a sales order |
| Accelerator Global Sales Order System API | get:/orders/{orderId}/productItems | Retrieve order line items for a sales order |
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 Name | Description |
|---|---|
| api.autodiscoveryID | Required if using API Manager to secure this API |
| anypoint-mq.server-url | Anypoint MQ URL where the message Exchange, Topics, queues have been created |
| anypoint-mq.slsorder-queue-name | Anypoint MQ queue name for receiving Sales Order events |
| anypoint-mq.slsorder-dl-queue-name | Anypoint MQ dead letter queue name for Sales Order events |
| anypoint-mq.client-id | Anypoint MQ Client Id to access messages from MQ |
| anypoint-mq.client-secret | Anypoint MQ Client Secret to access messages from MQ |
| global-slsorder-sys.host | Accelerator Global Sales Order System API Hostname |
| global-party-sys.host | Accelerator Global Party System API Hostname |
| global-product-sys.host | Accelerator Global Product System API Hostname |
| global.cloudhub.appPrefix | The App Prefix that is used to determine the config files needed for the accelerator |
| systems-common-params.http-client-id | Client Id to access other system APIs |
| systems-common-params.http-client-secret | Client Secret to other system APIs |
Implementation notes
- It is assumed that all the system APIs configured for sync process will accept CIM objects.
- All the default configurations needed for sync to target systems are read from configuration yaml files in the config folder. The
systems-common-paramsproperty 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. - The property
global.cloudhub.appPrefixproperty 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 asaccel-and the configuration yaml files under theaccel-configare 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. - The property
systems-configured-property-namesholds 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 undersystems-common-paramsproperty. - The sync to a specific target system can be enabled/disabled using the property
enabledunder the System API's Configuration in the properties file. For example, settingsaphana-sys.enabledto true enables the sync to SAP_4HANA System API. - The property
sync-enabled-objectscan 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. - The Sales Order events processing can be enabled/disabled by using the property
listener-stateunder the slsorder-sync-prc-api configuration in the properties file. The allowed values arestartedandstopped. By default, Sales Order events processing is enabled. - The property name
source-identifierholds 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
- 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.