Creating Custom Workflow Report
This document aims to describe a generic approach to workflow reporting, illustrating how events can be captured and reported to build insightful reports across various workflow types.
For further details on creating new generic events, visit Creating New Generic Events.
Please, consider the figure and the example sequence of generic events below¶
| dim5 (Sequence number) | dim4 (Step name) | action (Action name) | dim1 | dim2 | value | property (how the value is calculated for the detail card) | label | organization_id | version | category | visitor_id | Required event in a sequence (this is not a field) |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 (Reserved) | Source | Source name | <flow_id> | ignored | 1(ignored) | This field is ignored for the source step (dim5=0) | <workflow_id> | <organization_id> | 1 | workflowReportingEvent | <visitor_id> | Optional |
| 1 | Step name 1 | Action name 1 | <flow_id> | <room_id> | Positive Float | ["Description string1=SUM", "Description string2=AVG"] | <workflow_id> | <organization_id> | 1 | workflowReportingEvent | <visitor_id> | Required |
| 2 | Step name 2 | Action name 2 | <flow_id> | <room_id> | Positive Float | ["Description string1=SUM", "Description string2=AVG"] | <workflow_id> | <organization_id> | 1 | workflowReportingEvent | <visitor_id> | Optional |
| 4 (Pay attention that step 3 is skipped) | Step name 4 | Action name 3 | <flow_id> | <room_id> | Positive Float | ["Description string1=SUM", "Description string2=AVG"] | <workflow_id> | <organization_id> | 1 | workflowReportingEvent | <visitor_id> | Optional |
Brief Fields Description:¶
Description of the fields used in the generic workflow reporting events for constructing reports
| Field | Type | Description |
|---|---|---|
| category | String | Categorizes the event type within the system |
| version | Integer | Schema version of the event data |
| organization_id | UUID | Identifies the organization to which the event data belongs |
| visitor_id | String | Identifies the individual or entity initiating the workflow |
| label | String | ID of the workflow for which the report is generated |
| action | String | Specific action within a workflow step |
| value | Integer/Positive float | Numerical data associated with the action |
| property | String | Describes how the value field is aggregated or calculated |
| dim1 | String | Unique identifier for the workflow instance |
| dim2 | String | Specific room where the event occurred |
| dim4 | String | Descriptive label for the step within the workflow, correlating to its sequence number |
| dim5 | Integer | Sequence number of the event within the workflow sequence |
Detailed Fields Description:¶
- dim5 (Sequence Number) [Integer]: Indicates the order of the event within the workflow sequence. It is used to track the progression of steps and actions throughout a workflow. The usage of this field varies as follows:
- 0: Reserved for events detailing the source of the workflow initiation. This event is optional and specifies the origin from which the workflow was triggered (e.g., an advertisement click, direct entry). When present, it provides valuable context about how the workflow was initiated but does not describe an action within the workflow itself.
- 1: Indicates the initial action within the workflow. This event is essential as it marks the beginning of the workflow process. For example, it could represent the start of a customer's journey on a website or the creation of a support ticket. The initial event must always be provided to establish the starting point of the workflow.
- >1: Used for subsequent actions or steps within the workflow. Events with a sequence number greater than 1 are optional and can be included to describe additional stages or actions that occur after the initial step. This flexibility allows for event sequences that may skip certain steps, accommodating workflows that can branch or vary in complexity. Including these events when applicable provides a more detailed view of the workflow but they are not mandatory for every sequence.
- dim4 (Step Name) [String]: Provides a descriptive label for the step within the workflow, correlating to its sequence number (dim5). This name should concisely convey the nature of the step or action, aiding in the clear understanding and reporting of the workflow's progression. The handling of this field is as follows:
- First Occurrence Priority: When events are processed, the Step Name provided in the first occurrence of a specific dim5 value within a workflow sequence is used to label all subsequent events with the same dim5 value. This ensures consistency in reporting and analysis, even if subsequent events for the same step vary in their dim4 description.
- Default Assignment: If the Step Name field is empty for the first event of a specific sequence number (dim5), a default step name will be assigned to maintain clarity in the workflow's progression. For instance, if the first action in a workflow does not specify a Step Name, it will be automatically labeled as "1st action". This default naming convention helps maintain the integrity and readability of the report, ensuring each step is identifiable even when specific names are not provided.
- action (Action Name) [String]: A mandatory field identifying the specific action or event within a workflow step, such as "Checkout Initiated" or "Support Ticket Closed." It provides a concise descriptor of the activity or decision point, crucial for grouping related events and analyzing workflow progression.
- dim1 [String]: A unique identifier for the workflow instance, allowing for tracking and reporting on specific instances or sessions of a workflow. For example, in a customer support ticket system, this might be the ticket ID.
- dim2 [String]: Identifies the specific room where the event occurred, using the room_id. IMPORTANT: Currently we don’t use it in the frontend, although it is being returned in the response in the rooms attribute of nodes
- value [Integer/Positive float]: Numerical data associated with the action, which can be 1 or a positive float. This could represent quantities, durations, or other measurable outcomes of the action. For actions not requiring a numerical value, this should be set to 1.
- property [String]: Describes how the value field is aggregated or calculated, using a format such as "Total Amount=SUM" or "Average Time=AVG". This field allows for customizable aggregation in reports, tailored to the specific analysis needs of the workflow. IMPORTANT: Currently we don’t use it in the frontend, although it is being returned in the response in the description attribute of nodes
- label [String]: A mandatory field that holds the ID of the workflow for which the report is generated.
- organization_id [UUID]: Identifies the organization to which the event data belongs.
- version [Integer]: Indicates the schema version of the event data; the current version is 1. This field ensures compatibility and proper interpretation of event data across different versions of the reporting system.
- category [String]: Should always be set to "workflowReportingEvent" to categorize the event type within the system. visitor_id [String]: A mandatory field identifying the individual or entity initiating the workflow. It is crucial for attaching goals to the workflow.
Creating a New Workflow Instance¶
It's necessary to initiate a new workflow instance. This step registers the workflow within the system, enabling the structured analysis of events tied to specific visitor journeys. Follow the detailed instructions provided in the Create a New Workflow documentation.
Workflow Event Rules¶
Keeping Event Order Consistent: Every event in a workflow has a sequence number (dim5), a step name (dim4), and an action. These should stay the same through the whole workflow to make sure events are matched correctly to the steps they belong to. For example, if an event is about finishing a task with the action "Form Submitted", it should keep its sequence number even if some steps before it didn't happen.
Example for Clarity (consider the figure below): If we have an event (action) called "Action 0-2", it might be given the sequence number 3. This number stays the same for this event, even if earlier steps (numbered 2) are skipped or not needed for some reason. This helps keep track of where each action fits in the workflow.
Sequence Numbers Must Be Different: Each event in a sequence needs to have a different sequence number. If two events in a sequence have the same number, it can make things confusing. Only the first event with a unique number will be used, and any extras are ignored. This rule helps keep the workflow clear and easy to understand.
Attaching Goals to Workflows¶
Effectively measuring workflow success requires attaching specific, measurable goals. By sending goal events to the system and utilizing the visitor_id field, we can attach them to the workflow. For a complete guide on how to send goal events, consult the Goal Match API documentation.