Skip to main content

Launch Journey and Draft Entity

Using APIs to create Entity Draft and launch Journey Instance​

A journey in the Fenergo SaaS platform is a configured process flow that represents a client's 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
Journey Command
Journey Query

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 Oriented Programming, and then the instances of that Object is how we can think of Journey Instances.

API 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
  • Get the Launch Journey Business Process details by a specific Business Process 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 DevOps processes.

API Capabilities:

  • Create Instances of Journeys
  • Cancel a Journey Instance
  • Complete a Journey Instance's Task
  • Save a Review Outcome (Approvals)
  • Reassign a Task (To a specific FenX User)
  • Reset a Task (Reopen an already completed task)
  • Initialize a Launch Journey Business Process (Creates Entity Drafts and Journeys for specific Entity)

Sample Use Case for Creating a Journey and Entity Draft​

  As an API consumer:

      GIVEN: I have created a new Client Legal Entity

      AND: I want to create journey instances with a specific type and scope for that Legal Entity

      THEN: I initialize the launch journey business process which creates journeys and draft entity data records for that Legal 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

Creating Journey Instances and Draft Entities using Launch Journey Business Process​

This approach provides a streamlined alternative to the legacy approach for creating journeys and draft entities. Rather than requiring multiple separate API calls to determine available journeys and create instances, this business process automatically evaluates scoping conditions and creates both journey instances and entity draft records in a single API request.

To initialize the business process, send a POST request to **{{baseURL}}**/journeycommand/api/journey-instance/launch-journey with the following required parameters in the request body: entityId and journeyType. The jurisdictions and accessLayers parameters are optional and can be included as needed.

Journey Command Launch Business Process - JSON POST Request
{
  "tenant": "4c60779e-e001-4286-ac0f-5df3e2658c57",
  "data": {
    "entityId": "58e4b43a-a082-49a6-bf79-0cf8df2313c6",
    "journeyType": "Client Onboarding"
  }
}
Journey Command Launch Business Process - JSON POST Response
{
    "data": {
        "businessProcessId": "24511767-4586-4b69-af43-c405ec6b154a"
    },
    "messages": []
}

Understanding the Launch Journey POST Response​

When you provide the target entity ID and journey type in the POST request, the SaaS platform launches a business process that creates an entity draft and journey instance for the target entity.

  • "businessProcessId" is the unique identifier for the launched business process, which can be used to track the creation of journeys for the target entity.

Details of the launched journeys and entity draft records​

To retrieve details of the launched journeys and entity draft records, send a GET request using the businessProcessId from the previous POST response.

`**{{baseURL}}**/journeyquery/api/journey-instance/launch-journey/{businessProcessId}`;
{
    "data": {
    "businessProcessId": "24511767-4586-4b69-af43-c405ec6b154a",
    "status": "In Progress",
    "payload": {
      "entityId": "58e4b43a-a082-49a6-bf79-0cf8df2313c6",
      "journeyType": "Client Onboarding"
    },
    "created": "2025-01-05T14:48:00.000Z",
    "messages": [],
    "items": [
      {
        "journeyId": "118313c6-91e6-4b05-a537-5a1ab906418f",
        "journeySchemaId": "a5cfd4e8-732f-4601-ac88-652b64c8439c",
        "journeySchemaVersionNumber": 1,
        "entityDraftId": "c7b9fd6f-cdea-46fb-ab9c-1006adc812a0",
        "journeyType": "Client Onboarding",
        "journeyName": "COB Journey",
        "status": "Done"
      },
      {
        "journeyId": "77538ab0-5463-4dd3-b19d-ca631378a275",
        "journeySchemaId": "bf44f48e-3eff-40f3-a1e5-da389ab7aa9d",
        "journeySchemaVersionNumber": 1,
        "entityDraftId": "fed6a403-7a56-4d08-bbda-c34f1c0c35ee",
        "journeyType": "Client Onboarding",
        "journeyName": "COB Journey 2",
        "status": "In Progress"
      }
    ]
  },
  "messages": []
}

Understanding the Launch Journey GET Response​

The GET response provides comprehensive details about the launched journeys and created entity drafts, enabling monitoring of the business process progress.

  • "status" is the status of the business process, available values:

    • In Progress: there are some unfinished actions like creating journeys/entity drafts
    • Done: the business process is completed and all scoped journeys and entity drafts are created
    • Error: some error occurred while creating journeys/entity drafts

  • "payload" contains target entity ID and the journey type for which the business process was created

  • "messages" contains error details if the business process encounters any issues during execution

  • "items" contains all details of launched journeys and created drafts, each entry has below important information:

    • "journeySchemaId" and "journeySchemaVersionNumber" - evaluated schema information scoped for target entity and journey type
    • "entityDraftId" ID of created entity draft for target entity and linked with launched journey
    • "journeyType" the type of launched journey
    • "journeyName" the name of launched journey
    • "status" of launched journey, available values:
      • In Progress: the specific journey is not yet created
      • Done: the specific journey is created
      • Error: some error occurred while creating specific journey

Creating/Updating Entities and Journey Instances using Event Ingress​

Event Ingress is Fenergo's API interface for automatic integrations where client systems need to seamlessly push data updates to the Fenergo SaaS platform without manual intervention. Clients send a single event message containing entity data, and Fenergo automatically handles all internal orchestration and business process execution. The system operates asynchronously - clients receive immediate acknowledgment upon message receipt, followed by final outcome notifications through the standard notification service. This approach provides loose coupling between client systems and Fenergo, eliminating the need for multiple API calls while Fenergo manages workflow complexity internally.