IJC Tutorial: Filtering items using roles

    This guide describes how to configure role based filtering in an IJC schema. This will allow your organisation to control access to the various schema objects for specific users, using role filters. For instance, you might want to hide particular data trees or fields from your biologists, but show them to your chemists and vice versa. This guide explains what you need to do to set up your users with specific roles.

    {primary} There is also a startup option that lets you show a particular data tree (and hide all others). This is described in the IJC URLs page of the user guide. The method described there may be simpler and more convenient, but the approach described in this document is much more secure and rigorous.

    How it works

    The IJC schema items (data trees, entities, fields etc.) are defined in the IJC_SCHEMA table in the schema's database. Each schema item has it's own row in this table. When IJC connects to a schema it reads all the items for that schema from it's IJC_SCHEMA table and loads them for access for each user. Some organisations might wish to limit access to some items based upon each user's role within the company.

    Some items can be hidden from particular users. In fact, it is better to think of it as allowing particular items to be visible to the most relevant users of those objects to reduce over all complexity. You can do this by defining a role which you want to use for such a purpose. Lets assume we want to create a role named 'ROLE_CHEMIST' which we can then assign to all of our chemist users and a role named 'ROLE_BIOLOGIST' for our Biologist users. We can then make certain data trees visible only to Chemists and Biologists users as appropriate. When the setup is complete IJC will only make relevant data trees accessible to users who have the roles that allow them access. Lets see how to do this.

    1. Creating the roles

    In order to access the relevant system tables, this must currently be done directly in the database. Connect to the RDBMS with your favourite tool. See the Using the database explorer tip from the user guide if you want to use the Database Explorer that is provided in IJC for this.

    The role(s) must then be inserted into the IJC_AUTHORITIES table. Do this like this:

    
    insert into IJC_AUTHORITIES (AUTHORITY,DESCRIPTION,RANK) values ('ROLE_CHEMIST', 'Any chemist', 10);
    
    insert into IJC_AUTHORITIES (AUTHORITY,DESCRIPTION,RANK) values ('ROLE_BIOLOGIST', 'Any Biologist', 11);

    {primary} You can create and name, any number of extra roles you want, but you must not delete or modify the 4 existing standard IJC roles: ROLE_USER, ROLE_EDIT_DATA, ROLE_EDIT_SCHEMA and ROLE_ADMIN. The RANK property affects the order in the 'User management' interface that the roles appear in IJC. Before you set this value for your new role, you should check the existing values that are already in use in the table and not duplicate.

    2. Associating the role to the user

    You should have at least one IJC user available for each role. Whilst connected as admin and if you have not already done so, create a new user 'ChemistA' and 'BiologistA'. If you have not done so, you will first need to set up a security policy. Once complete, open the 'Security settings' in the 'Schema' section of the schema editor and look at the 'User management' tab. Click on the 'Add User...' button and you should see you ROLE_CHEMIST/ROLE_BIOLOGIST roles that you can assign to one of your users. Add or edit your users as appropriate and give them the new roles in addition to ROLE_USER (but not ROLE_EDIT_SCHEMA). Once the users are created, assign the role ROLE_CHEMIST to ChemistA and ROLE_BIOLOGIST to BiologistA by selecting update settings and then ticking the relevant role for the user.

    images/download/thumbnails/1806026/5_1_add_chemist.pngimages/download/attachments/1806026/5_2_add_biologist.png

    3. Associating the role to the schema item

    Now create 3 data trees in the schema for this example - this can be done directly in IJC schema editor (right click, New Data Tree from entity... or different). Initially we are going to restrict access to two data trees to our chemists and one to our Biologist, then we will share one data tree between each. First identify the appropriate data trees in the IJC_SCHEMA table. This query will help:

    
    select SCHEMA_ID, ITEM_ID, ITEM_VALUE from IJC_SCHEMA where GENERIC_TYPE = 'DATATREE';

    Make a note of the SCHEMA_ID and the ITEM_ID for two datatrees that you wish to filter for chemist only access.

    Now insert two rows into the IJC_SCHEMA_AUTHORITIES table, using the syntax below, that associates ROLE_CHEMIST with those particular data trees (of course you will substitute your values for <schema_id> and <item_id>):

    
    insert into IJC_SCHEMA_AUTHORITIES (SCHEMA_ID, ITEM_ID, PROPERTY, AUTHORITY) values ('<schema_id>', '<item_id>', 'VISIBILITY', 'ROLE_CHEMIST');

    {primary} If an item has no roles associated with it is is accessible to all users. e.g. initially the item is accessible to all users, but as soon as you associate one role to it then it is restricted to only that role.

    Now login as the user ChemistA who has been assigned the role ROLE_CHEMIST. All 3 data trees are visible, 2 are assigned and one which is currently unassigned defaults to visible.

    Now login as the user BiologistA who has been assigned the role ROLE_BIOLOGIST. Only 1 data tree is visible which is currently unassigned. The ROLE_CHEMIST has been associated with 2 data trees hence any user without that role i.e. BiologistA will only see the 1 unassigned data tree.

    Now insert one row into the IJC_SCHEMA_AUTHORITIES table, using the syntax below, that associates ROLE_BIOLOGIST with the currently unassigned data tree (of course you will substitute your values for <schema_id> and <item_id>):

    
    insert into IJC_SCHEMA_AUTHORITIES (SCHEMA_ID, ITEM_ID, PROPERTY, AUTHORITY) values ('<schema_id>', '<item_id>', 'VISIBILITY', 'ROLE_BIOLOGIST');

    Now login as the user ChemistA who has been assigned the role ROLE_CHEMIST. Only 2 data trees are visible which are the 2 assigned to ROLE CHEMIST.

    Now login as the user BiologistA who has been assigned the role ROLE_BIOLOGIST. Only 1 data tree is visible which is the 1 now assigned to ROLE_BIOLOGIST.

    
    You can add as many filters as you want to this table. e.g. you can specify multiple roles for any particular item just by adding additional rows to the IJC_SCHEMA_AUTHORITIES table. The user need only be in one of the specified roles to see the item.

    Now insert one row into the IJC_SCHEMA_AUTHORITIES table, using the syntax below, that associates ROLE_BIOLOGIST with one of the data trees that is also assigned to ROLE_CHEMIST (of course you will substitute your values for <schema_id> and <item_id>):

    
    insert into IJC_SCHEMA_AUTHORITIES (SCHEMA_ID, ITEM_ID, PROPERTY, AUTHORITY) values ('<schema_id>', '<item_id>', 'VISIBILITY', 'ROLE_BIOLOGIST');

    Now login as the user ChemistA who has been assigned the role ROLE_CHEMIST. Only 2 data trees are visible which are the 2 assigned to ROLE CHEMIST.

    Now login as the user BiologistA who has been assigned the role ROLE_BIOLOGIST. Only 2 data tree is visible which are the 2 now assigned to ROLE_BIOLOGIST. Effectively the Chemist and Biologist have a private data tree each and share access to a 'public' data tree.

    images/download/thumbnails/1806026/8_1_chemtree.pngimages/download/thumbnails/1806026/8_2_biotree.png

    {primary} If you have role ROLE_EDIT_SCHEMA then filtering does not apply and you see everything, independent of what roles are associated with it. This is because users with ROLE_EDIT_SCHEMA can edit the IJC schema, and so need to know about all things in it. So filtering only applies to users with lesser privileges.

    {primary} Filtering the SCHEMA item itself is disabled. You are already connected to it so filtering it out makes no sense.

    More advanced issues

    Filtering data trees is the most obvious application of this functionality. However, any item in the IJC_SCHEMA can potentially be filtered using this mechanism, except for the schema item itself (see above). For instance, individual entities and fields can be filtered if you need. But be cautious if you work at this level, as data trees are dependent on the entities they use and entities are dependent on some of the fields that they own. For instance, its probably a bad idea to filter fields that are involved in relationships, are primary keys or whose values are required for inserting new rows. And filtering out relationships is probably a very bad idea indeed! In some rare cases some of these can be sensible things to do, but not usually. Do test carefully. Its quite easy to filter out a field and have a data tree disappear because it is dependent on the field for some reason! If you make a mistake just delete the offending row from the IJC_SCHEMA_AUTHORITIES table.

    {primary} The above description assumes you are using database based security. If you are using a different approach such as LDAP then most of this still applies. You need to perform steps 2 and 3, but as the actual roles are defined in LDAP then step 1 is not necessary. However the roles you use (obtained from LDAP) still need to be configured according to steps 2 and 3 for this to work.

    Problems?

    If you have any questions or comment then please report them to the Chemaxon FreshDesk.