MuleSoft Accelerator for Retail

Overview

• CIM usage guidelines
• Interpretation of identifiers
• Enumerations
• Composition
• Representation of numbers

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:

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:

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.