Modify Instance(s) in Digital Twin for multiple Litmus Edge
To modify Instance(s) with Litmus Excel Add-ins, you should be familiar with how Instances work in Digital Twins on Litmus Edge.
Before You Begin
- You have installed the Litmus Excel Add-ins extension. See Install Litmus Excel Add-ins for details.
Initial Preparation
Open a new DT Instance Management Tool File in Excel.
If prompted, Enable Content to allow the code to run.
Make sure the the tool is for the Connect To option set to Multiple LE.
Modify Instance(s)
Import Model(s)
Import the Settings for Instance(s) defined on Litmus Edge using the Import Instance(s) Wizard.
Users can set a filter to reduce the number of Instance(s) shown as selection to the user.
- LE Device IP: Select or enter the IPv4 of the Litmus Edge you want to import Instance(s) from
Notes:
You may need to provide the API Key if the Litmus Edge has not been used with the tool.
- Search Option: Select what type of filter is to be used
- Instance Name Mask: Set the filter to be applied. Will be ignored if Search Option is set to ALL
- Digital Twin Models: Select if you want to search for Instance(s) only from a specific Model.
- The wizard will show what filter will be applied.
- Press the Search button to pull the filtered List of Instance(s) from Litmus Edge.
- The user will be shown the filtered List of Instance(s) matching their filter.
- Select the Instances(s) to import and press the Import button.
Notes:
Users can choose between:
- Press New Search to set another filter and search again if the list doesn't show the Instance(s) the user wanted to import
- Select All Instance(s) using the Checkbox in the Header Row.
- Select a Group of Instance(s) by selecting their respective Check Box
- Select one Instance by selecting the respective Check Box
- Select No Instance and close the Wizard pressing the Close button instead.
- The selected Instance(s) with their settings are imported into the sheet. Once finished, the user can either.
- perform another search using the New Search button
- finish the import using the Close button
- The Action for each imported tag is set to M for modify.
Mandatory Instance Settings
Users can modify these mandatory settings for an Instance(s).
Instance Name: The Name of an existing Instance can be changed.
Instance Definition Properties are a mandatory set of Instance Settings, which are required for defining the Digital Twin Instance.
- Static Attributes: Static Attributes displays the metadata values for the model the instance belongs to. You can customize the attribute values for the instance. This column combines all of these as a single JSON Object. It is recommended to use the Static Attributes Wizard when setting your specific values for Static Attributes.
- Dynamic Attributes: Dynamic Attributes displays the variable data attributes configured in the model the instance belongs to. You can map one-to-one relationships with data topics and attributes by updating the topic field for the instance. This column combines all of these as a single JSON Object. It is recommended to use the Dynamic Attributes Wizard when setting your specific values for Dynamic Attributes.
Not Mandatory Instance Settings
- Update Interval in Seconds: Enter the interval between retrieving data from the instance. The minimum interval allowed is one second.
- DT Instance Topic: Review the default topic name for the instance. You have the option of entering a custom topic name.
Notes:
- Flatten Hierarchy: Select if you want to send hierarchy data in a flat JSON structure. When selected, it will take a nested JSON object and convert it into a JSON object with one layer using dot notation. This is useful when sending JSON objects to InfluxDB, because InfluxDB does not accept nested JSON objects.
- Publish Attributes: Select if you want to publish additionally to the DT Instance Topic each individual Attributes under their own Topic (FALSE)
Notes:
The Publish Attributes feature is not available for all supported Litmus Edge Versions. If not supported, the column is grayed out.
Notes:
You can repeat modifying mandatory and not mandatory Instance settings for every Instance you need to modify before executing Actions.
Executing Actions
When all mandatory and sheet mode dependend not mandatory settings for all Model(s) are set they are ready to be modified.
It is Recommended but not mandatory to verify the configuration first without executing the Action by pressing the Verify Only button.
This will check that all required Instance Settings are provided and logically correct. And provide any finding to the user. Example: Below the user did not set a Topics (value is "") for the Dynamic Attribute.
Important: The tool can not verify if all provided Instance settings are factually correct. For example it can not verify that the value of a Static Attribute is correct for what the user wants to achieve.
The Instance(s) can be modified to Litmus Edge by pressing the Verify + Execute button.
The tool will group all the Instance(s) based on the Litmus Edge(s) defined in column Target Litmus Edge IP. For each Litmus Edge this will check that all required Instance Settings are provided and logically correct. And provide any finding to the user. If no issues have been identified, the tool will verify that the user wants to execute ALL the actions from the Action Column:
- A: Add Instance(s)
- M: Modify Instance(s)
- D: Delete Instance(s)
- I: Ignore Instance(s) -> do nothing
To perform all actions, press the Yes button.
The Tool will perform ALL Actions row by row for the Litmus Edge. When finished, a result Summary is shown for each Litmus Edge. Close the Result Summary by pressing the X close button.
Once all Litmus Edge have been processed, the tool will ask if the user wants to re-compare the Instance(s) against Litmus Edge. To re-compare, press the Yes button. To not re-compare, press the No button.
If the User selected to press the Yes button from aboves messagebox, the tool will pull all the Instance settings from Litmus Edge again including the InstanceID and also change the Action to M for each Instance with a InstanceID or A for an Instance with no InstanceID.
Troubleshooting
The Tool will perform several checks throughout the proces of defining the Instance settings. If they do not pass successfully, the user will be notified. The checks include:
- Instance Name uniqueness on a Litmus Edge level.
- The tool checks if a Instance Name already exist for a specific Litmus Edge in the Tool.
- The user is shown a message box as notification.
- The character(s) are highlighted in red and also shown in a note.
- See Allowed and not allowed Ascii Characters for Names and Descriptions for a full list for both Names and Descriptions.
- Correct JSON formating for Static Attributes and Dynamic Attributes.
- Example for an invalid JSON formatting of the Static Attributes
- While it is possible to not define entries for the columns Static Attributes and Dynamic Attributes, the tool verifieds if any of these columns are empty. As this will cause Instances of this model to not return data or not return expected data.
- While it is possible to leave some Values for Static Attributes and Dynamic Attributes empty, the tool checks for such empty values. As this will cause Instances of this model to not return data or not return expected data. Example: No Topic defined for Dynamic Attribute.
- if a Model is selected
- Verify that a DT Instance Topic is defined.
- Verify that the topic in the column DT Instance Topic follows the guidelines for topic names: Subject-Based Messaging.
