Introduction
VConsole comes with a great built in feature. The ability to create, manage, and assign permissions. This allows you, as a VConsole developer, to create multiple permissions and it allows your clients, as users of the software, to create groups and assign those permissions to the groups of their choice. So, you define what permissions exist, and your clients or users of the software say who has those permissions. Your users can even setup multiple organizational units (or accounts) that allow administrators to delegate control of those units to other users. Read on to find out how all this is done.

Module Permissions
As you may have read in previous pages in this documentation, there are 4 types of modules. Data Manager Modules, Wizard Manager Modules, Properties Manager Modules, and Basic Modules. Each module can have 1 or more permissions created for it. If no permissions are created for the module, then it is assumed that everyone has access to the module and all actions provided by the module.

In the case of Wizard Manager and Properties Manager module types, you can usually only create 1 permission that either allows access to the module or not. This is because all the module file does is create the data structure and hand control off to the wizardmanager() or propertiesmanager() functions, so an access / no access permissions seems appropriate. If you want to create multiple permissions for these types of modules, then the one thing that you could do is check permissions and create a different data structure based on those permissions. (See The Wizardmanager or The Propertiesmanager for more information on these module types)

In the case of Basic module types, you can create as many permissions as you want, but you have to check those permissions manually within your main.php file and do something different based on the results. To check permissions manually, use the following funcions:

• check_permissions()
• check_action_permission()
• check_module_permission()

And finally, in the case of Data Manager module types, you can (and should) create a permission for each action that exists within the module. (See Data Manager Actions for more information on actions) The entire infrastructure that gives access to certain actions within a Data Manager type module is already created for you. All you have to do is create the permissions as described below.

Creating Permissions
You create permissions by simply adding records to the vc_modules-actions MySQL table. Each record in this table is considered a permission which can be assigned to 1 or more user groups. First, we will go over the different fields in the table, what they mean, and what you should put:

• id - This is the primary key for the table. It is an auto-increment field so you should just leave this blank and the number for this field will be auto generated.
• module - This is the name of the module that the permission refers to. This should match the name of the module as in the vc_modules table (module field). You can create multiple permissions for each module.
• action - This is the name of the module action. It should match the name of the action file as in the vconsole/modules/<module>/actions/ folder (without the .php extension). If the module is not a Data Manager type module, then you can put whatever you want here as long as it is lower case alpha-numeric, starts with a letter, is at least 3 characters, and is no more than 20 characters. (These are the recommended naming conventions for this field.). If you just want to control access to a non Data Manager type module, we recommend setting this field to access
• button - This field is optional and is ignored unless the module for this permission is a Data Manager type module. If you put anything here, you should put the name of a button as required by the getimage() php function. You can pull up showimages.php in a browser to list the different types of buttons that can go in this field. (Only buttons are allowed here, not icons) This field allows users to add the button to the Top Navigation bar using the "Customize Toolbar" button or you can make it visible by default.
• order - This field is optional and is ignored unless the module for this permission is a Data Manager type module. This field is also ignored if the button field is left blank. If you put anything here, it should be an integer that determines the order of the button in the top navigation bar. If you put a positive integer here then the button (defined by the button field) is shown by default in the top navigation bar and the user does not have to add it using the "Customize Toolbar" button. But, the user cannot get rid of the button either. If you set this to -1, then the button will never be shown and the user cannot add it. If you set this to 0, then the button is not shown by default, but the user can add it to the toolbar using the "Customize Toolbar" button if they wish.
• name - This field is required only if the module for this permission is a Data Manager type module and the order field is not a negative value. It is used as the human readable name when the button is shown in the top navigation bar.
• perm - This field is required. It is the human readable description of what this permission allows and is shown to users when assigning permissions to groups. Something like "Delete Records" or "Allow Access" is appropriate.
• help - This field should contain a small 1 or 2 sentence of what the permission does. It is only used as the hover help box for when users hover their mouse over the button in the top navigation bar. This field is ignored unless the module for this permission is a Data Manager type module.
• conf - This should be set to a human readable confirmation message to show to the user when they click on the button in the top navigation bar. The content of this field will be passed to the javascript confirm() function so no HTML is allowed. If set, then the user has a chance to cancel the operation. This field is ignored unless the module for this permission is a Data Manager type module.
• alwaysallow - This field should be set to 1 or 0. If set to 1, then no permission checking is done on the module before the main module file is executed. This doesn't mean that everyone should have access, this only means that you have to check permissions on the module manually. Set this to 1 if you want to do your own custom permission checking.

Creating Permissions For Wizard Manager and Properties Manager Modules
Creating permissions for these 2 module types is very simple. This is because you would normally just create a single permission which determines whether or not a user has access to the module. Simply create your entry in the vc_modules-actions table. That's it. Here is an example of what we would put in each field in the vc_modules-actions table.

• id - Leave blank.
• module - Enter the name of the module.
• action - Set to: access
• button - Leave blank.
• order - Leave blank.
• name - Leave blank.
• perm - Set to: Allow Access
• help - Leave blank.
• conf - Leave blank.
• alwaysallow - Set to: 0

Creating Permissions for Basic Modules
Creating permissions for basic modules is a simple matter of making all your entries in the vc_modules-actions table and then, in your main module file (main.php), you should check permissions and do something different based on the results. You can check to see whether or not the currently logged on user has access to a permission by using the check_action_permission() function. Here is a quick example.

Creating Permissions For Data Manager Modules
To create permissions for Data Manager type modules, you have to create all your entries in the vc_modules-actions table. You should create a single entry for each action in the vconsole/modules/<module>/actions/ folder. If you don't create an entry for each action file in the actions folder, then anyone will have access to those action files that you don't create an entry for. Also, each permission can be shown in the top navigation bar if you choose to allow that. Putting an action in the top navigation bar should be done for those actions that do not operate on data records. One example is an action that creates a new record. It doesn't make sense to have to right click on an existing record in order to create a new record. Therefore, you should put the action in the top navigation bar so that user's can easily click on it to create a new record. Also, you can put actions in the top navigation bar even if the action requires 1 or more records to operate on. You should just include the correct logic in your action file to check that at least 1 record was selected, and you should set an error message if no records were selected. We will go over some common scenarios below.

Creating A Permission For A Data Manager Module That Cannot Be Added To The Top Navigation Bar
If you want to create a permission for a data manager type module that cannot and should not have a button on the top navigation bar, all you need to do is create an entry in the vc_modules-actions table that has the order field set to -1. This tells VConsole to never show the action in the top navigation bar.

Creating A Permission For A Data Manager Module That Is Not On The Top Navigation Bar By Default, But Each User Should Be Able To Add It To The Top Navigation Bar If They Want To.
In the case that you have an action that you want users to be able to add to the top navigation bar as a button if they want to, all you need to do is create an entry in the vc_modules-actions table that has the button field set to a valid button name, the name field set to a human readable button name, and the order field set to 0. When these conditions are met, the user can add the button to the top navigation bar using the "Customize Toolbar" button in the top navigation bar. We will show an example that has a module name of invoices, an action name of add, and is used to create a new invoice. Here is the example:

• id - Leave blank.
• module - Set to: invoices
• action - Set to: add
• button - Set to: trash
• order - Set to: 0
• name - Set to: New Invoice
• perm - Set to: Create New Invoices
• help - Set to: Click to create a new invoice
• conf - Set to: Are you sure you want to create a new invoice?
• alwaysallow - Set to: 0

Creating A Permission For A Data Manager Module That Is Always Shown On The Top Navigation Bar
If you want to create a permission for a data manager type module that is always shown on the top navigation bar, all you need to do is use the "New Invoice" example above except set the order field to a positive integer like 1 or 2, etc... Buttons that should always be shown in the top navigation bar are shown from left to right based on the order field from lowest to highest. The only difference between a button that is always shown in the top navigation bar and a button that can be added by the user is the order field is set to 0 for buttons that can be added and the order field is set to a positive number for buttons that are always shown.

Creating A Permission For A Data Manager Module That Does Not Have An Associated Action File.
There may come a time that you want to create a permission for a data manager type module that does not have an associated action file in the actions folder. One example of this is when you want to control what records the user can see. Let's say you want to create a permission called listall that controls whether they can see all records or not. If the user does not have this permission, then they can only see records which they have created. Good news, this is possible. All you have to do is create your permission entry in the vc_modules-actions table and then change the queries in the dms.php file based on whether or not the user has the listall permission. You can check to see whether or not a user has access to a permission by using the check_action_permission() function. (See the example above). You should set the order field to -1 so that the button can never be shown.

These types of permissions that do not have an associated action file are called custom permissions. We call them custom permissions because you have to use the check_action_permission() function to check if the current user has access to the permission and then you have to somehow change the behavior of your module based on the results.