ION Actions Best Practices | ION Factory OS 2.0

[This manual has been deprecated.

Read the new manual](https://docs.firstresonance.io/)

For the complete documentation index, see llms.txt. This page is also available as Markdown.

Overview

The Ion Actions engine enables powerful automation and business logic within ION by allowing users to define rules that respond to object events such as Work Order updates, Issue creation, or Part changes. Rules are written in Python and executed dynamically based on event triggers.

This document outlines best practices for writing, testing, and managing Ion Action rules. Following these guidelines will help ensure reliable behavior, maintainability, and consistency across your automation logic.

1. Rule Execution and Behavior

Chained Execution

When multiple rules target the same object and event type (for example, Issues Update), they are chained together and executed sequentially. The execution order is determined by internal rule IDs, which are not user-controlled and may vary. Because of this, rule order should not be relied upon.

Avoid Top-Level return Statements

If a return statement is used at the top level of a rule, the Ion Actions engine will stop executing that rule and all subsequent rules in the chain. This can lead to unintended skipping of logic defined in other rules that share the same event target.

Example (Problematic):

if issue.status == "Closed":
    return  # ❌ This stops execution of all following rules for this event

Use Nested Returns Instead

To safely control flow within your rule without affecting other chained rules, scope your return statements within functions or conditionals. This allows the Ion engine to continue executing subsequent rules.

Example (Recommended):

if issue.status == "Closed":
    def handle_closed_issue():
        # Logic specific to closed issues
        return "Handled closed issue"  # ✅ Nested return affects only this function

handle_closed_issue()

Additional Recommendations

• Avoid relying on rule execution order. Each rule should be self-contained and independent.

• Use variables for decision-making. Employ local variables or persistent storage to manage conditional logic instead of using return to control flow.

• Test extensively. Validate behavior across multiple chained rules to ensure predictable outcomes.

2. Rule Development and Deployment

Version Control and Collaboration

• As larger organizations scale and have internal software teams we see success in storing Ion Action rules in a version-controlled repository (e.g., GitHub or similar).

• Connect your repository to the Ion API to enable direct, auditable deployment of rules.

• Use pull requests or merge reviews to facilitate peer review, ensuring code quality and alignment with operational standards.

• This approach allows engineers and operations teams to collaborate within familiar development workflows.

Deployment Process

• Maintain staging and production environments for rule deployment.

• Test rules thoroughly in staging before promoting them to production.

• Use automated or semi-automated deployment pipelines to push rules, reducing manual copying and minimizing risk.

• Clearly document rule changes and maintain an internal changelog for traceability.

Governance and Documentation

• Treat Ion as the execution platform for rule logic, while managing source, versioning, and review externally at scale.

• Implement a code review process before merging changes to production.

• Maintain a clear audit trail for compliance and troubleshooting.