Bensikin User Manual

Intended audience: users, administrators

Authors:

R.Girardot, M.Ounsy, A.Buteau, M.Thiam - Soleil

Introduction

This document is an end-user guide to using the Bensikin application, and a brief developer-oriented presentation of the application’s architecture.

Application’s context: Contexts and Snapshots

A snapshot is, as said in the name, a “picture” of a list of equipment’s “settings” (more precisely of their Tango attributes values) taken at a precise instant.

A snapshot is based on a context, which is a group of Tango devices and their attributes that must be part of the snapshots. A context is described by meta-data (author, description, etc.), so that users know which context is used what for.

A typical use case of a snapshot is to memorize a particular configuration of a set of equipment’s, to be able in the future to reset them to the values of this snapshot (for example, reposition all Insertion devices to their parking position after a beam loss).

Application’s description and goals

Application’s goals

Bensikin allows the user to define contexts and take snapshots. Snapshots can be saved as files and modified.

Bensikin is ready for multi-user use, which has for consequence the need to define accounts. An account is a way to map a user with a working directory. An important consequence of this is that 2 different users must not use the same working directory, or you may encounter application misbehaviors. An account has a name and a path to a working directory.

Bensikin is thus naturally divided (both in functionalities and display) in three parts:

  • The account part, which is an introduction to the rest of the

    application

  • The context part

  • The snapshot part

A first look to Bensikin

The Bensikin Account Manager is here to manage accounts, which means:

  • Creating a new account

  • Deleting an existing account

  • Launching application with an account chosen in a list

    ../../_images/image5.png

    Figure 1: Bensikin Account Manager

The Context Control Panel is where user can manage contexts, which means creating, loading and modifying contexts, and launching snapshots based on the defined contexts.

The Snapshot Control Panel is where user can manage snapshots, which means saving snapshots in files, loading snapshots from database and files, temporary modify snapshots attributes values and set equipment with defined snapshots (with or without modifying snapshots) or a subpart of them.

The application’s logs panel displays the application information and error messages (like database interaction, encountered problems, etc.)

The Menu and the Tool bar are for actions shortcuts and application’s options.

../../_images/image6.png

Figure 2: Bensikin main panel

Account Manager

The Figure 1: Bensikin Account Manager presents the account Manager Interface, on application start. With this manager, you can create a new account, or delete or use an existing one.

To quit the application, simply click on image3 or image4 button.

Existing accounts are listed in the account Selection Combo Box, which you can reload by clicking on image5 button (if you think that someone could have modified it by creating a new account or deleting an existing one, for example).

Creating a new account

To create a new account, click on the button image6 (at the bottom left of the panel). A new dialog will appear, as following.

../../_images/image111.png

Figure 3: Creating a new account

In this new dialog, you will have to enter the name of your new account and the path of the application working directory for this account. If you prefer, you can browse for the path by clicking on the image8 button. Then, a classic browsing dialog will be displayed, in which you can choose the directory. When both fields (Name and Path) are fulfilled, click on image9 button to validate your new account, which will be automatically added in the list of existing accounts. If you click on image10 or image11 button, you go back to the first dialog, as presented in Figure 1: Bensikin Account Manager, and nothing is done.

Deleting an existing Account

To delete an existing account, first select the account in the account selection combo box, as following:

../../_images/image151.png

Figure 4: Account selection

When the account is selected, click on Delete button to delete it. If you do it, you won’t be able to use this account any more (and no other user either), because the account is definitely removed from list. The account deletion doesn’t involve the corresponding directory (neither its content) deletion.

If you want to see your account path, you can check Show account path.

../../_images/image5.png

Figure 5: Show account path

Launching application with an existing account

To launch application with an existing account, first select the account in the account selection combo box, as presented in Figure 4: Account selection.

Then, click on Ok button, and you will reach the application main panel configured with this account (the account name is displayed in frame title).

Contexts Management

This section describes how to control contexts with Bensikin. A context is a list of attributes for which you can make a snapshot. A context has an ID and a creation date, both defined by the database. A context also has a name, an author, a reason and a description. The reason usually describes why the context was created (example: because of an incident or in order to set some equipment), whereas the description is here to have an idea of what kind of attributes you will find in this context.

Contexts are managed in the context control panel:

../../_images/image161.png

Figure 6: Context control panel

Creating a new context

To create a new context, click on the new icon in toolbar (image17), or choose option to make a new context from File menu or Contexts menu:

image18image19

You also are ready to make a new context at application first start or by clicking on the reset icon (image20):

../../_images/image211.png

Figure 7: Application first start

The difference between the reset icon(image22) and the new icon(image23) is, that the “reset” icon will clear every panel, whereas the “new” icon will only clear the snapshot list and the Context Details sub panel.

Classic way (tree)

The tree on the left side of the Context Details sub panel allows you to check for available attributes. The one on the right side represents your context attributes.

To add attributes in your context browse the left tree, select attributes (represented by the icon image24), and click on the arrow image25 to transfer them to the right tree.

To remove attributes from your context, select them in the right tree and click on the cross image26.

Finally, fill the context Meta data (Name, Author, Reason and Description) in the corresponding fields (Note that filling the fields activates the register button image27).

Then, you can save your context in database by clicking on the register button image28.

Doing so will deactivate the register button and activate the launch snapshot button image29.

You can save your context in a file using the save icon image30.

Alternate way (table)

To select this alternate way, go to tools menu and select options.

Then select the context tab and click on the table radio button.

../../_images/image28.png

Figure 8: Option –context tab

Click on the ok button. The context panel now has the “table selection mode”.

../../_images/image80.png

Figure 9: Bensikin with context table selection mode (new context)

  • Attribute selection and automatic attributes adding:

    • Choose a Domain. This refreshes the list of possible Device classes for this Domain.

    • Choose a Device class. This refreshes the list of possible Attributes for this Domain and Device class.

    • Choose an Attribute and press OK:

      All Attributes with the selected name AND belonging to any Device of the selected Class and Domain are added to the current Context’s list of attributes.

    All new attributes are light red until the Context is registered.

  • Line level sub-selection of loaded attributes:

    Each attributes are initially checked, but this check can be removed by the user. When the user clicks on validate, all unchecked attributes will be removed from the current Context.

    • Click All to select all lines

    • Click None to select no lines

    • Highlight lines in the list (CTRL and SHIFT are usable), then click Reverse highlighted to reverse the checked/unchecked status of all highlighted lines.

As for the classic way, you will have to fill the Meta data fields and register your context in database by clicking on the register button image34

Modifying an existing context

As a matter of fact, you can’t really “modify” a context. What you can do is to create a new context with its information (attributes and Meta data) based on another one.

The very difference is in alternate mode, where former attributes are in white and new ones in light red:

../../_images/image81.png

Figure 10: Bensikin with context table selection mode (modified context)

The “register” button changed a little too: its text is Register this context instead of “Register this new context”, as you can see on the figure above.

Loading a context

There are 2 ways to load a context:

  • Load it from the database

  • Load it from a file

In both cases, loading a context will apply a quick filter on the snapshot list, so you can see the snapshots about this context that have been created this day (the day when you load the context).

Loading a context from database

In the Contexts menu, choose load then select DB:

image36

A dialog will then appear to allow you to filter the list of contexts in database following different criteria:

../../_images/image32.png

Figure 11: Data base Context filter dialog

Select no criterion to search for all contexts present in database. Click on the image38 button to apply the filter. The list of corresponding contexts will then appear in the Context List sub panel, as shown in Figure 6: Context control panel. Double click on a context in table to load it and see its details in the Context Details sub panel (See Figure 6: Context control panel).

If there are too many contexts in the list, you can remove some contexts from list (not from database) by selecting them in list and clicking on the cross on the top right corner of the list (image39).

Loading a context from file

In the Contexts menu, choose load then select File, or in File menu choose load then select Context:

image40 image41

A classic file browser will appear. Search for your “.ctx” file and select it to load the corresponding context in the Context Details sub panel (See Figure 6: Context control panel).

Printing a context

Once you have context ready, click on the print icon (image42) and select context:

image43

The classic print dialog will then appear. Validate your print configuration to print an xml representation of your context.

User can also print context by pressing the button image44

Saving a context

Once you have context ready, click on the save icon (image45) and select context:

image46

You can also go to menu Contexts and click on save, or go to menu File, select Save and click on Context.

image47 image48

Then, the behavior is “Word-like”. This means that if this is the first time you save this context, you will see the classic file browser to choose where to save your context, with file name. However, else, it will automatically save in the corresponding file. If you want to save in another file, you have to go to File menu, select Save As and click on Context or go to Contexts menu and click on Save As

image49 image50

Snapshot Management

This section describes how to control snapshots with Bensikin. A Snapshot is a view of your equipment at a precise date, view based on a context. A Snapshot has an ID, a creation date (Time), and a comment to describe it (which can be left empty).

Snapshots are managed in the snapshot control panel:

../../_images/image45.png

Figure 12: Snapshot control panel

Creating a new snapshot

To create a new snapshot, first select a valid context in the context control panel (see Figure 6: Context control panel). Then click on the button image52. The corresponding snapshot is added in the list of snapshots in the Snapshot List sub panel.

Loading a snapshot

There are 2 ways to load a snapshot:

  • Load it from the database

  • Load it from a file

Loading a snapshot from database

Loading a snapshot from database consists in adding this snapshot in the list of snapshots in the Snapshot List sub panel.

As you can see in Figure 12: Snapshot control panel, the Snapshot List sub panel allows you to filter snapshots from database to find the snapshot you want to load. However, have in mind that this filter is “context dependent”, which means that the snapshots which will appear in the list by clicking on the filter button (image53) are the one that correspond to your filter criteria AND the selected context in the Context Control Panel. If the filter is cleared (which you can obtain by clicking on the button image54), you will search for all the snapshots in database that correspond to the selected context.

Loading a snapshot from file

In the Snapshots menu, choose load then select File, or in File menu choose load then select Snapshot:

image55 image56

A classic file browser will appear. Search for your “.snap” file and select it to load the corresponding snapshot in the Snapshot Details sub panel (See Figure 12: Snapshot control panel)

Editing a snapshot

To edit a snapshot, double click on the snapshot you want to edit in the snapshot list (in the Snapshot List sub panel). This will open a new tab about this snapshot in the Snapshot Details sub panel, tab named by this snapshot ID. If you load a snapshot from file, the name of the tab is the name of the file. To differentiate snapshots loaded from file and the ones loaded from database, the snapshot loaded from file tabs have the icon image57.

Setting equipment with a snapshot

A snapshot allows you to set equipment with its attributes write values. You can choose which attributes will set equipment, and which not, by selecting or unselecting the corresponding check box in the column Can Set Equipment (See Figure 12: Snapshot control panel). By default, every attribute is selected. If you unselect some attributes, an icon image58 will appear in tab title to notify you that these attributes will not set equipments. You can quick select/unselect all the attributes by clicking on All and None buttons. When you are ready to set equipment with the selected write values, click on the button image61.

You can also modify the write value before setting equipment by editing it in the table. If you do so, the value becomes red and an image62 icon appears to warn you about the fact that you made modifications in this snapshot (these modifications will not be saved in database, they are just here to set equipment).

../../_images/image54.png

Figure 13: Modified snapshot

Snapshot comparison

There are 2 ways to compare snapshots:

  • Compare a snapshot with another one:

    To do so, select a tab in Snapshot Details sub panel (Figure 12: Snapshot control panel). Click on button image64. You will see the tab title of this attribute appear in the field “1 st snapshot”. Select another tab and click again on image65 button to put this attribute tab title in the field “2 nd snapshot”. Click then on image66 button to see the comparison between these 2 snapshots.

    If user wants to see only the first line of comparison, he must check filter image67

    Else if he/she wants to see all the details of the comparison, he/she must check image68

    ../../_images/image57.png

    Figure 14: Snapshot comparison - full table

    To print this comparison table, click on Print button.

  • Compare a snapshot with current state:

    To compare a snapshot with current state, set this snapshot as “1 st snapshot”, as explained above, and leave the “2 nd snapshot” empty. Note that once the “1 st snapshot is selected, you only can update the “2 nd snapshot or clear the comparison selection. To do so, click on the button image70. What is hidden behind this is a creation of a snapshot, named “BENSIKIN_AUTOMATIC_SNAPSHOT”, and you compare this snapshot with your snapshot. Have in mind that this automatic snapshot is registered in database. So, in the comparison table, the current state will appear as the second snapshot with the name “Current state” (red block in the comparison table).

Snapshot Details copy

As you can see in Figure 12: Snapshot control panel, snapshots are detailed in a table. You can copy this table to clipboard as a text-CSV formatted table by clicking on image71 or image72 button. If you want to see this text result and may be filter it (like removing lines), click on image73 button. You will see the text appear in a dialog.

../../_images/image59.png

Figure 15: Snapshot edit clipboard dialog

Modifying a snapshot comment

Once your snapshot details are loaded, click on image75 button to modify its comment (and save it in database or file).

Printing a snapshot

Once you have context ready, click on the print icon (image76) and select snapshot:

image77

The classic print dialog will then appear. Validate your print configuration to print an xml representation of your snapshot.

Saving a snapshot

Once you have context ready, click on the save icon (image78) and select snapshot:

image79

You can also go to menu Context and click on Save, or go to menu File -> Save -> Snapshot.

Then, the behavior is “Word-like”. This means that if this is the first time you save this snapshot, you will see the classic file browser to choose where to save your snapshot, with file name. However, if not, it will automatically save in the corresponding file. If you want to save in another file, you have to go to File menu, select Save As and click on Snapshot, or go to Snapshots menu and click on Save As.

image82 image83

Favorites

Bensikin manages a list of favorite context, so you can quickly switch to anyone of them. Those favorites are saved at application shutdown and loaded on startup.

Adding a context to favorites

To add a context to your favorites, have your context ready by creating or loading it. Then go to Favorites menu and click on Add selected context.

image84

Switching to a context in favorites

To switch to a context in favorites, which means to load it from favorites, go to “Favorites” menu, select “contexts”, and click on the context you want to load.

image85

Options

Bensikin manages global options. Those options are saved at application shutdown, and loaded on startup. The Options menu is located in the Menu bar: Tools -> Options.

Application’s history save/load Options

Define whether Bensikin has a history, i.e. a persistent state when closed/reopened.

If yes is checked, a XML History file will be saved in Bensikin’s workspace, and on next startup the current Context and Snapshot will be loaded.

../../_images/image69.png

Figure 16: Save option

Snapshot Options

These are the Bensikin Snapshot Options:

../../_images/image70.png

Figure 17: Snapshot options

  • In the Comment Panel, you can choose to automatically set or not a value to a new snapshot comment. This means, when you click on image89 button, the newly created snapshot will or will not have a pre-defined comment.

  • In the Comparison Panel, you can choose which columns you want to show/hide for every block in the Snapshot Comparison table. You can choose to show/hide the Difference block too (See Figure 14: Snapshot comparison - full table)

  • In the Export Panel, you can choose the column separator for your text-CSV formatted tables (See Figure 15: Snapshot edit clipboard dialog), and which columns to export.

Context Options

Context options allow you to select which way you want to edit your contexts, see Figure 8: Option –context tab and the Creating a new snapshot section.

The Bensikin toolbar

The toolbar is located under the menu bar, and consists mainly of a set of shortcuts to often used functionalities.

../../_images/image84.png

Figure 19: Bensikin toolbar

  • image101 is a shortcut to creating a new Context

  • image102 is a shortcut to saving the selected Context/Snapshot into a Context/Snapshot file

  • image103 is a shortcut to doing a saving all opened Contexts and Snapshots

  • image104 is a shortcut to printing the xml representation of the current Context/Snapshot

  • image105 is a shortcut to removing all opened Contexts and Snapshots from display