РуководствоДата-менеджер

Импортировать дизайн из файла

Основной способ собрать дизайн — конструктор CRF. Но дизайн можно подготовить и вне системы — в одном файле по шаблону — и загрузить целиком: визиты, формы, поля, списки вариантов, проверки, деривации и переводы. Тот же файл служит для переноса дизайна между стендами или арендаторами и как резервная копия.

Кому и когда

Дата-менеджер — тот, кто собирает дизайн.

Создать исследование из файла — право «создавать исследования» (study.create).
Импортировать файл в черновик существующего исследования — право «править версию дизайна» (studyversion.update).
Скачать шаблон и схему формата — право читать дизайн (mdr.read).

Задача возникает в начале исследования, когда дизайн удобнее подготовить по протоколу в файле, и при переносе готового дизайна из другого контура.

Перед началом

Для нового исследования — свободный код исследования в вашем арендаторе.
Для импорта в существующее исследование — версия дизайна в статусе Черновик: опубликованный дизайн не меняется.
Под рукой протокол исследования: график визитов и перечень собираемых данных.

Шаги

Скачайте шаблон. На экране Дизайн откройте панель документов версии и в группе переноса и импорта скачайте Шаблон для подготовки дизайна (ZIP). Внутри:
- README.md — краткая инструкция;
- schema.json — описание формата файла (JSON Schema), по нему проверяется готовый файл;
- example.json — минимальный корректный пример: один визит, одна форма, список вариантов «Пол» и одна проверка;
- current.json — текущий дизайн версии, если он уже начат: удобно взять за основу.
Одну только схему можно скачать и кнопкой Скачать JSON Schema в диалогах импорта.
Заполните файл по образцу example.json — вручную или любым удобным инструментом. Визиты — study_events, формы — forms (поля сгруппированы в разделы item_groups), варианты ответов — codelists, проверки — edit_checks. Коды (oid) — латиница, цифры, «_» и «.»; названия (name_key) — обычным текстом. Проверка (expression) пишется на языке выражений ядра и описывает ситуацию, при которой нужно открыть запрос или не принять значение, например num(WEIGHT) > 200.
Загрузите файл. Откройте раздел Исследования, нажмите Новое исследование и выберите режим Из JSON. Перетащите файл в зону загрузки или вставьте JSON в поле Или вставьте JSON. Пакет разбирается сразу — превью показывает, сколько визитов, форм, полей, списков и проверок окажется в дизайне.
Проверьте без изменений. Нажмите Проверить. Сервер прогоняет файл через те же проверки, что и создание, но ничего не создаёт и не меняет — вы получаете список замечаний с серьёзностью каждой находки. Исправьте файл (Заменить файл) и проверьте снова, пока не увидите «Сервис не нашёл замечаний». Создание доступно только после успешной проверки.
Задайте код, название и фазу исследования — поля предзаполняются из метаданных пакета, но код должен быть свободен в вашем арендаторе.
Импортируйте. Нажмите Создать исследование.

Импортировать в черновик существующего исследования

На экране Дизайн у версии в статусе Черновик выберите импорт дизайна (в конструкторе — меню Ещё → Импорт JSON). Откроется диалог Импорт дизайна (JSON).
Вставьте JSON в поле JSON дизайна или выберите файл .json (Или выберите файл) — его содержимое подставится в поле.
Сверьте состав: диалог показывает счётчики визитов, форм, полей и списков. Если вы загрузили пакет целиком, диалог предупредит: метаданные исследования из файла не применяются — импортируется только дизайн.
Нажмите Импортировать. Появится сообщение «Дизайн импортирован: событий — M, форм — N».

Создать исследование из шаблона исследования

В том же диалоге Новое исследование есть режим Из шаблона: галерея готовых дизайнов. Выберите карточку, задайте код и название и нажмите Создать из шаблона — черновик версии v1.0 соберётся из выбранного дизайна. Подробнее — в разделе Шаблоны исследования ниже.

Что произойдёт

Новое исследование из файла: одной операцией создаются исследование в статусе Черновик и его первый черновик дизайна — версия v1.0, наполненная содержимым файла. В аудиторский след пишутся создание исследования, создание версии и импорт пакета со счётчиками.
Импорт в черновик: содержимое черновика заменено; в аудиторский след пишется замена декларации версии. Если в файле указана метка версии (version_label), черновик переименовывается.
Каждое скачивание пакета тоже фиксируется в аудиторском следе.
Импортированный дизайн не попадает в работу, минуя людей: дальше — доработка в конструкторе (порядок полей, расписание визитов, панель Проблемы), затем ревью и публикация.

Если не получилось

«Не удалось разобрать JSON — проверьте синтаксис» — файл не является корректным JSON. Исправьте синтаксис.
«В конверте нет декларации дизайна (definition)» — в пакете отсутствует часть definition. Возьмите за образец example.json или current.json из шаблона.
Проверка вернула замечания (например, ссылки на несуществующие списки) — исследование с заведомо битым дизайном не создаётся. Исправьте файл и повторите Проверить.
«Код уже занят» (STUDY_CODE_CONFLICT) — исследование с таким кодом уже есть в арендаторе. Задайте другой код; до этого ничего не создаётся.
Импорт в черновик отклонён: версия не изменяема (VERSION_NOT_MUTABLE) — версия уже на ревью или опубликована. Создайте новый черновик (поправку) и импортируйте в него.
Импорт в черновик вернул ошибку валидации (422) — декларация некорректна; транзакция откатывается, текущее содержимое черновика не теряется.
Нет режима «Из JSON» или кнопки импорта — у вас нет study.create или studyversion.update. Обратитесь к администратору.

Дальше

Создать исследованиеРучной путь: код, название, фаза и статусы.

Конструктор CRFДоработка импортированного дизайна: формы, списки, логика.

Опубликовать версиюРевью, публикация версии, активация центров, UAT и go-live.

Аудиторский следКаждый экспорт и импорт пакета оставляет запись.

Подробнее

Пакет исследования

Пакет исследования — JSON-файл формата x7.study-package.v1, в котором живёт весь дизайн версии: формы, разделы и поля, кодлисты, визиты и матрица SoA, правила проверки, вычисляемые поля (деривации) и переводы. Внутри пакета две части:

метаданные исследования — код, название, фаза;
definition — сам дизайн в том же формате декларации, который использует конструктор при импорте и экспорте JSON черновика.

Субъектов, их данные, центры и права пакет не содержит — это строго дизайн.

Экспорт пакета

Скачать пакет версии можно на экране Дизайн (панель документов версии, дизайн версии в формате JSON) и в конструкторе — меню «⋯» → Пакет исследования (JSON). Имя файла собирается из кода исследования и метки версии — файл study-X7-042-1.0.json узнаётся в переписке и в архиве без открытия. Полученный JSON можно положить в хранилище проекта как резервную копию дизайна, передать коллеге в другой контур или взять за основу нового дизайна.

Формат пакета: короткая справка

Поле	Что содержит
`format`	Версия формата пакета — строка `x7.study-package.v1`
`$schema`	Адрес публикуемой JSON Schema формата (`/api/v1/study-packages/schema`)
`exported_at`	Момент экспорта (ISO 8601)
`study`	Метаданные исследования: `code`, `title`, `phase`
`definition`	Весь дизайн версии: формы, поля, кодлисты, визиты, правила проверки, деривации, переводы — формат декларации конструктора

Файл без поля format трактуется как голая definition — дизайн напрямую, как в прежнем экспорте черновика. Поэтому старые файлы и фрагменты, собранные до появления пакета, продолжают импортироваться.

JSON Schema описывает, каким обязан быть корректный пакет: какие поля обязательны, какие типы допустимы и как выглядят выражения проверок (с примерами). Актуальную схему всегда можно скачать из продукта (Скачать JSON Schema) — она является источником истины о формате. Файл можно подготовить любым инструментом, включая внешних помощников: результат всё равно проходит серверную проверку, создаёт только черновик, а ревью и публикация остаются за людьми. Текущая версия формата — v1; при развитии формата версия в format сменится, а импорт старых пакетов останется возможным.

Шаблоны исследования

Если пакет — это «дизайн в файле», то шаблон исследования — «дизайн в библиотеке». В диалоге Новое исследование режим Из шаблона показывает галерею карточек; клик по карточке — и черновик версии v1.0 собирается из готового дизайна.

Системные заготовки поставляются вместе с платформой: «Базовое исследование (скрининг, виталы, НЯ)» и «Демо-исследование X7» — с них удобно начинать и на них удобно учиться.
Свои шаблоны собираются из ваших версий: на экране Дизайн нажмите Сохранить как шаблон — в библиотеку уедет дизайн версии (код исследования не сохраняется: у нового исследования будет свой). Библиотеку ведёт держатель права designtemplate.manage.
Создание из шаблона всегда спрашивает код нового исследования — само исследование целиком новое, со своим черновиком v1.0.

Не путайте с шаблонами форм в конструкторе: те вставляют готовую форму (с её кодлистами) в существующий дизайн, а шаблон исследования создаёт новое исследование целиком.

Документы ИРК: бланк, аннотированный ИРК и спецификация

Документы версии собирает сервер — на экране Дизайн они в панели документов версии (группа документов на согласование), в конструкторе — те же пункты в «⋯». Каждый документ — прогон журнала выгрузок: файл формируется на сервере воспроизводимо (PDF/A с контрольной суммой SHA-256 в журнале и аудиторском следе), а не окном печати браузера.

Бланк ИРК (PDF) — для центра и первичной документации: каждая форма как бланк для заполнения от руки — вопросы, поля нужного вида (клетки для чисел и дат, варианты ответа, строки для текста), единицы и условия «заполняется, если …» человеческими словами, без OID и служебных отметок; расписание визитов — таблицей на отдельной странице.
Аннотированный ИРК (PDF) (aCRF) — та же вёрстка бланка, но у каждого поля — аннотация в рамке: OID, тип и длина, обязательность, кодлист (OID и коды = расшифровки), единица, диапазон, условие видимости (выражение и словами), деривация и проверки. Именно так практики подачи (FDA/PhUSE) понимают «annotated CRF».
Спецификация (PDF) и Спецификация (Excel) — словарь данных версии: формы, поля, списки, проверки, деривации и визиты. Оба формата строятся из одной серверной модели.

Документы дизайна не содержат клинических данных: достаточно права читать дизайн исследования. Все они строятся из одной версии — правка дизайна меняет их разом, бумажный бланк не расходится с электронной формой.

Отчёт о развёртывании

Отчёт о развёртывании (на экране Дизайн — в панели документов версии, доступен после публикации; в конструкторе — пункт в «⋯») собирает ZIP, который отвечает аудитору на вопрос «что именно развёрнуто, где и в какой конфигурации»:

report.pdf — сам отчёт (PDF/A, собирается сервером): продукт, релиз и коммит, окружение и СУБД, методы входа; жизненный цикл версии — кто создал, отправил на ревью, утвердил и опубликовал, когда и с каким комментарием; центры и их активные версии; состав дизайна и его отпечаток (SHA-256 декларации); включённые модули; проектные настройки;
design/study-package.json — пакет версии (машинный шаблон ИРК, импортируется обратно);
design/specification.xlsx — спецификация ИРК;
settings/project-settings.json и system/system-config.json — настройки проекта и конфигурация системы;
manifest.json — контрольная сумма и размер каждого файла.

Конфигурация собирается по белому списку несекретных параметров: ключей шифрования, паролей и адресов почтового сервера в отчёте нет, клинических данных — тоже. Отчёт доступен тем, кто читает дизайн и аудиторский след исследования и может запускать выгрузки; каждая выдача записывается в журнал. Об устройстве серверных документов — Документы и заверенные копии.

Обмен с OpenClinica

Модуль «OpenClinica: импорт и экспорт» (панель в инспекторе конструктора) работает с шаблонами CRF OpenClinica 3.x (.xls) в обе стороны:

Импорт — переносит шаблоны в черновик версии: секции и группы, списки, скип-логику, валидации и калькуляции. Сначала показывает, что получится, затем импортирует одним действием; существенные потери (проверки, деривации) требуют явного подтверждения.
Экспорт — на экране Дизайн в панели документов версии пункт Шаблоны OpenClinica 3.x (.xls) (если модуль включён) скачивает ZIP: шаблон CRF на каждую форму версии и отчёт export-report.txt о том, чего формат OpenClinica выразить не может. Проверки ядра в OpenClinica задаются отдельным Rules XML, деривации и составные условия показа в шаблон CRF не входят — отчёт перечисляет каждую такую позицию.

Загрузка в OpenClinica: Tasks → CRFs → Create CRF и выбор файла .xls.