Skip to navigation
Workflows

Workflow triggers

A workflow trigger is the record Solvimon creates each time a workflow matches an event. Triggers are how you prove a workflow ran, and how you run one on demand.

How it works

Workflows and actions are configuration and live in the Configuration API. Triggers are transactional records and live in the Transaction API. Each trigger names the workflow that ran, the customer it ran for, and a type-specific block pointing at the invoice, payment, subscription or wallet involved.

Trigger typeCreated by
EVENTSolvimon, from a lifecycle event that matched an active workflow.
MANUALYou, through the API or Desk, usually to test or to re-send.

The type-specific block matches the workflow’s type:

Workflow typeBlockKey field
INVOICEinvoiceinvoice_id
PAYMENTpaymentpayment_id
PRICING_PLAN_SUBSCRIPTIONpricing_plan_subscriptionpricing_plan_subscription_id
WALLETwalletwallet_id, wallet_type_id
USAGEusagemeter_value_calculation_id

A USAGE workflow produces an EVENT trigger when a customer’s consumption crosses a threshold of their usage limit, once per threshold per billing period. Its usage.event block names the customer that crossed, the threshold and its threshold_type, and the resolved limit the threshold came from.

Implementation

Trigger a workflow manually

Creating a trigger runs the workflow’s active actions immediately. This is the fastest way to verify an email before you widen a workflow’s customer scope:

Manually trigger an invoice workflow
curl -X POST https://test.api.solvimon.com/v1/workflow-triggers \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "MANUAL",
    "workflow_id": "wf_7KcQm1RtbXeUvL2NpHZ4S",
    "customer_id": "cust_AbD3DqausjOYiMNDZY11F",
    "invoice": {
      "invoice_id": "inv_6WdKp3ZqtYcRnB8MjXH2V"
    }
  }'
Response
{
  "object_type": "WORKFLOW_TRIGGER",
  "id": "wft_8LmPc5XrvNbTeK4QjYZ9H",
  "type": "MANUAL",
  "workflow_id": "wf_7KcQm1RtbXeUvL2NpHZ4S",
  "customer_id": "cust_AbD3DqausjOYiMNDZY11F",
  "invoice": {
    "invoice_id": "inv_6WdKp3ZqtYcRnB8MjXH2V"
  }
}

For a payment workflow, swap the block for "payment": { "payment_id": "pay_..." }. Wallet triggers are EVENT-only in practice, since the balance condition is evaluated by Solvimon.

Read the balance a wallet trigger fired on

A wallet trigger records the balance that crossed the threshold, so you can answer “how low was it?” without reconstructing the wallet at that moment. wallet_balance.open_balance is the open balance when the execution was created and wallet_balance.threshold is the threshold configured on the workflow it crossed. Both are stated in the unit the wallet’s ledger is denominated in, so each is a container carrying credits and amount of which exactly one is populated:

A wallet trigger denominated in credits
{
  "object_type": "WORKFLOW_TRIGGER",
  "id": "wft_8LmPc5XrvNbTeK4QjYZ9H",
  "type": "EVENT",
  "wallet": {
    "wallet_id": "wall_3TnRk9YbvQdMeF6WpXJ2L",
    "wallet_type_id": "wtyp_5RmXe2QbtKfYuA9DcNH3P",
    "wallet_reference": "prepaid-credits",
    "event": { "variant": "WALLET_BALANCE" },
    "wallet_balance": {
      "open_balance": { "credits": { "quantity": "40", "credit_type_id": "ctyp_2PnBx7VdtRgLmE4WcQJ8K" } },
      "threshold": { "credits": { "quantity": "100", "credit_type_id": "ctyp_2PnBx7VdtRgLmE4WcQJ8K" } }
    }
  }
}

A wallet type funded with an amount keeps its ledger in a currency, and its trigger reports amount in the same two places instead:

The same block for a wallet denominated in a currency
"wallet_balance": {
  "open_balance": { "amount": { "quantity": "40.50", "currency": "EUR" } },
  "threshold": { "amount": { "quantity": "100.00", "currency": "EUR" } }
}

Before release 1.186 both fields were a bare credits object, as in "open_balance": { "quantity": "40", "credit_type_id": "ctyp_..." }. A consumer reading open_balance.quantity has to move to open_balance.credits.quantity. The send-email action is unaffected: its wallet_balance and wallet_balance_threshold variables are rendered figures either way, and credit_unit_name carries the currency code when the wallet is denominated in an amount.

Find the triggers for a resource

Use search when you are answering “did this invoice get its email?”. POST /v1/workflow-triggers/search takes the platform’s standard filter_fields structure, where each entry names a field on the trigger:

Search triggers for one customer
curl -X POST https://test.api.solvimon.com/v1/workflow-triggers/search \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "filter_fields": [
      { "name": "workflow_id", "value": "wf_7KcQm1RtbXeUvL2NpHZ4S" },
      { "name": "customer_id", "value": "cust_AbD3DqausjOYiMNDZY11F" }
    ]
  }'

Use values instead of value to match a list, and combine with the limit, page and order_by query parameters to page through the results.

An empty result means the workflow never matched. Triggers carry no result of their own, so if a trigger exists but no email went out, check the execution result on the workflow’s page in Desk; see Monitoring and audit.

Via Desk

Triggers appear on the workflow’s detail page and on the invoice, payment or subscription itself, so you can start from either end of the question.

Troubleshooting

Work through this in order when an email did not arrive:

  1. Is the workflow ACTIVE? A DRAFT or INACTIVE workflow never produces triggers.
  2. Is the customer in scope? Check customer_ids on the workflow.
  3. Does a trigger exist for the invoice or payment? If not, the event never matched the variant.
  4. Is the action ACTIVE? A trigger runs only the workflow’s active actions.
  5. If a trigger exists and the action is active, open the workflow in Desk and read the execution result and error message.
  6. If the execution succeeded, the problem is downstream. Check the email provider’s own logs.

API reference