Управление различными документами на сайте
Допустим, нам необходимо разместить на сайте и/или в мобильном приложении Пользовательское соглашение и Политику обработки персональных данных. Их содержимое определяется юристами, согласовывается с руководством, и попадает на сайт с помощью технических специалистов. Зачастую, работа над такими документами ведётся в ручном режиме: сами документы формируются в .doc или .odt файлах, хранятся на сетевом или облачном диске, пересылаются друг-другу по электронной почте, либо работа ведётся в онлайн редакторе. После согласования финальная версия передаётся технической команде, которая конвертирует документ в PDF, HTML или сохраняет контент в БД, для обработки бэк-эндом системы. Проблемы, которые возникают при подобном процессе:
- В случае работы с файлами на сервере или сетевом диске есть риск потери изменений в случае обновления файла другими сотрудниками.
- Отсутствие версионности. Для нумерации версий приходится создавать отдельные документы, что доставляет неудобства.
- Отсутствие системы согласования. Согласующие подключаются к процессу по запросу других сотрудников. Отследить, согласован ли документ, довольно сложно, как парвило, это происходит в переписке по почте или в мессенджере. Повышается риск опубликовать несогласованный документ.
- Трудно отслеживать, какая именно версия документа сейчас опубликована. Повышается риск не опубликовать согласованную для публикации версию.
- Обновлённые документы, как и любой новый функционал, необходимо тестировать с составе системы. Тестируют как содержание, так и отображение (на компьютере, на мобильном устройстве, во всплывающем окне). Для проверки документа его приходится отдельно выкладывать сначала на тестовом сервере, потом на пред-прод серевере и наконец на прод сервере.
- Невозможно быстро откатиться на предыдущую версию в случае необходимости. Приходится обращаться к техническим специалистам.
- Права на публикацию всегда находятся у технического специалиста, при этом реальное решение, как правило, принимает юрист или бизнес-руководитель. Т.е. требуется дополнительная синхронизация между сотрудниками.
Решением этих проблем является система, которая позволяет редактировать документы, вести контроль версий, согласовывать их, публиковать, обеспечивает выкладку на различные экземпляры системы (тест/прод), позволяет откатываться.
Рассмотрим, как организовать такой процесс с помощью системы Az Doc.
- Для начала необходимо зарегистрировать аккаунт организации на главной странице https://azdoc.online/
Теперь у нас есть аккаунт организации, в котором будут храниться необходимые документы. Пользователь данного аккаунта имеет роль admin. После создания аккаунта Вам на почту придёт письмо со ссылкой для подтверждения адреса e-mail, не забудьте перейти по ссылке, иначе, через 24 часа аккаунт будет заблокирован. - Добавим пользователей, которые будут иметь возможность редактировать, согласовывать и публиковать эти документы. Предположим, что мы добавляем следующих пользователей:
- Фёдор Плевако (юрист) - права уровня "Создание и редактирование документов"
- Софья Ковалевская (руководитель юридической службы) - права уровня "Создание и редактирование документов"
- Семён Дежнёв (инженер по тестированию) - права уровня "Чтение документов"
- Иван Павлов (руководитель проекта) - права уровня "Чтение документов"
- Дмитрий Менделеев (операционный директор) - права уровня "Чтение документов"
- В Настройках создадим стадии публикации. Предполагаем, что наша инфраструктура включает три среды: тестовую, пред-прод и прод.
- Название "Test", Порядок "1", Разрешить автоматическую публикацию "Да". В качестве согласующего укажем Софью Ковалевскую. Публикующих не указываем.
- Название "Pred-prod", Порядок "2", Разрешить автоматическую публикацию "Нет". В качестве согласующего укажем Семёна Дежнёва, в качестве публикующего - Ивана Павлова.
- Название "Prod", Порядок "3", Разрешить автоматическую публикацию "Да". В качестве согласующих укажем Софью Ковалевскую и Ивана Павлова, в качестве публикующего - Дмитрия Менделеева.
- В Az Doc все документы хранятся в папках, поэтому, прежде чем создать документы, нужно создать папку, назовём её, например, "Соглашения". Папки, так же как и документы, создаются в разделе Документы
- Создадим необходимые документы: "Пользовательское соглашение" и "Политика обработки персональных данных". При создании укажем тип документа HTML, т.к. предполагаем отображать его на сайте.
- Внесём какие-нибудь правки в документ и сохраним его, чтобы у нас была история версий для наглядности.
- Перейдём на страницу "Версии", в списке версий выберем ту, которую нужно опубликовать и нажмём кнопку "Отправить на публикацию". При этом должен смениться статус версии на Публикуется. И в списке стадий публикации стадия Test должна стать активной.
- Авторизуемся под Софьей Ковалевской (руководитель юридической службы), которая указана в качестве согласующего для стадии Test. Откроем документ, перейдём в список версий и согласуем публикацию нужной версии.
- Т.к. в настройках была указана автоматическая публикация, то сразу после согласования данная версия документа будет опубликована на стадии Test и доступна по ссылке https://azdoc.online/doc/{id}/content/stage/{stageName}
-
В конфигурационном файле вашего приложения необходимо настроить значение {stageName}, если вы планируете конструировать ссылки динамически, либо настроить полную ссылку на конкретный документ. Например:
https://azdoc.online/doc/cabeecb1-0e04-47f3-9eeb-cc84f44985dd/content/stage/Test - Теперь авторизуемся под Семёном Дежнёвым (инженером по тестированию), предполагаем, что он протестировал на тестовом сервере весь функционал, связанный с документом, и теперь документ может быть допущен к публикации на следдующем этапе, в нашем случае, на Pred-prod. Для Семёну нужно перейти в список версий, выбрать нужную версию, выбрать стадию и согласовать.
- Теперь авторизуемся под Семёном Дежнёвым (инженером по тестированию), предполагаем, что он протестировал на тестовом сервере весь функционал, связанный с документом, и теперь документ может быть допущен к публикации на следдующем этапе, в нашем случае, на Pred-prod. Для Семёну нужно перейти в список версий, выбрать нужную версию, выбрать стадию и согласовать.
- По окончании тестирования (и, возможно других работ на проекте), руководитель проекта Иван Павлов принимает решение, что ноавя версия продукта готова к релизу и запускает процесс выкладки на Pred-prod сервере. В т.ч. ему необходимо выложить документ. Для этого ему нужно авторизоваться в нашей системе, перейти в список версий, выбрать нужную версию, выбрать стадию и опубликовать. Теперь документ доступен на pred-prod сервере.
- На pred-prod сервере руководитель проекта Иван Павлов и руководитель юридической службы Софья Ковалевская, проверяют доукумент ещё раз, и согласовывают на публикацию на Prod.
- Предполагаем, что в нашей организации за публикацию юридически значимых документов на сайте организации отвечает операционный директор Дмитрий Менделеев. Получив все согласования (и не ранее), он может войти в систему и опубликовать нужную версию на Prod сервере.
Управление различными документами на сайте (АПИ)
Допустим, нам необходимо разместить на сайте и/или в приложении Оферту для пользователей. Зачастую проблема с подобными документами в том, что их содержимое определяется руководством компании или юристами, и не всегда оперативно и последовательно эти изменения попадают на сайт. Процесс ещё более осложняется, если эти изменения должны согласовываться внутри компании.
Всё взаимодействие с AZ doc осуществляется посредством АПИ. Ниже описан процесс взаимодействия.
- Создаём аккаунт нашей организации:
POST https://azdoc.online/api/register
Content-Type: application/json
{"username":"company@company.ru", "password":"abc123", "password2":"abc123"}
Ответ:
{ "status": "Sucess", "message": "Registered sucessfully." }
Теперь у нас есть аккаунт организации, в котором будут храниться необходимые документы. Пользователь данного аккаунта имеет роль admin. После создания аккаунта Вам на почту придёт письмо со ссылкой для подтверждения адреса e-mail, не забудьте перейти по ссылке, иначе, через 24 часа аккаунт будет заблокирован. - Авторизуемся:
POST https://azdoc.online/api/login
Content-Type: application/json
{"username":"company@company.ru", "password":"abc123"}
Ответ:
{ "access_token": "sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C", "expires_on": 1621318069333, "refresh_token": "pNtxHZ3lUvhwPkKqjw4RlkotPyhtiE4kdCMzBENf6YjnDfPlXk" }
В ответе мы получили access token и refresh token, которые будем использовать для аутентификации запросов. Время жизни access токена 30 минут, после этого его нужно обновлять. - Добавляем пользователей, которые будут редактировать документ (обратите внимание на заголовок Authorization, в котором указан access token, полученный ранее):
POST https://azdoc.online/api/user/add
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C
{"username":"manager@company.ru", "group":"author"}
Ответ:
{ "status": "Success", "message": "Created sucessfully.", "id": "ffe8df10-06cd-43b1-95da-739fa806a9d4" }
В ответе мы получили id нового пользователя. - Авторизованные пользователи с ролью admin или author могут добавлять и редактировать документы. Все документы хранятся в папках. Необходимо создать минимум одну корневую папку:
POST https://azdoc.online/api/folder/add
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C
{"name":"Все документы"}
Ответ:
{ "status": "Success", "message": "Created sucessfully.", "id": "f3386450-ed39-47fe-a0ea-05f876dc817b" }
В ответе мы получили id новой папки. - Добавим документ в эту папку:
POST https://azdoc.online/api/doc/addгде:
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C
{ "title": "Оферта", "status": 0, "type": "html", "body": "текст оферты в html формате", "folderId":"f3386450-ed39-47fe-a0ea-05f876dc817b" }
status - 0 или 1. 0 - черновик (значение по умолчанию), 1 - опубликованный документ;
type - тип документа, может быть любой;
body - тело документа в любом формате (plain text, json, markdown, html).
Ответ:
{ "status": "Success", "message": "Created sucessfully.", "id": "f7a817af-2b50-404e-a63f-771ee31be27a" }
В ответе мы получили id нового документа. - Пока документ находится в статусе 0 (черновик), он не будет доступен неавторизованным пользователям. Для изменения статуса используется АПИ doc/edit:
POST https://azdoc.online/api/user/edit
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C
{"id":"f7a817af-2b50-404e-a63f-771ee31be27a", "status": 1}
Ответ:
{ "status": "Sucess", "message": "Updated sucessfully." }
При обновлении документа старая версия будет сохранена в БД, и её всегда можно будет получить по АПИ (см. ниже). - Теперь этот документ доступен по ссылке, которую можно использовать на сайте:
GET https://azdoc.online/api/public/doc/{id} - АПИ doc/edit также используется для редактирвания документа:
POST https://azdoc.online/api/doc/edit
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C
{"id":"f7a817af-2b50-404e-a63f-771ee31be27a", "title": "Оферта для пользователей", "type": "html", "body": "текст №2 оферты в html формате"}
Ответ:
{ "status": "Sucess", "message": "Updated sucessfully." }
Т.к. поле "status" в вызове АПИ отсутствует, то по умолчанию оно равно "0", т.е. новая версия будет сохранена в статусе "черновик", и по публичной ссылке /api/public/doc/{id} будет доступна предыдущая, наиболее высокая версия со статусом "опубликовано". Чтобы новая версия стала доступна по публичной ссылке, необходимо изменить status на 1, как показано в примере выше, либо при редактировании документа сразу указывать "status":1. - Вы можете получить список версий документа и откатиться к старой версии. Для отката необходимо: получить список версий (doc/{id}/versions), получить контент нужной версии (doc/{id}/version/{number}), сохранить документ (doc/edit), заполнив нужные поля (как правило, title и body) значениями, взятыми из той версии, на которую откатываетесь. Подробное описание АПИ можно посмотреть в документации.
Хранение документов для корпоративной системы управления знаниями
Допустим, нам необходимо создать систему для накопления знаниями в компании. Привычным способом хранения документов является структура вложенных папок, при этом, желательно, чтобы можно было определять порядок следования (сортировку) подпапок и документов. Именно этот подход и реализует AZ doc.
Всё взаимодействие с AZ doc осуществляется посредством АПИ. Процесс взаимодействия по большей части идентичен процессу описанному выше в разделе "Управление различными документами на сайте". Сейчас мы рассмотрим работу со структурой папок и документов.
- Все документы хранятся в папках, т.е. в каждой учётной записи необходимо иметь как минимум одну корневую папку. Максимальное количество корневых папок не ограничено. Создадим корневую папку:
POST https://azdoc.online/api/folder/add
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C
{"name":"Отдел маркетинга"}
Ответ:
{ "status": "Success", "message": "Created sucessfully.", "id": "f3386450-ed39-47fe-a0ea-05f876dc817b" }
В ответе мы получили id новой папки. - При создании последующих корневых папок, при необходимости мы можем указывать порядок сортировки папок. Для этого при созднии используется параметр order:
POST https://azdoc.online/api/folder/add
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C
{"name":"Отдел ИТ", "order":"0"}
Ответ:
{ "status": "Success", "message": "Created sucessfully.", "id": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5" }
В ответе мы получили id новой папки. Поскольку order был указан равным 0, то система пересчитала порядок сортировки для остальных папок. - Попробуем получить список папок:
GET https://azdoc.online/api/folder/list
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C
Ответ:
[ { "id": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5", "name": "Отдел ИТ", "order": 0, "parentId": null }, { "id": "f3386450-ed39-47fe-a0ea-05f876dc817b", "name": "Отдел маркетинга", "order": 1, "parentId": null } ]
В ответе мы получили список папок. Обратите внимание на порядок папок в списке. - Создадим вложенные папки внутри раздела "Отдел ИТ":
POST https://azdoc.online/api/folder/add
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C
{"name":"Документация", "parentId": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5", "order":"0"}
И ещё одну:
POST https://azdoc.online/api/folder/add
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C
{"name":"Список сотрудников", "parentId": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5", "order":"1"}
Посмотрим на список папок теперь:
GET https://azdoc.online/api/folder/list
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C
Ответ:
[ { "id": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5", "name": "Отдел ИТ", "order": 0, "parentId": null, "children": [ { "id": "347b7fe2-0eab-40c5-b1c1-06f73fdeccad", "name": "Документация", "order": 0, "parentId": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5" }, { "id": "d8f614ac-b74c-4da9-9be3-a0facbd23a6f", "name": "Список сотрудников", "order": 1, "parentId": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5" } ] }, { "id": "f3386450-ed39-47fe-a0ea-05f876dc817b", "name": "Отдел маркетинга", "order": 1, "parentId": null } ]
Аналогично можно создавать вложенные папки внутри подпапок, количество уровней вложенности неограничено. Чтобы изменить порядок сортировки папок достаточно изменить order у одной папки, указав ей желаемую позицию, для остальных папок order будет пересчитал автоматически. - Добавим документ в корневую папку "Отдел ИТ" и ещё один в под-папку "Документация". Пример добавления в корневую папку:
POST https://azdoc.online/api/doc/add
Content-Type: application/json
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C
{"folderId":"df8f5f89-b93a-4b71-a5ee-2340ecc387e5", "title":"Описание структуры отдела", "status":0, "type": "Markdown", "body": "текст оферты в markdown формате", "order":0}
Ответ:
{ "status": "Success", "message": "Created sucessfully.", "id": "a9506e6f-b519-4768-a1c1-4ed01f5c3282" }
В ответе мы получили id нового документа. Документ в подпапке создаётся аналогично, нужно просто указать соответствующий id подпапки. - Посмотрим на список документов:
GET https://azdoc.online/api/doc/list
Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C
Ответ:
[ { "id": "a9506e6f-b519-4768-a1c1-4ed01f5c3282", "title": "Описание структуры отдела", "order": 1, "active": true, "FolderId": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5" }, { "id": "9ebd51b0-d05b-44d9-bbae-8d9c9333218b", "title": "Протокол интеграции", "order": 0, "active": true, "FolderId": "347b7fe2-0eab-40c5-b1c1-06f73fdeccad" } ]
Как было показано в пирмере выше, есть АПИ для получения документа по его id. Каждый документ может быть, как в статусе черновика, так и опубликован.