How-toData manager

Import a study design from a file

The main way to build a design is the CRF builder. But a design can also be prepared outside the system — in a single file, from a template — and loaded as a whole: visits, forms, fields, answer lists, checks, derivations and translations. The same file moves a design between environments or tenants and serves as a backup.

Who and when

Data manager — whoever builds the design.

Creating a study from a file requires the “create studies” permission (study.create).
Importing a file into an existing study’s draft requires “edit a design version” (studyversion.update).
Downloading the template and the format schema requires the right to read the design (mdr.read).

The task comes up at the start of a study, when it is easier to prepare the design from the protocol in a file, and when moving a finished design from another environment.

Before you start

For a new study — a study code that is free in your tenant.
For an existing study — a design version in Draft status: a published design never changes.
The study protocol at hand: the visit schedule and the data to collect.

Steps

Download the template. On the Design screen, open the version’s document panel and, in the transfer and import group, download the Design preparation template (ZIP). It contains:
- README.md — short instructions;
- schema.json — the file format (JSON Schema); validate your file against it;
- example.json — a minimal valid example: one visit, one form, a “Sex” answer list and one check;
- current.json — the version’s current design, if already started: a good base.
The schema alone is also available via Download JSON Schema in the import dialogs.
Fill in the file following example.json — by hand or with any tool you prefer. Visits are study_events, forms are forms (fields grouped into sections item_groups), answer options are codelists, checks are edit_checks. Codes (oid) use Latin letters, digits, “_” and “.”; names (name_key) are plain text. A check (expression) is written in the core expression language and describes when to raise a query or reject a value, e.g. num(WEIGHT) > 200.
Upload the file. Open Studies, click New study and choose the From JSON mode. Drop the file into the upload area or paste the JSON into Or paste JSON. The package is parsed immediately — the preview shows how many visits, forms, fields, lists and checks the design will have.
Validate without changes. Click Validate. The server runs the file through the same checks as creation but creates and changes nothing — you get a list of findings with the severity of each. Fix the file (Replace file) and validate again until you see “The service found no issues”. Creation is available only after a successful validation.
Set the code, title and phase of the study — the fields are prefilled from the package metadata, but the code must be free in your tenant.
Import. Click Create study.

Import into an existing study’s draft

On the Design screen, for a version in Draft status, choose design import (in the builder — the More menu → Import JSON). The Import design (JSON) dialog opens.
Paste the JSON into Design JSON or pick a .json file (Or pick a file) — its content is put into the field.
Check the contents: the dialog shows counts of visits, forms, fields and lists. If you loaded a whole package, the dialog warns that study metadata from the file is not applied — only the design is imported.
Click Import. A message appears: “Design imported: M events, N forms”.

Create a study from a study template

The same New study dialog has a From template mode: a gallery of ready-made designs. Pick a card, set the code and title and click Create from template — the v1.0 version draft is assembled from the chosen design. See Study templates below.

What happens

New study from a file: a single operation creates the study in Draft status and its first design draft — version v1.0, filled with the file’s content. The audit trail records the study creation, the version creation and the package import with counts.
Import into a draft: the draft’s content is replaced; the audit trail records the replacement of the version definition. If the file specifies a version label (version_label), the draft is renamed.
Every package download is also recorded in the audit trail.
An imported design never goes live bypassing people: next comes refinement in the builder (field order, visit schedule, the Problems panel), then review and publication.

If it doesn’t work

“Could not parse the JSON — check the syntax” — the file is not valid JSON. Fix the syntax.
“The envelope has no design definition (definition)” — the package lacks the definition part. Use example.json or current.json from the template as a model.
Validation returned findings (e.g. references to non-existent lists) — a study with a known broken design is not created. Fix the file and click Validate again.
“This code is already taken” (STUDY_CODE_CONFLICT) — the tenant already has a study with this code. Choose another code; nothing is created until then.
Import into a draft rejected: version not mutable (VERSION_NOT_MUTABLE) — the version is already in review or published. Create a new draft (an amendment) and import into it.
Import into a draft returned a validation error (422) — the definition is invalid; the transaction is rolled back and the draft’s current content is not lost.
No “From JSON” mode or import button — you lack study.create or studyversion.update. Ask your administrator.

Create a studyThe manual path: code, title, phase and statuses.

CRF builderRefining an imported design: forms, lists, logic.

Publish a versionReview, version publication, site activation, UAT and go-live.

Audit trailEvery package export and import leaves a record.

More details

The study package

A study package is a JSON file in the x7.study-package.v1 format holding the entire design of a version: forms, sections and fields, code lists, visits and the SoA matrix, edit checks, computed fields (derivations) and translations. The package has two parts:

study metadata — code, title, phase;
definition — the design itself, in the same declaration format the builder uses to import and export a draft’s JSON.

The package contains no subjects, their data, sites or permissions — it is strictly the design.

Exporting a package

Download a version’s package on the Design screen (the version’s document panel, the version design as JSON) or in the builder — the ⋯ menu → Study package (JSON). The file name is built from the study code and version label — a file like study-X7-042-1.0.json is recognisable in email and archives without opening it. Keep the JSON in the project storage as a design backup, hand it to a colleague in another environment, or use it as the base for a new design.

Package format: a quick reference

Field	Contents
`format`	Package format version — the string `x7.study-package.v1`
`$schema`	URL of the published format JSON Schema (`/api/v1/study-packages/schema`)
`exported_at`	Export moment (ISO 8601)
`study`	Study metadata: `code`, `title`, `phase`
`definition`	The whole version design: forms, fields, code lists, visits, edit checks, derivations, translations — the builder format

A file without the format field is treated as a bare definition — the design directly, as in the earlier draft export. So older files and fragments assembled before the package existed keep importing.

The JSON Schema describes what a valid package must look like: which fields are required, which types are allowed and what check expressions look like (with examples). The current schema can always be downloaded from the product (Download JSON Schema) — it is the source of truth for the format. The file can be prepared with any tool, external assistants included: the result still passes server-side validation, creates only a draft, and review and publication stay with people. The current format version is v1; as the format evolves, the version in format will change, while older packages will remain importable.

Study templates

If a package is a “design in a file”, a study template is a “design in a library”. In the New study dialog the From template mode shows a gallery of cards; a click on a card — and the v1.0 version draft is assembled from a ready-made design.

System templates ship with the platform: “Basic study (screening, vitals, AE)” and “X7 demo study” — convenient starting points and a good way to learn.
Your own templates are collected from your versions: on the Design screen click Save as template — the version design goes to the library (the study code is not saved: the new study will have its own). The library is managed by holders of designtemplate.manage.
Creating from a template always asks for the code of the new study — the study itself is entirely new, with its own v1.0 draft.

Do not confuse these with form templates in the builder: those insert a ready-made form (with its code lists) into an existing design, while a study template creates a whole new study.

eCRF documents: blank, annotated CRF and specification

Version documents are built server-side — on the Design screen they are in the version’s document panel (the group of documents for approval); the builder offers the same items in ⋯. Every document is a run of the export journal: the file is produced reproducibly on the server (PDF/A with a SHA-256 checksum in the journal and audit trail), not by the browser print dialog.

CRF blank (PDF) — for the site and source documentation: each form as a blank to fill in by hand — questions, entry areas of the right kind (boxes for numbers and dates, answer options, lines for text), units and “complete if …” conditions in plain words, without OIDs or technical marks; the schedule of activities as a table on its own page.
Annotated CRF (PDF) (aCRF) — the same blank layout, but every field carries a boxed annotation: OID, type and length, requiredness, code list (OID and code = decode pairs), unit, range, visibility condition (the expression and in words), derivation and edit checks. This is what submission practices (FDA/PhUSE) mean by “annotated CRF”.
Specification (PDF) and Specification (Excel) — the version data dictionary: forms, fields, code lists, checks, derivations and visits. Both formats come from one server-side model.

Design documents carry no clinical data: the right to read the study design is enough. They are all built from the same version — a design change updates them at once, and the paper form never drifts from the electronic one.

Deployment report

The Deployment report (on the Design screen — in the version’s document panel, available after publication; in the builder — an item in ⋯) builds a ZIP that answers an auditor’s question “what exactly is deployed, where and in which configuration”:

report.pdf — the report itself (PDF/A, built server-side): product, release and commit, environment and database, sign-in methods; the version lifecycle — who created, submitted, approved and published it, when and with what comment; sites and their active versions; design contents and fingerprint (SHA-256 of the definition); enabled modules; project settings;
design/study-package.json — the version package (the machine CRF template, re-importable);
design/specification.xlsx — the CRF specification;
settings/project-settings.json and system/system-config.json — project settings and system configuration;
manifest.json — the checksum and size of every file.

The configuration is collected from an allow-list of non-secret parameters: there are no encryption keys, passwords or mail server addresses in the report, and no clinical data either. The report is available to those who read the study design and audit trail and can run exports; every issuance is recorded in the journal. How server-built documents work — Documents and certified copies.

Exchange with OpenClinica

The OpenClinica: import and export module (a panel in the builder inspector) works with OpenClinica 3.x CRF templates (.xls) both ways:

Import — brings templates into a draft version: sections and groups, code lists, skip logic, validations and calculations. It previews the result first, then imports in one action; substantial losses (checks, derivations) require explicit confirmation.
Export — on the Design screen, the OpenClinica 3.x templates (.xls) item in the version’s document panel (when the module is enabled) downloads a ZIP: a CRF template per form of the version and an export-report.txt listing what the OpenClinica format cannot express. Core checks are a separate Rules XML in OpenClinica, and derivations and compound display conditions are not part of a CRF template — the report lists every such item.

Upload into OpenClinica: Tasks → CRFs → Create CRF and choose the .xls file.