Configuring Custom Metrics, KRIs and QTLs

This guide provides detailed instructions on how to upload and structure custom metric data files in the form of <UniqueMetricName>.dynmetric.json files. Custom metrics are used to track various study-related data over time, and it is important to follow specific guidelines when preparing and uploading these files.

Table of Contents

1. Introduction
2. File Naming Convention
3. File Structure and Content
4. Adding Reports
5. Data Import
6. Creating a Custom Metric
7. Creating Custom KRI and QTL
8. Data Reprocessing

1. Introduction

Custom metric data can be a crucial part of your study data, allowing you to track various custom metrics over time. To ensure successful data management, follow the guidelines outlined below when uploading and structuring custom metric data files.

2. File Naming Convention

• Filename: Each custom metric data file should have this format: <UniqueMetricName>.dynmetric.json.
• File Extension: The file extension must always be .dynmetric.json.
• Unique Metric Name: The <UniqueMetricName> must be a distinctive name for your metric and must not contain underscores. It should be unique across all custom metrics.
• Zip Archive: To upload your custom metric data, you must create a zip archive containing all the relevant .dynmetric.json files. This zip archive should also include other study data files, if applicable.

3. File Structure and Content

Each *.dynmetric.json file should adhere to the following structure:

{
   "Data": [
      {
          "ValueTime": "<Timestamp>",
          "EntityType": "<Entity>",
          "ExternalKey": "<Key>",
          "DataPoint": {
             "Value": <Value>,
             "ValueExplanation": "<ValueExplanation>",
             "Reports": [
                {
                  "RelativeFilePath": "<RelativeFilePath>",
                  "Name": "<Name>",
                  "Description": "<Description>",
                  "MimeType": "<MimeType>",
                  "IsRoot": <IsRoot>
               },
            // Additional reports can be added here
            ]
         }
      },
      // Additional data points can be added here
   ]
}

• The root element must be “Data” and is a list of metric data points.
• <Timestamp>: The timestamp represents the time of the metric value in ISO 8601 format (e.g., “2011-04-23T18:25:43.000Z”).
• <Entity>: The “EntityType” specifies the level of the metric data and can be one of the following: study, country, site, patient, or visit.

• <Key>: The “ExternalKey” should be in sync with the ExternalKey used in the study.

  

• <Value>: “Value” represents the actual metric value for the data point.
• <ValueExplanation>: here you can add text that explains how the values was calculated.

4. Adding Reports

You can include PDF and HTML reports associated with your custom metric data. These reports will be visible on the metric page. Each report should be structured as follows:

{
   "RelativeFilePath": "<RelativeFilePath>",
   "Name": "<Name>",
   "Description": "<Description>",
   "MimeType": "<MimeType>",
   "IsRoot": <IsRoot>
}

• <RelativeFilePath> (mandatory): The actual filename including the relative path of the report.
• <Name> (optional): The name of the report.
• <Description> (optional): A brief description of the report.
• <MimeType> (mandatory): The MIME type of the report (e.g., “text/html,” “application/pdf”).
• <IsRoot> (mandatory): Set to true if the report is the root report; otherwise, set it to false.
  • IsRoot: true => core report file,
  • IsRoot: false => supporting files for report (pics, scripts etc.)

5. Data Import

There are two ways to upload your zip archive containing all .dynmetric.json files and reports:

1. Along with other study data through the regular data import process
2. Separately, using customdimensions label in the data upload form field "Agreed Data Processing Workflow Labels" (as in the screenshot below). This will only import dynmetrics (and not other data) and will be quicker as the regular data import.

6. Creating a Custom Metric

1. After a successful data import, navigate to the Metrics page and click Create Custom Metric.

   

2. Select a Dimension among the ones that were uploaded as .dynmetric.json in the pop-up metric creation form.

3. Complete the rest of the fields. Some fields' placeholders suggest possible values as examples, but don't limit the users. Not mandatory fields are marked as (Optional). Unit of measure and Category fields allow the user to select already existing values or create new ones:

4. Select relevant levels from the list:

5. Once all mandatory fields are filled, click Save.
6. Double-check the new metric's details.
7. Click Confirm.

Note: selected dimension, calculation notes and levels can only be edited while creating a metric. If selected dimension, calculation notes and levels need to be changed after confirming metric's creation, the custom metric must be deleted and again created with the modified levels.

6. For the custom Metric you have created to appear in the list of Metrics, the study data needs to be synchronized first:

However, you will be able to see, edit, and delete it via the Manage Custom Metrics button even before that:

7. Inspect your custom metric in MyRBQM in the Metrics list under the selected Category. To find attached reports, navigate to the Metric page and click on the Folder icon in the Value column:

7. Custom KRI Creation and QTL Creation

1.     After creating your custom metric, navigate to KRIs page and click Create Custom KRI. Custom KRIs can only be based on the Custom Metrics.

2. Select the Calculation method.
3. Select the Input Metric (one of the already created Custom Metrics).

4. Enter the New Dimension Name.

   Note: Each custom KRI requires a new Dimension created for it, and the name of this dimension has to be unique. A suggestion is generated automatically after selecting the Input Dimension(s), but you will be asked to provide a unique one yourself if a Dimension with this name already exists. Please use only Latin characters and digits in this name and limit the length to 64 characters or fewer.

3. Similarly to the Metrics creation form, follow the wizard to fill in the rest of the fields and select the levels:

4. When all information entered, click Save.
5. Check all the details.
6. Click Confirm to create a KRI.

Note: selected Calculation Method, Dimension(s) and Levels can only be edited while creating a KRI. If Calculation Method, Dimension(s) and Levels need to be changed after confirming KRI's creation, the custom KRI must be deleted and again created with the modified levels.

5. For the custom KRI you have created to appear in the list of KRI, the study data needs to be synchronized first:

However, you will be able to see, edit, and delete it via the Manage Custom KRI button on the KRI page even before that.

Note: A custom QTL is created in the same way as a custom KRI. The Create and Manage Custom QTLs functions are located in the QTL tab:

8. Data Reprocessing

To ensure that your custom metric data is accurately reflected in your study data, it is important to reprocess the latest data import . You can initiate the reprocessing of the latest import by going to Study Settings -> Study Data page and selecting Re-process from this data package:

Note: Because of the intricacies of the software architecture, it is necessary for the Study Type to facilitate the import of custom metrics data (DynamicDataImport). If you're uncertain whether the Study Types deployed within your company support this feature, please contact Cyntegrity or refer to the Data Processing Specification in MyRBQM specific to your study and look up "DynamicDataImport". If you find this term, your study supports the data import of custom metrics.