MuleSoft Accelerator for Retail

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.

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.

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 a property represents an enumeration by putting the entire definition on a single line, as shown above.

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

Type	Property	Allowable values
ExternalId	externalIdType	MDM SAPECC SAP4HANA SalesforceB2C SalesforceCore SalesforceMarketing
	status	VALID INVALID
ContactPoint	contactPointType	ContactPointAddress ContactPointEmail ContactPointPhone
Customer	customerStatus	ACTIVE INACTIVE
Party	partyType	Individual
PartyRole	partyRoleType	Customer

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.

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.