Skip to main content

Core Concepts

Every MSPintegrations product uses the same mental model. Once you understand this model, switching between Email Processing, Scheduled Tasks, Forms, and Workflows is mostly a matter of where the trigger comes from and what data arrives with it.

The Processing Model​

Every run in MSPintegrations follows the same shape:

Trigger
  └── Rule(s) or Task
        └── Action Step(s)
              └── Variables and History

Trigger​

A trigger is the event that starts a run. Each product has its own trigger type:

ProductTrigger
Email ProcessingAn inbound email arrives at a hosted mailbox, or is pulled from a remote mailbox
Scheduled TasksA schedule tick fires based on a cron-style cadence
FormsA visitor submits a public form
WorkflowsA PSA event (ticket change, asset change, and so on) is delivered to your account

The trigger determines what data is available at the start of the run. For example, an Email Processing run has the full inbound message on the email namespace; a scheduled task has no payload and starts with nothing but meta.

Rule or Task​

A rule (or task, in Scheduled Tasks) is a named container for one or more action steps. A product can have multiple rules attached to the same trigger; rules are evaluated top-to-bottom in order, and every rule that matches fires unless a Stop action halts processing.

Each rule has an optional Expression that controls whether it fires at all. If the expression is empty, the rule fires for every run. If an expression is set, the rule only fires when the expression evaluates to true.

Learn more → Expression Builder

Action Steps​

Inside each rule, action steps execute top-to-bottom in order. Each step can also have its own optional expression ("only run if..."), so you can make individual steps conditional.

Actions are drawn from the shared Actions library. The same action library is available in Email Processing, Scheduled Tasks, Forms, Workflows, and Macros, though a few email-specific actions (like "Stop All Email Processing") are scoped to email triggers.

The output of each step is stored in a named variable and is available to all subsequent steps in the same rule. This is what allows you to build multi-step workflows: look something up in one step and use the result in the next.

How Rules and Steps Stop​

By default, every matching rule fires, and every step within a rule runs. To stop processing early, use a Stop action:

Stop actionEffect
Stop Processing This RuleStops remaining steps in the current rule. Other matching rules continue.
Stop Processing This Message CompletelyHard stop. No further rules or steps run for this trigger.

Most workflows end with a Stop action. For example, after creating a ticket, you stop so that no further rules accidentally create a second ticket for the same trigger.

The most common mistake

Forgetting to add a Stop action. Without it, every matching rule fires. In a standard support mailbox with an Update rule and a Create rule, if the Update rule succeeds but does not stop, the Create rule will also run and create a second ticket.

Variables and Data Flow​

Every action step can store its results in a named variable using the Store results in variable field. The variable is then accessible in all subsequent steps using {{custom.variableName}}.

Variables are organized into namespaces. Some namespaces are system-provided (populated by the system before your rules run); others are user-populated (you write into them during your rules).

NamespacePopulated byAvailable in
emailSystemEmail Processing only
inputSystem (from caller or form)Macros, Forms
metaSystemAll products (properties vary)
customYouAll products
globalYouEmail Processing only (persists across rule sets)
outputYouMacros only

Full reference → Variable Namespaces

Chaining steps​

The output of each step accumulates as the rule processes. Step 3 can reference variables set by steps 1 and 2. Step 5 can reference all of them. Nothing is lost as the rule progresses, so you can always reach back to an earlier result.

The { shortcut​

In any text field inside an action step, type { to open the variable autocomplete menu. Every available variable (system namespaces, metadata, and anything stored in previous steps) appears in the list.

Inspecting variables in the processing log​

Every run appears in History with a complete execution log. For each step, you can see the exact state of every custom.* (and other namespace) variable before and after the step runs. This makes it straightforward to understand exactly what data is available at each point in the workflow.

Workflow Actions vs. API Call Actions​

Every PSA integration in MSPintegrations provides two categories of actions.

Workflow actions​

Workflow actions contain built-in business logic and perform multiple API calls behind the scenes. They accept high-level inputs (like an email address) and handle the full lookup-and-create process automatically.

Examples:

  • Create Autotask Ticket: searches for the sender as a Contact, finds the Account, creates the ticket, and attaches files.
  • Update Existing Autotask Ticket: scans the email for a ticket number, finds the ticket, adds a note, and updates the status.
  • Create Autotask Ticket (by Configuration Item): extracts a device identifier from the email, finds the matching CI, and creates the ticket under the CI's account.

Use workflow actions when you are processing standard incoming email and want MSPintegrations to handle the matching and routing logic for you.

API call actions​

API call actions make a single, direct call to the PSA API. You provide all the parameters. No additional lookup logic is included.

Examples:

  • API: Create an Object: creates any PSA entity with the exact fields you specify.
  • API: Update an Object: updates any entity by ID.
  • API: Query for One Object: searches the PSA and returns the top result.
  • API: Query for Object(s): searches the PSA and returns an array of results.

Use API call actions when you already have all the required IDs (from a previous step), when you need to work with entity types not covered by workflow actions, or when you are building custom multi-step logic.

Choosing between them: Start with workflow actions for standard support email processing. For more custom workflows (monitoring alerts, scheduled tasks, multi-step automations), use API call actions chained together.

Full comparison → Workflow Actions vs. Single API Call Actions

The Processing Log​

Every trigger that arrives is recorded in History. Each entry has a full execution log showing:

  • Which rules matched and in what order
  • Every action step that ran, with its configuration at the time it ran
  • Every API call made to your PSA or other systems, including the payload sent and the response received
  • The state of all custom.* and other namespace variables at each step
  • Any errors or exceptions, including the exact error message from the upstream API

This log is the primary tool for understanding why something worked or did not work. When troubleshooting, open the history entry, expand the steps, and read what happened.

Replay: The Play button on any history entry re-processes the same trigger through your current rule configuration. You do not need to send a new test email, wait for the next schedule tick, or resubmit a form. Just replay the existing entry.

Dedicated Triggers per Integration​

A key principle for keeping your workflows maintainable: use a dedicated trigger for each third-party tool or use case.

In Email Processing, this means dedicated mailboxes:

The same principle applies to Scheduled Tasks (one task per purpose, not a mega-task with many conditions), Forms (one form per intake reason), and Workflows (narrow expressions per rule).

This makes each trigger's rules simpler, makes History easier to read, and means a problem in one workflow cannot interfere with another.

What's Next​