Create and edit mappings
Learn how mappings transfer data between items, create and edit mappings and mapping groups, and configure triggers, logic, synchronization, and Store'n'forward.
A mapping is a virtual connection that transfers data from a sender to a receiver. You can use mappings to send PLC or sensor values to a cloud service, database, or broker, synchronize values between devices, or connect systems that use different industrial protocols.
The sender determines when the mapping runs. The receiver is the item that receives the value or command.
Before you begin
- The sender item must be enabled and support reading.
- The receiver item must be enabled and support writing.
- Review the sender item's Trigger behaviour when using the Item trigger type.
Understand mapping triggers
| Trigger type | How it works | Required settings |
|---|---|---|
| Item | The sender item starts the mapping according to its Trigger behaviour. | Sender instance, one or more sender items, receiver instance, and receiver item. |
| Instance status | A change in the sender instance status starts the mapping. | Sender instance, receiver instance, and receiver item. |
| Time | The mapping runs at the configured interval. | Sender instance, one or more sender items, a positive whole-number interval in milliseconds, receiver instance, and receiver item. |
Create a mapping
- Expand Instances in the sidebar.
- Open the instance that you want to use as the sender.
- Scroll to Mappings on <Connector name>.
- Select New mapping.
- Select the sender Instance.
- Select a Trigger type.
- Select one or more sender Item values when using the Item or Time trigger.
- Enter Mapping interval (ms) when using the Time trigger.
- Complete any optional fields under Logic.
- Select the receiver Instance and Item.
- Configure any optional synchronization, start-up, acknowledgement, or buffering settings.
- Select Save mapping.
When the mapping is saved successfully, the editor closes and the portal displays Mapping saved successfully.
Create a mapping group
Selecting more than one sender item creates a mapping group. Each selected sender item gets its own mapping to the same receiver and uses the same logic and optional settings.
- Select two or more sender items.
- Enter a Group name.
- Optionally enter a Group description.
- Complete the receiver, logic, and optional settings.
- Select Save mapping.
The group name is required when multiple sender items are selected.
Mapping settings
| Setting | Default | Meaning |
|---|---|---|
| Sender - Instance | Current instance | The instance that provides the trigger or source value. |
| Trigger type | Item | Selects whether an item sample, instance status change, or time interval starts the mapping. |
| Sender - Item | Not selected | The readable item whose value is sent. Select multiple items to create a mapping group. |
| Mapping interval (ms) | Empty | The interval for a Time mapping. Enter a whole number greater than 0. |
| Group name | Empty | Names the mapping group. It is required when more than one sender item is selected. |
| Group description | Empty | Optional information describing the mapping group. |
| Condition | Empty | An expression that must evaluate successfully before transmission runs. |
| Custom value | Empty | Wraps, enriches, or changes the transmitted value. It overrides the receiver item's Input template. |
| Receiver - Instance | Not selected | The destination instance. |
| Receiver - Item | Not selected | The writable item that receives the value or command. |
| Bidirectional synchronization | Off | Also transmits data from the receiver back to the sender. |
| Execute on start-up | Off | Runs the mapping when the service starts or reinitializes. |
| Acknowledge writing | Off | Returns received data to the sender to acknowledge the transmission. |
| Store'n'forward | Latest value (no history) | Controls whether failed writes are retained and their retry order. |
Choose a Store'n'forward mode
| Mode | Behavior |
|---|---|
| Disabled | Does not retain failed write commands. |
| Latest value (no history) | Keeps only the latest retryable value. The mapping row does not show the Store'n'forward icon for this mode. |
| FIFO | Retries the oldest buffered values first. |
| LIFO | Retries the newest buffered values first. |
| Sporadic | Uses the legacy sporadic buffer ordering. |
Navigate the mapping overview
The mapping overview groups mappings under their destination entries. Expand a destination to see the mappings that write to it. Select a mapping row to open its complete details in the panel beside the list.
You can also open mappings from the destination information shown for an item. This lets you move directly from a receiving item to the mappings connected to it.
Each row summarizes the data flow from sender to receiver. The row can include compact indicators for:
- Trigger - Shows whether the mapping is started by an item, an instance status change, or a time interval.
- Condition - Indicates that the mapping has a condition. Point to it to review the condition.
- Template - Indicates direct parsing, a receiver Input template, or a custom mapping value. Point to it to review the available detail.
- Acknowledge writing and mapping direction.
- Store'n'forward - Shown when a history-based buffer mode is enabled. It is not shown for Latest value (no history).
- Active mapping errors.
Repeated rows with the same destination are collapsed into one destination entry. Expand the entry when you need to see the individual mappings. Use Expand all or Collapse all to change the complete list, and use Search Mappings to filter it.
Edit a mapping
- Open either the sender or receiver instance.
- Scroll to the Mappings section.
- Expand the required destination and select the mapping or mapping group.
- Select the edit control in the details panel. You can also open the context menu and select Edit mapping or Edit mapping group.
- Change the required settings.
- Select Save changes.
When editing a mapping group, adding a sender item creates another mapping in the group. Removing a sender item removes that mapping when you save.
Review mapping details
Select a mapping to review its sender and receiver, value handling, condition, trigger, enabled options, buffer count and mode, event history, and active errors. Select an instance or item name in the details panel when you need to open and edit that connected resource.
Delete a mapping
- Open the mapping or mapping group editor.
- Select Delete mapping or Delete group.
- Select Confirm delete.
Deleting a mapping is permanent. Deleting a group also removes every mapping inside it.
Common problems
| Message or behavior | What to do |
|---|---|
| Sender instance is required. | Select the instance that provides the mapping trigger. |
| Select at least one sender item. | Select one or more enabled, readable items. |
| Receiver instance is required. | Select the destination instance. |
| Receiver item is required. | Select an enabled, writable receiver item. |
| The mapping interval is missing or invalid | Enter a positive whole-number interval in milliseconds. |
| Group name is required when multiple sender items are selected. | Enter a group name, or select one sender item. |
| Failed to load mapping options. Refresh the page and try again. | Refresh the page and confirm that the required instances and items still exist. |