Menu related Permissions

In BB2 users navigate the various modules of the system using the main left-hand menu. Each main menu option then displays a number of different sub-menu links related to that module. Once a user accesses any of these sub-menu links he/she is able to use the top-level menu bar to navigate within and perform functions relating to that section. There are of course also a number of other links and buttons that make-up the various sections, and which appear outside of the top-level menu bar, on the various pages themselves. Together, all these menu options, links and buttons define the visual access level for any given user.

It is very important to understand the difference between this visual access level defined by menu options, page links and buttons, and the functional level of access defined by the actions a user is capable of performing, and the areas they have access to. These two layers one intuitively expects to amount to the same thing and to always be aligned with one another. However, although this should ideally be the case and most often is, the two do not necessarily always align automatically. This is because the two layers are granted using distinct permission sets. What this means is that it is both possible to access a section without having been given the permission to see the menu option or page link that links to that section (provided you know the correct link), and to see a particular menu option but not have access to the area it links to.

A helpful analogy would be that of a passage with a row of doors. The visual layer of the permissions determines which doors or options you are able to see. In order to open any of the doors and enter one must have the right keys. The functional layer of the permissions determines which of these doors you have keys for. Herein lies the distinction between having been granted the ability to see a particular menu option, page link or button, and having been granted the necessary permission set(s) associated with that menu option, page link or button. The former is a visual permission that is of no real use without also having the latter, functional permission that grants the user access to the area or function the menu option, page link or button merely denotes.

User session data & Menu cache

Whenever adding or removing menu/visual related permission sets to a user group be aware that these changes will only reflect once a user's session is refreshed and their menu cache cleared. This can be achieved by flushing the menu via the 'Menu Manager' and then having all users log out and back into the system. A quicker method is to instruct users to click the eye icon in their login details section, above the left-hand system menu and to the right of the 'Edit' link. This feature allows users to rebuild their user session and flush their menu cache without having to log out of the system. In any event it should be noted that, unlike other functional related permission changes, changes to a user group's visual or menu-related permissions will not be applied simply by having users log off and log back in.

Main-Menu Items

Let us begin then by identifying the permission sets required for making main-menu options on the left-hand system menu visible. In order to enable a main-menu item (e.g. 'Sales') for a specific user group, the permission method 'enable_menu' must be granted for the permission class associated with that menu item (e.g. 'bb_sales_menu'). The naming convention pattern ensures that, save for the odd exception, the permission class related to any main-menu item would be in the format, 'bb_menuname_menu'. The applicable method relating to any of these permission classes is always 'enable_menu'. Once the 'enable_menu' method is granted for a permission class relating to a main-menu item, members of the group to which it was granted will be able to see that top-level menu item in the system menu.

Sub-Menu Items

Main menu items broadly reflect the various modules of the system. Hovering over any one of these top-level menu items will display a list of sub-sections associated with those modules. For each of these sub-menu items there is a corresponding permission set. In order to enable a sub-menu item (e.g. 'Sales Orders') for a specific user group, the permission method 'enable_menu' must be granted for the permission class associated with that sub-menu item (e.g. 'bb_sales_orders'). As before, the naming conventions guarantee that, as a general rule, the permission class related to any sub-menu item be in the format, 'bb_submenuname' (with each word used in the sub-menu name separated by an underscore).

The applicable method relating to any of these permission classes is always 'enable_menu'. Once the 'enable_menu' method is granted for a permission class relating to a sub-menu item, members of the group to which it was granted will be able to see that menu item in the system menu. If the user group has not been granted access to the main-menu item under which the sub-menu item is naturally designated, then it will appear as a top-level item until such time as the permission to the parent menu-item is also granted.

Again I must stress that both the top-level and sub-menu item permission sets outlined here only relate to the visibility of these options in the system menu and not to the system functionality/sections to which they refer.

Top-level Menu Bar

The top-level menu bar appears right throughout the system at the top of every module section (e.g. 'Module Home' and 'Data Functions'). The top-level menu bar options differ from one module or section to another, depending on the functionality each module offers and the actions relevant to that section. For instance, when on the 'Sales Dashboard' page there is a 'Sales Orders' top-level menu option. This link is relevant to the Sales module and does not appear anywhere in the top-level menu bar in the Publishing module.

In order to enable the top-level menu bar and make it visible for any particular section you must grant the permission method 'menu_bar' for the permission class related to that section. So, granting the 'menu_bar' method for the 'bb_sales' class will make the top-level menu bar visible on the Sales Dashboard. Enabling the top level menu bar for any given section merely makes the menu bar options relevant to that section visible to a user, but does not automatically grant the user access to the areas of the system each of those menu options link to. Thus, in addition to enabling the top-level menu bar, the user must be granted the relevant permission set(s) associated with each top-level menu option.

Data Functions 

The 'Data Functions' top-level menu bar link provides users with a number of data related options, each of which relates to a specific permission method that must be granted in order to be populated in the 'Data Functions' menu list. The following list details each of these permission methods, and the data functions menu options they are associated with. Where the permission class is not specified, please note that the correct class to grant the following methods for would be the class associated with the section of the system you wish to make available these menu options for (e.g. granting them for the 'bb_sales_orders' class would add them to the top-level menu bar of the 'Sales Orders' module).

• The 'Tree' menu option requires the 'showTree' method
  (for more information on the tree view please refer to the help article titled, 'Tree View: An overview'  at http://www.bluebox.co.za/?showkm&global[uid]=291-(2.System-Basics)-Tree-View:-An-Overview).
• The 'Add' menu option requires the 'add_form' method (allows a user to add data).
• The 'List' menu option requires the 'viewlist' method (allows user to list data).
• The 'Search' menu option requires the 'search_form' method (allows a user to search/filter data).
• The 'Export' menu option requires the 'export_form' method (allows user to export data).
• The 'Import' menu option requires the 'import_form' method (allows user to import data).
• The 'Attach Files' menu option requires the 'attach_files' method.
• To add the 'Quick List' option to your 'Data Functions' menu bar for all sections you need only grant the following permission set: Class: 'bb_module_quick_list', Method: 'default_method'.
• The 'Apply Default Data' menu option requires the 'default_data' method.
• The 'Show System Data' menu option requires the 'admin' method.  
  
  

The following 'Data functions' menu options are only available when logged in as the System Administrator and cannot be made accessible to another user by granting their corresponding permission methods. This is due to the severity of the actions associated with these data functions.

• 'Delete All'
• 'Drop Column'
• 'Drop Table'
• 'Raw Data'

Permissions

In BB2 users gain access to the various software modules and particular functions within those modules by becoming a member of one or more user groups (e.g. 'Sales' or 'Admin'). Permissions are first added and applied to user groups before users can inherit these permissions indirectly through their association with these groups. Thus, a well organised system will include a user group for each particular level or type of access required by the users that access it. This allows users to very quickly be granted the precise scope of access they require simply by being added to the relevant user groups that together define the breadth and depth of that access.

Permission Sets: Class & Method

Permissions are made up of two component parts, namely 'class' and 'method'. The permission class defines the boundaries of the permission set. These boundaries often coincide with a specific system module (e.g. Publishing or Inventory ) but can also demarcate an area that applies to more than one module. Each permission class is made up of a 'bundle' of permission methods. Each permission method defines a particular action, view or function that may be performed within the demarcated area of the permission class (e.g. list, add or edit). Methods are generally universal in the system and so the same bundle of methods that make up one class are generally replicated and bundled together with every other class.

For example, the 'bb_sales_debtors_invoices' class refers to the debtors invoices section within the sales module, and the 'bb_procurement_creditors_invoices' class refers to the creditors invoices section within the procurement module. Both of these classes have a permission method called 'viewlist' which allows users, in the case of the first class, to view a list of debtor invoices, and, in the case of the second, to view a list of creditor invoices. The method works in exactly the same way in each instance but relates specifically to the area of the system defined by the class to which it belongs.

There are of course exceptions to this general logic. Some permission classes have custom methods that are only relevant to that particular class. The 'bb_inventory' class associated with the Inventory module contains a method called 'inventory_dash'. This method relates specifically to the inventory dashboard view and is therefore unique to this class.

Setting up and Managing Permissions

The BB2 Permissions Dashboard section is accessed via the 'Admin' module on the left-hand main menu. From here it is possible to manage the scope of access granted to each user group on the system by adding or removing permission sets that together define the kind of access bestowed upon each group's members.

First select the user group you would like to manage permissions for from the 'Choose User Group' field. If the user group you intend to define permissions for has not yet been added then you will need to create the user group first. This can be done via the 'User Groups' sub-menu item, under 'Admin' on the left-hand system menu. For more help with adding user groups consult the Bluebox knowledge base: http://www.bluebox.co.za/?km.

Next, use the 'Filter' field to return a list of the permission classes you would like to work with. For instance, typing in the word 'sales' would return all permission classes with the word 'sales' in the class title. Click the 'Go' button to return a list of permission classes that match the string of characters you provided in the filter field. Leaving the filter field blank will simply return all permission classes, allowing you to add or remove permission methods for the selected user group from any one of the permission classes.

Now locate the permission class you wish to add or remove permission methods for from the class list. Click the green '[View]' link (View Method List) to the right of the permission class name to expand the list of permission methods for that class. Remember that permission sets are made up of class and method. For the chosen class you must now select which of its specific methods to grant or deny for the current user group. For every permission method already granted to the selected user group there can be seen a positive selection mark to the left of the method name, under the 'Grant' column. To grant a specific permission method for this permission class, locate the method in the method list for that class and then click the selection option to its left, under the 'Grant' column. In this way permission sets, containing the permission class and the method within that class, are assigned to the chosen user group.

To grant all permission methods and thereby allow members of this user group to make use of any method in this permission class, click the selection under the 'Grant' column, to the left of the 'all' method. To remove a specific permission method for this permission class, locate the method in the method list and then click the selection option to its left, under the 'Remove' column, to remove it from the current user group.

Follow this same process for each and every permission class whose methods you would like to assign to the user group. Once you have completed adding and/or removing permission sets for the selected user group, scroll right to the bottom of the permission class list, and click the 'Set Permissions' button to apply these changes. All that is now required is for members of this group currently logged into the system to refresh their session data.

Linking Users to User Groups

Once you have set-up permissions for user groups all that is required is for users to be linked to the appropriate combination of groups. The right combination of groups will depend entirely on what the user's duties on the system include and on the available user groups and their permission settings. Ultimately, a user should be linked to the minimum amount of groups that afford just enough access to perform those duties. For instance, if a new employee has joined the Sales team and is required to have access to both the 'Sales' and 'Marketing' modules then they would be linked to the 'Sales' and 'Marketing' user groups, provided these groups allowed access only to those particular modules.

Users can be linked to user groups either via the 'User Groups', or 'Users' sections found under the 'Admin' module on the system menu. When viewing the user groups tree click the '+' icon ('Add New Link') to the right of the user group you wish to add a new member to. This will allow you to select a new user to link to that user group, resulting in the user being listed under the user group in the users tree.

Alternatively, go to the 'Users' section and, once loaded, click the 'Data Functions' top-level menu link. Then click the 'List' option in the menu that appears to list all user records. Locate the user you would like to link to a user group and then click the eye icon ('View') to the left of the user record, under the 'Action' column. Once the user view page has loaded scroll down to the section titled 'User Groups Link'. Click the '+' icon in the top right hand corner of this section to add a new user group link for this user. Remember, users can be linked to multiple groups, so create as many links as required.

Access Denied: Resolving Permission Failures

Whenever a user tries to access an area of the system that they do not have explicit permission to view, or whenever they attempt to perform a particular action (e.g. add, edit, delete) they have not explicitly been authorised to execute, the system returns a permission failure message. These messages outline the specific permission set (class and method) that the current user has not yet been granted, and which is required in order to access the relevant system area. To illustrate this, let us consider the following permission failure message:

“Permission failure for Class: sales and Method: show”.

From this message we are able to determine that the action or section the current user is trying to access requires the 'show' method for the the 'bb_sales' class. Together this class and method form the required permission set that must first be granted to the user before satisfying the permission requirements for that action. The permission failure can be bypassed either by granting this permission set to a user group the user is already a member of, or by adding the user to a user group that already includes this permission set. In each case the user must inherit the permission set indirectly by means of his/her membership to a user group. Once this is done the user need only refresh their user session data. This is achieved by clicking the eye icon in the login details section, above the left-hand system menu and to the right of the 'Edit' link. Once the user's session has been refreshed all permission changes will be applied to the user's current session.

It should be noted that often multiple permission sets are required before gaining access to an area of the system. So, referring back to the above example, even though the user has since been granted the 'show' method for the 'bb_sales' class and refreshed his/her user session data, the system may then display a second permission failure message such as:

“Permission failure for Class: sales and Method: viewlist”.

From this we can determine that the section the user is trying to access requires more than one permission set. Although they have been granted the first permission set, the system now prompts them on the second permission requirement, namely the 'viewlist' method in the 'bb_sales' class. In each case the user must be granted the permission set defined in the permission failure message and then refresh their user session data before reattempting to perform the desired action, or to access the desired section in the system.

Granting users access only to those permission sets necessary to carrying out their specific tasks on the system is a recommended security practise. However, when a user group needs access to an entire section or where security is of little concern, the 'all' method can be granted for any permission class, allowing members of that group to inherit all permission methods within that class in one easy step.

Data Functions: The Ins & Outs

In this article I will be focussing on two areas of the system that users most commonly require data to be exported from and imported to at one time or another, namely User Records & Groups, and Content Items & Categories. Perhaps you're having trouble importing a list of existing clients into the system in order to send out your monthly newsletter, or other business communications to. Similarly, you may be wondering how to import a list of all your staff members, each of which require various levels of access to the system. In these instances the data would need to be imported to the user group and user record tables.

Alternatively, you're possibly uncertain of the correct process to follow in order to update the content structure of your website by adding or removing content categories and content items displayed on its pages. In this circumstance the updated content would need to be imported to the content category and content item tables. It should be noted that, despite my focus on these two data types, every data table in BB2 can be output and input in much the same way, and thus the principles covered here apply to every system module and can be used as a model.

File Format

BB2 data is exported as a CSV file and must be imported in the same file format. CSV stands for Comma Separated Values and is a simple, plain text format that stores database information one record per line, separating each field within that record with a comma. It shall be assumed that you have an editor capable of reading and manipulating .csv files, such as Microsoft Excel or OpenOffice.org Calc.

Where do I Start?

Data tables are imported and exported by means of the 'Data Functions' top-level menu option. The starting point in each case is the same: navigate to the section that corresponds with the data you intend to export or import, click the 'Data Functions' menu link, and then select either 'Export' or 'Import' from the menu list that appears. For instance, if you are intending to import/export user records then go to the user records section by hovering over 'Admin' in the main left-hand menu, and clicking the 'Users' sub-menu link. If you want to import/export content categories then go to the content categories list by hovering over 'Publishing' in the main left-hand menu, clicking the 'Content System' sub-menu link, and clicking the 'Categories List' link under 'Tools'.

Data Table Basics:

Although a basic understanding of how BB2 data is structured and the logic behind this design is not necessary in order to successfully export and import data, it may nonetheless prove useful in achieving first-time, accurate results and avoid painful, time-consuming errors.

Don't get confused between 3 types of table prolific in BB2:

1. Data tables: these contain the actual data items such as the user records and content items. Each record/ item is assigned a unique number (id).
   
   Examples: bb_users and bb_content
   
   
2. Group Tables: these contain the different categories that the data items listed in the data tables can be grouped by. They could be content categories that separate the content displayed on your website into different sections, such 'Home', 'About us', 'News' etc. They could also be user groups ('Sales', 'Marketing', 'Management' etc.) which user records can then be linked to. Each category or group record is also assigned a unique id.
   
   Examples: bb_users_groups and bb_content_categories
    
3. Link Tables: the purpose of these tables is merely to create a relationship between data items found in data tables, and the data item groups found in group tables. This is achieved simply by matching a unique data item id with a unique data item group id. This is what makes it possible for users to link to one or more user groups, and for content items to be linked to one or more content categories.
   
   Examples: bb_users_groups_link and bb_content_categories_link

The most important thing to remember here is that although these three tables work closely together in each section, each table contains a different set of data with its own unique set of id's. As a result you should always be aware which table type your import data is targeted at and never mistakenly import it to one of the other table types.
 

Exporting

There is no real risk involved in exporting data. In the worst case scenario you export the wrong data and try again. Having said that, getting the correct data out of the system can often be just as important to you as it was once to get it in correctly. The first step is to navigate to the section of the system that correlates most accurately with the data you are after. Exporting user records requires that you go to the 'Users' section (bb_users), whereas exporting user groups requires that you go to the 'Users Tree' view (bb_users_groups). In the same way, to export content items go to the Content List (bb_content), and to export content categories go to the Categories List (bb_content_categories). Once you have found the section of the system related to the data to be exported, click the 'Data Functions' top-level menu option, and then click the 'Export' option in the menu list that appears.

Export Structure

Your first option is to customise the structure of your export, or to export the default structure which will include all fields. The data export screen will display the fields to be exported. To stop a field from being exported uncheck the corresponding check-box located to the right of that field's name.

It is also possible to change the order of the fields/ columns in your export. Fields can be repositioned (this will move the columns in the actual csv file) by clicking and dragging the field to the position that you would like it to appear in.

Field column names can be changed by clicking the name shown after the field name (this will default to the field name). For instance, next to the 'Name' field the text “name as name” appears. To change the header for this column from 'name' to 'Surname', click the text that appears after 'as' and type in the word 'Surname'. This can always be done afterwards when editing the .csv file.

Any field that has linked data can also be exported in the same csv file by clicking on the drop down and selecting one of the linked data fields. Note that additional fields can be added to the export by clicking the [+] icon.

Export Data

Once you are happy with the structure of your export file you can choose which data to export within that chosen structure. In order to have only a defined set or group of data included in the export, provide the criteria necessary to identify/filter that data in the data input boxes found below the field check list. For example, supply the id range of the desired user records or content items etc. If you do not provide any data filter criteria the system will include all data available for the chosen fields.

Saving your Custom Exports

No matter what section you export data from there is the option to save your export field selection as a custom export. This custom export can then be selected in future, instead of having to define all the fields you wish to include/exclude from your export each time you wish to export the same information in a particular structure. This can prove very useful and save a lot of time for regular exports. It should be noted, however, that the custom export only saves the export field structure and not the data criteria specified (Id range, Name, description etc.).

Once you are happy with the field structure of a particular export, click the link at the top of the page, directly above the export field list that says, “Click Here to add a New Ordered List Filter”. Provide a name for your custom export selection in the 'Name' input box and click the 'ADD' button to save it. Once saved, continue with your export by scrolling to the bottom of the page and clicking the 'EXPORT' button.

Whenever you need to use this custom export again, navigate back to the same section you last exported data from and click the 'Export' link in the 'Data Functions' menu list. Then simply select the custom export from the 'New Ordered List Filter' drop down at the top of the export page.

Importing

The stakes are a lot higher when it comes to importing. You want to take all the precautions necessary to help insure current data is not overwritten for the wrong reasons, and/or data is not imported to the incorrect location. In other words, you want to avoid importing the wrong data to the right place, the right data to the wrong place, and, of course, importing the wrong data to the wrong place (which doesn't help much either).

Location, Location, Location.

When importing data it is crucial that you do so from the correct location since the location determines where the data is imported to. So, for instance, attempting to import users from the 'User Groups' section will result in each user record being imported as a user group. Furthermore, if a user record id was specified for any of the records in your import file then the system will treat these as the user group id's and update/overwrite user groups matching those id numbers with the user record details. Please refer again to the section above titled 'Data Table Basics'.

In other words, the system is not going to examine your import file and make a decision based on its content as to which system table or section the data should be imported to. On the contrary, you make the decision yourself by choosing the section from within which to click the 'Data Functions' top-level menu option and run through the import process via the 'Import' link.

Use the source, Luke.

There are a number of good reasons why you should always export the data table you intend to import before attempting the import. To begin with, you may well be anxious to import your data from the correct location but remain uncertain of whether the location you have chosen is indeed the one that corresponds directly with the data you intend to import. Exporting data from this location will immediately show whether it is correct or not, because if the type of data found in the export matches the data you are trying to import then you're in the right place. For example, if you're about to import content items, and, upon performing an export from your chosen location, you find that the exported data lists content categories then you know that you are in the wrong section.

The second reason why it is best practise to model your import file on an exported file of the same data table, is that it insures the structure and column names used in your import are accurate. This eliminates a number of unnecessary errors by relying on a file generated and used by the system itself, rather than a file compiled by human “hands”. Remove the columns you do not intend to use (save for the '_id' column which is always required), and use the shell of the export file as the structure for your import by replacing the export data with your own.

Finally, working from an export is absolutely critical when updating records because the correct id no. for each record must by supplied under the '_id' column for the system to find and update those records with the correct data. An export will list these id's for you next to each record and therefore insure your import matches and updates the correct data.

_id's Please

It is very important to distinguish between two different types of records in an import file. The first record type is one that does not yet exist on the system and which is therefore being imported/added for the first time. The other type of record in an import is one that does already exist on the system and which is intended to edit/update the matching record on the system. One import file may consist entirely of one of these record types, or, more commonly, a mixture of both.

The golden rule to remember is that records in the import file aimed at updating pre-existing records in a system table must have the correct id's provided in the '_id' column. The system uses each unique id number to find the matching records in the table you are importing to and to update those records with the information supplied for each in your import file. Wherever an id number is specified in the '_id' column the system will first attempt to find the matching record and update it. If a record with that id number does not exist then a new record is created with the id specified.

If, on the other hand, you are importing new records that do not yet exist on the system then make sure no id numbers are specified for each of those records in the '_Id' column of your import file. The system will assign each of these records the next available id number when it adds each of the new records to the system table. If, as is most often the case, your import file includes both record types then ensure the above rules are followed according to these types.

Stay cool, Murray. What's the hurry?

One last faithful habit to cultivate; a ritual that has saved many a desperate soul in the dark hours of need that so often follow a reckless moment, is that of backing up data before attempting to manipulate it by import.

BB2 is equipped with a very user-friendly backup module, accessible via the 'Admin' menu item on the system's left-hand menu. Once your system's data has been backed up, it can easily be restored to its former state in the event of an unforeseen import “complication”. For more information on how to use the backup module please read the article titled 'System Backup Module' which can be found in the Bluebox knowledge base (www.bluebox.co.za/?km).

Another way of creating a backup is to export and save all the data for each of the tables you are intending to manipulate via the import. This will allow you to simply reimport these 'master' copies if the import yields any mildly catastrophic results. Be sure to export all three data table types (data, group, and link tables) for the relevant section just to be entirely certain that you have everything you need to find your way back to the pre-import state of affairs. Refer back to the section above called 'Data Table Basics' if you can't recall the significance of each of these data table types.

The LINKTABLE bypass

This section outlines a very handy short-cut to importing data items (such as user records or content items) and linking them to data groups (such as user groups and content categories) in one import. This is an alternative to the typical two step process of 1) importing the data table, and then 2) importing the link table to link the data records in the data table to the correct groups in the data groups table.

Please note that this short-cut works on the assumption that the relevant groups have already been imported/added to the groups table so that they can merely be linked to the data in the data table via the short-cut process.

The short-cut requires only that you add an additional column to the end of your import file structure called 'LINKTABLE_bb_data_groups_link', where 'bb_data_groups' refers to the relevant group table associated with the data being imported. So, if you are importing user records then the column would be called 'LINKTABLE_bb_users_groups_link', and if you are importing content items then it would be 'LINKTABLE_bb_content_categories_link'.

Below this new column, and for each data record (i.e. user record or content item for example), provide the id no. or the name of the group/category you wish to link that data record to. If you are importing a user called 'Bob' and want him to be linked to the 'Management' user group, then you would put either the text “Management” or the id no. of the management user group (e.g. “10”) beneath the new link table column and on the same line as Bob's user record. The very same logic would apply when attempting to link a content item to a pre-existing content category.

Lastly, data items can also be linked to multiple content categories at once by adding another link table column (e.g. 'LINKTABLE_bb_users_groups_link') for each group link required. In each case a number must be added before the column name corresponding with the number of link table columns used. E.g. '1LINKTABLE_bb_users_groups_link' for the first link table column, '2LINKTABLE_bb_users_groups_link' for the second link table column. Remember that these examples are specific to user records, so change them according to the section you are importing to.