Использование в браузере
Примечание
В инициализированном web-приложении Records и Citeck.Records ссылаются на один компонент.
Для работы с Records API разработан компонент Records, который доступен в глобальном контексте на любой странице системы.
Атрибуты статуса, лицензии, рабочих областей и другие прикладные поля в примерах ниже предоставляются соответствующими сервисами. Их доступность и права определяются источником записи.
Доступные операции:
get(recordRef) - Получить запись по её идентификатору. Ниже представлен список операций с записью;
query(query, attributes) - Поиск записей. Первый аргумент - запрос для поиска, а второй - какие атрибуты нам нужны у найденых записей;
remove(records) - Удаление записей.
Операции с записью, которая получена через метод «Records.get»:
load(attributes, forceLoad) - Загрузить атрибут или несколько атрибутов. При
forceLoad=trueсохранённые значения загружаются повторно; при false или отсутствии параметра используется кэш;att(attributeName, value) - Проставить значение атрибута для записи. Используется перед сохранением записи;
save(attsToLoad) - Сохранить изменения в записи, которые были сделаны методом att из предыдущего пункта и загрузить атрибуты, которые передали в attsToLoad (опционально);
load возвращает Promise: для строки атрибута — одно значение, для массива строк — объект с этими строками в качестве ключей, для карты алиасов — объект с заданными ключами.
Метод save может принимать атрибуты для загрузки. В этом случае на сервер вместе с изменениями отправляется поле attributes. save(attsToLoad) возвращает Promise с той же формой данных, что и load; обычный save() для серверной записи возвращает Promise объекта Record. remove возвращает Promise без значения. Для последовательных операций используйте await.
Примечание
forceLoad=true не отменяет несохранённые изменения, сделанные через att: для изменённого атрибута может вернуться локальное значение. Виртуальные записи обрабатываются локально; параметр не гарантирует HTTP-запрос в каждом случае.
Метод Records.getRecordToEdit(recordRef) возвращает отдельную обёртку редактирования базовой записи. Её временный идентификатор с -alias- связан с исходной записью и не является идентификатором новой сущности на сервере.
Структура query
Records.query возвращает Promise объекта с полями records, messages, hasMore, totalCount, attributes и errors. Без запроса атрибутов элементы records — строки ссылок. С атрибутами это объекты с запрошенными значениями и полем id, содержащим полную ссылку, если алиас id не задан потребителем.
Этот результат браузерного компонента отличается от сырых серверных записей вида {id, attributes}.
Поле |
Описание |
|---|---|
|
Идентификатор источника данных в формате «приложение/id_локального_источника_данных» |
|
Любой формат, который поддерживается источником данных |
|
Язык для определения содержимого query. Источник данных может поддерживать несколько языков |
|
Список объектов |
|
Список атрибутов для группировки |
|
Объект |
|
Ожидаемая консистенция данных: |
{
"sourceId": String,
"query": Any,
"language": String,
"sortBy": [
{
"attribute": String,
"ascending": Boolean
}
],
"groupBy": [String],
"page": {
"maxItems": Number,
"skipCount": Number
},
"consistency": EVENTUAL | TRANSACTIONAL | DEFAULT | TRANSACTIONAL_IF_POSSIBLE
}
Примеры использования
Запрос ФИО пользователя:
var user = Records.get('emodel/person@user');
await user.load(['userName', 'firstName', 'lastName'])
Запрос имени пользователя:
var user = Records.get('emodel/person@user')
await user.load('firstName')
Пример скрипта для смены статуса:
var doc = Records.get('someDocumentRef');
doc.att('_status', 'some_status_id');
await doc.save();
Получение сразу нескольких атрибутов у вложенного значения:
await Records.get('uiserv/rjournal@test587').load('boardRefs[]{id,name}', true)
Статус объекта:
await Records.get('emodel/someType@id').load("_status?str")
Проверка enterprise лицензии:
await Records.get('emodel/meta@').load('$license.enterprise?bool', true)
Получение рабочих областей текущего пользователя:
await Records.query({
sourceId: 'emodel/workspace',
language: 'user-workspaces'
}, {
'wsId': '?localId',
'wsName': '?disp!?localId'
})
Узнать sourceId по typeId:
await Records.get('emodel/type@typeId').load('sourceId')
CRUD операции
Ниже представлены примеры основных операций, выполняемых при управлении данными и манипулировании:
const record = Records.get("emodel/someType@");
record.att("name", "New record");
record.att("someAttribute", "Hello world!");
await record.save();
const record = Records.getRecordToEdit("emodel/someType@id");
await record.load("?json");
const record = Records.getRecordToEdit("emodel/someType@id");
record.att("someAttribute", "New value");
await record.save();
await Records.remove("emodel/someType@id1"); // 1 объект
await Records.remove(["emodel/someType@id1", "emodel/someType@id2"]); // массив объектов
Общение с сервером происходит через POST запросы:
Браузерный клиент передаёт version: 1 в теле запроса для выбора версии REST-контракта.
Запрос |
Описание |
В коде ecos-ui используется |
|---|---|---|
/gateway/api/records/query
|
Поиск записей и/или получение атрибутов |
Records.query и Records.get("id_сущности").load(атрибуты_для_загрузки)
|
/gateway/api/records/delete
|
Удаление сущностей |
Records.remove
|
/gateway/api/records/mutate
|
Создание или изменение сущностей |
var rec = Records.get("id_сущности"); rec.att("атрибут", "значение"); rec.save()
|
Возвращаемые в ответе типы
Браузерный клиент читает ответы этих endpoint как JSON. Это описание транспорта браузерного клиента; Java/Kotlin API возвращает также DTO и другие объекты.
Коды HTTP ответов
Примеры HTTP-кодов ответа (полный набор зависит также от gateway и авторизации):
200 OK
401 Unauthorized
500 Internal Server Error
Описание ошибок и их уровни
Ошибки отражены в теле ответа по ключу messages и с полем level равным «ERROR».
Пример:
{
"messages": [
{
"level": "ERROR",
"time": 1653990549261,
"type": "text",
"msg": "Some error",
"requestId": "7848a70e-a449-4b24-abb9-a2a7fbb8ebfa",
"requestTrace": [
"gateway:06d039e1766550be603cf98379bbdb22",
"alfresco:019ca5db-160f-45df-84a6-02750a4f13b7"
]
}
],
"txnActions": [],
"records": [],
"hasMore": false,
"totalCount": 0,
"version": 1
}
Поддерживаются уровни ERROR, WARN, INFO и DEBUG; состав сообщений зависит от настроек запроса. Отладочные сообщения можно запросить через Records.query(query, attributes, {debug: true}).
Ошибка может присутствовать в messages даже при HTTP 200. Транспорт браузерного компонента при сообщении ERROR отклоняет Promise; поле msg может содержать строку или объект ошибки. Для type=records-error текст может находиться в msg.msg.
При обработке результата учитывайте особенности метода: некоторые ветки load перехватывают ошибку, выводят её в консоль и возвращают пустое значение. Успешный HTTP-статус сам по себе не подтверждает успешное выполнение операции.