Skip to content

Tracker State Trigger

Overview

The Tracker State trigger invokes a Service or connected workflow nodes whenever a new state is added to a Tracker document and that state matches the trigger's configured document type, state type, and state name conditions. It is transport-agnostic—it only detects a matching Tracker state event and invokes the configured handler. The invoked Service or workflow decides what to do next, using existing Martini capabilities such as an HTTP request, an email-sending agent, or custom logic.

What You Will Learn

  • What the Tracker State trigger is and how it matches Tracker document state events
  • How to configure the trigger's Document Type, State Type(s), and State Name / Pattern fields
  • Which parameters are available to the invoked Service or workflow

When To Use This

Use this when you need to:

  • Send a notification (for example, an email) when an ERROR state is logged against a document
  • Call an external webhook or HTTP endpoint through a Service or workflow when a specific state occurs
  • Branch into custom business logic when a WARNING or other state appears on a document
  • Automate a response to a Tracker document reaching a particular state, without hardcoding notification-channel logic into Tracker itself

Prerequisites

  • A Martini Package containing the Tracker document type you want to monitor
  • Familiarity with Martini Tracker Functions and how document states are added
  • Martini Runtime v3.x and Martini Designer v1.8.x or later

Usage in Workflows

To learn how to setup and use the Tracker State trigger in workflows, see Martini Workflows Trigger Nodes

Usage in Services

To learn how to setup and use the Tracker State trigger in services, see Invoking Services via a Trigger

Properties

General Configuration

Property Default Description
Name (required) The name of the trigger. Not applicable in Workflow node mode, where the node is identified within the workflow instead.
Service (required, Service Trigger mode only) The Service to invoke when a new state matches the trigger configuration. Not present, and not required, in Workflow node mode—the connected workflow nodes act as the handler instead.
Auto Start true Whether the trigger should automatically activate upon package startup. Applies to Service Trigger mode only.

Tracker State-Specific Configuration

These fields define which Tracker state events the trigger matches, and are configured the same way in both Service Trigger mode and Workflow node mode.

Property Default Description
Document Type (required) The Tracker document type whose newly added states should be monitored by this trigger, using the same document type selection pattern as other Tracker-related trigger forms and nodes.
State Type(s) (none) Optional multi-select filter—ERROR, SUCCESS, WARNING, INFO—for which state types should invoke the handler. Leave empty to match any state type.
State Name Match Mode (none) Exact or Pattern. Chooses how the state name filter is matched. Required only if State Name / Pattern is set; does not block saving when State Name / Pattern is left empty.
State Name / Pattern (none) An optional exact state name or pattern to match when a new state is added. If left empty, the trigger can match any state name that satisfies the other conditions.

Matching behavior:

  • If a state type filter is configured, the new state must match one of the selected types.
  • If a state name filter is configured, the new state name must match according to the selected match mode (Exact or Pattern).
  • If no state name filter is configured, any state name that satisfies the other conditions matches.
  • Matching is deterministic and does not produce duplicate trigger executions for the same state and trigger combination.
  • Multiple Tracker State triggers can match the same state event; each configured handler is invoked independently.
  • If the invoked handler fails, the original Tracker state write still succeeds; the handler failure is logged but does not fail state persistence.

Note: The Tracker State trigger has its own icon in Martini Designer, distinct from other trigger types.

Parameters

When the trigger matches, the invoked Service or connected workflow nodes receive the following parameters:

Name Type Description
parameters java.util.Map A map containing all the trigger-specific variables. (advanced)
martiniPackage io.toro.martini.ipackage.MartiniPackage The Martini Package that contains this trigger. (advanced)
properties java.util.Map A map containing all the properties configured for this trigger. (advanced)
document io.toro.martini.tracker.Document The Tracker document whose new state matched this trigger.
state io.toro.martini.tracker.Document.State The Tracker document state that was added and matched this trigger.
stateId java.lang.String The id of the Tracker document state that was added.
stateName java.lang.String The name of the Tracker document state that was added.
stateType java.lang.String The type of the Tracker document state that was added, expressed as the state type key (for example, ERROR).
timestamp long The timestamp of the trigger event, expressed in milliseconds.

These parameters are also exposed through Designer's invocable properties, for both Service Trigger mode (available to the selected Service) and Workflow node mode (available to the downstream connected workflow nodes).

Example

Consider a Shipment Tracking document type that is updated as a shipment moves through processing. One workflow logs document states—including a WARNING state when a shipment is delayed—and a second, independent workflow reacts to that WARNING state using a Tracker State Trigger node.

Workflow 1: Logging Shipment States

This workflow processes a shipment and adds a WARNING state to its Shipment Tracking document if the shipment is delayed:

flowchart LR
    A[Start Trigger] --> B[Invoke Service: processShipment]
    B --> C{Delayed?}
    C -- true --> D["Function: addDocumentState('Delayed', 'WARNING')"]
    C -- false --> E["Function: addDocumentState('On Time', 'SUCCESS')"]

Workflow 2: Reacting to the Warning State

This workflow uses a Tracker State Trigger node, configured with Document Type set to Shipment Tracking and WARNING selected under State Type(s), as its entry point. When Workflow 1 logs a matching WARNING state, this workflow starts and notifies the shipping team:

flowchart LR
    A["Tracker State Trigger\n(Document Type: Shipment Tracking, State Type: WARNING)"] --> B[Map: stateName, document]
    B --> C[Invoke Service: notifyShippingTeam]

The Map node reads the stateName and document parameters from the trigger, and the connected Service sends a notification using whatever channel it implements (for example, email or an HTTP request to a messaging system).

Expected result: Whenever a WARNING state is added to a Shipment Tracking document—by Workflow 1 or by any other process—Workflow 2 starts automatically and can access the document, state, stateName, stateType, and other parameters listed above.

Troubleshooting

Problem Detection Cause Fix
Trigger does not fire No Service or workflow execution after a matching state is logged Document Type doesn't match the document type used when the state was added, or the State Type(s) filter excludes the logged state type Confirm Document Type matches exactly and that State Type(s) (if configured) includes the state type being logged
State Name / Pattern does not match Trigger never fires despite matching document type and state type State Name Match Mode doesn't correspond to how State Name / Pattern is defined Set State Name Match Mode to Exact for a literal state name, or Pattern for a pattern-based match
Handler does not appear to run Trigger matches but no Service or workflow logic executes Service not selected (Service Trigger mode), or no workflow nodes connected to the trigger node (Workflow node mode) Select a Service, or connect workflow nodes to the trigger node, then save and start the trigger
Tracker state is missing even though the handler failed Document state was logged, but the expected notification or downstream action didn't occur This is expected behavior—the original Tracker state write always succeeds even if the invoked handler fails Check the handler's own logs; the handler failure is logged separately and does not block state persistence

Helpful Resources