ConnectorHub Overview

ConnectorHub is a core component of the Luther Systems platform that enables seamless integration between enterprise systems and the Common Operations Script (also known as phylum), which automates complex business processes. It acts as a secure, configurable interface between process logic and external systems, allowing the platform to send and receive data across organizational and system boundaries without requiring custom code for each integration.

ConnectorHub listens for events emitted by the Common Operations Script. These events represent requests to external systems—such as verifying a customer’s identity, updating a database, sending an invoice, or triggering a payment. The hub dispatches these requests to the correct third-party service and relays the results back into the business process.

Key Concepts

• Event-Driven Process Automation Business processes emit structured events to represent tasks that require interaction with external systems. Each event includes metadata (e.g., system name, organization, payload) and is tagged to a handler that processes the response once it arrives.

• Connectors A connector is a reusable integration with a third-party system. Examples include Equifax for ID verification, Postgres for database queries, Stripe for payments, and Camunda for workflow execution. The hub uses configuration files to map system names to their corresponding connector and responsible organization.

• Factories and Handlers When an event is created, it is associated with a business object (e.g., a claim, payment, or task) and a handler that knows how to process the eventual response. These are created using a factory pattern, allowing scalable, stateless processing logic.

• Response Lifecycle After receiving a response from the external system, the ConnectorHub routes it back into the platform’s logic layer. The platform identifies the original business object and passes the response to the appropriate handler, which may update the object’s state or raise new events.

• Privacy and Storage Event data can include sensitive or proprietary information. To protect this data, the platform stores event context and payloads in a private data collection (PDC) shared only among authorized organizations. The orderer (consistency layer) has no access to this data. Storage strategies are configurable to support privacy, auditability, and data minimization.

Real-World Example: Insurance Claims Process

Imagine a digital insurance claims process. As a claim progresses, the system must interact with multiple external parties: verifying customer identity, checking policy details, generating and emailing invoices, and issuing payments. ConnectorHub enables this by dispatching requests at each step to the appropriate system and returning the results to the business logic layer.

This enables end-to-end automation of processes—without hardcoding integration logic or exposing sensitive data to unnecessary parties.

ConnectorHub Event Functions

These functions generate structured event payloads to be dispatched by ConnectorHub to third-party systems. Each function must be used within the context of a connector factory, and returns a sorted-map that encapsulates a request for a specific connector.

mk-email-req

Creates a request to send an email.

Arguments:

• recipient (string): The email address of the recipient.
• title (string): The subject line of the email.
• body (string): The plain text body of the email.

Returns:

A sorted-map capturing the email request, destined for the connector via the factory and ConnectorHub.

mk-gocardless-req

Creates a request to initiate a GoCardless payment.

Arguments:

• details (sorted-map):

  • "amount" (int): Payment amount in minor currency units.
  • "app_fee" (int): Application fee amount.
  • "charge_date" (string): Date to schedule the charge (ISO 8601).
  • "currency" (string): Currency code (e.g., "GBP", "USD").
  • "faster_ach" (bool): Whether to enable Faster ACH payment.
  • "mandate_link" (string): GoCardless mandate ID.
  • "metadata" (sorted-map): Optional key-value metadata.
  • "reference" (string): Payment reference label.
  • "retry_if_possible" (bool): Whether to retry on failure.

Returns:

A sorted-map capturing the payment request, destined for the connector via the factory and ConnectorHub.

mk-camunda-start-req

Triggers the start of a Camunda workflow process.

Arguments:

• process_definition_key (string): ID of the process definition to start.

• vars_map (sorted-map, optional):

  • "business_key" (string): Optional correlation key.
  • Other keys: Additional workflow variables.

Returns:

A sorted-map capturing the workflow start request, destined for the connector via the factory and ConnectorHub.

mk-camunda-inspect-req

Inspects the state of a Camunda process instance.

Arguments:

• process_instance_id (string): ID of the workflow instance to inspect.
• wait_for_state (string, optional): Optional workflow state to await.

Returns:

A sorted-map capturing the inspection request, destined for the connector via the factory and ConnectorHub.

mk-equifax-req

Performs an identity verification request against Equifax.

Arguments:

• details (sorted-map):

  • Required:

    • "forename" (string): First name.
    • "surname" (string): Last name.
    • "dob" (string): Date of birth (YYYY-MM-DD).

  • Optional:

    • "account_number" (string)
    • "account_sort_code" (string)
    • "middle_name" (string)
    • "address_name" (string)
    • "address_number" (string)
    • "address_street1" (string)
    • "address_street2" (string)
    • "address_postcode" (string)
    • "address_post_town" (string)
    • "previous_address_name" (string)
    • "previous_address_number" (string)
    • "previous_address_street1" (string)
    • "previous_address_street2" (string)
    • "previous_address_postcode" (string)
    • "previous_address_post_town" (string)
    • "nationality" (string)

Returns:

A sorted-map capturing the identity verification request, destined for the connector via the factory and ConnectorHub.

mk-psql-req

Executes a query on a PostgreSQL database.

Arguments:

• query (string): SQL query string.

• args (vector of sorted-maps, optional): List of parameters:

  • "clazz" (string): Data type class.
  • "representation": Value of the parameter.

• metadata (sorted-map, optional): Additional metadata.

Returns:

A sorted-map capturing the database query request, destined for the connector via the factory and ConnectorHub.

mk-pdfserv-req

Creates a request to convert HTML into a PDF.

Arguments:

• html (string): Raw HTML content to render.

Returns:

A sorted-map capturing the PDF generation request, destined for the connector via the factory and ConnectorHub.

mk-stripe-charge-req

Initiates a Stripe charge against a customer.

Arguments:

• req (sorted-map):

  • "customer_id" (string): Stripe customer ID.
  • "amount" (int): Charge amount in minor units.
  • "currency" (string): Currency code.
  • "source_id" (string): Payment source (e.g., card token).
  • "description" (string): Optional description.

Returns:

A sorted-map capturing the charge request, destined for the connector via the factory and ConnectorHub.

mk-invoice-ninja-email-req

Sends an invoice email through Invoice Ninja.

Arguments:

• req (sorted-map):

  • "invoice_id" (string): ID of the invoice to email.

Returns:

A sorted-map capturing the email request, destined for the connector via the factory and ConnectorHub.

Connector Factories

A connector factory is a reusable structure that manages business objects (such as claims, payments, or tasks) participating in connector-based workflows. Each object defines how to process events, raise new events, and respond to third-party responses. The factory registers these objects with the platform so that they can be automatically invoked by ConnectorHub when responses are received.

Connector factories allow stateful, event-driven process automation where each object represents a unit of business logic with its own lifecycle.

Defining a Connector Factory

A connector factory must provide the following methods:

Each object created by the factory must itself implement:

Required Factory Operations

Required Object Operations

Example

In this example:

• mk-claims is a factory that produces and manages claim objects.
• Each claim object tracks the current state of a claim and raises connector events to external systems.
• register-connector-factory makes the factory known to the platform, enabling the phylum to raise events and route responses via ConnectorHub.

Raising Events from the Object

Within the object’s handle or init methods, events can be created using the helper functions and returned like so:

The returned "events" vector is automatically dispatched via ConnectorHub.

Triggering Object Methods

You can invoke object logic manually from within the phylum using the helper functions:

• create-claim: Creates and initializes a new claim.
• trigger-claim: Processes a connector response for an existing claim object.