Внешние действия (уведомления, пуш, email, вызов API)

Что такое внешние действия

Вызов внешних действий - это возможность действия, выходящего за рамки возможности работы с БД через SQL. 

В некоторых процедурах можно вызвать такие внешние действия как отправка почты, СМС, очистка кеша, создание уведомления. Это можно использовать в следующих случаях:

1. В SaveItem при сохранении формы (SELECT 2)
2. В выполнении операции у таблицы (SELECT 2)
3. В периодических вызовах sync (SELECT 2-10)
4. После смены статуса сущностей в процедуре afterChangeStatus (SELECT 2).
5. В обновлении поля в Таблице (SELECT 2)
6. В выполнении Request JS запроса (SELECT 3)
7. После добавления комментария (SELECT 2)

Пример данного select2:

select 'email' type,   -- email, sms, notification, clearcache
   'x1' spCallback,  -- вызов некой хранимки после внешнего действия (с именем outer_x1) 
    'ru@rudensoft.ru' [to], 'sub1' subject, 'bodyXXX'+@itemIDs body,   ---EMAIL
    'Text 1' msg, '723429234' [number],           --- SMS
    '' prefix,    --CLEAR CACHE
    'text1' text , 'ru@rudensoft.ru' [to],
'ticketExecutor' typeCode, 'http///' url,
 'add111' additional  -- notifications

Использоваться будут только те параметры, которые актуальны для выбранного type (обязательный параметр для внешнего действия).

Необязательный параметр spCallback также есть для всех внешних действий и необходим для вызова некой хранимой процедуры outer_xxxx после выполнения внешнего действия (см. ниже описание)

Если необходимо сделать сразу несколько внешних действий - то можно прописать через Union (и в этом случае указать все параметры чтобы была возможность сделать union).

Примечание. Внешние действия могут возвращать результат на front end сторону (ВАЖНО! эти данные доступны пользователю в браузере!), где вы можете обработать их через JS и показать пользователю результат (поле data.additionalData в коллбеке сохранения формы).  

Если вызвано было несколько действий, то результаты передаются через конкатенацию с "||", например, aa||bbb||c.

Внимание! Параметры SELECT с внешним действием зависимы от регистра букв. Указывайте названия именно в том регистре, какой используется в документации или рабочих примерах. 

Описание параметров внешнего действия

Type -  типы команды (notification, clearcache, email, emailtemplate, sms, apirequest)

Уведомления на сайте

select 'notification' type, 'text1' text , 'demo1' [to], 'ticketExecutor' typeCode, 'http///' url, 'add111' additional

• additional - дополнительная информация к уведомлению
• text - текст уведомления
• to - кому уведомление
• typeCode - код типа уведомления (as_nt_notificationTypes)
• url - добавочный адрес к уведомлению

См. подробнее про работу с уведомлениями. 

Очистка кеша

select 'clearcache' type, '' prefix

Если префикс указан, то кеш будет чистить ключи только с заданным префиксом (по умолчанию это as_).

Отправка в телеграм

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

-- простая отправка
select 'telegram' type, 'username' [to], 'message text' [text]

-- отправка с кнопками
 select 'telegram' type, 'text1' text, 'admin' [to],  '@falconSpaceTest' channel, '{}' buttonsJSON, '' parseMode
   

• buttonsJSON - настройки кнопок (смотри документацию по Телеграм боту)
• parseMode - задает способ обработки сообщений перед выводом в телеграм (html, default, markdown, markdownv2. По умолчанию html). 
• text - сообщение
• to, channel - кому отправляем (если задан channel - то отправляем в канал. to - это username в системе, к которому привязан некий телеграм или сам логин телеграма).  

Также в to можно указать ранее привязанный telegram в tg_settings в формате '@telegramLogin' (поиск осуществляется через процедуру tg_getChatID). Таким образом можно отправлять незарегистрированным в системе пользователям уведомления по их логину в телеграм (но они должны изначально обратиться к боту для создания привязки в tg_settings).

Информация о чате телеграм

type = telegram.info

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

Данные сохраняются в JSON и передаются в параметре Msg (который можно обработать через коллбек внешнего действия spCallback либо на стороне JS (например, callback для сохранения формы в Javascript) в AdditionalData).

В случае использования spCallback все результаты выполнения этой команды приходят в @parameters ExtendedDictionaryParameter. в нем будут элементы: 

• msg - JSON объект с данными, полученными в результате команды.
• result - результат операции

Примеры: 

 select 'telegram.info' type, 'chatmemberscount' infotype, '273533547' chatID
 select 'telegram.info' type, 'chat' infotype, '273533547' chatID
 select 'telegram.info' type, 'chatadministrators' infotype, '273533547' chatID
 select 'telegram.info' type, 'me' infotype
 select 'telegram.info' type, 'chatmember' infotype, '273533547' chatID, '273533547' userID
 

Email

select 'email' type, 'ru@rudensoft.ru' [to], 'sub1' subject, 'body1' body

• to - кому отправляем сообщение
• subject - тема сообщения
• body - тело email
• from (необязательный) - от кого сообщение. Если не указан, то берется из Настроек сайта (код настройки mail.from)
• displayName  (необязательный) - отображаемое имя отправителя. Если не указан, то берется из Настроек сайта (код настройки mail.displayName)
• server (необязательный) - сервер отправки. Если не указан, то берется из Настроек сайта (код настройки mail.server)
• loginEmail (необязательный) - логин-почта. Если не указан, то берется из Настроек сайта (код настройки mail.loginEmail)
• password (необязательный) - пароль логина. Если не указан, то берется из Настроек сайта (код настройки mail.password)
• port (необязательный) - порт (25, 465). Если не указан, то берется из Настроек сайта (код настройки mail.port)
• ssl (необязательный) - Требуется ли SSL (true). Если не указан, то берется из Настроек сайта (код настройки mail.ssl)
• bcc (необязательный) - Скрытая копия. Если не указан, то берется из Настроек сайта (код настройки mail.bcc)
• cc (необязательный) - Копия. Если не указан, то берется из Настроек сайта (код настройки mail.cc).
• attach - можно указать пути к файлам через ||. Тогда они будут добавлены в письмо как вложение. Пример: /uploads/1.jpg||/uploads/2.jpg
• version - возможность использовать для отправки альтернативную библиотеку. Если указано mailkit - то используется библиотека MailKit (связано с использованием Implicit SSL / Explicit SSL для некоторых почтовых серверов). ВАЖНО. Настройки порта для MailKit отличаются (например, нельзя использовать 25 порт с SSL. Необходимо использовать 465). 

См. подробное про настройки Email

Отправка Email по шаблону

Шаблоны писем создаются в разделе /email-templates

   select 'emailtemplate' type, 'code1' code,
 'ru@rudensoft.ru' [to], 'hecrus@mail.ru' bcc,
'Некий параметр' name1, 'Наименование некоего товара' productName1

• code - это код шаблона уведомления
• to, cc, bcc - кому отправлять сообщения (можно указывать через запятую в них несколько адресов).
• Также можно передавать необязательные from, displayName, server, loginEmail, password, port, ssl, attach (пути к файлам вложения через запятую), version (если равно mailkit - то используется альтернативный способ отправки) - параметры по аналогии с type=email. 
• Любые параметры для замены в теле и теме письма, например name1. В теме и теле письма шаблона можно использовать псевдопараметры вида {name1}, которые будут заменяться соответствующим параметром из команды. 

Примечание: для корректной работы отправки, в системе должны быть таблицы as_mailing_templates, as_mailing_log

Отправка SMS (устаревший метод)

select 'sms' type, 'Text 1' msg, '723429234' [number]

• msg - текст SMS
• number - телефон получателя

Внимание! Используйте вместо type=sms отправку API (с подключением к какому-либо провайдеру SMS) запросов для отправки SMS.

Вызов запроса к внешнему API

select 'apirequest' type, 'code1' code, 'name1' p1_name, 'val1' p1_value,..........'name10' p10_name, 'val10' p10_value

• code - код запроса к внешнему API
• p1_name, p1_value - параметры, которые передаются в запрос (может быть до 10 параметров, все параметры необязательные).

ВАЖНО! Параметры во внешнее действие apirequest должны быть иметь тип Строка (приводите числа, булев тип и др к строке через cast). Пример:

select 'apirequest' type, 'checkContragent' code, 'clientID' p1_name, cast(@clientID as nvarchar(max)) p1_value

См. подробнее про запросы API. 

Прямой вызов API (без использования исходящего API)

select 'directAPI' type, @purl url, @pcontenttype contenttype, @pmethod method, 
    	@pheaders headers, @pformparams formparams, @pfiles files, @ppostbody body

Параметры: 

• body - если в POST запросе необходимо передавать JSON в виде всего тела запроса
• contenttype - в каком формате идут данные запроса (можно оставлять пустым).
• headers  - список HTTP заголовков (ключ=значение), разделенные символом \n (перевод строки)
• files - список файлов (имя=путь), разделенные символом \n (перевод строки)
• formparams - список параметров формы (ключ=значение), разделенные символом \n (перевод строки)
• method - get или post запрос
• url - адрес с https:// - куда обращаемся
• Генерация картинок

Генерация картинки через JSON generateImage 

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

Пример: 

   select 'generateImage' type, '
    {
        "options":{
		"path":"'+@url+'",
		"width":"735",
		"height":"354",
		"backColor":"#fff",
        },
        "render": [
			{
            	"type": "image",
				"path":"'+@backImg+'",
				"x":"0",
				"y":"0",
				"width":"735",
				"height":"354",
				"opacity":"1"
			},
            {
            	"type": "text",
				"text":"'+iif(@langID=1, 'Discount', 'Скидка')+' '+@pdiscount+'%",
				"x":"30",
				"y":"120",
				"width":"400",
				"height":"120",
				"color":"#fff",
				"backColor":"",
				"fontSize":"38",
				"fontFamily":"Verdana"
            },
            {
            	"type": "line",
				"x1":"20",
				"y1":"190",
				"x2":"380",
				"y2":"190",
				"thickness":"1",
				"color":"white"
			},
            {
            	"type": "text",
				"text":"'+iif(@langID=1, 'Coupon 124322', 'Купон 1234241')+'",
				"x":"120",
				"y":"200",
				"width":"400",
				"height":"120",
				"color":"#fff",
				"backColor":"",
				"fontSize":"18",
				"fontFamily":"Verdana"
            },
            {
            	"type": "text",
				"text":"'+iif(@langID=1, 'Active till ', 'Действует до ')+' '+@date+'",
				"x":"20",
				"y":"10",
				"width":"400",
				"height":"120",
				"color":"#fff",
				"backColor":"",
				"fontSize":"10",
				"fontFamily":"Verdana"
            },
            {
            	"type": "text",
				"text":"'+iif(@langID=1, 'John Smith Ltd', 'ИП Иванов И.И. ОГРН 12355152413123')+'",
				"x":"230",
				"y":"10",
				"width":"400",
				"height":"120",
				"color":"#000",
				"backColor":"",
				"fontSize":"10",
				"fontFamily":"Verdana"
            },
            {
            	"type": "text",
				"text":"'+@ptext+'",
				"x":"20",
				"y":"300",
				"width":"400",
				"height":"120",
				"color":"#fff",
				"backColor":"",
				"fontSize":"7",
				"fontFamily":"Verdana"
            }

        ]
    }
    ' options

раздел options задает общие настройки картинки.

раздел render задает последовательность вывода элементов на картинке. Поле type задает формат вывода элемента: 

type=text - вывод элемента Текст,  параметры: 

• text - текст, который требуется написать
• x, y - координаты расположения блока
• width, height - ширина и высота блока
• color, backColor - цвет текста и цвет фона
• fontSize, fontFamily - установка шрифта
• alignment - горизонтальное выравнивание Near, Center, Far (регистр букв важен).

type=image - вывод картинки. У него следующие параметры: 

• x, y - координаты расположения блока
• width, height - ширина и высота блока
• path - путь к картинке
• opacity - прозрачность (float от 0 до 1)

type=line- это Линия, параметры: 

• x1, y1, x2, y2 - координаты точек начала и конца отрезка
• thickness - толщина линии
• color - цвет линии

type=barcode  - добавляет картинку штрихкода. Параметры: 

• width, height - ширина и высота изображения в пикселях.
• x, y - координаты расположения блока
• path - путь к файлу сохранения 
• font - задает шрифт для вывода штрихкода
• fontSize - высота штрихкода

ВАЖНО: должен быть установлен (открыть файл ttf и кнопка Установить) шрифт font39 на сервере или другой аналогичный шрифт для вывода штрихкодов.  Шрифт есть в папке /content/fonts. После установки шрифта нужно перезагрузить IIS на сервере.

Пример: 

select 'generateImage' type, '
    {
        "options":{
		"path":"/uploads/_1.jpg",
		"width":"735",
		"height":"354",
		"backColor":"#fff",
        },
        "render": [
			{
            	"type": "barcode",
				"value": "13244241",
                "x":"0",
				"y":"0",
				"width":"300",
				"height":"254"
			}
        ]
    }
    ' options

Обработка картинок (processimage)

Вы можете выполнить трансформацию картинок (изменить размеры, качество и т.д.)

Для этого необходимо выполнить следующее действие: 

 select 'processimage' type, '/uploads/viki.png' path, '/uploads/x-viki.png' url,
       300 width, 300 height, 50 quality, '1' fitWithWhitespace, '' watermarkUrl
 union
 select 'processimage' type, '/uploads/viki2.png' path, '/uploads/x-viki2.png' url,
       100 width, 100 height, 50 quality, '1' fitWithWhitespace, '' watermarkUrl

Таким образом можно сделать пакетную обработку множества картинок. 

Параметры processimage

• fitWithWhitespace - если 1, то картинка будет дополняться пробелами с боков. Если не 1 - то трансформироваться по высоте и ширине.
• height - ширина в пикселях выходной картинки.
• path - путь к исходной картинке.
• quality - качество от 10 до 100. 
• url - путь к новой сохраненной картинке.
• watermarkUrl - путь к картинке водяному знаку, который накладывается на исходную картинку.
• width - ширина в пикселях выходной картинки.

Важно: path и url должны быть различными!

Запуск автоматизированных тестов (frontchecker)

Автоматизированный тест позволяет выполнить некий сценарий действий в Chrome и записать результаты выполнения этих операций для проверки работы корректности страниц. 

Вы можете запустить тесты, указав в actions коды тестов через запятую. Сами тесты создаются в разделе /frontchecker (пока доступно только в Core версии платформы). 

 select 'frontchecker' type, 'action1,action2' actions

Генерация документов (generatedoc)

Вы можете передать некие параметры на вход механизму генерации документов (as-doc) и получить ссылку на результирующий документ.

select 'generatedoc' type, 'stageAct' code, '2459' itemID, '{
    	"date" : "11.11.11",
    	"num": "4444"
    }' parameters

• code - это код генератора документа (управляется в разделе /docTemplates)
• itemID - ID некоторой сущности (для которой производится генерация документа).
• parameters - это параметры в виде JSON объекта, которые будут переданы в процедуру getData в виде параметра ExtendedDictionaryParameter @parameters (используются Key, Value2).

Полученный результат от внешнего действия можно использовать либо в коллбеке {code}_saveItem формы, либо через дополнительную обработку outer_ действий (последовательное выполнение нескольких внешних действий, например, для отправки на почту).

Пример коллбека формы: 

$(function(){
  as.form.callbacks["generateAct_saveItem"] = function(data){
      var url = data.additionalData;
    if(url){
      as.sys.bootstrapAlert("Ваш файл", {type:"success", delay:0});
    }
  }
});

Сжатие и распаковка zip архива (zip и extractZip)

Вы можете сжать некую папку на сервере в zip архив следующей командой:

select 'zip' type, '/uploads/dir1' directory, '/uploads/zipFile.zip' zipFile

Для распаковки архива используйте следующую команду:

select 'extractZip' type, '/uploads/zipFile.zip' zipFile,'/uploads/dir1' outputDirectory, 1 overwrite

Скачивание файла по сети (download)

Скачиваем некие файлы с удаленного источника и размещаем в папку:

select 'download' type, '/uploads/dir1' path, 'https://site.ru/uploads/zipFile.zip' url, 4 maxFileSizeMb, '' filename

• filename - если указан, то будет файл сохранен с этим именем (например, "1.txt"),
• headers - дополнительные HTTP заголовки, которые передаются с запросом (например, для авторизации). Формат передачи key||value,key||value,key||value,key||value
• maxFileSizeMb - максимальный размер файла,
• path - локальный путь к папке, куда сохраняем результат,
• url - откуда скачиваем файл в сети,

Пример с headers: 

select 'download' type, '/uploads/dir2' path, 
   'https://falconspace.ru/uploads/falcon-logo.png' url, 
    4 maxFileSizeMb, 'ss||11,ddd||22' headers

В выходном Msg будет ссылка на скачанный файл. 

Скачать и распарсить страницу HTML (downloadPage)

Скачиваем некоторый файл по URL и извлекаем из него некоторые теги через XPath:

select 'downloadPage' type, 'https://yandex.ru' url, '//title,//h1' commaxpath

На входе: 

• commaxpath - через запятую правила xpath для извлечения тегов. В выходной ExtendedDictionaryParameter @parameters записываются Key = xpath, Value2 - извлеченное значение тега (их может быть несколько с одинаковым Key).
• url - что скачиваем в сети.  

 На выходе: 

• content - строка с полным содержанием страницы
• result, msg - стандартный результат операции.
• пары Key, Value2 в @parameters - с Xpath и соответствующим значением тега в странице. 

Через spCallback вы сможете обработать эти извлеченные значения: 

Create or ALTER PROCEDURE [dbo].[outer_relmapProcessPage]
	@parameters ExtendedDictionaryParameter readonly,
	@data nvarchar(128) = '',
	@username nvarchar(128) = ''
AS
BEGIN
	declare @s nvarchar(max) = (select Value2 from @parameters where lower([Key]) = 'content')

        declare @title nvarchar(max) = (select top 1 value2 from @parameters where [key]='//title')
	
	-- SELECT 1 ReesultModel
	select 1 Result, '' Msg	
END

HTML to DOCX (html2docx)

Из HTML строки создаем Word файл. 

select 'html2docx' type, 'some html' html, '/uploads/g1.docx' filename

На входе: 

• filename- путь к файлу docx
• html - некая строка с HTML.  

На выходе: 

• result, msg - стандартный результат операции.

Отправка запросов в браузер (sendToBrowser)

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

Формат команды: 

select 'sendToBrowser' type, 'admin' username, 
       '' falconGuid,
       '' url,
       'action1' code,
    	'{
        	"s":1,
                "redirectUrl" : "",
                // любые другие данные...
        	"alert": {
         	   "text": "Текст сообщения",
                   "type": "warning",
                   "delay": 2000,
                   "hidePrev": true,
                   "title": "Заголовок"
         	},
                "audio": "/uploads/mp3/call.mp3",
                "updates": [
            	     {"control": "table", "code":"code1", "itemID": "123", "pk":"12345", "col": "col1", "value": "value1"},
                     {"control": "form", "code":"code1", "itemID": "123", "col": "col1", "value": "value1"}
                ],
                "refreshContainer": ".class1",
                "setContainerContent": { "selector": ".class1", "value": "value1", "delay": 1000 }
         }' data

Параметры:

• code - задает код отправки, он используется для создания коллбека вида as.signalr_[code], который будет вызываться при получении данных (дальше эти данные можно обработать в JS и выдать в нужном виде пользователю).
• data - данные в JSON, которые передаются на клиентскую сторону. Может иметь любой формат. Если содержит структуру alert, то при получении данных на клиенте будет выводиться окошко с заданными настройками.
• falconGuid - список Guid подключенных пользователей, которым надо разослать эти данные в браузер (используется если username пустой)
• url - url страниц на которые надо отправить эти данные (работает как фильтр для username и falconGuid. Также можно отправить всем пользователям на указанную страницу, указав пустые username и falconGuid).
• username - это список логинов пользователей username через запятую, которым будут отправлены данные.

Параметр audio (путь к файлу mp3) - если указан путь к файлу, то он будет единоразово проигран в браузере получателя. 

Параметры для alert: 

• delay - задержка сколько будет показываться окно в мс (если 0, то будет висеть постоянно)
• hidePrev - если true, то уберет все предыдущие сообщения 
• text - текст сообщения
• title - заголовок окна
• type - вид окна (primary, success, warning, danger, info и т.д.)

Массив updates позволяет обновить в режиме реального времени поле таблицы или формы. Указываем тип компонента (control), код компонента (code), itemID (привязка к сущности - параметр компонента data-itemID), какая колонка (col) и какое значение необходимо установить. Для таблиц также передается pk - первичный ключ таблицы (параметр id). 

Раздел setContainerContent - позволяет установить через delay мс нужную разметку(value) в некотором контейнере с селектором selector. 

Если передан refreshContaner, то на клиенте будет обновлена область с указанным jquery селектором в refreshContainer. 

redirectUrl - если задан, то пользователь, которому пришло это сообщение, будет переведен на указанный адрес. 

Раздел pushOptions задает настройки push уведомления пользователю: 

• actions  - массив действий (с полями action, title). Отображаются внизу push уведомления как ссылки.  
• body - текст
• id - id, который передается в data в push уведомлении
• icon - ссылка на иконку
• image - ссыка на картинку
• tag - некая строка, которая позволяет сделать так, чтобы выводилось одно пуш уведомление (а не много дублей) при нескольких открытых вкладках (например, идентификатор уведомления). 
• title - заголовок push уведомления
• vibrate - если true, то будет вибрация мобильного устройства при пуш уведомлении. 

Раздел printlog выводит общий поток подобных данных в контейнере слева внизу на странице: 

• text  - текст
• title - заголовок
• type - тип (warning, info, danger, success,primary).

Коллбек опционально может быть подключен на странице. Пример коллбека: 

$(function(){
	as.signalr_action1 = function(data){
    	console.log("Полученные с сервера данные", data);
    }
});

Если коллбек найден, то он будет выполнен. Ему на вход передается объект JSON data, который мы передали из внешнего действия. 

Команда для Google Drive (gd)

Команда может иметь различные действия (задаются в поле action), выполняемые в отношении объектов на Google Drive

Подробнее про интеграцию с Google Drive и варианты команд action.

Команда для работы с FTP клиентом (ftp)

Команда может иметь различные действия (задаются в поле action) с FTP протоколом - загружать файлы на FTP хранилище, скачивать, удалять и т.д.

Подробнее про передачу файлов по FTP.

Генерация PDF файла (generatepdf)

Вы можете задать некие правила в виде JSON и исходя из них будет формироваться файл PDF.

Формат команды: 

• options - JSON настроек файла
• url - адрес выходного файла PDF. 

Пример настроек: 

declare @url nvarchar(128) = '/uploads/pdf/'+convert(nvarchar(50), newid())+'.pdf'


	-- SELECT 1 (Result, Msg, SuccessUrl, HideFormAfterSubmit, RefreshContainer)
	select 1 Result, 'OK  Download PDF' Msg, '' SuccessUrl, 1 HideFormAfterSubmit, '' RefreshContainer


	--select 1 Result, 'Сохранено'
    declare @options  nvarchar(max) = N'
    {
    "options": {
        "title": "Test Document"
    },
    "pages": [
        {
            "elements": [
                {
                    "type": "text",
                    "value": "'+isnull(@pname, 'No name')+N'",
                    "alignment": "center",
                    "marginTop": "6cm",
                    "marginBottom": "0",
                    "marginLeft": "0",
                    "marginRight": "0",
                    "paddingTop": "0cm",
                    "paddingBottom": "0",
                    "paddingLeft": "0",
                    "paddingRight": "0",
                    "firstLineIndent": "0cm", //красная строка для абзацев
                    "color": "#000000",
                    "backgroundColor": "#FFFFFF",
                    "font": {
                        "size": 30,
                        "bold": false,
                        "italic": false
                    }
                },
                {
                    "type": "text",
                    "value": "PDF Generator test",
                    "alignment": "center",
                    "font": {
                        "size": 16,
                        "italic": true
                    }
                }
            ]
        },
        {
            "elements": [
                {
                    "type": "image",
                    "path": "/uploads/land/finance.jpg",
                    "width": "10cm", //соотношение сторон сохраняется, можно указывать либо ширину, либо высоту
                    "height": "10cm",
                    "alignment": "left",
                    //"wrapStyle": "through" //при значении through картинка становится фоном для последующих элементов. По идее здесь же настраиваниется обтекание текста вокруг картинки, пока это не работает
                },
                {
                    "type": "text",
                    "value": "Text below the image",
                    "alignment": "left",
                    "font": {
                        "size": 14,
                        "italic": true
                    }
                },
                {
                    "type": "line",
                    "color": "#333399",
                    "thickness": "0.1cm"
                },
                {
                    "type": "text",
                    "value": "This is a line test",
                    "alignment": "right",
                    "font": {
                        "size": 12,
                        "bold": true
                    }
                }
            ]
        },
        {
            "elements": [
                {
                    "type": "table",
                    "border": {
                        "width": "0.02cm",
                        "color": "#000000"
                    },
                    "columnWidths": ["4cm", "4cm", "2cm"],
                    "headers": ["Column ", "Column 2", "Column 3"],
                    "values": [
                        ["value 1_1", "value 1_2", "value 1_3"],
                        ["value 2_1", "value 2_2", "value 2_3"],
                        ["value 3_1", "value 3_2", "value 3_3"],
                        ["result", "", ""]
                    ],
                    "styleOptions": [
                        {
                            "position": [4, 0], //координаты ячейки, которую правим. [X, Y] - где X - строка, Y - столбец, начиная с нуля, строка 0 - шапка
                            "alignment": "right",
                            "font": { "bold": true, "italic": false, "family": "Arial", "size": 12 },
                            "mergeRight": 2, //объединить n ячеек справа с этой
                            "mergeDown": 0 //объединить n ячеек ниже с этой
                        }
                    ]
                },
                {
                    "type": "text",
                    "value": "This is a table",
                    "color": "#ff3333",
                    "backgroundColor": "#ddddff",
                    "paddingBottom": "0.2cm",
                    "marginTop": "0.1cm"
                },
                {
                    "type": "text",
                    "value": "Some lists:",
                    "marginTop": "1cm"
                },
                {
                    "type": "list",
                    "listStyle": "ul",
                    "items": [
                        "item1",
                        "item2",
                        "item3"
                    ]
                },
                {
                    "type": "list",
                    "listStyle": "ol",
                    "items": [
                        "item1",
                        "item2",
                        "item3"
                    ]
                },
                {
                    "type": "list",
                    "listStyle": "ol2",
                    "items": [
                        "item1",
                        "item2",
                        "item3"
                    ]
                },
                {
                    "type": "list",
                    "listStyle": "ol3",
                    "items": [
                        "item1",
                        "item2",
                        "item3"
                    ]
                },
                {
                    "type": "text",
                    "value": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
                    "marginBottom": "0.5cm",
                    "firstLineIndent": "1.5cm"
                },
                {
                    "type": "text",
                    "value": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
                    "marginBottom": "0.5cm",
                    "firstLineIndent": "1.5cm"
                },
                {
                    "type": "text",
                    "value": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
                    "marginBottom": "0.5cm",
                    "firstLineIndent": "1.5cm"
                }
            ]
        }
    ]
}
'

    select 'generatepdf' type,
    	@url url,
        @options options
    

Мы последовательно указываем страницы документа и элементы на этих страницах, это может быть текст, картинка, таблица, списки, линии.

ВАЖНО: при вставке параметров в JSON обязательно строку помечайте как N'' (иначе будет не юникод и не будет корректно обрабатываться JSON объект). 

Скачивание файлов

Скачивает файлы на сервер из внешнего источника

select 'download' type, 'https://site.ru/uploads/importXML/rss.zip' url, '/uploads' path
union
select 'download' type, 'https://site.ru' url, '/uploads' path 

• path - локальный путь к папке, куда сохранить файл (без конечного слеша)
• url - внешний ресурс, который необходимо скачать

Получить список онлайн пользователей (user.onlineusers)

Возвращает Result и Msg (через запятую имена онлайн пользователей)

select 'user.onlineusers' type

Массовая загрузка файлов через zip архив в систему ресурсов (processimagezip)

Возвращает Result, Msg, Count (количество созданных файлов в системе ресурсов). 

Подробнее про массову загрузку файлов из zip архива

Удаление ресурсов менеджера ресуров  (deleteresources)

Удаляет записи и сами файлы в системе ресурсов. 

Входные параметры 

• typeCode - код менеджера ресурса,
• itemID - itemID сущности, к которой привязаны ресурсы,
• resourceID - id удаляемого ресурса (если 0 - то удалятся все ресурсы, связанные с параметром itemID),
• withCallback - вызывать коллбек или нет (bit) после удаления,
• user - под каким пользователем выполнять процедуру (если NULL, то под текущим пользователем).

Возвращает Result, Msg.

Работа с файлами (file.command1)

Работа с папками и файлами доступна только в пределах папки /uploads (и ее подпапок). 

Все методы (за исключением getFolder) возвращают стандартный ResultModel (Result, Msg).

Сохранение файла на диске file.savefile

select 'file.savefile' type, '/uploads/111/22.txt' path,
   'Привет!'+char(10)+ '2222' content, 'windows-1251' encoding 

• content - содержимое файла
• encoding - кодировка файла (по умолчанию UTF8)
• path - путь к папке

Получить файл file.getfile

select 'file.getfile' type, '/uploads/111/22.txt' path,  'windows-1251' encoding

• encoding - кодировка файла
• path - путь к файлу 

Переместить файл/папку file.move

select 'file.move' type, '/uploads/111/22.txt' path, '/uploads/33.txt' destinationPath
select 'file.move' type, '/uploads/111' path, '/uploads/land/22' destinationPath

• destinationPath - путь к объекту назначения (для папок - это папка, куда будет переноситься содержимое исходной папки).
• path - путь к исходному файлу или папке

Копировать файл/папку file.copy

select 'file.copy' type, '/uploads/111/22.txt' path, '/uploads/33.txt' destinationPath
select 'file.copy' type, '/uploads/111' path, '/uploads/land/22' destinationPath

• destinationPath - путь к объекту назначения (для папок - это папка, куда будет переноситься содержимое исходной папки).
• path - путь к исходному файлу или папке

Проверка существования файла file.exists

select 'file.exists' type, '/uploads/111/22.txt' path

• path - путь к файлу

Получить размер файла/папки file.getsize

select 'file.getsize' type, '/uploads/111/22.txt' path
select 'file.getsize' type, '/uploads/111' path

• path - путь к исходному файлу или папке

На выходе в Msg будет длина файла в байтах.

Удаление файла file.deleteFile

select 'file.deleteFile' type, '/uploads/111/22.txt' path

• path - путь к удаляемому файлу

Получить содержимое папки file.getfolder

select 'file.getFolder' type, '/uploads' path

• path - задает путь к папке

В результате в items будут записаны отдельно объекты с key=file (title- название файла, value2 - URL файла, value - расширение файла) и key=folder (title - название папки, value2 - URL папки, value - количество вложенных элементов).

Создание папки file.createFolder

select 'file.createFolder' type, '/uploads/111/22' path

• path - путь к папке

Удаление папки file.deleteFolder

select 'file.deleteFolder' type, '/uploads/111/22' path

• path - путь к удаляемой папке

Скачать zip папки file.downloadFolder

select 'file.downloadFolder' type, '/uploads/111/22' path

• path - путь к папке

Zip создается в папке /uploads/tmp (необходимо периодически чистить эту папку через fushFolder и периодические действия). 

Очистить содержимое папки file.flushFolder

select 'file.flushFolder' type, '/uploads/111/22' path

• path - путь папки, которую следует очистить

Сохранение файла из строки в формате base64 savebase64

select 'savebase64' type, '/uploads/xx/1.jpg' path, 'XXXXXXXXXXXXXXXX' value 

• path - путь сохраняемого файла (если папки не существовало, то она будет создана). Обязательно начинается с /uploads
• value - файл в формате base64 - для создания строки base64 можно использовать сервис https://elmah.io/tools/base64-image-encoder/

Информация по диску сервера (diskinfo)

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

select 'diskinfo' type, 'C:\\' disk

• disk- какой диск нас интересует (если пустое, то берется первый диск на сервере)

На выходе 3 поля в структуре: 

• AvailableFreeSpace - сколько есть места на диске, доступного для текущего пользователя,
• TotalFreeSpace - сколько физически есть свободного места на диске,
• TotalSize - размер диска в байтах.

Экспорт-импорт через Excel (io.command1)

Делаем выгрузку в Excel либо загружаем некий файл на обработку в БД.  В основе работы данных внешних действий - компонент выгрузки в Excel.

Экспорт файла в Excel 

select 'io.export' type, 'code1' code,  '123' itemID, '0' isEmpty, 1 page, 500 pageSize

• code - код компонента выгрузки в Excel
• isEmpty - ставим '1' если нам нужен просто файл-шаблон для выгрузки, а не файл с данными.
• itemID - id сущности для которой делается выгрузка Excel. 
• page - номер страницы выгрузки (чтобы не выгружать очень большой объем данных в файл)
• pageSize - размер страницы выгрузки (сколько данных будет выгружено для выбранной страницы page). 

В выходной модели будет поле с key=url - содержать URL сформированного файла. 

Импорт файла из Excel в БД

select 'io.import' type, 'code1' code,  '123' itemID, '/uploads/file.xlsx' url

• code - код компонента выгрузки в Excel
• itemID - id сущности для которой делается выгрузка Excel. 
• url - файл Excel в локальной папке сайта для подгрузки данных 

В выходной модели будут данные лога выгрузки, результат операции.

Обработка данных из Excel файла с произвольным форматом

 select 'io.parseExcel' type, '/uploads/1.xlsx' path, 
    	'' listName, 'parseExcel1' spCallback

• path  - путь к файлу Excel 
• listName - название листа (если пустая строка, то берется первый лист) 

В выходной модели в @parameters будут данные: 

• Title - тип данных ячейки,
• Key - номер строки ячейки,
• Value - номер колонки ячейки,
• Value2 -  значений ячейки.

См. статью про обработку Excel произвольного формата

Вызов дополнительной хранимой процедуры после выполнения внешнего действия 

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

 select 'telegram' type, 'text1asd' text, '@hecrus' [to],
    	'{}' buttonsJSON,
         'test' spCallback

Затем мы должны реализовать процедуру outer_{spCallback}. 

ALTER PROCEDURE [dbo].[outer_test]
	@parameters ExtendedDictionaryParameter readonly,
	@data nvarchar(128) = '',
	@username nvarchar(128) = ''
AS
BEGIN
	-- SELECT 1 ReesultModel
	select 1 Result, '123' Msg


	exec as_print @str = '123321'

	-- SELECT 2 Outer actions
	 select 'telegram' type, 'text12222' text, '@hecrus' [to],
    	'{}' buttonsJSON
END

На входе: 

• data - результат выполнения вызывающего внешнего действия в виде строки (msg). Необязательный параметр (в целом все необходимые данные передаются в @parameters). 
• parameters - коллекция Key, Value2, это параметры  инициирующего внешнего действия (то, что мы передавали в SELECT внешнего действия). Также сюда передаются данные из выполненного внешнего действия (классические result, msg и возможно дополнительные данные по результату выполнения внешнего действия). Также здесь передается langID. 
• username - текущий пользователь

На выходе: 

• SELECT 1 - Msg и Result (Msg передается как выходной параметр внешнего действия-инициатора). 
• SELECT 2 - вызов других внешних действий (таким образом можно делать целые цепочки внешних вызовов). 

Примечание:

• spCallback лучше именовать как продолжение вызывающей ее процедуры, так будет проще видеть цепочку команд. Например, для fm_stageInfo_getItem это может быть fm_stageInfo_getItem_saveFileID - в этом случае процедура  будет выглядеть так outer_fm_stageInfo_getItem_saveFileID.
• Таким образом можно строить бесконечные цепочки внешних действий (например вызовы API): вызвали внешнее действие с sp коллбеком - внутри него тоже внешнее действие со своим коллбеком и т.д.

Обработка результатов внешнего действия на frontend

Обновление Янв2025. Простой способ обработать результат внешнего действия на странице без JS - использовать actions. См раздел Обработка результата внешнего действия через actions 

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

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

Данные по внешнему действию приходят в поле additionalData - в нем находится серилизованный массив объектов ResultModel в виде JSON строки. 

У каждого из результатов внешнего действия может быть дополнительный вызов другого внешнего действия (если указан был spCallback) - в этом случае у него также будет по аналогии заполнен additinalData данными по результатам соответствующего внешнего действия. 

Основные поля каждого результата (OuterResultModel).

• additionalData - результат выполнения дополнительных внешних действий в виде строки JSON (массив OuterResultModel). 
• items - все выходные данные от результата работы внешнего действия (у каждого типа могут быть свои данные)
• msg - строка результата (сообщение или данные по результатам)
• result - если true, то операция выполнена успешно.

$(function(){

as.formcallbacks.createpdf_saveItem = function(data){
  console.log("_saveItem",data)
  var outerData = JSON.parse(data.additionalData);
  if(!outerData || outerData.length==0) return;
  console.log("outerData", outerData)
  var ss1 = JSON.parse(outerData[0].additionalData);
  console.log("ss1", ss1)
  var ss2 = JSON.parse(ss1[0].additionalData);
  console.log("ss2", ss2)
  if(ss2) url = ss2[0].msg;
  console.log("url", url)
  if(url) location.href= url;

}

});

 Вот так может выглядеть additionalData: 

additionalData: "[
	{"items":[
		{"key":"result","value":null,"title":null,"value2":"True"},
		{"key":"msg","value":null,"title":null,"value2":""},
		{"key":"url","value":null,"title":null,"value2":"/uploads/doc/buydeal/договор на закупку_4e76.docx"},
		{"key":"spCallbackResult","value":"True","title":"","value2":null}],
	"result":true,"msg":"/uploads/doc/buydeal/договор на закупку_4e76.docx",
	"additionalData":"
	[
			{\"items\":
				[
				{\"key\":\"result\",\"value\":null,\"title\":null,\"value2\":\"True\"},
				{\"key\":\"msg\",\"value\":null,\"title\":null,\"value2\":null},
				{\"key\":\"fileId\",\"value\":null,\"title\":null,\"value2\":\"111\"},
				{\"key\":\"spCallbackResult\",\"value\":\"True\",\"title\":\"\",\"value2\":null}
             ],
			\"result\":true,
			\"msg\":null,
			\"additionalData\":\"
			[
					{\\\"items\\\":
[{\\\"key\\\":\\\"result\\\",\\\"value\\\":null,\\\"title\\\":null,\\\"value2\\\":\\\"True\\\"},
{\\\"key\\\":\\\"msg\\\",\\\"value\\\":null,\\\"title\\\":null,\\\"value2\\\":\\\"/uploads/111.pdf\\\"},
{\\\"key\\\":\\\"exportPath\\\",\\\"value\\\":null,\\\"title\\\":null,\\\"value2\\\":\\\"/uploads/111.pdf\\\"}],
					\\\"result\\\":true,
					\\\"msg\\\":\\\"/uploads/111.pdf\\\",
					\\\"additionalData\\\":null,
					\\\"icon\\\":null}
			]\",
			\"icon\":null}
	]",
	"icon":null}]"