Roles and Authorization

Introduction

This page describes how user roles and transaction authorization is implemented.

Roles

The types of roles are defined in the database in the Roles table.

Role Types

The following types of roles are defined:

• Administrative Roles - for managing users, user roles and the system configuration

• Workflow Roles - for performing workflow steps on revisions and tasks

• Submittal Recipient Roles - define who receives copies of submittals

• Task Subscriber Roles - define who receives emails when tasks are created and updated. A long term goal is to improve the management

Note that the former Management Roles (PM, LE, Assistants, Deputies, etc.) will be deleted. They attempted to define a project organization, which is unrelated to user roles and transaction authorization.

Detailed List of Roles

• Documents and Revisions
  • New/Update - Allows creation and update of Documents and Revisons

  • Workflow - Allows user to perform a workflow step. Determines which users appear in the who dropdown menu.

    • Receive
    • Design/Create
    • Check
    • Approve - Up to four approval steps
    • Release
    • Submit - Filled in by the submittal transaction
  • View
    • Normal

    • Restricted - User not allowed to see revisions where the workflow is not complete, and (depending on the site settings) superseded revisions. Also called the contractor role.

• Tasks
  • New/Update - Allows creation and update of Tasks

  • Workflow - Allows user to perform a workflow step. Determines which users appear in the who dropdown menu. Note that this will not be implemented immediately. The workflow steps will probably be limited to an approve step, which allows setting status and complete date.

    • Receive
    • Design/Create
    • Check
    • Approve - Up to four approval steps
    • Release
  • View
    • Normal - Allows view and creation of all types of comment notes
    • Restricted - Restricts the display and creation of comment notes. The configuration (or site settings) have lists of what types of contents can be created and displayed
• Submittals
  • New/Update - Allows creation of submittals and transmissions
  • Transmit - Allows transmission of submittals and transmissions
  • View
• Users and User Roles
  • New/Update - Allows creation and updating of users and user roles.
  • View
    • Normal - Sees all users and user roles
    • Restricted - Can see user records, but not user roles
• System Configuration
  • New/Update - Allows users to create/update/delete reference data records

User Roles

A UserRole defines the authorization to perform operations, based on:

• userId - the Users ID

• contractId - the contract/area of the data being operated upon. If zero/null then the UserRole applies to all contracts.

• groupId - the group of the data being operated upon. If zero/null then the UserRole applier to all groups in the contract.

• roleId - the role involved

Transaction Authorization

The ability to run transactions is controlled by UserRole records. Two steps of authorization are performed:

1. The ability to start a FSM or BT transaction is checked when it is instantiated by the finite state machine (in newBT and newFSM?). Given the following inputs: This is probably incomplete/incorrect

   • a Transaction Name (as defined in app/config/TransactionMap.php) or Transaction Class (a BT or FMS class name)

   • the userId from the global session

   • the current contractId and groupId from the global session

2. In the transaction class, an additional test is made. The test varies depending on whether a new object is being created or updated/displayed:

   • For a new transaction the contractId (from the session) and groupId of the object (?) is used

   • For a update and view transaction the contractId and groupId of the object is used For view transactions, additional checks based on the type of view may be performed that alter what is displayed. In this case

Transaction Map

The transaction map is defined in app/config/TransactionMap.php

The transaction map is an associative array:

• Keys: Transaction Class names, the classes defined in php files in sub-directories in the app/tran directory

• Values: Transaction Names or arrays of transaction names. These names are used to make lookups in the Profiles (see next section).

Example extract from the transaction map:

•       $this->map = array(
  
          ...
          'DocumentUpdFSM'                => 'DrawingUpd',      
          'DocumentUpdFormBT'             => 'DrawingUpd',
          'DocumentUpdConfBT'             => 'DrawingUpd',
          ...
          'RevisionNewFSM'                => 'RevisionNew',     
          'RevisionNewFormBT'             => 'RevisionNew',
          'RevisionNewConfBT'             => 'RevisionNew',
          ...
          'RevisionWorkflowREST',         => array( 'RevisionReceive', 'RevisionDesign', 'RevisionCheck', ... ),
          ...
          'DrawingListFSM'                => array( 'DrawingView', 'DrawingViewRestricted' ),
          'DrawingListBT'                 => array( 'DrawingView', 'DrawingViewRestricted' ),
          'DrawingDetailFSM'              => array( 'DrawingView', 'DrawingViewRestricted' ),
          'DrawingDetailBT'               => array( 'DrawingView', 'DrawingViewRestricted' ),
          ...
          'CommentNoteNewFSM'             => 'CommentNew',      
          'CommentNoteNewFormBT'          => 'CommentNew',
          'CommentNoteNewConfBT'          => 'CommentNew',
  
          'CommentNoteUpdFSM'             => array( 'CommentView', 'CommentViewRestricted' ),    
          'CommentNoteUpdFormBT'          => array( 'CommentView', 'CommentViewRestricted' ),
          'CommentNoteUpdConfBT'          => array( 'CommentView', 'CommentViewRestricted' ),
           ...

Profiles

The transaction profiles are defined in app/config/Profiles.php

The transaction profiles is a 2-dimensional matrix, defined as an associative array.

• Vertical axis: Transaction Names - as defined in the Transaction Map (sescribed above)

• Horizontal axis: Roles - As defined in the database tables Roles. The offset in the array is determined by the roleId.

• Values: at each transaction name and roleId intersection there is a flag that defines if it is possible to run the transaction given the role.

Note that, for some transaction names, there is a simply a 0 or 1 instead on an array, that indicates the transaction is allowed or disabled for all roles.

Example showing how the definition of view normal and restricted are defined:

• 	Roles
  	..	View Normal	View Restricted	..
  Transaction Names
  ..
  DocumentViewNormal	..	1	0
  DocumentViewRestricted	..	1	1
  ..

Example Authorization

Scenario: A user wants to add a task note. They have the task view restricted role for the task in question.

1. Dispatcher.php tries to instantiate the class CommentViewBT with a statement like the following:

   •          $bt->FiniteStateMachineBase::newBT( "CommentViewBT" );

2. FiniteStateMachineBase::newBT calls BusinessTransactionBase::newBT, which contains the following code:

   •       ..
           $authorizer = Authorizer::get( .. );
           if ( ! $authorizer->isAuthorized( $className ) ) {
             .. transaction no authorized
           }
           .. transaction authorized

3. Authorizer::isAuthorized performs the following check (note that $tranName can be an array):

   •       ...
           $tranMap = new TransactionMap();
           $tranName = $tranMap->getTransactionName( $cmd );
     
           return $this->isTransactionAuthorized( $tranName, $userId, $contractId, $groupId );

Open Points

• Who is allowed to see history pages? Suggest:

  • Normal view - Yes
  • Restricted view - No
• Marking items obsolete and restoring them?
• Changing comment notes created by other users?