Версионирование контента
Версионирование контента — механизм, при котором каждая замена основного файла записи сохраняет предыдущее состояние файла в отдельную запись версии. Благодаря этому доступны просмотр и скачивание любой из предыдущих версий документа, а также сравнение версий между собой.
Пользовательский интерфейс механизма — виджет «Журнал версий» и функция сравнения версий.
Ниже описан механизм record-version для записей, хранящихся в БД через DbRecordsDao. Для Alfresco и источников с собственной реализацией версий правила хранения и работы с версиями могут отличаться.
Включение версионирования
Версионирование включается добавлением аспекта «Версионируемый» (versionable) к типу данных:
aspects:
- ref: emodel/aspect@versionable
Аспект не содержит атрибутов — он служит признаком того, что для записей типа нужно вести версии.
Аспект «Версионные данные»
Аспект «Версионные данные» (versionable-data, префикс version) определяет служебные данные текущей версии:
Атрибут |
Название |
Описание |
|---|---|---|
|
Версия |
Номер актуальной версии записи. Если не задан, считается равным |
|
Комментарий |
Комментарий к актуальной версии. |
|
Версии |
Дочерняя ассоциация на записи предыдущих версий. |
Что хранится в версии
Предыдущие версии сохраняются как отдельные записи системного типа record-version. Данные размещаются в таблице ecos_record_version в той же схеме БД, что и сама версионируемая запись.
Атрибут |
Тип |
Описание |
|---|---|---|
|
ASSOC |
Ссылка на версионируемую запись. |
|
CONTENT |
Файл версии. |
|
MLTEXT |
Имя файла на момент создания версии. |
|
TEXT |
Номер версии. |
|
TEXT |
Комментарий к версии. |
|
PERSON |
Автор версии. |
|
DATETIME |
Дата и время создания версии. |
Примечание
Запись версии ссылается на ту же запись контента, которая была у документа до замены файла, — физически файл при создании версии не копируется.
Важно
В версии сохраняются только файл и перечисленные выше метаданные. Значения остальных атрибутов записи в версию не попадают. Для отслеживания изменений атрибутов используется история событий (аспект history-config).
Когда создаётся версия
Обработчик версионирования сохраняет версию при получении события изменения контента, если одновременно выполняются условия:
среди аспектов записи есть «Версионируемый»;
до изменения у записи уже был сохранённый контент — иначе версия не создаётся (первая загрузка файла версию не порождает).
В версию сохраняется предыдущее состояние файла; актуальный файл всегда остаётся в самой записи. В журнале версий актуальная версия формируется на лету из текущего контента записи и в таблицу версий не пишется.
Примечание
Версионируется только основной атрибут контента типа (тот, что доступен через _content, см. конфигурацию контента). Файлы в дополнительных атрибутах с типом «Содержимое» не версионируются.
Нумерация версий
Если номер версии отсутствует или пуст, при сохранении предыдущей версии и отображении актуальной используется
1.0.REST-загрузка передаёт относительный инкремент:
+0.1для минорной версии,+1.0для мажорной.
Правила обработки абсолютных номеров и относительных инкрементов определяются используемой версией DB-слоя.
Работа с версиями через API
Загрузка новой версии (REST)
POST /gateway/emodel/api/content-version/upload
Параметр |
Описание |
|---|---|
|
Файл новой версии. |
|
Ссылка на версионируемую запись. |
|
Комментарий к версии (необязательный). |
|
|
Перед загрузкой проверяются право Write на запись, признак защиты контента от изменения, а также состояние блокировки документа: если документ редактируется в редакторе документов или заблокирован другим пользователем, загрузка отклоняется.
Загрузка новой версии через мутацию записи
REST-метод выше — обёртка над обычной мутацией записи, поэтому создать версию можно и напрямую через Records API:
recordsService.mutate(
recordRef,
mapOf(
"version:version" to "+0.1",
"version:comment" to "Комментарий к версии",
"_content" to tempFileRef
)
)
Перечисленные выше проверки Write, защиты контента и блокировки выполняются REST-контроллером. Прямая мутация не вызывает этот контроллер; применяемые к ней ограничения определяются источником записи и нижележащими сервисами.
Получение списка версий
Список версий запрашивается у источника version, который сам определяет, где хранятся версии конкретной записи:
{
"query": {
"sourceId": "version",
"query": { "record": "emodel/document@some-id" }
},
"attributes": {
"version": "version",
"modified": "modified",
"modifier": "modifier?disp",
"comment": "comment",
"name": "name",
"downloadUrl": "downloadUrl"
}
}
Источник version выбирает обработчик в следующем порядке:
для Alfresco-ссылок —
alfresco/version;при наличии специализированного источника —
<app>/<source>-version;для остальных записей приложения
emodel—emodel/record-version.
Если подходящий обработчик не найден, источник не возвращает результат.
В DB-механизме сохранённые версии сортируются по versionCreated от новых к старым. При наличии текущего контента первой в списке добавляется актуальная версия записи.
Локальный идентификатор сохранённой версии имеет вид <sourceId>__<id записи версии>, актуальной — <sourceId>__current__<id документа>. В последующих запросах используйте полную ссылку из результата, включая этот составной идентификатор.
Скачать файл конкретной версии можно по ссылке из атрибута downloadUrl:
/gateway/emodel/api/ecos/webapp/content?ref=record-version%40<полный localId версии>&att=content&download=true
Создание записи версии напрямую
Записи версий можно создавать напрямую в источнике record-version, в том числе при миграции данных из внешних систем, когда нужно явно задать исходных авторов и даты версий:
recordsService.create(
"record-version",
mapOf(
"_parent" to recordRef,
"_parentAtt" to "version:versions",
"version" to "1.0",
"comment" to "Перенесено из внешней системы",
"versionCreator" to EntityRef.create("emodel", "person", "ivanov"),
"versionCreated" to Instant.parse("2019-05-14T10:15:30Z"),
"_content" to tempFileRef
)
)
Предупреждение
Источник record-version допускает только создание и удаление записей версий. Мутация уже существующей записи версии игнорируется.
Синтетическую актуальную версию удалить через этот источник нельзя.
Сравнение версий
Сравнение выполняется источником version-diff:
{
"query": {
"sourceId": "version-diff",
"query": {
"first": "record-version@<id первой версии>",
"second": "record-version@<id второй версии>"
}
},
"attributes": { "diff": "diff" }
}
В примере <id первой версии> и <id второй версии> обозначают полные составные локальные идентификаторы, полученные при запросе списка версий.
В атрибуте diff возвращается HTML-разметка с классами INSERT, DELETE и EQUAL. Обычно фрагменты оборачиваются в span; для формата bpmn используется code с отдельным экранированием текста.
Обе сравниваемые версии должны принадлежать одному приложению и источнику. Для записей вне Alfresco также проверяется совпадение атрибута format. Сравнение Alfresco-версий делегируется в alfresco/version-diff.
Как работает сравнение
Для сохранённой и актуальной DB-версий атрибут data формируется из _content.convertedTo.text и передаётся обработчику сравнения в UTF-8. Затем выполняется посимвольное сравнение текстов с семантической очисткой результата.
Поддерживаемые форматы
Возможность сравнения зависит от доступности преобразования контента в текст через convertedTo.text. Обработчик сравнения не задаёт фиксированный список расширений; поддержка конкретного формата определяется доступными преобразованиями.
Примечание
Сравнивается только извлечённый текст. Оформление, расположение таблиц и изображения отдельно не сравниваются. Для файлов без извлекаемого текста потребуется подходящее преобразование, например распознавание текста для сканов.
Хранение файлов версий
При автоматическом создании версии используется существующий идентификатор предыдущего контента. Поэтому создание версии само по себе не переносит файл в другое хранилище и не создаёт физическую копию.
Настройки контента описаны в конфигурации типа, смене типа хранилища и разделе Content микросервис. Удаление записи версии передаётся DB-слою; момент физического удаления файла определяется механизмом хранения и очистки контента.
Права доступа
Тип record-version использует политику прав PARENT — права на версию наследуются от версионируемой записи. Список версий возвращается только при наличии права Read на саму запись; сам запрос к хранилищу версий после проверки прав выполняется в системном контексте.
Для типа record-version отключено ведение истории событий (аспект history-config, параметр disableHistory), чтобы создание версий не засоряло историю изменений документа.
Ограничения
Версионируется только основной атрибут контента типа; дополнительные атрибуты с типом «Содержимое» не версионируются.
Значения атрибутов записи в версии не сохраняются — версионируется только файл.
Сравнение версий доступно только для форматов, из которых можно извлечь текст, и является текстовым.
Изменение уже созданной записи версии через API не выполняется.
В API
record-versionнет отдельной операции назначения предыдущей версии актуальной. Вернуться к предыдущему содержимому можно, скачав нужный файл и загрузив его как новую версию.При автоматическом создании версии автор и дата берутся из метаданных предыдущего контента. При отсутствии значений используются SYSTEM и
Instant.EPOCHсоответственно. При прямом создании записи версии можно явно задатьversionCreatorиversionCreated.