Configure the Ignition Module

availability

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

This article explains how to configure the MaintainX® Ignition Module and troubleshoot your 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, select Settings, and under Organization Settings, select Integrations.

3. On the Integrations page, go to the Connectors tab.

4. Navigate to the Ignition Module tile, and select Connect. An Ignition Module dialog appears.

5. Select + Create New Instance.

6. Follow the steps to create a new instance until the Token appears.

7. Copy the Token and save it for later use.

8. Select Connect to finish provisioning the Ignition Module connector with the token you saved.

9. When the confirmation message appears, select Done to close the dialog.

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.

Add a Connector in the Ignition Gateway

To send tag data to MaintainX, you need to add a connector in the Ignition Gateway. The connector uses the access token you created to authenticate and route data to the correct MaintainX organization.

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

   • Navigate to Home > MaintainX, then select Configuration.

2. Select + New Connector and complete the required fields:

   • In the Connector Name field, name the connector according to your naming conventions.
   • Set the Connector Status to Enabled.
   • In the API Token field, paste the Token you generated when you created your connector token.

3. Select Save.

info

Each gateway supports up to 20 connectors, and each connector supports up to 6,000 tags. For the full list of limits, see Limitations.

Locate Your Ignition Tag Paths

Before MaintainX can monitor your Ignition tags, you need to provide their paths:

• Copy the Path value only (e.g., [default]Boiler1) to monitor all tags in the folder.
• Copy the Path value with the tag name appended (e.g., [default]Boiler1/Temperature) to monitor a specific tag.

Enter Your Ignition Tag Paths in the MaintainX Module

Tag paths tell MaintainX which Ignition tags to monitor. Each connector supports up to 300 distinct tag paths and a total of 6,000 tags. For more information, see Limitations.

If your Ignition tag tree uses UDP-based Data Transfer Protocol (UDT), MaintainX flattens UDT member paths into meter names by joining the UDT instance name and member with a slash (/). For nested UDTs (UDTs that include other UDTs as members), the separator stacks at each level. For example:

• A member tag inside a UDT instance: PumpA/Temperature
• A member tag inside a nested UDT: CompressorSkid01/MainMotor/RPM

When entering a tag path, treat each UDT instance like a folder. MaintainX subscribes to all of the leaf tags beneath it. You can also enter the path to a single member tag inside a UDT instance to subscribe to just that tag.

1. In the Ignition Gateway, go to the MaintainX Module Settings page and navigate to Config > Overview.

2. On the connector you set up earlier, select the (pencil) icon.

3. Select + New Path.

4. 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. Example: [default]Boiler1
     • To monitor all member tags in a UDT instance. Example: [default]EnterpriseData/UDTSim/Pump1

5. Select Save.

Map Tags to Meters

After you enter your Ignition tag paths in the MaintainX Module, use smart tag mapping to connect your tags to meters in MaintainX.

The smart tag mapping system uses AI to analyze data tags you make available through your organization's Ignition connectors. For each tag, the system suggests a meter name, a unit of measurement, and an asset to assign the meter to. Using the tag management tool, you can:

• View the Ignition tags that are available through your organization's Ignition connectors.
• Review MaintainX's suggestions for mapping tags to assets in your organization.
• Automatically create meters for your tags and associate them with the correct assets.

The tag mapping AI provides a confidence rating for each suggestion. You can edit any suggestion before creating the meter, and easily update mapped tags at any time.

For detailed instructions, see Smart Tag Mapping for OT Data.

info

The smart tag mapping system replaces the Auto Create Meters feature, which is no longer available. If you have existing OT connectors that connect to meters you configured using the Auto Create Meters feature, the smart tag mapping system will not affect them.

What Happens Next

Once configured, the MaintainX Ignition module:

• Subscribes to the tags you mapped.
• Automatically syncs your Ignition Tags with MaintainX Meters.
• Sends tag value changes to MaintainX as Meter readings.
• You can view and manage from the tag management tool.

Update the MaintainX Module

We recommend updating the MaintainX Module once a quarter to receive security patches and compatibility improvements. Updates can be installed at any time and do not affect your existing configuration or interrupt data flow to MaintainX.

1. Open the Ignition Gateway web UI.

2. Go to Platform > Modules.

3. Select Install or Upgrade Module.

4. Upload the .modl file you downloaded.

   For more information, see Download the MaintainX Ignition Module.

5. Select Install.

Manage Access Tokens

Regenerate the connector's access token whenever:

• You cannot retrieve the original token (it is only shown once) or the token has been exposed to anyone who is not a trusted administrator.
• An administrator with access to the token leaves your organization or you rotate credentials as part of a security review.
• The MaintainX UI or module logs show Invalid API Token, which indicates that the token was revoked.
• While troubleshooting connectivity issues, MaintainX Support instructs you to reissue the token.

warning

Running the connector with an invalid or revoked token stops data flow until you generate a new token and paste it into the module.

Revoke 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 a token:

1. Log into MaintainX as an Administrator.

2. From the sidebar, select Settings, and under Organization Settings, 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 the Token field shows Revoked.

MaintainX Module Statuses

The module's status shows whether it's healthy and exchanging data with MaintainX. To view it, open the Ignition Gateway and go to Platform > Modules.

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

MaintainX Connector Statuses

A connector's status shows whether it's healthy and exchanging data with MaintainX. To view it, open the Ignition Gateway and go to Home > MaintainX, then select Configuration.

Status	Description
Disabled	This connector is currently disabled.
Running	The connector is enabled and sending tag values to MaintainX.
Invalid API Token	The connector has an invalid API token.
Syncing	The module is syncing tags to monitor with MaintainX.
Sync Error	An error occurred while syncing tags.

MaintainX Redundancy Statuses

In a redundant Gateway setup, the module's redundancy status shows whether it's actively streaming tag data to MaintainX or holding in standby to take over if the Master Gateway fails. For more information, see Use Ignition Gateway Redundancy.

Status	Description
Active	The module is active and sending data to MaintainX.
Standby	The module is waiting for failover and not sending data to MaintainX.

Troubleshooting

If the MaintainX Ignition Module is not behaving as expected, use the steps below to identify and resolve common issues.

Not Seeing Data in MaintainX

• Check Status > System in the Ignition Gateway to verify that the module status is Running.
• Confirm the connector status is Running on the MaintainX Module settings page.
• Confirm your tag paths are valid and exist in Ignition.
• Double-check that the access token is correct and has not been revoked.
• Check Status > Logs in the Ignition Gateway for any MaintainX Module errors.

The MaintainX Ignition Module Is in a Sync Error State

The module shows Sync Error when one or more connectors have a tag synchronization issue. To resolve the error, identify the affected connector and follow the instructions in The Connector in the Module is in a Sync Error State.

The Connector in the Module Is in a Sync Error State

A connector displays Sync Error when one or more configured tag paths are invalid or not found in Ignition. Valid tags will continue to be monitored, but invalid ones are not added to MaintainX.

To identify the invalid tags, check the Ignition Gateway logs at Status > Logs. Each invalid tag path will be logged with an error message.

The MaintainX Ignition 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 restart the module:

1. In the Ignition Gateway, go to the Platform > Modules page
2. Locate the MaintainX Module and select Restart.

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 us investigate the issue.

The Connector is Unable to Reach the MaintainX Service

If the connector can't reach the MaintainX service, it usually means your Ignition Gateway can't reach MaintainX. Common causes include:

• A firewall rule blocking outbound traffic.
• The Gateway not using the proxy server configured in your organization.

For the required network settings, see Secure Outbound Communication.

To test whether your Ignition Gateway can reach MaintainX:

1. Open the Ignition Designer for your Gateway.

2. From the top menu, select Tools > Script Console.

3. Paste the following script and run it:

   from java.lang import Exception as JavaException
   
   url = "https://agent.maintainx.com/"
   
   try:
       client = system.net.httpClient()
       response = client.get(url)
       status = response.getStatusCode()
   
       if status >= 200 and status < 500:
           print "MaintainX is reachable."
       else:
           print "MaintainX is unreachable."
   
   except JavaException as e:
       print "MaintainX is unreachable."
       print str(e)

4. If the output shows MaintainX is unreachable, your Gateway cannot connect to MaintainX. Review the network settings with your IT administrator.

Still Stuck?

Contact MaintainX Support. Make sure to download your Ignition logs and share them with us to help us investigate the issue.