2.5. Методы API и события¶
Мы продолжаем развивать функциональность методов API.
2.5.1. Использование сессии Synergy в REST API¶
Synergy REST API использовал сессии для запросов, из-за чего при передаче в запросе
cookie
от Synergy для аутентификации использовались данные сессии, а не то,
что было передано в Authorization
.
Внешне эту проблему можно было наблюдать, если в одной вкладке браузера авторизоваться
в клиенте /Synergy
, а в соседней - во внешнем модуле под другим пользователем. В этом
случае все запросы во внешнем модуле выполнялись от имени того пользователя, который
авторизован в основном клиенте Synergy.
В новой версии hamming
эта проблема была исправлена: теперь авторизация не смешивается,
и в запросах API используются только переданные данные Authorization
, а не данные сессии.
2.5.2. Изменение логина и пароля пользователя¶
Мы реализовали новый метод, позволяющий изменить логин и/или пароль авторизованного пользователя. Рекомендуем использовать этот метод в портальных решениях на базе Synergy.
URL метода: rest/api/filecabinet/user/changeCredentials
Тип: POST
Параметры метода:
actionCode
- тип действия (обяз.):CHANGE_LOGIN
- изменить логинCHANGE_PASSWORD
- изменить парольCHANGE_ALL
- изменить и логин, и пароль пользователя
login
- новый логин пользователя; обязателен, если параметрactionCode
имеет значениеCHANGE_LOGIN
илиCHANGE_ALL
password
- новый пароль пользователя; обязателен, если параметрactionCode
имеет значениеCHANGE_PASSWORD
илиCHANGE_ALL
passwordConfirm
- подтверждение пароля, значение параметра должно совпадать с параметромpassword
; обязателен, если параметрactionCode
имеет значениеCHANGE_PASSWORD
илиCHANGE_ALL
locale
- локаль пользователя (не обязателен, по умолчанию используетсяru
).
Полное описание метода приведено в swagger.
2.5.3. Использование кодов для групп пользователей¶
Исторически сложилось, что во всех методах API, оперирующих группами пользователей, невозможно было использовать код этой группы: методы принимали и возвращали только UUID объекта группы.
Мы доработали все методы, работающие с группами пользователей, добавив в их принимаемые и/или
возвращаемые параметры новый параметр groupCode
. Перечень измененных методов:
rest/api/storage/groups/list
rest/api/userchooser/search
rest/api/userchooser/search_ext
rest/api/userchooser/getUserInfo
rest/api/storage/groups/add_user
rest/api/storage/groups/remove_user
rest/api/storage/groups/list
rest/api/groups/content
rest/api/groups/find
rest/api/person/auth
2.5.4. Повторная отправка блокирующего процесса в очередь¶
Теперь решать проблемы с «зависшими» блокирующими процессами в маршрутах документов стало проще. Мы реализовали новый метод API, повторно отправляющий все зависшие блокирующие процессы в указанном документе в очередь.
URL метода: rest/api/processes/retry_bp
Тип: POST
Параметр:
documentID
- идентификатор документа, в котором требуется переотправить БП.
Примечание
Метод должен выполняться от имени пользователя с ролью «Разработчик Synergy».
Полное описание метода приведено в swagger.
2.5.5. Проверка принадлежности пользователя к подразделению¶
Мы реализовали два новых метода, предназначенных для проверки принадлежности пользователя определенному родительскому подразделению. Причем для проверки могут использоваться как UUID подразделений и пользователей, так и их коды для показателей, что упрощает процесс переноса приложений.
2.5.5.1. Получение всех подразделений пользователя¶
Метод возвращает список из ID и кодов подразделений, к которым принадлежит этот пользователь, начиная с его непосредственного подразделения и вверх до корня.
Описание метода приведено в swagger.
URL метода: rest/api/person/get_user_departments
Тип: GET
Параметры:
userCode
- код для показателей пользователяuserID
- UUID пользователя (не обязателен, если переданuserCode
)
Если переданы одновременно и код, и UUID пользователя, будет использован только код.
Пример:
На сервере настроена оргструктура вида:
- ROOT
- Basic 1
- Линия 1
- должность «Service manager»
- Линия 1
- должность «Test»
- Basic 1
Пользователь «Тестовый Сотрудник» назначен на должности «Service manager» и «Test».
Для этого пользователя метод rest/api/person/get_user_departments
вернет массив json
вида:
[
[
{
"id": "1",
"code": "root"
}
],
[
{
"id": "6fd171e5-dc6f-45da-a677-3d0dd75e4802",
"code": "liniya_1"
},
{
"id": "6262e38d-bcac-4ef6-acae-dfaf193c0cdc",
"code": "basic"
},
{
"id": "1",
"code": "root"
}
]
]
Метод вернул массив с двумя элементами:
элемент с корневой нодой структуры: признак того, что пользователь непосредственно принадлежит этой ноде:
[ { "id": "1", "code": "root" } ]
2. элемент со списком из трех нод: «liniya_1», «basic» и «root»: признак того, что пользователь непосредственно входит в подразделение «Линия 1», далее перечислены родительские подразделения вплоть до корневой ноды «root»:
[ { "id": "6fd171e5-dc6f-45da-a677-3d0dd75e4802", "code": "liniya_1" }, { "id": "6262e38d-bcac-4ef6-acae-dfaf193c0cdc", "code": "basic" }, { "id": "1", "code": "root" } ]
2.5.5.2. Проверка принадлежности пользователя определенному подразделению¶
Метод определяет, принадлежит ли указанный пользователь указанному подразделению или любому его из родительских подразделений вплоть до корня.
Описание метода приведено в swagger.
URL метода: rest/api/person/check_user_department
Тип: GET
Параметры:
depCode
- код для показателей подразделенияdepID
- UUID подразделения (не обязателен, если переданdepCode
)userCode
- код для показателей пользователяuserID
- UUID пользователя (не обязателен, если передан ``userCode`)
Если переданы одновременно и код, и UUID пользователя/подразделения, будет использован только соответствующий код.
Метод возвращает true
, если пользователь входит в указанное подразделение, и false
в противном случае.
2.5.6. Передача значений произвольных компонентов при поиске по реестру¶
При разработке бизнес-приложений на Synergy часто возникает необходимость получить максимум данных из реестра одним запросом, а потом использовать полученные данные или фильтровать их на стороне клиента.
Такой вариант использования требует указания всех данных, которые необходимо получить из
реестра, как отображаемых полей реестра. При этом получаемые данные могут иметь специфическую
структуру - например, это может быть изображение, закодированное в Base64
, или UUID данных.
Мы доработали метод поиска по реестру rest/api/registry/data_ext
, добавив для него новый
параметр fields
. В этом параметре можно передать коды компонентов формы, которые нужно
возвращать для каждой записи реестра.
Пример использования: fields=text1&fields=text2&fields=number1
Теперь один запрос данных реестра позволяет получить не только данные отображаемых полей реестра, но и данные произвольных компонентов формы этого реестра.
Полное описание метода приведено в swagger.
2.5.7. События открытия и закрытия документов¶
Реализованы новые события открытия и закрытия документов. Теперь можно реализовать произвольную обработку этих событий: например, запретить открывать документ, пока он открыт другим пользователем, чтобы избежать перезаписи данных.
Описания событий:
event.docflow.document.opened
- открытие документа (генерируется только из UI Synergy):documentID
- идентификатор документа;userID
- идентификатор пользователя, сохранившего данные по форме;date
- дата и время открытия документа;
event.docflow.document.closed
- закрытие документа (генерируется только из UI Synergy):documentID
- идентификатор документа;userID
- идентификатор пользователя, сохранившего данные по форме;date
- дата и время открытия документа.