[Legacy] Create new Journey and Draft Entity
Using the APIs to create and then read back a new Journey Instance
A journey in the Fenergo SaaS platform is a configured process flow that represents a clients business operating model. Once an Entity has been created, managing that entity is done by creating a Journey Instance for that Entity. It contains a defined sequence of Steps, Stages and Tasks which is used to gather data for the entity.
| APIs Referenced |
|---|
| Entity Data Command |
| Entity Data Query |
| Journey Command |
| Journey Query |
| Journey Logic Engine |
Overview of the Journey Query
Clients can use the Journey Query API to get the details of Journey Definitions as well as Journey Instances. The Definition (or schema) can be thought of as similar to an Object Definition or class in Object Orientated Programming and then the instances of that Object is how we can think of Journey Instances.
APIs Capabilities:
- List a summary of all journey types
- Get the Schema details of a specific Journey Type
- Get a Journey Instance by Journey ID
- Get the Journeys associated with a specific Entity ID.
Overview of the Journey Command
Clients can use the Journey Command API to not only Create Journey Instances but also to edit and >update the Journey Definitions (Schemas). This would suit clients who wish to create operations around the activation / deployment of new Journeys as part of their Dev-Ops processes.
APIs Capabilities:
- Create Instances of Journeys
- Cancel a Journey Instance
- Complete a Journey Instances Task
- Save a Review Outcome (Approvals)
- Reassign a Task (To a specific FenX User)
- Reset a Task (Reopen an already completed task).
Overview of the Journey Logic Engine
nother API which is available, allows clients to determine which Journeys are in scope based on the Scoping Conditions which are set when the Journey was configured. If you are trying to determine which Journey Instance can be called dynamically or simply creating a list of environment variables for your downstream integration.
APIs Capabilities:
- Determine which journeys are available by Legal Entity Type.
- Can accept values for other available properties which may have a bearing on the available journeys.
- Allows for an Optional Filter to specify Journey Types
Sample Use Case for Creating a Journey
As an API consumer:
GIVEN: I have created a new Client Legal Entity
AND: I want to list all available journeys in scope for that Legal Entity
WHEN: I have identified the appropriate journey
THEN: I want to create an instance of that Journey and a Draft Entity Data Record for that Entity.
Journey Creation Considerations
Journey Scoping : When a Journey Definition is created in the Journey Configuration admin section of the SaaS application, it can have Scoping Conditions applied to it, which control what kind of journey can be created for what kind of entity. It is common, for example to have a different Client Onboarding journey for Legal Entity Company and Individual Types because the process steps and the data points for these entity types are typically not the same.
Journey Data: Within the SaaS User Interface, interacting with a journey appears that data is captured within that journey, however the journey and data whilst related, are not directly connected. After a Journey instance is created, the next step in the pattern is to create a Draft of the entity record which was identified when the Journey Instance was created.
A Journey Instance:
- Records the state of the tasks and the position of the journey instance.
- Maintains a reference to the Entity Draft which is used to record changes to the actual Legal Entity data.
- Is used to merge Draft Legal Entity Data into the verified record.
Listing all Journey types
You can retrieve a list of all the Journey Types by calling the Journey Query API **{{baseURL}}**/journeyquery/api/journey-schema/lite. Simply Send a GET Request to the endpoint opposite. The response will list all the Journeys configured on the Tenant irrespective of the Scoping Conditions defined on the Journey Definition itself.
{
"data": [
{
"id": "d56bac8b-9cfb-4075-be9e-fbcbf579d206",
"versions": [
{
"id": "94524bc8-aa92-4970-afe1-b5bc6e2c377e",
"journeySchemaId": "d56bac8b-9cfb-4075-be9e-fbcbf579d206",
"name": "Company Onboarding New",
"identifier": "COB1",
"type": "Client Onboarding",
"versionNumber": 17,
"effectiveFrom": "2021-09-08T00:00:00Z",
"effectiveUntil": "2021-09-08T00:00:00Z",
"publicationDate": "2022-03-27T18:15:49.291+00:00",
"status": "Published",
"created": "2022-03-27T18:15:17.449Z",
"isActive": false,
"channelType": "Internal",
"version": 2
},
{
"id": "e16ddee3-1b4e-43d5-8827-fbdbc0de5bea",
"journeySchemaId": "d56bac8b-9cfb-4075-be9e-fbcbf579d206",
"name": "Company Onboarding New",
"identifier": "COB1",
"type": "Client Onboarding",
"versionNumber": 19,
"effectiveFrom": "2021-09-08T00:00:00Z",
"effectiveUntil": null,
"publicationDate": "2022-05-27T13:13:58.893+00:00",
"status": "Published",
"created": "2022-05-27T13:13:12.23Z",
"isActive": true,
"channelType": "Internal",
"version": 2
}
.
.
{Other Versions Listed . . . }
.
.
],
.
.
{Further Data Listed . . . . . }
.
.
},
.
.
{Other Journey Types...}
.
.
]
}
Understanding the Journey Query Lite Response
This response above is a snippet of a full response that you will get from your tenant. It lists ALL the Journeys and their versions (including the latest version). The important items to note have been highlighted.
"id": "d56bac8b-9cfb-4075-be9e-fbcbf579d206"is the Top level Id which is the Journey Schema Id. As can be seen within EACH version it is refereed to as the"journeySchemaId".- Within the
"versions"array is an"id"which is the identifier of the version instance of the Journey Schema. This is NOT the identifier to use when creating a Journey Instance. - Also within the
"versions"array is the"status"element, this is the status of the version. - Finally within the
"versions"array is the"isActive"element, which can be true or false.
Calling The Journey Logic Engine - What Journey is in Scope for my Entity?
You can retrieve a list of all the Journeys in scope for a given type by calling the Journey Logic Engine API
**{{baseURL}}**/journeylogicengine/api/v2/engine/evaluate-journey-schema`.
Simply Send a POST Request to this endpoint. The response will list all the Journeys available for the data passed in the Request Body.
{
"data": {
"properties": {
"legalEntityName": {
"type": "Single",
"value": "Acme Finance Group"
},
"companyType": {
"type": "Single",
"value": "Bank"
},
"category": {
"type": "Single",
"value": "Corporation"
},
"country": {
"type": "Single",
"value": "Ireland"
},
"dateOfIncorporation": {
"type": "Single",
"value": "2021-12-31"
},
"entityType": {
"type": "Single",
"value": "Company"
},
"irishEircode": {
"value": "WC91 V59",
"valueId": null,
"type": "Single",
"discriminator": "Single",
"isValid": null
}
}
}
}
{
"data": [
{
"journeySchemaId": "a3fa72bc-bcd1-47d4-b81a-2e181575a5f8",
"journeySchemaVersion": 4,
"name": "Maintenance",
"identifier": "MAINT_1",
"journeyType": "Maintenance",
"channelType": "Internal"
},
{
"journeySchemaId": "af91ca27-6375-41ec-8c22-2ead044adf80",
"journeySchemaVersion": 1,
"name": "Offboard Client",
"identifier": "OFF_1",
"journeyType": "Client Offboarding",
"channelType": "Internal"
},
{
"journeySchemaId": "d56bac8b-9cfb-4075-be9e-fbcbf579d206",
"journeySchemaVersion": 19,
"name": "Company Onboarding New",
"identifier": "COB1",
"journeyType": "Client Onboarding",
"channelType": "Internal"
}
],
"messages": null
}
Understanding the Journey Logic Engine Response
The Logic engine is subjective with regard to how clients have configured their Journeys and set the scoping rules. That will affect the quantity of result items. The scoping rules could be very simple, focusing on just a single property of an Entity Record or could be more complex. In this example we have used two properties. In the response there are three Journeys in Scope returned.
"journeySchemaId"can be used to create an Instance of a Journey."journeyType"is the Journey Schema of type Client Onboarding.
Passing the Optional journeyTypeFilter would have narrowed the search result to just that specific Journey Type. The Journey Types are defined in reference data and can be configured as per client Requirements.
**{{baseURL}}**journeylogicengine/api/v2/engine/evaluate-journey-schema?
journeyTypeFilter=Client%20Onboarding&journeyTypeFilter=ClientOnboarding
Creating a Specific Journey Instance Type
Using the Journey Instance Id from the logic engine response above a POST request can be sent to the following URL **{{baseURL}}**/journeycommand/api/journey-instance containing the below POST body. You need to send in the entityId and the journeySchemaId as parameters in the body as below.
{
"tenant": "4c60779e-e001-4286-ac0f-5df3e2658c57",
"data": {
"entityId": "d1aeecdf-b654-49b3-b3e6-02575de5f4d1",
"journeySchemaId": "d56bac8b-9cfb-4075-be9e-fbcbf579d206"
}
}
{
"data": {
"journeyInstanceId": "a12aabc4-11cc-4db1-a136-b985dc317971",
"journeySchemaId": "d56bac8b-9cfb-4075-be9e-fbcbf579d206",
"journeySchemaVersionNumber": 19,
"entityId": "d1aeecdf-b654-49b3-b3e6-02575de5f4d1"
},
"messages": null
}
Understanding the Create Journey Instance Response
With the Journey Schema Id and the Target Entity Id passed into the POST Request the SaaS platform will create a Journey Instance against the target entity.
"journeyInstanceId"is the Journey Instance Id which can be used to track the process for the given journey.
Creating a Draft Entity Record
The last step in delivering the use case is to create a Draft Entity Record which will be used to gather data throughout the Journey.
**{{baseURL}}**/entitydatacommand/api/entity/d1aeecdf-b654-49b3-b3e6-02575de5f4d1/draft
You need to send a HTTP POST Request to the URL above. This will create a copy of the current verified entity record as a draft which will be used alongside the Journey to gather data. A Journey is configured to know which data from a policy is gathered within which steps/tasks in the Journey, but the actual data itself is saved inside a Draft Entity Record.
{
"data": {
"journeyId": "a12aabc4-11cc-4db1-a136-b985dc317971"
}
}
{
"data": {
"id": "f91f0d6f-b43e-43b4-a8ef-ef73ed2b4595",
"sourceEntityId": "d1aeecdf-b654-49b3-b3e6-02575de5f4d1",
"sourceEntityVersion": 1,
"conflictsResolvedSourceEntityVersion": 0,
"journeyId": "a12aabc4-11cc-4db1-a136-b985dc317971",
"type": "Individual",
"properties": {
"firstName": {
"value": "Pat",
"valueId": null,
"type": "Single",
"discriminator": "Single",
"isValid": null
},
"lastName": {
"value": "Short",
"valueId": null,
"type": "Single",
"discriminator": "Single",
"isValid": null
},
"nationality": {
"value": "Ireland",
"valueId": null,
"type": "Single",
"discriminator": "Single",
"isValid": null
},
"irishEircodeIndividual": {
"value": "WC91 V59",
"valueId": null,
"type": "Single",
"discriminator": "Single",
"isValid": null
}
},
"risk": null,
"role": {
"name": null,
"version": -1
},
"status": "InProgress",
"created": "2023-10-19T09:12:55.8130787Z",
"jurisdictions": [
{
"jurisdiction": "Global",
"versionId": "5d54c3be-a6cf-46ff-b241-52c620b072d2"
},
{
"jurisdiction": "Ireland",
"versionId": "86e2d785-69ad-4b1e-b672-38162797adb9"
}
],
"associatedJurisdictionsFromParents": {},
"evaluatedJurisdictions": [
{
"jurisdiction": "Global",
"versionId": "5d54c3be-a6cf-46ff-b241-52c620b072d2"
},
{
"jurisdiction": "Ireland",
"versionId": "86e2d785-69ad-4b1e-b672-38162797adb9"
}
],
"riskVersion": null,
"accessLayers": {
"geographic": [
"Global"
],
"businessRelated": [
"Enterprise"
],
"geographicDetails": [
{
"dataKey": "Global",
"inheritedFrom": [],
"isInherited": false
}
],
"businessRelatedDetails": [
{
"dataKey": "Enterprise",
"inheritedFrom": [],
"isInherited": false
}
]
},
"version": 0,
"maskedProperties": {
"singleProperties": []
}
},
"messages": null
}
The Create Draft request also returns the created draft record in the response.
This will include as can be seen above the "evaluatedJurisdictions" section. These are the policy's that have been evaluated as in scope.
For clients who intend to update the draft records at a later stage and must retrieve requirements before updating, the policy version Id is an important field. These versionId values are in the response.