CIM Usage Guidelines | MuleSoft Documentation
# CIM Usage Guidelines
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.
API | Message | Object ID Type | External ID Type  
---|---|---|---  
Salesforce Experience API | Customer Update | SALESFORCE_CORE  
Customers Process API | Customer Upsert | SALESFORCE_CORE  
Global Data Party System API | Customer Update | SALESFORCE_CORE  
SAP ECC Customers System API | Customer Create  
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`.
```
{
  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.
Type | Property | Allowable 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  
VALID, INVALID  
Customer | customerStatus | ACTIVE, INACTIVE  
PartyRelatedParty | partyRelationshipType | AGENT, BUYER, CHILD, CLIENT, OTHER, RELATION, SPONSOR, SPOUSE, SUPPLIER, USER, VENDOR  
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:
```
{
  "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:
```
{
  "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 Design Elements
  *