Перейти на сайт Case.one

Интеграция с Doc.one

Как включить интеграцию с Doc.one?

Интеграция с Doc.one позволяет:

  • Изменять документы в редакторе документов в режиме онлайн.
  • Использовать шаблоны, созданные в Doc.one, для формирования документов в Case.one.
  • Редактировать шаблоны документов перед созданием документа по шаблону.

Вы можете включить интеграцию с Doc.one в разделе Администрирование — Приложения.

Подключение интеграции с Doc.one выполняется в два этапа:

  1. Создание учетной записи приложения Case.one (клиента) в Doc.one и получение данных клиента для подключения.
  2. Включение интеграции с Doc.one в разделе Администрирование — Приложения в Case.one.

Для получения параметров Name (Идентификатор приложения), Secret (Защитный ключ):

  1. Создайте клиента (учетную запись Case.one в Doc.one) с помощью пользователя Doc.one с ролью Администратор.
  2. Выполните скрипты в PowerShell для создания клиента через вызов метода API регистрации нового клиента (в параметрах метода необходимо передать полный адрес API аутентификации подключаемого клиента Doc.one):
    • Для авторизации в Doc.one:
      Invoke-WebRequest https://адрес инстанса Doc.one/web/user/login -Method Post -SessionVariable Session -Headers @{'content-type'='application/json'} -Body '{"email":"email учетной записи","password":"пароль учетной записи"}'
    • Для создания клиента (учетной записи приложения Case.one):
      Invoke-WebRequest https://адрес инстанса Doc.one/oauth/clients -Method Post -Headers @{'Content-Type'='application/json'} -Body '{"name":"CasePro", "redirect":"https://адрес инстанса Case.one/api/DocOne/AuthFinish"}' -WebSession $Session | ConvertFrom-Json
    • Если вы хотите удалить клиента, выполните следующий скрипт в PowerShell:
      Invoke-WebRequest https://адрес инстанса Doc.one/oauth/clients/идентификатор клиента -Method Delete -WebSession $Session
  3. Откройте в браузере ссылку https://адрес инстанса Doc.one/oauth/clients для получения списка зарегистрированных клиентов (учетных записей приложения Case.one). Данные можно получить после выполнения скриптов PowerShell или при наличии уже зарегистрированных клиентов. Отобразится список с данными, которые используются для включения интеграции с Doc.one в Case.one.
  4. Скопируйте данные клиента, которые нужны для включения интеграции с Doc.one в разделе Администрирование — Приложения в Case.one:
    • URL инстанса Doc.one — скопируйте из адресной строки браузера
    • Name (Идентификатор приложения/клиента) — скопируйте без кавычек
    • Secret (Защитный ключ) — скопируйте без кавычек

Для включения интеграции в Case.one:

  1. Авторизуйтесь в Doc.one под учетной записью администратора.
  2. Авторизуйтесь в Case.one под учетной записью администратора.
  3. Выберите пункт Приложения в меню раздела Администрирование.
  4. Нажмите кнопку Подключить.
  5. В открывшемся окне заполните следующие данные:
    • URL Doc.one — адрес Doc.one (URL должен начинаться с http:// или https://)
    • Идентификатор приложения — параметр Name в списке зарегистрированных клиентов
    • Защитный ключ — параметр Secret в списке зарегистрированных клиентов
  6. Нажмите кнопку Сохранить. Выполнится проверка заполнения полей и попытка перейти в Doc.one для выполнения oAuth-авторизации:
    • Если URL Doc.one не соответствует маске (не начинается с http:// или https://), отобразится ошибка
    • Если пройдены проверки полей на стороне Case.one, данные будут отправлены в Doc.one, после чего выполнится авторизация уже на стороне Doc.one (подключение выполняется только от имени администратора аккаунта Doc.one)

При первом подключении интеграции отобразится окно авторизации — нажмите кнопку Authorize.

Отключение интеграции с Doc.one выполняется либо через приватный (внутренний) API, либо в настройках БД (необходимо отключить статус Только для чтения у приложения Doc.one).

Мы не рекомендуем самостоятельно отключать приложение — пожалуйста, обратитесь к команде Case.one.

При отключении интеграции:

  • Все шаблоны, которые были скачаны из Doc.one, будут удалены со всеми настройками доступности в типе дела/объекта.
  • Редактор документов будет недоступен.

Особенности подключения и самой интеграции:

  • Приложение перейдет в статус Подключено только после получения токена доступа от Doc.one. 
  • Подключение выполняется отдельно для каждого инстанса. 
  • Несколько инстансов Case.one могут быть подключены к одному аккаунту Doc.one.
  • После выполнения подключения Doc.one кнопка Отключить не активна.
  • После подключения все шаблоны из Doc.one будут переданы в Case.one (даже те, в которых нет ни одной переменной: например, вопрос, поле, блок). В дальнейшем — только в результате синхронизации по вебхукам.
  • Пустые шаблоны (например, без полей) загружаются только при первом подключении интеграции, но не загружаются при выполнении синхронизации.
  • Теги Case.one должны быть прописаны в настройке поля Внешний идентификатор в Doc.one, поскольку для корректной работы функции формирования документа по шаблону эти значения должны совпадать.
  • Редактор документа Doc.one (документы с расширением .docx) открывается в iframe в новой вкладке.
  • Если пользователь не зарегистрирован в Doc.one, он будет создан автоматически.

Работа с редактором документов

При работе с редактором документов предусмотрены следующие ограничения:

  • Если интеграция с Doc.one включена, теперь при попытке открыть документ в первый раз выполнится автоматическая (фоновая) проверка на расширение документа — если документ имеет расширение *.docx, Case.one отправит документ в Doc.one: 
    • Если документ успешно загружен в Doc.one:
      • Doc.one вернет в Case.one ссылку на этот документ
      • Case.one сохранит и документ, и ссылку на Doc.one
      • Case.one получит информацию по изменению документа в Doc.one
    • Если документ не получилось загрузить в Doc.one, Case.one сохранит документ без ссылки на Doc.one
  • Редактор документа Doc.one (документы с расширением *.docx) открывается в iframe в новой вкладке.
  • При скачивании документа в Case.one выполняется актуализация версии документа в Case.one по версии Doc.one:
    • При наличии более актуальной версии документа в Doc.one документ сначала будет актуализирован, а потом скачан
    • Если попытка актуализировать документ не удалась, будет скачана текущая версия документа в Case.one
  • При скачивании подписанного документа выполнится проверка актуальности версии документа в Case.one по версии Doc.one:
    • Если после подписания документ не был изменен, документ будет скачан вместе с файлом подписи
    • Если после подписания в документ вносились изменения:
      • Подпись будет удалена
      • Будет скачана актуальная версия документа (без подписи)
  • При подписании документа выполняется актуализация версии документа в Case.one по версии Doc.one. В результате в Case.one будут сохранены файл подписи и ссылка на документ в Doc.one.

Получение данных по шаблонам и документам в Case.one

Case.one получает данные по документам и шаблонам документов из Doc.one автоматически (с помощью вебхуков), если в Doc.one были выполнены следующие действия:

  • Изменение документа — при изменении документа, который есть в Case.one, документ будет скачан из Doc.one:
    • Данные приходят по всем документам в Doc.one (в том числе по документам, которые были созданы в Doc.one, но их нет в Case.one):
      • В истории записывается информация о редактировании документа
      • Автором изменения считается пользователь, который создал документ в Doc.one (отображается Внешний редактор)
    • Если пришло изменение по подписанному документу, это значит что на стороне Doc.one изменилась версия документа, а документ будет не подписан
  • Добавление нового шаблона документа в Doc.one — если в шаблоне не содержится ни одного тега, шаблон не будет загружен в Case.one. 
  • Переименование шаблона документа в Doc.one — у шаблона будет изменено название файла.
  • Публикация/снятие с публикации шаблона документа в Doc.one — изменяется статус шаблона документа:
    • Если в шаблоне не содержится ни одного тега, и он не создан в Case.one, шаблон добавлен не будет
    • Если в шаблоне не содержится ни одного тега, и он создан в Case.one, шаблон будет актуализирован
    • Если в шаблоне содержатся теги, и он создан в Case.one, шаблон будет актуализирован
    • Если в шаблоне содержатся теги, и он не был создан в Case.one, шаблон будет создан
  • Удаление шаблона документа — шаблон будет удален.

Синхронизация шаблонов документов с Doc.one по расписанию выключена по умолчанию.

Мы не рекомендуем включать синхронизацию по расписанию, поскольку возможно существенное увеличение количества запросов к Doc.one, что приведет к превышению лимита запросов и может сказаться на скорости генерации шаблонов и появлении задержек при работе.

Если вы хотите включить синхронизацию по расписанию для исправления возможных проблем, измените настройки в файле appsettings.json:

"Custom": {
...
    "DocOneSynchronizationJobEnable": "true",
    "DocOneSynchronizationPeriodCron": "0 * * * *",
...
}

Для разбора причин возможных багов или особенностей работы включите логирование в настройках файла nlog.config:

<rules>
    <!-- Логирование всех запросов и ответов к приложению doc.one -->
    <logger name="CaseMap.Modules.DocOne.Clients.DocOneClient" 
appendTo="full" final="true" minlevel="Debug"/>
    <!-- Логирование всех полученных вебхуков от doc.one -->
    <logger name="DocOneReceiveEvent" appendTo="full" 
final="true" minlevel="Info"/>
    <!-- Логирование процесса подписки на вебхуки doc.one -->
    <logger name="CaseMap.Modules.DocOne.Notify.SubscribeWebHooks" 
appendTo="full" final="true" minlevel="Info"/>
</rules>

Методы

Для просмотра API Doc.one перейдите по ссылкам:

  • https://АДРЕС ИНСТАНСА DOC.ONE/api/v3/documentation
  • https://АДРЕС ИНСТАНСА DOC.ONE/api/v2/documentation
  • https://АДРЕС ИНСТАНСА DOC.ONE/api/v1/documentation

Doc.one передает информацию о поддерживаемом формате шаблона с помощью атрибута DownloadFormats (docx, pdf или both — скачивание возможно и в *.docx, и в *.pdf):

  • При получении веб-хуков по Doc.one.
  • В методах API:
    • V1
      • GET /api/v1/templates/{id}
      • GET /api/v1/document
      • PUT /api/v1/documents
      • POST /api/v1/documents
    • V2
      • GET /api/v2/templates/{id}
      • GET /api/v2/document
      • PUT /api/v2/documents
      • POST /api/v2/documents
    • V3
      • POST /api/v3/templates/upload
      • GET /api/v3/document
      • PUT /api/v3/documents
      • POST /api/v3/documents
      • POST /api/v3/documents/copy
      • POST /api/v3/documents/edit
      • POST /api/v3/documents/upload

Если в параметре DownloadFormats передано значение both, при формировании документа по шаблону документ будет сформирован в формате *.docx.

Если документы в Case.one и Doc.one уже были синхронизированы, но после этого документ удалили в Case.one, по нему будет отправлен запрос в Doc.one об удалении с помощью метода DELETE /api/v3/documents (поиск документов выполняется за счет встроенного механизма удаления файлов без документов — если найден файл, по которому нет документа, но есть ссылка на Doc.one, по нему будет отправлен запрос) в следующих случаях:

  • Если в Case.one загрузили документ в формате *.docx, открыли документ, а затем удалили.
  • Если выполнено формирование документа по шаблону Doc.one:
    • Без открытия в редакторе, а форма добавления документа в Case.one была закрыта без сохранения
    • С включенной функцией открытия шаблона в редакторе, но редактор был закрыт без сохранения
    • С включенной функцией открытия шаблона в редакторе, информация в редакторе сохранена, а форма добавления документа в Case.one была закрыта без сохранения