Configure IO Maps

You can create, edit or delete IO Maps from the IO Maps pane of the viewing area, which you can access in either of the following ways:

  • Choose Configuration ‣ External Data ‣ IO Maps from the menu.

  • In the Navigation sidebar, go to Settings ‣ IO Maps.

Prerequisites

Before you can create IO Maps, you must set up data connectors as described in Configure Data Connectors. For each data connector protocol created, a separate tab gets visible on the IO Maps pane, from which you can configure the related IO Maps as described below.

Create IO Maps

  1. On the IO Maps pane, select the tab corresponding to the data connector protocol for which you want to create the IO Map. IO Maps are organised into tabs according to the the protocol type of their associated data connector, such as CSV or Excel.

  2. Click add Add on the toolbar.

  3. In the Add IO Map dialog, follow these three steps to specify the field values, as detailed below:

    Step 1: Configure general IO Mapping parameters, including settings for raw and filtered tags.

    Field

    Description

    Required

    Connection Id

    Select the Data Connector that you want to associate with the IO mapping.

    Yes

    Enabled

    Select one of the following options:

    • True: The IO Map record will be processed according to the read/write time specified.

    • False: This record will be ignored during the read/write process.

    Yes

    Tag Alias

    Enter an alias name for the mapping. This is just for categorisation and won’t be used in any service or logic.

    No

    Description

    You can provide additional information about the IO Mapping to help identify its purpose or details.

    No

    IO Type Id

    Choose the type of operation from the following options:

    • Input: The value will be read/ingested into WIP

    • Output: The value will be sent from WIP to the external data source.

    Yes

    Filter Data Type

    Select the data type of the WIP tag for the Filtered Tag.

    When using a filtered tag.

    Raw Tag

    Enter the WIP tag name that will hold values from the external data source. No modifications such as filters or limits will be applied to this value. If you select None, the raw process value without filtering will be recorded, but you must set a Filtered Tag.

    Yes

    Filter Tag

    Enter the WIP tag that will receive the processed/filtered value if you want to apply modifications or filters to the value being read from the external data source. Examples include applying a gain/offset, specifying an Override value, applying limits, or holding the last good value if a bad or out-of-range value is received.

    Yes

    External Unit Type

    Select the unit of measure type for the external tag.

    Yes

    Raw Tag Data Type

    Choose the data type of the Raw WIP tag.

    Yes

    External Unit

    Select the actual unit of measure for the external data. A list of available units will be provided based on the selected External Unit Type. During a read operation, WIP will read the External Unit and convert it to the Unit Type base units of measure before storing the data. Similar conversions are performed during writes/outputs, where WIP converts to the proper external unit type before sending an output value.

    Yes

    External Id

    Enter the unique identifier needed to locate/request a value in the external data source. For example, when using OPC DA connectors, this would be the OPC Tag name. This links the WIP Raw/Filtered tag to the external data source.

    Yes

    Step 2: Set parameters for processing IO Map records, including filter configurations if needed.

    Field

    Description

    Required

    Protocol Parameter 1/2/3

    You can enter additional parameters specific to the data connector protocol. These parameters may be necessary to uniquely identify the information to be retrieved from the data source. For detailed information on these fields, refer to the data connector protocols.

    No

    Action Id

    Select the action to take when the value (after gain/offset has been applied) is not within the specified range. The selected value will determine the value of the Filtered Tag. You can select one of the following values:

    • UseRawValue: Use the adjusted value (Gain Offset Value) as the current Filtered Value.

    • ClampAtLimit: If the Gain Offset Value is below or above the minumum or maximum limit, then clamp the Filtered Value at the minimum or maximum value. The Data Quality is set to Bad - BelowLoLimit or Bad - AboveHiLimit.

    • UseLastGoodValue: Use the last good Filtered Value.

    Yes

    Frequency

    Set the processing frequency for the IO Map record. If operations are configured via the Scheduler, set the frequency to OnDemand.

    Yes

    Change Period Check

    Enter the period (in seconds) to check if a value has been changing. If the value has not changed over this period, it will be flagged in WIP, which can then be used to adjust calculations or raise an event. If set to 0, this check is not performed.

    Yes

    Gain

    Enter the gain value to adjust the raw value. The adjusted value is calculated as (Raw Value * Gain) + Offset. The default Gain value is 1, which does not change the raw value (since it’s multiplied by 1).

    Yes

    Offset

    Enter the offset value to adjust the raw value. The adjusted value is calculated as (Raw Value * Gain) + Offset. The default Offset value is 0, which does not change the raw value (since it adds 0 to the value).

    Yes

    Override Value

    Enter the value to be used if the Override Enabled field is set to True. This is useful when an instrument has failed or is giving invalid inputs, and you need to force a value to prevent downstream calculations from being impacted.

    Yes

    Override Enabled

    If you select True, the Override Value will be placed into the Filtered Tag.

    Yes

    Minimum

    Enter the minimum bound to check the adjusted value against (after applying Gain and Offset). This is in the external unit of measure.

    Yes

    Maximum

    Enter the maximum bound to check the adjusted value against (after applying Gain and Offset). This is in the external unit of measure.

    Yes

    Step 3: Define additional parameters.

    Field

    Description

    Required

    Comments

    Add any additional information you want to store about the IO Map record.

    No

    Group

    Use this field if you need to group tags for organisational purposes.

    No

    Future

    This field is designed for future use and can be used for filtering and sorting.

    No

  4. Click Submit to save your entry.

Result

A new row for the IO Map record gets added to the grid. The system automatically fills in the following additional fields for the record:

Field

Description

IO Last Read Write

Shows the time when the operation was last attempted.

Filtered Value

Displays the value saved to the Filtered Tag. It could be the override value (if specified), the last good value (if the raw value is missing or has bad data quality), the adjusted value (if within limits), or the value specified by the Action Id (either the last good value or clamped at the Minimum or Maximum value).

Raw Value

Contains the last raw value received from the external data source, in the external unit of measure.

Gain Offset Value

Shows the value obtained after the raw value has been adjusted using the gain and offset.

Change Timestamp

If the Change Period Check is set to 0, this field is updated with the timestamp associated with the raw value. Otherwise, the change timestamp is updated to the timestamp associated with the raw value when the difference between the current raw value and the last change value is greater than the current raw value divided by 10^7.

Data Quality Code

Contains the numeric value for the data quality associated with the value. This field is visually enhanced through conditional formatting based on the quality code:

  • White: Data quality is Good (Range 0-9)

  • Yellow: Data quality is Suspect (Range 10-29)

  • Orange: Data quality is Bad (Range 30+)

The colour mappings are defined in the installation file src/Common/Quality/BuiltInQualities.txt. To customise these colours, the corresponding entries in this file can be modified.

Data Quality Description

Provides the description associated with the data quality.

Tip

You can also create a new IO Map by copying an existing IO Map and editing its values. To copy an IO Map, click copy in the Action column of the relevant IO Map:

../_images/conf.extd.iomaps.copy.png

This creates a new entry for the copied IO Map, which you can edit as required.

Edit IO Maps

  1. On the IO Maps pane, select the tab corresponding to the protocol of the relevant IO Map’s data connector (for example, Excel, CSV, etc.)

  2. For the required IO Map row, click edit Edit in the Action column.

    ../_images/conf.extd.iomaps.edit.png

  3. In the Edit IO Map dialog, update the values as required.

  4. Click Submit to save your entries.

Delete IO Maps

  1. On the IO Maps pane, select the tab corresponding to the protocol of the relevant IO Map’s data connector (for example, Excel, CSV, etc.)

  2. Select the IO Maps that you want to delete. You can select multiple IO Maps at a time.

  3. Click delete Delete on the toolbar.

  4. Confirm the deletion.

See also