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

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

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 бота.

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).

См. подрообноее про настройки 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 (по аналогии с type=email). 
  • Любые параметры для замены в теле и теме письма, например name1. В теме и теле письма шаблона можно использовать псевдопараметры вида {name1}, которые будут заменяться соответствующим параметром из команды. 

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

Отправка SMS

select 'sms' type, 'Text 1' msg, '723429234' [number]
  • msg - текст SMS
  • number - телефон получателя

Вызов запроса к внешнему 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

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

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

Пример: 

 select 'generateImage' type, '
    {
                "ImageModel":{
		"path":"/uploads/image.png",
		"width":"500",
		"height":"500",
		"backColor":"red",
                },
		"ImageText": [
			{
				"Text":"Some text",
				"x":"10",
				"y":"10",
				"width":"400",
				"height":"30",
				"color":"black",
				"backColor":"black",
				"fontSize":"18",
				"fontFamily":"Arial"

            },
			{
				"Text":"Second line",
				"x":"10",
				"y":"40",
				"width":"800",
				"height":"30",
				"color":"blue",
				"backColor":"black",
				"fontSize":"20",
				"fontFamily":"Arial"
			},
			{
				"Text":"третья линия",
				"x":"10",
				"y":"70",
				"width":"400",
				"height":"30",
				"color":"green",
				"backColor":"black",
				"fontSize":"18",
				"fontFamily":"Arial"
			}
		],
		"ImagePicture": [
			{
				"path":"/uploads/Дашборды.gif",
				"x":"0",
				"y":"100",
				"width":"100",
				"height":"75",
				"opacity":"0.9"
			},
			{
				"path":"/uploads/Дашборды.gif",
				"x":"0",
				"y":"175",
				"width":"150",
				"height":"75",
				"opacity":"0.9"
			}
		],
		"ImageLine": [
			{
				"x1":"0",
				"y1":"200",
				"x2":"300",
				"y2":"200",
				"thickness":"3",
				"color":"black"
			},
			{
				"x1":"150",
				"y1":"300",
				"x2":"50",
				"y2":"0",
				"thickness":"20",
				"color":"black"
			},
			{
				"x1":"10",
				"y1":"200",
				"x2":"150",
				"y2":"300",
				"thickness":"3",
				"color":"black"
			},
            {
				"x1":"0",
				"y1":"0",
				"x2":"150",
				"y2":"300",
				"thickness":"3",
				"color":"white"
			}
		]
    }
    ' options

раздел ImageModel  - задает общие параметры: 

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

ImageText - это массив объектов Текст, каждый из которых имеет следующие параметры: 

  • text - текст, который требуется написать
  • x, y - координаты расположения блока
  • width, height - ширина и высота блока
  • color, backColor - цвет текста и цвет фона
  • fontSize, fontFamily - установка шрифта

ImagePicture - это массив Картинок, которые будут размещены на выходной картинке. У них следующие параметры: 

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

ImageLine - это массив Линий, которые будут размещены на выходной картинке. У них следующие параметры: 

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

Обработка картинок (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

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

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

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

select 'sendToBrowser' type, 'admin' username, '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 через запятую, которым будут отправлены данные.
  • 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. 

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

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

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

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

Если нам необходимо обработать результат выполнения внешнего действия, то мы должны передать парамер 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 внешнего дейсвтия). Также здесь передается langID.
  • data - результат выполнения внешнего действия
  • username - текущий пользователь

На выходе: 

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

 

Платформа Falcon Space

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

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

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

по ходу эксплуатации программы

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

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

Бесплатное обучение разработке на Falcon Space

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