Working with MassConfig

This section will guide you through the use of the MassConfig display and how it can help you 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 How-to 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 main 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 type of object, its path and the Model Panel that it will be created in. For this Example select from the drop down menus to create a Folder in the I/O Model. The path will include the object name in your system and, for this example, the MassConfig Training folder is created under the Core object. Click Begin to go to the next step.

    Create Object in MassConfig Wizard - Object Type
    Figure 4. Create Object in MassConfig Wizard - Object Type
    Remember to change the Core name from "MasterCore" in the Object path to match the name of the Core object in your system!.

  3. In the Common properties step, confirm the object name and add an object description if you wish. The rest of the 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 actually creating it on the server side (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 actually applying them. This allows to see configuration errors, before they actually 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 sever. A similar message box like above will show the result of the actual change. Also the I/O model tree will be updated automatically and 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 that you 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 for Folder and one for Generic Item. 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

To complete this part of the How-to you need to have MS Excel 2007 or higher installed on your host machine.

  1. Open a new MassConfig display, and add the GenericItem created above to it (or create a new Generic Item in the wizard).

  2. Click the Export to File icon TIP: in the menu bar of the MassConfig display (shortcut Ctrl+Shift+E).

    MassConfig - Export to File
    Figure 12. MassConfig - Export to File

  3. The content of the MassConfig display is exported to an .xlsx file which is automatically opened in MS Excel (or whatever the default application for .xlsx files on your system is).

    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. Since MS Excel allows for setting any value, they might be invalid, however, the MassConfig simulation will reveal this after importing into the MassConfig display. Check the properties page for details about object properties and their allowed 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 you created in the 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 by 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 reported during the simulation they will be indicated in the errors. 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 tree and check in the Object Properties Panel that the GenericItemsare generating numeric values.

    GenericItems Created from MassConfig Display in the I/O Model Tree
    Figure 18. GenericItems 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.

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 object paths 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 19. Namespace in MassConfig

  3. Click on the Rebase button in the menu bar to open the Rebase dialog.

    Rebase button in Menu Bar
    Figure 20. 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. We will create a new copy of the "Examples" subtree by changing the new base path to "Examples 2".

    Rebase Dialog
    Figure 21. 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 22. Rebase Completed

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

  10. Before we can create the duplicate tree, we need to change the Object Name of the Examples node.

  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 23. 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.

    Mass Config results
    Figure 24. Mass Config results

Other MassConfig Operations

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

Mass Operation with No Changes
Figure 25. 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 allows to 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.