# Configuring the Study Training Matrix Builder

The Study Training Matrix Builder is a user-friendly interface that allows an authorized user to rapidly assemble the training needs for a given _Study_ by specifying the training materials that each study team member needs to complete training on.



<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: The <a href="/en/lr/50533901/">Study Training Matrix Builder</a> is available in Study Training Vaults only.</p>
    </div>
  </div>
</div>



## Configuration Overview

To configure the Study Training Matrix Builder:

1. Add the **Create Study Training Matrix** record action to the _Study_ object in **Admin > Configuration > Objects > Study > Actions**.
2. For the _Training Role_ (`learner_role__v`) object:
  * Ensure the _Add to All New Studies_ field is active and assigned to the _Study Training Role_ object type, and that the [default value](/en/lr/42778/) is configured such that all new records are created with the field set to "Yes" (`add_to_all_new_studies__v = true`). This configuration allows Vault to automatically add _Study Training Roles_ to all new _Study_ records.
  * Add the _Add to All New Studies_ field to the Details panel of the _Study Training Role_ object page layout.
3. Ensure the _Study_ object page layout includes the  _System Aided Matrix Management_ field in the Details panel.
4. Review your Vault's security configuration and confirm the Study Manager, CRA, or other users managing your organization's Training Matrix are assigned a security profile configured with the related [permissions][5].
5. Optional: Configure [Study Training Matrix Review][1] to enable Training Admins to send new and updated matrices to other Vault users prior to publication.



<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: In Vaults where Study Training Matrix Review is not configured, Vault still uses the <em>Training Matrix Update</em> lifecycle to manage matrix updates, including creating records in the <em>Draft</em> state when a Training Admin saves a matrix draft, and moving them to <em>Published</em> upon publication.</p>
    </div>
  </div>
</div>



## About Study Training Matrix Review {#about-review}

By default, Vault immediately applies new and updated matrix records when a Training Admin publishes a Study Training Matrix. With Study Training Matrix Review, Training Admins can send a workflow to other Vault users, providing an opportunity to review the matrix before it is published and Vault begins issuing or cancelling *Training Assignments*.

The basic Veeva-recommended [configuration][3] for this feature requires minor *Training Matrix Update* object lifecycle updates. However, Training Admins and Vault Admins should consider organizational requirements against the *Training Matrix Update* lifecycle and workflow [default behavior][2], as well as feature [limitations][4].


### About the Training Matrix Update Lifecycle & Workflow {#about-tmu}

Study Training Matrix Review includes both the *Training Matrix Update* object lifecycle and *Training Matrix Update Review* workflow. These standard components are pre-configured for a basic review process, however many aspects outlined here can be updated as required.

The standard *Training Matrix Update Review* workflow operates such that:

1. The workflow initiator can select any Vault user as a workflow participant (Reviewer).
    * Vault Admins can update the Start step's participant controls to narrow or limit the list of selectable users.
    * Additional Start step configuration can include more advanced security options, such as enabling Dynamic Access Control for the *Training Matrix Update* object so that only users related to the record's indicated *Study* can be selected as a workflow participant.
2. The workflow's Review step assigns tasks to all users selected as a Reviewer, via the *Assign to all users in participant group* assignment option. We recommend continuing to use this setting in your configuration, as it supports a user-experience [limitation][4].
3. The workflow's Task step includes Approve and Reject verdicts configured with the *Short-circuit tasks with the configured tags* option. This means that once any Reviewer renders either verdict, Vault cancels the tasks for all other Reviewers and proceeds to the next step in the workflow.
    * To require that all selected Reviewers render a verdict, Vault Admins can de-select the short-circuit option.
    * Alternatively, Vault Admins can update the *Assign to all users in participant group* assignment option (item 2 above) to instead use the *Make available to users in participant group* option. However, this option has a user-experience [limitation][4].

The standard *Training Matrix Update* object lifecycle operates such that:

1. The *Draft* state is mapped to the lifecycle's *Initial* state type, and the *Published* state is mapped to the *Complete* state type.
    * This configuration supports the simple *Training Matrix Update Review* workflow, which moves the matrix from *Draft* to *In Review*, then to *Approved* once the workflow is complete. A Training Admin must still click the **Publish** button to transition the matrix to *Published*.
    * While the state types are required for Study Training Matrix Review functionality, their mapped states can be adjusted according to any related workflow updates.
2. The *Training Matrix Update Review* workflow is initiated via user action from the *Draft* state. The workflow can only be configured as an entry action when the workflow configuration automatically populates Reviewers.


### Configuring Matrix Review {#configuring}

The below Study Training Matrix Review configuration leverages the feature's standard object, lifecycle, and workflow components for quick implementation. See [additional details][2] on implementing specfic organizational requirements.

To configure Study Training Matrix Review:
1. Within the *Training Matrix Update* object lifecycle's *Draft* state, configure a "Send for Review" user action using the *Training Matrix Update Review* workflow.
2. Review your Vault's security configuration and confirm that users working with Study Training Matrix Review are assigned a security profile configured with the related [permissions][6].


### Matrix Review Limitations {#limitations}

The Study Training Matrix Builder does not fully support some workflow configurations, including:
* Using a custom (`__c`) review workflow in lieu of the standard (`__v`) *Training Matrix Update Review* workflow. We strongly recommend that Vault Admins incorporate any organizational requirements into this workflow.
* Configuring the Task step with the *Make available to users in participant group* assignment option. Similarly, the *Allow workflow initiator to select assign to all or make available* option can produce a mixed user experience as described below. We recommend using the *Assign to all users in participant group* assignment option for the smoothest user experience.

The above configurations prevent Vault from properly and fully displaying the workflow task banner and/or the task's **Accept** button within the Study Training Matrix Builder. While Reviewers can ultimately complete the task elsewhere (for example, within their **Home** page's **Available Tasks**), these extra steps can degrade user experience by separating the review task from the builder's visual interface and its highlighting of proposed changes.


## Related Permissions {#permissions}

At minimum, Study Managers or other users building a Study Training Matrix require a security profile with _Read_ and _Edit_ permissions on the following objects to view and work with the matrix builder:

* _Curriculum_
* _Curriculum-Training Role_ (`curriculum_learner_role__v`)
* _Study Curriculum_
* _Study Learner Role_
* _Training Requirement_
* _Training Requirement Classification_
* _Training Requirement-Curriculum_
* _Training Role_ (`learner_role__v`)
* _Training Role-Study_ (`learner_role_study__v`)

Access to each function in the matrix builder is controlled by certain object or field permissions, and if the user lacks those permissions, they will not see the function in the builder interface:

| **Area**              | **Action/Function**                              | **Object Permission(s) Required**  |
| --------------------- | ------------------------------------------------ | ---------------------------------- |
| Study Team Roles      | Add Study Team Roles                             | _Read_ to _Learner Role_ of type _Study_ object, _Create_ and _Read_ to _LearnerRole-Study_ object |
| Study Team Roles      | Remove Study Learner Roles                       | _Read_ to _Learner Role_ object of type Study, _Delete_ to _LearnerRole-Study_ object, _Delete_ to _LearnerRole-Curriculum_ object |
| Study Curricula       | + Document and Add Document                     | _Create_ and _Read_ to _Curriculum_ object, _Create_ and _Read_ to _Training Requirement_ object, _Create_ and _Read_ and _Edit_ to _Training Content Set_ and _Training Content Set-Documents_ objects |
| Study Curricula       | Rename                                           | _Edit_ to `name__v` field on _Curriculum_ object |
| Study Curricula       | Specify Country                                  | _Edit_ to the `study_country__v` field on _Curriculum_ object |
| Study Curricula       | Add Training Requirements                        | _Create_ and _Read_ to _Curriculum-Training Requirement_ object, _Read_ to _Training Requirement_ object |
| Study Curricula       | Delete                                           | _Delete_ to _Curriculum_ object, _Delete_ to _Curriculum-Training Requirement_ object, _Delete_ to _Curriculum-Learner Role_ object |
| Study Curricula       | View More Details                                | _Read_ to _Curriculum_ object  |
| Training Requirements | Rename Training Requirement                      | _Edit_ to `name__v` on _Training Requirement_ object |
| Training Requirements | Add Training Materials                           | _Create_ and _Edit_ to _Training Content Set_ and _Training Content Set-Documents_ objects |
| Training Requirements | Move Training Requirement                        | _Delete_ to _Curriculum-Training Requirement_ object, _Create_ to _Curriculum-Training Requirement_ object |
| Training Requirements | Copy Training Requirement                        | _Create_ to _Curriculum-Training Requirement_ object |
| Training Requirements | Remove Training Requirement                      | _Delete_ to _Curriculum-Training Requirement_ object |
| Training Requirements | Remove (when hovering over Training Requirement) | _Delete_ on _Training Content Set-Document_ object |
| Training Requirements | Delete                                           | _Delete_ to _Training Requirement_ object, _Delete_ to _Curriculum-Training Requirement_ object |
| Training Requirements | View More Details                                | _Read_ to _Training Requirement_ object |
| Matrix Checkboxes     | Select or deselect checkboxes                    | _Create_ to _Curriculum-Learner Role_ object, _Delete_ to _Curriculum-Learner Role_ object |
| Matrix Updates        | Create, view, and edit a draft matrix.           | _Read_, _Create_, and _Edit_ to the _Training Matrix Updates_ object. |

### Matrix Review Permissions {#matrix-review-permissions}

Users participating in Study Training Matrix Review must be assigned a permission set with the below permissions.

Vault always loads the live matrix for users assigned only *Read* permission for the *Training Matrix Update* object.

| Permission Label | Permission | Controls |
|---|---|---|
| Application: Workflow | Start, Participate, eSignature | Ability to send the Training Matrix Update Review workflow to reviewers. |
| Application: Workflow | Participate, eSignature | Ability to participate in the Training Matrix Update Review workflow. |
| Objects: Training Matrix Update | Read, Create, Edit, Delete | Ability to publish a matrix draft.<br>Delete permission allows users to discard drafts during this process. |

[1]: #about-review
[2]: #about-tmu
[3]: #configuring
[4]: #limitations
[5]: #permissions
[6]: #matrix-review-permissions