The AWS Injector module provides the ability to push Tag data to an Kinesis Streams and DynamoDB Database endpoints.  The settings configuration for this module are located under the Configure tab of the Ignition Gateway web UI. Once in the AWS Injector Settings configuration section there are five tabs: General, Kinesis, DynamoDB, Sets, and Tag Agents.  Each of these tabs is described in detail in the following sections.

General

The first tab contains the general settings for the AWS Injector module.

The general configurations options available on this tab are listed below:

Main

• Enabled
  • Sets whether the module is enabled or disabled.  If disabled, the Tag Agents will not run and now data will be pushed to any configured endpoints.

Kinesis Streams

The next tab is the list of AWS Kinesis Stream endpoints that the module should connect to to push Tag data.

One or more AWS Kinesis Stream endpoints can be configured on this tab. The configuration options for an AWS Kinesis Stream connection are listed below.

Main

• Setting Name
  • This is a friendly name of the AWS Kinesis Stream used to easily identify it.  This must also be unique.
• Enabled
  • Whether or not this stream is enabled to connect to the Kinesis endpoint
• AWS Access Key
  • The AWS Access Key ID.
  • Example: AKIAIOSFODNN7EXAMPLE
• Password/AWS Secret Key
  • The AWS Secret Access Key.
  • Example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
• AWS Session Tokens
  • Whether to use AWS session tokens
  • Role ARN
    • The AWS role ARN
  • Session Duration
    • The AWS session duration
  • Session Name
    • The AWS session name
• Region
  • The AWS region.
  • Example: us-east-1
• Set
  
  • The Set to associate this AWS Kinesis Stream connection with.
• Stream Name
  • The name of the AWS Kinesis Stream.
• Firehose Stream
  • Enables pushing data directly to Firehose

Store & Forward

• Store & Forward Enabled
  • Whether to enable Store & Forward capabilities for this stream
• Store & Forward Type
  • The type of the Store & Forward mechanism
• Message Capacity
  • The Maximum number of messages to store before dropping the oldest historical messages
• Flush Period
  • The period of time to wait (in milliseconds) between sending when flushing messages

Advanced

• Partition Key Count
  • The number of unique indexed partition keys
• Partition Key
  • An optional partition key pattern that supports token substitution for the following message fields: ${group}, ${edgenode}, ${device}.  This should only be configured if explicitly defined partition keys are necessary when inserting into the Kinesis Stream.
• Max Message Size
  • The maximum message size allowed to be pushed before messages will be broken up into smaller messages (in bytes).

Clicking on the "Create new Kinesis Stream Setting..." link will bring up the following form for adding a new AWS Kinesis Stream endpoint.

DynamoDB Databases

The third tab is the list of AWS DynamoDB Database endpoints that the module should connect to to push Tag data.

One or more AWS DynamoDB Database endpoints can be configured on this tab. The configuration options for an AWS DynamoDB Database connection are listed below.

Main

• Setting Name
  • This is a friendly name of the AWS DynamoDB Stream used to easily identify it.  This must also be unique.
• AWS Access Key
  • The AWS Access Key ID.
  • Example: AKIAIOSFODNN7EXAMPLE
• Password/AWS Secret Key
  • The AWS Secret Access Key.
  • Example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
• Region
  • The AWS region.
• Set
  
  • The Set to associate this AWS DynamoDB Database connection with.
• Table Name
  • The name of the AWS DynamoDB Database table.

Store & Forward

• Store & Forward Enabled
  • Whether to enable Store & Forward capbilities for this stream
• Store & Forward Type
  • The type of the Store & Forward mechanism
• Message Capacity
  • The Maximum number of messages to store before dropping the oldest historical messages
• Flush Period
  • The period of time to wait (in milliseconds) between sending when flushing messages

Clicking on the "Create new DynamoDB Setting..." link will bring up the following form for adding a new AWS DynamoDB Database endpoint.

Sets

The Sets tab contains a list of AWS Sets.  Each set represents a grouping of AWS endpoints.  When a set is referenced by a Tag Agent the Agent will push Tag data to all AWS endpoints contained within that Set. The Sets are disjoint, meaning that a single AWS Kinesis Stream or DynamoDB Database endpoint cannot be in more than one set.  Out of the box the AWS Injector module will have one "Default" set defined.

Additional Sets can be configured for situations where multiple Tag Agents will need to push to different AWS endpoints. The configuration options for Sets are listed below.

Main

• Name
  • This is the friendly name of the set used to easily identify it.
• Description
  
  • This is a friendly description of the set.
• Push Policy
  • This defines which endpoints to push to. If PUSH_TO_ALL is selected, every endpoint that is part of this set will receive all messages. If PUSH_TO_ANY is selected, only one of the endpoints that is part of this set will receive any given message. PUSH_TO_ANY is useful when adding endpoint configurations to increase the throughput of the Injector.

Clicking on the 'Create new AWS Set...' link will bring up the following form to add a new Set.

Tag Agents

Tag Agents are the workers within AWS Injector that monitor tag events, convert them to a JSON representation, and push them to one or more AWS endpoints. Out of the box the AWS Injector module will have one "default" Tag Agent defined.

Tag Agents are configured to point to a single folder.  All Tags within that folder will be monitored by the Tag Agent. 

Tag Settings

• Tag Provider Name
  
  • The name of the Tag provider containing the tags.
• Tag Path
  • An optional folder path under the Tag provider where the root folder of the Tags can be found.
• Tag Pacing Period
  • The buffer period, in milliseconds, that Tag events will be aggregated into a single payload before pushing.
• Convert UDTs
  • Whether to convert UDT members to normal Tags before publishing.  If enabled the Tags representing the UDT member will retain their member path prefixed by the UDT Instance name.
  • Publish UDT Definitions
    • This can only be set if 'Convert UDTs' is false  
    • Whether or not to push the UDT Definitions in the the NBIRTH messages
• Set
  • The Set of AWS endpoints that the Tag Agent will push to.
• Auto-discover Tags
  • Whether newly added tags should be dynamically scanned and their values pushed.  This field is disabled by default.  It should remain disabled while manually editing tags and/or their configurations. It should only typically be enabled in systems where tags are created in real time.

Sparkplug Settings

• Group ID
  • An ID representing a logical grouping of MQTT Edge Of Network (EoN) Nodes and Devices into the infrastructure.
• Edge Node ID
  • An ID that uniquely identifies the MQTT Edge Of Network (EoN) Node within the infrastructure.
• Device ID
  • An optional ID that uniquely identifies a Device within the infrastructure.

The Sparkplug settings are optional and allow for an additional customization of how the Tag Agent scans and discovers tag within the specified Tag Path.  Here is a brief description of how the Agent scans/discovers folders based on the different combinations of potential Sparkplug Settings.

• If all three IDs are left blank the Agent will assume the following folder structures follow the Tag Path:
  • <groupFolder>/<edgeNodeFolder>/<deviceFolder>/<tags>
  • <groupFolder>/<edgeNodeFolder>/<tags>
    
• If only the Group ID is specified the Agent will assume the following folder structure follows the Tag Path:
  • <edgeNodeFolder>/<deviceFolder>/<tags>
  • <edgeNodeFolder>/<tags>
    
• If the Group ID and the Edge Node ID are specified the Agent will assume the following folder structure follows the Tag Path:
  
  • <deviceFolder>/<tags>
  • <tags>
• If the Group ID, Edge Node ID, and the Device ID are specified the Agent will assume the following folder structure follows the Tag Path:
  
  • <tags>

As you can see, the Sparkplug settings can be defined by setting these IDs in this configuration page, or leave them blank so that the Agent will scan and discover them based on the tag tree layout. 

Clicking on the 'Create new Tag Agent Settings..' link will bring up the following form to add a new Tag Agent.