User Guide: Periodic Async Event Configuration
This guide explains how to configure and use the Periodic Async Event
Generator in the system. It is designed to assist both technical and non-
technical users in understanding and effectively utilizing the feature.
Overview
The Periodic Async Event Generator allows you to schedule automated events
based on specific conditions in your data. These events can trigger workflows,
such as querying a database and processing the resulting records.
Key Features
Upload JSON configuration files to define the behaviour of the Async
Event Generator.
Automatically trigger events at a specific time interval.
Generate event payloads based on a query that fetches data from the
system.
Limit the number of events and records processed during each
execution.
Steps to Configure and Use the Async Event Generator
Step 1: Create the JSON Configuration File
The configuration file defines how and when the Async Event Generator should
trigger events. Below is the structure:
JSON File Schema
KEY Description
eventIntervalInSeconds Time interval (in seconds) between each event generation. Minimum
value: 60 seconds.
eventId A unique identifier for the event, which refers to the listener
resourceIdField Column name in the query result that contains the unique ID of the
record. The name must be in camelCase format, e.g., internalRequestId.
resourceIdValueQuery Query to fetch the records from the system.
maxRecordsPerEvent Number of records included in each event payload. Current options: 1
(one record per event) or 0 (all records in a single event). Currently our
system supports only 1 for now
eventStaggerlimit Maximum number of records processed in each execution cycle.
Given here is a sample JSON configuration
{
"eventIntervalInSeconds": "3600",
"eventId": "EINV-POST",
"resourceIdField": "internalRequestId",
"resourceIdValueQuery": "select internal_request_id from
xceler_e_invoice_tracking xeit where status = 'PENDING:VALIDATION'",
"maxRecordsPerEvent": 1,
"eventStaggerlimit": "20"
}
Step 2: Set Up Base File Upload Configuration
1. Navigate to System Settings → Base File Upload.
2. Click Add and create a new Base File Upload Record
a. Upload File Category: Select “async_event_config”.
b. Upload File Type: Enter a unique name for the event
configuration.
Save the record.
The system will validate the uploaded JSON configuration to ensure it matches
the expected schema.
Validation Behavior
If validation fails, the system logs the error:
"Upload File Type: 'async_event_config' does not match the expected file
schema", and the engine stops.
If validation succeeds, the Async Event Generator begins processing the
configuration.
Step 3: Event Generation and Processing
1. Executes the resourceIdValueQuery at the interval specified in
eventIntervalInSeconds.
2. Processes records up to the limit specified in eventStaggerlimit.
Event Payload Example
If the resourceIdValueQuery returns the following result:
internal_request_id
REQ001
REQ002
The system generates events like:
Event Name: EINV-POST Payload: {" internalRequestId ": "REQ001"}
Event Name: EINV-POST Payload: {" internalRequestId ": "REQ002"}
Important Notes
Single Record Mode: Currently, only one record (maxRecordsPerEvent =
1) can be included in each event payload.
Stagger Limit: A maximum of eventStaggerlimit events is generated per
execution cycle.
Future Enhancements: The system may support bulk processing of
multiple records in a single event in future updates.
System Behavior
If there are 100 matching records, the system:
1. Generates 20 events in the first execution cycle.
2. Processes the remaining records in subsequent cycles.
Success and Error Logging in Event Generation
The system logs the outcome of each event generation process in the
xceler_async_event_logs table. This ensures traceability for both
successful and failed events.
How Logging Works:
Successful Event Generation:
When an event is successfully generated, a success status set to true is
recorded in the xceler_async_event_logs with the
corresponding resourceIdValue.
The log includes the tenant ID, event ID, payload details of the generated
event and the uploaded configuration.
Failed Event Generation:
When an event is successfully generated, a success status set to false is
recorded in the xceler_async_event_logs with the
corresponding resourceIdValue.
The log includes the tenant ID, event ID, payload details of the generated
event and the uploaded configuration.