MuleSoft Accelerator for Retail icon

MuleSoft Accelerator for Retail

(0 reviews)

Appendix

Overview

CIM usage guidelines

The physical representations of the Cloud Information Model (e.g,. RAML, DDL) implement a highly-normalized view of objects and relationships, where enumerated values are defined as separate entities. In our solution, these relationships will be simplified to reduce complexity and overall development effort. This section clarifies our use of the model in more detail.

Audience

The primary audience for this document primarily includes architects, consultants, developers, and testers engaged in architecting, designing, developing, and testing API-based solutions.

Glossary

The following table defines general terms and acronyms referenced in this document:

TermDefinition
MDMA Master Data Management solution provides an accurate, consistent, and complete copy of master data for use by enterprise applications and business partners. Most solutions include data quality tools and workflow processes for managing conflicting updates.
CIMThe Cloud Information Model defines a set of standard data structures that can be used as canonical representations of common entities for integrating systems.

Interpretation of identifiers

For the MuleSoft Accelerator for Retail, the MDM System API is responsible for generating and maintaining universal identifiers for all entities. Also known as "master", or "global"identifiers, these values represent the unique ID for any given instance of an entity. They are therefore assigned to the id property of any given CIM object (e.g., Customer.id) in all Experience and Process APIs. All other system identifiers are treated as external, and thus may be found in the externalIds property (where supported).

For System APIs, however, the id property of any given CIM object will be set to the identifier understood by that system on all request/response messages. If supported, the universal identifier will be found in the externalIds property with an external ID type of "MDM". The intent behind this approach is to keep the interpretation of the identifiers for a target system as being from the perspective of that system, rather than from MDM.

The following table provides some examples involving a sales order, published from B2C Commerce, to help clarify ID usage:

APIMessageCIM ID TypeExternal ID Type
B2C Commerce Experience APIOrder UpdateMDMSALESFORCE_B2C
Orders Process APIMDM Order RetrieveMDMSALESFORCE_B2C
Orders Process APIERP Order CreateMDMSALESFORCE_B2C
ERP Orders Process APISAP ECC Order CreateSAP_ECCMDM
ERP Orders Process APISAP S/4HANA Order CreateSAP_HANAMDM
SAP S/4HANA Orders System APIOrder RetrieveSAP_HANAMDM
OMS System APIOrder RetrieveOFBIZMDM

Enumerations

In CIM, some enumerations are defined as plain strings while others are defined as complex types (e.g., to normalize the structure). For our purposes, all properties that represent enumerations can be treated as strings instead of complex types thanks to the addition of a string union to the definition. Where string/type unions are defined as being arrays, it is expected that the contents of the array will be a single string identifying the enumerated value.

Enumeration types

For our purposes we support two distinct types of enumerations: those used as discriminators for polymorphism and those that represent coded values. For example, the partyType property is used as the discriminator for Party, and thus will contain an actual type name (e.g., Individual). Something like a status field, on the other hand, represents a static value and thus would have a predefined list of upper-case codes (e.g,. ACTIVE). This distinction helps to quickly identify coded values vs. discriminator types in messages.

Enumeration example

In the following example, contactPointType is an enumeration, which identifies the type of ContactPoint the snippet represents:

{
    contactPoints: [{
        "id": "bbafefc5-8cb4-11eb-b4c8-0233bdd64096",
        "contactPointType": [ "ContactPointEmail" ],
        "emailAddress": "traisley@flcx.com"
    }]
}

When creating sample messages it can help clarify that a property represents an enumeration by putting the entire definition on a single line, as shown above.

Predefined enumeration list

The following table lists all fields, which represent enumerated values relevant to the Customer Profile Sync solution, along with the values allowed:

Type Property Allowable values
ExternalId externalIdType FIS
JIRA
OFBIZ
MDM
SAP_ECC
SAP_4HANA
SALESFORCE_B2C
SALESFORCE_CORE
SALESFORCE_FSC
SALESFORCE_MARKETING
SERVICENOW
status VALID
INVALID
ContactPoint contactPointType ContactPointAddress
ContactPointEmail
ContactPointPhone
Customer customerStatus ACTIVE
INACTIVE
Party partyType Individual
Organization
PartyRelatedParty partyRelationshipTye AGENT
BUYER
CHILD
CLIENT
OTHER
RELATION
SPONSOR
SPOUSE
SUPPLIER
USER
VENDOR
PartyRole partyRoleType Customer
Employee
Product type MASTER
VARIANT
SalesOrder salesOrderType ADD_ON
CANCELLATION
INITIAL
JOURNAL
RENEWAL
RETURN
SUBSCRIPTION
UPGRADE
salesOrderStatus CANCELLED
CREATED
CONFIRMED
DELIVERED
IN_CART
IN_TRANSIT
INVOICED,LOST
PARTIALLY_SHIPPED
PICKUP_AVAILABLE
PROCESSING
REJECTED
RETURNED
SalesOrderProduct salesOrderProductStatus ACTIVE
DISCONTINUED
INACTIVE
NOT_SELLING
OUT_OF_STOCK

Composition

In the version of the CIM RAML libraries created for use by Accelerator assets, objects have been structured to support a great deal of flexibility when it comes to composition. Put simply, applications have the ability to represent entities either as flat structures, where references to other entities are provided as strings, or as tree structures, where child or referenced entities are embedded as part of other objects.

Composition example

For example, a flat representation of a Customer instance might look like this, where only a key reference to the associated party is provided:

{
    "id": "5550ae29-8caf-11eb-b4c8-0233bdd64096",
    "customerNumber": "00002496",
    "customerStatus": "ACTIVE",
    "party": [
        "54d59448-8caf-11eb-b4c8-0233bdd64096"
    ],
    "partyRoleType": "Customer"
}

However, the same definition of the model also supports a more complete representation of a Customer, such as the following:

{
    "id": "ed3a2956-8b0d-11eb-b4c8-0233bdd64096",
    "partyRoleType": "Customer",
    "party": [{
        "partyType": "Individual",
        "externalIds": [{
            "id": "0371853b-88bf-11eb-b4c8-0233bdd64096",
            "externalId": "INDVBCZXWC21121",
            "externalIdType": [ "SalesforceCore" ]
        }],
        "firstName": "Scott",
        "lastName": "Jenks",
        "personName": "Scott Jenks",
        "contactPoints": [{
            "id": "1ea2d3bd-8cb0-11eb-b4c8-0233bdd64096",
            "activeFromDate": "2015-03-15",
            "contactPointType": [ "ContactPointPhone" ],
            "formattedNationalPhoneNumber": "551-488-6996",
            "telephoneNumber": "551-488-6996"
        },{
            "id": "1defef22-8cb0-11eb-b4c8-0233bdd64096",
            "activeFromDate": "2015-03-15",
            "contactPointType": [ "ContactPointEmail" ],
            "emailAddress": "Jenks.Scott@example.net"
        }]
    }],
    "customerNumber": "1234446",
    "customerStatus": "Screened"
}

Individual applications may therefore choose to support arbitrary levels of composition in API requests and responses while still remaining valid against the model definition.

Representation of numbers

In CIM, all numeric properties are defined as integers. This means that, to accurately capture decimal amounts (e.g., dollars and cents), values need to be multiplied and divided by the desired precision factor when assigning or reading numeric values, respectively. For example, the dollar amount of a sales order would need to be multiplied by 100 when assigning it to a CIM structure, as follows:

    grandTotalAmount: round(payload.orderTotalGross * 100)

The amount is rounded to more accurately reflect the precision in the event there are more than 2 decimals. Conversely, when this value is read from the CIM structure to be written to a back-end system expecting dollar amounts, it would need to be divided by 100 like so:

    Order_Total: payload.grandTotalAmount / 100

Since we are converting the value back to 2-decimal precision in this case, rounding is not required.


Reviews

TypeCustom
OrganizationMulesoft Inc.
Published by
MuleSoft Solutions
Published onDec 3, 2021
Contact nameMuleSoft Solutions
Contact emailsolutions-questions@mulesoft.com
Asset overview

Asset versions for 2.3.x

Asset versions
VersionActions
2.3.0