Методы API

Работа со скриптами

Бизнес-объекты в скриптах
Работа со значениями атрибутов
Настройка оповещений и уведомлений
Принудительное сжатие больших изображений в тексте RTF
Вывод пользовательских сообщений об ошибке
Скрипты на пользовательские события (кнопка-скрипт)
Аннотация @InjectApi

Бизнес-объекты в скриптах

Для обращения к объектам системы в скриптах используются контекстные переменные, например, subject, oldSubject.

Получение значения атрибута при обращении к атрибутам объекта напрямую — obj.'код атрибута', где obj — объект системы:

subject.UUID // UUID объекта

subject.title // название объекта

subject.state // код состояния объекта с настроенным жизненным циклом

Общие методы для бизнес-объектов, возвращаемых API-методами (utils.get, utils.find и др.):

subject.getUUID() // аналогично subject.UUID

subject.getMetainfo() // FQN класса (типа) объекта. Может быть null на этапе создания объекта, когда его тип еще не определен

subject.getMetainfo() считается предпочтительным способом получения FQN объекта

Описание переменных, используемых в скриптах приводится в описании категорий скриптов, см. Категории скриптов.

Работа со значениями атрибутов

Счетчики времени

Получение значения атрибута типа "Счетчик времени":

subject.'код атрибута типа счетчик времени';

Пример. Получение значения системного атрибута текущего запроса "Время обработки запроса" типа "Счетчик времени":

subject.processingTimeTimer;
Получение параметров атрибута типа "Счетчик времени":
- timerVal.status — статус счетчика времени;
- timerVal.elapsed — время счетчика;
- timerVal.status.code — код статуса счетчика времени:
  - 'e' (EXCEED) — кончился запас времени;
  - 'a' (ACTIVE) — активен;
  - 'n' (NOTSTARTED) — ожидает начала;
  - 'p' (PAUSED) — приостановлен;
  - 's' (STOPPED) — остановлен.
Получение значения атрибута типа "Счетчик времени (обратный)":

subject.'код атрибута типа счетчик времени (обратный)'

Пример. Получение значения системного атрибута текущего запроса "Запас нормативного времени обслуживания" типа "Счетчик времени (обратный)":

subject.timeAllowanceTimer
Получение параметров атрибута типа "Счетчик времени (обратный)":
- backTimerVal.status — статус обратного счетчика времени;
- backTimerVal.deadLineTime — время окончания счетчика;
- backTimerVal.allowance — остаток времени счетчика
- timerVal.status.code — код статуса счетчика времени:
  - 'e' (EXCEED) — кончился запас времени;
  - 'a' (ACTIVE) — активен;
  - 'n' (NOT STARTED) — ожидает начала;
  - 'p' (PAUSED) — приостановлен;
  - 's' (STOPPED) — остановлен.
Получение времени перехода счетчика времени в статус "Кончился запас времени":

def deadLineTime = backTimerVal.deadLineTime
Получение времени, которое счетчик времени находится в статусе "Кончился запас времени" с момента входа в статус по текущее время (в мс):

def elapsedFromOverdue = backTimerVal.elapsedFromOverdue

Временной интервал

Получение значения атрибута типа "Временной интервал":

subject.'код атрибута'

Пример. Получение значения системного атрибута текущего запроса "Нормативное время обработки" типа "Временной интервал":

subject.resolutionTime
Получение параметров атрибута типа "Временной интервал":

Количество:

def length = value.length;

Единица измерения:

def interval = value.interval;

Длина интервала в мс.:

def ms = value.toMiliseconds();
api.types.newDateTimeInterval(length, interval)

Создание нового значения типа "Временной интервал".

Параметры метода:
- length — длительность интервала. Int;
- interval — единица измерения интервала SECOND, MINUTE, HOUR, DAY или WEEK. String.
Пример:

def newVal = api.types.newDateTimeInterval(7, 'DAY')

Гиперссылка

Получение значения атрибута типа "Гиперссылка":

subject.'код атрибута типа гиперссылка'
Получение параметров атрибута типа "Гиперссылка":

Название ссылки:

hyperlinkVal.text;

URL ссылки:

hyperlinkVal.URL;
api.types.newHyperlink()

api.types.newHyperlink(text)

api.types.newHyperlink(text, url)

Создание новой гиперссылки.

Параметры метода:
- text — название гиперссылки;
- url — url гиперссылки.

Текст с подсветкой синтаксиса

Получить значение атрибута:

def sourceCodeVal = ...
Получить текст (скрипт):

def text = sourceCodeVal.text
Получить язык (синтаксис):

def url = sourceCodeVal.lang
api.types.newSourceCode(text, lang)

api.types.newSourceCode(text)

Создание нового значения типа "Текст с подсветкой синтаксиса".

Параметры метода:
- text — текст(скрипт);
- lang — язык(синтаксис)
Примечание: При указании синтаксиса доступны следующие значения:
- Без синтаксиса = ""
- Groovy = "text/x-groovy"
- Javascript = "text/javascript";
- SQL = "text/x-sql";
- XML = "application/xml";
Если синтаксис указан неправильно или с ошибкой, то применяется значение "Без синтаксиса".

Тип объекта

Получить тип объекта по идентификатору fqn:

def classFqn = api.types.newClassFqn(fqn)

Пример. Получение типа запроса по идентификатору 'serviceCall$incident':

def incidentClassFqn = api.types.newClassFqn('serviceCall$incident')

Ссылка на атрибут

Получить ссылку на атрибут по типу объекта fqn и коду атрибута code:

def attrReference = api.types.newAttrReference(fqn, code)

Значения атрибута на форме

initialValues.getProperty(attrCode)

Получение значения атрибута с формы.

Параметр метода:
- attrCode — код атрибута, значение которого необходимо получить.
Возвращает значение атрибута.
initialValues.hasProperty(attrCode)

Проверка наличия атрибута на форме.

Параметр метода:
- attrCode — код проверяемого атрибута.
Возвращает:
- true — при наличии атрибута на форме,
- false — при отсутствии атрибута на форме.

Настройка оповещений и уведомлений

Настройка оповещений

Объект notification может использоваться внутри скрипта кастомизации оповещения, внутри темы и внутри текста сообщения. Перед отправкой оповещения объект notification можно модифицировать, что позволяет изменять следующие параметры оповещений:

notification.parameters — параметры отправки оповещения:
- parameters.from — Адрес отправителя.
  
  При изменении параметра в скрипте, важно учитывать ограничения используемого сервера, например, для сервера smtp.gmail.com допустимо использовать только подтвержденные реальные адреса;
- parameters.name — Имя отправителя
- parameters.feedbackAddress — Адрес электронной почты, на который будут автоматически отсылаться сообщения о серверных ошибках
- parameters.outgoingServer — Код подключения к серверу исходящей почты
- parameters.characterEncoding — Кодировка текста, по умолчанию 'UTF-8'
- parameters.transliterateSubject — Транслитерация заголовков писем, по умолчанию false
notification.setHeader(headerName, headerValue)

Добавление и редактирование заголовка оповещения.

Параметры:
- headerName — название заголовка;
- headerValue — значение указанного заголовка
Пример:

notification.setHeader('In-Reply-To', '52D635DD.90108@naumen.ru')'

Изображения в теле письма

utils.imageForHtml(fileUUID)

Добавление изображения в тело оповещения или уведомления. Метод преобразует изображение в HTML-строку

Параметр:
- fileUUID — uuid файла с изображением
Возвращает строку вида <img src="data:... "/> с закодированным в base64 изображением или пустую строку в случае ошибки.

Пример в тексте оповещения:

${utils.imageForHtml('file$72801')}

Прикрепление события календаря к оповещению

notification.addCalendarEvent(event)

Добавление события календаря к оповещению.

Параметр:
- event — событие календаря, которое нужно добавить.

Параметры упоминания объекта

Переменная mention доступна для действия по событию "Упоминание в рамках выбранных объектов".

mention — параметры упоминания объекта (атрибута, в котором использовались упоминания):
- mention.changedAttribute — измененный атрибут типа "Текст в формате RTF" (если упоминание добавлено в рамках комментария, то содержит 'text');
- mention.newMentions — список идентификаторов новых упоминаний;
- mention.untouchedMentions — список идентификаторов неизмененных упоминаний;
- mention.removedMentions — список идентификаторов удаленных упоминаний

Переменная mentions доступна для действий по событию "Добавление комментария", "Редактирование комментария", "Добавление объекта", "Редактирование объекта", "Смена статуса", "Смена ответственного".

mentions — список атрибутов, в которых использовались упоминания, в формате:

mentions == [код_атрибута_1: mention, код_атрибута_2:mention...]

Настройка всплывающих уведомлений в интерфейсе

Объект push может использоваться внутри скрипта кастомизации уведомления, внутри темы и внутри текста сообщения. Перед отправкой оповещения объект push можно модифицировать, что позволяет изменять следующие параметры уведомления:

Параметры уведомления в веб-интерфейсе:
- push.toEmployee — список сотрудников-получателей уведомлений. Поле push.toEmployee всегда будет пустым списком в момент начала выполнения скрипта. Данное поле необходимо заполнять в самом скрипте.
- push.toRemoveEmployee — список сотрудников-для исключения из получателей уведомления
- push.browserNoticeLink — ссылка для перехода при нажатии на браузерном уведомлении

Принудительное сжатие больших изображений в тексте RTF

api.preview.shrinkImages(bo, attrCode)

api.preview.shrinkImages(bo, attrCode, skipWithSizes)

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

Параметры метода:
- bo — бизнес-объект;
- attrCode — код атрибута типа "Текст в формате RTF";
- skipWithSizes — параметр, указывающий на то, как должны быть обработаны изображения с установленными размерами (атрибуты width и height элемента):
  - true (или параметр не задан) — изображения с установленными размерами пропускаются;
  - false — будут обработаны все изображения.
api.preview.shrinkImages(message)

api.preview.shrinkImages(message, skipWithSizes)

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

Параметры метода:
- message — входящее сообщение
- skipWithSizes — параметр, указывающий на то, как должны быть обработаны изображения с установленными размерами (атрибуты width и height элемента):
  - true (или параметр не задан) — изображения с установленными размерами пропускаются;
  - false — будут обработаны все изображения.

Вывод пользовательских сообщений об ошибке

Вывод пользовательских сообщений об ошибке без использования методов скриптового API:

Конструкция для вывода сообщений в интерфейс оператора в скриптах условий на вход в статус / выход из статуса:

return "message"

Вывод пользовательских сообщений об ошибке с использованием методов скриптового API. Для доступа к методам используется утилитарный метод api.utils или его короткий псевдоним utils:

utils.throwReadableException(message, args)

Вывод в лог пользовательского сообщения об ошибке (message). В интерфейс оператора будет выводиться стандартное системное сообщение об ошибке.

Метод используется в скриптах условий и действий при входе в статус / выходе из статуса и в скриптах синхронных действий по событиям.

Метод не может вызываться из консоли.

Параметры метода:
- message — формат сообщения об ошибке для лога. String;
- args — аргументы к формату сообщения. Object.
utils.throwUiReadableException(message, args)

Вывод пользовательского сообщения об ошибке в интерфейсе оператора (на форму) и в лог (консоль). В интерфейс оператора будет выводиться сообщение, которое было передано в данный метод. Никаких дополнительных системных сообщений к тексту ошибки не добавляется.

Форматы сообщений должны соответствовать спецификации java.util.Formatter. Так же допускается указывать обычный текст вместо форматов. В этом случае следует вместо массива аргументов указывать null.

Метод используется в скриптах условий и действий при входе в статус / выходе из статуса и в скриптах синхронных действий по событиям.

Параметры метода:
- message — формат сообщения об ошибке для интерфейса оператора, сообщение будет продублировано в лог. String;
- args — аргументы к формату для интерфейса оператора, дублируется в лог. Object.
utils.throwReadableException(message, messageArgs, uiMessage, uiMessageArgs)

Вывод различных пользовательских сообщений об ошибке в интерфейсе оператора и в лог (консоль). Форматы сообщений должны соответствовать спецификации java.util.Formatter. Так же допускается указывать обычный текст вместо форматов. В этом случае следует вместо массива аргументов указывать null.

Метод используется в скриптах условий и действий при входе в статус / выходе из статуса и в скриптах синхронных действий по событиям.

Метод не может вызываться из консоли.

Параметры метода:
- message — формат сообщения об ошибке для лога. String
- messageArgs — аргументы к формату сообщения для лога. Если аргументы для форматирования не требуются, то они задаются как [] as String[]
- uiMessage — формат сообщения об ошибке для интерфейса пользователя. String
- uiMessageArgs — аргументы к формату сообщения для интерфейса пользователя
Для скриптов условий при входе в статус / выходе из статуса рекомендуется использовать методы return и utils.throwUiReadableException

Пример 1:

utils.throwReadableException("Внимание! нельзя менять категорию на %s", ['меньшую'] as String[], "Внимание! нельзя менять %s %s",['категорию', 'на меньшую'] as String[]);

Пример 2:

utils.throwReadableException("Внимание! нельзя менять категорию на меньшую", [] as String[], "Внимание! нельзя менять категорию на меньшую", [] as String[]);
Использование конструкции try-catch (обработчик исключений). При использовании конструкции try-catch в api исключение нужно пробрасывать дальше, иначе некоторые системные проверки будут игнорироваться и транзакция будет завершаться успешно.

Пример. Получение содержимого файла.

Считываем содержимое файла как массив байтов. Файл не должен быть слишком большим, поскольку его содержимое будет помещено в оперативную память, что может негативно сказаться на производительности. Не следует использовать в одном скрипте вместе с методами добавления файлов (например, utils.attachFile), т.е. добавление файла и его считывание одним скриптом (или в одной транзакции), может привести к ошибке.
```
def file = fileList[0] // объект типа "Файл"
try
{
byte[] data = utils.readFileContent(file)
}
catch(e)
{
logger.error "Ошибка при чтении содержимого файла из файлового хранилища"
}
```

Скрипты на пользовательские события (кнопка-скрипт)

В скрипте действия по событию используется переменная result, с помощью которой устанавливается действие, производимое после события.

Методы переменной result используются только для синхронных действий по событию.

В переменной result доступны следующие методы.

Для веб-приложения

downloadFile(file)

downloadFile(file, title)

Инициировать скачивание файла браузером.

Параметры метода:
- file — объект класса "Файл" или uuid объекта класса "Файл";
- title — название файла, которое будет установлено скачанному файлу
executeJavaScript(js)

Выполнение javascript на клиенте.

Параметр метода:
- js — код на javascript. String
Пример: Асинхронная передача данных со стороны браузера на сервер (функция callback). Пользователю показывается popup-окно с полем ввода и кнопкой. После заполнения поля и нажатия кнопки, в системе создается одноименный отдел.

Первое действие по событию (на которое настроена кнопка-скрипт):
Copy
```
def js='''newWindow = window.open("", null, "height=70,width=200,status=yes,toolbar=no,menubar=no,location=no");
newWindow.document.write("<input id='id1' type='text'/><br/><input id='id2' type='button' value='Создать отдел'/>");
newWindow.document.getElementById('id2').onclick = function () {
result.ouTitle=newWindow.document.getElementById('id1').value;
result.nextEventUuid='eventAction$2';
callback(result);
newWindow.close()
}'''
result.executeJavaScript(js);
```
Второе действие по событию:

utils.create('ou$ou', ['title':clientData.ouTitle])
goToUrl(url)

goToUrl(url, newTab)

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

Если открывается форма с необходимостью заполнения некоторых параметров, и на форме нажимается кнопка "Отмена", то происходит редирект на главную страницу SMP.

Параметры метода:
- url — ссылка. String
- newTab:
  - true — в браузере откроется новая вкладка или окно в зависимости от браузера;
  - false или параметр не определен — новая вкладка не открывается
Для полной перезагрузки карточки объекта можно использовать:

result.goToUrl(api.web.open(subject))

Примеры некорректной настройки:
- Бизнес-логика игнорирует попытки перехода на ту же ссылку, что открыта в текущий момент. При таком вызове ничего не произойдет
  
  result.goToUrl(api.web.baseUrl + '#uuid:'+subject.UUID)
- Вот такой вызов будет неправильным,
  
  result.goToUrl("www.google.com")
  
  путь нужно указать полностью:
  
  result.goToUrl("https://www.google.com/")
Примечания:
- Чтобы в пользовательском событии использовать goToUrl и api.web.getPlace, нужно перед результатом api.web.getPlace добавить #. Без # сгенерируется некорректная ссылка с uuid.
- При использовании метода для перехода на вручную сформированные ссылки (например, при добавлении в URL !{"fast":"true"}) необходимо последнюю часть передавать в формате RFC Compability. Таким образом вручную сформированная ссылка должна иметь вид подобный следующему:
  
  //http://any-stand.ru/sd/operator/#add:serviceCall$request::request!%21%7B%22fast%22%3A%22true%22%7D
  
  т.е. часть !{"fast":"true"} следует передавать в url-encoded виде.
  
  При использовании в связке с методом api.web.add() дополнительных действий не требуется
reload(needReload)

Отключение обновления значений атрибута на карточке после выполнения пользовательских действий.

Параметр needReload:
- true — после выполнения пользовательских действий карточка объекта обновляется. Происходит обновление данных и частичную перерисовку интерфейса (если это необходимо), без полной перезагрузки страницы. Обновление не затрагивает контенты типа "Встроенное приложение";
- false — карточка не обновляется.
showMessage(message)

showMessage(title, message)

Показать сообщение.

Параметры метода:
- title — заголовок сообщения. String.
  
  Если параметр не определен, то сообщение показывается с пустым заголовком;
- message — текст сообщения, возможно форматирование через прямое указание тегов.
  
  Использовать можно только теги и их атрибуты, которые перечислены в файле "белый лист" (параметр ru.naumen.security.sanitizeHtml конфигурационного файла dbaccess.properties, см. Безопасность).
Пример. Показать сообщение с заголовком:

result.showMessage("Alert!", "Сообщение")

Для мобильного приложения

showMessage(message)

Показать toast сообщение.

Параметр метода:
- message — текст сообщения
Пример. Показать сообщение без заголовка в МК (toast):

result.showMessage("Сообщение")
showMessage(title, message)

Показать сообщение в диалоговом окне.

Параметры метода:
- title — заголовок сообщения. String
- message — текст сообщения. String
Пример. Показать сообщение с заголовком в МК (alert):

result.showMessage("Alert!!", "Сообщение")
goToMobileAddForm(formCode, attributes)

Переход на форму добавления объекта.

Параметры метода:
- formCode — код формы добавления объекта в мобильном приложении. String;
- attributes — ассоциативный список атрибутов <Код : Значение>
Если в параметре formCode указан код формы, которая является вложенной, то может быть подобрана родительская или другая вложенная форма, т.к. при открытии формы в мобильном приложении тип объекта заполняется автоматически и подбирается соответствующая ему форма, см. Логика формирования набора полей на форме добавления.

Чтобы точно была открыта определенная форма добавления, рекомендуется указывать тип объекта в параметре attributes.

Пример. Выполнение переадресации пользователя на форму добавления объекта внутри мобильного приложения:
Copy
```
def attributes = [
'intValue':1020434,
'hLink' : api.types.newHyperlink('ссылка на ресурс', 'https://www.naumen.ru'),
'Logic' : true,
'DateNL' : new Date(),
'DateTime' : new Date(),
'catItem' : 'impact$2802'
'dateTimeIntervalAttribute' : 1020434
];
def subject = utils.get('userClassA$2902');
//на форму добавления объекта с кодом "addClassAform"
result.goToMobileAddForm("addClassAform", attributes);
```
goToMobileEditForm(subject, attributes)

goToMobileEditForm(subject, formCode, attrs)

Переход на форму редактирования объекта.

Параметры метода:
- subject — объект (UUIDIdentifiable) или UUID-объекта, для которого вызывается форма редактирования. Object;
- formCode — код формы редактирования объекта в мобильном приложении. String;
- attributes — ассоциативный список атрибутов <Код : Значение>
Пример 1. Выполнение переадресации пользователя на форму редактирования объекта внутри мобильного приложения:
```
def attributes = [
'intValue':1020434,
'hLink' : api.types.newHyperlink('ссылка на ресурс', 'https://www.naumen.ru'),
'Logic' : true,
'DateNL' : new Date(),
'DateTime' : new Date(),
'catItem' : 'impact$2802'
'dateTimeIntervalAttribute' : 1020434
];
def subject = utils.get('userClassA$2902');
//на форму редактирования объекта
result.goToMobileEditForm(subject, attributes);
```
Пример 2. Выполнение переадресации пользователя на форму редактирования объекта с кодом "editClassAform" внутри мобильного приложения:
```
def attributes = [
'intValue':1020434,
'hLink' : api.types.newHyperlink('ссылка на ресурс', 'https://www.naumen.ru'),
'Logic' : true,
'DateNL' : new Date(),
'DateTime' : new Date(),
'catItem' : 'impact$2802'
'dateTimeIntervalAttribute' : 1020434
];
def subject = utils.get('userClassA$2902');
//на форму редактирования объекта с кодом "editClassAform"
result.goToMobileEditForm(subject, "editClassAform", attributes);
```
goToMobileObjectCard(subject)

Переход на карточку объекта.

Параметр метода:
- subject — объект (UUIDIdentifiable) или UUID-объекта, на карточку которого необходимо перейти. Object.
Пример. Выполнение переадресации пользователя на карточку объекта внутри мобильного приложения:
```
def attributes = [
'intValue':1020434,
'hLink' : api.types.newHyperlink('ссылка на ресурс', 'https://www.naumen.ru'),
'Logic' : true,
'DateNL' : new Date(),
'DateTime' : new Date(),
'catItem' : 'impact$2802'
'dateTimeIntervalAttribute' : 1020434
];
def subject = utils.get('userClassA$2902');
//на карточку объекта
result.goToMobileObjectCard(subject);
```
goToExternal(url)

goToExternal(url, attributes)

Переадресация в стороннее приложение.

Параметры метода:
- url — ссылка на приложение. String
- attributes — ассоциативный список параметров <Код : Значение>
Пример. Выполнение переадресации пользователя в стороннее приложение:
```
def url = "text:/coolreader";
def attributes = [
'intValue':1020434,
'hLink' : api.types.newHyperlink('ссылка на ресурс', 'https://www.naumen.ru'),
'Logic' : true,
'DateNL' : new Date(),
'DateTime' : new Date(),
'catItem' : 'impact$2802'
];
result.goToExternal(url, attributes);
```

Аннотация @InjectApi

Инжектирование API в groovy-классы.

Аннотация @InjectApi позволяет использовать скриптовое API внутри классов, помеченных этой аннотацией.

Внедряет следующие контекстные переменные как свойства класса:
- api
- appVersion
- logger
- modules
- op
- queuedDate
- sp
- utils
- geo
Особенности: несовместима с аннотацией @Delegate в пределах класса и со static контекстом.

Пример:
```
import ru.naumen.core.server.script.api.injection.InjectApi
@InjectApi
class TestClass
{
  def testMethod(def testArg)
  {
     logger.info("$testArg") //без @InjectApi переменная logger будет недоступна
  }
}
```

api.actionContext Получение контекста выполняемого действия

api.actionContext.isMobile()

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

Возвращаемое значение:
- true — контекст выполнения действия: мобильное приложение;
- false — контекст выполнения действия: веб-интерфейс системы.
Пример. Для действия по событию "Прикрепление файла к объекту" будет добавляться комментарий, в котором будет указано прикреплен файл через мобильное приложение или веб-интерфейс системы.
Copy
```
boolean isMobile = api.actionContext.isMobile()
def comment = "Добавлен новый файл: ${sourceObject.title }<br>Дата добавления файла: ${new Date()}<br>Мобильный клиент: ${isMobile}"
utils.edit(subject, ['@comment' : comment.toString()]) 
```

api.advimport Работа с импортом

Остановка импорта

api.advimport.stop(advimportConfig)

Остановка выполнения активной конфигурации импорта.

Используется в консольном скрипте, который может быть запущен в любой момент выполнения импорта, см. Скрипты, выполняемые в консоли.

Параметр метода:
- advimportConfig — идентификатор конфигурации импорта. Идентификатор импорта указывается в адресной строке карточки конфигурации:
  
  ../sd/admin/#advImportConfig:f0e05190-145d-0247-0000-00007388e0bf
Результат выполнения: Импорт остановлен — в лог системы и лог импорта записывается сообщение, создание и модификация объектов, выполненные до момента остановки импорта, не отменяются. Если конфигурация импорта с указанным идентификатором отсутствует или не запущена, выводится сообщение об ошибке

Пример: Остановка активной конфигурации импорта (идентификатор конфигурации импорта — f0e05190-145d-0247-0000-00007388e0bf):

api.advimport.stop('f0e05190-145d-0247-0000-00007388e0bf')
api.advimport.stopAll()

Остановка обработки всех активных конфигураций импорта.

Результат выполнения: список сообщений об ошибках, полученных при остановке

Запуск импорта

api.advimport.start(advimportConfig, parameters)

Метод позволяет запустить определенную конфигурацию импорта с заполнением ее параметров запуска (gui-parameter).

Параметры метода:
- advimportConfig — идентификатор конфигурации импорта. Идентификатор импорта указывается в адресной строке карточки конфигурации:
  
  ../sd/admin/#advImportConfig:f0e05190-145d-0247-0000-00007388e0bf
- parameters —параметры запуска импорта (<gui-parameter> конфигурации импорта)
  
  Допустимые типы значения параметров:
  - STRING — используется для передачи:
    - строки для заполнения строковых параметров;
    - UUID файла источника данных для импорта (file$1234);
    - содержимого файла источника данных для импорта.
  - byte[] и InputStream — используется для передачи содержимого файла источника данных для импорта.
Результат выполнения: Запуск конфигурации импорта.

Пример 1: Запуск конфигурации импорта без параметров (f0e05190-145d-0247-0000-00007388e0bf — идентификатор конфигурации импорта, [:] — пустые параметры запуска):

api.advimport.start('f0e05190-145d-0247-0000-00007388e0bf', [:]);

Пример 2: Запуск конфигурации импорта с использованием UUID файла в качестве источника импорта и строкового параметра:

api.advimport.start('f0e05190-145d-0247-0000-00007388e0bf', [ 'fileForProcess' : 'file$1234', 'defaultValue' : 'defaultString' ]);

Пример 3: Запуск конфигурации импорта с использованием вложения письма в качестве источника импорта (byte[]):

api.advimport.start('f0e05190-145d-0247-0000-00007388e0bf', [ 'fileForProcess' : message.getAttachments()[0].getData() ]);

Из скрипта обработки почты:
Copy
```
def startImport(def message)
{
for (def attachment : message.getAttachments())
{
logger.debug("Filename is: " + attachment.getFilename() + " content type is : " + attachment.getContentType());
try {
api.advimport.start('advImportConfig:f9157637-14c7-0d65-0000-00005e6f5b10', [ 'fileForProcess' : attachment.getData() ]);
}
catch(e) {
logger.error("Error ${e.message}");
}
}
}
```

Запуск импорта без изменения метаинформации с пользовательским файлом конфигурации

api.advimport.importByXmlConfiguration(fileXmlConfiguration, objectForLogAttachUuid, parameters)

api.advimport.importByXmlConfiguration(fileXmlConfiguration, objectForLogAttachUuid, attribute, parameters)

api.advimport.importByXmlConfiguration(fileXmlConfiguration, objectForLogAttachUuid, parameters, customUuid)

Метод позволяет создать любую произвольную конфигурацию импорта, прикрепить это в виде файла и запустить импорт с параметрами.

Параметры метода:
- fileXmlConfiguration — файл конфигурации импорта (xml) или его UUID;
- objectForLogAttachUuid — UUID объекта, к которому необходимо прикрепить лог импорта;
- attribute — код атрибута файла к которому нужно прикрепить лог;
- parameters — параметры импорта (в качестве значения может передаваться String/byte[]/InputStream);
- customUuid — желаемый UUID для конфигурации импорта.

Получения информации о конфигурации импорта

api.advimport.getActiveImports()

Метод позволяет получить {@link List} uuid всех активных конфигураций импорта (активная конфигурация импорта — это конфигурация импорта/ синхронизации в статусе "started").

Метод возвращает одно значение или 0, так как очередь импорта разбирается последовательно по одному.
api.advimport.getImportInfo(uuid)

Метод позволяет получить {@link Map} с информацией о конфигурации импорта с заданным uuid, а именно время начала импорта, продолжительность импорта в секундах, количество объектов в файле, количество строк в файле, количество пойманных ошибок, количество импортированных объектов, количество измененных объектов, количество пропущенных объектов, статус импорта.

Параметр метода:
- uuid — UUID конфигурации импорта.
Метод возвращает {@link Map} с информацией о конфигурации импорта, где:
- mportStartTime — Время начала импорта;
- importDuration — Продолжительность импорта;
- itemsCount — Количество объектов для импорта;
- totalLines — Количество строк в файле импорта;
- totalErrors — Количество ошибок при импорте;
- importedObjects - Количество импортированных объектов;
- updatedObjects — Количество измененных объектов;
- skippedObjects — Количество пропущенных объектов;
- status — Статус импорта.
  
  Возможные статусы:
  - queued — Поставлен в очередь;
  - started — Начат;
  - ended — Закончен;
  - absent — Отсутствует;
  - error — Завершен с ошибкой.

api.apps Работа с контентом типа "Встроенное приложение"

api.apps.listContents(applicationCode)

Получение списка контентов, на которые выведено встроенное приложение.

Параметр метода:
- applicationCode — код встроенного приложения.
Возвращает список контентов.
api.apps.contentParameters(fqn, formType, contentUuid)

Получение параметров контента встроенного приложения.

Параметры метода:
- fqn — метакласс или тип для поиска контента. String;
- formType — тип формы на которую выведен контент. String:
  - __window__ — для карточки объекта;
  - newEntryForm — для формы добавления;
  - editForm — для формы редактирования);
- contentUuid — идентификатор контента. String.
Возвращает список контентов.

api.attrs. Работа с атрибутами

Пересчет значения атрибута, определяемого по таблице соответствий

api.attrs.recalculateRulesSettingsValue(obj, attrsCode)

Принудительный пересчет значения атрибута, определяемого по таблице соответствий, для указанного объекта (при этом объект проходит валидацию, отрабатывают действия по событиям и т.д. ).

Параметры метода:
- obj — объект или uuid объекта, для которого производится пересчет. Object;
- attrsCode — список кодов атрибутов, определяемых по таблице соответствий. String.
Пример 1:

api.attrs.recalculateRulesSettingsValue('qwe$123', ['title', 'userAttr']);

Пример 2:
```
def obj = utils.get('qwe$123')
api.attrs.recalculateRulesSettingsValue(obj, ['title', 'userAttr'])
```

Пересчет значения составного атрибута

api.attrs.recalculateCompositeAttributeValue(uuid, attrCode)

Принудительный пересчет значения составного атрибута в отдельном объекте. Объект проходит валидацию в полном объеме, срабатывают действия по событиям и т.д., как при обычном редактировании.

Параметры метода:
- uuid — уникальный идентификатор объекта, в котором будет пересчитано значение атрибута. String;
- attrCode — код составного атрибута, значение которого будет пересчитано. String.
Пример:

api.attrs.recalculateCompositeAttributeValue('ad3516$96903', 'title');

api.auth Работа с ключами авторизации

Ключ авторизации генерируется для формирования ссылок на карточку объекта (на форму редактирования) и выполнения действия через REST сервисы.

Не рекомендуется отправлять пользователю в оповещении ссылку с accessKey другого сотрудника. Ссылка в оповещении либо не содержит ключ, чтобы пользователь мог сам авторизоваться в системе, особенно если настроена сквозная авторизация, либо ключ должен быть одноразовый или с коротким сроком жизни и выписанный для текущего пользователя.

Генерация ключей авторизации

api.auth.getAccessKeyByUUID(userUUID)

Генерация ключа авторизации по UUID пользователя (ключ авторизации, не требующий наличия у сотрудника логина). Пользователь может генерировать accessKey только для себя.

Параметр метода:
- userUUID — UUID пользователя, для которого будет сгенерирован ключ авторизации. Не может быть null.
api.auth.getAccessKey(username)

Генерация ключа авторизации по имени пользователя (по умолчанию генерируется многоразовый ключ с возможностью использования в течение недели). Пользователь может генерировать accessKey только для себя.

Параметр метода:
- username — реальное имя пользователя (логин), для которого будет сгенерирован ключ авторизации.
  
  При использовании пустого значения или несуществующего имени пользователя выводится ошибка.
Примечание. Для получения значения AccessKey необходимо добавить свойство UUID:

return api.auth.getAccessKey('username').uuid

Атрибуты метода:
- api.auth.getAccessKey('username').setDisposable() — одноразовый ключ авторизации;
- api.auth.getAccessKey('username').setReusable() — многоразовый ключ авторизации;
- api.auth.getAccessKey('username').setDeadlineDays(days) — время жизни многоразового ключа в днях;
- api.auth.getAccessKey('username').setDeadlineHours(hours) — время жизни многоразового ключа в часах;
- api.auth.getAccessKey('username').setDeadlineMinutes(minutes) — время жизни многоразового ключа в минутах;
- api.auth.getAccessKey('username').setDescription('description') — описание ключа.

Работа с временными характеристиками ключей авторизации

AccessKey setDeadline(date)

Устанавливает конкретную дату, до которой ключ будет действителен.

Параметр метода:

date — дата и время.

Возвращает объект ключа авторизации.

Пример:

/*Параметры*/
def Date = new Date().parse("d/M/yyyy", "19/10/2022"); //дата, до которой ключ будет действителен
/*Установка конкретной даты, до которой ключ будет действителен */
api.auth.getAccessKey('username').setDeadline(Date);

AccessKey setDeadlineDays(days)

К сегодняшней дате добавляет указанное количество дней и устанавливает дату, до которой ключ будет действителен.

Параметр метода:
- days — количество дней. Int.
Возвращает объект ключа авторизации.

Пример:
```
/*Параметры*/
def days = 5; //количество дней
/*Установка через сколько дней истечет время жизни ключа */
api.auth.getAccessKey('username').setDeadlineDays(days);
```
AccessKey setDeadlineHours(hours)

К сегодняшней дате добавляет указанное количество часов и устанавливает дату, до которой ключ будет действителен.

Параметр метода:
- hours — количество часов. Int.
Возвращает объект ключа авторизации.

Пример:
```
/*Параметры*/
def hours = 5; //количество часов
/*Установка через сколько часов истечет время жизни ключа */
api.auth.getAccessKey('username').setDeadlineHours(hours);
```
AccessKey setDeadlineMinutes(minutes)

К сегодняшней дате добавляет указанное количество минут и устанавливает дату, до которой ключ будет действителен.

Параметр метода:
- minutes — количество минут. Int.
Возвращает объект ключа авторизации.

Пример:
```
/*Параметры*/
def minutes = 5; //количество минут
/*Установка через сколько минут истечет время жизни ключа */
api.auth.getAccessKey('username').setDeadlineMinutes(minutes);
```

Инвалидация ключей доступа

api.auth.removeAccessKeys(username)

Инвалидация всех ключей доступа указанного пользователя (имя пользователя).

Параметр метода:
- username — имя пользователя, не может быть null.
api.auth.removeAccessKeysByUUID(userUUID)

Инвалидация всех ключей доступа указанного пользователя (UUID пользователя).

Параметр метода:
- userUUID — UUID пользователя, не может быть null.

Активация / деактивация ключей доступа

api.auth.activateAccessKey(UUID)

Активация ключа авторизации по его UUID.

Параметр метода:
- UUID — уникальный идентификатор ключа доступа. String.
api.auth.deactivateAccessKey(UUID)

Деактивация ключа авторизации по его UUID.

Параметр метода:
- UUID — уникальный идентификатор ключа доступа. String.

Получение всех существующих ключей авторизации для сотрудника

api.auth.findAccessKeysByEmployeeLogin(employeeLogin)

Получение списка всех уникальных идентификаторов ключей авторизации для сотрудника с указанным логином.

Параметр метода:
- employeeLogin — логин сотрудника. String.
Возвращает:
- Коллекция UUID ключей авторизации для конкретного сотрудника.
- Пустую коллекцию, если ключи не найдены.
- FxException, если параметр employeeLogin нулевой или содержит пустое значение.
api.auth.findAccessKeysByEmployeeUUID(employeeUUID)

Получение списка всех уникальных идентификаторов ключей авторизации для сотрудника с указанным UUID.

Параметр метода:
- employeeUUID — уникальный идентификатор сотрудника. String.
Возвращает:
- Коллекция UUID ключей авторизации для конкретного сотрудника.
- Пустую коллекцию, если ключи не найдены.
- FxException, если параметр employeeUUID нулевой или содержит пустое значение.

Получение информации о существующих ключах авторизации

api.auth.getAccessKeyInfo(UUID)

Получение информации о конкретном ключе авторизации.

Параметр метода:
- UUID — уникальный идентификатор ключа авторизации. String.
Возвращает:
- Ассоциативный массив (карту): ключ — код атрибута класса AccessKey, значение — значение соответствующего атрибута.
- Пустую карту, если ключ не найден.
api.auth.getAllAccessKeysInfo(firstResult, maxResults)

Получение информации о всех существующих ключах авторизации.

Параметры метода:
- firstResult — начальная позиция результирующего списка. Int.
- maxResults — максимальное количество возвращаемых значений. Int.
Возвращает:
- Коллекцию карт: ключи — коды атрибутов класса AccessKey; значения — значения соответствующих атрибутов.
- Пустую коллекцию, если ключи не найдены.
api.auth.getEmployeeAccessKeysInfoByLogin(employeeLogin)

api.auth.getEmployeeAccessKeysInfoByLogin(employeeLogin, firstResult, maxResults)

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

Параметры метода:
- employeeLogin — логин сотрудника. String;
- firstResult — начальная позиция результирующего списка. Int;
- maxResults — максимальное количество возвращаемых значений. Int.
  
  Если не указано, то максимальное количество возвращаемых объектов по умолчанию 100.
Возвращает:
- Коллекцию карт: ключи — коды атрибутов класса AccessKey, значения — значения соответствующих атрибутов.
- Пустую коллекцию, если ключи не найдены.
- FxException, если передана пустая строка/null в качестве аргумента employeeLogin.
api.auth.getEmployeeAccessKeysInfoByUUID(employeeUUID)

api.auth.getEmployeeAccessKeysInfoByUUID(employeeUUID, firstResult, maxResults)

Получение информации обо всех существующих ключах авторизации для конкретного сотрудника по его UUID.

Параметры метода:
- employeeUUID — уникальный идентификатор сотрудника. String;
- firstResult — начальная позиция результирующего списка. Int;
- maxResults — максимальное количество возвращаемых значений. Int.
  
  Если не указано, то максимальное количество возвращаемых объектов по умолчанию 100.
Возвращает:
- Коллекцию карт: ключи — коды атрибутов класса AccessKey, значения — значения соответствующих атрибутов.
- Пустую коллекцию, если ключи не найдены.
- FxException, если передана пустая строка/null в качестве аргумента employeeUUID.

Методы отзыва мобильных JWT-токенов

Методы также инвалидируют сессию при SSO-аутентификации.

api.auth.revokeJwtToken(token)

Отзывает access и refresh JWT-токены.

Параметр метода:
- token — access-токен или refresh-токен. String.
api.auth.revokeAllJwtTokens()

Отзывает активные JWT-токены всех пользователей, кроме суперпользователей.
api.auth.revokeJwtTokensForEmployee(employee)

Отзывает активные JWT-токены любого пользователя, включая суперпользователей.

Параметр метода:
- employee — объект сотрудника, его идентификатор или логин.

api.barcode Формирование штрих-кодов

api.barcode.getBarCode(text, type, format, width, height)

Формирование штрих-кодов.

Параметры метода:
- text — строка для преобразования в штрих-код. String;
- type — тип штрих-кода. Допустимые значения: "AZTEC", "CODABAR", "CODE_39", "CODE_93", "CODE_128", "DATA_MATRIX", "EAN_8", "EAN_13", "ITF", "PDF_417", "QR_CODE", "UPC_A", "UPC_E", регистр значения не имеет. String;
- format — формат результирующего изображения. Допустимые значения: "JPG", "JPEG", "BMP", "GIF", "PNG", регистр значения не имеет. String;
- width — ширина результирующего изображения в пикселях. Int;
- height — высота результирующего изображения в пикселях. Int.
Возвращает массив байт результирующего изображения.

Пример
Copy
Консольный скрипт для генерации QR-кода
```
def text = '123';
def width = 100;
def height = 100;
def bytes = api.barcode.getBarCode(text, "QR_CODE", "PNG", width, height);
return "<img src=\"data:image/png;base64,${bytes.encodeBase64().toString()}\" width=\"${width}\" height=\"${height}\">";
```

api.cache Работа с кэшем

api.cache.create(name)

api.cache.create(name, limit)

api.cache.create(name, limit, lifetime)

Создать новый или получить уже имеющийся кэш с заданными параметрами.

Параметры метода:
- name — имя кэша. String;
- limit — максимальное количество элементов. Int;
- lifetime — время жизни элемента в кэше (в секундах) с момента добавления. Int.
Возвращает представление кэша в виде Map, отражает текущее состояние кэша и позволяет взаимодействовать с ним.

Пример:

def result = api.cache.create('test', 5, 15);

Особенности:
- Тайм-аут вытеснения будет срабатывать только после сохранения транзакции. До сохранения все объекты добавленные в кэш, включая просроченные, будут еще доступны.
- Вытеснение по максимальному размеру сработает после сохранения транзакции. До сохранения размер кэша может быть больше максимально установленного. После сохранения лишние элементы будут вытеснены.

api.calendarEvent Работа с событиями календаря в формате ICS

api.calendarEvent.create(summary, start)

Создание события.

Метод только создает файл события календаря. Чтобы воспользоваться этим событием, нужно отправить его как вложение в письме, тогда получатель сможет добавить событие в свой календарь.

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

Параметры метода:
- summary — название события. String;
- start — дата и время начала события. Date.

Методы интерфейса ICalendarEvent для работы с моделью события

ICalendarEvent setEndDateTime(end)

Устанавливает дату и время окончания события.

Параметр метода:
- end — дата и время окончания события. Date.
ICalendarEvent setDescription(description)

Устанавливает описание события.

Параметр:
- description — описание события. String.
ICalendarEvent setRecurRule(frequency, count)

ICalendarEvent setRecurRule(frequency, endRecur)

Устанавливает повторяемость события.

Параметры метода:
- frequency — частота события. String.
  - "FREQ_DAILY" — ежедневно;
  - "FREQ_WEEKLY"' — еженедельно;
  - "FREQ_MONTHLY" — ежемесячно;
  - "FREQ_YEARLY" — ежегодно.
- count — количество повторений события. Int;
- endRecur — количество повторений события. Date.
getContentAsString()

Получение события в виде строки для сохранения.

Пример 1.

Copy

/* Параметры */
String eventTitle = "Название события";
String eventDescription = "Описание события";
String fileName = "event.ics"; //имя файла с расширением
String rootUuid = "root\$801"; //UUID объекта к которому прикрепится событие
String contentType = "text/calendar"; //тип содержимого файла (mime-тип)

def s = new GregorianCalendar(2021, Calendar.APRIL, 28, 18, 0); //дата начала события
def e = new GregorianCalendar(2021, Calendar.APRIL, 28, 19, 0); //дата окончания события
def r = new GregorianCalendar(2021, Calendar.APRIL, 30, 20, 0); //дата до которой будет повторяться событие

/* Создание модели события */
def event = api.calendarEvent.create(eventTitle, s.getTime())
                    .setEndDateTime(e.getTime())
                    .setRecurRule(api.calendarEvent.FREQ_DAILY, r.getTime())
                    .setDescription(eventDescription);

/* Прикрепление файла к объекту */
def attachedEvent = api.utils.attachFile(utils.get(rootUuid), fileName, contentType, fileName, event.getContentAsString().getBytes());

Пример 2.

Copy

/* Параметры */
String eventTitle = "Название события";
String eventDescription = "Описание события";
String fileName = "event.ics"; //имя файла с расширением
String rootUuid = "root\$801"; //UUID объекта к которому прикрепится событие
String contentType = "text/calendar"; //тип содержимого файла (mime-тип)
String timeZone = "Europe/Copenhagen"; // часовой пояс в котором указвыаются даты\время события

def s = new GregorianCalendar(TimeZone.getTimeZone(timeZone));
s.set(2021, 5, 19, 18, 0, 0); //дата начала события
def e = new GregorianCalendar(TimeZone.getTimeZone(timeZone));
e.set(2021, 5, 19, 19, 0, 0); //дата окончания события
def r = new GregorianCalendar(TimeZone.getTimeZone(timeZone));
r.set(2021, 5, 21, 20, 0, 0); //дата до которой будет повторяться событие

/* Создание модели события */
def event = api.calendarEvent.create(eventTitle, s.getTime(), timeZone)
                    .setEndDateTime(e.getTime())
                    .setRecurRule(api.calendarEvent.FREQ_DAILY, r.getTime())
                    .setDescription(eventDescription);

Пример 3.

Copy

/* Параметры */
String eventTitle = "Название события";
String eventDescription = "Описание события";
String fileName = "event.ics"; //имя файла с расширением
String rootUuid = 'ou$801'; //UUID объекта к которому прикрепится событие
String contentType = "text/calendar"; //тип содержимого файла (mime-тип)
String timeZone = "Europe/Moscow"; // часовой пояс в котором указвыаются даты\время события

def s = new Date().parse("dd/MM/yyyy HH:mm XXX", "17/06/2021 17:00 +03:00")
def e = new Date().parse("dd/MM/yyyy HH:mm XXX", "17/06/2021 18:00 +03:00")
def r = new Date().parse("dd/MM/yyyy HH:mm XXX", "29/06/2021 17:00 +03:00")

/* Создание модели события */
def event = api.calendarEvent.create(eventTitle, s, timeZone)
                    .setEndDateTime(e)
                    .setRecurRule(api.calendarEvent.FREQ_DAILY, r)
                    .setDescription(eventDescription);
def attachedEvent = api.utils.attachFile(utils.get(rootUuid), fileName, contentType, fileName, event.getContentAsString().getBytes());

Методы интерфейса ICalendarEvent для корректного отображения события в письме оповещения

ICalendarEvent setOrganizerName(name)

Устанавливает имя организатора.

Для корректного отображения события в письме обязательно нужно создавать событие с использованием методов setOrganizerEmail и setOrganizerName.

Параметр метода:
- name — имя организатора. String.
ICalendarEvent setOrganizerEmail(organizerEmail)

Устанавливает email организатора.

Параметр метода:
- organizerEmail — email организатора. String.
ICalendarEvent setUID(uid)
Устанавливает UID события.

По умолчанию, заполнять UID методом setUID не нужно, поскольку это может привести к наличию одинаковых UID у разных событий. UID генерируется и присваивается событию при его создании методом create. Метод setUID нужно использовать только для переноса/отмены заданного события и в качестве аргумента передавать UID созданного раннее события, которое нужно перенести/отменить

Параметр метода:
- uid — UID события. String.
ICalendarEvent setMethod(method)

Устанавливает метод события.

По умолчанию, событие создается с методом REQUEST, поэтому метод setMethod можно использовать только для отмены уже существующего события

Параметр метода:
- method — метод события. String
  - REQUEST - запланировать событие;
  - CANCEL - отменить событие.
String getMethod()

Получить метод события.
String getUID()

Получить UID события.

Примеры:

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

Copy

/* Параметры */
String eventTitle = "Название события";
String eventDescription = "Описание события";
String timeZone = "Asia/Yekaterinburg"; // часовой пояс в котором указываются даты\время события
String organizerName = "Фамилия И.О"; // имя организатора
String organizerEmail = "test@nausd.local"; // email организатора

def s = new GregorianCalendar(2021, Calendar.NOVEMBER, 23, 17, 0); // дата начала события
def e = new GregorianCalendar(2021, Calendar.NOVEMBER, 23, 20, 0); // дата завершения события

/* Создание объекта события */
def event = api.calendarEvent.create(eventTitle, s.getTime(), timeZone)
            .setEndDateTime(e.getTime())
            .setDescription(eventDescription)
            .setOrganizerName(organizerName)
            .setOrganizerEmail(organizerEmail)

/* Прикрепление события к оповещению */
notification.addCalendarEvent(event)

Пример переноса времени события

Для того, чтобы перенести событие созданное раннее событие, нужно иметь его UID . Для его получения нужно использовать метод getUID и полученное значение сохранить в атрибут объекта-заглушки.

Скрипт переноса события отличается от скрипта создания события только тем, что нужно заполнить UID события.

Copy

/* Параметры */
String eventTitle = "Название события";
String eventDescription = "Описание события";
String timeZone = "Asia/Yekaterinburg"; // часовой пояс в котором указываются даты\время события
String organizerName = "Фамилия И.О"; // имя организатора
String organizerEmail = "test@nausd.local"; // email организатора
String eventUid = "f410df49-17d1-dcb5-0000-00001c9f634d" // UID события, которое нужно перенести

def s = new GregorianCalendar(2021, Calendar.NOVEMBER, 24, 17, 0); // перенесенная дата начала события
def e = new GregorianCalendar(2021, Calendar.NOVEMBER, 24, 20, 0); // перенесенная дата завершения события

/* Создание объекта события */
def event = api.calendarEvent.create(eventTitle, s.getTime(), timeZone)
            .setEndDateTime(e.getTime())
            .setDescription(eventDescription)
            .setOrganizerName(organizerName)
            .setOrganizerEmail(organizerEmail)
            .setUID(eventUid)

/* Прикрепление события к оповещению */
notification.addCalendarEvent(event)

Пример отмены события

Скрипт отмены события отличается от скрипта создания события тем, что нужно заполнить UID события и значение параметра METHOD строкой "CANCEL".

Copy

/* Параметры */
String eventTitle = "Название события";
String eventDescription = "Описание события";
String timeZone = "Asia/Yekaterinburg"; // часовой пояс в котором указываются даты\время события
String organizerName = "Фамилия И.О"; // имя организатора
String organizerEmail = "test@nausd.local"; // email организатора
String eventUid = "f410df49-17d1-dcb5-0000-00001c9f634d" // UID события, которое нужно отменить

def s = new GregorianCalendar(2021, Calendar.NOVEMBER, 23, 17, 0);
def e = new GregorianCalendar(2021, Calendar.NOVEMBER, 23, 20, 0);

/* Создание объекта события */
def event = api.calendarEvent.create(eventTitle, s.getTime(), timeZone)
            .setEndDateTime(e.getTime())
            .setDescription(eventDescription)
            .setOrganizerName(organizerName)
            .setOrganizerEmail(organizerEmail)
            .setMethod("CANCEL")
            .setUID(eventUid)

/* Прикрепление события к оповещению */
notification.addCalendarEvent(event)

api.collections Работа с коллекциями

api.collections.joinMaps(Map<K,V>... maps)

Объединяет ассоциативные списки (коллекции).

Возвращает ассоциативный список, в котором пары ключ-значение ассоциативного списка map1 дополняются парами ключ-значение ассоциативного списка map2. Если в ассоциативных списках map1 и map2 есть одинаковые ключи, то значение данного ключа в результате остается таким как в map1

Пример:
Copy
```
def map1 = ['key1':'value1', 'key2' : 'value2'];
def map2 = ['key1':'value3', 'key2' : 'value2'];
def map3 = ['key1':'value4', 'key3' : 'value5'];
def resultMap = api.collections.joinMaps(map1, map2, map3);
return resultMap.inspect(); //Результат: ['key1':'value1', 'key2':'value2', 'key3': 'value5']
```

api.date Работа с датами

Получение номера дня недели

api.date.getNumberOfDayOfWeek(date)

Возвращает номер дня недели в timezone сервера.
api.date.getNumberOfDayOfWeek(date, timezoneID)

Параметр метода:
- timezoneID — ID заданной timezone (например, 'Asia/Yekaterinburg')
Возвращает номер дня недели в заданной timezone.

Получение номера дня в месяце

api.date.getNumberOfDayOfMonth(date)

Возвращает номер дня в месяце в timezone сервера:
api.date.getNumberOfDayOfMonth(date, timezoneID)

Параметр метода:
- timezoneID — ID заданной timezone (например, 'Asia/Yekaterinburg')
Возвращает номер дня в месяце в заданной timezone.

Получение номера месяца

api.date.getNumberOfMonth(date)

Возвращает номер месяца в timezone сервера.
api.date.getNumberOfMonth(date, timezoneID)

Параметр метода:
- timezoneID — ID заданной timezone (например, 'Asia/Yekaterinburg')
Возвращает номер месяца в заданной timezone.

Получение номера недели в месяце

api.date.getNumberOfWeekOfMonth(date)

Возвращает номер недели в месяце в timezone сервера.
api.date.getNumberOfWeekOfMonth(date, timezoneID)

Параметр метода:
- timezoneID — ID заданной timezone (например, 'Asia/Yekaterinburg')
Возвращает номер недели в месяце в заданной timezone.

Перерасчет дат

api.date.addDays(date, amountOfDays)

Добавление дня к дате /дате-времени (отнимание дня от даты /даты-времени).

Параметры метода:
- date — дата /дата-время, к которой применяется перерасчет. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате;
- amountOfDays — количество добавляемых календарных дней (целое положительное число), количество отнимаемых календарных дней (целое отрицательное число).
Возвращает пересчитанное значение даты /даты-времени.
api.date.addMonths(date, amountOfMonths)

Добавление месяца к дате /дате-времени (отнимание месяца от даты /даты-времени).

Параметры метода:
- date — дата /дата-время, к которой применяется перерасчет. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате;
- amountOfMonths — количество добавляемых месяцев (целое положительное число), количество отнимаемых месяцев (целое отрицательное число). Int.
Возвращает пересчитанное значение даты /даты-времени. Если в полученном месяце нет указанного дня, то возвращает последний день получившегося месяца.
api.date.addYears(date, amountOfYears)

Добавление количества лет к дате /дате-времени (отнимание количества лет от даты /даты-времени.

Параметры метода:
- date — дата /дата-время, к которой применяется перерасчет. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате;
- amountOfYears — количество добавляемых лет (целое положительное число), количество отнимаемых лет (целое отрицательное число). Int.
Возвращает пересчитанное значение даты /даты-времени. Если в полученный год нет указанного дня, то возвращает последний получившийся месяц.

Ограничение значений атрибутов типа "Дата" и "Дата/время"

Примеры использования методов api.date.filter() см. Скрипт ограничения значения атрибутов типа "Дата" и "Дата/время".

api.date.filter()

Получение объекта, используемого для генерации предикатов фильтрации атрибутов типа "Дата" и "Дата/время".

Возвращает экземпляр объекта генерации предиката (IDatePredicate).

В классе IDatePredicate доступны следующие методы:
- IRestriction after(date)
  
  IRestriction after(date, useTime)
  
  Параметры метода:
  - date — дата, больше которой должно быть проверяемое значение;
  - useTime:
    - false (по умолчанию) — сформировать предикат без учета времени;
    - true — сформировать предикат учитывающий время.
  Возвращает предикат, проверяющий, что дата/время больше указанной.
- IRestriction before(date)
  
  IRestriction before(date, useTime)
  
  Параметры метода:
  - date — дата, меньше которой должно быть проверяемое значение;
  - useTime:
    - false (по умолчанию) — сформировать предикат без учета времени;
    - true — сформировать предикат учитывающий время.
  Возвращает предикат, проверяющий, что дата/время меньше указанной.
- IRestriction between(from, to)
  
  IRestriction between(from, to, useTime)
  
  Параметры метода:
  - from — дата, больше или равно которой должно быть проверяемое значение;
  - to — дата, меньше или равно которой должно быть проверяемое значение;
  - useTime:
    - false (по умолчанию) — сформировать предикат без учета времени;
    - true — сформировать предикат учитывающий время
  Возвращает предикат, проверяющий, что дата/время лежит в диапазоне между указанными.
- IRestriction dayOfWeek(int dayOfWeek)
  
  Параметр метода:
  - dayOfWeek — день недели, которому должна соответствовать проверяемая дата (1 - воскресенье... 7 - суббота)
  Возвращает предикат, проверяющий соответствие дню недели.
- IRestriction equals(date)
  
  IRestriction equals(date, useTime)
  
  Параметры метода:
  - date — дата, которой должно соответствовать проверяемое значение;
  - useTime:
    - false (по умолчанию) — сформировать предикат без учета времени;
    - true — сформировать предикат учитывающий время
  Возвращает предикат, проверяющий, что дата/время соответствует указанной.
- IRestriction in(dates)
  
  IRestriction in(dates, useTime)
  
  Параметры метода:
  - dates — даты, одной из которых должно соответствовать проверяемое значение
  - useTime:
    - false (по умолчанию) — сформировать предикат без учета времени;
    - true — сформировать предикат учитывающий время
  Возвращает предикат, проверяющий, что дата/время соответствует одной из указанных.
- IRestriction inTime(from, to)
  
  Параметры метода:
  - from — время, с которого начинается промежуток (количество мс прошедшее с 00:00:00);
  - to — время которым заканчивается промежуток (количество мс прошедшее с 00:00:00).
  Возвращает предикат, проверяющий, что дата/время соответствует временному периоду, например, с 9:00 по 17:00.
- IRestriction isNull()
  
  Возвращает предикат, проверяющий, что дата/время null.
- IRestriction isNull(date)
  
  Параметр метода:
  - date — значение, которое должно быть null.
  Возвращает предикат, проверяющий, что указанная дата/время null.
- IRestriction notNull()
  
  Возвращает предикат, проверяющий, что дата/время НЕ null.
- IRestriction notNul(date)
  
  Параметр метода:
  - date — значение, которое НЕ должно быть null.
  Возвращает предикат, проверяющий, что указанная дата/время НЕ null.
- IRestriction and(restrictions)
  
  Параметр метода:
  - restrictions — массив ограничений или список ограничений.
  Возвращает предикат, объединяющий другие по логическому "И".
- IRestriction or(restrictions)
  
  Параметр метода:
  - restrictions — массив ограничений или список ограничений.
  Возвращает предикат, объединяющий другие по логическому "ИЛИ".
- IRestriction not(restrictions)
  
  Параметр метода:
  - restrictions — предикат, значение которого будет инвертировано.
  Возвращает предикат, инвертирующий результат указанного предиката.

api.db Использование запросов к базе данных

api.db.query. HQL запросы

Результат исполнения методов api.db.query зависит от конкретной базы данных, например, может изменяться сортировка получения результатов, если правило сортировки не было явно указано в запросе.

Использование api.db.query увеличивает скорость получения данных, но такие скрипты требуют тщательного анализа и контроля при обновлении отдельных составляющих системы и версии приложения в целом.

Не рекомендуется при вызове прямых запросов к базе данных использовать команды INSERT INTO, UPDATE и DELETE. Все изменения данных в системе следует проводить только через системное API (методы utils.create, utils.edit и utils.delete). В частности работа с объектами через этот метод не учитывает права на работу с объектами.

Запросы к базе данных со сложной логикой фильтрации (язык запросов ):

Получение списка объектов.

HQL запрос:

def query = api.db.query('from T');

def objectList = query.list();
Получение всех объектов типа INC класса "Запрос" (serviceCall):

HQL запрос:

return api.db.query("SELECT count(sc.id) FROM serviceCall sc WHERE case_id ='INC'").list();

Поле case_id используется при построении HQL запросов для получения объектов определенного типа в рамках одного класса объектов. При выполнении запросов с case_id, которые обращаются к объектам двух и более классов, возникает ошибка.
Установка максимального количества возвращаемых объектов в запросе:

HQL запрос:

def query = api.db.query('from T');

query.setMaxResults(10);

def objectList = query.list();

Установка значения параметра в запросе:

HQL запрос:

def query = api.db.query('from T where id = :id');
query.set('id', 1234);
def objectList = query.list();

Установка значения параметра-коллекции в запросе:

HQL запрос:

def query = api.db.query('from T where type in :types');
def types = ['my-type', 'my-type-2', 'my-type-3'];
query.set('types', types);
def objectList = query.list();

Установка параметров в запросе с использованием набора элементов ключ-значение:

HQL запрос:

def query = api.db.query('from T where type = :type and enabled = :enabled');
def params = [type: 'my-type', enabled: true];
query.set(params);
def objectList = query.list();

Поиск элементов справочника по названию:

HQL запрос:

def QUERY = api.db.query("""
SELECT p.color
FROM impact as p
WHERE p.title.ru = 'Высокая'""");
return QUERY.list().get(0);

Получение внутренних свойств атрибута типа "Временной интервал" dtInterval. Можно получить количество миллисекунд (ms) и строковое представление единицы измерения периода (interval).

HQL запрос:
```
def ms = api.db.query('select resolutionTime.ms from serviceCall').list()[0]
def interval = api.db.query('select resolutionTime.interval from serviceCall').list()[0]
assert ms instanceof Long
assert interval instanceof String
assert interval in ['DAY', 'SECOND', 'WEEK', 'MINUTE', 'HOUR']
```
Если в настройках атрибута типа "Временной интервал" включено свойство "Запоминать выбранные единицы измерения", то получение interval недоступно.

Параметры атрибута типа "Временной интервал" можно получить скриптовыми методами через обращение к переменным контекста. Не рекомендуется обращаться к параметрам атрибута через HQL-запрос к базе данных, так как структура базы данных может меняться
Поиск объектов по атрибуту типа "Ссылка на бизнес объект" (использование в WHERE):

При использовании параметра запроса для указания значения атрибута типа "Ссылка на бизнес объект" внутри блока WHERE и передаче объекта в качестве его значения, необходимо указывать .id у атрибута внутри HQL-запроса. Если не указать, будет ошибка, что атрибут не найден: classCode$typeCode:$type$.
```
def query = api.db.query('from classCode$typeCode where sboAttr.id = :boValue')
query.set('boValue', utils.load('classCode$1234'))
return query.list()
```

api.db.isReadOnly

api.db.isReadOnly()

Идентификации инстанса SMP, на котором выполняется текущий скрипт. Метод позволяет определить в скрипте работает ли нода с RO репликой или нет, на какой ноде (front, back, report) выполняется скрипт.

Возвращает:
- true — если скрипт выполняется на инстансе SMP (отчетной ноде), который работает с read-only репликой базы данных;
- false — скрипт выполняется на back или universal нодах.

api.employee Персональные настройками сотрудника

Персональные настройки сотрудника

api.employee.getPersonalSettings(employeeUuid)

Получение персональных настроек для пользователя.

Параметр метода:
- employeeUuid — идентификатор пользователя или суперпользователя. String.
Возвращает объект с персональными настройками:
- Если у сотрудника или суперпользователя заданы персональные настройки, тогда возвращаются они.
- Если персональных настроек нет, то проверяется наличие глобальных настроек заданных в интерфейсе администратора и если они есть, то возвращаются они.
- Если глобальных настроек тоже нет, то при получении настроек будут возвращены настройки по умолчанию:
  - локаль по умолчанию = 'ru';
  - тема в операторе по умолчанию = 'system#default';
  - часовой пояс по умолчанию = null;
  - домашняя страница = null.
Методы для получения различных настроек, связанных с пользователем:
- getLocale() — получение локали;
- getTimeZone() — получение часового пояса;
- getThemeOperator() — получение кода темы в интерфейсе оператора;
- getThemeAdmin() — получение кода темы в интерфейсе администратора;
- getHomePage() — получение URL домашней страницы.
Пример 1. Работа с обычным пользователем:
```
def settings = api.employee.getPersonalSettings('employee$123') // получение объекта персональных настроек для пользователя 'employee$123'
String locale = settings.getLocale() // получение кода локали ('ru', 'en' и другие)
String timeZoneCode = settings.getTimeZone() // получение кода часового пояса ('Asia/Ekaterinburg' и другие)
String theme = settings.getThemeOperator() // получение кода темы в интерфейсе оператора ('blue', 'site' и другие)
```
Пример 2. Работа с суперпользователем:
```
def settings = api.employee.getPersonalSettings('superUser$nick') // получение объекта персональных настроек для суперпользователя 'nick'
String locale = settings.getLocale() // получение кода локали ('ru', 'en' и другие)
String timeZoneCode = settings.getTimeZone() // получение кода часового пояса ('Asia/Ekaterinburg' и другие)
String theme = settings.getThemeOperator() // получение кода темы в интерфейсе оператора ('blue', 'site' и другие)
```
api.employee.getTimeZone(employeeUuid)

Получение объекта часового пояса.

Данный метод может использоваться в том случае, если часовой пояс в настройках сотрудника является элементом справочника "Часовые пояса".

Параметр метода:
- employeeUuid — идентификатор пользователя. String.
Возвращает:
- объект часового пояса;
- null — если часовой пояс в настройках пользователя не указан или не является элементом справочника "Часовые пояса".
Методы для получения параметров часового пояса:
- timeZone.code — получение кода часового пояса;
- timeZone.title — получение названия часового пояса.
api.employee.setTimeZone(employee, timeZoneId)

Установка часового пояса для конкретного сотрудника.

Параметры метода:
- employee — объект сотрудника или его идентификатор. Object;
- timeZoneId — идентификатор часового пояса. String
Пример:

api.employee.setTimeZone('employee$123', 'Asia/Ekaterinburg')
api.employee.setTimeZoneEntireOu(employee, timeZoneAttrCode)

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

Параметры метода:
- employee — объект сотрудника или его идентификатор. Object;
- timeZoneAttrCode — код атрибута типа "Элемент справочника", в котором хранится информация о часовом поясе String.
Возвращает сообщение об успешной установке часовых поясов.

Пример.

api.employee.setTimeZoneEntireOu('ou$123', 'timeZoneAttr')
api.employee.setTimeZoneAccordingToLocation(object, timeZoneAttrCode, relatedLocationAttrCode)

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

Параметры:
- object — объект отдела или его идентификатор. Object;
- timeZoneAttrCode — код атрибута типа "Элемент справочника", в котором хранится информация о часовом поясе. String;
- relatedLocationAttrCode — код атрибута типа "Ссылка на БО", в котором хранится информация об объекте с указанным часовым поясом. String.
Возвращает сообщение об успешной установке часовых поясов.

Пример:

api.employee.setTimeZoneAccordingToLocation('ou$123', 'timeZoneAttr', 'relatedAttrWithTimeZoneAttr')
api.employee.setHomePage(employee, homePage)

Установка домашней страницы для конкретного сотрудника.

Страницей по умолчанию является часть ссылки после `#`. Метод поддерживает следующие форматы задания значения:
- Полный или частичный адрес с символом решетки (#) - 'http://example.ru/sd/operator/#uuid:ou$123' или '#uuid:ou$123' (домашней страницей станет - uuid:ou$123).
- Ожидаемая страница по умолчанию (часть после #) - 'uuid:ou$123'.
Параметры метода:
- employee — объект отдела или его идентификатор. Object;
- homePage — домашняя страница. String;
Пример:

api.employee.setHomePage('employee$123', 'uuid:ou$123')
api.employee.setLocale(employee, locale)

Установка локали для конкретного сотрудника.

Параметры метода:
- employee — объект отдела или его идентификатор. Object;
- locale — код локали. String;
Пример:

api.employee.setLocale(subject, 'en')
api.employee.setTheme(employee, themeCode)

Установка темы для всех интерфейсов для конкретного сотрудника.

Параметры метода:
- employee — объект отдела или его идентификатор. Object;
- themeCode — код темы. String;
  
  Коды тем: 'blue' (основная), 'site' (фирменная), 'scheme1' (сине-фиолетовая), 'scheme2' (сине-оранжевая), 'scheme3' (сиреневая), 'scheme4' (оранжевая), 'scheme5' (светлая), 'scheme6' (бронзовая), 'system#default' (тема по умолчанию).
Пример:

api.employee.setTheme(subject, 'scheme1')
api.employee.setTheme(employee, themeCode, module)

Установка темы для конкретного интерфейса для конкретного сотрудника.

Параметры метода:
- employee — объект отдела или его идентификатор. Object;
- themeCode — код темы. String;
  
  Коды тем: 'blue' (основная), 'site' (фирменная), 'scheme1' (сине-фиолетовая), 'scheme2' (сине-оранжевая), 'scheme3' (сиреневая), 'scheme4' (оранжевая), 'scheme5' (светлая), 'scheme6' (бронзовая), 'system#default' (тема по умолчанию).
- module — модуль ('admin' - для технолога, 'operator' - для оператора). String;
Пример:

api.employee.setTheme(subject, 'scheme2', 'admin')

Поиск активных пользователей

api.employee.getActiveEmployees()

Получение активных пользователей (исключая суперпользователей).
api.employee.getActiveEmployeesUUIDs()

Получение идентификаторов активных пользователей (исключая суперпользователей).

Возвращает UUID'ы активных пользователей.
api.employee.getLicensesUsage()

Получение информации об использовании лицензий. Метод для поиска числа активных пользователей, отсортированных по лицензиям, в том числе нелицензированных пользователей.

Возвращает ассоциативный список: ключ — код лицензии, значение — число активных пользователей.

api.encryption Шифрование и дешифрование

Шифрование паролей включается и отключается в файле dbaccess.properties, см. Безопасность.

api.encryption.encryptAllPasswords()

Зашифровывает и пересохраняет все пароли, задаваемые через интерфейс администратора.

Работает только в случае, если шифрование паролей в данный момент включено. Иначе в лог будет выведено сообщение об ошибке
api.encryption.encryptString(string)

Шифрование произвольной строки.

Параметр метода:
- string — строка, которую нужно зашифровать.
Возвращает зашифрованную строку.
api.encryption.decryptAllPasswords()

Расшифровывает и пересохраняет все пароли, задаваемые через интерфейс администратора.

Работает только в случае, если шифрование паролей в данный момент отключено. В противном случае в лог будет выведено сообщение об ошибке

api.fileStorage Работа с файловыми хранилищами

Подробнее о работе с файловыми хранилищами см. Файловые хранилища.

Сжатие файлов в хранилищах и перемещение файлов между ними

api.fileStorage.compressAll(storageCode)

Сжатие всех файлов, ранее добавленных в указанное хранилище.

Параметр метода:
- storageCode — код файлового хранилища или null, если файлы хранятся в базе данных.
api.fileStorage.moveAll(from, to)

Перемещение всех ранее добавленных файлов из одного файлового хранилища в другое.

Не перемещаются файлы настройки, поврежденные файлы (если они есть в хранилище).

Параметры метода:
- from — код файлового хранилища, из которого переносятся файлы, или null, если файлы хранились в базе данных;
- to — код файлового хранилища, в которое перемещаются файлы, или null, если файлы переносятся в базу данных.
api.fileStorage.move(fileUuid, from, to)

api.fileStorage.move(fileUuid, to)

Перемещение одного файла из одного файлового хранилища в другое.

Параметры метода:
- fileUuid — уникальный идентификатор файла, uuid;
- from — код файлового хранилища, из которого переносится файл, или null, если файл хранился в базе данных;
- to — код файлового хранилища, в которое перемещается файл, или null, если файл переносится в базу данных.

Разделение и слияние файлов

api.fileStorage.expand()

Разделение файлов (операция по присваиванию контента и хеша каждому файлу, вместо ссылки на один и тот же хеш).

Метод вызывается только при отключенном слиянии файлов (параметр deduplication в конфигурации файловых хранилищ).
api.fileStorage.shrink()

Слияние файлов (операция по присваиванию ссылки на один и тот же хеш одинаковым файлам с последующим удалением дубликатов).

Чтение настроек файловых хранилищ из конфигурационного файла

api.fileStorage.reload()

Чтение настроек файловых хранилищ из конфигурационного файла.

Создание копии или временного файла

api.fileStorage.copyFile(uuid)

Копирование файла с заданным UUID.

Копируются параметры файла: название, описание, контент, mime-type, автор, размер файла, источник файла, атрибут связи файла с хранилищем (если хранилище указано), хранилище, признак сжат или не сжат.

Не копируются параметры файла: shareAlias, cacheControl.

Метод не копирует системные файлы, временные файлы, файлы-изображения из атрибутов типа "Текст RTF".

Параметр метода:
- uuid — uuid копируемого файла
Возвращает UUID скопированного файла
api.fileStorage.createTempFileFromOrigin(file)

Создание временного файла на основе переданного файла.

Копируются: название, описание, контент, mime-type, автор, размер файла, источник файла, связь файла (атрибут) если указано, хранилище, признак сжат /не сжат. Источник файла вычисляется произвольным образом.

Параметр метода:
- file — файл, на основе которого будет создан временный файл. Object
Возвращает ISDtObject временного файла.

api.filters Работа со скриптами фильтрации

api.filters позволяет обращаться напрямую к СУБД во время генерации элементов фильтруемого списка.

Не рекомендуется использовать методы группы api.filters в скриптах фильтрации для ссылочных атрибутов.

Равенство свойств определенным значениям

api.filters.eq(objs)

api.filters.eq(objs, attrs)

Фильтрация объектов по нескольким атрибутам.

Пример:
```
def author = ...
def service = ..
api.filters.eq('serviceCall', ["author" : author, "service" : service])
```

Получение объекта фильтра

api.filters.none()

Фильтр, удаляющий все результаты из списка:
api.filters.not(filter)

Фильтр-отрицание.

Параметр метода:
- filter — заданный фильтр. IFilter
api.filters.all()

Используется отдельно от других фильтров!

Скрипт должен возвращать или этот фильтр, или какие-то другие. Без И, ИЛИ, НЕ .

Возвращает объект фильтра для контроля прав в списках, означающий, что фильтрацию применять не надо
api.filters.and(filters)

Объединение нескольких условий фильтрации по И.

Параметр метода:
- filters — набор фильтров. IFilter
api.filters.or(filters)

Объединение нескольких условий фильтрации по ИЛИ.

Параметр метода:
- filters — набор фильтров. IFilter
api.filters.except( object)

Получение всех объектов, кроме заданного.

Параметр метода:
- object — объект, который надо исключить из результата. IUUIDIdentifiable
api.filters.except(uuid)

Получение всех объектов, кроме объекта с заданным uuid.

Параметр метода:
- uuid — uuid объекта, который надо исключить из результата. String
api.filters.attrContains(name, value, ignoreCase, revert)

Получение объектов, значение указанного атрибута которых содержит значение фильтра (или наоборот, значение фильтра содержит значение атрибута).

Параметры метода:
- name — код атрибута. String;
- value — значение для сравнения. Object;
- ignoreCase — признак сравнения строк без учета регистра. Boolean;
- revert — признак инвертирования сравнения (атрибут содержит заданное значение или наоборот). Boolean.
api.filters.attrsInequality(attrCode1, op, attrCode2)

Получение объектов, значения двух указанных атрибутов которых находятся в заданном соотношении.

Параметры метода:
- attrCode1 — код первого атрибута. String;
- op — символ отношения ("<", "<=", ">", ">="). String;
- attrCode2 — код второго атрибута. String
api.filters.inequality(attrCode, sign, value)

Получение объектов, значение атрибута которых удовлетворяет заданному неравенству.

Параметры метода:
- attrCode — код атрибута. String;
- sign — код неравенства ("<", "<=", ">", ">="). String;
- value — значение для сравнения. Object.
api.filters.attrValueEq(attrCode, value)

Получение объектов, значение указанного атрибута которых равно значению фильтра:

Параметры метода:
- attrCode — код атрибута. String
- value — значение. Object
api.filters.attrValueIn(attrCode, value, not)

Получение объектов, значение указанного атрибута которых содержится в заданной коллекции:

Параметры метода:
- attrCode — код атрибута. String
- value — коллекция значений. Collection<Object>
- not = true (значение атрибута не должно содержаться в заданной коллекции). Boolean
api.filters.hasAnyFile(attributeFqn)

Получение объектов, у которых есть хотя бы один файл.

Параметр метода:
- attributeFqn — идентификатор связи файла и объекта. IAttributeFqn
api.filters.inAttributesChainOfObject(attrChain)

Получение объектов, которые содержатся в значении указанной цепочки атрибутов заданного объекта:

Параметр метода:
- attrChain — цепочка атрибутов, последовательных ссылок с одного метакласса на другой. List<IAttrReference>
Возвращает объект фильтра типа InAttributesChainFilter

см. Методы API
api.filters.inAttrValueOf(objectId, attribute, not)

Получение объектов, которые содержатся в значении указанного атрибута заданного объекта (или наоборот, не содержатся).

Параметры метода:
- objectId — uuid объекта. String
- attribute — код атрибута объекта. String
- not:
  - true — объекты содержатся в значении указанного атрибута заданного объекта;
  - false — объекты не содержатся в значении указанного атрибута заданного объекта.
api.filters.inCases(caseIds)

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

Параметр метода:
- caseIds — коллекция кодов типов объектов. Collection<String>
api.filters.stateTitleEq(fqns, stateTitle)

Получение объектов заданных типов, название статуса которых равно заданному.

Параметры метода:
- fqns — набор типов объектов. Iterable<IClassFqn>
- stateTitle — название статуса. String
api.filters.stateTitleLike(fqns, stateTitle)

Получение объектов заданных типов, название статуса которых содержит заданную подстроку.

Параметры метода:
- fqns — набор типов объектов. Iterable<IClassFqn>
- stateTitle — название статуса. String
api.filters.inDirectAndBackLink(objectId, attrCode, showRelatedWithNested, linkAttrFqn, hierarchyAttrFqn)

Получение объектов, которые находятся с двух сторон связи.

Параметры метода:
- objectId — uuid объекта. String
- attrCode — код ссылочного атрибута на бизнес-объект того же класса. String
- showRelatedWithNested — true (отображать связанные со вложенными). Boolean
- linkAttrFqn — fqn атрибута, после которого строится иерархия. Имеет смысл только когда showRelatedWithNested = true. Если linkAttrFqn.getCode == "currentObject", то иерархия строится от исходного объекта. IAttributeFqn
- hierarchyAttrFqn — код атрибута, по которому строится иерархия. Имеет смысл только когда showRelatedWithNested = true. String
api.filters.children()

Получение объектов, которые вложены в объект, определяемый некоторым условием.

Возвращает объект фильтра типа ParentFilter, см. Методы API
api.filters.aggregateAttrTitleNotContains(name, value, ignoreCase)

Получение объектов, у которых значение агрегирующего атрибута не содержит объект с заданным названием.

Параметры метода:
- name — код агрегирующего атрибута. String
- value — значение атрибута. String
- ignoreCase — признак сравнения строк без учета регистра. Boolean
api.filters.stringAttrValueEq(attrCode, value, ignoreCase)

Получение объектов, у которых значение указанного атрибута типа "Строка" или "Текст" равно значению фильтра.

Параметры метода:
- attrCode — код атрибута. String
- value — значение. Object
- ignoreCase — признак сравнения строк без учета регистра. Boolean
api.filters.backLinkAttrContains(directLinkAttrCode, objectId, dtObjects, contains)

Получение объектов, у которых значение атрибута типа "Обратная ссылка" содержит хотя бы один из заданных объектов (или не содержит ни одного).

Параметры метода:
- directLinkAttrCode — код атрибута прямой ссылки. String
- objectId — идентификатор метакласса объекта, на который ссылается обратная ссылка. String
- dtObjects — набор объектов, на которые должна ссылаться обратная ссылка (хотя бы на один). ArrayList<String>
- contains = true (в значении обратной ссылки должен быть хотя бы один объект из dtObject)
- contains = false (не должно быть ни одного)
api.filters.backLinkAttrTitleContains(directLinkAttrCode, objectId, titleValue, contains)

Получение объектов, у которых значение атрибута типа "Обратная ссылка" содержит хотя бы один объект с заданным наименованием (или не содержит ни одного).

Параметры метода:
- directLinkAttrCode — код атрибута прямой ссылки. String
- objectId — идентификатор метакласса объекта, на который ссылается обратная ссылка. String
- titleValue — наименование объектов, на которые должна ссылаться обратная ссылка (поиск по подстроке). String
- contains = true (в значении обратной ссылки должен быть хотя бы один объект с названием titleValue)
- contains =false (не должно быть ни одного)
api.filters.dateAttrInInterval(attrCode, sdate, edate, compareAsLong)

Получение объектов, у которых значение указанного атрибута которых типа "Дата" или "Дата/время" лежит в заданном интервале.

Параметры метода:
- attrCode — код атрибута. String;
- sdate — начальная дата. Date;
- edate — конечная дата. Date;
- compareAsLong — признак сравнивать даты как даты или преобразовывать в миллисекунды. Boolean
api.filters.lastNDays(attrCode, days)

Получение объектов, у которых значение атрибута типа "Дата" или "Дата/время" отстоит от текущей даты не более чем на заданное количество дней.

Параметры метода:
- attrCode — код атрибута. String
- days — количество дней, диапазон интервала для сравнения даты. Long
api.filters.fqnAttrIsDescendantOf(attrCode, ancestorClassFqn, includeAncestor)

Получение объектов, у которых значение указанного атрибута типа "Тип объекта" является потомком заданного ClassFqn.

Параметры метода:
- attrCode — код атрибута. String;
- ancestorClassFqn — FQN метакласса-родителя. IClassFqn;
- includeAncestor — признак, надо ли учитывать сам ancestorClassFqn в условии. Boolean.
api.filters.inDisconnectingStates(masterSlaveFqn)

Получение объектов класса "Запрос" (serviceCall), которые находятся в статусе разрыва связи.

Параметр метода:
- masterSlaveFqn — fqn ведущего (ведомого) запроса. IClassFqn
Возвращает офильтра типа InAttributesChainFilter, см. Методы API
api.filters.searchableAttributesContainString(searchString, fqn)

Получение объектов определенного метакласса, значения атрибутов, разрешенных для поиска, которых содержат в себе заданную строку (используется в контенте Массовые запросы).

Параметры метода:
- searchString — строка для поиска. String
- fqn — fqn типа или класса. IClassFqn

Методы создаваемого объекта фильтра ParentFilter

Методы создаваемого объекта фильтра ParentFilter. Каждый из них возвращает ссылку на этот же объект, что позволяет вызывать их в "цепочке":
- filter.setChildrenParentEq(String childrenFqn, String parentUuid)
  
  Задает условие, что дочерние объекты типа childrenFqn вложены в родительский объект с parentUuid (классический вариант использования фильтра).
- filter.setChildren(String childrenFqn, IObjectFilter... childrenFilters)
  
  Задает условие, что дочерние объекты типа childrenFqn задаются набором фильтров childrenFilters, объединяемыми по И (например, когда дочерние объекты должны быть вложены в родительский + еще что-нибудь).
- filter.setNestedInNested()
  
  Устанавливает признак выборки вложенных во вложенные.
- filter.setParents(String parentsFqn, IObjectFilter... parentFilters)
  
  Дополнительное ограничение, накладываемое на родительские объекты при выборке вложенных во вложенные. Например, ограничение на типы метаклассов родительских объектов.
- filter.setParentUuid(String parentsFqn, String parentUuid)
  
  Условие, что родительский объект — это бизнес-объект типа parentsFqn с uuid parentUuid при выборке вложенных во вложенные.
Если nestedInNested = false, то при работе фильтра учитываются только фильтры на дочерние объекты. Если nestedInNested = true, то появляется дополнительный слой родительских объектов.

Пример 1. Найти всех сотрудников, вложенных в отдел с uuid = UUID:

return api.filters.children().setParents('ou').setChildrenParentEq('employee', UUID);

Пример 2. Найти всех сотрудников, вложенных во вложенные в отдел с uuid = UUID:

return api.filters.children().setParentUuid('ou', UUID).setChildren('employee').setNestedInNested();

Пример 3. Найти все отделы, вложенные во вложенные в отделы, где сотрудник с uuid = UUID является руководителем:

return api.filters.children().setParents('ou', api.filters.attrValueEq('head', UUID)).setChildren('employee').setNestedInNested();

Методы создаваемого объекта фильтра InAttributeChainFilter

Методы создаваемого объекта фильтра InAttributeChainFilter. Каждый из них возвращает ссылку на этот же объект, что позволяет вызывать их в "цепочке":
- filter.setEqUuid(String uuid)
  
  Накладывает на конец или начало цепочки фильтр по uuid (классический вариант использования фильтра).
- filter.setEndOfChainFilters(IObjectFilter... filters)
  
  Накладывает на конец цепочки набор заданных фильтров.
- filter.setStartOfChainFilters(IObjectFilter... filters)
  
  Накладывает на начало цепочки набор заданных фильтров.
- filter.setRelationWithNested(IAttributeFqn linkAttrFqn, String hierarchyAttrFqn)
  
  Устанавливает режим выборки связанных со вложенными:
  - linkAttrFqn FQN атрибута, после которого строится иерархия. Если linkAttrFqn.getCode == "currentObject", то иерархия строится от исходного объекта
  - hierarchyAttrFqn код атрибута, по которому строится иерархия.
Пример 1. Вывести объекты, в атрибуте 'attr' которых лежит текущий сотрудник:

return api.filters.attrValueEq('attr', user)

Пример 2. Вывести объекты типа 'objType', привязанные к услугам через атрибут 'services', получателем которых является отдел текущего пользователя:
```
def attrChain = [
   api.types.newAttrReference('objType', 'services'),
   api.types.newAttrReference('slmService', 'agreements'),
   api.types.newAttrReference('agreement', 'recipientsOU')];
return api.filters.inAttributesChainAreObjects(attrChain).setEqUuid(user.parent.UUID);
```
Пример 3. Вывести услуги, связанные с соглашениями, поставщиком которых является текущий сотрудник или команда текущего сотрудника (если поле Поставщик-сотрудник пусто):
```
def attrChainTeamMembers = [
    api.types.newAttrReference('slmService', 'agreements'),
    api.types.newAttrReference('agreement', 'supplierTeam'),
    api.types.newAttrReference('team', 'members')];
def teamFilter = api.filters.inAttributesChainAreObjects(attrChainTeamMembers).setEqUuid(user.UUID);
def attrChainEmps = [
    api.types.newAttrReference('slmService', 'agreements'),
    api.types.newAttrReference('agreement', 'supplierEmployee')];
def empFilter = api.filters.inAttributesChainAreObjects(attrChainEmps).setEqUuid(user.UUID);
def noEmpFilter = api.filters.inAttributesChainAreObjects(attrChainEmps).setEqUuid(null);
return api.filters.or(empFilter, api.filters.and(noEmpFilter, teamFilter));
```

api.fts Полнотекстовый поиск

api.fts.simpleSearch(term, mode, limit)

Быстрый поиск.

Параметры метода:
- term — строка поиска. String
- mode — тип поиска: "active" (неархивные), "removed" (архивные), "all" (все). String
- limit — максимальное число найденных объектов. Int.
Возвращает коллекцию uuid. В результаты поиска не попадают объекты, найденные по атрибуту, поиск по которому настроен только для нелицензированных сотрудников.
api.fts.extendedSearch(fqn, terms, mode, limit)

Расширенный поиск.

Параметры метода:
- fqn — fqn метакласса. String
- terms — ассоциативный список значений атрибута <Код атрибута : Значение атрибута>
- mode — тип поиска: "active" (неархивные), "removed" (архивные), "all" (все). String
- limit — максимальное число найденных объектов. Int.
Возвращает коллекцию uuid. В результаты поиска не попадают объекты, найденные по атрибуту, поиск по которому настроен только для нелицензированных сотрудников.

api.http Формирование запросов к JSON сервисам

api.http.postJSON(url, data)

api.http.postJSON(url, data, headers)

JSON-запрос к внешнему сервису методом HTTP (POST).

Метод ожидает ответ в формате JSON от внешнего сервиса. Максимальное время ожидания ответа от ресурса — 5 сек. Ожидаемая кодировка содержимого — UTF-8.

Параметры:
- url — адрес ресурса. URL должен быть в URL-закодированном виде;
- data — ассоциативный список параметров запроса, которые передаются в теле запроса, преобразуясь в JSON перед отправкой. Допускаются параметры типов: String, Integer (Int), Float, Double, Boolean;
- headers — заголовки запроса (Map<String, String>), если заголовков нет, то null.
Возвращает:
- Ассоциативный список содержащий JSON-данные ответа сервиса.
- Если сервер ответил строкой {'test':'done'}, то метод вернет ассоциативный список следующего содержания ['test':'done'].
- Если сервер ответил строкой [{"test":"done"}], то метод вернет ассоциативный список следующего содержания [0:['test':'done']].
Пример 1. В теле запроса будет передана строка {key:value}:

api.http.postJSON('http://ya.ru', ['key':'value'])

Пример 2. В теле запроса будет передана строка {key:value}. В заголовке запроса будет передана строка {key:value}:

api.http.postJSON('http://ya.ru', ['key':'value'], ['key': "value])
api.http.putJSON(url, data, headers)

JSON-запрос к внешнему сервису, методом HTTP (PUT).

Метод ожидает ответ в формате JSON от внешнего сервиса. Максимальное время ожидания ответа от ресурса — 5 сек. Ожидаемая кодировка содержимого — UTF-8.

Параметры:
- url — адрес ресурса. URL должен быть в URL-закодированном виде;
- data — ассоциативный список параметров запроса, которые передаются в теле запроса, преобразуясь в JSON перед отправкой. Допускаются параметры типов: String, Integer, Float, Double, Boolean;
- headers — ассоциативный список заголовков запроса (Map<String, String>), если заголовков нет, то null.
Возвращает:
- Ассоциативный список содержащий JSON-данные ответа сервиса.
- Если сервер ответил строкой {'test':'done'}, то метод вернет ассоциативный список следующего содержания ['test':'done'].
- Если сервер ответил строкой [{"test":"done"}], то метод вернет ассоциативный список следующего содержания [0:['test':'done']].
Пример. В теле запроса будет передана строка {key:value}:

api.http.putJSON('http://ya.ru', ['key':'value'], null)
api.http.getJSON(url)

api.http.getJSON(url, headers)

Запрос к внешнему сервису, методом HTTP (GET).

Метод ожидает ответ в формате JSON от внешнего сервиса. Максимальное время ожидания ответа от ресурса — 5 сек. Ожидаемая кодировка содержимого — UTF-8.

Параметры:
- url — адрес ресурса. URL должен быть в URL-закодированном виде;
- headers — заголовки запроса (Map<String, String>), если заголовков нет, то null.
Возвращает:
- Ассоциативный список содержащий JSON-данные ответа сервиса.
- Если сервер ответил строкой {'test':'done'}, то метод вернет ассоциативный список следующего содержания ['test':'done'].
- Если сервер ответил строкой [{"test":"done"}], то метод вернет ассоциативный список следующего содержания [0:['test':'done']].
Пример:

api.http.getJSON('http://ip.jsontest.com')
api.http.patchJSON(url, data, headers)

Запрос к внешнему сервису, методом HTTP (PATCH).

Параметры:
- url — адрес ресурса. URL должен быть в URL-закодированном виде;
- data — ассоциативный список параметров запроса, которые передаются в теле запроса, преобразуясь в JSON перед отправкой. Допускаются параметры типов: String, Integer, Float, Double, Boolean;
- headers — заголовки запроса (Map<String, String>), если заголовков нет, то null.
Возвращает:
- Ассоциативный список содержащий JSON-данные ответа сервиса.
- Если сервер ответил строкой {'test':'done'}, то метод вернет ассоциативный список следующего содержания ['test':'done'].
- Если сервер ответил строкой [{"test":"done"}], то метод вернет ассоциативный список следующего содержания [0:['test':'done']].
Пример. В заголовке запроса будет передана строка {key:value}. В заголовке запроса будет передана строка {key:value}:

api.http.patchJSON('http://ip.jsontest.com', ['key': "value], ['key': "value])
api.http.deleteJSON(url, headers)

Запрос к внешнему сервису, методом HTTP (DELETE).

Параметры:
- url — адрес ресурса. URL должен быть в URL-закодированном виде;
- headers — заголовки запроса (Map<String, String>), если заголовков нет, то null.
Возвращает:
- Ассоциативный список содержащий JSON-данные ответа сервиса.
- Если сервер ответил строкой {'test':'done'}, то метод вернет ассоциативный список следующего содержания ['test':'done'].
- Если сервер ответил строкой [{"test":"done"}], то метод вернет ассоциативный список следующего содержания [0:['test':'done']].
Пример. В заголовке запроса будет передана строка {key:value}:

api.http.deleteJSON('http://ip.jsontest.com', ['key': "value], ['key': "value])
api.http.createHttpBuilderClient(url)

Создает HttpBuilder с учетом доверенных сертификатов из локального хранилища и из cacerts.

Параметр:
- url — адрес ресурса. URL должен быть в URL-закодированном виде.
Возвращает HttpBuilder для работы с http сервером.

Пример:
Copy
```
def httpClient = api.http.createHttpBuilderClient("https://vc.sd.naumen.ru/");
httpClient.get(
contentType : '*/*'
)
```

api.keyValue Работа с хранилищем пар "ключ-значение"

api.keyValue.put(namespace, key, value)

Сохранение или изменение значения по ключу в указанном пространстве значений.

Параметры метода:
- namespace — пространство значений. String;
- key — ключ. String;
- value — значение. String
Возвращаемое значение:
- true — успех сохранения /обновления;
- false — провал сохранения /обновления
api.keyValue.get(namespace, key)

Получение значения по ключу из пространства значений.

Параметры метода:
- namespace — пространство значений. String;
- key — ключ. String
Возвращаемое значение:
- строковое значение;
- null (если по ключу ничего не найдено)
api.keyValue.delete(namespace, key)

Удаление значения по ключу из пространства значений.

Параметры метода:
- namespace — пространство значений. String;
- key — ключ . String
Возвращаемое значение:
- true — успех удаления
- false — провал удаления
api.keyValue.find(namespace, keyPart, predicate)

Поиск всех пар "ключ-значение" в указанном пространстве значений, содержащие keyPart подстрокой ключа. Выборка из хранилища выполняется последовательно по N объектов за один запрос до тех пор, пока есть подходящие значения.

* Число объектов N настраивается в конфигурационном файле dbaccess.properties, по умолчанию 1000

Параметры метода:
- namespace — пространство значений. String;
- keyPart — ключ. String;
- predicate — предикат вида (key, value) → boolean, который фильтрует значения
Возвращаемое значение:
- ассоциативный список найденных пар значений;
- пустой список (если ничего не найдено)

api.keystore Работа с сертификатами

api.keystore.importCertificate(alias, pem)

Добавляет сертификат в локальный KeyStore.

Параметры метода:
- alias — псевдоним сертификата в KeyStore. String;
- pem — строковое представление сертификата в PEM формате. String
Пример:

api.keystore.importCertificate("hello", str)
api.keystore.getCertificate(alias)

Получение сертификата из локального KeyStore.

Параметр метода:
- alias — псевдоним сертификата в KeyStore. String;
Возвращает найденный сертификат.

Пример:

def cert = api.keystore.getCertificate("hello")
cert.getValidUntil()

Возвращает срок действия сертификата.
api.keystore.getAllCertificates()

Получение всех сертификатов в системе (из cacert и локального KeyStore).

Возвращает список найденных сертификатов.
api.keystore.deleteCertificate(alias)

Удаление сертификата из локального KeyStore.

Параметр метода:
- alias — псевдоним сертификата в KeyStore. String;

Интерфейс IX509Certificate

/**

* @return Имя субъекта

IX500PrincipalName getSubjectX500Principal() throws IOException;

/**

* @return Имя издателя

IX500PrincipalName getIssuerX500Principal() throws IOException;

/**

* @return Серийный номер

String getSerialNumber();

/**

* @return Дата выдачи

Date getValidFrom();

/**

* @return Срок действия

Date getValidUntil();

/**

* @return PEM открытого ключа субъекта

String getPublicKey();

/**

* @return Алгоритм подписи сертификата

String getSignatureAlgorithm();

Интерфейс IX500PrincipalName

/**

* @return Страна (C)

String getCountry();

/**

* @return Организация (O)

String getOrganization();

/**

* @return Подразделение (OU)

String getOrganizationalUnit();

/**

* @return Общее имя (CN)

String getCommonName();

/**

* @return Город (L)

String getLocality();

/**

* @return Регион (ST)

String getState();

api.ldap Работа с LDAP

Методы для работы с LDAP можно использовать:

в действиях по событиям:
- Скрипт действия по событию
- Скрипт условия действия по событию
в консоли, см.Скрипты, выполняемые в консоли;
в задаче планировщика, см.Скрипт задачи планировщика.

Подробнее о работе с LDAP см. Синхронизация с LDAP

api.ldap.open(url, user, passwd)

Установление соединения с сервером LDAP.

def ctx = api.ldap.open("ldap://localhost:389/", "cn=admin,dc=localhost", "123")
ctx.setSkipCertVerification(true)

Выключение проверки сертификатов (если используется ldaps и серверный сертификат самоподписанный).

ctx.create(dn, objectClass, attributes)

Создание записи в LDAP.

ctx.create("cn=" + subject.lastName + ",ou=test,dc=localhost",
['inetOrgPerson', 'top' ],
['givenName' : subject.firstName,
'sn' : subject.lastName ,
'cn' : subject.lastName ]);

ctx.edit(dn, attributes)

Редактирование записи в LDAP.

ctx.edit("cn=" + subject.lastName + ",ou=test,dc=localhost", [ 'givenName' : subject.firstName ])
ctx.delete(dn)

Удаление записи в LDAP.

ctx.delete("cn=" + oldSubject.lastName + ",ou=test,dc=localhost");
ctx.rename(oldDn, newDn)

Переименование записи в LDAP.
ctx.search(baseDn, search)

ctx.search(baseDn, search, attributesToReturn)

ctx.search(baseDn, search, attributesToReturn, attrValueDelimiter)

Поиск записи в LDAP. Поиск осуществляется только на уровне указанной директории.

Параметры:
- baseDn — базовая директория, ветка от которой начинается поиск данных. Важен корректный порядок OU!. String.
  
  Пример: 'CN=Users,DC=nau,DC=local'.
- search — карта параметров для поиска. Map<String, Object>.
  
  Пример: ['title' : 'название'].
- attributesToReturn — коллекция названий атрибутов, которые необходимо вернуть. @Nullable Iterable<String>.
  
  Пример: ['title', 'parent', 'number']
- attrValueDelimiter — разделитель значений атрибута, если значение не одно. По умолчанию "; ". String.
  
  Пример: '', ''.
Возвращает коллекцию объектов, со всеми атрибутами, если не было указанно конкретных атрибутов в attributesToReturn.

Пример. Установить соединение с ldap. Найти указанную группу и получить значение атрибута member:

def conn = api.ldap.open('ldap://localhost:389','ivanov@nau.local','123qwery');

def props = [:];

props.distinguishedName = 'CN=amgroup,CN=Users,DC=nau,DC=local';

def attrs = ['member'];

conn.search('CN=Users,DC=nau,DC=local', props, attrs, '#');
ctx.search(baseDn, search)

ctx.search(baseDn, search, attributesToReturn)

ctx.search(baseDn, search, attrValueDelimiter)

Поиск записи в LDAP. Поиск осуществляется рекурсивно.

Параметры:
- baseDn — базовая директория, ветка от которой начинается поиск данных. Важен корректный порядок OU!. String.
  
  Пример: 'CN=Users,DC=nau,DC=local'.
- search — строка для фильтрации. String.
  
  Пример: "(title=${'название'})".
- attributesToReturn — коллекция названий атрибутов, которые необходимо вернуть. @Nullable Iterable<String>.
  
  Пример: ['title', 'parent', 'number']
- attrValueDelimiter — разделитель значений атрибута, если значение не одно. По умолчанию "; ". String.
  
  Пример: '', ''.
Возвращает коллекцию объектов, со всеми атрибутами, если не было указанно конкретных атрибутов в attributesToReturn.

Пример. Скрипт модифицирует соответствующую запись о сотруднике в LDAP, или создает новую, если такой записи нет.

Copy

def ctx = api.ldap.open("ldap://localhost:389/", "cn=admin,dc=localhost", "123");
def r = ctx.search("ou=test,dc=localhost", ['cn' : subject.lastName]);
if (r.size() == 0) {
ctx.create("cn=" + subject.lastName + ",ou=test,dc=localhost",
[ 'inetOrgPerson', 'top' ],
[ 'givenName' : subject.firstName,
'sn' : subject.lastName ,
'cn' : subject.lastName ]);
} else {
ctx.edit("cn=" + subject.lastName + ",ou=test,dc=localhost",
[ 'givenName' : subject.firstName ]);
}

api.locale Работа с текущей локализацией

api.locale.call (object, callable)

Метод для выполнения задачи с предварительной установкой переданной локали в случае необходимости.

Параметры метода:
- object
  
  Возможные значения:
  - Объект пользователя (employee), идентификатор пользователя.
    
    Если первым аргументом передается пользователь (employee), то перед выполнением задачи будет установлена локаль, полученная из персональных настроек пользователя, если она отличается от текущей установленной, а после выполнения задачи будет возвращено первоначальное значение локали.
  - Строка с локалью.
    
    Если первым аргументом передается строка с локалью ("ru", "en" или иная локаль поддерживаемая платформой), то перед выполнением переданной будет установлена данная локаль, если она отличается от текущей установленной, а после выполнения задачи будет возвращено первоначальное значение локали
- callable — задача, которую необходимо выполнить и вернуть результат работы.
Особенности работы метода:
- Если переданная строка с локалью не состоит в списке доступных локалей для приложения, то создается объект-исключение.
- Если вместо пользователя или строки с локалью передано нечто иное, то создается объект-исключение.
- Если передан идентификатор пользователя, у которого настроена системная локаль (то есть пользователь не изменял язык системы вручную), то метод выполняется в системной локали.
- Если передан не существующий пользовательский UUID, то метод выполняется в системной локали.
- Для задания кода локали используется официальный двухбуквенный код языка.
Пример 1. Выполнение задачи под локалью пользователя:
```
def employee = utils.get('employee$8517')
return api.locale.call(employee) { utils.get('mc$25701').title }
```
Пример 2. Выполнение задачи под локалью, переданной в методе:

api.locale.call('ru') { utils.edit('employee$8517', ['title' : 'newTitle']) }

api.location Запрос геопозиции

api.location.getMobileLocation(recipient)

api.location.getMobileLocation(recipient, timeToLive)

Метод запрашивает текущее местоположение последнего активного мобильного устройства пользователя у мобильного приложения, используя механизм отправки push-уведомлений.

Запрос выполняется асинхронно. Метка геопозиции, полученная от мобильного приложения, сохраняется как объект служебного класса "История перемещений".

Параметры метода:
- recipient — uuid сотрудника, для которого запрашивается местоположение мобильного устройства. String;
- timeToLive — время жизни отправляемого запроса в секундах, по умолчанию 300 (5 минут Int.
Возвращаемое значение:
- true — если запрос успешно отправлен;
- false — если отправить не удалось.
  
  Возможные причины: включен режим Silent mode, нет ни одного ассоциированного с сотрудником мобильного устройства

api.logging Настройки минутной ротации логов

Методы используются, если в файле log4j.properties настроена периодическая минутная ротация логов.

api.logging.getMinutelyAppenderParams()

Просмотр текущих настроек.
api.logging.setMinutelyAppenderParam(param)

Установка параметров ротации.

Параметры метода:
- param — период ротации в минутах >0 и <=60, по умолчанию 15, например, ('MinutelyPeriod', 10)
- param — максимальное количество файлов логов, по умолчанию 2, например, ('MaxBackupIndex', 5)
- param — ротация по размеру файла,
  
  например:
  - ('MaxFileSize', '10KB') — размер файла в KB, MB, GB, целое значение от 0 до 2^63
  - ('MaxFileSize', '1024') — размер файла в байтах
  - ('MaxFileSize', '-1') — отключение ротации по размеру

api.mail Обработка почты

Параметры входящих сообщений

Параметры получателей и отправителей обрабатываемого почтового сообщения (message):
- message.getRecipientsAsString() — Список всех адресов получателей через символ ";"
- message.getToAsString() — Список адресов получателей, указанных в поле "Кому" (TO);
- message.getCcAsString() — Список адресов получателей, указанных в поле "Копия" (CC);
- message.getCc() — Список получателей из адресов поля "Копия";
- message.getFrom().getAddress() — Адрес отправителя сообщения;
- message.getFrom().getName() — Имя отправителя сообщения;
- message.getFrom().getDomain() — Домен отправителя сообщения (часть адреса после "@").
Получение параметров почтового сообщения (message):
- message.getHeaders().get("название_заголовка") — Заголовок сообщения;
- message.getSubject() — Тема сообщения;
- message.getBody() — Тело сообщения как обычный текст;
- message.getHtmlBody() — Тело сообщения в формате html, без обрамляющих тегов (<html> и <body> и др.) и потенциально опасных тегов;
- message.getBodyRTF() — Тело сообщения в формате html, в котором ссылки на inline-вложения заменены на содержимое этих вложений;
- message.getContentType() — Строка — тип содержимого;
- message.getDigitalSignature() — Строка, соответствующая ЭЦП письма;
- message.getInReplyTo() — Строка с идентификатором (Message-ID) родительского письма;
- message.getPriority() — Строка, соответствующая приоритету письма;
- message.getSize() — Размер письма в байтах;
- message.getReplyTo() — Список строк-адресов для ответа.
message.getAttachments() — Список файлов, прикрепленных к письму
Получение параметров вложения (attachment):
- attachment.getFilename() — Имя файла (обычно короткое имя с расширением);
- attachment.getContentType() — MIME-тип содержимого файла;
- attachment.getData() — Массив байтов содержимого файла;
- message.getAttachmentsTotalSize() — Суммарный размер вложений к письму message в байтах;
- message.getInlineAttachments() — Список объектов-вложений, встроенных в тело в email сообщении message;
- message.getNotInlineAttachments() — Список объектов-вложений, содержащихся в email-сообщении message.

Результаты обработки (result)

Параметры результатов обработки:
- result.getMessageState() — статус сообщения;
- result.isRejected() — факт отклонения письма: true — если письмо отклонено (rejected); false — в остальных случаях;
- result.getRejectReason() — причина отклонения письма;
- result.getRejectMessage() — текстовое описание причины отклонения;
- result.isError() — факт наличия ошибки при обработке письма: true — если есть ошибка (error), false — в остальных случаях;
- result.getErrorMessage() — текстовое описание ошибки при обработке письма;
- result.error(errorMessage) — указание на то, что результатом является ошибка и назначение ее текстового описания.
result.setMessageState(messageState)

Назначение статуса почтового сообщения.

Параметр метода:
- messageState — статус почтового сообщения.
Возможные значения статуса:
- api.mail.ERROR_MSG_STATE — обработка сообщения закончилась ошибкой;
- api.mail.REJECT_MSG_STATE — сообщение было отклонено;
- api.mail.NEW_BO_MSG_STATE — при обработке сообщения был создан новый бизнес-объект;
- api.mail.ATTACH_MSG_STATE — обрабатываемое сообщение было прикреплено к существующему бизнес-объекту;
- api.mail.OUTGOING_MSG_STATE — другое.
result.reject(reason)

result.reject(reason, message)

Отклонение письма с указанием причины.

Параметры метода:
- reason — причина отклонения;
- messageState — статус почтового сообщения.
Возможные причины отклонения:
- api.mail.BAD_ATTACHMENTS_REJECT_REASON — к сообщению прикреплены несоответствующие вложения
- api.mail.INVALID_EMAIL_REJECT_REASON — указан некорректный email-адрес;
- api.mail.BIG_ATTACHMENT_REJECT_REASON — к сообщению прикреплено слишком большое вложение
- api.mail.BAD_FORMAT_REJECT_REASON — несоответствующий формат сообщения
- api.mail.CLIENT_NOT_FOUND_REJECT_REASON — не удалось определить клиента для запроса
- api.mail.CONTACT_NOT_FOUND_REJECT_REASON — не удалось определить контактное лицо для запроса
- api.mail.BLACKLIST_REJECT_REASON — входит в черный список
- api.mail.OTHER_REJECT_REASON — другая причина.
result.isSuccessfull()

Получение результата обработки входящего сообщения.

Возвращаемое значение:
- true — если письмо не отклонено (rejected) и не ошибка (error).
- false — в других случаях.

Проверки входящих сообщений

api.mail.hasBadAttachment(message, acceptableExtensions, exceptableExtensions)

Проверка допустимых и недопустимых типов вложений в сообщении. Данный метод не влияет на системную проверку наличия в письме недопустимых вложений с расширениями: "exe", "com", "bin". Если в письме есть хоть одно вложение с указанным расширением, то письмо будет отклонено.

Параметры метода:
- message — проверяемое сообщение
- acceptableExtensions — список допустимых расширений файлов во вложении письма, может быть пуст
- exceptableExtensions — список недопустимых расширений файлов во вложении письма, может быть пуст.
Возвращаемое значение:
- true — если в письме есть хоть одно вложение с недопустимым расширением
- false — иначе
Пример. Допустимые расширения файлов во вложении письма (скрипт правила обработки входящей почты):
Copy
```
def acceptableExtensions = ['gif', 'jpg', 'png', 'htm', 'html', 'txt']; 
//Недопустимые расширения файлов во вложении письма 
def exceptableExtensions = ['exe', 'com', 'bin']; 
if (api.mail.hasBadAttachment(message, acceptableExtensions, exceptableExtensions)) 
{ 
logger.error('Входящее письмо содержит недопустимые файлы во вложении!'); 
} 
else 
{ 
logger.info('Входящее письмо не содержит недопустимых файлов во вложении.'); 
}
```
api.mail.isValidEmail(email)

api.mail.helper.isValidEmail(email)

Проверка email-адреса на корректность. Сравнение, поиск, изменение, удаление email-адресов производятся без учета регистра.

email-адрес корректен, если
- начинается только с буквы или цифры;
- в FQDN (после @) используются только прописные от A до Z, строчные буквы от a до z; числа от 0 до 9; дефисы ( - )
Для прохождения валидации внутренних доменов верхнего уровня необходимо указать эти домены в конфигурационном файле dbaccess.properties.

Возвращаемое значение:
- true — если email-адрес корректен.
- false — если email-адрес не корректен.
api.mail.helper.isInvalidEmail(email)

Проверка email-адреса на корректность. Сравнение, поиск, изменение, удаление email-адресов производятся без учета регистра.

email-адрес корректен, если
- начинается только с буквы или цифры;
- в FQDN (после @) используются только прописные от A до Z, строчные буквы от a до z; числа от 0 до 9; дефисы ( - )
Для прохождения валидации внутренних доменов верхнего уровня необходимо указать эти домены в конфигурационном файлеdbaccess.properties.

Возвращаемое значение:
- null, если email-адрес корректен;
- сообщение об ошибке, если email-адрес не корректен.
api.mail.helper.isSystemEmailAddress(email)

Проверка email-адреса на принадлежность к email-адресу системы. В сообщениях, отправляемых системой, в поле "from" указан email-адрес системы, который задан в настройке исходящей почты.

Возвращаемое значение:
- true — если проверяемый email-адрес является email-адресом системы (сообщения, отправляемые системой, имеют from с указанным адресом).
- false — иначе.
api.mail.helper.getFeedbackAddress()

Возвращает строку — адрес службы технической поддержки
api.mail.helper.getInboundMailAddresses()

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

Прикрепление входящих сообщений к объекту

api.mail.attachMessage(subject, message)

api.mail.helper.attachMessage(subject, message)

Прикрепление входящего сообщения к объекту.

Параметры метода:
- subject — объект, к которому прикрепляется сообщение
- message — входящее сообщение
Результат выполнения: входящее сообщение прикрепляется как файл .eml, для просмотра файла используется почтовый клиент.
api.mail.attachMessageAttachments(subject, message)

api.mail.helper.attachMessageAttachments(subject, message)

Прикрепление вложений из входящего сообщения к объекту.

Параметры метода:
- subject — объект, к которому прикрепляется сообщение и его вложения
- message — входящее сообщение
Особенности метода: файлы изображения, вложенные в само сообщение, пропускаются
api.mail.attachAllMessageAttachments(subject, message)

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

Параметры метода:
- subject — объект, к которому прикрепляется сообщение и его вложения
- message — входящее сообщение
api.mail.attachMessageAttachments(subject, message, attrCode)

Прикрепление всех вложений из входящего сообщения к объекту, в определенный атрибут объекта.

Параметры метода:
- subject — объект, к которому прикрепляется сообщение и его вложения
- message — входящее сообщение
- attrCode — атрибут объекта, к которому прикрепляется сообщение и его вложения

Модификация входящих сообщений

api.mail.helper.replaceReferencesToAttachments(message)

Модификация html содержимого письма с целью корректного отображения содержимого по ссылкам (например, вложенные картинки).

Преобразует содержание письма в формате HTML: заменяет ссылки на составные части письма (например, содержимое картинки) ссылками на прикрепленные файлы.

Данный метод следует использовать после прикрепления всех вложений входящего сообщения message к объекту subject: api.mail.helper.attachMessageAttachments(subject, message)

см. Методы API
api.mail.helper.correctFileName(name)

Замена запрещенных для windows/linux символов в именах файлов.

Параметр метода:
- name — имя файла. String
Возвращает имя файла, в котором все запрещенные символы заменены знаком подчеркивания.

Получение информации из письма

api.mail.getCallNumber(messageTheme)

Получение номера запроса из темы письма. Метод ищет номер как слово (т.е. последовательность цифр, отделенная разделителями, например, "запрос 1 создан"). Если ничего не найдено, ищет последовательность цифр в строке (например, "запрос №1 создан").

Параметр метода:
- messageTheme — тема письма в скрипте обработки почты IInboundMailMessage
Возвращает номер запроса из темы письма.
api.mail.getNumberWithPrefix(messageTheme, prefix)

Получение номера запроса из темы письма, после определенного префикса и пробела.

Параметры метода:
- messageTheme — тема письма. String
- prefix — префикс номера. String
Возвращает номер запроса.
api.mail.getNumberWithPrefix(messageTheme, prefix, existSpaceAfterPrefix)

Получение номера запроса из темы письма, после определенного префикса.

Параметры метода:
- messageTheme — тема письма. String
- prefix — префикс номера. String
- existSpaceAfterPrefix — true (есть пробел между префиксом и номером), false (пробела нет)
Возвращает номер запроса.

Поиск запроса

api.mail.helper.searchSCByNumber(callId)

Поиск запроса по номеру.

Параметр метода:
- callId — номер запроса. String
Возвращает запрос.
api.mail.searchByCallNumber(message)

Поиск запроса по номеру из письма.

Параметр метода:
- message — входящее сообщение
Возвращает запрос.
api.mail.searchByCallNumberWithPrefix(message, prefix)

Поиск запроса по номеру из письма с префиксом.

Параметры метода:
- message — входящее сообщение
- prefix — префикс номера. String
Возвращает объект-запрос по его номеру.
api.mail.helper.searchByCallTitle(subject)

Поиск запроса по названию.

Возвращает первый запрос с таким названием или null, если нет запросов с таким именем.

Поиск сотрудника

api.mail.searchEmployeeByEmail(email)

api.mail.helper.searchEmployeeByEmail(email)

Поиск сотрудника по email-адресу.

Возвращаемое значение:
- сотрудник — если найден только один сотрудник;
- null — если не найдено ни одного сотрудника или найдено два сотрудника с одинаковым email;
- генерирует исключение — если найдено более одного сотрудника.
api.mail.searchEmployeesByEmail(email)

Поиск всех сотрудников с указанному email.

Возвращает список неархивных сотрудников с указанным email.
api.mail.helper.findEmployeesByEmail(email, type)

Поиск всех сотрудников указанного типа с указанным email.

Параметры метода:
- email — email адрес сотрудника
- type — тип сотрудников
api.mail.searchEmployeeByLastName(lastName)

Поиск сотрудника по фамилии.

Возвращает неархивного сотрудника с указанной фамилией. Если существует несколько сотрудников с одинаковой фамилией вернется null.

Генерация события "Поступление письма"

api.mail.helper.notifyMailReceived(scall)

Генерация события "Поступление письма":

Формирование тела обратного письма

При использовании методов respondBody письмо загружается целиком в память и потенциально может возникнуть нехватка памяти.

api.mail.formRespondBody(processingResult)

Формирование тела обратного письма с пометкой об отклонении обработки входящего письма, а также указанием причины отклонения (если она есть)

Параметр метода:
- processingResult — результат обработки входящего письма
Возвращает сформированное тело письма в виде строки.

Пример:

def respondBody = api.mail.formRespondBody(result);
api.mail.respondBody(message)

Формирование тела обратного письма с цитированием исходного сообщения.

Параметр метода:
- message — исходное входящее сообщение.
Возвращает сформированное тело письма в виде строки.

Пример:

def respondBody = api.mail.respondBody(message)

api.mail Отправка сообщений

Нельзя отправить письмо на адрес, который используется для подключения к серверу входящей почты.

Отправка сообщения

api.mail.sender.send (email, title, subject, message)

api.mail.sender.send (email, title, subject, message, contentType)

Отправка текстового сообщения одному получателю с учетом транзакции (сообщения отправляются, только если транзакция будет зафиксирована).

Параметры метода:
- email — email, на который будет отправляться сообщение. String.
- title — имя получателя. String.
- subject — тема сообщения.
- message — содержание сообщения.
- contentType — тип сообщения, может быть "text/plain" или "text/html".
api.mail.sender.send (['email1' :'title1', 'email2' : 'title2'], subject, message)

api.mail.sender.send (['email1' :'title1', 'email2' : 'title2'], subject, message, contentType)

Отправка текстового сообщения нескольким получателям с учетом транзакции (сообщения отправляются, только если транзакция будет зафиксирована).

Параметры метода:
- ['email1' :'title1', 'email2' : 'title2'] — ассоциативный массив: ключ — email-адрес, на который будет отправляться сообщение, значение — имя получателя.
- subject — тема сообщения.
- message — содержание сообщения.
- contentType — тип сообщения, может быть "text/plain" или "text/html".
api.mail.simpleSender.send(email, title, subject, message)

api.mail.simpleSender.send(email, title, subject, message, contentType)

Отправка текстового сообщения одному получателю вне контекста транзакции.
api.mail.simpleSender.send(['email1' :'title1', 'email2' : 'title2'], subject, message)

api.mail.simpleSender.send(['email1' :'title1', 'email2' : 'title2'], subject, message, contentType)

Отправка текстового сообщения нескольким получателям вне контекста транзакции.

Создание и отправка сообщения

Создание и отправка сообщения с подключением по умолчанию

api.mail.sender.sendMail(message)

Отправка сообщения с сервера исходящей почты по умолчанию.

Параметр метода:
- message — содержание сообщения.
api.mail.sender.createMail()

Создание объекта почтового сообщения c предзаполненными полями "От кого (from)[имя, email]", "кодировка", "флаг транслитерации заголовка". Данные берутся из подключения по умолчанию.
Параметры почтового сообщения:
- message.addTo('name recipient', 'email recipient')
  
  Добавляет получателя (поле письма "Кому").
- message.addCc(name recipient', 'email recipient')
  
  Добавляет получателя копии.
- message.addBcc(name recipient', 'email recipient')
  
  Добавляет получателя скрытой копии.
- message.addReplyTo('name', 'reply-to email')
  
  Добавляет адрес replyTo.
- message.setFrom('name addresser', 'email addresser')
  
  Задает адрес отправителя.
- message.setSubject('theme')
  
  Устанавливает тему отправляемого сообщения.
- message.setText('body')
  
  Устанавливает текст отправляемого сообщения.
- message.setHeader(headerName, headerValue)
  
  Устанавливает заголовок отправляемого сообщения.
- message.addText('\n\nsignature')
  
  Дописывает текст в конец тела сообщения.
- message.contentType = 'text/plain'
  
  Задает тип содержимого письма.

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

Copy

def message = api.mail.sender.createMail() 
message.addTo('Имя получателя №1', 'address1@mail.com')  //добавление получателя (поле письма "Кому")
message.addCc('Имя получателя №2', 'address2@mail.com')  // добавление получателя в копию
message.addBcc('Имя получателя №3', 'address3@mail.com') //добавление получателя в скрытую копию
message.addReplyTo('Имя', 'reply-to@mail.com') //добавление адреса replyTo
message.setFrom('Имя отправителя', 'from@mail.com') //добавление адреса отправителя
message.setSubject('Тема сообщения') // тема сообщения
message.setText('Тело сообщения') //текст сообщения
message.addText('\n\nПодпись') //добавление текста в конец тела сообщения
message.contentType = 'text/plain' // тип содержимого письма
message.setHeader('In-Reply-To', '52D635DD.90108@naumen.ru')// добавление/редактирование заголовка сообщения 
def file = ... // системный объект класса "Файл" (file)
def source = utils.getFileDataSource(file) // получение источника данных для объекта file
message.attachFile(source) // прикрепление файла к сообщению (также можно прикрепить два и более файлов)
def replyMessage = api.mail.createMessageResponse(message, "reply text");
 api.mail.sender.sendMail(message) //отправка созданного сообщения

Создание и отправка сообщения с заданным подключением

api.mail.sender.sendMail(message, connection)

Отправка сообщения с конкретного сервера исходящей почты.

В качестве второго параметра принимает идентификатор исходящего подключения, из которого будет отправлено переданное письмо. Если передан некорректный идентификатор, то будет выбрано подключение по умолчанию. Если в сообщении ранее не были заполнены поля: "От кого(from)[имя, email]", "кодировка" и "флаг транслитерации заголовка", то они будут заполнены значениями из выбранного исходящего подключения.

Для использования данного метода рекомендуется создавать письмо с помощью api.mail.sender.createEmptyMail().

Параметры метода:
- message — содержание сообщения;
- connection — идентификатор подключения исходящей почты, который можно посмотреть в адресной строке на карточке подключения:
  
  https://naumen.ru/sd/admin/#out-mail-server:9f23688c-c4ca-4a3e-8b60-c92401f710ef
  
  Значение параметра не влияет на from и reply to письма.
аpi.mail.sender.createEmptyMail()

Создание объекта пустого почтового сообщения, не содержащего предзаполненных полей. Альтернатива методу api.mail.sender.createMail().

Созданное сообщение может быть отправлено через подключение, отличное от подключения по умолчанию. В отличии от сообщения, созданного методом api.mail.sender.createMail(), поля "От кого(from)[имя, email]", "кодировка" и "флаг транслитерации заголовка" заполняются данными из выбранного подключения.

Если при отправке подключение не было выбрано явно, т.е. отправка осуществлялась через api.mail.sender.sendMail(message), то будут взяты данные из подключения по умолчанию.

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

Copy

//ВАЖНО: для корректной отправки сообщения с указанием подключения сообщение должно быть создано через api.mail.sender.createEmptyMail():
def message = api.mail.sender.createEmptyMail()
message.addTo('example', 'example@example.com')
message.setSubject('Example subject')
message.setText('Example')
api.mail.sender.sendMail(message, '9e3f62fe-6ce5-4acd-a85e-f292f96c0f5f')

api.metainfo Работа с метаинформацией

Данное API определяет несколько методов для доступа к метаинформации:

fqn метакласса (fqn) — краткое описание метакласса: содержит код класса и код типа;
строковое представление метакласса — полный код метакласса, например 'serviceCall$incident';
метакласс — полное описание класса или типа объектов, содержит, например информацию об атрибутах, группах атрибутов и т.п.;
переменная subject.metaClass возвращает fqn метакласса объекта (на форме добавления возвращает null, лучше использовать api.metainfo.getMetaClass(subject))

Получение и проверка метаинформации

api.metainfo.getMetaClass(obj)

Получение метакласса.

Параметр метода:
- obj — fqn метакласса либо строковое представление метакласса, либо объект, либо метакласс
api.metainfo.metaClassExists(obj)

Проверка существование метакласса.

Параметр метода:
- obj — fqn метакласса либо строковое представление метакласса, либо объект, либо метакласс
api.metainfo.getTypes(fqn)

Получение всех типов заданного класса (список метаклассов).

Параметр метода:
- fqn — fqn метакласса либо строковое представление метакласса
api.metainfo.checkAttributeExisting(fqn, attribute)

Проверка наличия атрибута с заданным кодом в метаклассе.

Параметры метода:
- fqn — fqn метакласса либо строковое представление метакласса, либо объект, либо метакласс;
- attribute — код атрибута.
Возвращаемое значение:
- пустая строка, если атрибут существует
- сообщение об ошибке, если атрибута не существует
api.metainfo.checkAttrsExisting(fqn, attributes)

Проверка наличия нескольких атрибутов с заданным кодом в метаклассе.

Параметры метода:
- fqn — fqn метакласса либо строковое представление метакласса, либо объект, либо метакласс;
- attribute — набор кодов атрибутов.
Возвращаемое значение:
- пустая строка, если все атрибуты существуют;
- сообщение об ошибке, если хотя бы одного атрибута не существует.
api.metainfo.checkAttributeType(fqn, attribute, possibleTypes)

Проверка соответствия типа атрибута одному из списка possibleTypes.

Параметры метода:
- fqn — fqn метакласса либо строковое представление метакласса, либо объект, либо метакласс
- attribute — набор кодов атрибутов для проверки
- possibleTypes — набор кодов допустимых типов атрибутов для проверки
Возвращает:
- пустая строка, если список possibleTypes содержит код типа проверяемого атрибута
- сообщение об ошибке "Для атрибута 'attribute' в метаклассе 'metaClass' задан тип '...', а ожидается один из следующих типов: possibleTypes.", если не содержит
Пример:
```
def fqn = 'serviceCall$call';
def attribute = 'agreement';
def possibleTypes = ['object', 'boLinks'];
def error = api.metainfo.checkAttributeType(fqn, attribute, possibleTypes)
```
api.metainfo.checkAttrsType(fqn, attributes)

Проверка соответствия типа атрибута одному из списка, заданного для этого атрибута.

Параметры метода:
- fqn — fqn метакласса либо строковое представление метакласса, либо объект, либо метакласс
- attributes — ассоциативный список
  
  //def attributes = ['agreement': ['object', 'boLinks'], 'qweqtqr' : ['string']]
Возвращает:
- пустая строка, если для всех атрибутов выполняется условие: список кодов типов содержит код типа проверяемого атрибута
- сообщение об ошибке, если не содержит.
api.metainfo.getDefaultServiceCallCase(uuid)

Получение типа запроса по умолчанию для заданного контрагента.

Параметр метода:
- uuid — строковое представление уникального идентификатора контрагента запроса
Возвращает:
- тип запроса
- null, если тип запроса по умолчанию не задан
Пример:
```
def uuid = 'employee$1001';
def defaultScCase = api.metainfo.getDefaultServiceCallCase(uuid);
```
api.metainfo.fixEmptyFieldsInSearchSettings()

Замена пустых названий в настройках поиска на локализованные.
api.metainfo.getParentFqn(fqn)

Получение ClassFqn родителя для метакласса по его fqn.

Параметр метода:
- fqn — fqn метакласса, или строковое представление метакласса
Параметр:
```
def fqn = 'serviceCall$call';
def parentFqn = api.metainfo.getParentFqn(fqn);
```

Обращение к свойствам метакласса

api.metainfo.getMetaClassTitle(fqn)

api.metainfo.getMetaClassTitle(fqn, locale)

Получение названия метакласса (РЕКОМЕНДУЕМЫЙ).

Параметры метода:
- fqn — идентификатор метакласса (ClassFqn):
  - строковое представление идентификатора метакласса (String);
  - объект, для которого требуется определить метакласс (IScriptDtObject);
  - метакласс (MetaClassWrapper).
- locale — название локали.
Возвращает: Название метакласса
Методы обращения к свойствам метакласса, доступны после получения самого метакласса:
- title — название метакласса (УСТАРЕВШИЙ);
- getAttribute(String code) — атрибут метакласса по коду;
- attributeCodes — коллекция кодов всех атрибутов метакласса;
- attributeGroupCodes — коллекция кодов групп атрибутов;
- attributeGroups — коллекция групп атрибутов;
- getAttributeGroup(String code) — группа атрибутов по коду;
- attributes — коллекция атрибутов;
- children — список метаклассов-подтипов первого уровня вложенности, т.е. метаклассы, родителем которых является данный метакласс;
- code — код метакласса, например, incident;
- description — описание;
- fqn — объект, идентифицирующий метакласс: getCase() — код типа; id — код класса;
- fqnCase — код типа метакласса;
- parent — родитель (метакласс);
- workflow — объект жизненного цикла;
- hasAttribute(String code) — true, если у метакласса есть атрибут с указанным кодом, иначе false;
- hasWorkflow — true, если у метакласса есть жизненный цикл, иначе false;
- hasResponsible — логическое значение, есть ли в метаклассе механизм передачи ответственного;
- tags — список меток, которыми помечен метакласс;
- removed — логическое значение, является ли метакласс архивным.

Обращение к атрибутам метакласса

Методы обращения к атрибутам метакласса, доступны после получения атрибута метакласса (getAttribute(String code)):
- title — название
- code — код
- type — тип атрибута
- declaredMetaClass — метакласс, в котором этот атрибут создан
- defaultValue — значение по умолчанию (если значение по умолчанию является вычислимым, то возвращает null)
- hasDefaultValue — логическое значение, определено ли значение по умолчанию
- hardcoded — логическое значение, является ли атрибут системным
- filteredByScript — логическое значение, фильтруется скриптом
- computable — проверяет, является ли атрибут вычислимым
- required — проверяет, является ли атрибут обязательным
- requiredInInterface — проверяет, является ли атрибут обязательным для заполнения в интерфейсе
- unique — проверяет, является ли атрибут уникальным
Пример. Название атрибута метакласса

api.metainfo.getMetaClass(subject).getAttribute(attrCode).title

Метод для получения кода типа атрибутов: code — возвращает код типа атрибута.

Обращение к группам атрибутов метакласса

Методы обращения к группам атрибутов метакласса, доступны после получения группы метакласса getAttributeGroup(String code):
- title — название
- code — код
- attributeCodes — список кодов атрибутов, входящих в группы

Работа со статусами жизненного цикла

Методы получения статуса жизненного цикла, доступны после получения объекта жизненного цикла метакласса workflow:
- endState — конечный статус
- originalState — первоначальный статус, с которым создается объект
- getState(String code) — статус по коду
- states — список статусов
- isTransitionExists(beginState, endState) — проверяет наличие разрешенного перехода из состояния beginState в endState, где beginState и endState — либо коды статусов, либо статусы как объекты
api.metainfo.getStateTitle(fqn, stateCode)

api.metainfo.getStateTitle(obj)

api.metainfo.getStateTitle(fqn, stateCode, locale)

api.metainfo.getStateTitle(obj, locale)

Методы получения названия статуса.

Параметры методов:
- fqn — идентификатор метакласса (ClassFqn):
  - строковое представление идентификатора метакласса (String)
  - объект, для которого требуется определить метакласс (IScriptDtObject)
  - метакласс (MetaClassWrapper)
- stateCode — код статуса
- locale — название локали
- obj — бизнес-объект с жизненным циклом (IScriptDtObject), например, utils.get('ou$123'), subject
Возвращает название метакласса.
Методы обращения к свойствам статуса жизненного цикла, методы доступны после получения статуса метакласса (getState(String code)):
- code — код статуса
- description — описание статуса
- enabled — проверяет доступность

Работа с метками

Методы обращения к свойствам метки:
- code — код метки
- title — название метки
- enabled — состояние метки: true, если она включена, иначе false

Получение настроек из интерфейса администратора

api.metainfo.getServiceCallParameters()

Получение настроек параметров запросов из интерфейса администратора.

Возвращает: Настройки параметров запросов: "Определяющее поле при выборе соглашения/услуги и типа запроса" (выбирать сначала), "Значение поля "Соглашение/Услуга", "Представление для редактирования".

Пример:

def scParams = api.metainfo.getServiceCallParameters()

Параметры объекта scParams:
- scParamsscParams.priority:
  - AgreementService — определяющее поле "Соглашение/Услуга";
  - Case — определяющее поле "Тип запроса"
- scParams.agreementService.setting:
  - Agreement — только соглашения;
  - Both — соглашения и/или услуги;
  - Service — только услуги.
- scParams.agreementService.editPresentation:
  - TreeList — иерархический список (соглашение и услуга);
  - List — плоский список;
  - FoldersTree — выбор из каталога;
  - ServiceTreeList — иерархический список для случая, когда услуга вложена в себя.
api.metainfo.checkTagEnabled(tagCode)

Получение состояния метки (включена или выключена).

Параметр метода:
- tagCode — код метки (String).

Анализ компиляции модулей

api.metainfo.compileAll()

Компилирует скриптовые модули в режиме all. Метод рекомендуется выполнять в консоли для выявления проблем компиляции скриптовых модулей.

Метод возвращает:
- true — если проблемы компиляции отсутствуют;
- ошибку с описанием проблемы — если есть проблемы с компиляцией.
  
  Пример сообщения об ошибке:
  
  Script compilation error
  
  startup failed:
  
  testa: 1: Invalid duplicate class definition of class Temp : The sources testa and testb each contain a class with the name Temp.
  
  @ line 1, column 1.
  
  class Temp{}
  
  ^
  
  1 error
  
  где:
  - "Invalid duplicate class definition of class Temp" — описание проблемы компиляции, например, наличие в проблемных классах классов с одинаковым именем);
  - "testa and testb" — в каких классах проблемы
  - "contain a class with the name Temp" — дополнительное описание проблемы;
  - "class Temp{}" — как это выглядит в коде.
См. подробнее Скрипты и скриптовые модули

api.mq Отправка сообщения в пользовательскую очередь

api.mq.send(jmsQueueCode, data)

api.mq.send(jmsQueueCode, messageEnhancer)

Логика работы: api-метод api.mq.send отправляет сообщение в пользовательскую очередь → срабатывает действие по событию на поступление сообщения в очередь → поступившее сообщение обрабатывается в очереди согласно скрипту действия по событию.

Методы поддерживаются только для очередей брокеров Artemis.

Параметры метода:
- jmsQueueCode — код пользовательской очереди. String.
- data — сообщение для отправки. Object.
- messageEnhancer — оператор, дополняющий сообщение. Closure<?>.

api.naming Правила нумерации объектов

api.naming.set(metaClass, rule, number)

Устанавливает следующий номер, который будет возвращен последовательностью N, ND, RND.

Использовать этот метод стоит только тогда, когда в системе не создаются объекты, при создании которых используются изменяемые последовательности. Типовое использование этого метода — выставление правильных номеров после первоначального импорта системы.

При использовании метода необходимо учитывать уникальность атрибута "Номер" (number):
- Если значения атрибута являются не уникальными и есть созданные объекты указанного класса, то "Номер" может дублироваться.
- Если значения атрибута являются уникальными и есть созданные объекты указанного класса, то "Номер" не может дублироваться и попытка создания объектов с не уникальным номером не будет успешной.
Параметры метода:
- metaClass — FQN метакласса;
- rule — строка, определяет для какой последовательности будет устанавливаться значение.
  
  Возможные значения:
  - N — будет заменено системой на уникальный идентификатор;
  - ND — будет заменено системой на уникальный номер в рамках дня;
  - RND — будет заменено системой на случайный уникальный идентификатор.
- number — число, с которого начнется нумерация – number + 1.
Пример 1. number = 100, следующий запрос, у которого правило нумерации {N}, будет создан с номером 101:

api.naming.set('serviceCall', 'N', 100)

Пример 2. number = 100, следующий запрос, у которого правило нумерации {ND}, для текущей даты будет создан с номером 101, со следующего дня будет 1:

api.naming.set('serviceCall', 'ND', 100)

api.navigation Работа с навигационным меню

api.navigation.clearLeftMenuCache()

Очистить кэш левого навигационного меню.
api.navigation.clearTopMenuCache()

Очистить кэш верхнего навигационного меню.
api.navigation.clearAllCache()

Очистить кэш левого и верхнего навигационного меню.

api.notification Отправка уведомления

api.notification.sendWebPush(message, recipient)

Отправка упрощенного уведомления в веб-интерфейсе. Отправляет уведомление с текстом message получателю recipient.

Параметры:
- message — текст уведомления
- recipient — получатель уведомления (uuid либо объект)
Возвращает true — уведомление успешно отправлено, иначе false.
api.notification.sendMobilePush(message, recipient)

Отправка упрощенного уведомления в мобильное приложение. Отправляет уведомление с текстом message получателю recipient.

Параметры:
- message — текст уведомления
- recipient — получатель уведомления (uuid либо объект)
Возвращает true — уведомление успешно отправлено, иначе false.
api.notification.createPushMessage(message)

api.notification.createPushMessage(message).setLink(link).setUseHtml(false). ... .showBrowser()

Создание уведомления с дополнительными параметрами.

Для отправки созданного уведомления используются методы api.notification.sendWebPush и api.notification.sendMobilePush

Параметр:
- message — текст уведомления
Пример. Каждый из методов set*()/show*() возвращает this, поэтому для формирования объекта уведомления можно использовать следующий синтаксис:

def push=api.notification.createPushMessage(message).setLink(link).setUseHtml(false). ... .showBrowser()
api.notification.sendWebPush(push, utils.get('employee$2601'))

Отправка уведомления в веб-интерфейс.

Возвращает true — уведомление успешно отправлено, иначе false.
api.notification.sendMobilePush(push, 'employee$2601'):

Отправка уведомления в мобильное приложение.

Возвращает true — уведомление успешно отправлено, иначе false.
api.notification.markEventsAsRead(events)

Маркировка уведомлений, как прочитанных:

Параметр:
- events — коллекция строк-идентификаторов уведомлений
Параметры для создания уведомления с дополнительными параметрами

Параметры уведомления в веб-интерфейсе:
- push.setLink(api.web.open('employee$2601')) — Ссылка, на которую будет осуществлен переход при нажатии на уведомление (браузерное)
- push.setUseHtml(true) — Установка флажка "В формате HTML". По умолчанию true
- push.useTemplate('templateCode', ['var' : 'value']) — Применение шаблона стилей с кодом templateCode и контекстными переменными (Map<String (код), Object (значение)>). Из шаблона/текста уведомления можно обращаться к значению через ${код}
- push.useTemplate('templateCode') — Применение шаблона стилей с кодом templateCode, без контекстных переменных. По умолчанию ассоциативный массив будет содержать {'content' : текст уведомления}
- push.showBrowser() — Установка типа отображения "Только браузерное уведомление"
- push.showInterfaceAlways() — Установка типа отображения "В интерфейсе всегда. Дополнительно браузерное уведомление, если вкладка неактивна". Установлено по умолчанию
- push.showInterfaceAndBrowser() — Установка типа отображения "В интерфейсе и браузерное уведомление"
- push.showInterfaceOnly() — Установка типа отображения "Только в интерфейсе"
- push.getText() — Текст уведомления
Параметры уведомления в мобильном приложении:
- push.setLink(api.web.open('employee$2601')) — Ссылка, на которую будет осуществлен переход при нажатии на уведомление
- push.setSubject(message) — Тема уведомления в мобильном приложении
- push.setUseHtml(true) — Установка флажка "В формате HTML"
- push.useTemplate('templateCode', ['var' : 'value']) — Применение шаблона стилей с кодом templateCode и контекстными переменными (Map<String (код), Object (значение)>). Из шаблона/текста уведомления можно обращаться к значению через ${код}
- push.useTemplate('templateCode') — Применение шаблона стилей с кодом templateCode, без контекстных переменных. По умолчанию ассоциативный массив будет содержать {'content' : текст уведомления}
- push.showSubject() — Заголовок уведомления содержит только тему уведомления
- push.showSystemName() — Заголовок уведомления содержит значение параметра "Название системы" (настройки мобильного приложения вкладка "Прочее" — блок "Прочие настройки"). Установлено по умолчанию
- push.showSystemNameAndSubject() — Заголовок уведомления содержит значение параметра "Название системы" (настройки мобильного приложения вкладка "Прочее" — блок "Прочие настройки") и тему уведомления, разделенные пробелом
- push.getText() — Текст уведомления

api.ou Работа с оргструктурой

Работа с отделами

api.ou.nestedEmployees(ou)

Получение сотрудников отдела.

Параметр метода:
- ou — объект-отдел, для которого ищутся сотрудники.
Возвращает суммарное количество сотрудников в этом отделе и во всех вложенных.
api.ou.nestedOUs(ou)

Получение вложенных отделов.

Параметр метода:
- ou — объект-отдел, для которого ищутся вложенные отделы.
Возвращает UUID отделов, вложенных в отдел. Список результатов включает отдел OU.
api.ou.listNestedOUs(ou_uuid)

Получение вложенных отделов по UUID.

Параметр метода:
- ou_uuid — UUID отдела, для которого ищутся вложенные отделы.
Возвращает UUID отделов, вложенных в отдел с ou_uuid. Список результатов не включает сам отдел с ou_uuid.

Распространение соглашений

api.ou.distributeAgreements(agreement, recipients)

api.ou.distributeAgreements(agreement, rootRecipient)

Распространение соглашений (РЕКОМЕНДУЕМЫЙ). Для работы только с активными объектами.

api.ou.distributeAgreements(agreement, recipients, ignoreRemoved)

api.ou.distributeAgreements(agreement, rootRecipient, ignoreRemoved)

Работа либо только с активными объектами, либо с архивными и активными одновременно.

Параметры метода:
- agreement — соглашение, либо его UUID, либо коллекция соглашений, либо их UUID;
- recipients — коллекция UUID получателей соглашения (сотрудник, отдел, команда). Соглашение распространяется только на указанных получателей;
- rootRecipient — UUID команды или отдела. Соглашение будет распространено на все объекты, вложенные в указанный;
- ignoreRemoved — условие отбора объектов для добавления соглашений:
  - true — только с активные объекты;
  - false — активные и архивные объекты
api.ou.assignAgreementToEmployee(employee, agreement)

Распространение соглашений (УСТАРЕВШИЙ).

Параметры метода:
- recipients — сотрудник, который связывается с соглашением;
- agreement — соглашение, связываемое с сотрудником.

Отзыв соглашений

api.ou.removeAgreements(agreement, recipients)

api.ou.removeAgreements(agreement, rootRecipient)

Для работы только с активными объектами.

api.ou.removeAgreements(agreement, recipients, searchMode)

api.ou.removeAgreements(agreement, rootRecipient, searchMode)

Работа с объектами, в зависимости от выбранного типа поиска — с активными, архивными или с архивными и активными одновременно.

Параметры метода:
- agreement — соглашение, либо его UUID, либо коллекция соглашений, либо их UUID;
- recipients — коллекция UUID получателей соглашения (сотрудник, отдел, команда);
- rootRecipient — UUID команды или отдела. Соглашение будет отозвано у всех вложенных объектов;
- searchMode — тип поиска объектов: только для активных объектов (active), только для архивных объектов (removed) или всех(активные и архивные (all).

Получение списка участников команд

api.team.getTeamMembers(teamUUIDs, removed)

Параметры метода:
- teamUUIDs — коллекция уникальных идентификаторов команд
- removed — true (если необходимо вернуть только архивных участников команд); false (если необходимо вернуть только неархивных участников команд).
Возвращает набор уникальных участников, которые состоят в перечисленных командах.

Если необходимо получить UUID участников команд:

api.team.getTeamMembers(Collection<String> teamUUIDs, boolean removed)?.UUID

api.rest Формирование ссылок для выполнения действий без перехода в интерфейс системы

При переходе по ссылке выполняется:

заданное действие с объектом;
выводится сообщение для пользователя в отдельном окне: "операция выполнена успешно" или "%текст ошибки%" (если действие не выполнено).

api.rest.create(fqn, attributes)

api.rest.create(fqn, attributes, login_or_accesskey)

api.rest.createWithUserUUID(fqn, attributes, login_or_accesskey)

Генерация URL-ссылки для добавления объекта указанного класса и типа с определенными атрибутами.

Параметры метода:
- fqn — fqn типа (класса) добавляемого объекта
- attributes — ассоциативный массив, содержащий атрибуты создаваемого объекта: ключ— код атрибута, значение — значение атрибута
- login_or_accesskey — логин или ключ авторизации пользователя для входа в систему (по имени пользователя или по uuid пользователя)
Возвращает строку, содержащую URL-ссылку для добавления объекта указанного типа/класса с определенными атрибутами.

Пример 1. Ссылка для создания отдела с названием "новый отдел" с ключом авторизации:

<a href="${api.rest.create('ou$ou', ['title' : 'новый отдел'], api.auth.getAccessKey('username'))}">Создать новый отдел</a>

<a href="${api.rest.create('ou$ou', ['title' : 'новый отдел'], 'username')}">Создать новый отдел</a>

<a href="${api.rest.createWithUserUUID('ou', ['title' : 'новый отдел'], 'userUUID')}">Создать новый отдел</a>

Пример 2. Ссылка для создания отдела с названием "новый отдел" с указанием логина и пароля или через прозрачную аутентификацию (Kerberos):

<a href="${api.rest.create('ou$ou', ['title' : 'новый отдел'])}">Создать новый отдел</a>
api.rest.edit(obj, attributes)

api.rest.edit(obj, attributes, login_or_accesskey)

api.rest.editWithUserUUID(obj, attributes, login_or_accesskey)

Генерация URL-ссылки для редактирования определенных атрибутов указанного объекта.

Параметры метода:
- obj — объект, атрибуты которого будут изменены при переходе по ссылке
- attributes — ассоциативный массив, содержащий атрибуты, значение которых будет изменено при редактировании объекта: ключ— код атрибута, значение — значение атрибута
- login_or_accesskey — логин или ключ авторизации пользователя для входа в систему (по имени пользователя или по uuid пользователя).
Возвращает строку, содержащую URL-ссылку для редактирования определенных атрибутов указанного объекта.

Пример 1. Ссылка для редактирования названия объекта (title) с ключом авторизации:

<a href="${api.rest.edit(subject, ['title' : 'new title'], api.auth.getAccessKey('username'))}">Переименовать в 'new title'</a>

<a href="${api.rest.edit(subject, ['title' : 'new title'], 'username')}">Переименовать в 'new title'</a>

<a href="${api.rest.editWithUserUUID(subject, ['title' : 'new title'], 'userUUID')}">Переименовать в 'new title'</a>

Пример 2. Ссылка для редактирования названия объекта (title) с указанием логина и пароля или через прозрачную аутентификацию:

<a href="${api.rest.edit(subject, ['title' : 'new title'])}">Переименовать в 'new title'</a>
api.rest.delete(obj)

api.rest.delete(obj, login_or_accesskey)

api.rest.deleteWithUserUUID(obj, login_or_accesskey)

Генерация URL-ссылки для удаления указанного объекта.

Параметры метода:
- obj — объект, который будет удален при переходе по ссылке
- login_or_accesskey — логин или ключ авторизации пользователя для входа в систему (по имени пользователя или по uuid пользователя)
Возвращает строку, содержащую URL-ссылку для удаления указанного объекта.

Пример 1. Ссылка для удаления объекта с ключом авторизации:

<a href="${api.rest.delete(subject, api.auth.getAccessKey('username'))}">Удалить</a>

<a href="${api.rest.delete(subject, 'username')}">Удалить</a>

<a href="${api.rest.deleteWithUserUUID(subject, 'userUUID')}">Удалить</a>

Пример 2. Ссылка для удаления объекта с указанием логина и пароля или через прозрачную аутентификацию:

<a href="${api.rest.delete(subject)}">Удалить</a>
api.rest.find(fqn, attributes)

api.rest.find(fqn, attributes, login_or_accesskey)

api.rest.findWithUserUUID(fqn, attributes[, login_or_accesskey])

Генерация URL-ссылки для поиска объекта. По ссылке открывается страница с результатами поиска.

Параметры метода:
- fqn — fqn типа (класса) добавляемого объекта;
- attributes — ассоциативный массив: ключ— код атрибута, значение — значение атрибута;
- login_or_accesskey — логин или ключ авторизации пользователя для входа в систему (по имени пользователя или по uuid пользователя)
Возвращает строку, содержащую URL-ссылку для поиска объекта.

Пример. Ссылка для удаления объекта с ключом авторизации:

<a href="${api.rest.find('ou', [:], api.auth.getAccessKey('username'))}">Получить список отделов</a>

<a href="${api.rest.find('ou', [:], 'username')}">Получить список отделов</a>

<a href="${api.rest.findWithUserUUID('ou', [:], 'userUUID')}">Получить список отделов</a>
api.rest.get(obj)

api.rest.get(obj, login_or_accesskey)

api.rest.getWithUserUUID(obj)

api.rest.getWithUserUUID(obj, login_or_accesskey)

Генерация URL-ссылки для получения объекта. По ссылке открывается страница с атрибутами указанного объекта.

Параметры метода:
- obj — объект, который будет получен при переходе по ссылке;
- login_or_accesskey — логин или ключ авторизации пользователя для входа в систему (по имени пользователя или по uuid пользователя).
Возвращает строку, содержащую URL-ссылку для получения объекта.

Пример. Ссылка для получения объекта с ключом авторизации:

<a href="${api.rest.get(subject, api.auth.getAccessKey('username'))}">Получить объект</a>

<a href="${api.rest.get(subject, 'username')}">Получить объект</a>

<a href="${api.rest.getWithUserUUID(subject, 'userUUID')}">Получить объект</a>

Для работы с api.rest через и Internet Explorer предлагается использовать решение Json. Описание решения: http://www.codeproject.com/Tips/216175/View-JSON-in-Internet-Explorer.

api.scheduler Работа с планировщиком

api.scheduler.getStatus()

Получение списка всех правил выполнения задачи и информации по ним (название, период в мс, дата если разовый запуск, включено или выключено) для всех задач планировщика. Информация о расписании выводится на экран в формате JSON
api.scheduler.getStatus(uuid)

Получение списка всех правил выполнения задачи и информации по ним (название, период в мс, дата если разовый запуск, включено или выключено) для определенной задачи планировщика .

Параметр метода:
- uuid — uuid задачи планировщика
api.scheduler.getStatus(uuid, triggerName)

Получение информации о конкретном правиле выполнения задачи (название, период в мс, дата если разовый запуск, включено или выключено) для определенной задачи планировщика.

Параметры метода:
- uuid — uuid задачи планировщика
- triggerName — название правила выполнения задачи планировщика
api.scheduler.getTriggersInfo(uuid, onlyEnabled)

Получение информации о расписании определенной задачи планировщика (только включенные правила выполнения задачи или все).

Параметры метода:
- uuid — uuid задачи планировщика
- onlyEnabled — true (возвращает только включенные правила выполнения задачи планировщика; false (аналогичен .getStatus('uuid задачи')
api.scheduler.interruptJob(uuid)

Прерывание выполнения задачи планировщика. Метод вызывает появление ошибки Thread Death в логах

Параметр метода:
- uuid — uuid задачи планировщика
api.scheduler.run(uuid)

Запуск задачи планировщика.

Параметр метода:
- uuid — uuid задачи планировщика
api.scheduler.setTriggerDate(uuid, triggerName, date)

Установка даты разового запуска задачи планировщика. Дата разового запуска расписания не может быть в прошлом. Действует для правил выполнения задачи с типом "Выполнение в определенную дату и время".

Параметры метода:
- uuid — uuid задачи планировщика
- triggerName — название правила выполнения задачи планировщика
- date —дата разового запуска задачи планировщика
  
  Дата в формате: 'dd.MM.yyyy HH:mm:ss'
  
  def date = utils.formatters.strToDate('str', 'dateFormat')
  
  Дата в формате: 'dd.MM.yyyy HH:mm'
  
  def date = utils.formatters.strToDateTime('str')
api.scheduler.setTriggerPeriod(uuid, triggerName, period, strategy, startingDate)

Установка периода для запуска задачи планировщика (1). Действует для правил выполнения задачи с типом "Периодическое выполнение". Период устанавливается в мс. Метод редактирует уже созданные триггеры.

Параметры метода:
- uuid — uuid задачи планировщика
- triggerName — название правила выполнения задачи планировщика
- period — период выполнения задачи планировщика: ежедневно, еженедельно, ежемесячно, ежегодно
  
  def period = 'daily'\'weekly'\'monthly'\'yearly'
- strategy — стратегия расчета периода со старта расписания или с момента последнего запуска
  
  def strategy = 'from_start'\'from_last_execution'
- startingDate — дата, с которой начнется выполнение периодического правила
api.scheduler.setTriggerInterval(uuid, triggerName, interval, strategy, startingDate)

Установка периода для запуска задачи планировщика (2). Действует для правил выполнения задачи с типом "Периодическое выполнение". Период устанавливается в мс. Метод редактирует уже созданные триггеры.

Параметры метода:
- uuid — uuid задачи планировщика
- triggerName — название правила выполнения задачи планировщика
- interval — интервал выполнения задачи планировщика
  
  def interval = api.types.newDateTimeInterval(length, interval)
  
  где length — число, interval — строка, возможные значения 'SECOND','MINUTE','HOUR'
  
  Пример. Получение интервала "раз в 3 минуты":
  
  def interval = api.types.newDateTimeInterval(3, 'MINUTE')
- strategy — стратегия расчета периода со старта расписания или с момента последнего запуска
  
  def strategy = 'from_start'\'from_last_execution'
- startingDate — дата, с которой начнется выполнение периодического правила
api.scheduler.disableTrigger(triggerName)

Выключение правила выполнения задачи планировщика.

Параметр метода:
- triggerName — название правила выполнения задачи планировщика
api.scheduler.enableTrigger(triggerName)

Включение правила выполнения задачи планировщика.
api.scheduler.deleteTask(uuid)

Принудительное удаление задачи планировщика. При удалении задачи "Обработка входящей почты" также удаляет необработанные сообщения, которые мешают удалению задачи.

Параметр метода:
- uuid — uuid задачи планировщика

api.search Работа с полнотекстовым поиском

api.search.reindexAll()

Переиндексация полнотекстового поиска. Индексация запускается асинхронно по метаклассам с разбивкой по 500 объектов.

Использование поиска во время переиндексации с использованием данного метода недоступно

Переиндексация объектов при больших объемах данных может занимать продолжительное время. Во время переиндексации производительность системы может быть снижена.
Рекомендуется запускать переиндексацию во время минимальной нагрузки на систему или во время технологических блокировок.

При запуске переиндексации происходит блокировка кнопки "Переиндексировать" на карточках всех классов /типов и справочников. Кнопка "Переиндексировать" остается недоступной для нажатия до момента окончания переиндексации независимо от того, перезагружалась ли страница класса /типа или справочника. После окончания процесса переиндексации кнопка будет недоступной до первой перезагрузки страницы.
api.search.getLastIndexDate()

Дата и время последней индексации в приложении.

Возвращает последнюю дату добавления любого объекта в индекс.

api.security Работа с правами

Проверка наличия профиля или роли

api.security.hasProfile(fqn, profile)

Проверка наличия профиля у текущего пользователя для указанного метакласса.

Данная конструкция имеет ограниченное применение, она не используется для действий по событию, так как в этом случае действие производится от лица суперпользователя.

Параметры метода:
- fqn — fqn типа (класса) объекта, для которого проверяются права;
- profile — профиль пользователя.
api.security.hasProfile(object, profile)

Проверка наличия профиля у текущего пользователя для указанного объекта:

Параметры метода:
- object — объект, для которого проверяются права;
- profile — профиль пользователя.
api.security.hasRole(object, role)

Проверка наличия роли у текущего пользователя для указанного объекта.

Данная конструкция имеет ограниченное применение, она не используется для действий по событию, так как в этом случае действие производится от лица суперпользователя.

Параметры метода:
- object — объект, для которого проверяются права;
- role — роль пользователя.

Проверка прав

api.security.hasAddServiceCallPermission(fqns, client, user)

Проверка, имеет ли текущий пользователь права на создание запросов указанных типов.

Параметры метода:
- fqns — список типов запроса, для которых выполняется проверка (строка или ClassFqn);
- client — контрагент, для которого проверяются права: сотрудник, отдел или команда (идентификатор или объект);
- user — сотрудник, для которого выполняется проверка прав.
api.security.hasEditPermission(object, attributeCode) [не поддерживается и корректная работа метода не гарантируется!]

Проверка, имеет ли текущий пользователь разрешение на редактирование атрибута.

Параметры метода:
- object — объект, атрибут которого нужно проверить на возможность редактирования;
- attributeCode — код атрибута.
Возвращаемое значение: true, если есть разрешение; false, если нет разрешения.

Работа с паролями

api.security.forceGlobalPasswordChange()

Обязать всех пользователей сменить пароль при следующем входе в систему.

При входе в систему все пользователи будут перенаправляться на форму принудительной смены пароля.

Исключение: Пользователь не перенаправляется на форму принудительной смены пароля, если переход в систему был по ссылке, содержащей accessKey.
api.security.forcePasswordChange(employee)

Обязать конкретного пользователя сменить пароль при следующем входе в систему.

При входе в систему указанный пользователь будет перенаправлен на форму принудительной смены пароля.

Параметр метода:
- employee — пользователь, который будет обязан сменить пароль, или его uuid.
Исключение: Пользователь не перенаправляется на форму принудительной смены пароля, если переход в систему был по ссылке, содержащей accessKey.
api.security.generatePassword()

Сгенерировать пароль, удовлетворяющий политике безопасности.

Возвращаемое значение: Сгенерированный пароль, который содержит:
- английские буквы;
- не более 2-х цифр (есть требование на использование цифр);
- не более 1 спецсимвола из !, @, #, $, %, ^, &, *, (, ), =, + (есть требование на использование спецсимволов).
Минимальная длина 7 символов (если значение параметра "Минимальное количество символов в пароле" равно или меньше 7) или соответствует указанному в параметре.

Описание требований политики безопасности см. Политика безопасности паролей.

Работа с группами пользователей

api.security.getGroup(grpCode)

Определение группы пользователей по ее коду.

Параметр метода:
- grpCode — код группы пользователей. String.
Возвращаемое значение: Группа пользователей.
api.security.getAllEmployees(groups)

Определение сотрудников заданной группы пользователей.

Параметр метода:
- groups — группы пользователей.
Возвращаемое значение: Группа пользователей.
api.security.addMembersToGroup(grpCode, membersUUIDs)

Добавление участников в группу пользователей.

Параметры метода:
- grpCode — код группы пользователей. String
- membersUUIDs — коллекция UUID участников группы пользователей: сотрудников, команд, отделов
api.security.addMemberToGroup(grpCode, memberUUID)

Добавление участника в группу пользователей.

Параметры метода:
- grpCode — код группы пользователей. String
- memberUUID — UUID участника группы пользователей: сотрудника, команды, отдела
api.security.removeMemberFromGroup(grpCode, memberUUId)

Удаление участника из группы пользователей.

Параметры метода:
- grpCode — код группы пользователей. String
- memberUUID — UUID участника группы пользователей: сотрудника, команды, отдела

api.serviceTime Работа с классами обслуживания

api.serviceTime.getExclusions (serviceTimeUuid)

Получение уже существующих исключений класса обслуживания.

Параметр метода:
- serviceTimeUuid — uuid класса обслуживания. String
Возвращает список исключений для заданного класса обслуживания List<IServiceTimeExclusion>.

Пример:

api.serviceTime.getExclusions('servicetime$2204')
api.serviceTime.activateDraft(serviceTimeUuid)

Активация уже существующего черновика класса обслуживания.

Параметр метода:
- serviceTimeUuid — uuid класса обслуживания. String
Пример:

api.serviceTime.activateDraft('servicetime$2204');
api.serviceTime.createExclusionApproved(serviceTimeUuid, exclusionDate)

api.serviceTime.createExclusionApproved(serviceTimeUuid, exclusionDate, startTime, endTime)

Создание исключения в классе обслуживания и активация черновика класса обслуживания.

Параметры:
- serviceTimeUuid — uuid класса обслуживания. String
- exclusionDate — дата исключения. Date
- startTime — время начала периода исключения (количество мс с начала дня). Long
- endTime — время окончания периода исключения (количество мс с начала дня). Long
Возвращает созданное исключение.

Пример. Создание исключения для класса обслуживания
Copy
```
// Дата создания исключения
String theDate = "19/10/2010";
def newdate = new Date().parse("d/M/yyyy", theDate);
// Время начала исключения
def theStartTime = "16:00 UTC";
def startTime = new Date().parse("H:m z", theStartTime).getTime();
// Время окончания исключения
String theEndTime = "19:00 UTC";
def endTime = new Date().parse("H:m z", theEndTime).getTime();
// Создание исключения класса обслуживания 'servicetime$2204' на дату newdate с startTime до endTime
def exclusion = api.serviceTime.createExclusionApproved('servicetime$2204', newdate, startTime, endTime);
```
api.serviceTime.createExclusion(serviceTimeUuid, exclusionDate)

api.serviceTime.createExclusion(serviceTimeUuid, exclusionDate, startTime, endTime)

Создание исключения в классе обслуживания без активации черновика класса обслуживания.

Параметры метода:
- serviceTimeUuid — uuid класса обслуживания. String
- exclusionDate — дата исключения. Date
- startTime — время начала периода исключения (количество мс с начала дня). Long
- endTime — время окончания периода исключения (количество мс с начала дня). Long
Возвращает созданное исключение.
api.serviceTime.editExclusionApproved(exclusionUuid, startTime, endTime)

Создание периода исключения в классе обслуживания и активация черновика класса обслуживания.

Параметры метода:
- serviceTimeUuid — uuid класса обслуживания. String
- startTime — время начала периода исключения (количество мс с начала дня). Long
- endTime — время окончания периода исключения (количество мс с начала дня). Long
Возвращает созданное исключение.

Пример. Изменение периода исключения в существующем исключении класса обслуживания:
Copy
```
String theStartTime = "20:15 UTC";
def startTime = new Date().parse("H:m z", theStartTime).getTime();
String theEndTime = "21:30 UTC";
def endTime = new Date().parse("H:m z", theEndTime).getTime();
api.serviceTime.editExclusionApproved('srvTimeExcl$6202', startTime, endTime);
```
api.serviceTime.editExclusion(exclusionUuid, startTime,endTime)

Создание периода исключения в классе обслуживания без активации черновика класса обслуживания.

Параметры метода:
- serviceTimeUuid — uuid класса обслуживания. String
- startTime — время начала периода исключения (количество мс с начала дня). Long
- endTime — время окончания периода исключения (количество мс с начала дня). Long
Возвращает созданное исключение.

Получение параметров исключения:

getUuid() — uuid исключения класса обслуживания;
getId() — id исключения класса обслуживания;
getExclusionDate() — дата исключения класса обслуживания;
getStartTime() — время начала периода исключения;
getEndTime() — время окончания периода исключения

Пример. Создание исключения для класса обслуживания:

Copy

// Дата создания исключения
String theDate = "19/10/2010";
def newdate = new Date().parse("d/M/yyyy", theDate);
// Время начала исключения
def theStartTime = "16:00 UTC";
def startTime = new Date().parse("H:m z", theStartTime).getTime();
// Время окончания исключения
String theEndTime = "19:00 UTC";
def endTime = new Date().parse("H:m z", theEndTime).getTime();
// Создание исключения класса обслуживания 'servicetime$2204' на дату newdate с startTime до endTime
def exclusion = api.serviceTime.createExclusionApproved('servicetime$2204', newdate, startTime, endTime);
// Информация о созданном классе обслуживания (время начала, время окончания, uuid, id, дата исключения)
def info = "Created exclusion: Date: " + exclusion.getExclusionDate() + "Uuuid: "
exclusion.getUuid() + " id: " + exclusion.getId()

api.silentMode Работа с Silent Mode

api.mail.silentMode

Проверка, включен ли режим Silent Mode:

Для проверки текущего состояния режима Silent Mode рекомендуется использовать api.silentMode.isSilent().

Пример:
```
if (api.mail.silentMode)
{
return "SilentMode enabled"
}
return  "SilentMode disabled"
```
api.silentMode.isSilent()

Проверка текущего состояния режима Silent Mode.

Возвращает:
- true — если режим Silent Mode включен;
- false — если режим Silent Mode выключен
api.silentMode.getSuitableIPs()

Получение набора исключений:

Возвращает множество IP-адресов, c которыми система может взаимодействовать при включенном режиме Silent Mode.
api.silentMode.setNotSilent()

Выключение режима Silent Mode
api.silentMode.setSilent()

Включение режима Silent Mode
api.silentMode.setSilent(ips)

Включение режима Silent Mode и определение набора исключений.

Параметр метода:
- ips — IP-адреса, через "," (запятую), каждый адрес в одинарных кавычках. String
  
  Например, api.silentMode.setSilent('11.222.3.44','55.777.88.99').
Возвращает множество IP-адресов, c которыми система может взаимодействовать при включенном режиме Silent Mode.
api.silentMode.setSuitableIPs(ips)

Определение набора исключений.

Параметр метода:
- ips — IP-адреса, через "," (запятую), каждый адрес в одинарных кавычках. String
  
  Например, api.silentMode.setSuitableIPs('11.222.3.44','55.777.88.99')
Возвращает множество IP-адресов, c которыми система может взаимодействовать при включенном режиме Silent Mode.
api.silentMode.useLegacy(use)

Включение или отключение использования режима Silent Mode только для блокирования отправки оповещений и обработки входящей почты.

Возвращает:
- true — режим Silent Mode используется только для блокирования почтовых серверов;
- false — иначе.

api.sms Отправка SMS

Для работы с методом api.sms необходимо подключение к SMS-центру, параметры подключения указываются в конфигурационном файле dbaccess.properties.

Отправка SMS-сообщений

Методы api.sms выполняют валидацию аргументов from и text. Также данная группа методов выполняет исправление аргумент phone. Если номер телефона начинается не с "+7" или "8", то в начало номера будет добавлен код страны - "+7".

api.sms.sendSms(from, phone, text)

Отправка SMS-сообщения до 127 символов, см. Оповещение по SMS.

Параметры метода:
- from — автор сообщения, не более 20 байтов. String
- phone — номер телефона, на который будет отправлено сообщение. String
- text — текст сообщения, не более 127 символов. String
В случае, если from или text превышают ограничения или произошла ошибка при отправке сообщения, обрабатывается исключение.
api.sms.sendLargeSms(from, phone, text)

Отправка длинного SMS-сообщения до 400 символов.

Параметры метода:
- from — автор сообщения, не более 20 байтов. String
- phone — номер телефона, на который будет отправлено сообщение. String
- text — текст сообщения, не более 400 символов. String
В случае, если from или text превышают ограничения или произошла ошибка при отправке сообщения, обрабатывается исключение.

Отправка SMS-сообщений без валидации

api.sms.createSmsMessage(phone, text)

Создание и отправка SMS-сообщения.

Параметры метода:
- phone — номер телефона, на который будет отправлено сообщение. String
- text — текст сообщения. String
Пример:
```
def message = api.sms.createSmsMessage('71234567890', 'Text')
message.setFrom('Author')
api.sms.sendSms(message)
```
api.sms.createSmsMessage(smsMessage)

Создание и отправка SMS-сообщения.

Интерфейс ISmsMessage позволяет задавать следующие параметры через следующие методы:
- setTo(to) — номер телефона, на который будет отправлено сообщение. String;
- setFrom(from) — отправитель сообщения. String;
- setText(text) — текст сообщения. String;
- setCompressed(isCompressed)) — сжатие сообщения, Boolean, если true (по умолчанию) — сжатое сообщение.

Дополнительные параметры отправки SMS-сообщений

api.sms.setSourceAddrNpi(sourceAddrNpi)

Установка значения параметра "Идентификатор плана нумерации отправителя" — source_addr_npi(NumberingPlanIndicator).

Параметр метода:
- sourceAddrNpi — устанавливаемое значение параметра. int
  
  Возможные значения:
  - 0 — Unknown
  - 1 — ISDN (E163/E164)
  - 2 — Data (X.121)
  - 3 — Telex (F.69)
  - 4 — Land Mobile (E.212)
  - 5 — National
  - 6 — Private
  - 7 — ERMES
  - 8 — Internet (IP)
  - 9 — WAP Client Id (его должен определять WAP Forum)
api.sms.setSourceAddrTon(sourceAddrTon)

Установка значения параметра "Тип номера отправителя" — source_addr_ton(TypeOfNumber).

Параметр метода:
- sourceAddrTon — устанавливаемое значение параметра. int
  
  Возможные значения:
  - 0 — Неизвестный (Unknown)
  - 1 — Международный (International)
  - 2 — Государственный (National)
  - 3 — Сетевой Специальный (Network Specific)
  - 4 — Номер Абонента (Subscriber Number)
  - 5 — Алфавитно-цифровой (Alphanumeric)
  - 6 — Сокращенный (Abbreviated)

api.soap Формирование запросов к SOAP сервисам

api.soap.addAttachment(soapMessage, contentId, mimeType, is)

Добавление вложения к SOAP-сообщению.

Параметры метода:
- soapMessage — SOAP-сообщение. SOAPMessage;
- contentId — имя вложения. String;
- mimeType — тип вложения. String;
- is — контент вложения в виде InputStream
Возвращает SOAP-сообщение с вложением.
api.soap.addWsSecurityHeader(soapMessage, login, password)

Добавление заголовка wsse:Security к SOAP-сообщению.

Параметры метода:
- soapMessage — SOAP-сообщение. SOAPMessage;
- login — логин. String;
- password — пароль. String.
Возвращает SOAP-сообщение с заголовком.

api.soap.buildSoapMessage(is)

Создание SOAP-сообщения (1).

Параметр метода:

is — содержимое SOAP-сообщения в виде InputStream.

Возвращает SOAP-сообщение.

Пример:

import java.nio.charset.StandardCharsets
def soapMessageBody = '''...'''
def soapMessage = api.soap.buildSoapMessage(new ByteArrayInputStream(soapMessageBody.getBytes(StandardCharsets.UTF_8)))
api.soap.sendRequest('someUrl', soapMessage)

api.soap.buildSoapMessage(soapMessage)

Создание SOAP-сообщения (2).

Параметр метода:
- soapMessage — содержимое SOAP-сообщения. String.
Возвращает SOAP-сообщение.

Пример:
```
def soapMessageBody = '''...'''
def soapMessage = api.soap.buildSoapMessage(soapMessageBody)
api.soap.sendRequest('someUrl', soapMessage)
```
api.soap.getAttachment(soapMessage, contentId)

Получение содержимого вложения из SOAP-сообщения по его идентификатору.

Параметры метода:
- soapMessage — SOAP-сообщение. SOAPMessage;
- contentId — идентификатор вложения. String.
Возвращает содержимое вложения в виде InputStream.
api.soap.getSOAPMessageAsInputStream(soapMessage)

Преобразование SOAP-сообщение в InputStream.

Параметры метода:
- soapMessage — SOAP-сообщение. SOAPMessage.
Возвращает SOAP-сообщение в виде InputStream.
api.soap.getSOAPMessageAsString(soapMessage)

Преобразование SOAP-сообщение в строку.

Параметр метода:
- soapMessage — SOAP-сообщение. SOAPMessage.
Возвращает SOAP-сообщение в виде строки.
api.soap.sendRequest(url, is)

api.soap.sendRequest(url, is, timeout)

Выполнение SOAP запроса (1).

Параметры метода:
- url — ссылка на WSDL сервер. String;
- is — содержимое SOAP-сообщения в виде InputStream;
- timeout — таймаут в секундах, после которого выполнение soap-запроса будет принудительно прервано. Long.
Возвращает ответ на запрос в виде InputStream.

Пример: Выполнить SOAP запрос к сервису http://example.com/soap.wsdl с использованием содержимого строки string в качестве тела запроса:
```
def url = 'http://example.com/soap.wsdl'
def is = new ByteArrayInputStream(string.getBytes());
api.soap.sendRequest(url, is)
```
api.soap.sendRequest(url, message)

api.soap.sendRequest(url, message, timeout)

Выполнение SOAP запроса (2).

Параметры метода:
- url — ссылка на WSDL сервера. String;
- message — SOAP-запрос. SOAPMessage;
- timeout — таймаут в секундах, после которого выполнение soap-запроса будет принудительно прервано (long)
Возвращает ответ на запрос.
api.soap.sendRequest(url, message, canThrows)

api.soap.sendRequest(url, message, canThrows, timeout)

Выполнение SOAP запроса (3).

Параметры метода:
- url — ссылка на WSDL сервера. String;
- message — SOAP-запрос. SOAPMessage;
- canThrows — указывает, можно ли бросать исключения при получении SOAPFault. Boolean;
- timeout — таймаут в секундах, после которого выполнение soap-запроса будет принудительно прервано. Long
Возвращает ответ на запрос.

Если canThrows == true и получен SOAPFault, то будет выброшено исключение {@link FxExcepton} с содержимым fault.

api.string Утилитарные методы для работы со строками

Для работы со строками рекомендуется использовать возможности языка groovy.

Преобразования строки

api.string.concat(separator, strs)

Соединяет непустые строки через разделитель.

Параметры метода:
- separator — разделитель;
- strs — коллекция строк
Пример:

api.string.concat(", ", ["a", "", "c", "d", null]) == "a, c, d"
api.string.trim(str)

Удаляет пробелы (непечатаемые символы) в начале и конце строк. Непечатаемыми считаются символы с кодом меньшим или равным 'U+0020', в соответствии документацией Java метода trim().

Параметр метода:
- str — строка
Примеры:

api.string.trim(" abc ") == "abc"

api.string.trim([" a ", "b", "c ", " d"]) == ["a", "b", "c", "d"]

api.string.trim(null) == null
api.string.replace(str, from, to)

Заменяет части строки.

Параметры метода:
- str — строка
- from — заменяемая часть строки
- to — новая часть строки
Примеры:

api.string.replace("Маша ела раму", "ела", "съела") == "Маша съела раму"

api.string.replace(null, "ела", "съела") == null
api.string.htmlToText(html)

Преобразует HTML в текст согласно следующим правилам:
- html-теги удаляются;
- специальные символы заменяются на специальные теги: "<" → "<", "\"" → """, "&" → "&", ">" → ">";
- тег <br> интерпретируется как перевод строки
api.string.toMap(str, pairDelimiter, keyValueDelimiter)

Используется для обработки автоматически сформированных писем, в которых в теме или теле содержатся значения заранее известных атрибутов, разделенные спецсимволом.

Параметры метода:
- str — исходная строка
- pairDelimiter — разделитель пары. String
- keyValueDelimiter — разделитель ключа и значения. String
Возвращает список, где каждая пара атрибутов отделена друг от друга разделителем pairDelimiter, а ключ и значение отделены друг от друга разделителем keyValueDelimiter

Получение части строки

api.string.getDomain(email)

Получение домена из email-адреса.

Параметр метода:
- email — email-адрес. String
Возвращает подстроку строки email с первого символа после символа "@" до конца строки или пустую строку, если символ "@" не найден.
api.string.getMailbox(email)

Получение почтового ящика из email-адреса.

Параметр метода:
- email — email-адрес. String
Возвращает подстроку строки email с первого символа до символа "@" или всю строку, если символ "@" не найден.
api.string.getFileExtension(filename)

Получение расширения по имени файла.

Параметр метода:
- email — filename — имя файла. String
Возвращает подстроку строки filename после последнего символа "." до конца строки или пустую строку, если символ "." не найден.
api.string.getFileName(filename)

Получение собственного имени файла (без расширения).

Параметр метода:
- filename — имя файла. String
Возвращает подстроку строки filename с первого символа до последнего символа "." (исключительно) или всю строку filename, если символ "." не найден.
api.string.getTextBeforeDelimiterAsHtml(htmlBody, delimiter)

Получение фрагмента html документа до разделителя.

Параметры метода:
- htmlBody — параметр htmlBody. String;
- delimiter — разделитель. String
Возвращает:
- Валидный html — часть параметра htmlBody, находящаяся до разделителя delimiter;
- Весь htmlBody, если разделитель не найден;
- Пустая строка, если параметр htmlBody - null или пустая строка
api.string.notEmpty(strs)

Возвращает непустые строки коллекции.

Параметр метода:
- strs — коллекция строк
Примеры:

api.string.notEmpty(["a", "", "b", "c"]) == ["a", "b", "c"]

api.string.notEmpty(null) == null

Проверки строк

api.string.isEmpty(str)

Проверяет строку на пустоту.

Параметр метода:
- str — проверяемая строка
Возвращает:
- true — если строка null или не содержит ни одного символа,
- false — в остальных случаях.
Примеры:

api.string.isEmpty("") == true

api.string.isEmpty(null) == true

api.string.isEmpty("hgsdaj") == false
api.string.isEmptyTrim(str)

Проверяет строку на пустоту.

Параметры метода:
- str — проверяемая строка
Возвращает:
- true — если строка null, не содержит ни одного символа или состоит из одних непечатаемых символов (непечатаемыми считаются символы с кодом меньшим или равным 'U+0020', в соответствии документацией Java метода trim());
- false — в остальных случаях.
Примеры:

api.string.isEmptyTrim("") == true

api.string.isEmptyTrim(null) == true

api.string.isEmptyTrim(" ") == true

api.string.isEmptyTrim("hgsdaj") == false
api.string.contains(str, s)

Проверяет наличие подстроки в строке.

Параметры метода:
- str — строка;
- s — проверяемая подстрока
Примеры:

api.string.contains("Маша ела кашу", "ела") == true

api.string.contains("Маша ела кашу", "съела") == false

api.string.contains(null, "съела") == false
api.string.containsAnyFromCollection(str, substrCollection)

Проверяет наличие в строке хотя бы одной строки из коллекции.

Параметры метода:
- str — строка;
- substrCollection — коллекция строк
Возвращает:
- true — строка str содержит в качестве подстроки хотя бы одну строку из substrCollection;
- false — в остальных случаях
Примеры:

api.string.containsAnyFromCollection("str", ["qwe", "rty", "str"]) == true

api.string.containsAnyFromCollection("str", ["qwe", "rty", "zxc"]) == false
api.string.containsAnyFromCollectionIc(str, substrCollection)

Проверяет наличие в строке хотя бы одной строки из коллекции без учета регистра.

Параметры метода:
- str — строка;
- substrCollection — коллекция строк
Возвращает:
- true — строка str содержит в качестве подстроки хотя бы одну строку из substrCollection;
- false — в остальных случаях
Примеры:

api.string.containsAnyFromCollectionIc("str", ["qWe", "Rty", "Str"]) = true

Поиск числа или слова в строке

api.string.findByRegExp(str, regexp)

api.string.findByRegExp(str, regexp, flags)

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

Параметры метода:
- str — строка, в которой производится поиск;
- regexp — строка искомого регулярного выражения (например, "# (\d\d-\d\d-\d\d)");
- flags — строка флагов, определяющих способ сопоставления с регулярным выражением regexp, необязательный параметр.
  
  Примеры флагов:
  - (?i) — сопоставление без учета регистра;
  - (?m) — многострочный режим.
  Полный список возможных флагов приведен в документации Oracle (раздел "Embedded Flag Expressions").
Возвращает строку-результат поиска:
- Первая подстрока строки str, соответствующую регулярному выражению regexp.
- Первая подстрока строки str, соответствующую регулярному выражению regexp с флагами flags.
- null, если соответствий регулярному выражению regexp не найдено.
Пример 1. Поиск в строке по регулярному выражению:

В теле письма может присутствовать код заявки с префиксом NN. Необходимо в теле письма найти номер, например, NN 0123456789.
```
def rawText = ' 01234 Текст NN 0123456789 Текст'
def text = api.string.findByRegExp(rawText, /NN \d+/) //ищем число с префиксом NN
def finalText = api.string.findByRegExp(text, /\d+/) //ищем первое число
```
Пример 2. Поиск в строке по регулярному выражению с использованием флагов:
Copy
```
api.string.findByRegExp('Script with some strings', "script", "(?i)")
```
api.string.find(str, prefix, format)

Поиск числа, слова, подстроки в строке после префикса. Вместо этого метода рекомендуется использовать метод api.string.findByRegExp.

Параметры метода:
- str — строка, в которой производится поиск;
- prefix — строка, которая предшествует искомому значению;
- format — элемент списка "number", "word", "string"
Возвращает строку-результат поиска (при поиске учитывается регистра префикса).

Если префикс в строке найден, то:
- format = "number": первое число, найденное в строке str, идущее после строки-префикса prefix
- format = "word": первое слово (т.е. подстрока из цифр и букв), найденное в строке str, идущее после строки-префикса prefix
- format = "string": подстрока строки str, начиная с первого символа после строки-префикса prefix и null, если ничего не найдено
Если префикс в строке не найден, то:
- format = "number":
  - если в строке есть числа, то выводится первое число;
  - если в строке чисел нет, то выводится пустая строка.
- format = "word":
  - если в строке есть слова/числа, то выводится первое слово/число;
  - если в строке слов/чисел нет, то выводится пустая строка.
- format = "string":
  - если в строке есть символы, то возвращаются все символы строки, кроме пробелов в начале строки;
  - если строка пустая, то выводится пустая строка.

api.structure. Работа со структурами

Методы получения информации о структурах

api.structure.getAllStructures()

Получение списка всех структур объектов, зарегистрированных на сервере.

Возвращает: список кодов и названий структур List<ISDtObject>

Пример: Получить первую структуру, ее облегченный вариант, содержит только code, name
```
def structLight = api.structure.getAllStructures()[0]
def structureTitle = structLight.name
def structureCode = structLight.code
```
api.structure.getStructure(structureCode)

Получение информации о структуре.

Параметр метода:
- structureCode — код структуры. String
Возвращает информацию о структуре: код, название, описание структуры и перечисление элементов структуры. Для каждого элемента структуры указывается его код структуры, код элемента и название.

Пример: Получить полную информацию о структуре, содержит code, name, description, items
Copy
```
def struct = api.structure.getStructure(structureCode)
structureCode = struct.code
structureTitle = struct.name
def description = struct.description
def lightItems = struct.items //это список ISDtObject, каждый элемент содержит: code, codeStructure, name
def codeStruct = lightItems[0].codeStructure
def nameItem = lightItems[0].name
def codeItem = lightItems[0].code
```
api.structure.getStructure(lightStructure)

Получение подробной информации о структуре.

Параметр метода:
- lightStructure — облегченная структура, содержит только код и название. ISDtObject
Возвращает подробную информацию о структуре: код, название, описание структуры и перечисление элементов структуры. Для каждого элемента структуры указывается его код структуры, код элемента и название.

Пример: Получить полную информацию о структуре, содержит code, name, description, items

def struct = api.structure.getStructure(structLight)
api.structure.getStructureItem(structureCode, elementCode)

Получение подробной информации об элементе структуры.

Параметры метода:
- structureCode — код структуры. String
- elementCode — код элемента структуры. String
Возвращает информацию об элементе структуры:
- код элемента структуры;
- название элемента структуры;
- код структуры и код элемента родительского элемента;
- классы (как объектов api.metainfo.metaClass), которые указаны в параметре "Объекты";
- атрибут (как объект api.metainfo.getAttribute), который указан в параметре "Атрибут связи";
- группа атрибутов (как объект api.metainfo.getAttributeGroup), которая указана в параметре "Группа атрибутов";
- значение логического признака "Показывать объекты, вложенные во вложенные".
Пример: Получить полную информацию об элементе структуры, содержит: code, metaClasses, attributeGroup, name, parentStructureCode, attribute, parentItemCode
Copy
```
def structItem = api.structure.getStructureItem(structureCode, lightItems[0].code)
codeItem = structItem.code
def firstMetaclassCode = structItem.metaClasses[0].code
def attrGroupCode = structItem.attributeGroup.code
def attrFqn = structItem.attribute.fqn
def parentItemCode = structItem.parentItemCode
```
api.structure.getStructureItem(lightStructureElement)

Получение подробной информации об элементе структуры.

Параметр метода:
- lightStructureElement — облегченный элемент структуры, содержит только код и название. ISDtObject
Возвращает информацию об элементе структуры:
- код элемента структуры;
- название элемента структуры;
- код структуры и код элемента родительского элемента;
- классы (как объектов api.metainfo.metaClass), которые указаны в параметре "Объекты";
- атрибут (как объект api.metainfo.getAttribute), который указан в параметре "Атрибут связи";
- группа атрибутов (как объект api.metainfo.getAttributeGroup), которая указана в параметре "Группа атрибутов";
- значение логического признака "Показывать объекты, вложенные во вложенные".
Пример: Получить полную информацию об элементе структуры, содержит: code, metaClasses, attributeGroup, name, parentStructureCode, attribute, parentItemCode

def strItem = api.structure.getStructureItem(struct.items[0])

Методы получения данных по структуре

api.structure.getObjectParentsAndChildren(objectUuid, structureCode, limitParentAndChildren, itemCode)

Получение родителей и детей заданного объекта в указанной структуре иерархии.

Параметры метода:
- objectUuid — uuid объекта. String
- structureCode — код структуры. String
- limitParentAndChildren — ограничение на количество родительских и дочерних получаемых объектов (необязательный параметр). Integer
- itemCode — код элемента структуры (необязательный параметр). String
Возвращает список дочерних и список родительских uuid.

Пример:

def parent = api.structure.getObjectParentsAndChildren('ou$7107', 'OrgstrukturaSDvumyaRoditelyami',5).getParent()

def children = api.structure.getObjectParentsAndChildren('ou$7101', 'OrgstrukturaSDvumyaRoditelyami',5).getChildren()
api.structure.getObjectParentsAndChildren(objectUuid, structure, limitParentAndChildren, itemCode)

Получение родителей и детей заданного объекта в указанной структуре иерархии.

Параметры метода:
- objectUuid — uuid объекта. String
- structure — объект структура. ISDtObject
- limitParentAndChildren — ограничение на количество родительских и дочерних получаемых объектов (необязательный параметр). Integer
- itemCode — код элемента структуры (необязательный параметр). String
Возвращает список дочерних и список родительских uuid.

Пример 1:

structLight = api.structure.getAllStructures()[0]

def parent = api.structure.getObjectParentsAndChildren('ou$7107', structLight).getParent()

Пример 2:
```
def structLight = api.structure.getAllStructures()[0]
def struct = api.structure.getStructure(structLight)
def strItemLight = api.structure.getStructureItem(struct.items[0])
def parent = api.structure.getObjectParentsAndChildren('ou$7101', structLight, 5, strItemLight).getChildren()
```

api.systemUtils. Быстрое редактирование объектов

Использование методов быстрого редактирования объектов может привести к нестабильности системы. По возможности старайтесь использовать обычные методы редактирования!
Используйте методы быстрого редактирования объектов очень аккуратно и внимательно, так как происходит редактирование напрямую в базе данных и далеко не все проверки, которые реализованы при помощи стандартной бизнес-логики, реализованы в этих методах.
При вызове данных методов действия по событию не выполняются. Запись в историю событий отмечается кодом категории: fastEdit.

Допустимо использовать данный метод для сохранения большого числа ссылок на бизнес-объектов, а для примитивных типов (текст, числа, даты) рекомендуется использовать стандартный utils.edit

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

api.systemUtils.fillAttrsDirect(object, attrValue)

api.systemUtils.fillAttrsDirect(object, attrCode, attrValue)

Редактирование атрибутов объекта напрямую в базе. Можно редактировать сразу несколько атрибутов.

Метод предназначен для редактирования атрибутов типа: строка, текст, текст в формате RTF, набор ссылок на БО, ссылка на БО, обратная ссылка, целое число, логический, элемент справочника, набор элементов справочника, гиперссылка, временной интервал, вещественное число, набор типов класса, дата, дата/время.

Коды атрибутов, запрещенных для редактирования: removed, removalDate, creationDate, lastModifiedDate, serviceTime, clientOU, clientEmployee, clientTeam, agreement, service, timeZone, stateStartTime, registrationDate, requestDate, wfProfile, massProblem, massProblemSlaves, masterMassProblem, hasMasterProblem, resolutionTime, deadLineTime, folders, UUID, clientLinkName, parent.

Параметры метода:
- object — UUID объекта или сам объект, который необходимо редактировать;
- attrCode — код атрибута, значение которого меняется;
- attrValue — ассоциативный список кодов изменяемых атрибутов и устанавливаемых значений.
Результат выполнения метода: изменяются указанные значения атрибутов. Для атрибутов типа "Набор ссылок на БО", "Набор элементов справочника" и "Обратная ссылка" метод добавляет указанные значения к уже существующим значениям этого атрибута.

Метод возвращает null если:
- атрибут не принадлежит к типам, разрешенным для редактирования данным методом;
- значение атрибута является вычислимым, составным, вычисляется по таблице соответствий, определяется по правилу формирования номера или по правилу именования;
- выполняется попытка изменить значение атрибута, запрещенного для редактирования.
api.systemUtils.removeBOLinksDirect(object, attrCode, objsToRemove)

Удаление указанных объектов из значений атрибута типа "Набор ссылок на БО", "Набор элементов справочника" и "Обратная ссылка"
- Параметры метода:
  - object — объект или его UUID;
  - attrCode — код атрибута, значение которого меняется;
  - objsToRemove — объекты или их UUID, которые необходимо удалить из значения атрибута.

api.timing Работа с временными характеристиками и счетчиками времени

Временные характеристики

Методы используются в скриптах счетчиков времени, см. Скрипт счетчика времени

api.timing.serviceStartTime(serviceTime, timeZone)

Получение ближайшей даты начала обслуживания (1).

Параметры метода:
- serviceTime — код элемента справочника "Классы обслуживания"
- timeZone — код элемента справочника "Часовые пояса"
Возвращает ближайшее время начала обслуживания (на основе текущей даты).
api.timing.serviceStartTime(startDateTime, serviceTime, timeZone)

Получение ближайшей даты начала обслуживания (2).

Параметры метода:
- startDateTime — дата, к которой необходимо найти ближайшее время начала периода обслуживания
- serviceTime — код элемента справочника "Классы обслуживания"
- timeZone — код элемента справочника "Часовые пояса"
Возвращает ближайшее время начала обслуживания, на основе указанной даты (startDateTime).

Пример. Скрипт, определяющий попадает ли текущая дата в рабочее время.
Copy
```
def serviceCall = ... //берем запрос
def startDateTime = new Date() //берем текущую дату
def serviceStartTime = api.timing.serviceStartTime(startDateTime, serviceCall.serviceTime, serviceCall.timeZone) //вычисляем от нее ближайшую дату начала обслуживания
if(startDateTime == serviceStartTime)
{
//дата попадает в рабочее время
}
else
{
//дата попадает в НЕ рабочее время
}
```
api.timing.serviceEndTime(serviceTime, timeZone, startTime, interval)

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

Параметры метода:
- serviceTime — элемент или код элемента справочника "Классы обслуживания"
- timeZone — элемент или код элемента справочника "Часовые пояса"
- startTime — время, от которого необходимо начать отсчитывать период обслуживания
- interval — период обслуживания (количество миллисекунд, целое число)
"serviceTime" и "timeZone" либо оба являются кодом элемента справочника, либо оба — элементы справочника

Возвращает время окончания обслуживания.
api.timing.serviceTime(serviceTime, timeZone, startTime, endTime)

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

Параметры метода:
- serviceTime — элемент или код элемента справочника "Классы обслуживания"
- timeZone — элемент или код элемента справочника "Часовые пояса"
- startTime — время, от которого необходимо начать отсчитывать период обслуживания
- endTime — время окончания периода обслуживания
Возвращает регламентный период обслуживания в миллисекундах.

Счетчики времени

api.timing.timerDefinition(fqn, attrCode)

Получение описания счетчика времени, используемого в атрибуте.

Параметры метода:
- fqn — fqn класса, содержащего атрибут-счетчик
- attrCode — код атрибута типа "Счетчик времени" (прямой или обратный), для которого нужно получить описание.
Параметры счетчика времени, полученного при помощи метода api.timing.timerDefinition:
- timerDef.getCode() — Код счетчика
- timerDef.getTitle() — Название счетчика
- timerDef.getDescription() — Описание счетчика
- timerDef.getResolutionTimeAttribute() — Код атрибута, выбранного в поле "Промежуток времени" счетчика
- timerDef.getServiceTimeAttribute() — Код атрибута, выбранного в поле "Класс обслуживания" счетчика
- timerDef.getTimeMetric() — Код атрибута, выбранного в поле "Метрика времени" счетчика
- timerDef.getTimeZoneAttribute() — Код атрибута, выбранного в поле "Часовой пояс" счетчика
- timerDef.isRemoved() — Признак архивности счетчика
- timerDef.isSystem() — Является ли счетчик системным.
api.timing.parseDate(text)

Формирование даты по текстовому представлению.

Возвращает дату по тексту в формате "dd.MM.yyyy HH:mm:ss"

Работа с календарными датами, с учетом класса обслуживания

api.timing.addWorkingDays(date, amountOfDays, serviceTime, timeZone)

Добавление рабочих дней к текущей дате (отнимание рабочих дней от текущей даты).

Параметры метода:
- date — дата /дата-время, к которой применяется перерасчет. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате.
  
  Для корректной работы метода в формате "дата" должен быть указан часовой пояс, который будет передан в параметре timeZone.
  
  Если часовой пояс не указан, то дата будет рассчитываться в часовом поясе сервера.
  
  Пример формата с указанием часового пояса:
```
String strDate = "28/10/2023 22:00:00 +0500"
def myDate = new Date().parse("d/M/yyyy H:m:s Z", strDate)
```
- amountOfDays — количество добавляемых рабочих дней (целое положительное число), количество отнимаемых рабочих дней (целое отрицательное число).
- serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
- timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.
Возвращает пересчитанное значение даты-времени.

Особенности работы метода:
- Если время в полученном дне недоступно, то функция вернет значение в зависимости от параметра amountOfDays:
  - amountOfDays > 0, функция вернет первую секунду следующего рабочего периода;
  - amountOfDays < 0, функция вернет последнюю секунду предшествующего рабочего периода.
  Например, в системе задан класс обслуживания с периодами обслуживания пн-пт с 9:00 до 14:00 и с 15:00 до 18:00.
  
  На вход в метод передана пятница 14:30, к ней прибавлен 1 рабочий день. Будет получен понедельник 14:30. Но это время не попадает в период обслуживания, поэтому метод вернет первую секунду следующего рабочего периода, т.е. понедельник 15:00.
- Если в метод переданы дата-время начала/конца рабочего дня, то результат работы метода сдвигается на 1 рабочий день от искомого.
  
  Например, для вторника, 23 апреля 09:00:00, результатом вычитания одного дня будет не понедельник, 22 апреля 09:00:00, а пятница, 19 апреля 17:00:00:
  Copy
```
def serviceTime = utils.findFirst('serviceCall', [:]).serviceTime
def timeZone = utils.findFirst('serviceCall', [:]).timeZone

String theDate = "23/04/2024"
def date = new Date().parse("d/M/yyyy", theDate)

use(groovy.time.TimeCategory){
def startToday =  api.timing.getStartOfWorkingDay(date, serviceTime, timeZone) //Tue Apr 023 09:00:00 MSK 2024
def startPrevWorkDay = api.timing.addWorkingDays(startToday, -1, serviceTime, timeZone) //Fri Apr 19 17:00:00 MSK 2024
}
```
  Чтобы получить искомый рабочий день (понедельник), необходимо к дате-времени, к которой применяется перерасчет, добавить 1 секунду:
  Copy
```
use(groovy.time.TimeCategory){
def startToday =  api.timing.getStartOfWorkingDay(date, serviceTime, timeZone)+ 1.second //Tue Apr 023 09:00:00 MSK 2024
def startPrevWorkDay = api.timing.addWorkingDays(startToday, -1, serviceTime, timeZone) //Mon Apr 022 09:00:01 MSK 2024
}
```
api.timing.addWorkingHours(date, amountOfHours, serviceTime, timeZone)

Добавление рабочих часов к текущей дате (отнимание рабочих часов от текущей даты).

Параметры метода:
- date — дата /дата-время, к которой применяется перерасчет. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате.
- amountOfHours — количество добавляемых рабочих часов (целое положительное число), количество отнимаемых рабочих часов (целое отрицательное число).
- serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
- timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.
Возвращает пересчитанное значение даты-времени.
api.timing.getStartOfWorkingDay(date, serviceTime, timeZone)

Получение начала рабочего дня.

Параметры метода:
- date — дата, для которой необходимо найти начало рабочего дня. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате
- serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
- timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.
Возвращаемое значение: первая рабочая секунда указанного дня. null — если день нерабочий.
api.timing.getStartOfWorkingMonth(date, serviceTime, timeZone)

Получение начала рабочего месяца.

Параметры метода:
- date — дата, для которой необходимо найти начало рабочего месяца. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате
- serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
- timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.
Возвращаемое значение: первая рабочая секунда указанного месяца. null — если месяц не содержит рабочих дней.
api.timing.getStartOfWorkingYear(date, serviceTime, timeZone)

Получение начала рабочего года.

Параметры метода:
- date — дата, для которой необходимо найти начало рабочего года. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате
- serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
- timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.
Возвращаемое значение: первая рабочая секунда указанного года. null — если год не содержит рабочих дней.
api.timing.getEndOfWorkingDay(date, serviceTime, timeZone)

Получение конца рабочего дня.

Параметры метода:
- date — дата, для которой необходимо найти конец рабочего дня. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате
- serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
- timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.
Возвращаемое значение: первая рабочая секунда указанного дня. null — если день нерабочий.
api.timing.getEndOfWorkingMonth(date, serviceTime, timeZone)

Получение конца рабочего месяца.

Параметры метода:
- date — дата, для которой необходимо найти конец рабочего месяца. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате
- serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
- timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.
Возвращаемое значение: первая рабочая секунда указанного месяца. null — если месяц не содержит рабочих дней.
api.timing.getEndOfWorkingYear(date, serviceTime, timeZone)

Получение конца рабочего года.

Параметры метода:
- date — дата, для которой необходимо найти конец рабочего года. Возможно указание значения null. Если дата не указана (передан null), то пересчет применяется к текущей дате
- serviceTime — элемент справочника "Классы обслуживания". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID
- timeZone — элемент справочника "Часовые пояса". Необходимо передавать информацию об элементе справочника в качестве объекта, но не UUID. Возможно указание значения null. Если значение параметра null, то берется часовой пояс сервера.
Возвращаемое значение: первая рабочая секунда указанного года. null — если год не содержит рабочих дней.

api.tx Работа с транзакциями

api.tx.call(closure)

Выполнение замыкания внутри новой транзакции.

Для работы с транзакциями в контексте выполнения скрипта.

Найденные объекты не рекомендуется использовать за пределами транзакции, вместо этого следует возвращать примитивные значения (строки, числа и т.д.). Если необходимо использовать объект вне транзакции, то его следует снова получить с использованием уникального признака (например, UUID).

Параметр метода:
- closure — замыкание, которое должно быть выполнено
Пример.
```
def obj1 = ...
def obj2 = ...
def closure = {
utils.edit(obj1, [ state : 'closed' ]) // первое действие ...
utils.edit(obj2, [ state : 'closed' ]) // и второе действие, будут выполнены в новой транзакции
}
api.tx.call(closure) 
```
api.tx.call

Массовое удаление объектов.

Благодаря оборачиванию действия в отдельную транзакцию и блок try-catch, ошибка на какой-либо итерации никак не повлияет на обработку остальных объектов и будет корректно обработана

Пример.
```
def objs = ...
objs.each { obj ->
  try
  {
  api.tx.call { utils.delete(obj) }
  }
  catch (e)
  {
  logger.error('...', e)
  }
}
```

api.utils Поиск объектов

utils.get (fqn, attributes)

Поиск одного объекта по коду класса (типа) объектов и его атрибутам.

Параметры метода:
- fqn — класс (тип) объекта.
- attributes — ассоциативный список значений атрибута <Код атрибута : Значение атрибута>. Могут использоваться Условные операции
Возвращаемое значение:
- конкретный объект;
- "null", если объект не найден;
- исключение, если найдено более одного объекта (обработка исключений в данном документе не рассматривается, обратитесь к документации Groovy).
Пример 1. Поиск компании:

def root = utils.get('root', [:])

Пример 2. Поиск элемента справочника "Уровни срочности" с кодом low:

def urg = utils.get('urgency', ["code": "low"])
utils.get(uuid)

Поиск одного объекта по его уникальному идентификатору (1).

Возвращаемое значение:
- конкретный объект;
- исключение, если объект не найден (обработка исключений в данном документе не рассматривается, обратитесь к документации Groovy).
utils.load(uuid)

Поиск одного объекта по его уникальному идентификатору (2):

Возвращаемое значение:
- конкретный объект;
- null, если объект не найден.
utils.find (fqn, attributes)

Поиск нескольких объектов по коду класса (типа) объектов и его атрибутам. Могут использоваться Условные операции

Параметры метода:
- fqn — класс (тип) объектов. Если указан класс объектов, поиск проводится по классу и всем вложенным типам. Если указан тип объекта, поиск проводится по типу и вложенным в него типам
- attributes — ассоциативный список значений атрибута <Код атрибута : Значение атрибута>
Возвращает коллекцию объектов (может быть пустой, но не "null").

Возвращается не сам объект, а только его идентификатор (UUID). При обращении к атрибутам найденного объекта, через его идентификатор производится поиск самого объекта, который берется из текущей сессии. Если в сессии его нет, то объект берется из базы данных.

Примечания:
- Если скрипт фильтрации может вернуть все объекты (более 500), то вместо конструкции типа:
  
  Использование utils.find в скрипте фильтрации значений атрибута при редактировании.
  
  return utils.find('class$type',[:])
  
  рекомендуется использовать конструкцию, которая значительно сократит время формирования списка объектов:
  
  return api.filtration.disableFiltration()
- Для поиска элементов коллекции с помощью метода utils.find (найти совпадение хотя бы с одним из элементов) необходимо использовать Условные операции
  
  Пример: получение списка сотрудников с фамилиями Иванов и Петров.
  
  utils.find('employee', ['lastName' : op.in('Иванов', 'Петров')])
- При проведении поиска по UUID, игнорируется все значение до $
  
  utils.find('serviceCall', ['UUID': 'location$81101'])
  
  Если "location$81101" изменить на "redSocks$81101", то возвращаемый результат не изменится.
- Работа с логическими атрибутами:
  - В системе логические атрибуты представлены как объекты java, поэтому для всех логических атрибутов значение по умолчанию = null (если не указано "Значение по умолчанию Да = вкл).
  - В базе данных хранится значение атрибута null до момента явного сохранения значения атрибута на форме редактирования в интерфейсе оператора.
  - При получении значений для системных логических атрибутов, вернется:
    - false — если в базе данных значение атрибута установлено false или null;
    - true — если в базе данных значение атрибута установлено true.
  - В случае поиска объектов, у которых логический атрибут должен иметь значение false, необходимо учитывать кейс, что в базе данных валидными вариантами являются записи, которые хранят значения false и null для этого атрибута, например, utils.find('employee',['employeeForIntegration': false, 'employeeForIntegration': null])
Пример 1. Поиск отдела по названию:

utils.find('ou', ["title" : "Название отдела"])

Пример 2. Поиск объекта по атрибуту типа "Ссылка на бизнес-объект":
```
def author = utils.get('employee$12345');
objs = utils.find('serviceCall', ["author" : author])
```
Пример 3. Поиск объектов по атрибуту типа "Ссылка на бизнес-объект" по UUID объекта:

utils.find('serviceCall', ["author" : 'employee$12345'])

Пример 4. Поиск объектов по атрибуту типа "Ссылка на бизнес-объект" по набору объектов /UUID (качестве коллекции можно использовать null):
```
def empls = ['employee$7035', 'employee$7007']
utils.find('serviceCall', ["clientEmployee" : empls])
```
Пример 5. Поиск объектов по атрибуту типа "Элемент справочника" по коду элемента справочника:

utils.find('serviceCall', ["urgency" : "low"])

Пример 6. Поиск всех элементов справочника "Уровни срочности":

utils.find('urgency', [:])

Пример 7. Поиск объектов по нескольким атрибутам (поиск запроса по автору и услуге):
```
def author = subject.author
def service = subject.service
objs = utils.find('serviceCall', ["author" : author, "service" : service])
```
utils.findFirst (fqn, attributes)

Получение первого объекта из нескольких найденных.

Параметры метода:
- fqn — класс (тип) объекта
- attributes — ассоциативный список значений атрибута <Код атрибута : Значение атрибута>.Могут использоваться Условные операции
Возвращает первый объект из нескольких найденных объектов.

Пример. Первый найденный элемент справочника "Уровни срочности":

obj = utils.findFirst('urgency', [:])
utils.findUnique(attributes)

utils.findUnique(attributes, defaultObject)

utils.findUnique(attributes, defaultObject, ignoreCase)

Поиск уникального объекта по карте атрибутов. Могут использоваться Условные операции

Параметры метода:
- attributes — ассоциативный список значений атрибута <Код атрибута : Значение атрибута>. Наличие значения с ключом 'metaClass' обязательно в карте атрибутов, иначе FxException.
- defaultObject — объект, возвращаемый по умолчанию, если поиск завершился неуспешно
- ignoreCase — признак, определяющий будет ли учитываться регистр у строковых значений. Boolean.
Возвращает:
- Найденный объект, если он является единственным с таким набором атрибутов.
- null, если объект не найден или найдено несколько объектов (если не указан defaultObject).
- defaultObject, если объект не найден или найдено несколько объектов.
Пример 1. Поиск отдела по названию:

utils.findUnique(['title' : 'sampleTitle', 'metaClass' : 'sampleClass'])

Пример 2. Поиск объекта по названию со значением по умолчанию:
```
def defaultValue = "sample";
def obj = utils.findUnique(['title' : 'sampleTitle', 'metaClass' : 'sampleClass'], defaultValue);
```
Пример 3. Поиск объекта по названию со значением по умолчанию, регистр у строковых значений не учитывается:
```
def defaultValue = "sample";
def obj = utils.findUnique(['title' : 'sampleTitle', 'metaClass' : 'sampleClass'], defaultValue, false);
```
utils.find(metaClass, sp.ignoreCase().limit(100).offset(100))

utils.find(metaClass, attrCode : 'value', sp.ignoreCase().limit(100).offset(100))

где sp (SearchParams) — параметры поиска.

Параметры поиска можно задавать в любом порядке: sp.limit(5).offset(1) = sp.offset(1).limit(5).

Отсчет элементов начинается с 0.

Внимание! нельзя использовать параметр offset() без установки параметра limit()

Пример 1. Поиск возвращает отделы с 0 по 9:

utils.find('ou', [ : ], sp.limit(10));

Пример 2. Поиск возвращает отделы с 10 по 99:

utils.find('ou', [ : ], sp.limit(100).offset(10));

Пример 3. Поиск возвращает все отделы, название которых "Отдел", независимо от регистра (ОТДЕЛ, отдел):

utils.find('ou', ['title' : 'Отдел'], sp.ignoreCase());

Пример 4. Поиск возвращает отделы с 5 по 9, название которых "Отдел", независимо от регистра (ОТДЕЛ, отдел):

utils.find('ou', ['title' : 'Отдел'], sp.limit(10).offset(5).ignoreCase());
utils.find('employee', ['employeeSecGroups' : 'код группы'])

utils.find('ou', ['ouSecGroups' : 'код группы'])

utils.find('team', ['teamSecGroups' : 'код группы'])

utils.find('employee', ['all_Group' : 'код группы'])

Получение сотрудников (отделов, команд и сотрудников) по коду группы пользователей.

Параметры метода:
- teamUserGroups — группы пользователей команды
- ouSecGroups — группы пользователей отдела
- employeeSecGroups — группы пользователей сотрудника
- all_Group — группы пользователей сотрудника, отдела, команд. Возвращает всех сотрудников, сотрудников отделов и команд

Регистрозависимость поиска (метод поиска utils.find) зависит от типа используемой СУБД: PostgresSQL и Oracle поиск регистрозависим, MS SQL поиск регистроНЕзависим.

Условные операции

Условные операции могут использоваться при выполнении методов: utils.find(), utils.findFirst(), utils.get(), utils.count(), utils.findUnique().

op.like(value)

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

Ограничение: используется для атрибутов типа "Строка", "Текст", "Текст в формате RTF". Иначе генерируется исключение.

Пример 1. Получение списка сотрудников с фамилией "Иванов":

utils.find('employee', ['lastName' : op.like('Иванов')])

Пример 2. Получение списка сотрудников, фамилия которых начинается на "Иванов":

utils.find('employee', ['lastName' : op.like('Иванов%')])
op.orEq(value1, value2, value3, ...)

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

Ограничение: минимальное количество параметров: 2, иначе генерируется исключение.

Пример 1.

utils.find('employee', ['parent' : op.orEq('ou$123321', 'ou$123322', 'ou$123323')])

Пример 2. При поиске элементов справочника по условию, в качестве набора значений атрибута parent (типа "Ссылка на бизнес-объект"), передаются UUID родительских элементов справочника или папок:

utils.find('cOCSclassific', ['parent' : op.orEq('cOCSclassific$2395602', 'cOCSclassific$2395603')])
op.not(value1, value2, value3, ...)

Поиск объектов, значение целевого атрибута которых не совпадает ни с одним из значений из списка параметров. Допустимо использование с одним параметром и с несколькими параметрами.

Примеры:

utils.find('employee', ['parent' : op.not('ou$123321')])

utils.find('employee', ['parent' : op.not('ou$123321', 'ou$123322', 'ou$123323')])
op.gt(value)

Поиск объектов, значение целевого атрибута которых больше значения указанного параметра:

Ограничение: используется для атрибутов типа "Дата", "Дата/время" и числовых атрибутов, иначе генерируется исключение.

Примеры:

utils.find('employee', ['number' : op.gt(50)])

utils.find('employee', ['date1' : op.gt(new Date().parse('yyyy-MM-dd', '2017-04-07'))])
op.lt(value)

Поиск объектов, значение целевого атрибута которых меньше значения указанного параметра.

Ограничение: используется для атрибутов типа "Дата", "Дата/время" и числовых атрибутов, иначе генерируется исключение.

Примеры:

utils.find('employee', ['number' : op.lt(50)])

utils.find('employee', ['date1' : op.lt(new Date().parse('yyyy-MM-dd', '2017-04-07'))])
op.between(value1, value2)

Поиск объектов, значение целевого атрибута которых находится в рамках между value1 и value2, включая граничные значения (value1 <= value <= value2).

Ограничение: используется для атрибутов типа "Дата", "Дата/время" и числовых атрибутов, иначе генерируется исключение.

Примеры:

utils.find('employee', ['number1' : op.between(50,60)]);

utils.find('employee',['date1' : op.between(new Date().parse('yyyy-MM-dd', '2017-04-06'), new Date().parse('yyyy-MM-dd', '2017-04-10'))])
op.eq(value)

Поиск объектов, значение целевого атрибута которых совпадает со значением параметра.

Пример.

utils.find('employee', ['parent' : op.eq('ou$123321')])
op.isNull()

Поиск объектов, значение целевого атрибута которых null или пустой список.

Пример:

utils.find('employee', ['boLink' : op.isNull()])
op.isNotNull()

Поиск объектов, значение целевого атрибута которых не null или не пустой список.

Пример:

utils.find('employee', ['boLink' : op.isNotNull()])
op.in(value1, value2, value3, ...)

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

Допустимо использование коллекции объектов в качестве единственного параметра метода: op.in(value1, value2, value3) эквивалентно op.in([value1, value2, value3]).

Ограничение: при передаче в op.in на Oracle более 1000 объектов, а на MS SQL более 2100 будет выведено сообщение об ошибке, так как в указанных базах есть ограничение на количество параметров при использовании условия вхождения значений в список.

Примеры:

utils.find('employee', ['boLink' : op.in('employee$5211', 'employee$5208')]);

utils.find('employee', ['boLink' : op.in(['employee$5211','employee$5208'])]);

utils.find('employee', ['dateTime' : op.in(new Date(1492319201000), new Date(1492319201050))])

utils.find('employee', ['timer' : op.in('a', 'e')])

api.utils Работа с объектами

Для доступа к операциям используется утилитарный метод api.utils или его короткий псевдоним utils.

Подсчет количества объектов

utils.count(fqn, attributes)

Подсчет количества объектов с определенными значениями атрибутов.

Параметры метода:
- fqn — класс (тип) объекта. Параметр может быть задан в виде строки, содержащей fqn типа/класса, или в виде объекта ClassFqn, или в виде бизнес-объекта;
- attributes — ассоциативный список значений атрибута <Код атрибута : Значение атрибута>. Могут использоваться Условные операции
Возвращает количество объектов указанного типа (класса).

Пример 1. Количество объектов с метаклассом, совпадающим с метаклассом subject и с указанным названием:

utils.count(subject.getMetainfo(), ['title':'some title'])

или

utils.count(subject, ['title':'some title'])

Пример 2. Количество сотрудников с фамилией "Петров":

utils.count('employee', ['lastName':'Петров'])

Получение коллекции объектов

utils.getObjects(uuids)

Получение коллекции объектов по коллекции uuid.

Параметр метода:
- uuids — коллекция строк — уникальных идентификаторов (UUID) объектов, которые необходимо получить.
Возвращает коллекцию объектов, однозначно соответствующих коллекции UUID, переданных в качестве аргумента.

Пример:

def objs = utils.getObjects(['serviceCall$123', 'serviceCall$321']);

Добавление объекта

utils.create(fqn, attributes)

Добавление объекта (кроме объектов служебного класса "Письмо"), метод также можно использовать для добавления комментария к объекту.

Параметры метода:
- fqn — тип создаваемого объекта для основных классов или класс создаваемого объекта для служебных классов;
- attributes — ассоциативный список кодов изменяемых атрибутов и устанавливаемых значений. Если в списке изменяемых атрибутов отсутствует атрибут создаваемого объекта, то для него используется значение по умолчанию, если оно настроено.
Пример 1. Создание объекта основного класса (не служебного):

Для добавления объекта не служебного класса необходимо указать его тип, а также словарь из кодов атрибутов и их значений:
```
utils.create('userClass$userCase', ['attribute' : 'value'])
```
или
```
utils.create('userClass', ['attribute' : 'value', 'metaClass': 'userClass$userCase'])
```
Пример 2. Создание отдела в компании:
```
def root = utils.get('root', [:]);
def ou = utils.create('ou$simple', ["title" : "Название создаваемого отдела", "parent" : root]);
```
или
```
def attrs = [:]
attrs.title = "Название создаваемого отдела"
attrs.parent = root
def ou = utils.create('ou$simple', attrs);
```

Удаление объекта

utils.delete(obj)

Удаление объекта.

Параметр метода:
- obj — удаляемый объект.
Особенности:
- При использовании метода в скрипте пользовательского действии по событию с карточки объекта, необходимо отменить обновление страницы после выполнения действия, иначе произойдет ошибка и действие будет отменено.
- Удаление объекта служебного класса "Событие" данным методом невозможно.
- Удаление объекта служебного класса "Письмо" данным методом возможно только при нахождении письма в статусе "Обработано"
Пример: скрипт для удаления объекта с карточки объекта и последующего перехода на карточку предыдущего объекта.

utils.delete(subject.UUID)

result.reload(false)

result.executeJavaScript('window.history.back()')

Подробное описание пользовательских действий см. Особенности для пользовательских событий

Создание записи в истории событий объекта

utils.event(subject, message)

Создание пользовательской записи в истории событий указанного объекта.

Параметры метода:
- subject — объект, в историю которого добавляется запись.
- message — сообщение в историю.
Пример: добавление записи "Скрипт: Naumen" в историю событий объекта subject:
```
def message = 'Naumen';
utils.event(subject, message);
```

Сравнения и проверки объектов

utils.equal(obj1, obj2)

Проверка двух объектов на равенство. Объекты сравниваются по уникальным идентификаторам.
utils.equal(objs1, objs2)

Проверка двух коллекций на равенство. Коллекции сравниваются поэлементно.

Редактирование объекта

utils.editWithoutEventActions(obj, attributes)

utils.editWithoutEventActions(obj, attributes, newTransaction)

Редактирование объекта без выполнения действий по событию.

Параметры метода:
- obj — объект или его uuid
- attributes — ассоциативный список кодов изменяемых атрибутов и устанавливаемых значений
- newTransaction — признак, определяющий следует ли запускать редактирование объекта в отдельной транзакции. Boolean
  
  Использование метода editWithoutEventActions с параметром newTransaction аналогично оборачиванию метода editWithoutEventActions без параметра в отдельную транзакцию, с использованием api.tx.call, см. api.tx Работа с транзакциями
При использовании методов editWithoutEventActions, контекстная переменная changedAttributes равна пустому списку ([]).

Экспорт объектов в электронные таблицы формата .xlsx

utils.exportObjectsToXls(fqn, attributes)

Экспорт объектов в электронные таблицы формата .xlsx, с фильтрацией по значению атрибутов. Метод экспортирует атрибуты, определенные в классе/типе, который указан в параметрах метода

Параметры метода:
- fqn — класс (тип) экспортируемых объектов
- attributes — ассоциативный массив для фильтрации объектов экспорта: ключ — код атрибута; значение — значение атрибута
Результат выполнения: Ссылка на скачивание xlsx файла. Файл доступен для всех пользователей после авторизации в приложении.

Внутри файла колонки с атрибутами сортируются в следующей последовательности:
- Системные атрибуты указанного класса/типа
- Пользовательские атрибуты указанного класса/типа
Пример 1. Выгрузка всех запросов:

utils.exportObjectsToXls('serviceCall', [:])

Пример 2. Выгрузка запросов, решенных сотрудником employee$2345:

utils.exportObjectsToXls('serviceCall', [ state : 'resolved', solvedBy : 'employee$2345' ])
utils.exportObjectsToXlsWithAllAttrs(fqn, attributes)

Экспорт объектов в электронные таблицы формата .xlsx, с фильтрацией по значению атрибутов.

Метод экспортирует:
- атрибуты, определенные в классе/типе, который указан в параметрах метода;
- атрибуты, определенные во вложенных типах, указанного класса/типа.
Параметры метода:
- fqn — класс (тип) экспортируемых объектов
- attributes — ассоциативный массив для фильтрации объектов экспорта: ключ — код атрибута; значение — значение атрибута.
Результат выполнения: Ссылка на скачивание xlsx файла. Файл доступен для всех пользователей после авторизации в приложении.

Внутри файла колонки с атрибутами сортируются в следующей последовательности:
- Системные атрибуты указанного класса/типа;
- Пользовательские атрибуты указанного класса/типа;
- Пользовательские атрибуты, определенных во вложенных типах.

Вложенные объекты

utils.getNested(obj)

Получение всех вложенных объектов (того же класса, что и родитель) на всех уровнях вложенности.

Параметр метода:
- obj — объект
Возвращает коллекцию вложенных объектов
utils.getNested(obj, parentAttrCode)

Получение вложенных объектов, если код атрибута-ссылки на родителя отличается от 'parent'.

Параметры метода:
- obj — объект;
- parentAttrCode — код атрибута-ссылки на родителя
Возвращает коллекцию вложенных объектов.
utils.isUpper(upper, obj)

Сравнение объектов в одной родительской ветке. Метод определяет, находится ли 'upper' выше по иерархии, чем 'obj'. Сравниваются объекты одного класса.

Параметры метода:
- upper — объект
- obj — объект;
Возвращает true, если объект upper находится выше по иерархии чем obj, false в остальных случаях.

Получение истории смены статуса

В системе хранится история смены статусов и ответственных для объектов классов с настройкой жизненного цикла и/или ответственности. История характеризуется набором атрибутов служебного класса "История изменения ответственного и статуса", набор атрибутов одинаков для всех классов и расположен в карточках дочерних классов класса "История изменения ответственного и статуса".

Ниже перечисленные методы работают только для объектов, у которых есть жизненный цикл.

utils.stateHistory(obj)

Получение истории смены статуса.

Параметр метода:
- obj — объект, для которого формируется история событий.
Возвращает событий смены статуса указанного объекта. События сортируются в обратном порядке, первыми — последние изменения.
utils.lastState(obj)

Получение события истории последней смены статуса.

Параметр метода:
- obj — объект, для которого формируется история событий
Пример:
```
def stateEvt = utils.lastState(obj);
def lastStateCode = stateEvt.stateCode;//код предыдущего состояния
def currentStateCode = stateEvt.newStateCode;//код текущего состояния
```

Назначение ответственного

utils.setResponsible(subject, team, employee)

Назначение ответственного.

Пример:

errors = utils.setResponsible(subject, team, employee);
if (!errors.isEmpty())
{
logger.error("Ошибка при назначении ответственного: " + errors);
}

Получение истории смены ответственного

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

utils.responsibleHistory(obj)

Получение истории смены ответственного.

Параметр метода:
- obj — объект, для которого формируется история смены ответственного.
Возвращает список событий смены ответственного указанного объекта. События сортируются в обратном порядке, первыми — последние изменения.
utils.lastResponsible(obj)

Получение события истории последней смены ответственного.

Параметр метода:
- obj — объект, для которого формируется история смены ответственного.

Преобразование объекта в JSON строку

utils.asJson(object, attrs)

utils.asJson(object)

Преобразование любого объекта в JSON строку.

Параметры метода:
- object — сериализуемый объект или список объектов (ScriptDtOCollection — результат api.db.query(...))
  
  object должен быть наследником IUUIdentifiable или ScriptObjectBase, т.е. данный объект был получен с помощью выполнения какого-либо api метода, например, utils.{get, find, findFirst, create, edit, editWithoutAction} или с помощью api.db.query(...).list()
- attrs — коллекция кодов атрибутов, которые необходимо вернуть (если пусто или не указано, то весь сериализованный объект).
Возвращает JSON строку.

api.utils Работа с родительскими и дочерними объектами

utils.getChildUuids(obj)

utils.getChildUuids(obj, parentAttrCode)

Метод применяется только для иерархии в рамках одного класса.

Глубина получения объектов по иерархии не может быть глубже 100 уровня, иначе возникает ошибка

Параметры метода:
- obj — объект или его uuid. Object;
- parentAttrCode — код атрибута связи с родительским объектом. String.
Возвращает список uuid дочерних объектов.
utils.getParentUuids(obj)

utils.getParentUuids(obj, parentAttrCode)

Метод применяется только для иерархии в рамках одного класса.

Параметры метода:
- obj — объект или его uuid. Object;
- parentAttrCode — код атрибута связи с родительским объектом. String.
Возвращает список uuid родительских объектов, строго друг за другом по очередности старшинства (старший элемент будет последним), не производя сортировку.

api.utils Работа с атрибутами объекта

Для доступа к операциям используется утилитарный метод api.utils или его короткий псевдоним utils.

Получение значения атрибута

Получение значения атрибута в заданном представлении:
- utils.asString(def subject, def attrCode) — в виде строки;
- utils.asText(def subject, def attrCode) — в виде описания (plain-text);
- utils.asRTF(def subject, def attrCode) — в виде RTF-текста (html-text).
Для преобразования простого текста в html формат используется метод utils.formatToHtml(text).
utils.getAggrValueMap(obj, attrCode)

Получение значения агрегирующего атрибута.

Параметры метода:
- obj — объект (IUUIDIdentifiable).
- attrCode — код атрибута, значение которого нужно получить. String
Возвращает значения агрегирующего атрибута в виде Map<String, Object>. Постфикс части агрегирующего атрибута, значение соответствующей части агрегирующего атрибута: _em, _ou, _te.
object['aggregateAttrCode']

Получение значения агрегирующего атрибута (при обращении к полю объекта).

Возвращаемое значение: При обращении к полю получаем UUID сотрудника. Если UUID сотрудника не указан, то UUID отдела. Если UUID отдела не указан, то UUID команды.
utils.getFromValueMap(attrCode, vmapItem, subject)

Получение значения атрибута по таблице соответствий.

Параметры метода:
- attrCode — код атрибута, значение которого нужно получить. String
- vmapItem — элемент справочника "Таблицы соответствий" или его uuid. Если null, то возвращается значение атрибута по умолчанию. При этом атрибут, значение которого нужно получить (attrCode), должен быть выбран в качестве определяемого в этой таблице соответствий
- subject — объект, значение атрибута которого необходимо получить.
Возвращает значение атрибута объекта, определенное по таблице соответствий, или значение по умолчанию, если значение не удалось определить по таблице соответствий.
utils.getIterableElement(iterable, position, defaultValue)

Получение элемента коллекции.

Параметры метода:
- iterable — коллекция элементов
- position — номер позиции в коллекции
- defaultValue — значение по умолчанию, для случаев, когда нельзя извлечь значение из коллекции (указан неверный номер позиции или несуществующая коллекция)

Редактирование атрибутов объекта

Не рекомендуется редактировать системные нередактируемые атрибуты.

utils.edit(obj, attrsCode)

Редактирование атрибутов объекта (метод также можно использовать для добавления комментария к объекту).

Параметры метода:
- obj — редактируемый объект
- attrsCode — ассоциативный список кодов изменяемых атрибутов и устанавливаемых значений
Псевдоатрибут @user — пользователь, инициирующий первое действие из цепочки действий. Используется в скриптах при редактировании объектов, в следующий скрипт цепочки действий в качестве user передается пользователь, указанный в @user. Переданный в псевдоатрибуте пользователь не устанавливается как автор события в системе, в истории изменения объекта автором изменения по прежнему будет система. Например
```
def serviceCall = utils.get('serviceCall$3801');
utils.edit(serviceCall, ['title' : 'qwerty', '@user' : user]);
```
Пример цепочки действий: смена статуса → скрипт на вход в статус (редактирует subject через utils.edit) → скрипт проверки условия для счетчика времени (вызвался на редактирование) → действие по событию (событие: изменение объекта).

Особенности редактирования атрибута:
- "Набор ссылок на БО"
  
  Чтобы сбросить на "пусто" значение атрибута "Набор ссылок на БО", необходимо использовать конструкцию:
  
  utils.edit('employeeUUID', ['teams' : []]);
  
  Вариант utils.edit('employeeUUID', ['teams' : null]) может привести к ошибкам при работе с объектом
- "Файл"
  
  При выполнении скрипта:
```
def ou1 = utils.get('uuid_ou1')
def ou2 = utils.get('uuid_ou2')
def file = ou1.fileAttribute
utils.edit(ou2, ['fileAttribute' : file]);
```
  В объекте ou2 будут лежать копии файлов из ou1. У оригинала и копии разные UUID, у каждого объекта типа "Файл" своя строчка в таблице базе данных, но ссылаются они на один реальный файл в хранилище или базе данных (в целях экономии ресурсов при хранении документов)
- "Агрегирующий атрибут"
  
  Редактирование составных частей агрегирующего атрибута необходимо выполнять только через обращение к самому агрегирующему атрибуту, в противном случае корректная работа не гарантируется. Обращение в скрипте к составным частям агрегирующего атрибута и их отдельное редактирование может привести к рассинхронизации значений составных частей агрегирующего атрибута
Пример 1. Изменение названия компании:
```
def root = utils.get('root', [:]);
utils.edit(root, ['title' : "Новое название"]);
```
Пример 2. Установка значения агрегирующего атрибута при редактировании или добавлении объекта:

// Редактируется значение агрегирующего атрибута с кодом 'aggr', устанавливается сотрудника в рамках отдела utils.edit(subject, ['aggr' : ['ouUUID', 'employeeUUID']]); // c использованием uuid объектов utils.edit(subject, ['aggr' : [ou, employee]]); // c использованием объектов

// Редактируется ответственный за запрос utils.edit(subject, ['responsibleTeam' : 'teamUUID', 'responsibleEmployee' : 'employeeUUID' ]);

// Редактируется значение пользовательского агрегирующего атрибута с кодом 'aggr', устанавливается сотрудника в рамках отдела //(не рекомендуется т.к. не будет использована логика завязанная на изменение значения агрегирующего атрибута) utils.edit(subject, ['aggr_ou' : 'ouUUID', 'aggr_em' : 'employeeUUID' ]);
utils.edit (obj, attrsCode, newTransaction)

Редактирование атрибутов объекта в отдельной транзакции аналогично оборачиванию метода edit без параметра в отдельную транзакцию с использованием api.tx.call, см. api.tx Работа с транзакциями.

Параметры метода:
- obj — редактируемый объект
- attrsCode — ассоциативный список кодов изменяемых атрибутов и устанавливаемых значений
- newTransaction — указывает, следует ли запускать редактирование объекта в отдельной транзакции. Boolean
Пример. Изменение названия компании:
```
def root = utils.get('root', [:])
utils.edit(root, ['title' : "Новое название компании"], true)
```

Удаление значения атрибута

utils.clearAttribute(obj, attrCode)

Удаление значения атрибута.

Параметры метода:
- obj — редактируемый объект
- attrCode — код атрибута, у которого удаляется значение

Фильтрация атрибутов

utils.filterUUIDs(uuids, attrsCode)

Фильтрация уникальных идентификаторов по значениям атрибутов.

Параметры метода:
- uuids — список проверяемых uuid
- attrsCode — ассоциативный список кодов атрибутов и их значений.
Возвращает uuid'ы с учетом указанных ограничений по атрибутам.

Копирование атрибутов

utils.copyFromRelated(subject, subjectAttr, relationAttr, attrOfRelatedObject)

Копирование значения атрибута связанного объекта в атрибут текущего объекта.

Параметры метода:
- subject — объект, над которым производится действие
- subjectAttr — код атрибута текущего объекта, куда будет помещено значение
- relationAttr — код атрибута связи типа "Ссылка на бизнес-объект"
- attrOfRelatedObject — код копируемого атрибута связанного объекта
utils.copyManyLinks(subject, subjectAttr, relationAttr, attrsOfRelatedObject)

Копирование значения нескольких ссылочных атрибутов связанного объекта в атрибут типа "Набор ссылок на бизнес-объект" текущего объекта.

Параметры метода:
- subject — объект, над которым производится действие
- subjectAttr — код атрибута текущего объекта, куда будет помещено значение
- relationAttr — код атрибута связи типа "Ссылка на бизнес-объект"
- attrsOfRelatedObject — коды копируемых атрибутов связанного объекта
utils.copyToRelated(subject, subjectAttr, relationAttr, attrOfRelatedObject)

Копирование значения ссылочного атрибута связанного объекта в атрибут типа "Набор ссылок на бизнес-объект" текущего объекта.

Параметры метода:
- subject — объект, над которым производится действие
- subjectAttr — код атрибута текущего объекта
- relationAttr — код атрибута связи типа "Ссылка на бизнес-объект", куда будет помещено значение
- attrOfRelatedObject — код копируемого атрибута
utils.copyToNested(subject, attr)

Копирование значения атрибута объекта в атрибут вложенных объектов. Конструкция работает по всем уровням вложенности для классов, вложенных в самих себя ("Отдел" (ou) или "База знаний").

Параметры метода:
- subject — объект, у которого копируется значение атрибута
- attr — код копируемого атрибута
utils.copyToChilds(subject, subjectAttr, childAttr, classOfChild, types)

Копирование значения атрибута объекта в атрибут вложенных объектов указанного класса, определенных типов. Конструкция работает на первом уровне вложенности для классов, у которых есть вложенные пользовательские классы.

Параметры метода:
- subject — объект, у которого копируется значение атрибута (атрибутов)
- subjectAttr — код атрибута, значения которого требуется скопировать
- childAttr — атрибут вложенных объектов
- classOfChild — класс вложенных объектов
- types — типы вложенных объектов. Все типы — пустые скобки []

Сравнения и проверки атрибутов

utils.containsAttribute(obj, attrCode)

Проверка наличия атрибута у объекта.

Параметры метода:
- obj — объект, для которого проверяется наличие атрибута
- attrCode — код проверяемого атрибута
Возвращаемое значение:
- true — при наличии атрибута
- false — при отсутствии атрибута
utils.isFilled(obj, attrCode)

Проверка заполнения атрибута объекта, при условии отличия его значения от значения по умолчанию.

Параметры метода:
- obj — объект, для которого выполняется проверка
- attrCode — код проверяемого атрибута
utils.equalsDefaultValue(obj, attrCode)

Проверка равенства значения атрибута значению по умолчанию.

Параметры метода:
- obj — объект, для которого выполняется проверка
- attrCode — код проверяемого атрибута
api.utils.checkRestrictions(obj, skipRequired, skipUnique)

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

Параметры метода:
- obj — объект, для которого проверяется соответствие параметров атрибута
- skipRequired — проверка обязательности: true (пропустить), false (не пропускать)
- skipUnique — проверка уникальности: true (пропустить), false (не пропускать)
utils.isFolder(obj)

Проверка, является ли элемент справочника папкой (каталогом).

Параметр метода:
- obj — объект, для которого выполняется проверка

api.utils Работа с комментариями

utils.comments(subject)

Получение списка комментариев.

Параметр метода:
- subject — объект, для которого отображается список комментариев.
Возвращает список комментариев объекта, упорядоченных хронологически (по времени добавления).
utils.create(objCode, attributes)

Добавление комментария к объекту.

Параметры метода:
- objCode — код метакласса создаваемого объекта;
- attributes — ассоциативный список кодов изменяемых атрибутов и устанавливаемых значений.
Пример 1. Добавление комментария к запросу:
```
def serviceCall = utils.get('serviceCall$3801');
utils.create('comment', ['text' : 'Текст комментария', 'source' : serviceCall])
```
Пример 2. Добавление комментария с указанием автора:
```
def serviceCall = utils.get('serviceCall$3801');
utils.create('comment', ['text' : 'Текст комментария', 'author' : user, 'source' : serviceCall])
```
Пример 3. Добавление приватного комментария к запросу:
```
def serviceCall = utils.get('serviceCall$3801');
utils.create('comment', ['text' : 'Текст комментария', 'private' : true, 'source' : serviceCall])
```
utils.edit(obj, attributes)

Добавлять комментарии к объекту через utils.edit не рекомендуется, так как вызывает выполнение действие по событию на изменение объекта.
Добавление комментария через utils.edit следует использовать, если "Комментарий" обязателен для заполнения при изменении статуса объекта.

Для добавления комментария к объекту рекомендуется использовать utils.create.

Параметры метода:
- obj — объект, к которому добавляется комментарий;
- attributes = @comment' для добавления комментария;
- attributes ='@commentAuthor' для указания автора добавляемого комментария;
- attributes ='@isCommentPrivate' для добавления приватного комментария.
Пример 1. Добавление комментария к запросу, используется '@comment' (комментарий). Если включить действие по событию на изменение объекта типа "скрипт" с содержимым скрипта из примера, то действие по событию будет выполняться трижды при любом изменении редактируемого объекта serviceCall, каждый раз добавляя комментарий
```
def serviceCall = utils.get('serviceCall$3801');
utils.edit(serviceCall, ['@comment' : 'Текст комментария'])
```
Пример 2. Добавление комментария с указанием автора, используется '@commentAuthor' (автор добавляемого комментария):
```
def serviceCall = utils.get('serviceCall$3801');
utils.edit(serviceCall, ['@comment' : 'Текст комментария', '@commentAuthor' : user]);
```
Пример 3. Добавление приватного комментария к запросу, используется '@isCommentPrivate' (признак приватности комментария):
```
def serviceCall = utils.get('serviceCall$3801');
utils.edit(serviceCall, ['@comment' : 'Текст комментария', '@isCommentPrivate' : true]);
```
utils.lastComment(subject)

Получение последнего комментария объекта.

Параметр метода:
- subject — объект, для которого получаем последний комментарий.
Возвращает последний (по времени добавления) комментарий объекта.

api.utils Работа с файлами

Для доступа к операциям используется утилитарный метод api.utils или его короткий псевдоним utils.

Получение списка файлов

utils.files(obj)

Получение списка файлов, прикрепленных к объекту и атрибутам объекта типа "Файл" (кроме файлов, прикрепленных в атрибуте типа "Текст RTF").

Параметр метода:
- obj — объект, для которого отображается список файлов.
Возвращает список файлов, прикрепленных к объекту и атрибутам объекта типа "Файл", упорядоченных в хронологическом порядке (по времени добавления). При обращении к последнему элементу коллекции возвращается последний прикрепленный файл.

Пример: Получение списка файлов, прикрепленных к самому объекту, а не к его атрибутам типа "Файл" и "Текст в формате RTF":

def contentFiles = utils.files(obj).findAll{!it.relation};
utils.allFiles(obj)

Получение списка всех файлов, прикрепленных к объекту, атрибутам объекта типа "Файл" и атрибутам объекта типа "Текст в формате RTF".

Параметр метода:
- obj — объект или его uuid, для которого отображается список файлов.
Возвращает список всех файлов, прикрепленных к объекту, атрибутам объекта типа Файл и атрибутам объекта типа "Текст в формате RTF", упорядоченных в хронологическом порядке (по времени добавления).

При обращении к последнему элементу коллекции возвращается последний прикрепленный файл.
utils.filesFromRtf(obj)

utils.filesFromRtf(obj, inPreview)

Получение списка файлов, связанных с RTF атрибутами объекта.

Параметры метода:
- obj — объект или его uuid, для которого отображается список файлов;
- inPreview:
  - true — возвращает файлы с превью изображений, если они имеются, вместо оригиналов;
  - false или параметр не указан — возвращает только файлы с изображениями в оригинальном размере.
Возвращает список всех файлов, связанных с RTF атрибутами объекта.
utils.filesFromRtf(obj, attrCode)

utils.filesFromRtf(obj, attrCode, inPreview)

Получение списка файлов, связанных с определенным RTF атрибутом объекта.

Параметры метода:
- obj — объект или его uuid, для которого отображается список файлов;
- attrCode — код атрибута типа "Текст в формате RTF";
- inPreview:
  - true — возвращает файлы с превью изображений, если они имеются, вместо оригиналов;
  - false или параметр не указан — возвращает только файлы с изображениями в оригинальном размере.
Возвращает список всех файлов, связанных с определенным RTF атрибутом объекта.

Преобразования

utils.convertFilesToBase64(text, failIfFileNotFound)

Преобразует текст, содержащий ссылки на файлы в тегах img, в список файлов в формате base64.

Размер файла ограничивается в конфигурационном файле dbaccess.properties, параметр ru.naumen.file.base64.limit (Файлы).

Параметры метода:
- text — текст картинками. String;
- failIfFileNotFound. Boolean.
  - true — возникает ошибка при отсутствии файла или при отсутствии соединения с файловым хранилищем;
  - false (по умолчанию) — ошибка не возникает. Параметр необязательный.
Возвращает текст с картинками в виде base64.

Текст возвращается как html страница (т.е. обернутым в теги <html> <body> ...</body> </html>).

Получение содержимого файла

utils.readFileContent(file)

Получение содержимого файла (содержимое файла считывается как массив байтов).

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

Особенности:
- Метод не рекомендуется использовать в одном скрипте вместе с методами Методы API.
- В скрипте условии на вход в начальный статус "Зарегистрирован" (registered) содержимое файла получить нельзя, если file — файл принадлежит объекту, который находится в процессе создания.
Параметр метода:
- file — файл.
Пример:
Copy
```
def file = fileList[0] // объект типа "Файл"
try
  {
  byte[] data = utils.readFileContent(file)
  }
catch(e)
  {
  logger.error "Ошибка при чтении содержимого файла из файлового хранилища"
  }
```

Получение источника данных

utils.getFileDataSource(file)

Получение источника данных (DataSource) для указанного файла.

Параметр метода:
- file — файл.

Прикрепление файла

utils.attachFile(source, fileName, contentType, description, content)

utils.attachFile(source, relation, fileName, contentType, description, content)

utils.attachFile(source, relation, fileName, contentType, description, content, isFromRichTextAttr)

Прикрепление файла к указанному объекту.

Параметры метода:

source — объект, к которому прикрепляется файл;
relation — идентификатор связи файла и объекта;
fileName — название файла с расширением;
contentType — mime-тип файла;
description — описание файла;
content — содержимое файла;
isFromRichTextAttr — признак, является ли файл картинкой из rtf-атрибута.

Возвращает объект файла.

Примеры:

1. Прикрепление файлов к объекту в контент "Список файлов":

Copy

/*Параметры*/
def obj = ...                         //объект, к которому прикрепляется файл
def fileName = 'file1.txt'            //имя файла (с расширением)
def contentType = 'text/plain'        //тип содержимого файла (mime-тип)
def description = 'Описание'          //описание файла
def data = 'some string'.getBytes()   //содержимое файла в виде массива байт

/*Прикрепление файла к объекту*/
def attachedFile = utils.attachFile(obj, fileName, contentType, description, data)

2. Прикрепление файлов из параметров пользовательских событий к объекту в контент "Список файлов":

Copy

/*Параметры*/
def obj = ...         //объект, к которому прикрепляется файл
def file = ...        //файл, выбранный как значение параметра типа "Файл" пользовательского события

/*Прикрепление файла к объекту*/
def attachedFile = utils.attachFile(obj, file)

/*Пример*/
def obj = ...
params.files?.each { file -> utils.attachFile(obj, file) } // прикрепление к объекту

3. Прикрепление файлов к атрибуту объекта:

Copy

/*Параметры*/
def obj = ...                         //объект, к которому прикрепляется файл
def attribute = 'files'               //код атрибута, к которому прикрепляется файл
def fileName = 'file1.txt'            //имя файла (с расширением)
def contentType = 'text/plain'        //тип содержимого файла (mime-тип)
def description = 'Описание'          //описание файла
def data = 'some string'.getBytes()   //содержимое файла в виде массива байт

/*Прикрепление файла к объекту*/
def attachedFile = utils.attachFile(obj, attribute, fileName, contentType, description, data)

4. Прикрепление файлов к атрибуту объекта из параметров пользовательских событий:

Copy

/*Параметры*/
def obj = ...                 //объект, к которому прикрепляется файл
def attribute = 'files'       //код атрибута, к которому прикрепляется файл
def file = ...                //файл, выбранный как значение параметра типа "Файл" пользовательского события

/*Прикрепление файла к объекту*/
def attachedFile = utils.attachFile(obj, attribute, file)

/*Пример*/
def obj = ...
params.files?.each { file ->  utils.attachFile(obj, 'files', file) }

api.utils Работа с шаблонами Groovy

utils.processTemplate(template, bindings)

Метод позволяет:
- обрабатывать строки как шаблоны Groovy;
- обрабатывать шаблоны Groovy, записанные в документах .docx.
Метод utils.processTemplate можно использовать для формирования печатных форм, см. Формирование печатной формы.

В шаблонах Groovy есть возможность использовать методы api и скриптовые модули.

Параметры:
- template:
  - строка-шаблон (только в одинарных кавычках!);
  - файл или UUID файла в системе.
- bindings — ассоциативный массив параметров для обработки шаблона Groovy.
Возвращает обработанную строку ИЛИ содержимое файла в виде массива байт, иначе ошибка.

Примеры:

1. Обработка строки как шаблона Groovy, выполняется подстановка переменных в шаблон (template — строка)
```
template = 'Привет, ${userName}'
binding = def binding = ["userName":"dkolmogorov"]
// результат работы метода = "Привет, dkolmogorov"
```
2. Обработка шаблона Groovy, записанного в файле .docx.

Метод принимает файл (или UUID файла) шаблона документа, а также параметры для его обработки, которые передаются в виде ассоциативного массива, и возвращает массив байт обработанного шаблона.
```
def template = utils.get('UUID файла шаблона')
utils.processTemplate(template, bindings)
//или
utils.processTemplate(templateUUID, bindings)
```
Получаемый на выходе массив байт можно использовать в методе utils.attachFile, например, следующий скрипт добавит на карточку компании обработанный шаблон.
```
def subject = utils.findFirst('root', [:])
def template = utils.get('UUID ФАЙЛА ШАБЛОНА')
def bindings = ['название параметра' : значение параметра, ...]
def data = utils.processTemplate(template, bindings)
utils.attachFile(subject, 'Название обработанного шаблона.docx', 'unknown', 'описание', data)
```
3. Ограничение редактирования шаблона (файле .docx) паролем:
Copy
```
import org.apache.poi.xwpf.usermodel.XWPFDocument;
import org.apache.poi.poifs.crypt.HashAlgorithm; //подключаем библиотеку алгоритмов хеширования

try
{
    def subject = utils.findFirst('root', [:]);
    def template = utils.get('UUID ФАЙЛА ШАБЛОНА');
    def bindings = ['название параметра' : значение параметра, ...];
    def byteArrray = utils.processTemplate(template, bindings);
    new ByteArrayInputStream(byteArrray).withStream { targetStream ->
      XWPFDocument document = new XWPFDocument(targetStream);
      document.enforceReadonlyProtection('password',HashAlgorithm.md5); //в качестве пароля будет установлена строка 'password'
      new ByteArrayOutputStream().withStream { bos ->
        document.write(bos);
        def data = bos.toByteArray();
        utils.attachFile(subject, 'Название обработанного шаблона.docx', 'unknown', 'описание', data);
      }
    }
}
catch(e)
{
      logger.error(e.getMessage(), e);
}
```
Особенности применения utils.processTemplate:

При создании таблицы на основе списка связанных объектов, переменная создается как [имя_переменной]+List , а в файле шаблона просто [имя_переменной].

Это связано с тем, что метод utils.processTemplate реализуется через библиотеку https://github.com/snowindy/scriptlet4docx/tree/master. В эту библиотеку, передается [имя_переменной]+List (например, tasksList), и она преобразует в коллекцию(task), далее уже к коллекции обращаемся без List.

Этот вид скриптлетов используется для вывода списков объектов в таблицу внутри docx-документа и должен использоваться внутри ячейки таблицы.

Пример: Есть список объектов Person, каждый объект имеет два поля: 'name' и 'address', необходимо вывести список в таблице из двух колонок.
1. Создаем параметр 'personList' в карте входных значений, который ссылается на список объектов.
2. Создаем таблицы с двумя колонками и одной строкой в docx-документе.
3. $[@person.name] необходимо ввести в первую ячейку; $[@person.address] — во вторую.
4. Все готово, список personList будет распечатан в таблице.

api.utils Редактирование таблицы соответствий

Для доступа к операциям используется утилитарный метод api.utils или его короткий псевдоним utils.

utils.editValueMapRow(table, sourceValues, newValues)

Поиск и изменение отдельной строки в таблице соответствий.

Параметры метода:
- table — таблица соответствий или ее uuid
- sourceValues — набор значений определяющих атрибутов в строке, которую необходимо изменить. Можно указывать значения не для всех атрибутов, но указанная комбинация должна однозначно определять одну из строк. Значения атрибутов передаются в виде пар "ключ-значение". Несуществующие атрибуты при этом игнорируются
- newValues — набор новых значений атрибутов изменяемой строки. Значения атрибутов передаются в виде пар "ключ-значение". Несуществующие атрибуты при этом игнорируются
Пример:

utils.editValueMapRow(vmap, ['responsibleTeam': 'team$2345'], ['priority': 'priority@high'])

api.utils Форматирование данных

Для доступа к операциям используется утилитарный метод api.utils или его короткий псевдоним utils.

utils.formatters.escapeHtmlSymbols(text).asString()

Заменяет специальные символы (<, >, &) на их html-эквивалент, чтобы они отображались в строке, как обычные символы. Если text равен null, то возвращает пустой html
utils.formatters.format(obj)

Возвращает название объекта или его uuid, если у объекта нет атрибута "Название" (title).

Форматирование даты и времени

utils.formatters.formatDate(date)

Возвращает строку с датой в формате dd.MM.yyyy.
utils.formatters.formatDateTime(dateTime)

Возвращает строку с датой в формате dd.MM.yyyy HH:mm.
utils.formatters.strToDate(str, dateFormat)

Перевод строки заданного формата в дату.

Параметры метода:
- str — строка;
- dateFormat — формат даты.
utils.formatters.strToDateTime(str)

Перевод строки формата dd.MM.yyyy HH:mm в дату.
utils.formatters.strToDate(str)

Перевод строки формата dd.MM.yyyy в дату.
utils.formatters.formatDateTimeInterval(dateTimeInterval)

Возвращает строковое представление временного интервала.
utils.formatters.formatLongToTime(value, roundUp).asString()

Преобразование количества миллисекунд во время ЧЧ:ММ.

Параметры метода:
- value — значение в миллисекундах. Long
- roundUp;
  - true (миллисекунды округляются до минут в сторону большего значения);
  - false (миллисекунды округляются до минут в сторону меньшего значения).
  Возвращаемое значение: Время ЧЧ:ММ (количество часов может быть больше 0 любым целым значением).
utils.formatters.formatTimePeriod(ms)

Форматирование периода времени по шаблону "xx ч. yy д. zz мин.".

Параметр метода:
- ms — период времени. Long

Форматирование гиперссылки

utils.formatters.formatHyperlink(hyperlink)

Возвращает гиперссылку в виде текста.
utils.formatters.formatHyperlinkAsHtml(hyperlink).asString()

Форматирование гиперссылки для добавления ее на веб-страницу рабочей ссылкой.

Форматирование логических значений

utils.formatters.oneZeroFormatter(booleanValue)

Возвращаемое значение:
- 1, если значение true
- 0, если значение false
utils.formatters.yesNoFormatter(booleanValue)

Возвращаемое значение:
- да, если значение true
- нет, если значение false.

Форматирование числовых значений

utils.formatters.bytesToKb(value, roundUp)

Конвертация величины в байтах в килобайты.

Параметры метода:
- value — число в байтах
- roundUp = true (округляется в сторону большего значения)
- roundUp = false (округляется в сторону меньшего значения)
Возвращает целое число размер value в килобайтах округленный вверх или вниз.
utils.formatters.bytesToMb(value, roundUp)

Конвертация величины в байтах в мегабайты.

Параметры метода:
- value — число в байтах
- roundUp = true (округляется в сторону большего значения)
- roundUp = false (округляется в сторону меньшего значения)
Возвращает целое число размер value в мегабайтах округленный вверх или вниз.

utils.formatToHtml

utils.formatToHtml(subject."attrCode")

Форматирование простого текста (text) для представления в html.

Возвращает фрагмент HTML. Преобразование происходит заменой переносов строк ("\n") на теги <br>.

Пример. Конструкция для передачи описания запроса в оповещении:

${utils.formatToHtml(subject.description)}

api.web Формирование ссылок, ведущих в заданное место в интерфейсе

Ссылка на заданное место в веб-интерфейсе

api.web.asLink(url, title)

Формирование ссылки, ведущей в заданное место в интерфейсе системы.

Параметры метода:
- url — адрес карточки объекта, формы добавления или формы редактирования (для оповещения)
- title — представление в интерфейсе.

Получение базового URL-адреса приложения и GWT-place

api.web.getBaseUrl()

Получение базового URL-адреса приложения. Baseurl берется из конфигурационного файла dbaccess.properties, см. Общие настройки.

Возвращает URL-адрес системы вида "http://127.0.0.1:8080/sd/operator/".
api.web.getPlace(url)

Получение GWT-place из ссылки.

Генерируемая ссылка имеет вид:

http://sd40.naumen.ru/operator/?anchor=add:ouCase

Конструкция после связки "http://sd40.naumen.ru/operator/?anchor=" является GWT-place.

Параметр метода:
- url — метод для генерации ссылки: api.web.add, api.web.open, api.web.openWithUserUUID, api.web.edit, api.web.editWithUserUUID (String).
Возвращаемое значение:
- GWT-place ссылки;
- Пустая строка, если в переданной ссылке присутствует параметр accessKey.
Пример:

api.web.getPlace(api.web.add('ouCase'))

где add:ouCase — возвращаемое значение.

Ссылка на карточку или вкладку карточки в веб-интерфейсе системы

api.web.open(subject)

api.web.open(subject, login_or_accesskey)

api.web.openWithUserUUID(subject, login_or_accesskey)

Генерация URL-ссылки для перехода на карточку указанного объекта.

Параметры метода:
- subject — текущий объект, карточка которого открывается при переходе по ссылке. Параметр может быть задан в виде объекта или строки, содержащей его uuid
- login_or_accesskey — логин или ключ авторизации пользователя для входа в систему (по имени пользователя или по uuid пользователя), см. api.auth Работа с ключами авторизации
Все параметры метода являются строками и требуют при явной передаче значений оборачивания последних в одинарные кавычки.

Возвращает строку, содержащую URL-ссылку на карточку указанного объекта.

Пример 1. Ссылка для перехода на карточку текущего объекта с ключом авторизации:

${api.web.asLink(api.web.open(subject, api.auth.getAccessKey('username')), 'Карточка объекта')}

${api.web.asLink(api.web.open(subject.UUID, 'username'), 'Карточка объекта')}

${api.web.asLink(api.web.openWithUserUuid(subject, 'userUuid'), 'Карточка объекта')}

Пример 2. Ссылка для перехода в карточку с указанием логина и пароля или через прозрачную аутентификацию (Kerberos):

${api.web.asLink(api.web.open(subject), 'Карточка объекта')}

${api.web.asLink(api.web.open(subject.UUID)}, 'Карточка объекта')}
api.web.openTab(subject.UUID, tabId)

api.web.openTab(subject.UUID, tabId, username)

api.web.openTab(subject.UUID, tabId, accessKey)

Генерация URL-ссылки для перехода на конкретную вкладку в карточке объекта.

Параметры метода:
- subject.UUID — uuid объекта
- tabId — идентификатор вкладки
- username — имя пользователя
- accessKey — ключ доступа
Все параметры метода являются строками и требуют при явной передаче значений оборачивания последних в одинарные кавычки.

Возвращает строку, содержащую URL-ссылку на карточку указанного объекта.

Пример 1. Ссылка для перехода на вкладку карточки объекта:

${api.web.asLink(api.web.openTab(subject.UUID, tabId), 'Вкладка на карточке объекта')}

Пример 2. Ссылка для перехода на конкретную вкладку в карточке объекта с параметрами - идентификатор объекта, идентификатор вкладки, имя пользователя

${api.web.asLink(api.web.openTab(subject.UUID, tabId, 'username'), 'Вкладка на карточке объекта')}

Пример 3. Ссылка для перехода на конкретную вкладку в карточке объекта с параметрами - идентификатор объекта, идентификатор вкладки, ключ доступа

${api.web.asLink(api.web.openTab(subject.UUID, tabId, accessKey), 'Вкладка на карточке объекта')}

Ссылка на форму в веб-интерфейсе

api.web.edit(subject)

api.web.edit(subject, login_or_accesskey)

api.web.editWithUserUUID(subject, login_or_accesskey)

Генерация URL-ссылки для перехода на форму редактирования указанного объекта.

Параметры метода:
- subject — текущий объект, форма редактирования которого открывается при переходе по ссылке. Параметр может быть задан в виде объекта или строки, содержащей его uuid
- login_or_accesskey — логин или ключ авторизации пользователя для входа в систему (по имени пользователя или по uuid пользователя), см. api.auth Работа с ключами авторизации
  
  Если параметр не указан и пользователь не авторизован в системе, то он будет переадресован на форму ввода логина и пароля.
Короткие ссылки:
- Если включен сервис кодирования текста, то ссылка, превышающая 2000 символов, будет сокращена. Сервис кодирования текста включается в конфигурационном файле dbaccess.properties (Кодирование текста).
Возвращает сроку, содержащую URL-ссылку на форму редактирования указанного объекта.

Пример 1. Ссылка для перехода на форму редактирования объекта с ключом авторизации:

${api.web.asLink(api.web.edit(subject, api.auth.getAccessKey('username')), 'Форма редактирования объекта')}

${api.web.asLink(api.web.edit(subject.UUID, 'username'), 'Форма редактирования объекта')}

${api.web.asLink(api.web.editWithUserUuid(subject.UUID, 'userUuid'), 'Форма редактирования объекта')}

Пример 2. Ссылка для перехода на форму редактирования объекта с указанием логина и пароля или через прозрачную аутентификацию (Kerberos):

${api.web.asLink(api.web.edit(subject), 'Форма редактирования объекта')}

${api.web.asLink(api.web.edit(subject.UUID), 'Форма редактирования объекта')}
api.web.changeState(subject)

api.web.changeState(subject, login_or_accesskey, values)

Генерация URL-ссылки для перехода на форму смены статуса.

Параметры метода:
- subject — объект, форма смены статуса которого будет открыта при переходе по ссылке
- login_or_accesskey — логин или ключ авторизации пользователя для входа в систему (по имени пользователя или по uuid пользователя), см. api.auth Работа с ключами авторизации
  
  Если параметр не указан и пользователь не авторизован в системе, то он будет переадресован на форму ввода логина и пароля
- values — ассоциативный массив, содержащий значения атрибутов на форме смены статуса: ключ — код атрибута; значение — значение атрибута
  
  Методом можно заполнять атрибуты следующих типов: строка, текст, текст в формате RTF, вещественное число, целое число.
Возвращает сроку, содержащую URL-ссылку на форму смены статуса указанного объекта.

Если указан статус, в который следует перевести объект, то по ссылке открывается форма с установленным новым статусом. Если статус не указан, то форма смены статуса с выбора статуса.

Пример. Ссылка с ключом авторизации для перехода на форму смены статуса (с установленным новым статусом):

def subject = utils.get('serviceCall$8302');

def accessKey = api.auth.getAccessKey('nl');

api.web.changeState(subject,accessKey,['state':'resolved','stringAttr':'test','textAttr':'text test','rtfTextAttr':'test rtf','intAttr':123,'doubleAttrCode':12.1245454]);
api.web.add(fqns)

api.web.add(fqn, parent, attributes)

api.web.add(fqn, parent, attributes, needCheckAttrs)

Генерация URL-ссылки для перехода на форму добавления. Ссылка для перехода на форму добавления с предзаполненными полями. Генерирует URL-ссылку для перехода на форму добавления объекта указанного типа /класса.

Если указаны parent и attributes, то формируется ссылка для перехода на форму добавления объекта без проверок на существование заданных атрибутов в классе /типе и корректности их значений.

Если указано needCheckAttrs, то формируется URL-ссылки на форму добавления объекта указанного типа /класса с предзаполненными полями, с проверкой на существование заданных атрибутов в классе /типе и корректности их значений.

При переходе по ссылке требуется указывать логин и пароль, также может использоваться прозрачная аутентификация (Kerberos).

Параметры метода:
- fqns — коллекция fqn'ов доступных для выбора типов добавляемого объекта. Допускается указывать только типы объектов одного класса. Значение fqn может быть как объект ClassFqn, так и его строковый эквивалент
- fqn — класс /тип, форма добавления которого открывается при переходе по ссылке. Значение fqn может быть как объект ClassFqn, так и его строковый эквивалент
  
  Если параметр fqn указывает на тип, то при переходе по ссылке будет открыта форма добавления этого типа, контент "Тип объекта" на форме не отобразится, если на класс – будет открыта форма добавления класса с возможностью выбора любого доступного пользователю типа этого класса.
  
  Если ассоциативный массив, заданный в параметре attributes не пуст, соответствующие поля формы при ее открытии будут заполнены указанными значениями.
- parent — в зависимости от класса, на который указывает fqn, параметр рассматривается как:
  - контрагент запроса, если fqn задает класс "Запрос" (serviceCall).
  - родительский объект, если fqn задает класс вложенных объектов.
  Если fqn указывает на классы, не перечисленные выше, то данный параметр заполняется значением null или пустой строкой.
  
  Параметр может быть задан в виде объекта или строки, содержащей его UUID.
- attributes — ассоциативный массив, содержащий значения по умолчанию для атрибутов создаваемого объекта: ключ — код атрибута; значение — значение по умолчанию атрибута
  
  Доступные типы атрибутов: Набор ссылок на бизнес-объекты, Ссылка на бизнес-объект, Обратная ссылка, Набор элементов справочника, Дата, Дата/Время, Целое число, Вещественное число, Логический, Временной интервал, Гиперссылка, Строка, Текст, Текст в формате RTF и Текст с подсветкой синтаксиса.
  
  Особенности:
  - при предзаполнении на форме атрибута "Текст с подсветкой синтаксиса", тип синтаксиса не передается;
  - в ссылку можно добавлять строковые и текстовые параметры (Строка, Текст, ТекстRTF);
  - для ссылочных атрибутов передается только UUID объекта.
  Для передачи временных файлов в контент "Список файлов" используется специальный атрибут "@files".
  
  Файлы, добавленные в контент "Список файлов" таким образом, нельзя будет использовать в синхронных действиях по событию на создание объекта.
  
  Пример:
  
  def originFileUuid = 'file$0000'
  
  def tempFile = api.fileStorage.createTempFileFromOrigin(originFileUuid)
  
  api.web.add('serviceCall$EBsc', null, ['@files':[tempFile]])
- needCheckAttrs — признак, определяющий требуются ли проверки на существование заданных атрибутов в классе/типе и корректности их значений
Особенности работы метода:
- Метод api.web.add(fqn, parent, attributes, needCheckAttrs):
  - fqn = тип + есть атрибут, не присутствующий в типе
    - needCheckAttrs=true — метод возвращает ошибку "Редактируемый объект не содержит атрибуты '[xxx]'."
    - needCheckAttrs=false — метод возвращает ссылку с передачей несуществующего атрибута
  - fqn = класс + есть атрибут, не присутствующий в классе
    - needCheckAttrs=true — метод возвращает ошибку "Редактируемый объект не содержит атрибуты '[xxx]'."
    - needCheckAttrs=false — метод возвращает ошибку "Коллекция значений типов объектов должна содержать минимум один идентификатор типа метакласса"
  Метод с fqn и без needCheckAttrs, если коллекция содержит атрибут, не присутствующий в классе /типе, всегда возвращает ошибку "Редактируемый объект не содержит атрибуты '[xxx]'.
  
  Метод с fqns (набор типов) и без needCheckAttrs, если коллекция содержит атрибут, не присутствующий в классе /типе, возвращает ссылку с передачей несуществующего атрибута.
  
  При формировании ссылки символ $ в тексте скрипта нужно экранировать: \$
Короткие ссылки:
- Если включен сервис кодирования текста, то ссылка, превышающая 2000 символов, будет сокращена. Сервис кодирования текста включается в конфигурационном файле dbaccess.properties (Кодирование текста)
Возвращает сроку, содержащую URL-ссылку на форму добавления объекта указанного класса /типа.

Пример 1:
```
def list = ['ou$StdOu', 'ou$office', 'ou$storage'];
return api.web.asLink(api.web.add(list));
```
Пример 2:
```
def list = ['ou$StdOu', 'ou$office', 'ou$storage'];
def attributes = ['recipientAgreements' : utils.get('agreement$3001')];
return api.web.asLink(api.web.add(list, null, attributes));
```
Пример 3. Ссылка для перехода на форму добавления объекта класса "Отдел" (ou)/типа "office", вложенного в отдел с идентификатором (UUID) ou$1601. На форме добавления предзаполнено поле "Руководитель отдела":

<a href="${api.web.add('ou$office', 'ou$1601', ['head':employee1]), false}">Форма добавления отдела</a>

Пример 4. Ссылка для перехода на форму добавления объекта класса "Запрос" (serviceCall) с контентом "Выбор контрагента":

<a href="${api.web.add(fqn, parentUUID, attributes, false) + '!{"fast":"true"}'}">Форма добавления запроса</a>

Пример 5. Ссылка для перехода на форму добавления объекта класса "Отдел" (ou):
```
def obj = utils.get('ou$1234');
def attributes = ['recipientAgreements' : utils.get('agreement$3001')];
if(obj)
{
return api.web.asLink(api.web.add(obj.metaClass, null, attributes, false));
}
```
Пример 6.
```
def attributes = ['intTest' : 12121212121,
   'boLnsA' : utils.get('employee$4413'),
   'boLinksA' : [ utils.get('employee$4413'), utils.get('employee$4414') ],
   'catItemsV' : ['urgency$3103', 'urgency$3101'],
   'VrInt' : ["interval":"SECOND","length":"300"],
   'hLink' : ["text" : "link", "url" : "http://ya.ru"],
   'DoubleNL' : 111.511,
   'Logic' : true,
   'DateNL' : new Date(),
   'DateTime' : new Date(),
   'backLink' : [ utils.get('ou$4201'), utils.get('ou$4202') ],
   'catItem' : 'impact$2802'
   ];
api.web.add('UserClass$UserType3', null, attributes).replaceFirst('.*add:UserClass','#add:UserClass');
```

Ссылка на список с минимальным набором параметров

api.web.list(object, listContentCode)

Генерация ссылки на список объектов на карточке объекта с минимальным набором параметров.

Параметры:
- object — объект или UUID объекта, карточка которого открывается при переходе по ссылке. Object
- listContentCode — код контента, на который будет производиться позиционирование. String
Возвращает строку, содержащая URL-ссылку на контент со списком на карточке объекта.

Пример. Генерация ссылки на список на карточке объекта с минимальным набором параметров:

api.web.list('root$401','SpisokObektov')

Результат:

http://localhost:8080/sd/operator/?anchor=uuid:root$401!%7B%22tab%22:%22STAB100%22%7D!encoded_prms=encoded_text$596803
api.web.list(listTitle, classFqn, attrGroup)

Генерация ссылки на список объектов на отдельной странице с минимальным набором параметров.

Параметры:
- listTitle — название списка. String
- classFqn — код класса, к которому принадлежат объекты списка. String
- values — код группы атрибутов, определенной во всех типах переданного класса, которая определяет колонки списка. String
Возвращает:
- Строка, содержащая URL-ссылку на список объектов на отдельной странице.
- Пустая строка, если не определены обязательные атрибуты
Права: для просмотра списка на отдельной странице пользователь должен обладать правами. Право может быть выдано лицензированным и нелицензированным пользователям.

Пример. Генерация ссылки на список на отдельной странице с минимальным набором параметров:

api.web.list('Название списка', 'serviceCall', 'system')

Результат:

http://localhost:8080/sd/operator/?anchor=list:!!encoded_prms=encoded_text$596802

Ссылка на список с полным набором доступных параметров

api.web.list(builder)

Генерация ссылки на список объектов с полным набором доступных параметров. Ссылка генерируется на основании параметров, определенных билдером:
- ссылка на отдельной странице — билдер, определенный api.web.defineListLink(onCard) со значением параметра = false.
- ссылка на карточке объекта — билдер, определенный api.web.defineListLink(onCard) со значением параметра = true
Параметр:
- builder — инкапсулирует в себе параметры, необходимые для генерации ссылки на список объектов
Возвращает:
- Строка, содержащая URL-ссылку на список объектов.
- Пустая строка, если не определены обязательные атрибуты
Права: для просмотра списка на отдельной странице пользователь должен обладать правами. Право может быть выдано лицензированным и нелицензированным пользователям.
api.web.defineListLink(onCard)

Определение билдера, передаваемого в метод api.web.list(builder).

Параметр:
- onCard — определяет тип генерируемой ссылки: true (на карточке объекта), false (на отдельной странице)
Возвращает: Объект для генерации ссылки на список объектов. Список формируется с учетом ограничений содержимого списка и расположения постраничной навигации указанные в шаблоне.

Общие методы билдера

setTemplate — строка, содержащая код шаблона списков, которому будет соответствовать отображение полученного списка. Необязательный метод.
При отображении списка на отдельной странице в момент обработки ссылки проверяется точное соответствие:
- класса/типов шаблона классу/типам объектов самого списка (setClassCode);
- группы атрибута, указанной в шаблоне, группе атрибутов самого списка (setAttrGroup);
- типа списка "Простой/Сложный", указанного в шаблоне, типу самого списка (setSimple).
Если настройки не совпадают, то список не отображается и выводится сообщение об ошибке
setUsers — строка, содержащая UUID пользователей, которым доступна страница. Необязательный метод, по умолчанию значение пусто и особых ограничений к доступу к странице не применяется
setDaysToLive — продолжительность жизни ссылки в днях. Необязательный метод, по умолчанию берутся из параметра файле dbaccess.properties. Если значение в dbaccess.properties неуказано, то оно равно 30 дням

Методы билдера для списка объектов

setListType — тип списка:
- пустое значение (по умолчанию) — список имеет тип "Список объектов";
- значение RelObjectList — список имеет тип "Список связанных объектов".
- значение ChildObjectList — список имеет тип "Список вложенных объектов"
setUuid — UUID объекта, относительно которого строится список связанных и вложенных объектов.

Используется (и обязателен) только если вызывается метод setListType и на его вход переданы значения RelObjectList или ChildObjectList.

В качестве объекта связи можно указать текущего пользователя или объект, связанный с ним. Для этого в метод передается константа 'currentUser'. Чтобы указать объект, связанный с текущим пользователем, используется конструкция вида 'currentUser.attrCode1.attrCode2, в которой через точку можно указать коды атрибутов объектов типа "Ссылка на бизнес-объект".

Пример: 'currentUser.Parent.upperOU', где в качестве объекта связи будет взят объект, находящийся в атрибуте upperOU объекта currentUser.Parent. Если список строится относительно 'currentUser', то в интерфейсе пользователя для каждого пользователя будет свой список объектов, взятый из его атрибута
setNested — демонстрация объектов, вложенных во вложенные (параметр "Показывать в списке объекты, вложенные во вложенные" в списках вложенных объектов) и связанных со вложенными (параметр "Показывать в списке объекты, связанные с иерархией" в списках связанных объектов).
- true — в итоговый список попадут объекты, вложенные во вложенные и связанные со вложенными;
- false (по умолчанию) — не попадут.
Используется только если вызывается метод setListType и на его вход переданы значения RelObjectList или ChildObjectList.
attrChain — самостоятельный билдер, использующийся для задания иерархии объектов при построении "Списка связанных объектов".

Используется (и обязателен) только если вызывается метод setListType со значением RelObjectList.

Билдер имеет следующие методы:
- attributesChain. В качестве параметра метода передается массив FQN атрибутов для цепи связи (с какого по какой будет связь), аналогично параметрам "Атрибут" и "Построить иерархию объектов (вниз), начиная с объекта".
- nestedHierarchyAttrFqn. В качестве параметра метода передается код атрибута в цепи ссылок, после которого строится иерархия, аналогично параметру "В иерархии потомки связаны с предками через атрибут". Используется (и обязателен) только если вызывается метод setNested со значением true.
- nestedAttrLinkFqn. В качестве параметра метода передается код атрибута связи для вложенных объектов, аналогично параметру "Объекты иерархии связаны с объектами списка через атрибут". Используется (и обязателен) только если вызывается метод setNested со значением true
relatedWithNestedParams — альтернативный метод задания параметра "Показывать в списке объекты, связанные с иерархией", в метод передаются три параметра аналогично тому, как они задаются при добавлении контента, а именно:
- цепочка атрибутов, соответствующая параметру "Построить иерархию объектов (вниз), начиная с объекта"
- код атрибута, соответствующего параметру "В иерархии потомки связаны с предками через атрибут"
- цепочка атрибутов, соответствующая параметру "Объекты иерархии связаны с объектами списка через атрибут"
setTitle — строка, содержащая название списка
setClassCode — строка, содержащая код класса, которому принадлежат объекты списка
setCases — массив, содержащий список кодов типов класса, объекты которых будут отображаться в списке. Необязательный метод: по умолчанию показываются объекты всех типов класса из параметра setClassCode
setAttrGroup — строка, содержащая код группы атрибутов, определенной во всех типах из параметра выше, которая определяет колонки списка. Проверка на корректность указания группы атрибутов происходит на этапе работы метода
setAttrCodes — массив, содержащий перечисление кодов атрибутов из группы, указанной в методе setAttrGroup. Используется для уточнения набора колонок списка на основании переданного перечня кодов атрибутов (аналог "Настройки полей" в списке). Необязательный метод: по умолчанию набор колонок списка определяется группой атрибутов, переданной в методе setAttrGroup
setSimple — представление списка = "Простой список". Необязательный метод: по умолчанию список имеет представление "Сложный список"
setPaging — строка, определяющая расположение постраничной навигации (необязательный метод):
- both — "Над списком и под списком";
- top — "Над списком";
- bottom (по умолчанию) — "Под списком"
sortAsc — строка, содержащая перечисление кодов атрибутов, по которым будет производиться прямая сортировка списка.

Необязательный метод, по умолчанию сортировка к списку не применяется.

Для сортировки доступны атрибуты из группы атрибутов списка.

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

Допустима сортировка атрибутов, присутствующих в группе атрибутов (из setAttrGroup) во всех типах, указанных в setCases.

Сортировка не применяется при открытии ссылки в браузерах Internet Explorer 8 и 9.
sortDesc — строка, содержащая перечисление кодов атрибутов, по которым будет производиться обратная сортировка списка.

Необязательный метод, по умолчанию сортировка к списку не применяется.

Для сортировки доступны атрибуты из группы атрибутов списка.

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

Допустима сортировка атрибутов, присутствующих в группе атрибутов (из setAttrGroup) во всех типах, указанных в setCases.

Сортировка не применяется при открытии ссылки в браузерах Internet Explorer 8 и 9.
filter — представляет собой самостоятельный билдер, использующийся для задания ограничения содержимого списка (за исключением указанной быстрой фильтрации и ограничения настроек фильтрации, которые передаются в явном виде). Описание использования критериев фильтрации в механизме генерации ссылки на список см. Критерии фильтрации для атрибутов по типам

Билдер имеет следующие методы:
- AND. В метод AND в качестве параметра можно передавать значение, полученное применением метода OR.
- OR. В качестве параметров метода передаются: код атрибута сортировки, код критерия фильтрации и значение фильтрации.
  
  В качестве значения кода атрибута фильтрации можно передавать также перечисление ссылочных атрибутов через точку ".". Итоговая фильтрация будет применяться к последнему атрибуту в цепочке.
- fastFilter — определяет быструю фильтрацию. В качестве параметра метода передается условие фильтрации filter.OR. Метод сообщает о формировании быстрой фильтрации списка.
  
  Если для атрибута доступна фильтрация, но недоступна быстрая фильтрация (например атрибуты типов "Лицензия", "Счетчик времени"), то при передаче для таких атрибутов быстрой фильтрации фильтрация применяется верно, однако в операторе никак не отображается.
  
  Указанная быстрая фильтрация применяется к формируемому списку как быстрая фильтрация, а не как ограничение содержимого списка.
- fastSubstringFilter — определяет быструю фильтрацию по подстроке. В качестве параметра метода передается условие фильтрации filter.OR. Метод сообщает о формировании быстрой фильтрации списка по подстроке.
  
  Если для атрибута доступна фильтрация, но недоступна быстрая фильтрация (например атрибуты типов "Лицензия", "Счетчик времени"), то при передаче для таких атрибутов быстрой фильтрации фильтрация применяется верно, однако в операторе никак не отображается.
  
  Указанная быстрая фильтрация по подстроке применяется к формируемому списку как быстрая фильтрация по подстроке, а не как ограничение содержимого списка.
- restrictionFilter — определяет ограничение настроек фильтрации списка. В качестве параметров метода передаются: код атрибута сортировки, код типа ограничения настроек фильтрации и значение фильтрации.
  
  В качестве кодов критериев фильтрации доступны следующие значения:
  - 'LIST' — соответствует ограничению по содержимому в списке. Указывать значение фильтрации в этом случае не нужно.
  - 'SCRIPT' — соответствует ограничению скриптом. В качестве значения фильтрации в этом случае нужно указать код используемого скрипта.
  В итоговой конструкции билдера на одном уровне не могут одновременно применяться методы AND и OR.
  
  Необязательный метод, по умолчанию ограничение содержимого списка к списку не применяется.
  
  Контекстные критерии фильтрации, локали пользователя, часовой пояс и другие параметры, от которых может зависеть фильтрация, определяются в момент построения списка в приложении и не передаются в ссылке.
  
  Ограничение содержимого списка применяется к объектам из списка; для ограничения содержимого списка доступны все атрибуты класса объектов и атрибуты всех вложенных в него типов.
  
  Допустима сортировка атрибутов, присутствующих в группе атрибутов (из setAttrGroup) во всех типах, указанных в setCases.
- equals — фильтрация по равенству.
  
  Оператор equals реализован исключительно для фильтрации по UUID, при попытке фильтрации оператором equals по любому другому атрибуту — фильтрация будет игнорироваться.
  
  Для фильтрации по UUID доступны все операторы, которые совместимы с атрибутами типа "Строка".
Особенности определения фильтров для некоторых типов атрибутов:
1. Набор типов классов должен передаваться как коллекция ClassFqn:
  
  filter.OR('setOfCases', 'contains', [api.metainfo.getMetaClass('userclass$UserType').getFqn()])
2. Значение в фильтрации определяется как DTObject, uuid которого равен AttributeFqn объекта:
  
  filter.OR('<код атрибута объекта списка>', '<критерий фильтрации>', api.metainfo.getMetaClass('<код класса объекта, с атрибутом которого сравниваем>').getAttribute('<код атрибута>').getAttributeFqn())
  
  Пример фильтра:
  
  filter.OR('title', 'containsUserAttribute', api.metainfo.getMetaClass('employee').getAttribute('lastName').getAttributeFqn())
3. Целые числа должны передаваться как Long (то есть, указывая "L" в конце):
  
  filter.OR('creationDate', 'lastN', 5L)
4. Статус счетчика должен передаваться как код: ACTIVE("a"), EXCEED("e"), NOTSTARTED("n"), PAUSED("p"), STOPED("s").
  
  Пример фильтра для статусов "Активен" и "Кончился запас НВ":
  
  filter.OR('timeAllowanceTimer', 'timerStatusContains', ['e','a'])
  
  Для критерия фильтрации backTimerDeadLineContains доступны два варианта: Просрочен: "exceed", Не просрочен: "noExceed":
  
  //filter.OR('timeAllowanceTimer', 'backTimerDeadLineContains', 'exceed')
  
  filter.OR('timeAllowanceTimer', 'backTimerDeadLineContains', 'noExceed')

Примеры ссылок на список

Пример 1: Генерация ссылки на список на отдельной странице с полным набором параметров:

Copy

def builder = api.web.defineListLink(false).setTitle("Заголовок списка").setClassCode("userclass").setAttrGroup("system");
def filter = builder.filter();
filter.AND(
filter.OR('title', 'contains', 'other'),
filter.OR('metaClass', 'contains', 'userclass$UserType21')
)
.AND(
filter.OR('creationDate', 'fromTo', [new Date().parse("dd.MM.yyyy HH:mm", "29.03.2019 15:59"), null])
)
.AND(
filter.OR('linktosc', 'notContains', utils.get('serviceCall$6602'))
)
.AND(
filter.OR('state', 'titleNotContains', 'Закрыт')
)
builder.sortDesc('title').sortDesc('metaClass');
builder.setCases(['UserType21','UserType22']);
builder.setPaging('both');
builder.setUsers(['superUser$naumen','employee$6403','employee$6401']);
builder.setDaysToLive(2);
builder.setAttrCodes(['title','creationDate']);
//builder.setTemplate("TestovyiShablon");
//builder.setSimple();
api.web.list(builder);

Результат:

http://localhost:18080/sd/operator/?anchor=list:userclass:system::TOP_AND_BOTTOM:!!encoded_prms=encoded_text$579321

Пример 2: Генерация ссылки на список на карточке объекта с полным набором параметров:

Copy

def builder = api.web.defineListLink(true).setUuid('root$401').setListCode('tab1list2');
def filter = builder.filter();
filter.AND(
filter.OR('title', 'contains', 'код-3'),
filter.OR('metaClass', 'contains', 'serviceCall$ACHsc')
)
.AND(
filter.OR('creationDate', 'fromTo', [new Date().parse("dd.MM.yyyy HH:mm", "19.07.2018 18:50"), new
Date().parse("dd.MM.yyyy HH:mm", "19.02.2019 10:00")])
)
.AND(
filter.OR('massProblem', 'contains', false)
)
.AND(
filter.OR('number', 'contains', 3),
filter.OR('number', 'contains', 2)
)
builder.sortDesc('title').sortDesc('creationDate');
builder.setDaysToLive(2);
//builder.setSimple();
api.web.list(builder);

Пример 3. Пример вызова метода с применением быстрой фильтрации:

Copy

def builder = api.web.defineListLink(false).setTitle("Заголовок списка").setClassCode("UserClass").setAttrGroup("system");
def filter = builder.filter();
filter.fastFilter(
filter.OR('title', 'contains', 'KKK')
);
builder.setPaging('bottom');
api.web.list(builder);

Пример 4. Пример вызова сигнатуры для передачи быстрой фильтрации по подстроке:

Copy

def filter = builder.filter();
filter.fastSubstringFilter(
filter.OR('metaClass', 'titleContains', 'dddddd'),
);

Пример 5. Пример получения ссылки на список на отдельной странице, построенный на базе списка связанных объектов:

Copy

def builder = api.web.defineListLink(false).setTitle("Заголовок списка").setClassCode("ou").setAttrGroup("system").setUuid('root$501').setListType('RelObjectList').setNested(true);
def attrChain = builder.attrChain();
attrChain.attributesChain('root@NboOU','ou@author').nestedHierarchyAttrFqn('root@NboOU').nestedAttrLinkFqn('ou@parent');
api.web.list(builder);

Пример 6. Пример получения ссылки на список на отдельной странице, построенный на базе списка связанных объектов с использованием иерархии:

def builder = api.web.defineListLink(false).setTitle("Заголовок списка").setClassCode("team").setUuid('ou$4001').setAttrGroup("system").setListType('RelObjectList');
builder.relatedWithNestedParams(['ou@currentObject'], 'ou@parent', ['ou@currentObject', 'ou@head', 'employee@teams']);
api.web.list(builder);

Пример 7. Вызов сигнатуры для передачи ограничения настроек фильтрации:

Copy

//Ограничение по содержимому в списке
def filter = builder.filter();
filter.restrictionFilter(
filter.OR('UserClass@NBO', 'LIST', )
);

//Ограничение скриптом
filter.restrictionFilter(
filter.OR('UserClass@NBO', 'SCRIPT', 'titleScript')
);

Пример 8. Вызов сигнатуры для передачи ограничения настроек фильтрации по атрибуту "Статус":

//Ограничение по содержимому в списке
def builder = api.web.defineListLink(false)
builder.setTitle("Не закрытые задачи на пользователях")
.setClassCode('serviceCall')
.setAttrGroup('system')
def filter = builder.filter()
filter.AND(filter.OR('state', 'contains', 'serviceCall:closed'))
return api.web.list(builder)

Пример 9. Вызов сигнатуры для передачи ограничения настроек фильтрации, где атрибут фильтрации определяется через цепочку ссылочных атрибутов:

//Ограничение по содержимому в списке
def builder = api.web.defineListLink(false)
builder.setTitle("Сотрудники с не закрытыми запросами")
   .setClassCode('employee')
   .setAttrGroup('system')
def filter = builder.filter()
filter.AND(filter.OR('serviceCalls.state', 'contains', 'serviceCall:closed'))
return api.web.list(builder)

Пример 10. В результирующем списке будут отображаться все объекты ou, UUID которых равен ou$2021:

def builder = api.web.defineListLink(false)
   .setTitle('Название списка')
   .setClassCode('ou')
   .setAttrGroup('system')
def filter = builder.filter()
filter.AND(filter.OR('UUID', 'equals', 'ou$2021'))
api.web.list(builder)

Ссылка на иерархическое дерево в веб-интерфейсе

api.web.content(linkDefinition)

Генерация ссылки на контент на отдельной странице.

Возвращает ссылку на контент на отдельной странице в соответствии с параметрами, переданными в linkDefinition. Этот объект создается с помощью методов, предусмотренных для отдельных контентов, например, "Иерархическое дерево".
api.web.defineHierarchyGridLink()

Создает и возвращает билдер для ссылки на контент типа "Иерархическое дерево".

Пример. Генерация ссылки на иерархическое дерево на основе шаблона с кодом templateHG по структуре с кодом orgstruct. В дереве активирована фокусировка со скрытием, оно доступно только профилю operator. Ссылка действительна в течение 30 дней:
Copy
```
def linkDefinition = api.web.defineHierarchyGridLink()
.setTemplate('templateHG')
.setStructureCode('orgstruct')
.setObjectFocusMode('FOCUS_WITH_HIDDEN')
.setDaysToLive(30)
.setProfiles(['operator']);
def link = api.web.content(linkDefinition);
```

Общие методы билдера

setUsers — строка, содержащая UUID пользователей, которым доступна страница. Необязательный метод, по умолчанию значение пусто и страница с иерархическим деревом доступна всем пользователям с учетом ограничения по профилям.
setDaysToLive — продолжительность жизни ссылки в днях. Необязательный метод, по умолчанию берутся из параметра файле dbaccess.properties. Если значение в dbaccess.properties неуказано, то оно равно 30 дням

Методы билдера для иерархического дерева

setTemplate (template) — строка, содержащая код шаблона контента, которому будет соответствовать отображение полученного иерархического дерева. Необязательный метод.
setTitle — строка, содержащая название иерархического дерева.
setProfiles(List<String> profiles) — список кодов профилей, которым доступен контент. Переопределяет соответствующий параметр из шаблона.
setContextFqn(Object contextFqn) — FQN класса/тип объекта окружающего контекста. Если задан совместно с шаблоном, должен совпадать со значением из шаблона.
setObject(Object object) — Задает объект окружающего контекста. Если в шаблоне или через параметр задан класс/тип объекта контекста, то переданный объект должен иметь этот же либо унаследованный тип.

Поддерживается конструкция currentUser по аналогии со списками на отдельной странице.
setStructureCode(String structureCode) — код структуры иерархического дерева в виде строки. Обязательный параметр. Если шаблон задан, структура из шаблона должна совпадать с указанной в качестве параметра метода.
setBuildHierarchyFromCurrentObject(boolean buildHierarchyFromCurrentObject) — признак необходимости построения дерева от текущего объекта. Переопределяет соответствующий параметр из шаблона.
setObjectFocusMode(String objectFocusMode) — тип фокусировки на объекте контекста. Переопределяет соответствующий параметр из шаблона.

Возможные значения:
- OFF — выключено;
- FOCUS_WITH_HIDDEN — фокусировка со скрытием;
- FOCUS_WITHOUT_HIDDEN — фокусировка без скрытия.

Ссылка на комментарий, файл или объект списка в мобильном приложении

api.web.openCommentInList(objUUID, commentUUID)

Генерация URL-ссылки для позиционирования на конкретном комментарии в списке комментариев определенного объекта.

Параметры метода:
- objUUID — uuid объекта;
- commentUUID — uuid комментария, на котором необходимо позиционироваться.
  
  Допустимо использование sourceObject — в случае события "добавление комментария" возвращается добавленный комментарий.
Возвращает строку, содержащую URL-ссылку для позиционирования на конкретном комментарии в списке комментариев определенного объекта.

Пример. Ссылка для позиционирования на комментарии commentUUID в списке комментариев в объекте subject:

pushMobile.link << api.web.openCommentInList(subject.UUID, "commentUUID")
api.web.openFileInList(objUUID, fileUUID)

Генерация URL-ссылки для позиционирования на конкретном файле в списке файлов определенного объекта.

Параметры метода:
- objUUID — uuid объекта;
- fileUUID — uuid файла, на котором необходимо позиционироваться.
  
  Возможно использование sourceObject — в случае события "прикрепление файла к объекту" возвращает прикрепленный файл.
Возвращает строку, содержащую URL-ссылку для позиционирования на конкретном файле в списке файлов определенного объекта.

Пример. Ссылка для позиционирования на файле fileUUID в списке файлов в объекте subject:

pushMobile.link << api.web.openFileInList(subject.UUID, "fileUUID")
api.web.openObjectInList(listUUID, objUUID)

Генерация URL-ссылки для позиционирования на конкретном объекте в списке объектов.

Параметры метода:
- listUUID — uuid списка объектов в мобильном приложении (отображается в url-строке в настройках списков мобильного приложения);
- objUUID — идентификатор объекта, на который позиционируется ссылка.
Возвращает строку, содержащую URL-ссылку для позиционирования на конкретном объекте в списке объектов.

Пример. Ссылка для позиционирования на объекте subject в списке объектов с UUID "f9eceb6e-1549-0b63-0001-00001417f2b7":

pushMobile.link <<api.web.openObjectInList('f9eceb6e-1549-0b63-0001-00001417f2b7', subject.UUID)

Ссылка на форму в мобильном приложении

api.web.edit(subject, mobileForm)

api.web.edit(subject, mobileForm, attributes)

api.web.edit(subject, login_or_accesskey, mobileForm)

Генерация URL-ссылки для перехода на форму редактирования в мобильном приложении.

Параметры метода:
- subject — объект, форма редактирования которого будет открыта при переходе по ссылке;
- login_or_accesskey — логин или ключ авторизации пользователя для входа в систему (по имени пользователя или по uuid пользователя), см. api.auth Работа с ключами авторизации.
- mobileForm — код формы редактирования в мобильном приложении. Может быть null.
  
  Если параметр указан, то ссылка будет содержать код формы редактирования и при переходе по ссылке в мобильном приложении будет открыта указанная форма редактирования.
- attributes — ассоциативный массив, содержащий значения атрибутов, передаваемых на форму редактирования: ключ — код атрибута; значение — значение атрибута
  
  Доступные типы атрибутов: BOLinks, BOLink, BackLink, CatalogItems, Date, DateTime, Integer, Double, Boolean, DateTimeInterval, Hyperlink.
Возвращает строку, содержащую URL-ссылку на форму редактирования.
api.web.add(fqn, mobileForm, parent, attributes, needCheckAttrs)

api.web.add(fqns, mobileForm, parent, attributes)

Генерирует URL-ссылку для перехода на форму добавления объекта указанного типа /класса.

Если указаны parent и attributes, то формирует ссылку для перехода на форму добавления объекта без проверок на существование заданных атрибутов в классе/типе и корректности их значений.

Если указано needCheckAttrs, то формирует URL-ссылку на форму добавления объекта указанного типа /класса с предзаполненными полями с проверкой на существование заданных атрибутов в классе/типе и корректности их значений.

При переходе по ссылке требуется указывать логин и пароль, также может использоваться прозрачная аутентификация (Kerberos).

Параметры метода:
- fqns — коллекция fqn'ов доступных для выбора типов добавляемого объекта. Допускается указывать только типы объектов одного класса. Значение fqn может быть как объект ClassFqn, так и его строковый эквивалент.
- fqn — класс (тип), форма добавления которого открывается при переходе по ссылке. Значение fqn может быть как объект ClassFqn, так и его строковый эквивалент
  
  Если параметр fqn указывает на тип, то при переходе по ссылке будет открыта форма добавления этого типа, контент "Тип объекта" на форме не отобразится, если на класс – будет открыта форма добавления класса с возможностью выбора любого доступного пользователю типа этого класса.
  
  Если ассоциативный массив, заданный в параметре attributes не пуст, соответствующие поля формы при ее открытии будут заполнены указанными значениями.
- mobileForm — код формы добавления в мобильном приложении. Может быть null.
  
  Если mobileForm указан, то при переходе по ссылке в мобильном приложении будет открыта указанная форма добавления
- parent — в зависимости от класса, на который указывает fqn, параметр рассматривается как:
  - контрагент запроса, если fqn задает класс "Запрос" (serviceCall).
  - родительский объект, если fqn задает класс вложенных объектов.
  Если fqn указывает на классы, не перечисленные выше, то данный параметр заполняется значением null или пустой строкой.
  
  Параметр может быть задан в виде объекта или строки, содержащей его UUID.
- attributes — ассоциативный массив, содержащий значения по умолчанию для атрибутов создаваемого объекта: ключ — код атрибута; значение — значение по умолчанию атрибута
  
  Доступные типы атрибутов: BOLinks, BOLink, BackLink, CatalogItems, Date, DateTime, Integer, Double, Boolean, DateTimeInterval, Hyperlink.
- needCheckAttrs — признак, определяющий требуются ли проверки на существование заданных атрибутов в классе/типе и корректности их значений
Возвращает строку, содержащую URL-ссылку на форму добавления объекта указанного типа (класса).

Генерация ссылки на форму авторизации

api.web.signIn(employee)

Формирование ссылки на форму авторизации с заполненным логином.

Параметр метода:
- employee — объект, UUID или логин пользователя.
Возвращает строку со ссылкой для открытия формы авторизации.

Пример 1. Генерация ссылки на форму авторизации с заполненным логином, в аргумент передается логин пользователя:

api.web.signIn('user')

Результат: http://localhost:8080/sd/?smp_login=user.

Пример 2. Генерация ссылки на форму авторизации с заполненным логином, в аргумент передается UUID пользователя:

api.web.signIn('employee$6001')

Результат: http://localhost:8080/sd/?smp_login=testlogin.

Пример 3. Генерация ссылки на форму авторизации с заполненным логином, в аргумент передается объект пользователя:

api.web.signIn(utils.get('employee$6001'))

Результат: http://localhost:8080/sd/?smp_login=testlogin.

Примечание: любая ссылка, содержащая параметр smp_login, открывается после перехода в указанный аккаунт.

Ссылка на вкладку с результатами расширенного поиска

api.web.openSearch(classFqn, values)

api.web.openSearch(classFqn, values, accessKey)

api.web.openSearch(classFqn, values, mode, accessKey)

api.web.openSearch(classFqn, values, username)

api.web.openSearch(classFqn, values, mode, username)

Генерация ссылки на вкладку с результатами расширенного поиска в интерфейсе оператора с возможностью указания логина или ключа доступа.

Параметры метода:
- classFqn — идентификатор метакласса. Object или строковое представление идентификатора метакласса;
- values — набор атрибутов для поиска. [КодАтрибута:Значение]. Map<String,Object>;
- accessKey — ключ доступ. IAccessKeyWrapper;
- mode — тип поиска: "active" (не архивные), "removed" (архивные), "all" (все). String;
- username — логин пользователя. String.
Возвращает ссылку на вкладку с результатами расширенного поиска в интерфейсе оператора.

Если в параметре values указан хотя бы один атрибут, для которого не настроен ни быстрый, ни расширенный поиск, то метод возвращает ошибку: "Для атрибута %код атрибута%" не настроен поиск. Обратитесь к администратору системы.

api.websocket Методы для работы с Websocket-каналом

api.websocket.sendMessage('destination', 'message')

Применяется совместно с JSAPI для работы с websocket.

На клиенте создается websocket-соединение и клиенты на него подписываются.

Со стороны сервера могут отправляться сообщения, всем подписанным на определенный адрес (destination) клиентам.

Для корректной работы метода необходима настройка обратного прокси, см. Настройка WebSocket.

Параметры метода:
- destination — адрес назначения сообщения;
- message — текст отправляемого сообщения.

api.wf Получение статуса и списка переходов

api.wf.state(subject)

Получение статуса объекта:
api.wf.transitions(subject)

Получение списка возможных переходов из текущего статуса:

Также статус объекта может быть получен с помощью api.metainfo.

api.reports | api.parameters Работа с отчетами и печатными формами

api.reports Работа с отчетом

api.reports.getTemplateTitle(templateCode)

Получение названия отчета.

Параметр метода:
- templateCode — код шаблона отчета (печатной формы)
Возвращаемое значение:
- Название шаблона отчета (печатной формы).
- Пустая строка —если шаблона отчета (печатной формы) с указанным кодом не существует
api.reports.hasParameter(templateCode, parameter)

Проверка наличия в шаблоне отчета (печатной формы) параметра с указанным кодом.

Параметры метода:
- templateCode — код шаблона отчета (печатной формы)
- parameter — код параметра отчета (печатной формы)
Возвращаемое значение:
- true — если параметр с указанным кодом существует;
- false — если параметра с указанным кодом не существует, если шаблона отчета (печатной формы) с указанным кодом отчета (печатной формы)
api.reports.hasParameters(templateCode, parameter)

Проверка наличия в шаблоне отчета (печатной формы) параметров с указанным кодом.

Параметры метода:
- templateCode — код шаблона отчета (печатной формы)
- parameters — коды параметров отчета (печатной формы)
Возвращаемое значение:
- true — если параметры с указанными кодами существует;
- false — если параметры с указанными кодами не существуют, если шаблона отчета (печатной формы) с указанным кодом не существует.
api.reports.getReportLink(templateCode, subjectUUID, parametersValues)

api.reports.getReportLink(templateCode, reportTitle, subjectUUID, parametersValues)

Генерация ссылки на карточку экземпляра отчета (печатной формы), построенного по указанному шаблону.

Параметр метода:
- templateCode — код шаблона отчета (печатной формы)
- reportTitle — название отчета
- subjectUUID — uuid объекта, относительно которого строится отчет. Значение будет передано в контекстную переменную отчета subject
- parametersValues — ассоциативный массив: ключ — код атрибута; значение — значение атрибута
Возвращает строку, содержащую URL-ссылку на карточку указанного отчета (печатной формы).

Пример. Вызов метода с параметрами всех типов:

def link = api.reports.getReportLink(templateCode, 'root$101', ['string1':'abracadabra','integer1':987L,'double1':765.23D,'boolean1':false,'date1':new Date()+3,'dateTime1':new Date()-5,'catalogItem1':'urgency$1002','object1':'employee$2225','catalogItems1':['impact$1201','impact$1205','impact$1202'],'objects1':['employee$2241','employee$2227','employee$2223','employee$2211']]))

Особенности:
- Для параметров типа integer в конце значения указывается L. Пример 'integer1':987L
- Для параметров типа double в конце значения указывается D. Пример 'double1':765.23D
- Если оставить всю строку пустой в скобках [:], то в отчет попадают значения по умолчанию, указанные в скрипте шаблона отчетов
api.reports.getReportDataSource(templateCode, subjectUUID, parametersValues, format)

Генерация отчета (печатной формы) по шаблону в определенном формате и отправка его по почте.

Параметры метода:
- templateCode — код шаблона отчета (печатной формы). String.
- subjectUUID — uuid объекта, относительно которого строится отчет (печатная форма). Для использования переменной subject в отчетах. String.
- parametersValues — ассоциативный массив: ключ — код атрибута; значение — значение атрибута.
- format — формат отчета (печатной формы). Допустимые параметры: pdf, xls, csv, htmlZip, docx. String.
api.reports.getReportDataSources(templateCode, subjectUUID, parametersValues, formats)

Генерация отчета (печатной формы) по шаблону в нескольких форматах и отправка его по почте.

Параметры метода:
- templateCode — код шаблона отчета (печатной формы). String.
- subjectUUID — uuid объекта, относительно которого строится отчет (печатная форма). Для использования переменной subject в отчетах. String.
- parametersValues — ассоциативный массив: ключ — код атрибута; значение — значение атрибута.
- formats — форматы отчета (печатной формы). Допустимые параметры: pdf, xls, csv, htmlZip, docx. String.
Пример скрипта см. Настройка отправки отчета (печатной формы) по почте.
api.reports.getReportDataSource(reportFileBytes, customScript, subject, parametersValues, formats)

Генерация DataSource для отчета в определенном формате. В методе происходит построение отчета по шаблону. В дальнейшем может использоваться для отправки сгенерированного отчета письмом.

Параметры метода:
- reportFileBytes — данные файла отчета *.prpt в виде. Byte[].
- customScript — скрипт кастомизации отчета. Object.
- subject — объект, относительно которого строится отчет (для использования переменной subject в отчетах). Object.
- parametersValues — ассоциативный список значений параметров <Код параметра, Значение параметра>.
- formats — формат отчета. Допустимые параметры: pdf, xls, xlsx, csv, htmlZip. String.
Возвращает DataSource сгенерированного отчета.
api.reports.getReportExportedFileUuid(templateCode, subjectUUID, parametersValues, format)

api.reports.getReportExportedFileUuid(templateCode, reportTitle, subjectUUID, parametersValues, format)

Экспорт отчета в указанном формате (экспортированный файл доступен всем пользователям).

Параметры метода:
- templateCode — код шаблона отчета (печатной формы). String
- reportTitle — название отчета. String
- subjectUUID — uuid объекта, относительно которого строится отчет (печатная форма). Для использования переменной subject в отчетах. String
- parametersValues — ассоциативный массив: ключ — код атрибута; значение — значение атрибута
- format — формат отчета (печатной формы). Допустимые параметры: pdf, docx, xls, xlsx, csv, htmlZip. String
api.reports.getReportExportedFilesUuid(templateCode, subjectUUID, parametersValues, formats)

api.reports.getReportExportedFilesUuid(templateCode, reportTitle, subjectUUID, parametersValues, formats)

Экспорт отчета в указанных форматах (экспортированный файл доступен всем пользователям).

Параметры метода:
- templateCode — код шаблона отчета (печатной формы). String
- reportTitle — название отчета. String
- subjectUUID — uuid объекта, относительно которого строится отчет (печатная форма). Для использования переменной subject в отчетах. String
- parametersValues — ассоциативный массив: ключ — код атрибута; значение — значение атрибута
- formats — формат отчета (печатной формы). Допустимые параметры: pdf, docx, xls, xlsx, csv, htmlZip. String
api.reports.createAndSendExportedReport(templateCode, reportTitle, subjectUUID, parametersValues, format, emails)

Построение отчета, экспорт отчета в указанном формате и отправка на указанные email адреса (экспортированный файл доступен всем пользователям).

Параметры метода:
- templateCode — код шаблона отчета (печатной формы). String
- reportTitle — название отчета. String
- subjectUUID — uuid объекта, относительно которого строится отчет (печатная форма). Для использования переменной subject в отчетах. String
- parametersValues — ассоциативный массив: ключ — код атрибута; значение — значение атрибута
- format — формат отчета (печатной формы). Допустимые параметры: pdf, docx, xls, xlsx, csv, htmlZip. String
- emails — список email адресов, на которые отправится письмо. ArrayList<String>
api.reports.createAndSendExportedReport(templateCode, reportTitle, subjectUUID, parametersValues, format, email)

Построение отчета, экспорт отчета в указанном формате и отправка на указанный email адрес (экспортированный файл доступен всем пользователям).

Параметры метода:
- templateCode — код шаблона отчета (печатной формы). String
- reportTitle — название отчета. String
- subjectUUID — uuid объекта, относительно которого строится отчет (печатная форма). Для использования переменной subject в отчетах. String
- parametersValues — ассоциативный массив: ключ — код атрибута; значение — значение атрибута
- format — формат отчета (печатной формы). Допустимые параметры: pdf, docx, xls, xlsx, csv, htmlZip. String
- email — email адрес, на который отправится письмо. String.
Пример:

api.reports.createAndSendExportedReport('reportCode', 'reportTitle', 'root$301', [:], 'pdf', ['user@test.com'])

api.reports.table. Формирование таблицы отчета /печатной формы

api.reports.table()

Формирование таблицы отчета и получение данных, альтернатива SQL запросу. После вызова метод таблица наполняется данными, например, через Db Api. Получение строк таблицы, значения столбца с определенным кодом в строке, изменение или добавление вычисленного в скрипте значения в таблицу отчета.

Пример. Вычисление общего количества запросов и установка в каждую строку процентов от общего (в строке таблицы отчета выводится группа запросов, servicecalls — количество запросов в этой группе):
```
def all = table.rows.collect {row -> row.servicecalls}.sum();
table.rows.each() { row ->
row.percents = String.format("%.2f", row.servicecalls * 100.0 / all) + '%';
}
return table;
```

getFunctions. Кастомизация шаблона отчета

getFunctions()

Определение функции для расширения набора стандартных функций Pentaho Report Designer. Функции, определенные в скрипте, должны быть вынесены в шаблон отчета PRD, см. Использование функций, определенных в скрипте отчета.

Доступные переменные:
- subject (объект, на карточке которого строится отчет)
- user (текущий пользователь)
Пример 1:
```
* totalFunction — анализирует все строки отчета

def getFunctions()
def usr = user?.login
return [ api.reports.totalFunction('usr', { rows -> usr }) ]
}
```
Пример 2:
```
* groupFunction — отдельно анализирует каждую группу
def getFunctions() {
return [ api.reports.groupFunction('usr', { rows -> api.tx.call() { user?.login } }) ]
}
```

api.parameters Параметры отчета /печатной формы

Методы для определения параметров отчета /печатной формы, которые будут указываться при построении отчета. Для каждого типа параметров используется соответствующий метод.

api.parameters.get"parameter type"(code, title, defaultValue, required)

Определение параметров типа "Строка", "Целое число", "Дробное число".

Параметры метода:
- code — код параметра;
- title — название параметра, которое будет выводиться на форму добавления отчета и форму редактирования параметров отчета.
  
  Если название null, то параметр на форму не выводится, но доступен в отчете;
- defaultValue — значение по умолчанию для данного параметра;
- required — обязательность заполнения параметра отчета:
  - false (по умолчанию) или пусто— параметр не обязателен для заполнения;
  - true — параметр обязателен для заполнения и отмечен на форме звездочкой
Пример. Определение параметров "Строка", "Целое число", "Дробное число":
```
def getParameters() {
return 
[api.parameters.getString("string1", "Строка", "строка по умолчанию"),
api.parameters.getInteger("integer1", "Целое число", 123),
api.parameters.getDouble("double1", "Дробное число", 123.45, true),
] as List;
 }
```
api.parameters.getBoolean(code, title, defaultValue)

Определение параметра типа "Логический".

Параметры метода:
- code — код параметра;
- title — название параметра, которое будет выводиться на форму добавления отчета и форму редактирования параметров отчета.
  
  Если название null, то параметр на форму не выводится, но доступен в отчете;
- defaultValue — значение по умолчанию для данного параметра.
Пример. Определение параметра "Логический":

api.parameters.getBoolean("boolean1", "Логический", true)
api.parameters.getDate(code, title, defaultValue, required)

api.parameters.getDateTime(code, title, defaultValue, required)

api.parameters.getDateTime(code, title, defaultValue, ofFillingTime, required)

Определение параметров типа "Дата", "Дата/время". Время указывается в часовом поясе пользователя. Если пользовательский часовой пояс [не указано], то берется часовой пояс сервера, на котором установлено приложение.

Параметры метода:
- code — код параметра;
- title — название параметра, которое будет выводиться на форму добавления отчета и форму редактирования параметров отчета. Если название null, то параметр на форму не выводится, но доступен в отчете;
- defaultValue — значение по умолчанию для данного параметра;
- ofFillingTime — способ заполнения времени:
  - если этот аргумент не указан, то при заполнении параметра типа "Дата и время" из календаря подставляется указанная дата и текущее время;
  - значение "startOfDay", подставляется указанная дата и время "00:00";
  - значение "endOfDay", подставляется указанная дата и время "23:59".
  Параметр ofFillingTime передается в отчет только в случае задания или изменения даты пользователем вручную. Если используется значение по умолчанию, то значение не подставится.
- required — обязательность заполнения параметра отчета:
  - false (по умолчанию) или пусто — параметр не обязателен для заполнения;
  - true — параметр обязателен для заполнения и отмечен на форме звездочкой
Пример. Определение параметров "Дата", "Дата/время":
```
def getParameters() {
return 
[api.parameters.getDate("date1", "Дата", new Date(), true),
api.parameters.getDateTime("dateTime1", "Дата-время", new Date()),
api.parameters.getDateTime("dateFrom","Дата с", null, "startOfDay"),
] as List;
 }
```

api.parameters.getDate("beginDate", BEGIN_DATE)

api.parameters.getDate("endDate", END_DATE)

Определение параметра типа "Временной интервал" (Даты с, по).

Пример. Определение параметров "Временной интервал":

def getParameters()
{
//ПАРАМЕТРЫ--------------------------------
BEGIN_DATE = 'С' // Дата начала периода
END_DATE = 'По' // Дата конца периода
return 
[api.parameters.getDate("beginDate", BEGIN_DATE),
api.parameters.getDate("endDate", END_DATE) 
] as List;
};

api.parameters.getCatalogItem(code, title, catalogCode, defaultValue, required) Определение параметра типа "Элемент справочника".

Параметры метода:
- Обязательные:
  - code — код параметра;
  - title — название параметра, которое будет выводиться на форму добавления отчета и форму редактирования параметров отчета.
    
    Если название null, то параметр на форму не выводится, но доступен в отчете;
  - catalogCode — код справочника, элементы которого можно будет выбрать в параметре;
- Дополнительные:
  - defaultValue — значение по умолчанию для данного параметра. UUID;
  - required — обязательность заполнения параметра отчета:
    - false (по умолчанию) или пусто — параметр не обязателен для заполнения;
    - true — параметр обязателен для заполнения и отмечен на форме звездочкой
Пример. Определение параметра "Элемент справочника":

api.parameters.getCatalogItem("catalogItem1", "Справочник", "currency", "currency\$1303", true)
api.parameters.getCatalogItems(code, title, catalogCode, required)

api.parameters.getCatalogItems(code, title, catalogCode, defaultValue, required)

Определение параметра типа "Набор элементов справочника" (1).

Параметры метода:
- Обязательные:
  - code — код параметра;
  - title — название параметра, которое будет выводиться на форму добавления отчета и форму редактирования параметров отчета.
    
    Если название null, то параметр на форму не выводится, но доступен в отчете;
  - catalogCode — код справочника, элементы которого можно будет выбрать в параметре;
- Дополнительные:
  - defaultValue — значение по умолчанию для данного параметра, может быть null;
  - required — обязательность заполнения параметра отчета:
    - false (по умолчанию) или пусто — параметр не обязателен для заполнения;
    - true — параметр обязателен для заполнения и отмечен на форме звездочкой
api.parameters.getCatalogItemsByCodes(code, title, catalogCode, required)

api.parameters.getCatalogItemsByCodes(code, title, catalogCode, defaultValue, required)

Определение параметра типа "Набор элементов справочника" (2).

Параметры метода:
- Обязательные:
  - code — код параметра;
  - title — название параметра, которое будет выводиться на форму добавления отчета и форму редактирования параметров отчета.
    
    Если название null, то параметр на форму не выводится, но доступен в отчете;
  - catalogCode — код справочника, элементы которого можно будет выбрать в параметре;
- Дополнительные:
  - defaultValue — значение по умолчанию для данного параметра, может быть null;
  - required — обязательность заполнения параметра отчета:
    - false (по умолчанию) или пусто — параметр не обязателен для заполнения;
    - true — параметр обязателен для заполнения и отмечен на форме звездочкой
api.parameters.getObject(code, title, metaClass, defaultValue, required)

api.parameters.getObject(code, title, metaClass, defaultValue, required)

api.parameters.getObject(code, title, metaClass, defaultValue, key1: value1, ..., required)

Определение параметра типа "Объект".

Параметры метода:
- code — код параметра;
- title — название параметра, которое будет выводиться на форму добавления отчета и форму редактирования параметров отчета. Если название null, то параметр на форму не выводится, но доступен в отчете;
- metaClass — код метакласса, объект которого можно будет выбрать в параметре;
- defaultValue — значение по умолчанию для данного параметра;
- [key1: value1, ...] — определяет возможность выбора объектов с помощью формы выбора объекта и /или представления для редактирования:
  - key — "presentationCode" (представление для редактирования);
  - value — "0" (дерево выбора), "1" (дерево выбора с папками), "2" (список выбора), "3" (список выбора с папками)
  И/ ИЛИ
  - key — "attrGroupCode" (форма выбора объекта);
  - value — uuid группы атрибутов, например, "302b563a-47b3-4b02-a50a-4154676b4edf")
  Для получения uuid группы атрибутов рекомендуется использовать скриптовый модуль, возвращающий uuid группы по ее названию.
  
  Текст модуля:
```
import ru.naumen.metainfo.shared.ClassFqn
def getAttrGroupCodeByTitle(ClassFqn fqn, String title)
{
return api.metainfo.getMetaClass(fqn).attributeGroups.find { it.title==title }?.code
}
```
  Вызов функции модуля:
  
  modules.<Код модуля>.getAttrGroupCodeByTitle(fqn, title)
  
  Параметры "fqn" и "title" необходимо определить перед вызовом модуля: "fqn" — код метакласса, в котором необходимо найти группу (строка), "title" — название группы атрибутов (строка);
- required — обязательность заполнения параметра отчета:
  - false (по умолчанию) или пусто — параметр не обязателен для заполнения;
  - true — параметр обязателен для заполнения и отмечен на форме звездочкой
Пример 1. Определение параметра "Объект":

api.parameters.getObject("object1", "Сотрудник", "employee", "employee\$54801", true)

Пример 2. Выбор объекта с помощью представления для редактирования:

api.parameters.getObject('object1', 'Сотрудник', 'employee', 'employee\$54801', ['presentationCode':'1'])

Пример 3. Выбор объекта с помощью формы выбора объекта:

api.parameters.getObject('object1', 'Сотрудник', 'employee', 'employee\$54801', ['attrGroupCode':'302b563a-47b3-4b02-a50a-4154676b4edf'])

Пример 4. Выбор объекта с помощью формы выбора объекта и представления для редактирования:

api.parameters.getObject('object1', 'Сотрудник', 'employee', 'employee\$54801', ['presentationCode':'0', 'attrGroupCode':'302b563a-47b3-4b02-a50a-4154676b4edf'])
api.parameters.getObjects(code, title, metaClass, required)

api.parameters.getObjects(code, title, metaClass, defaultValue, required)

api.parameters.getObjects(code, title, metaClass, defaultValue, key1: value1, ..., required)

Определение параметра типа "Набор объектов".

Параметры метода:
- code — код параметра;
- title — название параметра. Указанное название будет выводиться на форму добавления отчета и форму редактирования параметров отчета.
  
  Если название null, то параметр не выводится на форму, но будет доступен в отчете;
- metaClass — код метакласса, объекты которого можно будет выбрать в параметре;
- defaultValue — список значений по умолчанию для данного параметра, может быть null;
- [key1: value1, ...] — определяет возможность выбора объектов с помощью формы выбора объекта и /или представления для редактирования:
  
  ['presentationCode':'0'])
  - key — "presentationCode" (представление для редактирования);
  - value — "0" и "2" (дерево выбора), "1" (дерево выбора с папками), "3" (список выбора), "4" (список выбора с папками)
  И/ ИЛИ
  - key — "attrGroupCode" (форма выбора объекта);
  - value — uuid группы атрибутов, например, "302b563a-47b3-4b02-a50a-4154676b4edf")
  Для получения uuid группы атрибутов рекомендуется использовать скриптовый модуль, возвращающий uuid группы по ее названию, см. описание метода api.parameters.getObject
- required — обязательность заполнения параметра отчета:
  - false (по умолчанию) или пусто — параметр не обязателен для заполнения;
  - true — параметр обязателен для заполнения и отмечен на форме звездочкой
Пример 1:

api.parameters.getObjects("tekTeam", "Кем решен", "team", ["team\$1901"]), true]

Пример 2: Выбор объектов с помощью представления для редактирования:

api.parameters.getObjects('object1', 'Сотрудник', 'employee', ['employee\$54801'], ['presentationCode':'0'])

Пример 3: Выбор объектов с помощью формы выбора объекта:

api.parameters.getObjects('object1', 'Сотрудник', 'employee', ['employee\$54801'], ['attrGroupCode':'302b563a-47b3-4b02-a50a-4154676b4edf'])

Пример 4: Выбор объектов с помощью формы выбора объекта и представления для редактирования

api.parameters.getObjects('object1', 'Сотрудник', 'employee', ['employee\$54801'], ['presentationCode':'0', 'attrGroupCode':'302b563a-47b3-4b02-a50a-4154676b4edf'])
api.parameters.getCaseList(code, title, metaClass)

api.parameters.getCaseList(code, title, metaClass, defaultValue)

api.parameters.getCaseList(code, title, metaClass, defaultValue, required)

Определение параметра типа "Набор типов класса".

Параметры метода:
- code — код параметра
- title — название параметра, которое будет выводиться на форму добавления отчета и форму редактирования параметров отчета.
  
  Если название null, то параметр не выводится на форму, но будет доступен в отчете;
- metaClass — код метакласса, типы которого можно будет выбрать в параметре;
- defaultValue — список значений по умолчанию для данного параметра, может быть null;
- required — обязательность заполнения параметра отчета:
  - false (по умолчанию) — параметр не обязателен для заполнения;
  - true — параметр обязателен для заполнения и отмечен на форме звездочкой
Пример:

api.parameters.getCaseList('caseList', 'Набор типов класса', 'ou', 'ou$geneal', false)
api.parameters.getState(code, title, metaClass)

api.parameters.getState(code, title, metaClass, defaultValue)

Определение параметра типа "Статус".

Параметры метода:
- code — код параметра;
- title — название параметра, которое будет выводиться на форму добавления отчета и форму редактирования параметров отчета.
  
  Если название null, то параметр не выводится на форму, но будет доступен в отчете;
- metaClass — код метакласса, статусы которого можно будет выбрать в параметре;
- defaultValue — список значений по умолчанию для данного параметра, может быть null
api.parameters.getStates(code, title, metaClass)

api.parameters.getStates(code, title, metaClass, defaultValue)

Определение параметра типа "Набор статусов".

Параметры метода:
- code — код параметра;
- title — название параметра, которое будет выводится на форму добавления отчета и форму редактирования параметров отчета.
  
  Если название null, то параметр не выводится на форму, но будет доступен в отчете;
- metaClass — код метакласса, статусы которого можно будет выбрать в параметре;
- defaultValue — список значений по умолчанию для данного параметра, может быть null

Изменение заполненных параметров до построения отчета

getActualParameters(def parameters)

Изменение параметров, заполненных в getParameters до построения отчета.

В методе доступны переменные:
- parameters — карта всех параметров отчета после их заполнения пользователем, у которой ключ — код параметра, значение — значение, которое было заполнено при построении отчета.
- user — пользователь, под которым строится отчет. Если отчет строится суперпользователем, то = null.
- subject — объект на карточке которого строится отчет.
В случае если параметр не имел значения по умолчанию или не заполнялся на форме и является пустым, то заполнить его в скрипте не получится.

Заполнение отсутствующих в getParameters параметров не поддерживается

Возвращает изначальный parameters или новую карту.
```
def getParameters()
{
return [ api.parameters.getObjects('ous', 'Отделы', 'ou', ['ou$19901']) ]
}
def getActualParameters(def parameters)
{
parameters.ous += utils.findFirst('ou', [:])
return parameters
}
```

Фильтрация параметров отчета

.setFiltrationScript(...) — метод для фильтрации выпадающего списка элементов параметров отчета. Метод может задаваться для указанного параметра отчета.

Внутри метода помещается скрипт для фильтрации параметров. Также внутри скрипта возможно использовать механизм зависимости параметров друг от друга:

def ATTRS_FOR_UPDATE_ON_FORMS = ['t1'];
if (subject == null)
{
return ATTRS_FOR_UPDATE_ON_FORMS;
}

Примеры использования скрипта фильтрации для параметров отчета:

Copy

def getParameters() {
   return [ 
     api.parameters.getObject("t1", "Команда", "team")
       .setFiltrationScript({
          return ['team$3601'];
      }),

     api.parameters.getObjects("t2", "Отдел", "ou", ['ou$4202'], ['presentationCode':'4'])
        .setFiltrationScript({
          def ATTRS_FOR_UPDATE_ON_FORMS = ['t1']; 
          if (subject == null)
          { 
              return ATTRS_FOR_UPDATE_ON_FORMS; 
          }
          return ['ou$4201'];
      }),

     api.parameters.getObject("t3", "Отдел", "ou", 'ou$4202', ['presentationCode':'1'])
        .setFiltrationScript({
          def ATTRS_FOR_UPDATE_ON_FORMS = ['t1']; 
          if (subject == null)
          { 
              return ATTRS_FOR_UPDATE_ON_FORMS; 
          }
          return ['ou$4201'];
      }),

     api.parameters.getObjects("t4", "Команда", "team", ['team$3601'], ['presentationCode':'1'])
        .setFiltrationScript({
          return ['team$3601'];
      }),
     
     api.parameters.getCatalogItems('t5', 'Справочник', 'priority', ['priority$4501'])
             .setFiltrationScript({
          return ['priority$4501'];
      }),

     api.parameters.getCatalogItemByCode('t6', 'Справочник', 'priority', 'sss1')
             .setFiltrationScript({
          return ['priority$4501'];
      }),
     
     api.parameters.getCaseList('t7', 'Набор типов класса', 'ou', ['ou$ou2'])
        .setFiltrationScript({
          return ['ou$ou1'];
      }),
     
     api.parameters.getStates('t8', 'Статус', 'serviceCall', ['registered'])
        .setFiltrationScript({
          return ['registered'];
      }),

     api.parameters.getState('t9', 'Статус', 'serviceCall', 'registered')
        .setFiltrationScript({
          return ['registered'];
      }),
     
     api.parameters.getDate('t10', 'Дата', new Date()-2)
        .setFiltrationScript({
          if (!subject)
          {
             return [];
          }
          def filter = api.date.filter();
          return [(filter.after(new Date())) : 'Значением может быть только дата в будущем'];
      })
   ] as List;
}

Использование зависимости параметров друг от друга (контекстная переменная params):

Copy

def getParameters() {
   return [ 
     api.parameters.getObject("serviceParam", "Услуга", "slmService"),
     
     api.parameters.getObjects("t3", "Заявки", "serviceCall")
        .setFiltrationScript({
          def ATTRS_FOR_UPDATE_ON_FORMS = ['serviceParam']; 
          if (subject == null)
          { 
              return ATTRS_FOR_UPDATE_ON_FORMS; 
          }
          return utils.find('serviceCall',['service': params.serviceParam]);
      })
   ] as List;
}

Обработка построенного отчета

Вывод произвольных значений в отчет (печатную форму):
```
table.addValue('number1', 123456);
table.addValue('text1', 'iText');
```
table.clearData()

Очистка таблицы отчета для полной замены данных в отчете groovy-скриптом.
Настройка возможности отправлять копию отчета по почте при построении отчета в списке отчетов (скрипт добавляется в шаблон отчета):
```
def getSettings() {
return [ 'possibleToSend' : true ]
}
```

api.cti Интеграция с IP-телефонией

Общие методы для интеграции с IP-телефонией

Методы api.cti работают при подключеном модуле CTI.

api.cti.isListenMessages(login)

Проверяет, что сотрудник находится в командах, ответственных за телефонию, авторизован в системе и находится в интерфейсе оператора.

Параметр метода:
- login — логин оператора телефонии (сотрудника).
api.cti.open(login, url, mode)

Открытие URL в браузере оператора телефонии.

Параметры метода:
- login — логин оператора телефонии (сотрудника), в браузере которого будет открыта ссылка;
- url — URL карточки контрагента, формируется через api.web
  
  def url = api.web.getBaseUrl() + "#search:101";
- mode — режим открытия карточки контрагента: в текущем окне (вкладке) — "current", в новом — "new". Место, где открывается карточка: вкладка или окно, зависит от настройки браузера
Пример 1. Открытие карточки контрагента в новом окне (вкладке):

api.cti.open('user101', api.web.open('ou$1601'), 'new')

Пример 2. Открытие карточки контрагента на текущей вкладке (окне):

api.cti.open('user205', api.web.open('ou$401'), 'current')

Методы для интеграции с Asterisk

Методы api.cti работают при подключенном модуле CTI.

api.cti.makeCall(src, dst)

api.cti.makeCall(src, dst, 'context':'ext-group')

Обращается к серверу IP-телефонии и организует звонок от src к dst на сервере телефонии, добавляя звонок в очередь вызовов.

Параметры метода:
- src — номер звонящего абонента;
- dst — номер телефона, на который совершается вызов;
- 'context':'ext-group' — групповой номер телефона в контексте ext-group, на который совершается вызов.
Результат выполнения:
- Если звонок добавлен в очередь вызовов успешно, то метод ничего не возвращает и инициирует вызов. На сервер IP-телефонии передается номер телефона, в котором удалены все пробелы, дефисы и/или тире, открывающие и закрывающие скобки, все знаки + (кроме первого в номере). На сервере IP-телефонии инициируется звонок.
- Если сработал таймаут обращения к серверу или сервер ответил ошибкой IOException, IllegalArgumentException или IllegalStateException, то метод возвращает эту ошибку.
- Если сервер ответит какой-то другой ошибкой (например, если нет очереди, либо номер не числится в качестве абонента), то метод ничего не возвращает.
api.cti.reconnect()

Переподключение к серверу телефонии, например, для перезагрузки интеграции:
api.cdr.search(filter)

Получение информации о звонке с сервера IP-телефонии. Запись разговора хранится на сервере. Сервер телефонии предоставляет возможность получить доступ к файлу по ссылке.

Метод возвращает с сервера IP-телефонии информацию о звонках, которые удовлетворяют заданным критериям.

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

Параметры метода:
- filter — ассоциативный список критериев для поиска звонков.
  
  Доступные ключи:
  - id — идентификатор звонка на сервере телефонии;
  - src — номер звонящего абонента;
  - dst — номер телефона, на который звонящий совершал вызов;
  - connected — номер абонента, с которым звонящий вел разговор;
  - dateFrom — дата совершения звонка "C";
  - dateTo — дата совершения звонка "По"
  Форматы дат: yyyy.MM.dd HH:mm:ss, yyyy.MM.dd HH:mm, yyyy.MM.dd.
Пример.

api.cdr.search([dateFrom": "2014.01.29 06:00:00", "dateTo": "2014.01.30 06:00:00"])

Описание api методов для определении правил определения тревоги и правил вычисления параметров, см. Методы api. DAP.

Синхронизация

api.ndap.syncObject(object)

Синхронизация объектов мониторинга из SMP с системой мониторинга DAP.

Параметр:
- object — object или UUID объекта мониторинга, атрибуты контекста которого синхронизируются с DAP.
Метод обновляет поля объекта в DAP или создает объект, если его нет в DAP. Объектная модель в DAP соответствует объектной модели мониторинга в SMP.

Пример: Консольный скрипт синхронизации метрики
```
def a = utils.get('monitoringMetric$13101')
api.ndap.syncObject(a)
```
api.ndap.syncProperties(object)

Синхронизация только атрибутов контекста с системой мониторинга DAP.

Параметр:
- object — object или UUID объекта мониторинга, атрибуты контекста которого синхронизируются с DAP.
Результат выполнения: Атрибуты контекста объектов мониторинга в DAP соответствует атрибутам контекста объектов мониторинга в SMP.

Работа с сервером DAP

api.ndap.checkAvailable()

Выполняется проверка корректности параметров подключения к центральному серверу мониторинга DAP.

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

В случае отсутствия подключения возникает исключение .
api.ndap.isAvailable()

Проверка доступности центрального сервера мониторинга DAP (2).

Возвращает true — если подключение есть; false — если подключение отсутствует.

Работа с триггерами

api.ndap.getTriggerStatus(Object)

Проверка статуса тревоги триггера.

Параметр:
- object — object или UUID триггера, для которого выполняется проверка статуса.
Возвращает true — если тревога активна; false — если тревога НЕ активна.

Работа с метриками

api.ndap.metricLastValue(Object)

Получение последнего значения метрики.

Параметр:
- object — object или UUID метрики, для которой запрашивается последнее значение;
Возвращает ассоциативный массив вида {value=<Последнее значение метрики>, time=<Время получения последнего значения>} .

Пример 1: Вычисление значения атрибута "Время получения последнего значения" (класс "Метрика").

return new Date(api.ndap.metricLastValue(subject).time)

Пример 2: Вычисление значения атрибута "Последнее полученное значение" (класс "Метрика").
```
lastValue = api.ndap.metricLastValue(subject)
exception
if(exception != null)
{
return exception.message.split("Details: ")[1]
}
return lastValue.value
if(exception != null)
{
return exception.message.split("Details: ")[1]
}
return lastValue.value
```
api.ndap.metricLastValueCached(object)

api.ndap.metricLastValueCached(object, lifespan)

Получение последнего значения метрики, с использованием кэша.

Время жизни значения в кэше определяется автоматически: для активных метрик — время жизни равно значению атрибута pollPeriod; для пассивных метрик — время жизни равно 1 минуте

Параметры:
- object — object или UUID метрики, для которой запрашивается последнее значение;
- lifespan — Время жизни элемента в кэше в миллисекундах. Long .
Возвращает ассоциативный массив вида {value=<последнее значение метрики>, time=<время получения последнего значения>}.
api.ndap.metricHistory(object, data)

Получение истории метрики.

Параметр:
- object — object или UUID метрики, для которой запрашивается история;
- data — ассоциативный массив, ключами которого являются начало () и конец () периода, за который запрашивается история метрики.
Возвращает ассоциативный массив вида {fetchStart=<начало выборки(в секундах)>, fetchEnd=<конец выборки(в секундах)>, rowCount=<количество точек выборки>, data=[[<время, <значение>], [<время, <значение>], ..]} .

Работа с моделями

api.ndap.fitPredictiveModel(model, maxEval, initialGuess, steps)

Автоматический подбор коэффициентов для модели экспоненциального сглаживания с помощью алгоритма Нелдера-Мида.

Параметр:
- model — объект модели экспоненциального сглаживания или uuid объекта модели, для которой подбираем коэффициенты;
- maxEval — максимальное количество шагов алгоритма;
- initialGuess — начальные значения коэффициентов;
- steps — длина шага алгоритма, отвечает за скорость и точность алгоритма.
Метод ничего не возвращает, он сразу же обновляет коэффициенты у указанной модели.

Пример: .
```
def model = utils.get('predictiveModel$2702');
def maxEval = 1000;
def initialGuess = [ 0.5, 0.5, 0.5, 0.5 ] as double[];
def steps = [ 0.001, 0.001, 0.001, 0.001 ] as double[]
api.ndap.fitPredictiveModel(model, maxEval, initialGuess, steps)
```
api.ndap.fitPredictiveModel(model, maxEval, initialGuess, steps)

api.ndap.fitPredictiveModel(model, maxEval, initialGuess, steps, from, to)

Автоматический подбор коэффициентов для модели экспоненциального сглаживания с помощью алгоритма Нелдера-Мида.

Параметр:
- model — объект модели экспоненциального сглаживания или uuid объекта модели, для которой подбираем коэффициенты;
- maxEval — максимальное количество шагов алгоритма;
- initialGuess — начальные значения коэффициентов;
- steps — длина шага алгоритма, отвечает за скорость и точность алгоритма.
- from — начало периода выборки данных, указывается включительно
- to — конец периода выборки данных. Указывается включительно
Метод ничего не возвращает, он сразу же обновляет коэффициенты у указанной модели.

Пример 1: .
```
def model = utils.get('predictiveModel$2702');
def maxEval = 1000;
def initialGuess = [ 0.5, 0.5, 0.5, 0.5 ] as double[];
def steps = [ 0.001, 0.001, 0.001, 0.001 ] as double[]
api.ndap.fitPredictiveModel(model, maxEval, initialGuess, steps)
```
Пример 2: .
```
def model = utils.get('predictiveModel$2702');
def maxEval = 1000;
def initialGuess = [ 0.5, 0.5, 0.5, 0.5 ] as double[];
def steps = [ 0.001, 0.001, 0.001, 0.001 ] as double[];
def from = new Date() - 1;
def to = new Date();
api.ndap.fitPredictiveModel(model, maxEval, initialGuess, steps, from, to);
```

Работа с шиной

api.ndap.createRestEvent(customAttrs)

Создать объект REST события для отправки на общую шину в DAP.

Параметр:
- customAttrs — дополнительные атрибуты.
Возвращает объект REST события.
api.ndap.postEvent(event)

Отправить в DAP событие на общую шину.

Параметр:
- event — событие для отправки.