MuleSoft Accelerator for Salesforce Clouds · solution includes production-ready APIs, connectors,...
Transcript of MuleSoft Accelerator for Salesforce Clouds · solution includes production-ready APIs, connectors,...
MuleSoft Accelerator for Salesforce Clouds V1.1 reference architecture
Introduction 4
Functional view of Accelerator use cases 4
Approach and methodology 5
Common Components 6 Common services 6
API template 6 Notification Service 7 Scheduling Service 8
Accelerator for Service Cloud 10 API-led view 11
Use case 1: Order history (Service Cloud ← OMS) 12 Use case summary 12 Sequence diagram 12
Service Cloud components & configurations: 13 OMS components & configurations 13
Data elements 13 Components view 14
Use case 2: Create issues/incidents [Service Cloud → SNOW (a) & Jira (b)] 15 Use case summary 15 Sequence diagram 15
ServiceNow components & configurations 16 Service Cloud Components & configurations 16
Data elements & mapping 17 Components view 18
Use Case 3: Updates to issues/incidents [Service Cloud ← SNOW (a) & Jira (b)] 19 Use case summary 19 Sequence diagram 20
Service Cloud Components & Configurations 20 Data elements & mapping 21 Components view 21
Accelerator for Commerce Cloud 23
API-led view 23
Use case 1: Products (Commerce Cloud ← PIM) 24 Use case summary 24 Sequence diagram 24
Commerce Cloud Component & Configurations 25 PIM Components & Configurations 25
Data elements 25 Components view (Proposed Approach) 27
Use case 2: Inventory (Commerce Cloud ← SAP) 28 Use case summary 28 Sequence diagram 28
Commerce Cloud Component & Configurations 29 SAP Components & Configurations 29
Data elements 29 Components view 30
Introduction MuleSoft Accelerators for Salesforce Clouds enable organizations to implement critical integration use cases for Service Cloud and B2C Commerce Cloud, faster and easier than ever before. The solution includes production-ready APIs, connectors, and integration templates that help unlock critical data from external systems such as SAP, ServiceNow, and Jira, all the while guiding you to adopt best practices synthesized from thousands of customer implementations. These assets can be used as is or extended to meet your company’s unique needs. This reference documentation should be used in conjunction with the set-up guide in the solution landing page. Using Accelerators Consumers of Accelerators should be aware of the interdependency among the APIs as noted in the use cases. Users are encouraged to customize Accelerators as needed, and should be aware that changes made to one template will likely affect other dependent templates.
Functional view of Accelerator use cases
Approach and methodology All artifacts are built with extensibility and customization in mind. For example, if our Accelerator provides guidance on how to get inventory data out of SAP, but the customer is using another ERP, the Accelerator will provide guidance for how the customer can modify or extend the API and the corresponding template to apply for their ERP. To help with this, we will provide a reference architecture and documentation. All assets are tested and high-quality. While we know most customers will not use all assets as is, all assets will be hardened and high quality. Accelerators provide best practice POVs for MuleSoft and Salesforce. Taking an API-led approach, following API design best practices, and adding common services are all MuleSoft best practices which we will adhere to. In addition, we will provide a POV on how to show this data within Salesforce, following Salesforce best practices.
Common Components Common components will be implemented as “Common Services”. The following is a list of the non-functional requirements to be implemented as common best practices in this solution.
● Unified scheduling: The solution must be able to view and manage all the schedules of the system from one location.
● Notifications: The solution must be able to send notifications to an individual or to a mailing list. The types of notifications can be SMS, push notifications, or email.
● Error handling: The solution must be able to react with different rules upon an error (eg. discern different types of errors and be able to communicate with the appropriate teams for troubleshooting).
Common services Common services are components that support the non-functional requirements of any project.
API template API template helps to jump-start API implementation development as it pre-implements some of the commonly needed features. It also helps to bring consistency in the implementation work since developers may have different ways of developing APIs. Below are the features/capabilities that the template provides:
● Standardized naming convention ● Configuration elements in one common global file ● Pre-built properties configurations yaml files ● Secure properties config for passwords encryption ● Externalized error handler into common project and imported into template ● Pre-built Notification API connectivity from error handler to send error notifications ● Externalized transformations using DWL files ● Support for parent POM to inherit common dependencies, properties etc. into child POM
Notification Service The solution provides a Notification API that will consume notification events and send notifications to individuals or groups via SMS, email, push notifications, etc.
High-level workflow:
1. Any module in the solution calls Notification Service API providing: ○ NOTIFICATION_TYPE: [EMAIL, SMS, etc] ○ NOTIFICATION_ADDRESS ○ NOTIFICATION_MESSAGE
2. Service will route the notification based on the TYPE. 3. Service will send the notification.
Scheduling Service Scheduling Service will run schedules and perform API calls. The benefit of having a common scheduler service is to have all the integration-level schedules maintained in one place.
The scheduling service may be built in two different ways, depending on the target deployment platform. Anypoint Platform offers operational advantages in CloudHub when dealing with schedules.
High-level workflow:
1. A predefined schedule is triggered. Schedules have enriched information about the last execution such as SCHEDULE_TYPE and WATERMARK.
2. Scheduling service invokes the job attached to the schedule and updates the schedule status to “TRIGGERED” and updates the timestamp. Trigger ID and CALLBACK URL are generated.
3. Once the invoked process completes, it does a call-back to the scheduling status service through the callback URLs to report the execution status.
Accelerator for Service Cloud Service reps impact every moment of the customer journey from pre- to post-purchase. This has also changed the expectations customers have for them, as 78% of customers expect service reps to have the same information about them and help them answer complex questions beyond simple issue-resolution. However, with siloed systems holding different pieces of customer data, this can be a challenge. Agents need to toggle between different monitors that have up to 50 different applications loaded just to support a single customer. Restricted agent access to certain systems compounds the situation. The result is that the agent can’t provide the necessary support, hindering their productivity and the customer does not receive the personalized, streamlined experience they expect. The goal of MuleSoft Accelerator for Service is to provide service agents with direct access to critical data they need to service the customer, all within the Service Console. We’ll also provide them with the ability to trigger actions in other relevant applications they may not have access to, but need to be connected with. Within Accelerators, we will provide assets and guidance to enable:
● Service Cloud and OMS integration [Use case 1] Without having to toggle to a separate application, service agents will be able to see real-time order history and order status information from an external order management system (OMS) within Service Cloud.
● Service Cloud and ServiceNow/Jira integration [Use case 2 & 3] While creating a Case within Service Cloud for a customer service agents will be able to route relevant issues within the case to ServiceNow, if it is an ITSM issue, and Jira, if it is a bug issue. Once the ServiceNow and Jira tickets are created, the agent will also be able to see any updates made to that ticket — whether new comments are added or the status changed — all within Service Cloud.
Use case 1: Order history (Service Cloud ← OMS)
Use case summary Show order history data from an external Order Management System (OMS) for the past 90 days within Service Cloud. The API should also allow searching for order history for a user-entered date-range. Order history workflow:
1. Service Cloud requests order history for a given customer/account number 2. Determine OMS to call, based on configuration. 3. Call OMS and transform order data to standard format. 4. Return order information to API Client. 5. In case of error, return proper error code to Service Cloud.
Sequence diagram
Systems involved:
● Service Cloud (SvC) ● OMS: Currently represented by an Order Database
Service Cloud components & configurations:
● Lightning Web Components (LWC) will be configured to show order history information. Below is how it appears in Service Cloud
(Screenshot of the Lightning Web Component)
OMS components & configurations
● DB Table with Customer order information covering data elements defined in the section below
Data elements
Element Name
Data Type Description
Filed Date Date Date the order was filed
Promise Date Date Date the order will be fulfilled
Order End Date
Date Date at which the order ends. For subscription-type orders, this would be the date when the subscription ends.
Order Start Date
Date Date on which the order becomes effective. For subscription-type orders, this is the date the subscription begins.
Sales Order Status
Text - Reference - Id (lookup)
Current order status e.g. Draft, Ready for Review, Placed, Ready for Activation, Activated
Original Order
Text - Reference - Id (lookup)
Reference to the parent order. Needed for reship, exchange and even-swap orders
Sales Order Type
Text - Reference - Id (lookup)
The type of order: Change, Renewal or Amendment.
Description Text
Name Text
Order Number
Text Unique number assigned to the order and displayed to end users.
Sales Order Id
Text - Primary Key Primary key
Components view
Design Center/API Manager Components
Salesforce Experience API | RAML Definition RAML definition for Salesforce Service Cloud experience API
Customers Process API | RAML Definition RAML definition for customer process API
OMS System API | RAML Definition RAML definition for OMS system API
Runtime Manager/Studio API Implementation Projects
Salesforce Experience API | Implementation Template
API implementation for Salesforce Service Cloud experience API
Customers Process API | Implementation Template
API implementation for customer process API
OMS System API | Implementation Template API implementation for the OMS system API
Use case 2: Create issues/incidents [Service Cloud → SNOW (a) & Jira (b)]
Use case summary Create a new “issue” in Jira or “incident” in ServiceNow from a “case” in Service Cloud. Use case workflow:
1. When a case with ServiceNow or Jira synchronization checkbox selected is created in Service Cloud, it pushes an event to Salesforce PushTopic
2. Mule streams that event with caseId and pushes it into Anypoint MQ 3. Mule further consumes that message from Anypoint MQ and retrieves required case details
from Service Cloud 4. Mule transforms the case details from Service Cloud and creates an incident in ServiceNow
or issue in Jira
Sequence diagram
Systems Involved:
● Service Cloud, where cases are created ● Jira ● ServiceNow (SNOW)
ServiceNow components & configurations
● A custom field is created in ServiceNow to hold the Salesforce CaseId ● ServiceNow Connector is used to invoke insert operation on incident service
Jira components & configurations
● A custom field is created in Jira to hold the Salesforce CaseId ● Below API is used to create Issue in Jira
https://developer.atlassian.com/cloud/jira/platform/rest/v3/#api-rest-api-3-issue-post
Service Cloud Components & configurations
Configurations Click here for documentation on Salesforce push-topics. Use Workbench to create a push topic query.
1. Login to Workbench 2. Select Data > Insert 3. Choose PushTopic as the Object Name and Single Record. 4. Click Next 5. Populate all required fields
Field Value
API Version 46.0 (Replace with current API version is applicable)
Name All_Cases (May not contain spaces)
NotifyForOperationCreate true
NotifyForOperationDelete false
NotifyForOperationUndelete false
NotifyForOperationUpdate false
Query SELECT Id FROM Case where Sync_With_SNOW__c=true or Sync_With_JIRA__c=true
6. Click Insert
Data elements & mapping ServiceNow
SFDC Data Element Name
Data Type
Description ServiceNow Data Element Name
Id Text Case identifier in salesforce service cloud
u_sfdc_case_id
Subject Text Case subject e.g. “widget received is wrong size”, “router is not responding”
short_description
Description Text Detailed description of the case description
Type Text Case type e.g. ”Product Support”, “Account Support”, “General”
Status Text Case status e.g. “On Hold”, “New”, “Working”, “Escalated”
state
Priority Text Case priority e.g. “High”, “Medium”
priority
Priority cross-reference
Salesforce ServiceNow
High 1 (Critical)
Medium 2 (High)
Low 3 (Medium)
Jira
SFDC Data Element Name
Data Type
Description JIRA Data Element Name
Id Text Case identifier in salesforce service cloud
customfield_10027
Subject Text Case subject e.g. “widget received is wrong size”, “router
summary
is not responding”
Description Text Detailed description about the case
description
Type Text Case type e.g.”Product Support”, “Account Support”, “General”
“Bug”
Priority Text Case priority e.g. “High”, “Medium”
priority
Status cross reference
Salesforce ServiceNow
New 1 (New)
Working 2 (In Progress)
Escalated 3 (On Hold)
Closed 5 (Resolved)
Components view
Design Center/API Manager Components
ServiceNow System API | RAML Definition
RAML definition for ServiceNow system API
Case Process API | RAML Definition
RAML definition for case process API
Salesforce System API | RAML Definition
RAML definition for Salesforce system API
Jira System API | RAML Definition RAML definition for Jira system API
Runtime Manager/Studio API Implementation Projects
ServiceNow System API | Implementation Template
API implementation for ServiceNow system API
Case AMQ Listener | Implementation Template
API implementation for case Anypoint MQ listener
Case Process API | Implementation Template
API implementation for case process API
Salesforce System API | Implementation Template
API implementation for the salesforce system API
Salesforce Topic Listener | Implementation Template
API implementation for the Salesforce topic listener
Jira System API l Implementation Template
API implementation for the Jira system API
Use Case 3: Updates to issues/incidents [Service Cloud ← SNOW (a) & Jira (b)]
Use case summary Any updates that occur to an “incident” in SNOW or an “issue” in JIRA (eg. comments or changes to the status field) will be synchronized with the corresponding Service Cloud “case”. Use case workflow:
1. Trigger an event from SNOW/JIRA when there is an update to the incident/issue 2. Mule consumes the event and pulls the update record from SNOW/JIRA 3. Mule calls the SvC System API to synchronize the updates on the Service Cloud case.
Sequence diagram
Systems Involved:
● Jira: source of product-related tickets ● ServiceNow: source of internal-related tickets ● Service Cloud
Service Cloud Components & Configurations Create custom fields on the Case object to represent field values from external systems.
SFDC Field Name SFDC Field Label Data Type Description
External_Comments__c
External Comments
Long Textarea(131,072)
Comments added on the incident/ticket in SNOW/JIRA
External_Status__c External Status Text(20) Status of the incident/ticket in SNOW/JIRA
External_System_Last_Updated__c
External System Last Updated
Date Date last updated in SNOW/JIRA
External_Owner__c External Owner Text(50) Incident/ticket owner in SNOW/JIRA
External_Priority__c External Priority Text(50) Incident/ticket priority in SNOW/JIRA
Data elements & mapping
SFDC Field Name SNOW Data Elements(UI field) Jira Data Elements(UI field)
External_Comments__c
comments (Comments) comments (Comments)
External_Status__c state(State) status(status)
External_System_Last_Updated__c
Generated in SNOW statuscategorychangedate(NA)
External_Owner__c opened_by(Opened by) creator(NA)
External_Priority__c priority(Priority) priority(Priority)
Components view
Design Center/API Manager Components
ServiceNow Experience API | RAML Definition
RAML definition for ServiceNow experience API
Case Process API | RAML Definition
RAML definition for case process API
Salesforce System API | RAML Definition
RAML definition for Salesforce system API
Jira System API | RAML Definition
RAML definition for Jira system API
Jira Experience API | RAML Definition
RAML definition for Jira experience API
Runtime Manager/Studio API Implementation Projects
ServiceNow Experience API | Implementation Template
API implementation for servicenow system API
Case AMQ Listener | Implementation Template
API implementation for case Anypoint MQ listener
Case Process API | Implementation Template
API implementation for case process API
Salesforce System API | Implementation Template
API implementation for the Salesforce system API
Jira System API l Implementation Template
API implementation for the Jira system API
Jira Experience API | Implementation Template
API implementation for the Jira experience API
Accelerator for Commerce Cloud Modern consumers expect shopping experiences to be relevant, personalized, and seamless across channels. Gone are the days of bulk uploading and updating data on a weekly basis. For retailers, this means customer, product, and inventory data needs to be connected in real-time across all systems and channels. To help manage this, we are providing best practice assets and approaches for two main use cases:
● B2C Commerce Cloud and PIM integration [Use case 1]: Ability to search for product deltas in a product information management (PIM) system and reflect those changes in Commerce Cloud on a scheduled basis, set as appropriate for your company.
● B2C Commerce Cloud and SAP (ERP) integration [Use case 2]: Ability to search for inventory availability data in SAP, as an example ERP, from Commerce Cloud on a scheduled basis, set as appropriate for your company.
API-led view
Use case 1: Products (Commerce Cloud ← PIM)
Use case summary On a (configurable) scheduled basis, build the product list from the PIM database and push changes in product data since the previous load into Commerce Cloud. Assumptions:
● The initial load of products into Commerce Cloud has already occurred. ● All new products from the delta load will be associated with the Standard Catalog. ● Delta is loaded into the Commerce Cloud (CC) staging environment with the assumption
that additional attributes and categorization will need to take place before it is published to the production environment. The promotion of products from CC staging into CC production should be handled within CC, and is not handled by this Accelerator.
Note:
● Accelerator supports the standard product type within CC (standalone products). Use case workflow:
1. At a configured schedule, Common Scheduler calls PIM DB Poller Mule API, which in turn queries PIM for new or updated products.
2. All the product create/update events are pushed into Anypoint MQ. 3. Anypoint MQ listener consumes events and calls the Product process API. 4. Product process API queries PIM system API for product data and then calls the CC system
API to upsert the product details into CC.
Sequence diagram
Systems involved:
● PIM System: contains all required information about products (product codes, pricing, images, etc.). This system is simulated with an Oracle database.
● Commerce Cloud: Mule publishes product information into the staging environment.
Commerce Cloud Component & Configurations
● Create a catalog in Commerce Cloud where the products from PIM will be inserted. ● Below Commerce Cloud OCAPI is used to insert products:
https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FOCAPI%2Fcurrent%2Fdata%2FResources%2FProducts.html&cp=0_12_4_34
PIM Components & Configurations
Database table with product information
Data elements Product Data Elements
Element Name Data Type Description
brand String The brand of the product.
creation_date Date Returns the value of attribute 'creationDate'.
id String The ID (SKU) of the product.
image_path String The path to the image file
min_order_quantity String Minimum order quantity of the product
in_store_pickup Char Whether in store pickup available or not
in_stock Boolean The flag that indicates if the product is in
stock, or not. This is a calculated value.
last_modified Date Returns the value of attribute 'lastModified'.
long_description Localized<MarkupText> The localized long description of the product.
manufacturer_name String The name of the product's manufacturer.
manufacturer_sku String The SKU of the product's manufacturer.
master_product_id String The master of the product. This is applicable for product types "variation_group" and "variant" only.
name Localized<String> The localized name of the product.
online Boolean The flag that indicates if the product is online, or not. This is a calculated value.
online_flag SiteSpecific<Boolean> The site specific online status of the product.
owning_catalog_id String The ID of the catalog that owns the product.
tax_class_id String Tax class Id of the product
price Decimal The price of the product.
price_currency String Currency for the product's price.
primary_category_id String The id of the products primary category.
searchable SiteSpecific<Boolean> The site specific searchable status of the product.
short_description String The localized short description of the product.
type String The type of the product. It can be “master”, “product” or “variant”
unit String The sales unit of the product.
upc String The Universal Product Code of the product.
Components view (Proposed Approach)
Design Center/API Manager Components
Commerce Cloud System API | RAML Definition
RAML definition for Commerce Cloud system API
PIM System API | RAML Definition RAML definition for PIM system API
Products Process API | RAML Definition
RAML definition for products process API
PIM DB Poller Process API | RAML Definition
RAML definition for PIM DB poller process API
Runtime Manager/Studio API Implementation Projects
Commerce Cloud System API | Implementation Template
API implementation for Commerce Cloud system API
PIM System API | Implementation Template
API implementation for PIM system API
Products Process API | Implementation Template
API implementation for products process API
PIM DB Poller Process API | Implementation Template
API implementation for PIM DB poller process API
PIM Product AMQ Listener | Implementation Template
API implementation for the products Anypoint MQ listener
Use case 2: Inventory (Commerce Cloud ← SAP)
Use case summary On a scheduled basis (which is configurable), build the inventory list and push into Commerce Cloud. Use Case workflow:
1. A configurable scheduled event gets triggered in scheduling service which calls inventory process API. (See scheduling service).
2. Inventory process API queries inventory list created or updated since the last run from SAP via the SAP system API
3. For each of the returned inventory items, upsert into the production environment of Commerce Cloud.
Sequence diagram
The following systems will be accessed:
● ERP System: Contains information about inventory and specific plant locations. SAP is accessed via the ERP system API.
● Commerce Cloud: Mule publishes inventory information into Commerce Cloud in the store inventory list.
Commerce Cloud Component & Configurations
● Create the appropriate inventory list in Commerce Cloud where the inventory information should be sent.
● Batch: https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FOCAPI%2Fcurrent%2Fusage%2FBatchRequests.html&cp=0_12_2_1
● InventoryLists resource: https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FOCAPI%2Fcurrent%2Fdata%2FResources%2FInventoryLists.html&cp=0_12_4_24
SAP Components & Configurations
BAPI exposing the inventory information
Data elements
Element Name Data Type Description
allocation Decimal The allocation quantity and reset date.
ats Decimal The quantity of items available to sell (ATS). This is calculated as the allocation plus the preorderBackorderAllocation minus the turnover.
creation_date Date Returns the value of attribute 'creationDate'.
inventory_list_id
String The user supplied ID of the inventory list.
product_id String The user supplied ID of the product.
product_name String The name of the product.
stock_level Decimal The current stock level. This is calculated as the allocation minus the turnover.
Components view
Design Center/API Manager Components
Commerce Cloud System API | RAML Definition
RAML definition for Commerce Cloud system API
Inventory Process API | RAML Definition
RAML definition for inventory process API
SAP System API | RAML Definition
RAML definition for SAP system API
Runtime Manager/Studio API Implementation Projects
Commerce Cloud System API | Implementation Template
API implementation for Commerce Cloud system API
Inventory Process API | Implementation Template
API implementation for inventory process API
SAP System API | Implementation Template
API implementation for SAP system API
Common Scheduler l Implementation Template
API implementation for common scheduler