HCL Domino · Event-Driven Integration · Domino API-Engine
Event-Driven Data Processing in HCL Domino – Beyond Scheduled Agents
Event triggers · Process orchestration · Runtime parameters · Execution logs
An integration process rarely begins with an SQL statement or a document update. It begins with a reason to run: a file arrives, an e-mail is delivered, a database changes, an HTTP request is received, or a scheduled processing window starts.
The difficult part is not simply launching code. It is turning these signals into repeatable workflows with clear configuration, controlled execution and useful operational records. This article looks at event-driven Domino integration using the SL Net-Solutions Domino API-Engine, illustrated by a deliberately simplified integration scenario.
Trigger versus workflow
1. An event is the beginning, not the whole process
Consider an incoming CSV file. Detecting its arrival is only the first step. Before any business data is written, the receiving process may need to check that the transfer is complete, validate the file structure, resolve references, apply transformation rules and decide which records to create or update.
After processing, an operator needs to know what happened: which job ran, which input was used, whether the target updates succeeded and what should happen if the run is repeated.
The architectural question is not “How do I start a script?” but “How do I connect an external event to a controlled, observable business process?” This distinction becomes important when several applications, servers and external systems are involved.
Domino agents already support schedules and event triggers. The API-Engine therefore does not introduce the idea of event-driven execution to Domino. Its value in this scenario is the integrated processing model around the trigger: job definitions, reusable scripts, parameter sets, integration functions and task-level logging.
Entry points
2. Several ways to start the same kind of work
Different integration tasks have different natural starting points. The API-Engine can support several activation patterns rather than forcing every process into one fixed polling interval.
Incoming files
Watch a directory or file pattern and process an incoming CSV, XML or other supported file when the workflow’s readiness conditions are met.
Incoming messages
Use the dedicated APIJOBF mail-in path to activate authorized processing jobs. Scripts can work with relevant message fields and attachments.
Domino data changes
Detect relevant NSF changes and initiate follow-up processing, such as transformation, replication or selective synchronization.
Incoming requests
Receive requests through a configured API-Engine HTTP listener, then use @HttpReceive to access request information for application logic.
Recurring jobs
Run work at defined intervals, once, or at system startup. Scheduled processing remains useful for reconciliation, batch operations and periodic exports.
Execution constraints
Where supported by the event configuration, restrict overlapping execution of sensitive jobs, select processing contexts and organize recurring tasks.
Event-driven does not necessarily mean instantaneous. Directory checks, database watches, listener configuration and scheduling policies determine when a workflow actually begins. The required latency should be part of the integration design.
System architecture
3. Separating activation, configuration, execution and logging
The API-Engine separates different operational responsibilities. That distinction is useful when a single script needs to run in several environments or when jobs must be maintained without embedding every configuration value in source code.
Simplified architecture, not a literal internal call sequence. Mail-in activation uses APIJOB.NSF; the exact path from an event to processing depends on the configured trigger.
| Component | Responsibility |
|---|---|
APICTRL | Stores event definitions, scripts, batches and related execution configuration. |
APIJOB | Receives mail-in submissions used to activate authorized Engine processing. |
TOOLBOX | Provides named parameters and alternative configurations for scripts, for example different paths, server contexts or processing profiles. |
APILOG | Maintains execution records that can be examined by task, job and execution time. |
These components are related, but they have different roles. In particular, TOOLBOX supplies parameters; it is not the scheduler. Likewise, an APILOG record provides traceability, but a production integration must still define what counts as a successful run and how failed work is recovered.
Practical example
4. A file arrives – what should happen next?
Imagine a generic supplier sending a product update as a CSV file. A Domino application maintains the internal product records, while selected data is also used by an external SQL-based service. The example is intentionally generic and uses no production system details.
A configured directory watch identifies a candidate file. The design verifies that it is complete and ready to process.
The appropriate job and script are selected, with environment-specific paths and other values supplied through configuration.
The script checks required columns, identifiers and data types. Invalid records are rejected or isolated according to the business rules.
Supplier identifiers, currency values and status fields are mapped to the Domino application’s data model.
Documents and related SQL data are created or updated with stable keys and repeatable write operations.
The job reports processed, rejected and failed items. Input disposition and retry behavior depend on the configured workflow.
A file-arrival event is not proof that a file is ready. Many transfers write a file gradually. A robust design can require an atomic rename, a separate ready marker or a stability check before opening the payload. The exact mechanism depends on the sending system.
Script configuration
5. One processing script, multiple environments
Integration logic and environment-specific configuration should not be the same thing. A script that imports structured records may need different paths, database names, filters or destination systems in test and production environments.
In the API-Engine, TOOLBOX can provide script parameters, including different parameter sets for different execution contexts. The script consumes the selected values rather than hard-coding them throughout its processing logic.
| Illustrative parameter | Test profile | Production profile |
|---|---|---|
| Input directory | /incoming/test/ | /incoming/production/ |
| Target database | products-test.nsf | products.nsf |
| Validation mode | Strict + verbose diagnostics | Strict + operational reporting |
| Script logic | Same processing logic | Same processing logic |
Illustrative configuration values only; these are not literal field names or a published API-Engine TOOLBOX schema.
This separation helps keep integration scripts reusable. It does not remove the need for controlled access to credentials, approval of configuration changes or environment-specific testing.
Reliability
6. Reliable automation needs more than an event trigger
Once an interface becomes operationally important, several questions deserve explicit answers. They are not automatically solved by a directory watcher, an HTTP listener or a logging database.
Idempotent writes
Can the same file, message or request be processed again without duplicate business records or unwanted side effects?
Overlapping executions
Could two runs update the same records? Where needed, use exclusive execution settings, locking or application-level coordination.
Partial success
What happens if Domino updates succeed but a subsequent SQL write fails? Define checkpoints, compensating operations or reconciliation paths.
Validation and authorization
Validate received data and restrict who can initiate processing. Mail-in and HTTP entry points require an explicit security design.
Useful task logs
Record enough context to distinguish a completed run, an input error and a recoverable system failure.
Retries and reconciliation
Define what is safe to replay and how missed or failed work will be detected. Logging alone does not provide automatic recovery.
The API-Engine provides execution infrastructure and integration functions; data consistency remains a design responsibility. This is especially relevant when several systems participate and no single transaction can cover every operation.
Two other integration patterns
7. Mail-In and HTTP can initiate the same processing model
The file example is intentionally simple. The underlying pattern also applies when the input arrives by a different route.
| Entry point | Illustrative processing | Important consideration |
|---|---|---|
Mail-In via APIJOB.NSF | An authorized message provides parameters or an attached XML/CSV document. A script reads the relevant content and starts a controlled import. | Restrict which senders or identities may activate which jobs; validate all received content. |
| HTTP request via configured listener | The Engine receives a request, accesses information through @HttpReceive, validates input and performs the required business operation. | Plan authentication, secure transport, timeouts, error responses and exposure of the listener separately. |
| NSF change or recurring scan | Relevant document changes trigger transformation or downstream synchronization without requiring a manual export. | Account for selection criteria, concurrent modifications, deletions and recovery after missed changes. |
The API-Engine can connect different entry points to a common processing architecture. That does not mean a file watch, a mail-in job and an HTTP request have identical security, latency or transaction semantics. Each adapter needs its own operational rules.
Choosing the right architecture
8. Domino agents, integration products or the API-Engine?
Standard Domino agents are capable of both scheduled and event-triggered execution. LotusScript and Java can also read files, call services, write data and implement sophisticated business workflows. For a small, self-contained task, an agent may be entirely appropriate.
The distinction becomes more relevant when an organization operates many recurring integration processes with different data sources, parameter profiles, triggers and logging requirements. In that situation, the API-Engine offers a dedicated runtime and a consistent framework for combining these concerns.
The API-Engine is an architectural option, not a claim that equivalent integration work is impossible with LotusScript, Java or other integration products. The choice depends on the existing application, operational requirements and the amount of integration logic that must be maintained.
For background on Domino’s native capabilities, see HCL’s documentation on event-triggered agents and Agent Manager execution settings.
Where the pattern fits
9. Typical use cases for event-driven Domino integration
File-based business interfaces
Watch incoming structured data, validate it and update Domino or downstream systems with repeatable mapping rules.
Inbound service requests
Connect a configured HTTP entry point to server-side Domino processing and controlled responses.
Document-driven workflows
React to relevant NSF changes and apply additional checks, transformations or integrations.
Mail-based data intake
Use authorized incoming messages and attachments to initiate background jobs.
Recurring reconciliation
Combine event-driven updates with scheduled checks that detect missed or inconsistent state.
Integration of mature applications
Retain established Domino business logic while connecting additional data sources and services.
These use cases do not require a wholesale replacement of existing Domino applications. The integration layer can help preserve established workflows while adding new entry points, destinations and operating controls.
Conclusion and next steps
From incoming events to traceable business processes
A reliable integration service has to do more than execute a script at the right moment.
It must understand the trigger, obtain the appropriate configuration, process business data consistently and leave a useful execution record. The Domino API-Engine brings these elements together in a dedicated server-side environment, while allowing each integration to define its own validation, security and recovery rules.
This article deliberately concentrates on the architecture. A separate, self-contained example script can illustrate the implementation details without mixing them into the conceptual overview.
Explore the Domino API-Engine
Review the capabilities, try the available Evaluation Package or discuss a concrete Domino integration scenario.