Какой должна быть лента событий

[GilimkhanovDenis]

Метод
Organization.GetDocumentEventList([AfterEventId])

имеет ряд неудобств:

• Метод работает крайне медленно
• Невозможно получить шаблоны
• Один и тот же EventType может быть у разных событий, произошедших с документом
• DocumentEvent'ы сложно сопоставлять с Resolution'ами, полученными методом DocumentBase.GetResolutions

Пожелания и предложения по тому, как должна выглядеть лента событий, приветствуются.

[GilimkhanovDenis]

#706 (comment)

Метод Organization.GetDocumentEventList([AfterEventId]) и формируемая на его основе лента событий

Проблема №1. Описание

Особенностью метода GetDocumentEventList является то, что в качестве параметра для него надо либо ничего не передавать, либо можно передать «Идентификатор события, после которого будет вычитываться лента событий». В случае, если параметр не задан, то будет происходит вычитка событий «с самого начала времен» для данной организации.

При этом идентификаторы событий сами по себе никак ни к какому времени возникновения событий не привязаны (ну, по крайней мере, так, чтобы это из самого идентификатора было понятно). Это просто некие ID. Например, 95dd0c83-8ee3-4ea1-823e-8f2974f2162b. Если передать его как параметр в функцию, то в возвращаемых результатах будут ID событий с временной привязкой в поле Timestamp – но это будет ПОСЛЕ получения данных, а не ДО этого. А по самому ID никак нельзя понять к какому времени он относится.

Это приводит к тому, что, если не сохранять куда-то в своей системе всю ленту получаемых событий или не фиксировать, в какой-то таблице по каким ID в какой момент времени мы получали события документооборота, то никаким образом нельзя будет потом связать имеющиеся ID со временем происходящих событий.

Т.е. будет невозможно выполнить действие типа – «Получить порцию событий начиная с сегодняшнего утра 00:00:00». А если мы просто храним последний ID, по которому получали события, и в системе произошел какой-то сбой, в результате которого мы этот ID потеряли, то начать получать события по схеме «давай всё заново с сегодняшнего утра получим» или что-то в таком же духе – невозможно.

И мы оказываемся в ситуации, когда ID из-за сбоя нет. По отметке времени возможности получения событий тоже нет… И единственным вариантом остается начать получать события «с самого начала времен», вызывая в первый раз функцию без параметров и начиная, по сути, пролистывать всю ленту событий с самого начала.

Если у вас много документов в документообороте, то это превращается… ну, скажем так, в весьма «забавное» мероприятие! Особенно с учетом того, что «вот прямо сейчас» надо бы получать текущие события документооборота. Поток документов-то не прекращается. А ты не можешь, т.к. у тебя ID для этого нет. И тебе надо сперва перечитать, например, несколько миллионов событий за последние 5 лет! Только для того, чтобы добраться до ID текущих событий. Тех, которые вот прямо сейчас происходят.

Плюс еще и сама операция GetDocumentEventList весьма небыстрая. Мне даже страшно представить, сколько времени у нас, например, с нашими 80-100 тысяч документов в месяц, может занять перечитывание всей ленты событий с начала времен, чтобы догнать наконец самые последние в истории. Не удивлюсь, если счет будет идти на недели!

Также, без хранения в своей системе обработанных ID c их привязкой ко времени невозможно выполнить какой-то откат обработки событий документооборота и сделать что-то типа «а давайте заново перечитаем все события начиная со вчерашнего утра».

Поэтому сохранять в своей учетной системе историю ленты событий с привязкой ID событий ко времени на текущий момент приходится в обязательном порядке!

Конкретно мы по этой причине ведем в 1С специальный регистр в котором храним историю ID событий с привязкой ко времени вызова GetDocumentEventList по этим ID. Именно для того, чтобы в случае каких-то сбоев можно было бы начать получать события документооборота не с самого их начала, а с более-менее недавнего времени. А также для потенциальной возможности перечитывания событий документооборота с какого-то определенного момента.

Проблема №1. Предложения по доработке

Нам представляется, что хорошим дополнением функционала работы с событиями было бы добавление каких-то методов из предлагаемого списка (или всех их, например). Названия условные (не в них дело):

1. GetDocumentEventLisByTime Версия получения событий, в которую в качестве параметра передается не ID события, с которого надо начать, а момент времени, с которого надо брать события. Т.е. она должна вернуть порцию событий начиная с тех, у кого Timestamp >= указанного в параметре момента времени. Время по идее указывается с точностью до секунд.

2. GetDocumentEventIdByTime Более «костыльный» вариант, но тоже вполне подходящий. Эта функция принимает на вход момент времени и в ответ возвращает первый подходящий самый ранний ID события у которого Timestamp >= указанного в параметре момента времени. Время по идее указывается с точностью до секунд.

С её помощью при проблемах с ID можно будет получить ID на нужный момент времени, а далее уже воспользоваться для работы с событиями стандартной имеющейся функцией GetDocumentEventList.

3. GetLastEventID Результатом её вызова должен быть последний существующий ID события документооборота из имеющихся на момент вызова (в рамках подключённой организации). Такая функция была бы весьма полезна для целей отладки и для обеспечения возможности быстрого перехода к последним событиям в ленте событий.

Важным вопросом для функций №1 и №2 является то, как понять, что это за время, к какому часовому поясу оно относится? И это, кстати, связано с проблемой №2.

[GilimkhanovDenis]

#706 (comment)

Проблема №2. Описание

Когда GetDocumentEventList возвращает данные, то, согласно документации, в поле Timestamp возвращается «дата и время события в текущем часовом поясе».

Самый главный вопрос – «текущий» – это вообще какой?!

Пример (кстати, вполне реальный!), я сижу во Владивостоке и вызываю этот метод. Из 1С на управляемых формах. Сервер, на котором это все в реальности выполняется расположен в Москве. При этом на этом сервере у нас обслуживаются разные базы 1С, и я выполняю это действие в базе, относящейся к городу Новосибирск. А весь функционал Контур.Диадок выполняется вообще непонятно, где (в смысле – мы не знаем где) – то ли в Москве, то ли в Екатеринбурге…

Вот какой часовой пояс в данном случае является «текущим» и, главное, как из даты и времени, например, «29.10.2021 18:09:20» это можно понять впоследствии?

Проблема №2. Предложения по доработке

Для снятия возможных неоднозначностей и разночтений, предлагаем явно вынести смещение по часовому поясу в данные, возвращаемые GetDocumentEventList. Для этого нужно вместо одного поля Timestamp возвращать два поля – Timestamp и GMT. И указывать то же самое текущее время события, как и сейчас, но дополнительно явным образом отмечать смещение по часовому поясу, ну, например, относительно Москвы.

Т.е., если выполнить GetDocumentEventList в Москве, то будет такой результат: Timestamp = «29.10.2021 10:00:00», GMT = 0.

А если это же и тогда же выполнить во Владивостоке, то был бы такой результат: Timestamp = «29.10.2021 17:00:00», GMT = 7.

[GilimkhanovDenis]

#706 (comment)

Проблема №3. Описание

Пожалуй, самым неоднозначным моментом в работе GetDocumentEventList является возвращаемый тип события (EventType).

С одной стороны типов событий вроде как довольно-таки много. А с другой стороны:

1. В документации они никак толком не привязаны к реальным действиям, происходящим над документами. Например, из документации невозможно понять возникает ли какое-то событие при получении запроса на аннулирование или отказе при получении такого запроса. А если и возникает, то>

Проблема №3. Описание

Пожалуй, самым неоднозначным моментом в работе GetDocumentEventList является возвращаемый тип события (EventType).

С одной стороны типов событий вроде как довольно-таки много. А с другой стороны:
какое именно. Или, например, каким событием отражается момент восстановления удаленного документа из папки «Удаленные»? А каким перемещение документа в другое подразделение? Т.е. скорее всего каким-то событием подобные моменты отражаются. Но из документации этого не понять.
2. Из-за п.1 мы самостоятельно проводили исследование и пришли к выводу, что не во всех возможных моментах изменения состояния документа по типу события возможно однозна>

Проблема №3. Описание

Пожалуй, самым неоднозначным моментом в работе GetDocumentEventList является возвращаемый тип события (EventType).

С одной стороны типов событий вроде как довольно-таки много. А с другой стороны:
чно понять, что же именно с ним произошло. Т.е., некое событие в ленте событий отражается, но из него нельзя определить, что же именно с документом произошло.
3. Вообще не хватает информации в плане описания сути уже отраженных в документации типов событий. В каких случаях они возникают и что означают? Например, что именно означает появление события MetaModify? О чем оно говорит, когда и для каких документов появляется – совершенно непонятно.

Из-за всего этого в комплексе, мы на текущий момент из данных ленты событий документооборота не можем однозначно понять, что же именно с документом произошло. И поэтому вынуждены работать по довольно-таки странному принципу – как только по какому-то документу в ленте событий документооборота появляется любое событие (т.е. «хоть что-то происходит»), то мы понимаем только, что «с документом в ЭДО что-то произошло». Но толком понять – что же именно произошло – не можем. Поэтому мы этот документ заново получаем из ЭДО и уже по текущему состоянию статусов документа определяем, что же именно поменялось, и в каком теперь состоянии находится документ.

Конечно, так тоже работать можно… но, если бы у нас было однозначное понимание по данным событий, что же именно произошло с документом, то можно было бы организовать обработку изменений состояния документов гораздо удобнее и экономичнее. В том числе и по ресурсам Диадока – мы бы (да, наверное, и не только мы) просто реже бы обращались в Диадок за получением документов целиком только для определения, что же с документом случилось и изменилось, т.к. нам было бы достаточно информации только из ленты событий без необходимости обращения за самим документом (из этого, кстати, вытекает дополнение А (см. далее)).

Проблема №3. Предложения по доработке

С нашей точки зрения данный метод требует как доработки в плане отражаемых в ленте событий, так и доработки в плане документирования самого метода.

Т.е. по минимуму нужно хотя бы доработать документацию. Явно указав:

1. Для каких документов
2. В случае каких действий с ними
3. Какое событие возникает

А по максимуму – обновить возможные варианты EventType, напрямую отразив в них все возможные действия над документами.

Для обеих вариантов минимальным набором действий, которые надо либо описать в документации, либо отразить в EventType (а лучше и то, и другое) с нашей точки зрения является:

1. Создание нового документа
2. Подписание извещения о получении СФ/УПД/УКД
3. Подписание документа
4. Отказ от подписания документа
5. Удаление документа в папку «Удаленные»
6. Восстановление документа из папки «Удаленные»
7. Отправка запроса на аннулирование
8. Получение предложения об аннулировании
9. Аннулирование документа
10. Отказ от аннулирования документа
11. Отправка запроса на уточнение документа
12. Получение запроса на уточнение документа
13. Отправка уточнения по документу
14. Получение уточнения по документу
15. Изменение состава документов в пакете данного документа
16. Изменение в составе дочерних документов данного документа
17. Изменение в составе родительских документов данного документа
18. Документ переместили из одного подразделения в другое
19. По документу обновились статусы внешних систем (Честный Знак и т.п.)
20. • Все действия с согласованием документа, маршрутизацией и т.п.

Скорее всего список не полон. И вы со своей стороны еще что-то в него сможете добавить.

Если реализация нового набора событий сложна или невозможна (а это, по идее, весьма вероятно), то огромная просьба – хотя бы документацию по текущим событиям доработать. Т.е. в привязке к событиям из вышеуказанного списка отметить – возникнет ли при этом событие в ленте событий и, если возникнет, то какое именно.

[GilimkhanovDenis]

#706 (comment)

Дополнение А

Очень часто вследствие того, что с документом что-то произошло (и это, наверное, отразилось в ленте событий документооборота) требуется узнать, какие теперь у документа статусы. Чтобы:

1. Обновить/синхронизировать их в своей учетной системе
2. Возможно, как-то прореагировать на их изменение
3. На основании текущих статусов точно понимать в каком состоянии на текущий момент находится документ

Однако, сейчас не существует возможности узнать статусы документа без получения всего документа целиком!

Узнать, какими стали статусы документа после того или иного действия с ним нужно практически всегда. При этом приходится получать его целиком. А это явно влечет за собой лишнюю нагрузку и на учетные системы пользователей и на сам Диадок. Ведь гораздо быстрее и дешевле получить и отдать пользователю небольшой список статусов документа, чем вернуть, например, целиком УПД на 1000 строк, да еще с данными на 5000 кодов маркировки в нем!

Представляется, что было бы крайне удобным и полезным добавление функции типа: GetDocumentStatusByID(<id lдокумента>), которая возвращала бы не весь документ целиком, а только сводное состояние его статусов. Включая статусы документа, подписантов, аннулирования, роуминга и т.д.

При наличии такой функции во многих случаях пользователям вместо обращения в Диадок за получением полной версии документа было бы достаточно получать только статусы документа для отражения их изменений в своей учетной системе. Это снизило бы и нагрузку на системы пользователей, и на Диадок. Т.е. в выигрыше были бы все.

Дополнительно: Огромная просьба как-то доработать документацию по новым статусам документов, отображаемым в DocflowStatus:

Очень хотелось бы увидеть хоть какое-то пояснение, что есть SecondaryStatus, когда и как в нём отражаются какие-то данные, и что они означают (с учетом того, что есть еще и PrimaryStatus). Особенно с учетом того, что на текущий момент ни в одном из своих документов мы это поле заполненным не видели.

А также какие значения может принимать поле Text в структуре StatusModel:

Т.к. теперь совершенно непонятно, у каких типов документов какие статусы и когда могут быть. А также – есть ли различия в этих значениях для PrimaryStatus и SecondaryStatus.

[GilimkhanovDenis]

#968

Необходимо получение событий за определённую дату или по конкретному документу