RTSM Actuals Extract Specification

Created by

Last updated 11 November 2024, 14:22

Overview
- PDF Download
Summary
Frequency
Connection
Authentication
JSON File
Appendix:
- JSON Schema

Overview

The Actuals Extract Specification defines the format RTSM actuals extract files have to comply with to be used successfully in 4C Supply®. The specification is displayed on this page, in full, beginning in the next section. It is also available for download below:

PDF Download

⬇️

If you have questions about any aspect of this specification, please reach out to the 4C Supply® team.

Summary

This specification defines how the RTSM Actuals Extract must be formatted for importing into the 4C Supply® forecasting tool. Files must be received in JSON format with the specified data structure for each required section. Each file should be a full export of the data in the RTSM rather than a delta file. Each file should be delivered independently and provide visibility to the status of the study at that point in time.

Frequency

Files will be requested to be delivered on a frequency dictated by the study team. This could be daily, weekly, monthly, etc. The delivery frequency should be provided by the study Sponsor.

Connection

4G Clinical provides an API to receive actuals data. Applications calling the actuals data endpoint must be authenticated. Access to the specific actuals endpoint is limited based on the specific permissions assigned to the calling application. See below for details on authentication.

Once authenticated, the actuals data will be sent to the actuals API endpoint: https://{sponsor}.4gclinical.com/_/api/partner/actuals

Required Headers for the API call:

· Content_type: application/json

· Authorization: Bearer {access_token}

· study_code: The study code for the actuals data

Note: The body of the API call should contain the actuals data in JSON format.

Authentication

Authentication is based on the OAUTH 2 standard. A single endpoint exists for authentication which returns an access token that needs to be sent along with the actuals data.

The authentication endpoint is: https://{sponsor}.4gclinical.com/_/api/partner/oauth/token/
Details for the authentication API call:
- Method: POST
- Content-Type: application/x-www-form-urlencoded

Body parameters:

Key	Value
grant_type	client_credentials
client_id	Provided by 4G
client_secret	Provided by 4G

Sample return:

 {
"access_token": "My_Access_Token",
"token_type": "bearer",
"expires_in": 1800,
}

JSON File

The data file should follow the JSON format. The structure of the file is described here and summarized in the JSON schema in the appendix.

File Structure

The file consists of one object that contains the following key-value pairs:

Key	Value Type	Description
`extract_date`	string	Date of extract creation. The format must be ‘YYYY-MM-DD’.
`extract_version`	string	Should be ‘1.0.0’.
`study_code`	string	Should match study code used in 4C Supply®.
`desc`	string	Typically contains the study code and extract date.
`data`	object	Contains all study data, see below for the details.

Data

All fields listed below are required unless stated otherwise. All the study data are contained in the object named ‘data’. This object contains the following key-value pairs:

Key	Value Type	Description
`references`	object	List of references used in other tables. See References section for details.
`sites`	array of `site`	List of sites. See Sites section for details.
`shipments`	array of `shipment`	List of shipments. See Shipments section for details.
`lots`	array of `lot`	List of lots. See Lots section for details.
`inventories`	array of `inventory`	List of inventories at sites and depots. See Inventories section for details.
`patients`	array of `patient`	List of patients. See Patients section for details.
`patient_visits`	array of `patient_visit`	List of patient visits. See Patient Visits section for details.
`currently_enrolling_cohort`	string	Optional entry. If used, must match an `id` listed in the cohorts reference section. If there is no such data this value should be `""`.

References

This section contains all object’s id that will be referred to in other sections of the data extract. It consists of arrays of ref_object or ref_visit for patient_visits.

ref_object

Field	Value Type	Description
`id`	string	Name of the object that will be used to refer to it in other sections.
`description`	string	Human-readable name of the object.

ref_visit

Field	Value Type	Description
`id`	string	Name of the object that will be used to refer to it in other sections.
`description`	string	Human readable visit name.
`is_optional`	boolean	Use `false` if it is a standard, scheduled visit. Use `true` if the visit is optional (unscheduled).

Object references should contain the following elements:

Field	Value Type	Description
`depots`	array of `ref_object`
`cohorts`	array of `ref_object`	If cohorts are not used in the study, set field to `[]`.
`countries`	array of `ref_object`	Our recommendation is to use the ISO alpha-3 country code as the `id`. However, the system will allow import of alpha-2 country codes, or even the full country names.
`kit_types`	array of `ref_object`
`kit_statuses`	array of `ref_object`
`treatment_arms`	array of `ref_object`	If treatment arms are not used in the study, set field to `[]`.
`patient_statuses`	array of `ref_object`
`patient_visits`	array of ref_visit
`titration_levels`	array of `ref_object`	If titration levels are not used in the study, set field to `[]`.
`site_enrollment_groups`	array of `ref_object`	Site group categories used for enrollment forecast and resupply strategy (e.g., Low, Medium, High)

Example of references section:

"references": {
        "depots": [
            {
                "id": "Regional_US",
                "description":"Regional Depot US"
            },
            {
                "id": "Regional_UK",
                "description":"Regional Depot UK"
            },
        ],
        "cohorts": [],
        "countries": [
            {
                "id": "USA",
                "description": "United States"
            },
            {
                "id": "AUS",
                "description": "Australia"
            },
            {
                "id": "GBR",
                "description": "UK"
            }
        ],
        "kit_types": [
            {
                "id": "Active 25mg",
                "description": "Active 25mg"
            },
            {
                "id": "Placebo 25mg",
                "description": "Placebo 25mg"
            }
        ],
        "kit_statuses": [
            {
                "id": "In Transit"
                "description": "In Transit"
            },
            {
                "id": "Rejected"
                "description": "Rejected"
            },
            {
                "id": "Queued"
                "description": "Queued"
            },
            {
                "id": "Destroyed"
                "description": "Destroyed"
            },
            {
                "id": "Released"
                "description": "Released"
            },
            {
                "id": "Quarantined"
                "description": "Quarantined"
            },
            {
                "id": "Available"
                "description": "Available"
            },
            {
                "id": "Dispensed"
                "description": "Dispensed"
            }
        ],
        "patient_visits": [
            {
                "id": "screening",
                "is_optional": false
            },
            {
                "id": "visit_3",
                "is_optional": false
            },
            {
                "id": "randomization",
                "is_optional": false
            }
        ],
        "treatment_arms": [
            {
                "id": "TGA / Active123"
                "description": "TGA / Active123"
            },
            {
                "id": "TGB / Placebo"
                "description": "TGB / Placebo"
            }
        ],
        "patient_statuses": [
            {
                "id": "Screening"
                "description": "Screening"
            },
            {
                "id": "Discontinued"
                "description": "Discontinued"
            },
            {
                "id": "Active"
                "description": "Active"
            },
            {
                "id": "Randomized"
                "description": "Randomized"
            },
            {
                "id": "Screen Failed"
                "description": "Screen Failed"
            }
        ],
        "titration_levels": [
            {
                "id": "10mg"
                "description": "10mg"
            },
            {
                "id": "40mg"
                "description": "40mg"
            },
        ],
        "site_enrollment_groups": [
            {
                "id": "High"
                "description": "High"
            },
            {
                "id": "Low"
                "description": "Low"
            },
            {
                "id": "Med",
                "description": "Med"
            }
        ]
    },

Lots

Each finished good lot released into the RTSM is required in the Lots section of the actuals extract file.

The table below lists the expected fields for each lot object.

Field	Value Type	Description
`lot_id`	string	This needs to be the unblinded lot number from the RTSM. This unblinded lot number would be considered the lot id that is being sent to the depot for unblinded ordering purposes.
`expiry_date`	string	This is the lot expiry date from the RTSM. The format must be ‘YYYY-MM-DD’.
`approved_countries`	array of string	Optional array containing id’s of countries for which the lot is approved. Values must match an id listed in the countries reference section.

Example of lots section (array of lot object):

"lots": [
        {
            "lot_id": "ABC123",
            "expiry_date": "2024-06-30",
            "approved_countries": []
        },
        {
            "lot_id": "ABC456",
            "expiry_date": "2024-06-30",
            "approved_countries": [
                "GBR",
                "USA",
                "DEU",
                "AUS",
                "ESP",
                "FRA"
            ]
        }]

Sites

Each clinical site in the RTSM will be required in the Sites section of the actuals extract file.

The table below lists the expected fields for each site object.

Field	Value Type	Description
`country`	string	Value must match an `id` listed in the countries reference section.
`site_code`	string	Unique identifier of the site used to associate patients to the site.
`activation_date`	string	The date the site was opened in the RTSM for the first time. If the site has not been activated yet, value should be `""`. The format must be ‘YYYY-MM-DD’. If a site has been closed this date must still be populated with the initial activation date, but the `enrollment_open` field should be set to `false`.
`enrollment_open`	boolean	Set as `true` if the site has been opened in the RTSM and is ready to screen/enroll patients, set as `false` otherwise.
`enrollment_group`	string	Value must match an id listed in the `site_enrollment_groups` reference section.
`inventory_site_code`	string	Identifier of the site, it will be used to associate the inventory to the sites. Must be different from any `id` listed in the depot reference section (otherwise inventory location will be ambiguous). Several sites can use the same value if they are sharing inventory.

Example of sites section (array of site object):

"sites": [
        {
            "country": "DEU",
            "site_code": "101",
            "activation_date": "2024-08-17",
            "enrollment_open": true,
            "enrollment_group": "Low",
            "inventory_site_code": "101"
        },
        {
            "country": "DEU",
            "site_code": "102",
            "activation_date": "2024-08-17",
            "enrollment_open": false,
            "enrollment_group": "Low",
            "inventory_site_code": "102"
        }
        ]

Shipments

Each shipment currently in transit in the RTSM will be required in the Shipments section of the actuals extract file.

The table below lists the expected fields for each in transit shipment object.

Field	Value Type	Description
`shipment_id`	string	Unique shipment identifier used to associate inventory to the shipment.
`origin`	string	Value must match either: An `id` defined in the depots reference section. An `inventory_site_code` defined in the `sites` section.
`destination`	string	Value must match either: An `id` defined in the depots reference section. An `inventory_site_code` defined in the `sites` section.
`date_created`	string	The date on which the shipment was created in the RTSM. The format must be ‘YYYY-MM-DD’.

Example of shipments section (array of shipment object):

 "shipments": [
        {
            "shipment_id": "10545",
            "origin": "EU_Depot",
            "destination": "Almac_US",
            "date_created": "2021-01-21"
        },
        {
            "shipment_id": "10547",
            "origin": "Almac_US",
            "destination": "101",
            "date_created": "2021-01-22"
        },]

Patients

All patients in the study should be included in the Patients section of the RTSM actuals extract file, regardless of their current enrollment status.

The table below lists the expected fields for each patient object.

Field	Value Type	Description
`site`	string	Value must match a `site_code` defined in the sites section.
`cohort`	string	Value must match an `id` defined in the cohorts reference section. If patient has no cohort, value should be `""`.
`status`	string	Value must match an `id` defined in the `patient_statuses` reference section.
`patient_id`	string	Unique identifier of the patient.
`date_enrolled`	string	Date the patient has been enrolled or randomized. If the patient is still in screening, value should be `""`. The format must be ‘YYYY-MM-DD’.
`treatment_arm`	string	Value must match an `id` defined in the `treatment_arm` reference section. If patient has no treatment arm, value should be `""`.
`date_registered`	string	This is the date the patient has first presented into the study visit schedule. The format must be ‘YYYY-MM-DD’.

Example of patients section (array of patient object):

"patients": [
        {
            "site": "101",
            "cohort": "",
            "status": "Screened",
            "patient_id": "101-0001",
            "date_enrolled": "",
            "treatment_arm": "",
            "date_registered": "2021-01-12"
        },
        {
            "site": "102",
            "cohort": "",
            "status": "Randomized",
            "patient_id": "102-0001",
            "date_enrolled": "2020-12-21",
            "treatment_arm": "TGA / Active123",
            "date_registered": "2020-12-03"
        }]

Inventories

All inventory for the study will be required in the Inventory section in the RTSM actuals extract file. The data structure example is listed below with the expected fields for each inventory location. Kits in all statuses and at every location (depots, sites, and in transit) should be included.

Note: Kits of the same lot, kit type, in the same status and at the same location, should be grouped in a single entry using the quantity field to specify how many kits there are in this situation.

The table below lists the expected fields for each inventory object.

Field	Value Type	Description
`lot`	string	Value must match a `lot_id` defined in the `lots` section.
`kit_type`	string	Value must match an `id` defined in the `kit_type` reference section.
`location`	string	Value must match either: an `id` defined in the `depot` reference section. an `inventory_site_code` defined in the `site` section. Note: Kits in transit should be associated with their destination.
`quantity`	number	Quantity of kits.
`kit_status`	string	Value must match an `id` defined in the `kit_statuses` reference section.
`shipment_id`	string	Optional field that should only be defined for kits that are currently in-transit. Value must match a `shipment_id` defined in the `shipments` section.

Example of inventories section (array of inventory object):

"inventories": [
        {
            "lot": "ABC465",
            "kit_type": "Placebo to 25mg",
            "location": "Almac_US",
            "quantity": 5,
            "kit_status": "In Transit",
            "shipment_id": "10546"
        },
        {
            "lot": "ABC456",
            "kit_type": "Placebo to 25mg",
            "location": "102",
            "quantity": 25,
            "kit_status": "Available"
        }]

Patient Visits and Dispensings

All patient visits for the study will be required in the Patient Visit section in the RTSM actuals extract file. The data structure example is listed below with the expected fields for each patient visit and the dispensing associated with that visit. All visits, including non-dispensing and unscheduled visits, should be included.

The table below lists the expected fields for each patient_visit object.

Field	Value Type	Description
`patient_id`	string	Value must match a `patient_id` defined in the `patients` section.
`visit_id`	string	Value must match an `id` defined in the `patient_visits` reference section.
`visit_date`	string	Date of the visit. The format must be ‘YYYY-MM-DD’.
`unscheduled_visit`	boolean	Use `false` if it is a standard, scheduled visit. Use `true` if the visit is optional (unscheduled).
`cohort`	string	Cohort of the patient. Value must match an `id` defined in the `cohorts` reference section. If patient had no cohort when the visit was performed, value should be `""`.
`treatment_arm`	string	Treatment arm of the patient at the time of the visit. Value must match one an id defined in the `treatment_arm` reference section. If patient had no treatment arm when the visit was performed, value should be `""`.
`titration_level`	string	Titration level of the patient at the time of the visit. Value must match an `id` defined in the `titration_levels` reference section. If patient had no titration level when the visit was performed, value should be `""`.
`dispensings`	Array of `patient_dispensing` object (see definition below)	Dispensing that occurred at the visit. If there were no kits dispensed at that visit, set field to `[]`.
`other data`	object	Should contain other patient data at the time of the visit that’s relevant from a dispensing / forecasting point of view. For example, the patient’s weight if the dispensing is weight-based. If there is no such data for that patient visit, value should be `{}`.

The table below lists the expected fields for each patient_dispensing object.

Field	Value Type	Description
`kit_type`	string	Value must match an id defined in the `kit_type` reference section.
`quantity`	number	Quantity of kits dispensed.
`multi_visit_dispensing`	boolean	Set to `true` if dispensing covers multiple visits. Set to `false` if dispensing will only cover a single visit. If not specified, defaults to `false`.

Example of patient_visits section (array of patient_visit object):

"patient_visits": [
        {
            "cohort": "",
            "visit_id": "screening",
            "other_data": {
                "weight": 52.5
            },
            "patient_id": "101-0003",
            "visit_date": "2020-10-15",
            "dispensings": [],
            "treatment_arm": "",
            "titration_level": "",
            "unscheduled_visit": false
        },
        {
            "cohort": "",
            "visit_id": "randomization",
            "other_data": {
                "weight": 52.5
            },
            "patient_id": "101-0003",
            "visit_date": "2020-10-22",
            "dispensings": [
               {
                  "kit_type": "kit_A",
                  "quantity": 2
               }
            ],
            "treatment_arm": "TGA / Active123",
            "titration_level": "",
            "unscheduled_visit": false
        },
        {
            "cohort": "",
            "visit_id": "uv_screen_fail",
            "other_data": {
                "weight": 75.0
            },
            "patient_id": "102-0004",
            "visit_date": "2020-11-01",
            "dispensings": [],
            "treatment_arm": "",
            "titration_level": "",
            "unscheduled_visit": true
        }]

Appendix:

JSON Schema

{
  "$schema": "4C Actuals 1.3.0",
  "$id": "4c_actuals",
  "title": "4C Data Import Schema",
  "definitions": {
    "ref_object": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "description": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "description"
      ]
    },
    "ref_visit": {
      "allOf": [
        {
          "$ref": "#/definitions/ref_object"
        },
        {
          "properties": {
            "is_optional": {
              "type": "boolean"
            }
          },
          "required": [
            "is_optional"
          ]
        }
      ]
    },
    "site": {
      "type": "object",
      "properties": {
        "site_code": {
          "type": "string"
        },
        "inventory_site_code": {
          "type": "string",
          "description": "Site code associated to the location for the inventory, which might be different than the site code used for patients. If not populated, it's assumed to be equal to the main site code"
        },
        "enrollment_group": {
          "type": "string"
        },
        "country": {
          "type": "string"
        },
        "enrollment_open": {
          "type": "boolean"
        },
        "activation_date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "string",
              "maxLength": 0
            }
          ]
        }
      },
      "required": [
        "site_code",
        "inventory_site_code",
        "enrollment_group",
        "country",
        "enrollment_open"
      ]
    },
    "lot": {
      "type": "object",
      "properties": {
        "lot_id": {
          "type": "string"
        },
        "expiry_date": {
          "type": "string",
          "format": "date"
        },
        "approved_countries": {
          "type": "array"
        }
      },
      "required": [
        "lot_id",
        "expiry_date",
        "approved_countries"
      ]
    },
    "inventory": {
      "type": "object",
      "properties": {
        "kit_type": {
          "type": "string"
        },
        "quantity": {
          "type": "integer"
        },
        "location": {
          "type": "string",
          "description": "The id of the inventory location (site or depot). Note that In-Transit inventory should be associated with the destination."
        },
        "kit_status": {
          "type": "string"
        },
        "lot": {
          "type": "string"
        }
      },
      "required": [
        "kit_type",
        "quantity",
        "location",
        "kit_status",
        "lot"
      ]
    },
    "shipment": {
      "type": "object",
      "properties": {
        "shipment_id": {
          "type": "string"
        },
        "origin": {
          "type": "string",
          "description": "The depot id of the shipment origin."
        },
        "destination": {
          "type": "string",
          "description": "The location id (depot or inventory_site_code) of the shipment destination."
        },
        "date_created": {
          "type": "string",
          "format": "date"
        }
      },
      "required": [
        "shipment_id",
        "origin",
        "destination",
        "date_created"
      ]
    },
    "patient": {
      "type": "object",
      "properties": {
        "patient_id": {
          "type": "string"
        },
        "site": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "date_registered": {
          "type": "string",
          "format": "date"
        },
        "date_enrolled": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "string",
              "maxLength": 0
            }
          ]
        },
        "cohort": {
          "type": [
            "string",
            "null"
          ]
        },
        "treatment_arm": {
          "type": "string"
        }
      },
      "required": [
        "patient_id",
        "site",
        "status",
        "date_registered",
        "treatment_arm"
      ]
    },
    "patient_dispensing": {
      "type": "object",
      "properties": {
        "kit_type": {
          "type": "string"
        },
        "quantity": {
          "type": "integer"
        }
        " multi_visit_dispensing": {
          "type": "boolean"
        }
      },
      "required": [
        "kit_type",
        "quantity"
      ]
    },
    "patient_visit": {
      "type": "object",
      "properties": {
        "patient_id": {
          "type": "string"
        },
        "visit_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "visit_date": {
          "type": "string",
          "format": "date"
        },
        "unscheduled_visit": {
          "type": "boolean"
        },
        "cohort": {
          "type": "string"
        },
        "treatment_arm": {
          "type": "string"
        },
        "titration_level": {
          "type": [
            "string",
            "null"
          ]
        },
        "other_data": {
          "type": "object"
        },
        "dispensings": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/patient_dispensing"
          }
        }
      },
      "required": [
        "patient_id",
        "visit_id",
        "visit_date",
        "unscheduled_visit",
        "treatment_arm",
        "cohort",
        "other_data",
        "dispensings"
      ]
    }
  },
  "type": "object",
  "properties": {
    "study_code": {
      "type": "string"
    },
    "desc": {
      "type": "string"
    },
    "extract_version": {
      "type": "string",
      "pattern": "^\\d\\.\\d\\.\\d(\\.[a-z])?$"
    },
    "extract_date": {
      "type": "string",
      "format": "date"
    },
    "data": {
      "type": "object",
      "properties": {
        "references": {
          "type": "object",
          "properties": {
            "site_enrollment_groups": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/ref_object"
              }
            },
            "countries": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/ref_object"
              }
            },
            "depots": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/ref_object"
              }
            },
            "patient_visits": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/ref_visit"
              }
            },
            "kit_types": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/ref_object"
              }
            },
            "treatment_arms": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/ref_object"
              }
            },
            "cohorts": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/ref_object"
              }
            },
            "titration_levels": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/ref_object"
              }
            },
            "patient_statuses": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/ref_object"
              }
            },
            "kit_statuses": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/ref_object"
              }
            }
          },
          "required": [
            "site_enrollment_groups",
            "countries",
            "depots",
            "patient_visits",
            "kit_types",
            "treatment_arms",
            "cohorts",
            "titration_levels",
            "patient_statuses",
            "kit_statuses"
          ]
        },
        "currently_enrolling_cohort": {
          "type": [
            "string",
            "null"
          ]
        },
        "sites": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/site"
          }
        },
        "lots": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/lot"
          }
        },
        "inventories": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/inventory"
          }
        },
        "shipments": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/shipment"
          }
        },
        "patients": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/patient"
          }
        },
        "patient_visits": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/patient_visit"
          }
        }
      },
      "required": [
        "references",
        "sites",
        "lots",
        "inventories",
        "shipments",
        "patients",
        "patient_visits"
      ]
    }
  },
  "required": [
    "study_code",
    "desc",
    "extract_date",
    "extract_version",
    "data"
  ]
}