= Roles and Authorization =

<<TableOfContents>>

= 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 users performing workflow steps on revisions and tasks in their own name
 * '''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 '''User``Role''' 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 User``Role applies to all contracts.
  * '''groupId''' - the group of the data being operated upon. If zero/null then the User``Role applier to all groups in the contract.
  * '''roleId''' - the role involved

= Transaction Authorization =

The ability to run transactions is controlled by ''User``Role'' 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

 1. 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. 


== 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 (described 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:

  ||                         ||<-4>  '''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" );
    }}}

 1. '''Finite``State``Machine``Base::newBT''' calls '''Business``Transaction``Base::newBT''', which contains the following code:

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

 1. '''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? 

  * What's about operations associated with 'Roleset' 'Manager'. It is currently used in:
    * !DashBoard - view tasks of other users
    * Changing documentTypeId, layoutTypeId, defaultWorkFlowTypeId, groupId on new/update Drawings
    * Changing layoutTypeId, workFlowTypeId on new/update Revisions
    * Viewing obsolete comments, comment notes
    * Changing default email behavior on update Comments