Using Entities with Journeys

Journeys can be associated with Entity Types and External Entity Types by utilizing the Entity and ExternalEntity DTOs during POST and PUT operations.

Intent of Entities with Journeys

Entity Types and External Entity Types are pre-defined objects that allows you to associate your application's identifiers with Chassi's native entities and track them alongside your journeys.

For example, if you want insight on how a customer, when not using Chassi's single customer view, from your application interacts with a checkout process... a Journey would be created and that customer ID would be added to it. This will allow you to obtain data on that customer's interacts throughout the journey.

Introduction to the Use Case

For our use case, we are going to create a journey that is linked to two Chassi entities, Customer and Contact, as well as a few external entity types. We are going to represent the data shown in the diagram below.

First, we have a Customer that is linked by the externalCustomerId through an accountId of Salesforce, and a Contact that is linked by the externalContactId through a userId of an external application, MyApp.

Next, we are going to link that Customer and Contact in the Entity Array of our journey, as well as, the externalCustomerId and externalContactId as customerId and contactId in the External Entity Array, respectively.

Finally, we are going to create a new, customer External Entity Type patientId that represents a field in MyApp and link that as an External Entity as well.

Creating a Customer with an externalCustomerId

During the customer creation process (see Create Customer ) you will have the option to fill out the externalCustomerId field. This ID will be the same one used from an external application. In our example it is the accountId we use for SalesForce.

DTO

Entity

This DTO is utilized within a Journey to associate it with a Chassi internal Entity Type.

Properties

Name	Type	Description	Notes
entityTypeIdentifier	String	Unique identifier for a chassi internal entity type	This is used as your qualifier. Example: If you want to associate with the internal entity type of Customer, customerId would be your entityTypeIdentifier
entityId	String	Field of the chassi internal entity being used as the identifier.	Example: If customerId is your entityTypeIdentifier, then this field would be the UUID of the customer you want to associate with the journey.

Example Json

{
  "externalEntityTypeIdentifier" : "customerId",
  "externalEntityId" : "b35b449c-7037-11e9-a923-1681be663d3e"
}

Creating an external entity type for patientId

In order to use patient as an external entity type and use it within the ExternalEntity DTO, we first need to create it using the ExternalEntityType API's POST method (See External Entity Type ).

An example post request to the proper endpoint would look like the following:

JSON

{
  "entityTypeIdentifier" : "patientId"
}

Upon creation of the ExternalEntityType, you will now be able to link your patientId into an array of ExternalEntity DTO objects during the creation of a Journey.

ExternalEntity DTO

This DTO is utilized within a Journey to associate it with the External Entity Type.

Properties

Name	Type	Description	Notes
externalEntityTypeIdentifier	String	Unique identifier for an external entity type	This is used as your qualifier. Example: If Patient is your entity type from an external source (such as Salesforce), then use patientId as your qualifier.
externalEntityId	String	Field of the external entity being used as the identifier.	Example: If Patient is your external entity type, then this field would be the ID, for your patient, from the external source.

Example Json

{
  "externalEntityTypeIdentifier" : "patientId",
  "externalEntityId" : "SFO-7771"
}

Journey Creation with EntityType and ExternalEntityType

During the Getting Started with Lifecycle documentation, you import a postman collection containing a request called Create a new Journey (Start Tracking).

When the collection is run, the following JSON POST request is sent to create a journey :

JSON

{
	"lifecycleId": "f19e9011-7b80-4123-b535-8fe32fda6258",
	"versionNo": 1,
	"entityArray": [{
			"entityTypeIdentifier": "customerId",
			"entityId": "0b166dae-028c-4e1b-95cd-4f09da6facc2"
		}
	],
	"externalEntityArray": [{
			"externalEntityTypeIdentifier": "customerId",
			"externalEntityId": "customer-123"
		}
	]
}

From the above request, there are two fields that allow you to associate your journey with entity types and external entity types... entityArray and externalEntityArray.

Linking Entity Identifiers to entityArray

The entityArray is a list of Entity DTOs containing the information to associate your journey to one or multiple Chassi internal entity types.

For example, if we want to associate our journey with a specific customer, we would add only one Entity DTO to the array containing the following:

JSON

{
	"lifecycleId": "f19e9011-7b80-4123-b535-8fe32fda6258",
	"versionNo": 1,
	"entityArray": [{
			"entityTypeIdentifier": "customerId",
			"entityId": "0b166dae-028c-4e1b-95cd-4f09da6facc2"
		}
	]
}

Linking External Entity Identifiers to externalEntityArray

Similar to the above Linking Entity Identifiers to entityArray section, the externalEntityArray is a list of ExternalEntity DTOs containing the information to associate your journey to one or multiple of the pre-defined external entity types.

Note: All external entity types that are being added to an externalEntityArray MUST be created before use.

An example of associating a single external entity type to the journey would be as follows:

Example of single External Entities in array

{
	"lifecycleId": "f19e9011-7b80-4123-b535-8fe32fda6258",
	"versionNo": 1,
	"externalEntityArray": [{
			"externalEntityTypeIdentifier": "patientId",
			"externalEntityId": "SFO-7771"
		}
	]
}

Note: In order to add patientId to the ExternalEntity and thus the array, you must have first added it as an external entity type. Failure to do so will return a HTTP 400 response. See External Entity Type for information on the CRUD operations available for the API.

A full example of a successful POST request and response is provided below.

POST request

{
	"lifecycleId": "f19e9011-7b80-4123-b535-8fe32fda6258",
	"versionNo": 1,
	"entityArray": [{
			"entityTypeIdentifier": "customerId",
			"entityId": "0b166dae-028c-4e1b-95cd-4f09da6facc2"
		}],
    "externalEntityArray": [{
			"externalEntityTypeIdentifier": "patientId",
			"externalEntityId": "SFO-7771"
		}]
}

POST response

{
	"journeyId": "5b4eba5c-a15b-4a15-8b6a-215bf79d4fb2",
	"dateCreated": "2019-05-09T20:03:25.350Z",
	"lastUpdated": "2019-05-09T20:03:25.350Z",
	"lifecycleId": "f19e9011-7b80-4123-b535-8fe32fda6258",
	"lifecycleName": null,
	"lifecycleVersionId": "97da9cd3-754b-4c2a-8ce4-9029bf138415",
	"versionNo": 1,
	"journeyCreateDate": "2019-05-09T20:03:25.349Z",
	"cycleStartDatetime": null,
	"previousStepId": null,
	"previousStepName": null,
	"previousStepType": null,
	"currentStepId": "447fda1f-84cc-4fed-9f4d-03c56599afdd",
	"currentStepName": "Onboarding",
	"currentStepType": "Not_Started",
	"currentCycleNo": 1,
	"stepStartDatetime": "2019-05-09T20:03:25.349Z",
	"currentPath": "{\"steps\":[{\"pathIndex\":1,\"stepId\":\"447fda1f-84cc-4fed-9f4d-03c56599afdd\",\"stepName\":\"Onboarding\"}]}",
	"entityArray": [{
			"entityTypeIdentifier": "customerId",
			"entityId": "0b166dae-028c-4e1b-95cd-4f09da6facc2"
		}],
    "externalEntityArray": [{
			"externalEntityTypeIdentifier": "patientId",
			"externalEntityId": "SFO-7771"
		}],
	"currentStepElapsedSeconds": 0,
	"currentCycleElapsedSeconds": 0,
	"elapsedJourneyTime": 0,
	"journeyTags": [],
	"metadata": []
}