Custom Properties (Metadata)

Custom Properties allow you to add metadata fields to objects in TrialGrid. Think of them as user-defined attributes that extend the built-in properties of each object type.

When you define a Custom Property for an object type in a URL, that property becomes available to all objects of that type in that URL. For example, adding a "Version" property to Fields means every field in your URL will have a Version attribute you can edit.

Supported Objects

Custom Properties can be associated with:

• Projects

• Drafts

• Custom Functions

• Data Dictionaries

• Data Dictionary Entries

• Derivations

• Edit Checks

• Forms

• Fields

• Folders

• Matrices

• Unit Dictionaries

• Test Cases

• Custom Objects

Property Types

Type	Description
Text	Free text up to 8,000 characters. Optionally constrained by a maximum length and/or a validation pattern (see Text Validation below).
HTML	Rich text with HTML formatting support. HTML content is sanitized for security. Script tags and potentially dangerous HTML are automatically removed.
Choice	A set of predefined options from which users select a value
Boolean	A true/false value. Displays as a dropdown with three options: blank (not set), TRUE, and FALSE.
Email	An email address. Values are validated to ensure they are properly formatted email addresses.
URI	A web address (URL). Values are validated to ensure they include a scheme (http, https, ftp) and are properly formatted.
Color	A hex color code in #rrggbb format (e.g. #ff5733). Displays as a colored swatch in listings. Uses a color picker for input.
Numeric	A numeric value. Optionally constrained by minimum/maximum values and number of decimal places (set to 0 for integers).
Date	A calendar date. Values are stored as ISO format (YYYY-MM-DD) and displayed using a native date picker.
DateTime	A date and time. Values are stored as UTC ISO datetimes (e.g. 2024-06-15T14:30:00Z). Users enter and edit values in their local time using a native datetime picker; conversion between UTC and local time happens transparently in the browser. Object listings render the value in the user's date format preference.
Reference	A reference to a custom object type. Creates a dynamic pick-list from custom objects of the referenced type in the same Draft.
Set	A multi-value selection from a fixed list of allowed values. Stored as a separator-joined string (default separator |). No allowed value may contain the separator character. See Set Values below.
User	A person, chosen from a list of the people who work on this object's Project. Listings show the person's name and picture. See User Values below.

Note

Converting between Date and DateTime types is supported with automatic value adjustment:

• Date -> DateTime: existing date values like 2024-06-15 are padded with UTC midnight to become 2024-06-15T00:00:00Z.

• DateTime -> Date: existing datetime values like 2024-06-15T14:30:00Z are truncated to 2024-06-15. This conversion is lossy. The time and timezone components are permanently dropped, and the conversion form does not currently warn about this. Confirm the value list before converting.

The same adjustments apply when converting via Text (Date -> Text -> DateTime, or DateTime -> Text -> Date).

Note

Timezone handling for DateTime values

DateTime values are stored in UTC (e.g. 2024-06-15T14:30:00Z). When a user enters or edits a value, the browser converts between UTC storage and the user's local time automatically. They always see and enter the value in their own timezone. Because absolute UTC instants are stored, the same DateTime value seen by a UK user as 15:30 will be seen by a US East Coast user as 10:30 for the same stored moment.

Important

Reference properties are only valid for Drafts and objects within Drafts. Projects cannot have reference properties. Note also that referenced properties cannot be self-referential so a custom object of type "Approval State" cannot have a reference property that relates to objects of type Approval State.

Editing a Property that is in use

Some type changes rewrite the values already stored against the property. Converting to Date or DateTime adjusts them as described above, and converting to Reference replaces them as described below.

If the property is part of a Custom Object identifier

Some properties make up the identifier of a Custom Object. Two kinds of edit change what those identifiers should be, so TrialGrid rebuilds them:

• Changing the property's type, because the identifier is built from the values you have just changed.

• Changing its Display Order, because the parts of an identifier appear in that order. Move a property in front of another and Monitoring / 2024-06-15 becomes 2024-06-15 / Monitoring.

TrialGrid does this for you. It starts a background task when you save, and the message on screen tells you which object type is being updated. You can watch the task finish in the usual way. There is nothing else you need to do.

Two things to be aware of once it has finished:

• Standards deviation explanations recorded against the old identifier of an object whose identifier changed are marked obsolete, so you can see they need attention. Nothing is deleted.

• Test Cases that referred to an object by its old identifier are unlinked, and show the object as one they can no longer find.

Note

Objects held inside one of the rebuilt objects are matched to a library using their parent's identifier as well as their own, so their explanations may need checking even though their own identifiers did not change. Use the Identify Obsolete button on the affected Projects to review them.

Important

Standards library rules match objects by identifier, and TrialGrid does not update them for you. If the identifiers have changed, check any rules that refer to those objects and update them yourself.

Converting to a Reference

A Reference does not store text. It stores a link to a particular object, so each of your existing text values has to be matched to an object of the chosen type before it can become a link.

TrialGrid checks this before it accepts the change. If any value does not match an object, the change is refused and you are shown which values are at fault.

Changing which type a Reference points at

You cannot point an existing Reference property at a different Object type while it holds values, because those values are links to objects of the type it points at now. Clear the values first, or add a new property and make the old one inactive.

Property Attributes

Each Custom Property has several configurable attributes:

Attribute	Description
Display Order	Controls the sequence in which properties appear. Properties with the same order value appear in undefined order. Negative values are allowed.
Active	Determines if the property is available for use. Unchecking this retires the property while preserving existing data.
Show in Lists	Makes the property visible in object listings alongside standard attributes like Name and OID.
Reserved for Actions	Prevents manual editing. Only Actions can modify these values. Read-only properties display with a icon.
Include in Compliance Calculations	Controls whether property values affect compliance checks when comparing objects for standards deviations.
Send to Agents	Controls whether this property's value is included in the specification an AI Agent reads. Off until you turn it on, so a value reaches the model only once someone has decided it belongs in the specification. Only shown on URLs with LLM Agents enabled.
Agent Instruction	Guidance for an AI Agent on how to read this property's value, sent with the value when the property is set. See Agent Instructions, where every property of an object type is shown together — the recommended place to write these. Only shown on URLs with LLM Agents enabled.

Text Validation

Text-type properties support two optional validation constraints. They are enforced wherever property values are entered: the form editor, property sheets, and action dialogs.

Maximum Length

Limits the number of characters allowed. Values exceeding this limit are rejected with a message indicating the maximum length.

Validation Pattern

A regular expression that values must match in full. For example, [A-Z]{2}\d+ requires two uppercase letters followed by one or more digits. A good introduction to regular expressions is available at https://regexone.com/ and you can test patterns at https://regex101.com/.

Both constraints are configured on the property definition form when the value type is set to Text. They appear automatically and are hidden for other value types.

When editing a property definition, TrialGrid checks existing values against new constraints. If any existing values would violate the new constraint, the change is rejected with an example of a conflicting value.

Tip

Keep validation patterns simple. Common examples include [A-Z0-9]+ for alphanumeric codes or \d{4}-\d{2}-\d{2} for date-like strings. Patterns that could cause excessive backtracking (nested quantifiers like (a+)+) are automatically rejected.

Set Values

Set-type properties allow users to pick zero or more values from a fixed list of allowed values. Values are stored as a single string with elements joined by a separator character (default |).

Defining allowed values

When creating a Set property, enter the allowed values one per line. Duplicate values (case-insensitive) and values containing the separator character are rejected.

Separator

Each Set property has a configurable separator character (default |). The separator is the character used to join elements when storing the property value. No allowed value may contain the separator character. Choose a separator that does not appear in any of your values. Common alternatives are ; or ,, if you are sure your values will never contain them.

Saving values

When a user picks values for a Set property, TrialGrid validates that every selected element is in the allowed values list. Values that contain elements not in the list are rejected.

Comparison

When comparing objects, Set property values are canonicalised by sorting their elements alphabetically. This means A|B and B|A compare as equal. The order in which a user picks values does not affect comparison results.

User Values

A User property records a person. Use one for things like who owns a Form or who signed off a Folder.

Choosing a person

The picker lists the people who have a role in the Project the object belongs to. On a page that is not about one Project, such as the Projects list for a URL or the Action editor, it lists the people who have a role on the URL instead, because those pages cover objects from many Projects.

Each entry shows the person's name, their email address and their picture, so you can tell two similar names apart. Type in the box at the top of the list to search.

How it looks in listings

Object lists show the person's picture and name, the same way an assigned user is shown elsewhere.

When someone leaves

Nothing you have already recorded is lost. If a person's role in the Project is removed, or their account is deactivated, every value naming them still shows their name. They stay in the picker for any object that already names them, so you can save that object without losing the value. They are not offered for objects that do not already name them.

Adding a Project

A new Project has no members yet, so there is nobody to choose. Create the Project first, add people to it, then set the value.

Who can be named

A value can name anyone who works here. There are three ways to qualify: belonging to this URL's Organization, holding a role in one of its Projects, or holding a role on one of its URLs.

Belonging to the Organization is only one of the three, so a contractor whose own account sits in another Organization can be named, as long as you have given them a role in a Project or on a URL here. Someone with none of the three cannot be chosen, and if a value somehow names one they show as a question mark rather than by name. This is checked when the value is saved, whichever screen it is saved from, and again when it is displayed.

Being nameable is not the same as being offered. The picker on a page about one Project lists that Project's people, so a contractor you have given a URL role but no Project role is offered on URL-level pages and not on a Form or Folder. Give them a role in the Project to have them offered there.

Anyone in the picker who is not a member of this Project is marked "not in this Project". That covers someone whose role was removed, someone who only ever held a URL role, and someone a value names because the property was converted from a Text property or the object came from an upload.

Changing an existing property to User

You do not need to know anyone's user id. Each stored value is matched to a person by email address, by user name, or by user id, and is rewritten to point at that person when you save. Upper and lower case do not matter.

TrialGrid refuses the change, and lists the values at fault, when a value matches nobody who works here or matches more than one person. The second happens when two accounts share an email address: correct those values to something that names one person, then change the type.

Anything you have not corrected is not silently dropped. The change is refused until every value names exactly one person.

Downloading and uploading

A Draft download writes the person's user name rather than a number, so the value still means something wherever the Draft is uploaded, and the upload matches the name back to a person. A name nobody holds is reported and the value left unset, as is a person who does not work in the Organization you are uploading to. See Import and Export.

Elsewhere

An Action cannot set a User property: see Property operations. A Document Template holds the stored number and turns it into a person with user_by_id(): see Template Context.

Managing Choice Values

Choice-type properties have a dedicated management page for their value list. To access it, edit the property and click Manage Value Choices.

Adding values

Enter a new value and click Add. Duplicate values (case-insensitive) are not allowed.

Renaming values

Click the rename button next to a value, enter the new name and confirm. TrialGrid updates the definition immediately and queues a background task to update all objects that use the old value. If the new name matches an existing value you are offered the option to merge instead. See Effects of a Bulk Value Change for what else the background task updates.

Merging values

When renaming would create a duplicate, TrialGrid offers to merge the source value into the target. Merging removes the source from the value list and updates all objects that used it to the target value.

Deleting values

A value can only be deleted if it is not currently assigned to any object. TrialGrid checks usage in the background and reports an error if the value is in use.

Reordering values

Use the up/down arrows to change the display order of values. The order is reflected in all dropdown selectors.

Activating and deactivating values

Individual choice values can be deactivated without removing them. Deactivated values:

• Do not appear in dropdown selectors for new selections

• Still appear in dropdowns where an object already has that value, so existing data is preserved

• Remain in the value list on the management page and can be reactivated at any time

Tip

Deactivating a value is useful when a choice should no longer be assigned to new objects but existing assignments must be preserved.

Converting Text Values

Text-type properties have a Convert Values utility for bulk-replacing values across all objects. This is useful when preparing data for a property type change. For example, you can convert free-text "Yes"/"No" responses to standardised values before changing the property to a Choice type.

To access it, edit a text-type property and click Convert Values in the right-hand panel.

The Convert Values page shows a table of all distinct non-empty values currently in use, along with the number of objects that have each value. You can search and sort this list.

Converting a value

Click Convert next to the value you want to change, enter the new value and confirm. TrialGrid shows the number of records that will be updated and asks for confirmation before proceeding.

The conversion runs as a background task, updating records in batches with a progress indicator. Fingerprints for affected objects are recalculated as part of each batch so that compliance results remain up to date throughout the operation. See Effects of a Bulk Value Change for the full set of things the task keeps in step.

When the conversion completes, the table refreshes automatically to show the updated values and counts.

Validation

New values are validated against any text constraints defined on the property:

• Values that exceed the maximum length are rejected

• Values that do not match the validation pattern are rejected

This prevents introducing invalid data during the conversion.

Case sensitivity

Text value conversions use exact (case-sensitive) matching. Converting "Yes" will not affect "yes" or "YES". Convert each spelling separately if you need to.

Tip

To convert a text property to a choice property: first use Convert Values to standardise all values to the desired choice options, then change the property type to Choice and define those values as choices.

Effects of a Bulk Value Change

Renaming or merging a choice value, and converting or deleting a text value, all rewrite that value on every object that holds it. Those values feed other parts of TrialGrid, so each of these operations also:

Recalculates fingerprints

The fingerprints of the affected objects are recalculated as each batch is written. Where the property belongs to a child object, such as a Field, the parent object's fingerprint is recalculated too, so comparison and compliance results stay in step with the new value.

Recalculates identifiers

Where the property contributes to a Custom Object identifier, the identifiers of the affected objects are rebuilt from their new values. Renaming a value that appears in an identifier therefore changes that identifier.

Recalculates standards compliance

Objects in drafts linked to a standards library are queued for a compliance recalculation. Where the property belongs to a child object it is the parent that is recalculated, since that is where compliance is held. Objects in drafts that are not linked to a library are left alone, as compliance does not apply to them.

Flags standards explanations left behind

Standards deviation explanations and approvals are matched to objects by identifier, so an object whose identifier changes stops matching the ones recorded against its old name. Those explanations are marked obsolete rather than left silently matching nothing, and any explanation already recorded against the object's new identifier is picked back up. Nothing is deleted: the explanation and its approval state are preserved, and the flag lifts by itself if the explanation is used again.

Updates Test Case references

Test Cases refer to objects by identifier. Where a changed identifier no longer matches the reference that named it, that reference is unlinked. The Test Case then shows it as an object it can no longer find, in the same way as if the object had been renamed in the object editor.

Does not run Automatic Actions

Changing a value is maintenance of the value list rather than an edit to the objects that use it, so Automatic Actions are not run against the affected objects. Without this, a single rename would evaluate every action precondition that reads the property against every object holding the value at once, and could apply labels or other operations across the whole set. Actions can still be applied deliberately from the object lists once the change is complete.

Important

Standards library rules are matched to objects by identifier, and unlike explanations they are not adjusted automatically. If a rename changes the identifiers of objects your rules refer to, update those rules yourself. Do this after the rename rather than before, so the rules are written against the identifiers the objects end up with.

Note

Merging two values can leave two objects with the same identifier, if the merged values were the only thing that distinguished them. The merge completes rather than stopping part-way, so review the affected objects afterwards if this is a possibility.

Inactive Properties

When a property is marked inactive, it becomes hidden in most contexts but remains functional where already in use:

Hidden from:

• New object creation screens

• Property listings

• Spreadsheet views (unless at least one row has a value)

• Metadata tabs in editors (unless a value exists)

• Comparison views (unless either object has a value)

Still active in:

• Compliance calculations and rules

• Diagnostic processing

• ALS imports and exports

• Existing projects that already use the property

Tip

Use inactive properties to phase out metadata fields without breaking existing projects or losing historical data.

Compliance Calculations

The "Include in Compliance Calculations" setting is particularly useful for library objects that contain metadata not relevant to study drafts.

Example scenario:

A library form might have properties like "Standards Reference" or "Usage Instructions" that shouldn't trigger compliance failures when absent from study drafts.

Import and Export

Custom Properties integrate with the Architect Loader Spreadsheet format:

Export

Properties are exported to worksheets named TG_<objectname>Properties (e.g., TG_FieldProperties)

Import

Properties can be imported from these same worksheets, with one critical requirement:

Important

TrialGrid only imports properties that already exist in the destination URL. For example, if your spreadsheet contains a "DOMAIN" property for Fields, it will only import if "DOMAIN" is already defined as a Field property in the target URL. Undefined properties are skipped with a warning.

Note

Medidata Rave ignores Custom Property worksheets in Architect Loader Spreadsheets uploaded to Architect.

Common Use Cases

Version Management

Add a "Version" text property to track iteration numbers across draft objects

Documentation

Add an HTML-enabled "Instructions" text property to provide formatted guidance within objects