Внешние действия (уведомления, пуш, 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
    '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.

Если необходимо сделать сразу несколько внешних действий - то можно прописать через 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
  • text - текст уведомления
  • to - кому уведомление
  • typeCode - код типа уведомления (as_nt_notificationTypes)
  • url - добавочный адрес к уведомлению
  • additional - дополнительная информация к уведомлению

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

Очистка кеша

select 'clearcache' type, '' prefix

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

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

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

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

-- отправка с кнопками
 select 'telegram' type, 'text1' text, 'admin' [to],  '@falconSpaceTest' channel, '{}' buttonsJSON, '' parseMode
   
  • to, channel - кому отправляем (если задан channel - то отправляем в канал. to - это username в системе, к которому привязан некий телеграм или сам логин телеграма).  
  • text - сообщение
  • buttonsJSON - настройки кнопок (см документацию по Телеграм боту)
  • parseMode - задает способ обработки сообщений перед выводом в телеграм (html, default, markdown, markdownv2. По умолчанию html). 

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

Подробнее о настройке Telegram бота.

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

type = telegram.info

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

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

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

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

Примеры: 

 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 параметров , все параметры необязательные).

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

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

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

Параметры: 

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

Генерация картинок

Вы можете через указание настроек сгенерировать графический файл. В файле вы можете писать некий текст, размещать блоки, линии и добавлять картинки.  Все настройки генерации указываются через 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 - установка шрифта

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

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

Важно: 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

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

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

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

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

На входе: 

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

На выходе: 

  • result, msg - стандартный результат операции.
  • content - строка с полным содержанием страницы
  • пары 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

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

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

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

select 'sendToBrowser' type, 'admin' username, 
       '' falconGuid,
       '' url,
       'action1' code,
    	'{
        	"s":1,
                // любые другие данные...
        	"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

Параметры:

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

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

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

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

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

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

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

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

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

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

  • title - заголовок
  • text  - текст
  • 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 
  • url - внешний ресурс, который необходимо скачать
  • path - локальный путь к папке, куда сохранить файл (без конечного слеша)

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

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

select 'user.onlineusers' type

Работа с файлами (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 

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

content - содержимое файла

encoding - кодировка файла (по умолчанию UTF8)

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

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

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

encoding - кодировка файла

Переместить файл/папку 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

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

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

Удаление папки 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 - путь к удаляемой папке

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

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

path - путь сохраняемого файла (если папки не существовало, то она будет создана). Обязательно начинается с /uploads

value - файл в формате base64 (для создания строки base64 можно использовать сервис https://elmah.io/tools/base64-image-encoder/)

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

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

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

select 'io.export' type, 'code1' code,  '123' itemID, '0' isEmpty, 1 page, 500 pageSize
  • code - код компонента выгрузки в Excel
  • itemID - id сущности для которой делается выгрузка Excel. 
  • isEmpty - ставим '1' если нам нужен просто файл-шаблон для выгрузки, а не файл с данными.
  • 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 в локальной папке сайта для подгрузки данных 

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

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

Если нам необходимо обработать результат выполнения внешнего действия, то мы должны передать парамер 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

На входе: 

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

На выходе: 

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

Примечание: spCallback лучше именовать как продолжение вызывающей ее процедуры, так будет проще видеть цепочку команд. Например, для fm_stageInfo_getItem это может быть fm_stageInfo_getItem_saveFileID

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

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

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

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

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

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

  • result - если true, то операция выполнена успешно.
  • msg - строка результата (сообщение или данные по результатам)
  • items - все выходные данные от результата работы внешнего действия (у каждого типа могут быть свои данные)
  • additionalData - результат выполнения доп внешних действий в виде строки JSON (массив OuterResultModel). 
$(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}]"

 

 

Falcon Space - функциальная веб-платформа разработки на узком стеке MS SQL/Bootstrap. Вводная по Falcon Space
Насколько полезной была статья?

Google поиск по нашей документации

Falcon Space

Это снижение стоимости владения

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

Это быстрое внесение изменений

по ходу эксплуатации программы. Как создается функционал на платформе

Это простой удобный интерфейс

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