Ignition Module - Setup and Configuration Guide

Currently in beta testing phase

Important information to know during the beta testing phase:

• The module currently uses a self-signed certificate.
• The module currently supports non-complex tags only (integer, float, string, text, datetime, boolean). It does not support UDT or array types. If a folder path is provided as input, invalid tags will be ignored.
• This beta version has a temporary limit of 1000 tags to protect performance. This is not the final limit of the module.

availability

Platform:	WebMobile
Plan Type:	BasicEssentialPremiumEnterprise
User Type:	RequesterFull UserAdministrator

This article explains how to set up the MaintainX Ignition Module to stream real-time tag data into MaintainX. This powers condition-based maintenance, asset tracking, asset status changes, usage-based maintenance, insights, and alerts.

Ignition Connector Overview

Requirements

info

We support Ignition versions greater than 8.1.3 but within the 8.1.x series.

Ignition Gateway

• Access to your Ignition Gateway with a user having an Administrator role. The user must have the following permissions:
  • Gateway Config Permissions
  • Gateway Status Permissions
• Tags configured in Ignition

MaintainX Account

• Integration Connectors permissions. Please contact your organization's Administrator to request access to the Integration Connectors feature.

Installation

Download the MaintainX Ignition Module

To set up the MaintainX Ignition Module, you need to download the .modl file. .modl files are used to install third party modules in Ignition.

1. In MaintainX, go to Settings > Integrations > Connectors
2. Under Available Connectors, locate Ignition Module
3. Click Download to get the latest version of the .modl file

Install the MaintainX Module in Ignition

Installing the module will load the MaintainX Module on your Ignition Gateway allowing it to synchronize data with MaintainX.

1. Open the Ignition Gateway web UI
2. Go to Config > Modules
3. Scroll down and select Install or Upgrade a Module
4. Upload the .modl file you downloaded
5. Read and accept the license agreement
6. Click Install Module

Configuration

Create Your Connector Instance and Token

To configure the MaintainX Ignition Module, you need an access token. The token authenticates the MaintainX Ignition Module with the MaintainX platform.

danger

It's important to keep your token secure. Do not share it with unauthorized users.

1. Log into MaintainX as an Administrator.
2. From the sidebar, open the Settings menu. From the Organization Settings section, select Integrations.
3. On the Integrations page, go to the Connectors tab.
4. Navigate to the Ignition Module tile, and select Create New Instance.
5. Select if you want to Auto Create Meters. This will automatically create meters in MaintainX for new tags discovered by the connector.
   • To learn more about auto creating meters, see Auto Create Meters.
6. Follow the steps to create a new instance until the Token appears.
7. Copy the Token and save it for later use.

info

The Token is only displayed once when you create the Ignition Module connector. If you lose the token for an Ignition Module instance, you can revoke it and create a new one. See Revoke and Regenerate an Ignition Module Access Token.

Enter your Token to the MaintainX Ignition Module

1. Go to the MaintainX Module Settings page in the Ignition Gateway:
   • Navigate to Config > Overview
   • Under the Connections section, click Configure the MaintainX Module
2. Enable the Module and paste the token on the MaintainX Module Settings page:
   • Toggle the Integration Status to Enabled
   • Paste the Connector Token we generated earlier in the API Token field

Locate Your Ignition Tag Paths

1. In the Ignition Gateway:
   • Navigate to Status > Tags
2. Browse to the tags you want to monitor by:
   • Clicking Browse on a specific folder to see other folders and tags underneath it
   • Clicking Details on a specific tag
   • Once you've found the tag you want to monitor and navigated to its details page:
     • Copy the Path value only (e.g., default/Boiler1) if you want to monitor all the tags in the folder
     • Copy the Path value with the tag name appended (e.g., default/Boiler1/Temperature) if you want to monitor the specific tag

Enter Your Ignition Tag Paths in the MaintainX Module

1. Go to the MaintainX Module Settings page in the Ignition Gateway:

   • Navigate to Config > Overview
   • Under the Connections section, click Configure the MaintainX Module

2. Enter the tag paths you want to monitor in the Tag Paths field:

   • Add the tag paths:
     • For a specific tag example: default/Boiler1/Temperature
     • To monitor all tags in a folder, for example: default/Boiler1

3. Click Save Changes

Update the MaintainX Module

note

Updating the module will not affect your existing configuration. It will only update the module to the latest version.

1. Open the Ignition Gateway web UI
2. Go to Config > Modules
3. Scroll down and select Install or Upgrade a Module
4. Upload the .modl file you downloaded
5. Click Install

Revoke and Regenerate an Ignition Module Access Token

The access token for an Ignition Module connector is only displayed once, when you first create it. If you lose the token, you can revoke it and generate a new one.

To revoke and regenerate a token:

1. Log into MaintainX as an Administrator.
2. From the sidebar, open the Settings menu. From the Organization Settings section, select Integrations.
3. On the Integrations page, go to the Connectors tab.
4. Navigate to the Ignition Module connector, and select Manage.
5. In the Ignition Module dialog, go to the Instances list and select the instance whose token you want to revoke.
6. In the Manage Instance dialog, select Revoke Token.

The instance's Status changes to Disconnected, and in the Token field shows Revoked.

7. Refer to the section on generating new token and applying the token

What Happens Next

Once configured, the MaintainX Ignition Module:

• Automatically sync your Ignition Tags with MaintainX Sensors
• Subscribes to the tags you specified
• Sends tag value changes to MaintainX as Sensor readings
• You can view and manage these under your connector instance in MaintainX under Settings > Integrations > Connectors > Ignition Module

Auto Create Meters

Instead of manually creating meters, you can enable an option to automatically create them when a new Ignition tag is discovered via a connector. The meter name will reflect the path of the tag in Ignition.

To use auto create meters:

1. Log into MaintainX as an Administrator.
2. From the sidebar, open the Settings menu. From the Organization Settings section, select Integrations.
3. On the Integrations page, go to the Connectors tab.
4. Navigate to the Ignition module tile, and select Connect.
5. Toggle Auto Create Meters on.
6. Follow the steps to create a new Ignition instance and token.

When a new tag is discovered, meters will be created automatically, using data reported by the tag.

MaintainX Module Statuses

Status	Description
Disabled	The module is currently disabled.
Initializing	The module is initializing its connection with MaintainX.
Syncing	The module is syncing tags to monitor with MaintainX.
Sync Error	An error occured while syncing tags.
Running	The module is enabled and sending tag values to MaintainX.
Shutting Down	The module is shutting down.
Fatal Error	The module is in a fatal error state.

Troubleshooting

Not seeing data in MaintainX?

• Validate the module is running on your Ignition Gateway:
  • Go to the Status page and check the System section. Check if the MaintainX status is set to running.
• Confirm your tag paths are valid and exist in Ignition
• Double-check that the token is correct and not expired
• Check the Logs of the MaintainX Module in Status > Logs page in Ignition for any errors

Still stuck? Contact support@getmaintainx.com. Make sure to download your logs and share them with us to help investigating the issue.

FAQs

Can I monitor multiple tags?

Yes - enter multiple tag paths, or monitor entire folders.

Are tag updates sent on a schedule?

Yes and no - the module only sends data when a tag value changes, reducing bandwidth and noise. It also supports batching of multiple updates to reduce the number of messages sent. Once it has enough data to complete a batch, it will send the data without waiting for the next update.

What is the tag filtering strategy?

We apply a combination of Time-Based Hysteresis and Token Bucket filters to manage tag updates efficiently.

1. Time-Based Hysteresis:

   • Filters out minor changes if the new value is within 1% of the last accepted value.
   • Still allows an update if too much time has passed (1 second) since the last accepted value.
   • Prevents jitter, while ensuring periodic updates.

   Time-Based Hysteresis Algorithm Example:

   Time (ms)	New Value	IsFiltered?
   t = 0	100	✅ No
   t = 100	100.5	❌ Yes
   t = 1000	100.5	✅ No

2. Token Bucket

   • Allows short bursts of 5 updates.
   • Then enforces a steady rate of 1 update per second.
   • This ensures that the system can handle spikes in data then smooths out the flow of updates.

   Token Bucket Algorithm Example:

   Time (ms)	Tokens Left	Bucket refill Triggered	IsFiltered?
   t = init	5	N/A	N/A
   t = 0	4	No	✅ No
   t = 100	3	No	✅ No
   t = 200	2	No	✅ No
   t = 300	1	No	✅ No
   t = 400	0	No	✅ No
   t = 500	0	No	❌ Yes
   t = 1000	0 → 1 → 0 (refill to 1, then consume 1)	Yes (1 token)	✅ No
   t = 1100	0	No	❌ Yes
   t = 5000	0 → 5 → 4 (refill to 5, then consume 1)	Yes (5 tokens)	✅ No

How are Sensors named in MaintainX?

MaintainX derives sensor names from the tag path:

Ignition Tag: default/Boiler1/Temperature
MaintainX Sensor: Boiler1_Temperature

What if I add a new tag under a folder that is already being monitored?

Tags added under a folder that is already being monitored will be automatically discovered and added to MaintainX. A rescan of the folder is automatically triggered every hour to ensure new tags are picked up.

If you want to force a rescan, you can do so by going to the MaintainX Module Settings page in the Ignition Gateway and clicking Save changes.

What to do if the MaintainX Module is in a Sync Error state?

If the MaintainX Module is in a Sync Error state, some of the provided tags are invalid or not found in Ignition. All valid tags will still be monitored, but the invalid ones will not be added to MaintainX.

You can check the logs in the Ignition Gateway to see which tags are invalid. The logs will contain an error message with the tag path that caused the error.

What are the supported tag types?

Currently, the module supports the following tag types: Integer, Float, String, Text, Datetime, and Boolean.

Any complex tags such as UDTs or arrays are not supported at this time.

What to do if the MaintainX Module is in a Fatal Error state?

If the MaintainX Module is in a Fatal Error state, it means that the module encountered an unrecoverable error and cannot continue running. You can restart the module to try to recover from the error. To do this, go to the Config > Modules page in the Ignition Gateway and select Restart for the MaintainX Module.

If the error persists, you can contact our support team at support@getmaintainx.com. Make sure to download your logs and share them with us to help investigating the issue.

Learn More

To learn more about how to setup the Ignition module, see the following: