Articles tagged with 'Annotates'

Documenting Standards with Annotates

One of the challenges of maintaining standard libraries in Rave Architect is that it is not possible to add any kind of notes or extended metadata on library objects. For example, a standard form might have the following information associated with it:

  • A unique version number
  • A description of the form and its intended usage
  • Copyright holder and licensing information (e.g. for copyrighted scales)
  • SDTM domain associated with the Form
  • Rules regarding changes which are allowed to be made to the Form and still be standards compliant

Since Architect can't store this information it has to be maintained in some separate system. That might be a Metadata Repository (MDR), a set of modified Architect Loader Spreadsheets or in Word documents. However it is managed or presented, that metadata isn't available in Rave Architect where the study builder is doing their work.

So how does TrialGrid help?

Additional Properties for Forms and Fields

First of all, TrialGrid allows you to add additional metadata properties to Forms and to Fields.

Here we add a property "Field Set" to all fields:

Field Set Property

And we do the same for the other properties we want:

  • SDTM identifier for fields
  • Instructions, Copyright, Version and SDTM Domain for Forms


Note that Version and SDTM Domain properties for Forms and Field Set properties for Field are marked as "show in lists". This tells the system to include this value in the Field and Form lists respectively.

Now that we have added these additional metadata properties we can now update these in our Form designer:

Setting Properties

Now our Form listing contains the Version and SDTM Domain for that form:

Form Listing

We can also complete some property settings for Fields:

Setting Field Properties

Note that for the Collection date we have entered a field set of COLLECTION_PLUS_AGE. In this form we should either be using COLLECTION_DATE and AGE fields or the Date of Birth Field. Later we'll use this custom property to display different sets of fields in different colors in our annotates.

Exporting and Importing Custom Properties

So far we've added custom properties to our Forms and Fields. This provides useful additional information to Study Builders inside the TrialGrid Form Editor. That's great if you're only using TrialGrid to manage your standards and to build studies - what if you want to load those custom properties into TrialGrid from an MDR export or want to feed the information captured in TrialGrid to other downstream processes?

TrialGrid provides this data as part of the Architect Loader Spreadsheet and can import and export this data:

Properties in the ALS

It's simply added as an extra sheet in the ALS which Rave Architect will ignore.

Including Custom Properties in Annotate output

Part of the reason we add additional metadata to Forms and to Fields is so that we can communicate this additional information to other team members who may not be study builders. Including this metadata in an annotate is one good example, so lets do that.

Annotates are a new feature of TrialGrid, they allow you to define a template which can be used to generate a Microsoft Word document. We start with a simple annotate that just shows the basics about our Demographics form:

Annotate Step 1

So far it contains none of the additional metadata which we just added. We'll need to edit the annotate template to do that. At the moment only TrialGrid employees can modify templates but I'm showing how it is done here because we expect that users will have the option to modify their own templates in future.

Adding Instructions

The format of annotate templates are very similar to HTML. Here we add a level 4 heading, grab the "Instructions" custom property and if it is defined (it may not have been set for all Forms) we insert the value into a paragraph before the layout:

Annotate Step 2

We can add the Form version and Copyright properties to the table of standard Form properties using markup like this to add a row to a table:

Adding a new Row

that generates an annotate like:

Annotate Step 3

Next we want to add the SDTM annotations. Typically these are done in color. We could choose any color for the background of these sections of text but lets go with aqua. Here we show how we add that text in that color to the field:

Adding SDTM field

And we do something similar to the top of the form to add the SDTM domain there:

Annotate 4

Lastly we want to highlight the rows of different Field groups to show those that should not be used together. The logic for this is reasonably complex but can be done within the template system in 8 lines. We need to look at every field and determine if it has a "Field Set" property set. For each unique "Field Set" value we assign a unique color from a list of colors we provide.

The result is:

Annotate 5

The colors used here make it clear which groups of fields belong together. Note that this isn't a feature of TrialGrid, it's something we created ourselves with custom properties and some modification of our annotate generator - if you have a different system or different metadata you want to capture and show in annotates this can easily be achieved!


In this post we showed how..

  1. Custom metadata (properties) can be defined in TrialGrid for Forms and Fields.
  2. Properties can be edited in the Form editor
  3. Property values appear in system listings such as the Form list
  4. Properties can be imported and exported into/from the TrialGrid system using the Architect Loader Spreadsheet
  5. Properties can be included in the new Annotate Templates system to document standards, usage instructions and key metadata such as SDTM annotations.

We're barely scratching the surface of what you can do with the annotate template system. Essentially it's a report writing engine that has access to all the data in an Architect Study Draft. That includes all the extra information that TrialGrid captures and that we haven't yet mentioned here - user comments on design objects, the audit trail of changes to objects, the standards compliance workflow state of an object, custom labels (such as workflow state) applied to an item and a whole lot more.

Contact us if you have particular needs for annotates or Draft reports. We can help!

Annotates in Microsoft Word

If you are building studies in Medidata Rave, sooner or later you'll want to generate an Annotated Case Report Form so that you can communicate the study design with other team members who may not have access to Rave and to document the study data structures.

Some time ago we were asked whether we could create annotated CRFs in Microsoft Word format since this format is easily modified and can easily be converted into PDF (and many other formats) from Word.

Experiments with Template solutions

For a proof of concept we began by looking at templating solutions for Word. The idea was to have a Word document and then "decorate" it with template control tags which would allow us to loop over collections such as the list of Forms in a study and its Fields and insert text.

This seemed like it would work well for simple content:

Simple Content

But for complex content like generating the Annotate of a Form it soon became a tangled mess of template tags that mixed up the content and the formatting.

Messy Templates

The idea had promise, "It's just a word processing document!" but the reality didn't deliver for complex documents like annotates.


Back at the drawing board we thought about next steps and refined our requirements:

  1. Word Based. We love free software but our corporate users have Microsoft Word installed already. Often their computers are locked down so that they can't install new software even if it is free.

  2. Flexible. Should be able to use Word features such as tables, borders, font-sizes and colors etc.

  3. Easy to author for a technical data manager but not code-inside-Word.

"Easy" is a relative term and difficult to reconcile with "Flexible" but if we could deliver a solution with roughly the complexity of authoring HTML web pages that seemed a reasonable compromise.

Word Documents from Markup

Inserting HTML into Word documents is possible. We tried it, but it didn't give us the fine level of control we wanted for generating our documents. Could we instead create a markup language for Word? Something like HTML?

Here is a simple example of the markup language we created:

<?xml version="1.0" encoding="utf-8" ?>
    <heading level="0" align="center">~ Invoice ~</heading>
        Dear Sir/Madam,<br/><br/>
        <run font-bold="true">Thank you</run> for your order:
    <table style="Light Shading Accent 1">
            <cell>User Licenses</cell>
    <para space-before="0.5cm">
        Yours Sincerely,<br/>
        The TrialGrid Team

to generate:

Word from Markup

This markup language gives us the ability to create headers, footers, tables of contents, insert pictures, change page sizing, manage fonts and styling etc.

Generating Annotates

With this markup language we were able to finally start on building our Annotate generator. Here's a sneak peek of an annotate that just shows the layout of the Form:

Simple Annotate


We didn't set out to create a system for generating any kind of Word document but it gives us a lot of flexibility in generating all kinds of annotate variants. In the example above we don't show Field OIDs or names but we can easily add that in any font, color or position you might want.

The markup to generate this result is not too complex and we plan to make it available to our users so that they can modify it and make their own variants.

In the meantime, if you have ever wanted something more or different from your Medidata Rave annotates please do get in contact, we'd be happy to discuss your requirements and maybe incorporate them.