Accelerator SalesOrders Process API

(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 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.

rcg-pos-integration-activity-diagram.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 Sales Order System is Salesforce.

** 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:

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-order-update-retail-queue
  2. 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 nameExampleAction
systems-configured-property-namessalesforce-lm-sys,saphana-sysThis 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.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-resourcesdefaults 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

API dependencies

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

API nameEndpointAction
Accelerator Global Sales Order System APIget:/ordersSearch sales orders
Accelerator Global Sales Order System APIput:/ordersCreate or update a sales order
Accelerator Global Sales Order System APIput:/orders/{orderId}/externalIdsUpdate external IDs for a sales order
Accelerator Global Sales Order System APIget:/orders/{orderId}/externalIdsRetrieve external IDs for a sales order
Accelerator Global Sales Order System APIget:/orders/{orderId}Retrieve an existing sales order
Accelerator Global Sales Order System APIput:/orders/{orderId}/productItemsCreate order line items for a sales order
Accelerator Global Sales Order System APIget:/orders/{orderId}/productItemsRetrieve 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 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.slsorder-queue-nameAnypoint MQ queue name for receiving Sales Order events
anypoint-mq.slsorder-dl-queue-nameAnypoint MQ dead letter queue name for Sales Order 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-slsorder-sys.hostAccelerator Global Sales Order System API Hostname
global-party-sys.hostAccelerator Global Party System API Hostname
global-product-sys.hostAccelerator Global Product 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 saphana-sys.enabled to true enables the sync to SAP_4HANA 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 Sales Order events processing can be enabled/disabled by using the property listener-state under the slsorder-sync-prc-api configuration in the properties file. The allowed values are started and stopped. By default, Sales Order events processing is enabled.
  8. 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 Solutions
Published onMar 8, 2024
Asset overview

Asset versions for 1.0.x

Asset versions
VersionActions
1.0.2
1.0.1
1.0.0