ION Actions

ION Actions is a powerful tool that allows users to create, write, update, and delete rules governing the behavior of your manufacturing processes using GraphQL.

1. Introduction

Control workflows (e.g. when users can progress status), set conditions for data validation (e.g. require fields).

2. Turn rules on in your environment

First, rules must be enabled in your organization settings in order to use them.

Check that the rules are enabled with the below query:

{
  organization(id: 1) {
    id
    _etag
    settings {
      rules {
        enabled
      }
    }
  }
}

If they are not, enable them with this mutation:

mutation UpdateOrganization($input: UpdateOrganizationInput!) {
  updateOrganization(input: $input) {
    organization {
      settings {
        rules {
          enabled
          errorState
          errorStateMessage
        }
      }
    }
  }
}

With the following input variables (retrieve the etag from the first query):

{
  "input": {
    "id": 1,
    "etag": "<populate from first query>",
    "settings": {
      "rules": {
        "enabled": true
      }
    }
  }
}

3. Definition of ION Action Attributes

Here are the definitions of key ION Action attributes:

• Title: The title is a visual identifier for the ION Action, shown in toast notifications, and used for internal tracking and logging. It should briefly describe the purpose of the ION Action.

• Context: The context is a placeholder that contains the data used in the ION Action's code. It can include model attributes, user roles, issue details, or any other relevant data. It is represented as a JSON string in GraphQL input. An example of a context structure could be:

{
    'changes': {
        'entities': {},
        'issues': {}
    },
    'currentUser': {
        'email': '[e-mail]',
        'roles': ['user', 'admin'],
        'teams': []
    },
    'issue': {
        'approvalRequests': {},
        'approvals': {},
        'attributes': [
            {'key': 'Cause Code', 'value': None },
            {'key': 'Component Part', 'value': None },
            {'key': 'Defect Type', 'value': None },
            {'key': 'Department', 'value': None },
            {'key': 'Major Subsystem', 'value': None }
        ],
        'causeCondition': ""
    }
}

• Code: The code attribute contains the Python-based script that is executed when the ION Action is triggered. It specifies the conditions and actions of the ION Action. If the conditions are not met, a ValidationError is raised.

• ErrorState: The errorState attribute specifies the action to be taken if an unexpected error occurs during the execution of the ION Action. It can have two values:

  • "ALLOW": The ION Action execution is allowed to continue despite the error.

  • "BLOCK": The ION Action execution is blocked and an error is returned.

4. Creating an ION Action with GraphQL

Create an ION Action

mutation CreateRule($create_rule: CreateRuleInput!) {
  createRule(input: $create_rule) {
    rule {
      id
      enabled
      status
      title
      target
      eventType
      context
      code
      errorState
      _etag
    }
  }
}

Variables:

{
  "create_rule": {
    "enabled": true,
    "title": "This is the message that shows in the toast banner",
    "target": "ISSUE",
    "eventType": "UPDATE",
    "ruleType": "VALIDATION",
    "errorState": "ALLOW",
    "context": "specify the fields for the code to interpret",
    "code": "the python code which runs the logic - must be a single line! (chatGPT helps a lot here)"
  }
}

5. Updating an ION Action with GraphQL

Find the rule you seek to update You'll need the rule's id and _etag value for the next step

Query all rules

{
  rules{
    edges{
      node{
        id
        _etag
        title
        ruleType
        eventType
        target
        code
        context
        enabled
      }
    }
  }
}

Write the UpdateRule Mutation:

Write a mutation using the UpdateRule input type, specifying the rule's id, _etag and the updates you seek to make (generally the context, code, or enabled values).

mutation UpdateRule($update_rule: UpdateRuleInput!) {
  updateRule(input: $update_rule) {
    rule {
      id
      _etag
      enabled
      title
      context
      code
    }
  }
}

Query variables:

{
  "update_rule": {
    "id": from step 1,
    "etag": "copied from the step 1",
    "enabled": "true or false"
    "title": "You could modify the title here, or remove this line",
    "context": "overwrite the query, or remove this line",
    "code": "completely overwrite the code, or remove this line"
  }
}

Execute the Mutation: Run the mutation in the GraphQL Explorer to update the ION Action.

NOTE: Every time you update a rule, its _etag value will change, so you need to start from step 1 each time you update a rule.

Example - Video Walkthrough

Enabling/Disabling a rule through GraphQL

6. Deleting an ION Action with GraphQL

This isn't necessary as you can set enabled to "false", but to delete an existing ION Action:

1. Query the rule to retrieve its id and _etag value

2. Write the DeleteRule Mutation: Write a mutation using the DeleteRule mutation, specifying the ION Action id and _etag value.

3. Execute the Mutation: Run the mutation in the GraphQL Explorer to delete the ION Action.

Example: Deleting an ION Action

mutation DeleteRule($id: ID!, $etag: String!) {
  deleteRule(id: $id, etag: $etag) {
    id
  }
}

Query variables:

{
  "id": <ION_Action_id>,
  "etag": "<current_etag_value>"
}