Implementation Best Practices

Cason Walker • Created • Last updated

Below you will find our best practices and answers to common questions that we receive during the Implementation process. If you have any questions, please reach out to your Implementation Specialist.

 

Phase 1: Administration: Users, Roles, Permissions, Custom Fields, Single Sign On

Phase 2: Document Categories and Documents

Phase 3: Training Records, Courses, Training Events, and Tests

 

Phase 1: Administration: Users, Roles, Permissions, Custom Fields, Single Sign On

 

Role Creation - Training vs Accessibility and Visibility

When creating roles, it is best practice to create roles for groups of users you will eventually be assigning the same training courses to, and to keep in mind the users in these roles will all have the same accessibility and visibility to different areas in Zen. You can create a more generic role for users you do not want to have as much accessibility and visibility, and when you assign permissions to your roles, you do not need to assign many or any to this particular one. You can create roles based on modules in Zen, so for users who will always be Document Owners, you can create a role for this and assign this role more in depth permissions that only pertain to the Documents module.

 

In general, when considering roles for training versus accessibility and visibility, you will be assigning permissions to roles that determine their accessibility and visibility levels in the system, and when assigning roles to trainings, you will simply be assigning those roles you create to training courses you set up.

 

You can also create roles for people based on things they may need to be doing in ZenQMS. For instance, if you have a group of users who will all be document admins in the system, you can create a role for this, and assign permissions to them that only pertain to documents that other general users would not have, as well as assign training courses to them that relate to being document admins in ZenQMS.

 

As another example, If you have multiple users who you know will all need to train on the same 12 documents, for example, you can create a role for these users and create a training course for those 12 documents and assign this role of users to train on that course.

 

Single Sign On

It is best practice to test out your Single Sign On configuration in the Sandbox during your Implementation before setting it up in Production. Sometimes configuring SSO takes longer than expected and you may want to test out different ways to execute signatures in ZenQMS. To learn how to set up Single Sign On, please follow the instructions here: ZenQMS SSO Single Sign-On Self Service

 

Permissions that come with Risk

Below are account level permissions that come with risk. You will want to limit who has access to these permissions:

  • Account Active Modules: this gives the user the ability to turn on and off your account’s active modules
  • Account Audit Trail: this gives the users access to the full account audit trail
  • Account Custom Fields: this gives the user the ability to create, manage, delete custom fields that are used in the User Table, Documents, Change Control, and Issues
  • Account Notification Defaults: this permission gives the user the ability to set notification frequency for new users and lock those settings in for all users.
  • Account Roles/Permissions: this permission gives the user access to the Roles and Permissions section in the Settings, allowing them to create, manage, and delete roles, including managing user assignments.
  • Account Single Sign-On (SSO): this permission gives the user access to your Single Sign On configuration, including the ability to enable and disable the configuration.
  • Account Users: this permission allows the user to add and manage users, including the ability to activate/disable users, manage roles and supervisors, and edit user information.
  • Can Edit any Audit or Observation That User Has Access To: this permission gives the user access to editing any audit or observation that they have permission to see.
  • Can Add New Supplier Sites: this gives the user the ability to create new sites that can be used within the audits module.
  • Can Create New Audit Reports: this permission allows the user to create a new audit report
  • Member Administration/Configuration: this permission gives the user access to Settings > Administration > Member Administration, where they will have access to configuring account preferences, reviewing ZenQMS access history, as well as configuring legacy custom fields, legacy permissions, audit workflows, and templates.
  • Super Admin: Has full Edit/Admin access to any Course, Event, Test or Audit: this gives the user full access to the Training and Audits modules.
  • Site Administration/Management: this gives the user access to the Site Administration section of Settings > Administration. This allows the user to create, edit, and manage sites.
  • Can Create/Manage New Training Courses: this permission grants the user the ability to create new courses and manage them, including training assignments. This does not give them access to all courses.
  • Can Add New Training Events: this grants the user the permission to create new OJT and Group events and manage those training assignments.
  • Can Add New Tests: this grants the user permission to create tests and assign training to them.
  • Can See & Edit All Tests: this permission allows users to edit test details, test questions, test answers, as well as edit training assignments to any test.
  • Can Set a Training Item as Compliant / Non-Compliant and Extend Due Dates For Any User: this permission gives users the ability to extend due dates for any user for any training item they have access to, as well as, mark users compliant or re-force training.
  • Can Create Personal Events for Other Users: this grants the user the ability to create personal events for individual users.
  • Can Edit any Events That User Has Access To: this permission grants users the ability to edit any event that they have access to, meaning they can edit details and training assignments.
  • Can Add New OJT Events: this permission grants users the ability to create new OJT events, including the ability to assign training.

  • Can Create, View, and be assigned as Owners on SCORM: this permission allows users to be the owner of a SCORM training, meaning that in addition to creating, viewing, and editing settings, they can also assign out training.

     

Phase 2: Document Categories and Documents

 

Broad vs Granular Document Categories

Broad categories are ideal when you want to keep things simple—including document settings, permissions, and workflows. Examples might include high-level groups like SOPs, Forms, Templates, Policies, and Work Instructions.

 

A more granular approach may be beneficial if your organization has complex permission structures, varied workflows, or metadata requirements that differ across departments.

 

In general, we recommend starting with a broad category structure and using features like roles, custom fields, links, and metadata to manage and organize documents at a more detailed level.

 

Document Category permission that come with Risk

Below are the permissions for the Documents that come with risk. These permissions are granted at the Document Category level. You will want to limit who has access to these permissions:

  • Can Edit All Settings In This Category: this permission allows users to edit any setting within a category - this includes making updates to workflows, grace periods, and permissions.
  • Can Edit Any Document in Category: this gives users the ability to view and edit all documents in the full table for the specific category, regardless of status, and the ability to review documents, thus potentially initiating up-versions and retirements.
  • Can Edit Document Details, Category Defaults, Custom Fields, and Links/Attachments: this permission allows users to edit document metadata for documents that they have access to.
  • Can Create New Documents: this permission allows users to create new draft documents for a category and launch them for approval.
  • Can Cancel Active Workflows: this permission grants users the ability to cancel active workflows for documents that they have access to.
  • Can Delete Draft Documents: this permission gives users the ability to delete draft documents. This includes newly created draft documents, as well as drafts that were created due to an up-version.

  • Can See Archive & Permanently Delete Eligible Items: this permission grants users access to the Documents Archive and the ability to permanently delete eligible documents. These deletions are permanent and cannot be reversed.

     

Uploading PDFs vs Word source files

The best practice for uploading source files would depend on user preference, and there are benefits to either uploading a word document versus uploading a PDF. Uploading a word source file document would allow for the option to generate pdfs anyway, and when up-versioning documents, would not require needing to convert from a pdf back to a word file since the source file would already be a word document. If there is a need to bring files in as PDFs to have proof of the already signed version of the document, you can include information about the previous version of the document in the version comments, and the workflow for migrated documents will state that the document was approved/made effective outside of ZenQMS. The benefit to uploading PDFs would be that the original signatures are there.

 

How to Set Up CVs and Job Descriptions in your Documents Module

There are a couple of different ways to bring in your CVS and Job Descriptions.

 

For JDs, we recommend creating a Job Description or HR Document Category. At the category level, you will be able to determine who can view, edit, or create Job Descriptions.

 

For CVs, we recommend creating a CV or HR Document Category.

 

If you would like users to manage their own CVs, you will want to give them permission to create documents within this category. To ensure that users are not creating documents incorrectly, a workflow should be established at the document category level. Typically, this will require a manager or QA approval. If users only have this permission, they will only be able to see the documents that they are the author of.

 

If you would like management or QA to manage users’ CVs, you will want to give the Management or QA roles the permission to create documents within the document category. To approve the CV, the user should be added as a signatory for the approval workflow.

 

If the user should have this CV on their training dossier, you will want to add them as a trainee for them to sign off. If you set up the setting “Auto Create training records for authors/workflow participants” any other user who is the author or approver will have this CV on their dossier, as well.

 

Migrating Historical Retired Documents

If your team is looking to migrate in retired documents, they will need to be added to the migration template. To ensure that these documents are tied to the effective version, you will want to make sure that the Document Name matches exactly. This allows our system to know that these documents are related, as opposed to creating separate documents. If you are bringing in retired documents, please make sure to fill out the retirement date, in addition to the effective date.

 

Fillable Forms

Please reference our attached article regarding supported Form Field types in Microsoft Word documents: Supported Form Fields in DOC/DOCX Files Overview 

 

Key ID Updates

ZenQMS will happily assist with a one-time Key ID adjustment for clients who implemented prior to the launch of Key-IDs. In order to best assist you with this, navigate to each document category and create a new Draft version. This will allow you to update the Key from your current value to your new preferred choice (please be aware that changing this in the draft configuration will update across all existing documents). Please refer to following knowledge base article which covers this process in depth. One-Time Document Key ID Help Desk Change Requests

 

Once the Key has been updated to the new correct value, we will provide a report for you to use and assign a new Key-ID number. Since the Key has already been changed, the new Key-ID will only need to assign the correct number. Once the template has been completed, please return this to our team for us to perform the updates.

 

How to Migrate Training Challenge Questions

If you’d like to add training challenge questions to your documents, we have a template that our technical team can use to add them once the documents are in production. However, this process can take some time, as our technical team is often handling other requests. If there aren’t too many questions, it may be quicker to add them manually in production to your documents.

 

How to Migrate Document Links

If you want to link one document to another in Zen, there is a piece to the Migration Template that can be made available to you that will allow you to do this. You will simply need to fill out the name of “Document A” and specify its version number, and then beside it list the name of “Document B”. This will link both documents together, so when you look at Document A in Zen, you will see Document B listed in the document links section of the metadata, and when looking at Document B , you will see Document A linked in this area of the metadata for Document B. This is a request that our technical team can assist with after migrating your documents into Production.

 

Custom Fields Pointers

Custom Fields are used to track any information that ZenQMS does not currently track. Account Custom Fields appear across all modules. For Documents, you can choose to apply User Custom Fields to your document categories, or have document category-specific custom fields configured. You can also create custom fields specific to issues and change controls, or add existing account custom fields here as well. It is best practice to use Account Custom Fields to apply to Document Categories when configuring information using the migration template.

 

If you’d like to use user custom fields, these may typically be things such as “Department” or “Location”, indicating user’s departments their job titles fall under and cities where they are located for work. These are just a couple of examples of typical user custom fields, and can be brought into the User table to see this information for all users at a glance. Custom fields are also used for Documents and configured at the category level. Common examples of custom fields for documents might include internal system ID numbers, internal document IDs, or anything else Zen does not currently track. Users should avoid creating existing ZenQMS fields as custom fields. It is best practice to avoid creating existing ZenQMS fields as custom fields, and to use these to bring in internal or company-specific information that Zen cannot track. You can bring in your custom fields to your users and documents tables in Zen and export these tables, making it easy to find groups of users and documents that have the same custom field information.

 

To configure Custom Fields on the Migration Template for Users, fill out the “Account CF Settings” and “Account CF Choices” tabs. Only use the “Account CF Choices” tab if your custom field is a single selection or multiple selection type. Use these tabs for custom fields you would like for your document categories as well, and also use the “CAT - Account Custom Fields” tab to specify which document category(ies) you would like certain custom fields to apply to.

 

If a custom field applies to a document category, this means this field will appear for all documents in the category.

 

Phase 3: Training Records, Courses, Training Events, and Tests

 

Marking Everyone Compliant on Training

Marking everyone as compliant is an effective way to establish a clean baseline during the transition. By acknowledging that users were previously compliant—based on training records maintained outside the system—you can prevent unnecessary escalations, overdue tasks, or misleading metrics caused by missing or outdated paper records. This approach also significantly reduces the initial workload by avoiding the need to manually enter historical data.

 

Super User Training in Production (Bringing it in as documents, keeping it in SB, setting up an OJT)

Super User Training records can be transferred from the Sandbox to the Production environment by creating a single OJT event to mark these users as compliant. In the Sandbox environment, we recommend keeping the individual documents available as new users may need to be assigned to train. Once the records have been captured in the Sandbox environment, you can create the OJT event in Production and assign the individuals who completed training in the Sandbox, then you can mark the users as compliant without the risk of users being assigned to the Super User Training directly in Production.

 

Assigning Training

We recommend assigning training based on roles rather than individuals. This approach streamlines onboarding, as users automatically inherit required training through their assigned role. It also promotes consistency by standardizing training across functions. While users may belong to multiple roles, they will only be required to complete training on a document once, even if it's assigned through multiple roles.

 

Creating Courses

When creating courses, we recommend creating them based on training roles, departments, company wide training, etc. We do not recommend creating a course per document, as this will be a lot for your team to manage. When creating a course, you can assign multiple documents to the course and then assign a training role you created. This allows you to manage both a group of users and a group of documents in one area, as opposed to individual document or user assignments.

 

How to Migrate OJT Events

If you have training events that you would like to assign to courses, have a retraining interval, and/or you would prefer your users do not sign off and instead be marked compliant, you may want to migrate OJT Events. To do this, please follow the instructions here: Training Event Migration: OJT Events

 

How to Migrate Personal Training Events

If you have training events that are tied to a singular user, such as a user attending a conference or earning a certification, you may want to migrate Personal Training Events. To do this, please follow the instructions here: Training Event Migration: Personal Events

 

How to Migrate Group Training Events

If you have training events that occurred on a specific date for a group, you may want to migrate Group Events. To do this, please follow the instructions here: Training Event Migration: Group Event

 

How to Migrate Tests

After Creating a test in the training module, navigate to the “Questions” tab. Select the “Import Questions” button in blue to open the pop-up window. Click on the link in this window to download the Test Migration Template. Each line on the template represents each individual test question. In column A, populate the test question. In column B, enter True for Multiple Choice, or False, for True/False question type. If Multiple Choice = True, populate Columns C through H with up to 6 different answer choices. If True/False, do not populate columns C through H. Column I, allows you to choose the correct answer for each question. For Multiple Choice questions, enter 1-6 corresponding with Choice 1-6. For True/False, enter True or False.

 

When the test template is complete, save this file and return to the Test Management Review window, and select “Import Questions” again, or if the pop-up window is still open, select “Browse” and choose the template to upload. After the upload completes, the Test will populate with your test questions. Repeat this process for each test you need to create, and a new template for each test.

 

How to Record General User Training in Production

If you are looking to record your users' General User Training in Production, you have a couple of different options when utilizing our pre-recorded training video or the live training session:

 

If you would like to record this as an OJT event, you could set up an OJT event in Production and assign your users. As they complete the general user training, you would then mark them as compliant. Within the event, you can either attach the recording of the training (if requested from the Implementation Team) or a link to the prerecorded General User Training available on the Knowledge Base.

 

If you would prefer to record this training as a document, you could set up the recorded session's file as a document (if requested from the Implementation Team) or include a link to the prerecorded General User Training available on the Knowledge Base within the source file of the document. You would then assign the users to train on the document and either mark them compliant or have them complete the training assignment upon logging in.

Enlarged view