# ION Actions Best Practices

### 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):**

```python
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):**

```python
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://manual-v2.firstresonance.io/os/ion-actions/ion-actions-best-practices.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.