Working with MassConfig

This section will guide you through the use of the MassConfig display and how it can be used to create, delete and modify multiple objects in system:inmation. MassConfig sheets, like workspaces, can be saved or exported and shared with other users.

Preparation

  1. Firstly, create a new workspace for this guided example by selecting System  New Workspace (shortcut Ctrl+N), saving your current workspace if needed.

    Create New MassConfig Training Workspace
    Figure 1. Create New MassConfig Training Workspace
  2. Open a new MassConfig display by selecting Open  Mass Config Sheet (shortcut Ctrl+M).

    MassConfig Display
    Figure 2. MassConfig Display

Create a New Object from Scratch

  1. Click on the New Object wizard icon in the menu bar of the MassConfig display.

    Open New Object Wizard
    Figure 3. Open New Object Wizard
  2. The first step in the Create Object wizard is to choose the Item Path, the Model Panel it will be created in and its type. For this example, select a Folder from the Type drop-down menu and set the Model as the I/O Model. The Item Path must include the object name in the system and, for this example, the MassConfig Training folder is created under the Core object. Click Begin to go to the next step.

    Remember to change the Core name from "MasterCore" in the Object Path to match the name of the Core object in your system!.
    Create Object in MassConfig Wizard - Object Type
    Figure 4. Create Object in MassConfig Wizard - Object Type
  3. In the Common properties step, confirm the Object Name. An optional Object Description can also be added. The remaining options can be left as default. Click Finish to add the object to the MassConfig display.

    MassConfig Wizard - Common Properties
    Figure 5. MassConfig Wizard - Common Properties
  4. The object appears in the MassConfig sheet as shown below.

    First Object in MassConfig Display
    Figure 6. First Object in MassConfig Display
  5. Once present in the MassConfig display, the object properties can be edited before it is created on the server (and in the I/O Model tree). One way is to right-click on the object in the MassConfig display to open the context menu and select Edit object. This reopens the wizard where the properties can be edited.

    Edit Object in MassConfig Display - Context Menu
    Figure 7. Edit Object in MassConfig Display - Context Menu
  6. Alternatively, the object properties can be edited directly in the table of the MassConfig display by double clicking on the respective column entry.

    Edit Properties in MassConfig Display Table
    Figure 8. Edit Properties in MassConfig Display Table
  7. Click Simulate to check that all the object properties are syntactically correct before executing the object creation.

    Although not mandatory, it is strongly recommended to always execute a simulation of the MassConfig changes before applying them. This will show any configuration errors before they go live on the server.
    MassConfig Display - Create Object Simulation Result
    Figure 9. MassConfig Display - Create Object Simulation Result
  8. The simulation result is displayed in the message box. Successful simulation will be indicated in the message and the object will have a green tick by it in the MassConfig display table.

    Training Task: Simulate a configuration error
    Edit the object path so it points to a non-existent location in the tree. Simulate the object creation and check the result. Once the simulation returns no errors, click Apply to send the configuration to the server. A message box will show the result of the actual change. Also, the I/O model tree will be updated automatically to show the new folder.
    Training Task: Create a Generic Item below the new "MassConfig Training" folder
    Close any open MassConfig displays and open a new empty one. Create a Generic Item object from the I/O model below the MassConfig Training folder using the Create Object wizard. Name the object GenItem and use Numeric Value Generator as Generation Type. Change the other settings to your choosing.

Editing an Existing Object

Existing objects in the Model Panels can be edited by dragging and dropping them from the Model Panel into the MassConfig display. You can also use the context menu to edit multiple objects or even whole sub-trees below objects. In this example we will edit the objects that were created in the last section.

  1. Right click on the MassConfig Training folder in the I/O Model tree created in the previous example and select Admin  MassConfig Sheet  Subtree.

    Adding Subtree to MassConfig Display
    Figure 10. Adding Subtree to MassConfig Display
  1. The currently selected folder and all its successors in the tree are added to the MassConfig display. Notice that there are 2 tabs at the top of the display, one Folder tab and one Generic Item tab. Each different system:inmation object type is placed under a separate tab (multiple objects of the same type are placed under the same tab).

    MassConfig Display - Object Type Tabs
    Figure 11. MassConfig Display - Object Type Tabs

Mass Import using MS Excel

Completing this part of the example requires MS Excel 2003 or higher installed on the host machine. Make sure to export the display as a compatible file type for the version of MS Excel used.
  1. Open a new MassConfig display, and add the Generic Item created above to it (or create a new Generic Item in the wizard).

  2. Click the Export to File icon in the menu bar of the MassConfig display.

    MassConfig - Export to MS Excel File
    Figure 12. MassConfig - Export to MS Excel File
  3. The content of the MassConfig display is exported to a .xls or a .xlsx file which is automatically opened in MS Excel (or in the default application for this file type on the host system).

    MassConfig Exported to MS Excel
    Figure 13. MassConfig Exported to MS Excel

    Each different object type tab from the MassConfig display will be exported to a different tab in the Excel sheet and each worksheet contains the same rows and columns as the MassConfig display table.

    We will use this worksheet to create 10 more generic items in the I/O Model tree.

  4. Copy the second row of the MS Excel worksheet ten times in the rows below.

  5. Rename the BasePath and ObjectName with unique names (or add sequential numbering) so it looks similar to the example below:

    Multiple Generic Item Objects in MS Excel Worksheet
    Figure 14. Multiple Generic Item Objects in MS Excel worksheet
    All properties can be set/changed in MS Excel. Some property’s values are limited to predefined constants though. As MS Excel allows any value to be set, they might be invalid, however, the MassConfig simulation will highlight this after importing into the MassConfig display. Check the properties page for details about object properties and their permitted values.
  6. Save the MS Excel workbook (default save location is your documents folder), keeping note of the filename and return to the MassConfig display in DataStudio.

  7. Click the import from file icon in the menu bar of the MassConfig Display to bring up the Open file dialogue.

    Import File into MassConfig Display
    Figure 15. Import File into MassConfig Display
  8. In the Open dialogue, navigate to the MS Excel worksheet file you just saved and click Open. The extra items created in the MS Excel worksheet will populate the MassConfig display.

    New Objects in MassConfig Display
    Figure 16. New Objects in MassConfig Display
  9. Click Simulate to check if the configuration information is valid. You should see that all changes are successful and a green tick is displayed next to each object in the MassConfig display.

    Successful Simulation of New Objects in MassConfig Display
    Figure 17. Successful Simulation of New Objects in MassConfig Display
    If there are any errors detected during the simulation, they will be indicated in the error message. It should be possible to fix the configuration problems. Common problems encountered are invalid file paths (orphaned paths) due to a change in the Core or Connector name from machine to machine. Also, an invalid property value could have been entered in the MS Excel sheet and flagged in the MassConfig display; in this case, allowed values for the property will be indicated in the error message.
  10. Click Apply to create the objects in the I/O Model Panel and check in the Object Properties Panel that the Generic Items are generating numeric values.

    Generic Items Created from MassConfig Display in the I/O Model Tree
    Figure 18. Generic Items Created from MassConfig Display in the I/O Model Tree
    Training Task: Add multiple subfolders and items
    Use the MS Excel worksheet export/import to create more folders and subfolders. Create multiple new Folders and Generic Items in the same MassConfig display and vary their properties.

Mass Import using JSON

The objects from a MassConfig display can also be exported as a JSON. Similar to the MS Excel example above, the exported JSON file can be used to edit the configuration outside of the MassConfig display.

MassConfig Export File as JSON
Figure 19. MassConfig Export File as JSON

When importing a JSON file into the MassConfig sheet, any changes made will now be visible in the MassConfig Display. Press Apply to configure these changes in the Model Panel.

Configuring Changes using Lua Scripts

Another option for making changes to a MassConfig Display is to use a Lua script. These can be used to create and edit objects within the MassConfig Display without using the Create Object Wizard.

  1. Right-click on one of the Generic Items in the I/O Model Panel, created in the example above and select Admin  Mass Config Sheet  Object.

    Generic Item in MassConfig Display
    Figure 20. Generic Item in MassConfig Display
  2. Click on the Generate Lua Script button in the MassConfig Display menu bar to open a console. The Generic Item in the MassConfig Display should already be shown in the console as a Lua script.

    Generate Lua Script Button in Menu Bar
    Figure 21. Generate Lua Script Button in Menu Bar
    The default operation type for the Lua script is Upsert, which will be used for this example, but can be configured to other options if required. The operation type determines what changes the Lua script can make to the objects in the MassConfig Display.
  3. Add a new Generic Item called 'NewGenItem' in the Lua script console.

    New Item in Lua Script Console
    Figure 22. New Item in Lua Script Console
  4. Run the Lua script (shortcut F5)

    Run Lua Script - MassConfig
    Figure 23. Run Lua Script - MassConfig
  5. As the operation type is set to Upsert, the new item is created and should be displayed automatically in the I/O Model Panel.

    Updated I/O Model - MassConfig
    Figure 24. Updated I/O Model - MassConfig

Change Paths with Rebase

A common use of MassConfig is to create duplicate sub-sections of Model trees that might only differ in the name of a root node. This can be achieved quickly and easily by changing the base path of the objects using the Rebase function.

  1. Create a namespace with a node folder with children below it (in the example shown, the DemoData namespace is used).

  2. Right-click on the node folder and select Admin  Mass Config Sheet  Subtree from the context menu.

    Namespace in MassConfig
    Figure 25. Namespace in MassConfig
  3. Click on the Rebase button in the menu bar to open the Rebase dialog.

    Rebase Button in Menu Bar
    Figure 26. Rebase Button in Menu Bar
  4. The Rebase dialog displays the longest common path of the objects in the MassConfig sheet in the Base path field. In this case, it is the path of the node folder "Examples".

  5. Create a new copy of the "Examples" subtree by changing the new base path to "Examples 2".

    Rebase Dialog
    Figure 27. Rebase Dialog
  6. The Rebase references checkbox is ticked meaning that the paths of any referenced objects will also be changed to the new base path. A total of 9 references will be changed.

  7. Click Change to make the changes to the paths.

  8. The changed paths are now visible in the MassConfig sheet.

    Rebase Completed
    Figure 28. Rebase Completed
  9. Click Close to close the Rebase Dialog and return to the MassConfig sheet

  10. Before creating the duplicate tree, the ObjectName of the Examples node must be changed.

  11. Click on the Folder (IO) tab in the MassConfig sheet and select the ObjectName field of your top node folder.

  12. Change the ObjectName to match the new base path.

    Change ObjectName of Node
    Figure 29. Change ObjectName of Node
  13. Click Apply to create the objects in the MassConfig sheet

  14. The results of the mass configuration will be displayed and the new "Examples 2" duplicate namespace should be visible in the I/O Model.

    MassConfig Results
    Figure 30. MassConfig Results

Validation of References

An important feature of the MassConfig display is the option to validate the references of the objects in the display. This feature checks the validity of both the References and the Security References.

To check the validity of a specific reference, right-click on the object in the MassConfig display and select Validate Reference. The Validate All References option will validate every reference across all tabs in the MassConfig display. Invalid references will be indicated by warning icons in the MassConfig display.

Invalid Reference Warning in MassConfig Display
Figure 31. Invalid Reference Warning in MassConfig Display
Warning icons on invalid references indicate that an object in the referenced path does not exist.
If changes are made to Object Paths in the MassConfig Display using the Rebase feature, it is important to Apply the changes before validating the references.

Other MassConfig Operations

You might have noticed in the above steps, that the Mass Operation results sometimes show that some of the objects to be configured will not be changed.

Mass Operation with No Changes
Figure 32. Mass Operation with No Changes

This happens when these two conditions are met:

  1. The mass operation contained an object, whose properties are 100% identical with an already existing object.

  2. The Operation mode is set to Upsert.

Upsert is the default operation mode, and can create and update existing items with the same mass operation. This means, if an object’s path specified in the display already exists, it will be updated with the configuration values in the display (if they differ from the server side). Should the specified path not be found, the object will be created.

There are other operation modes available, allowing for executing different actions on the specified object.