Customize document templates

Customize templates for document types to fit your specific case-by-case needs, such as type or complexity of model or model use case.

• Templates are versioned and saving a template after making changes or reverting to a previous version state always creates a new version, or you can duplicate templates to create new independent templates in your library.
• Documentation templates are stored as YAML files edited directly using the advanced editor, allowing you full control over the minitua such as desired guidelines.
• We also provide a simplified editing experience to allow you to easily construct and rearrange the outline of your template.

Prerequisites

• You are logged in to ValidMind.
• The template you want to edit must exist in the ValidMind Platform.¹
• You are a Customer Admin or assigned another role with sufficient permissions to perform the tasks in this guide.²

¹ Manage document templates

² Manage permissions

NoneNot sure which template or which version of a template your document is using?

Check the document template section³ in the right sidebar.

³ Manage document templates

Edit template outlines

1. In the left sidebar, click Settings.

2. Under Documents, select Templates.

3. Select one of the tabs for the type of template you want to edit:

   • Documentation⁴
   • Validation Report⁵
   • Ongoing Monitoring⁶
   • Custom⁷

4. Click the template to edit and on the template details page, select Edit Outline.

5. In outline editing mode, you can:

   1. Expand sections:
      • Expand the menu for any sections with subsections by clicking .
   2. Add content to sections: validation reports only
      • Click to add content to that section of the template, such as a Summary Block or a Guideline Block.⁸
   3. Rename sections:
      • Hover over a section until the appears, then click on it to change the name.
      • Save by clicking , and discard changes by clicking .
   4. Insert new sections:
      • Click to add a new section or subsection to the template.
      • To add a section above the current section, select Section Before.
      • To add a section below the current section, select Section After.
      • To add a subsection within the current section, select Subsection.
   5. Remove sections:
      • Hover over the section you want to delete.
      • When the appears, click on it.
      • After you confirm, that section will be removed.
   6. Reorder sections:
      • Click and hold firmly to drag to reorder sections.

6. When you’re done, click Create New Version to view a side-by-side comparison of your changes with the previous version:

   • Add a description in version notes to track your changes.
   • Click Save to save the new version.

⁴ Working with model documentation

⁵ Preparing validation reports

⁶ Ongoing monitoring

⁷ Working with model documents

⁸ Add guidelines to templates

Once saved, your new template version becomes available for use.

Editing a template outline

To add guidelines to your template, edit the YAML template directly.

Edit YAML templates

1. In the left sidebar, click Settings.

2. Under Documents, select Templates.

3. Select one of the tabs for the type of template you want to edit.⁹ For example:

   • Documentation
   • Validation Report
   • Ongoing Monitoring

4. Click the template to edit and on the template details page, select Edit Raw.

5. In the Edit Template YAML editor that opens, make your changes according to the template schema,¹⁰ including the addition of any shared text blocks from your library.¹¹

6. Once you’re finished editing, click Continue to view a side-by-side comparison of your changes with the previous version of the template.

7. On the Review Changes screen:

   • Add a description in version notes to track your changes.
   • Click Save Version # to save the new version.

⁹ Working with model documents

¹⁰ Template schema

¹¹ Add text blocks to templates

Editing the raw YAML behind a template

Once saved, your new template version becomes available for use.

Template schema

Type: object

root template_id

Type: string

Unique identifier for the template.

root template_name

Type: string

Name of the template.

root version

Type: string

Version of the template.

root description

Type: string

Description of the template.

root sections

Type: array

Documentation sections of the template.

Each item of this array must be:

root sections section

Type: object

root sections sections items id

Type: string

Unique identifier for the section.

root sections sections items title

Type: string

Title of the section.

root sections sections items description

Type: string

Description of the section.

root sections sections items parent_section

Type: string

ID of the parent section.

root sections sections items order

Type: integer

Order of the section in the navigation menu. By default sections are ordered alphabetically. If order is specified, sections will be ordered by the order value, and then alphabetically.

root sections sections items default_text

Type: string

Default text for the section. If set, a metadata content row will be created with this text when installing the template

root sections sections items index_only

Type: boolean

If true, the section will be displayed in the navigation menu, but it will not be accessible via direct link.

root sections sections items condensed

Type: boolean

If true, the section will condense all of its subsections into a single section.

root sections sections items guidelines

Type: array of string

Documentation or validation guidelines for the section.

Each item of this array must be:

root sections sections items guidelines guidelines items

Type: string

root sections sections items contents

Type: array

Contents to be displayed on the section.

Each item of this array must be:

root sections sections items contents section_contents

Type: object

Single content block of the module.

root sections sections items contents contents items content_type

Type: enum (of string) Default: "metadata_text"

Must be one of:

• "metadata_text"
• "dynamic"
• "metric"
• "test"

Examples:

"metadata_text"

"test"

root sections sections items contents contents items content_id

Type: string

ID of the content to be displayed for the given content type (text, tests, etc.).

Examples:

"sample_text"

"section_intro"

root sections sections items contents contents items options

Type: object

Options for the content block.

Examples:

{
    "default_text": "This is a sample text block."
}

{
    "metric_id": "metric_1",
    "title": "Custom Title for Metric 1"
}

{
    "test_id": "adf_test"
}

root sections sections items contents contents items options default_text

Type: string

Default text for the content block. Only applicable for metadata_text content blocks.

root sections sections items contents contents items options title

Type: string

Title of the content block. Only applicable for test content blocks.

Generated using json-schema-for-humans on 2023-06-08 at 14:44:40 -0700

Add text blocks to templates

To add shared text blocks¹² to your templates via the YAML editor:

¹² Manage text block library

1. Retrieve keys for shared blocks

1. In the left sidebar, click Settings.

2. Under Documents, select Block Library.

3. Select Shared Blocks and click under the right-most column for the block you’d like to insert into a template.

4. Select Edit Details and review the details for that block.

5. To the right of the key, click to copy the key to your clipboard.

2. Insert block keys into YAML templates

1. With your shared text block’s key copied to your clipboard, open up the editor for a YAML template.¹³

2. Under a section or subsection’s contents block sequence,¹⁴ insert a sequence item of content_type: text with your block_key nested under options.

   For example:

   - id: section
     title: Section
     contents:
       - content_id: shared_block2
         content_type: text
         options:
           block_key: cmg5jb7tw000rgraxmxsavxez
   - id: parent_section
     title: Parent Section
     sections:
       - id: subsection
         title: Subsection
         parent_section: parent_section
         contents:
           - content_id: shared_block1
             content_type: text
             options:
               block_key: cmg5m1vru0000ibaxa34pl0wp

3. Finish editing your template, then save a new version.

¹³ Edit YAML templates

¹⁴ Template schema

Troubleshooting

The document template editor validates the YAML changes you make and flags any errors that it finds. If you make a change that the editor cannot parse correctly, the editor will not let you save the changes until you correct the YAML.

Common issues with YAML include incorrect indenting, imbalanced quotes, or missing colons between keys and values. If you run into issues with incorrect YAML, check the error message provided by the template editor, as it might provide a line and column number where the error occurs.