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»
- должность «Test»

Пользователь «Тестовый Сотрудник» назначен на должности «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 - дата и время открытия документа.