Group Control Migration

In order to properly setup your app in Group Control to have access to the apps, you need to use the Group Control Migration, so that you can use special functions to control both the app itself in Group Control and Roles. You will not be able to use Auth Core or control anything properly if you do not use these things. Of course, if you are developing a non-GC dependent app, then you don't need to use this class (and can go directly from AbstractMigration from Phinx), but currently none of our apps are not GC dependent.

Managing Apps

So, in order to add roles or be able to manage departments and access to an app in Group Control itself, the app itself needs to be added to the gc_app table. There are three functions to allow you to add, modify or delete the information about the app:

• addApp is used to add the app to the database, and it takes three parameters: the app code, the app name, and the app description.
• updateApp allows you to update the name or description of an app you have already added (you are not able to change the appCode for an app after it has been added), and it takes the same three parameters as addApp. While you can update apps through the Group Control app itself (because it is GC data), it is recommended for consistency sake that if you change the description, you use a database migration so it is the same on all databases.
• deleteApp allows you to delete an app which has already been added. It takes one parameter, just the app code. This will remove all departments and roles attached to the app as well, so it is advisable that this is only used in the down function.

Managing Roles

To manage roles, there are very similar functions to with managing apps. It must be noted, however, that roles are dependent upon apps. This means that when adding you will need to make sure addApp is used before any addRole functions are called, and when deleting, deleteApp will delete any roles that you added automatically, without having to call deleteRole.

• addRole allows you to add a role to the database. It takes three parameters: the name of the role, the app code, and the role description.
• updateRole allows you to update the description of the role (it requires both the role name and the app code to determine which role you are updating, thus they cannot be changed after they are added). It takes the same three parameters as addRole
• deleteRole takes two parameters: role name and short code, and it will remove the role from the database (as well as all users, groups and departments have that role).

Example

To see how each of these might be used, here is an example from the first migration of Message Center, which shows what types of descriptions might be helpful for the apps:

class One extends GroupControlMigration {

    public function up() {
        // adding all tables
        $this->addApp('msgc', 'Message Center', 'An app that allows users to send emails to each 
                other and also interact through a blog type environment with channels and threads.')
             ->addRole('base', 'msgc', 'Basic Role that allows the user to access the application.')
             ->addRole('admin', 'msgc', 'Role that grants the user permission to create email
                templates and channels.');
    }

    public function down() {
        $this->deleteApp('msgc');
        // dropping all tables
    }
}

Usage Tips for GC

While this is not technically to do with the Group Control Migration itself, there are a few things which may be helpful tools for you to use as you are preparing to setup the app to work in Group Control. First of all, if you need help setting up in Group Control after you have created this, you can check out our guide for how to set up an app in GC. Additionally, when creating roles, it is helpful to know that we usually have roles which are used very commonly within all the apps (not every role is used in every app, but they are very common). While you are not limited to these roles, knowing what they are and how they are used is helpful in creating your own roles.

The following roles are the minimum that are necessary for the apps to function, and thus every app has at least these two roles:

• admin is a role that typically will allow the user to have rights to view the "Admin Pages", which help you to set up the app for each department.
• base is a role that typically gives the user access to the basic functions of the app, but not anything more advanced.

There are a few other roles that are common in several apps, which may be helpful:

• supervisor is a role between admin and base, which gives the user all the access of the base role, but not as much as the admin. Typically there are a couple of additional items that the supervisor has above base, but it is usually much more similar to the base access than admin (for example, in status Base Users can only change their own status, but Supervisor Users can change anyone's status in the department, but that is the only difference)
• global-admin is a role that means that the user has access to administrator capabilities across departments. Usually it is used when there is certain setup which effects all departments, and thus creating a role above admin to control those elements of the app. Global Admin is the highest role and typically has access to everything without restriction even where an admin would be restricted.
• robot is a role that is used only when your app has nightly scripts, and unlike the other roles is not in the hierarchy in that it typically only gives the "robot" user access to the specific nightly scripts functions and nothing else.

Of course, if you need a more specific role than this, you are free to add it, you just need to make sure to have a good description for unique roles as they are harder to know what they do than other roles.

Finally, if you are curious as to what specific roles have access to in a specific app, you can look under the Help Menu, and look at the Permissions page, which will tell you what access each role has. As a developer, this page must also be kept up to date.