--- schema_version: "1" id: 998a76094731cd90a168c369a65b5244a1fd85109c91f91cf6b275dc54703d7e title: CIM Usage Guidelines collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/accelerators-cim/latest/cim-usage-guide.md canonical_url: https://docs.mulesoft.com/accelerators-cim/latest/cim-usage-guide source_site: docs.mulesoft.com content_type: documentation content_hash: b8a2ccfa77f9b6521a7171f8d95b5a05e679245c7aaddff4abcf09d15815eb81 description: MuleSoft Documentation Site release: "2.0" latest: true --- --- product: Cloud Information Model version: 2.0 is-latest-version: true --- # CIM Usage Guidelines > For the full documentation index, see: https://docs.mulesoft.com/llms.txt This document provides some detailed information about how the Cloud Information Model (CIM) is typically used within MuleSoft Accelerators. The primary audience for this document includes architects, consultants, developers, and testers involved in the design, development, and testing of API-based solutions. ## Interpretation of Identifier Properties For all accelerator use cases involving the synchronization of entities between multiple systems (for example, customer profiles), the Global Data System APIs are responsible for generating and maintaining universal identifiers for all entities. Also known as "global" identifiers, these values represent a single, globally unique ID for any given instance of an entity. These values are typically assigned to the `id` property of any given CIM object (for example, `Customer.id`) in all Process APIs, where the representation of the object is expected to be the "golden copy" of it. All other system identifiers are treated as external, and thus may be found in the `externalIds` property where needed. 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 "GLOBAL" or "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 the Global Data repository. The same applies to most Experience APIs as well. The following table describes a series of API calls involving a customer profile update published from Salesforce, where the customer exists in the Global Data repository but does not yet exist in SAP, to help clarify identifier usage.
APIMessageObject ID TypeExternal ID Type

Salesforce Experience API

Customer Update

SALESFORCE_CORE

MDM

Customers Process API

Customer Upsert

MDM

SALESFORCE_CORE

Global Data Party System API

Customer Update

MDM

SALESFORCE_CORE

SAP ECC Customers System API

Customer Create

SAP_ECC

MDM

In this example, the Salesforce Experience API expects the value of the incoming `Customer.id` property to be of type `SALESFORCE_CORE`. For an existing customer, the request should also contain an external ID of type `MDM`, which is the global identifier for this profile. To call the Customers Process API, the `Customer.id` value must be set to the Global Party identifier while the original Salesforce identifier is mapped as an external ID. The Process API can use same value for updating Global Data, because the Global Party System API expects the global identifier as input. To create a new profile in SAP ECC, however, the Process API provides the Global Party identifier as an external ID because the SAP System API would expect an SAP identifier (since we are creating a new profile in this case, the `Customer.id` value would actually be set to null in the request). ## Enumerations In CIM, most enumerations are defined as plain strings instead of static enumerations or as complex types (for more normalized structures). We support two distinct types of enumerations: those used as discriminators for polymorphism, and those that represent a coded value from a static list. For discriminators, such as the `partyInstance` property of the `Party` type, the values for these will contain the actual type name (for example, `Individual`). As new child types extending a given base type added, the list of values for that discriminator property will grow. For properties, such as `partyStatus`, on the other hand, the list of values would generally be static and usually pre-defined. Since static value lists often differ from organization to organization (or even between applications), however, most have been defined as simple strings rather then actual enums. This approach also makes the model more flexible when the list may change over time, such as a property that represents an editable picklist in a Salesforce object. ### Enumeration Examples In the following example, `contactPointInstance` is the discriminator property that identifies which type of `ContactPoint` each item in the array of contact points represents, while `ussageType` is the enumeration of `Home`, `Work`, and `Other`. ```json { "contactPoints": [ { "id": "bbafefc5-8cb4-11eb-b4c8-0233bdd64096", "contactPointInstance": "ContactPointEmail", "emailAddress": "traisley@example.com", "usageType": "Home" }, { "id": "15d341df-06da-4fec-a640-29941a6e2bc3", "contactPointInstance": "ContactPointPhone", "telephoneNumber": "8885551234", "usageType": "Work" } ] } ``` ### Predefined Enumeration List The following table identifies all fields that have predefined enumerations used in various accelerator use cases, along with the current list of allowable values.
TypePropertyAllowable values

ExternalId

externalIdType

DOCUSIGN, EDI_SENDER_CODE, LOS, JIRA, OFBIZ, MDM, PIM, SALESFORCE_B2C, SALESFORCE_CORE, SALESFORCE_FSC_BANKING, SALESFORCE_FSC_INSURANCE, SALESFORCE_FSC_WEALTH, SALESFORCE_MARKETING, SALESFORCE_SALES, SALESFORCE_SERVICE, SAP_ECC, SAP_4HANA, SERVICENOW

status

VALID, INVALID

Customer

customerStatus

ACTIVE, INACTIVE

PartyRelatedParty

partyRelationshipType

AGENT, BUYER, CHILD, CLIENT, OTHER, RELATION, SPONSOR, SPOUSE, SUPPLIER, USER, VENDOR

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 first version of the CIM libraries created for use by Accelerator assets, objects were structured to support a great deal of flexibility when it comes to composition. Put simply, applications had 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. In the current version of CIM, the number of cases where this is supported has been significantly reduced. In fact, it is only supported - and in limited fashion - within the individual libraries of related types of an entity group. ### Composition Example For example, a flat representation of an Individual instance might look like this, where only key references to the associated contact points are provided: ```json { "partyInstance": "Individual", "personName": "Scott Jenks", "firstName": "Scott", "lastName": "Jenks", "contactPoints": ["1ea2d3bd-8cb0-11eb-b4c8-0233bdd64096", "1defef22-8cb0-11eb-b4c8-0233bdd64096"] } ``` The same definition of the model also supports a more complete representation of the Individual, however, by allowing complete ContactPoint objects to be provided: ```json { "partyInstance": "Individual", "personName": "Scott Jenks", "firstName": "Scott", "lastName": "Jenks", "contactPoints": [ { "id": "1ea2d3bd-8cb0-11eb-b4c8-0233bdd64096", "contactPointInstance": "ContactPointPhone", "telephoneNumber": "551-488-6996" "formattedNationalPhoneNumber": "(551)488-6996", "activeFromDate": "2015-03-15", }, { "id": "1defef22-8cb0-11eb-b4c8-0233bdd64096", "contactPointInstance": "ContactPointEmail", "emailAddress": "Jenks.Scott@example.com" "activeFromDate": "2015-03-15", } ] } ``` Individual applications may therefore choose to support arbitrary levels of composition in API requests and responses while still remaining valid against the model definition. This approach also allows object hierarchies to be constructed from a flat set of arrays. ## See Also - [CIM Subject Areas](https://docs.mulesoft.com/accelerators-cim/latest/cim-subject-areas) - [CIM Design Elements](https://docs.mulesoft.com/accelerators-cim/latest/cim-design-elements) - [CIM Overview](https://docs.mulesoft.com/accelerators-cim/latest/)