RAS Route Path Config

Basic Route Path Definition

The Route Path within RAS controls which users are required to approve proposals in the PD module, and in what order.

The basic Tufts route path for PD is:

Local Admin
Manager
Department Reviewer (optional escalation)
School Financial Reviewer (optional escalation)
Central Portfolio Manager
Central Administrator (aka Signing Official)

Escalation Factors

Stops # 3 and 4 will only be included if one of five predetermined "escalation factors" are present on the proposal. The factors are defined in JIRA ticket RAS-434, but the basic conditions are:

Special Capital Planning Considerations are present on the Proposal Questions questionnaire
A Course Release is required, as noted on the Proposal Questions questionnaire
The proposal budget contains any amount of cost sharing
The proposal budget contains any amount of unrecovered F&A
The user has marked that the proposal has "additional considerations that require special review" on the Proposal Questions questionnaire

If ANY of these five conditions are met on the proposal, stops 3 & 4 will be included on the route path. If none of the conditions are met, those stops will be skipped and the route path will go directly from stop #2 to #5.

Short Routing Path

There is a flag in PD named the 'Short Routing Path' flag. This flag can be set by the Central Administrator when rejecting a proposal; when set, the route path will skip ALL of stops 1-5 on subsequent routings, going directly to the Central Administrator. This option is available so that last-minute revisions to the proposal can be processed without requiring every approver to re-approve the record.

Route Path Assignments

Route paths are configured on a per-department basis, so each department ID will have a unique route path. The configuration is done via the RAS 'Unit Administrator' maintenance table. This table contains roles which correspond to each route path stop, and users can be assigned to these roles to configure the route path for a given department. The resulting assignments in the Unit Administrator table will look like this:

Not every role needs to have an assigned approver – only the 'Tufts Central Admin' role is required for each department. The other roles can be populated based on the specific department's needs. Any roles left empty will simply be skipped over in the route path.

Delegates

Each route path role has a corresponding 'Delegate' role. Users assigned to a delegate role will NOT get notifications related to approvals for that role, but will have the ability to approve on behalf of the "regular" approver.

Delegates are assigned the the Unit Administrator table exactly like regular approvers.

Route Path Configuration

The stops on the route path are configured using two Kuali Coeus features: Agenda and PeopleFlow.

A "PeopleFlow" is simply an ordered collection of people, groups, or roles. These PeopleFlows are used to define the order and definition of the route path stops.

An "Agenda" is a document containing rules which which PeopleFlows are called.

Tufts Agenda

The Tufts agenda used for routing is named 'TuftsRoutingAgenda'. It can be found by going to the Central Admin → Agenda page and executing a search. (There are only a handful of Agendas in our system, so it shouldn't be hard to find.)

The Agenda contains a number of preset rules, which are executed in sequence. Each rule will result in the proposal either being routed to the linked PeopleFlow (if the rule matches) or passed to the next rule (if the rule does not match). The PeopleFlows for each step can be found and edited via the Central Admin → PeopleFlow menu.

The rules within the TuftsRoutingAgenda are displayed and explained below.

TuftsRoutingStage1

Stage 1 will match all proposals that do NOT have the Short Routing Path flag set. The PeopleFlow for stage 1 will route the proposal to the Tufts Local Admin (stop 1) followed by the Tufts Manager (stop 2).

As seen in the PeopleFlow image below, the 'Tufts Delegate' roles are also set up here as delegate approvers for each stop.

Agenda Step	PeopleFlow

TuftsRoutingStage2

Stage 2 will match proposals that do not have the Short Routing Path flag set, AND have met one of the five Escalation Factors, as discussed above. Each of these five factors has a custom KRMS rule (Kuali Rules Management System) which contains the logic for checking the underlying field on the proposal. Details about creating a KRMS rule can be obtained from Kuali, but you can look up RAS-434 in both the kc-custom and kc-scripts git repos to see how these rules were created. Both custom java code and database configuration are required.

The PeopleFlow for this step will route the proposal to stops 3 and 4 (Department Reviewer and School Financial Reviewer) if the conditions are met.

Agenda Step	PeopleFlow

TuftsRoutingStage3

Stage 3 will match all proposals that do not have the short routing path set. This stage routes the proposal to stop 5, the Central Portfolio Manager.

Agenda Step	PeopleFlow

TuftsRoutingStage4

Stage 4 matches all proposals, and routes the proposal to the Central Administrator for final approval.

Agenda Step	PeopleFlow

Adding New Roles for Additional Stops

Based on the information above, you probably have a decent idea of how to add a new route path stop – simply update the appropriate PeopleFlow to call the desired role at the desired point in the route path. For example, to add a new stop between the Central Portfolio Manager (stop 5) and Central Admin (stop 6), you would add the new stop to either the end of Stage3 or the start of Stage4 (depending on which rule you wanted it to be tied to).

However, the roles themselves are custom "Derived" roles. Unlike regular roles, which are assigned directly to users, Derived Roles instead contain logic which dynamically determines which users are members of the role at any given time. The Dervied Role can also be given parameters when it is called, to be used in determining the result.

Our Tufts derived roles are passed the proposal's department ID as a parameter, and contain logic to look up the appropriate Unit Administrator assignments for that department. Each derived role is a custom Java class with a matching database entry. Examples of how the roles were created can be found in the git repo at the following commits:

Custom java classes for each role: https://gitlab.it.tufts.edu/ras/kc-custom/commit/38b9e814c57972378c1b5213eaff26c4d9ee29d2

Database configuration: https://gitlab.it.tufts.edu/ras/kc-scripts/commit/dc190af86e6d2b6d81fa9accef0ad8e0152b0ef7

To create a completely new role, you would need to:

Create the new UNIT_ADMINISTRATOR_TYPE entry which represents the new role
Create the new Java class which extends the AbstractUnitAdministratorDerivedRoleTypeService and implements the Unit Admin lookup for that role
Create KRIM_TYP_T and KRIM_ROLE_T entries to define the dynamic role within KC

Once complete, you will be able to look up the new KC-WKFLW dynamic role from within the PeopleFlow and add it to the route path. When called, the role will use the given parameters and inbuilt logic to determine the role members.

It's important to note that the use of dynamic roles here is a Tufts customization. Most schools are using the PeopleFlow to directly assign specific users (or non-dynamic roles) to the route path, and create unique Agendas/PeopleFlows for every unit.

Our custom roles allow us to define a SINGLE generic Agenda that applies to all units, and abstract the assignments out to the Unit Administrator table which is far easier to edit and maintain.

This also has the side effect of separating Route Path assignments from security roles, which can be beneficial since sometimes we want to give someone a role without putting them on the associated route path stop, or vice versa.