Web-To-Object

PDF
Сложный

Web-to-Object — это механизм реализации простых односторонних интеграций с Creatio. С его помощью можно создавать записи в разделах Creatio (лиды, обращения, заказы и т. д.), просто отправив необходимые данные сервису Web-to-Object.

Наиболее распространенные случаи использования сервиса Web-to-Object:

  • Интеграция Creatio с пользовательскими лендингами и веб-формами. Вызов сервиса выполняется из лендинга (особым образом настроенная пользовательская страница со специальной web-формой), после отправки заполненной web-формы посетителем.
  • Интеграция с внешними системами, в результате работы которых должны создаваться объекты Creatio.

С помощью функциональности Web-to-Object можно настроить регистрацию в Creatio практически любых объектов. Например, в Creatio может быть зарегистрирован лид, контакт, заказ, обращение.

Для работы с лендингами в Creatio предусмотрен раздел Лендинги и web-формы. Этот раздел входит во все продукты Creatio, однако он может быть не включен по умолчанию в рабочие места некоторых продуктов (например, данный раздел не включен в рабочие места линейки продуктов Sales Creatio). Каждая запись раздела Лендинги и web-формы соответствует определенному лендингу. На странице записи предусмотрена вкладка Настройка лендинга.

Реализация сервиса Web-to-Object 

Основная функциональность механизма Web-To-Object содержится в пакете WebForm и является общей для всех продуктов. В зависимости от продукта Creatio эта функциональность расширена механизмами Web-to-Lead (пакет WebLeadForm), Web-to-Order (пакет WebOrderForm) и Web-to-Case (пакет WebCaseForm).

Для обработки данных, отправленных web-формой лендинга, в пакете WebForm реализован конфигурационный сервис GeneratedObjectWebFormService (класс Terrasoft.Configuration.GeneratedWebFormService). Данные веб-формы лендинга принимаются в качестве аргумента метода public string SaveWebFormObjectData(FormData formData). Затем они передаются в метод public void HandleForm(FormData formData) класса Terrasoft.Configuration.WebFormHandler, в котором и выполняется создание соответствующего объекта системы.

Внешний API сервиса Web-to-Object 

Для использования сервиса необходимо отправить POST-запрос по адресу
[Путь к приложению Creatio]/0/ServiceModel/GeneratedObjectWebFormService.svc/SaveWebFormObjectData
Например
http://myсreatio.com/0/ServiceModel/GeneratedObjectWebFormService.svc/SaveWebFormObjectData

Тип содержимого запроса — application/json. Кроме необходимых cookies, в содержимое запроса нужно добавить JSON-объект, содержащий данные веб-формы. Пример JSON-объекта:

{
    "formData":{
        "formId":"d66ebbf6-f588-4130-9f0b-0ba3414dafb8",
        "formFieldsData":[
            {"name":"Name","value":"John Smith"},
            {"name":"Email","value":"j.smith@creatio.com"},
            {"name":"Zip","value":"00000"},
            {"name":"MobilePhone","value":"0123456789"},
            {"name":"Company","value":"Creatio"},
            {"name":"Industry","value":""},
            {"name":"FullJobTitle","value":"Sales Manager"},
            {"name":"UseEmail","value":""},
            {"name":"City","value":"Boston"},
            {"name":"Country","value":"USA"},
            {"name":"Commentary","value":""},
            {"name":"BpmHref","value":"http://localhost/Landing/"},
            {"name":"BpmSessionId","value":"0ca32d6d-5d60-9444-ec34-5591514b27a3"}
        ]
    }
}

Интеграция с внешними системами 

Для интеграции с внешними системами необходимо:

1. Добавить запись в разделе Лендинги и web-формы.

2. Получить из конфигурационного объекта созданной записи адрес к сервису (свойство serviceUrl ) и идентификатор (свойство landingId).

3. Реализовать во внешней системе отправку POST-запроса к сервису Web-to-Object по полученному адресу. В запрос добавить необходимые данные в виде JSON-объекта. Свойству formId отправляемого JSON-объекта установить значение полученного идентификатора.

Смотрите также
Настроить web-форму для создания пользовательского объекта
Средний

Используя web-форму посадочной страницы (лендинга) стороннего сайта можно создать пользовательский объект в приложении Creatio. Подробнее о лендингах можно узнать из блока статей "Раздел Лендинги и web-формы".

Общий порядок действий при создании пользовательского объекта через web-форму:

  1. Зарегистрировать новый тип лендинга.
  2. Добавить страницу записи web-формы.
  3. Связать новый тип лендинга с созданной страницей записи.
  4. Актуализировать наполнение скриптами для страницы web-формы.
  5. Создать и настроить лендинг раздела [Лендинги и web-формы] ([Landing pages and web forms]).
  6. Развернуть и настроить посадочную страницу, содержащую web-форму.
  7. Зарегистрировать пользовательский объект в справочнике [Настройки объекта для элемента кампании "Лендинг" ([Entity settings for campaign landing element]).

Важно. Трекинг событий сайта работает только для лидов. Для пользовательских объектов трекинг событий сайта не работает.

Пример. Через web-форму посадочной страницы создайте пользовательский объект Контакт (Contact).

1. Зарегистрируйте новый тип лендинга 

Для регистрации нового типа лендинга выполните следующие действия:

  1. Перейдите в дизайнер системы по кнопке . В блоке [Настройка системы] ([System setup]) перейдите по ссылке [Справочники] ([Lookups]).
  2. Выберите справочник [Типы лендингов] ([Landing types]).
  3. Создайте новую запись.

Для создаваемой записи установите:

  • [Название] ([Name]) — "Contact";
  • [Объект] ([Object]) — "Contact".

2. Добавьте страницу web-формы 

В разделе Конфигурация (Configuration) пользовательского пакета на вкладке Схемы (Schemas) выполните действие Добавить —> Схема модели представления карточки (Add —> Schema of the Edit Page View Module). Процесс создания схемы модели представления карточки описан в статье "Cоздать клиентскую схему".

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

  • [Заголовок] ([Title]) — "ContactGeneratedWebFormPage";
  • [Название] ([Name]) — "UsrContactGeneratedWebFormPage";
  • [Родительский объект] ([Parent object]) — "Edit page, landing".
UsrContactGeneratedWebFormPage.js
// UsrContactGeneratedWebFormPage — уникальное название схемы.
define("UsrContactGeneratedWebFormPage", ["UsrContactGeneratedWebFormPageResources"],
    function() {
        return {
            details: /**SCHEMA_DETAILS*/{}/**SCHEMA_DETAILS*/,
            methods: {
                /**
                 * @inheritdoc BaseGeneratedWebFormPageV2#getScriptTemplateFromResources
                 * @overriden
                 */
                getScriptTemplateFromResources: function() {
                    var scriptTemplate;
                    if (this.getIsFeatureEnabled("OutboundCampaign")) {
                        // ContactScriptTemplate — имя локализуемой строки.
                        scriptTemplate = this.get("Resources.Strings.ContactScriptTemplate");
                    } else {
                        scriptTemplate = this.get("Resources.Strings.ScriptTemplate");
                    }
                    return scriptTemplate;
                }
            },
            diff: /**SCHEMA_DIFF*/[]/**SCHEMA_DIFF*/
        };
    });

После внесения изменений сохраните схему.

Добавьте локализируемую строку ContactScriptTemplate. В значение строки добавьте <div>Test</div> . Больше информации о работе с локализуемыми строками содержится в статье "Работа с локализуемыми ресурсами".

После внесения изменений сохраните схему.

3. Свяжите новый тип лендинга с созданной страницей записи 

Чтобы связать новый тип лендинга с созданной страницей записи, добавьте запись в таблицу dbo.SysModuleEdit базы данных. Для этого выполните следующий SQL-запрос:

Запрос для добавления записи в таблицу dbo.SysModuleEdit
-- Parameters of new landing page
DECLARE @editPageName nvarchar(250) = N'UsrContactGeneratedWebFormPage'; -- название созданной схемы
DECLARE @landingTypeName NVARCHAR(250) = N'Contact'; -- название типа лендинга
DECLARE @actionCaption NVARCHAR(250) = N'Contact form'; -- название типа лендинга в разделе при создании новой записи
 
-- Set system parameters based on new landing page
DECLARE @generatedWebFormEntityUId uniqueidentifier = '41AE7D8D-BEC3-41DF-A6F0-2AB0D08B3967';
DECLARE @cardSchemaUId uniqueidentifier = (select top 1 UId from SysSchema where Name = @editPageName);
DECLARE @pageCaption nvarchar(250) = (select top 1 Caption from SysSchema where Name = @editPageName);
DECLARE @sysModuleEntityId uniqueidentifier = (select top 1 Id from SysModuleEntity where SysEntitySchemaUId = @generatedWebFormEntityUId);
DECLARE @landingTypeId uniqueidentifier = (SELECT TOP 1 Id FROM LandingType WHERE Name = @landingTypeName);
 
-- Adding new Landing page variant to application interface
INSERT INTO SysModuleEdit
(Id, SysModuleEntityId, TypeColumnValue, UseModuleDetails, CardSchemaUId, ActionKindCaption, ActionKindName, PageCaption)
VALUES
(NEWID(), @sysModuleEntityId, @landingTypeId, 1, @cardSchemaUId, @actionCaption, @editPageName, @pageCaption)

Важно. 41AE7D8D-BEC3-41DF-A6F0-2AB0D08B3967 — неизменный идентификатор схемы сущности GeneratedWebForm в таблице dbo.SysSchema базы данных для любого кейса добавления посадочной страницы для пользовательской сущности.

После выполнения скрипта очистите кэш браузера. В результате в разделе Лендинги и web-формы (Landing pages and web forms) появится возможность добавить новый тип лендинга Contact form. Но при открытии страницы лендинга будет отсутствовать скрипт, который необходимо добавить в код посадочной страницы.

Реестр раздела Лендинги и web-формы (Landing pages and web forms)
Страница лендинга

4. Актуализируйте наполнение скриптами для страницы web-формы 

Значение переменной содержит экранированный html с тегами <script> и другую информацию по настройке связи полей web-формы — колонок создаваемой сущности. Это значение должно быть локализируемым. Для этого выполните следующий SQL-запрос:

-- Landing edit page schema name
DECLARE @editPageName nvarchar(250) = N'UsrContactGeneratedWebFormPage'; -- название созданной схемы
 
-- region Scripts' structure
DECLARE @sqriptPrefix nvarchar(max) = N'<div style="font-family: &quot;Courier New&quot;, monospace; font-size: 10pt;">&lt;script&nbsp;src=&quot;http://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js&quot;&gt;&lt;/script&gt;<br>&lt;script&nbsp;src=&quot;https://webtracking-v01.bpmonline.com/JS/track-cookies.js&quot;&gt;&lt;/script&gt;<br>&lt;script&nbsp;src=##apiUrl##&gt;&lt;/script&gt;<br>&lt;script&gt;<br>/**<br>*&nbsp;Replace&nbsp;the&nbsp;&quot;<span style="color: #0c0cec;">css-selector</span>&quot;&nbsp;placeholders&nbsp;in&nbsp;the&nbsp;code&nbsp;below&nbsp;with&nbsp;the&nbsp;element&nbsp;selectors&nbsp;on&nbsp;your&nbsp;landing&nbsp;page.<br>*&nbsp;You&nbsp;can&nbsp;use&nbsp;#id&nbsp;or&nbsp;any&nbsp;other&nbsp;CSS&nbsp;selector&nbsp;that&nbsp;will&nbsp;define&nbsp;the&nbsp;input&nbsp;field&nbsp;explicitly.<br>*&nbsp;Example:&nbsp;&quot;Email&quot;:&nbsp;&quot;#MyEmailField&quot;.<br>*&nbsp;If&nbsp;you&nbsp;don&quot;t&nbsp;have&nbsp;a&nbsp;field&nbsp;from&nbsp;the&nbsp;list&nbsp;below&nbsp;placed&nbsp;on&nbsp;your&nbsp;landing,&nbsp;leave&nbsp;the&nbsp;placeholder&nbsp;or&nbsp;remove&nbsp;the&nbsp;line.<br>*/<br>var&nbsp;config&nbsp;=&nbsp;{<br>&nbsp;&nbsp;&nbsp;&nbsp;fields:&nbsp;{<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;';
DECLARE @sqriptDelimiter nvarchar(max) = N'<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;';
DECLARE @sqriptSuffix nvarchar(max) = N'<br>&nbsp;&nbsp;&nbsp;&nbsp;},<br>&nbsp;&nbsp;&nbsp;&nbsp;landingId:&nbsp;##landingId##,<br>&nbsp;&nbsp;&nbsp;&nbsp;serviceUrl:&nbsp;##serviceUrl##,<br>&nbsp;&nbsp;&nbsp;&nbsp;redirectUrl:&nbsp;##redirectUrl##<br>};<br>/**<br>*&nbsp;The&nbsp;function&nbsp;below&nbsp;creates&nbsp;a&nbsp;object&nbsp;from&nbsp;the&nbsp;submitted&nbsp;data.<br>*&nbsp;Bind&nbsp;this&nbsp;function&nbsp;call&nbsp;to&nbsp;the&nbsp;&quot;onSubmit&quot;&nbsp;event&nbsp;of&nbsp;the&nbsp;form&nbsp;or&nbsp;any&nbsp;other&nbsp;elements&nbsp;events.<br>*&nbsp;Example:&nbsp;&lt;form&nbsp;class=&quot;mainForm&quot;&nbsp;name=&quot;landingForm&quot;&nbsp;onSubmit=&quot;createObject();&nbsp;return&nbsp;false&quot;&gt;<br>*/<br>function&nbsp;createObject()&nbsp;{<br>&nbsp;&nbsp;&nbsp;&nbsp;landing.createObjectFromLanding(config)<br>}<br>/**<br>*&nbsp;The&nbsp;function&nbsp;below&nbsp;inits&nbsp;landing&nbsp;page&nbsp;using&nbsp;URL&nbsp;parameters.<br>*/<br>function&nbsp;initLanding()&nbsp;{<br>&nbsp;&nbsp;&nbsp;&nbsp;landing.initLanding(config)<br>}<br>jQuery(document).ready(initLanding)<br>&lt;/script&gt;</div>';
-- endregion
 
-- region Scripts' variables
DECLARE @sqriptNameColumn nvarchar(max); -- объявляем переменные для колонок, которые будем мапить с лендингом
DECLARE @sqriptEmailColumn nvarchar(max);
DECLARE @scriptResult nvarchar(max);
-- endregion
 
-- Adding entity columns.
SET @sqriptNameColumn = N'&quot;Name&quot;:&nbsp;&quot;<span style="color: #0c0cec;">css-selector</span>&quot;,&nbsp;//&nbsp;Name&nbsp;of&nbsp;a&nbsp;contact';
SET @sqriptEmailColumn = N'&quot;Email&quot;:&nbsp;&quot;<span style="color: #0c0cec;">css-selector</span>&quot;,&nbsp;//&nbsp;Email';
 
-- Concat result scripts.
SET @scriptResult = @sqriptPrefix + @sqriptNameColumn + @sqriptDelimiter + @sqriptEmailColumn + @sqriptSuffix;
 
-- Set new localizable scripts value for resource with name like '%ScriptTemplate'
UPDATE SysLocalizableValue
SET [Value] = @scriptResult
WHERE SysSchemaId = (SELECT TOP 1 Id FROM SysSchema WHERE [Name] = @editPageName)
and [Key] like '%ScriptTemplate.Value'

В блоке Adding entity columns добавьте названия колонок сущности, которые будут заполняться значениями из web-формы.

Важно. Символы двойных кавычек (") и пробела ( ) необходимо заменить экранируемыми " и  .

Важно. Для добавления поля необходимо добавить переменную (@sqriptИмяПеременнойColumn) и конкатенировать ее в scriptResult.

Если после выполнения всех настроек появилась необходимость получать значения других полей (кроме Name и Email), то необходимо повторно выполнить скрипт из данного пункта, но в блоке Adding entity columns прописать все необходимые колонки, включая существующие. При повторном выполнении скрипта произойдет обновление ранее созданных настроек.

После выполнения скрипта необходимо открыть созданную в конфигурации схему и пересохранить ее, чтобы пересохранились ресурсы. В результате в разделе Лендинги и web-формы (Landing pages and web forms) при выборе Contact form будет отображена страница лендинга со скриптом, который необходимо разместить в коде посадочной страницы.

Скрипт содержит конфигурационный объект config, в котором определены следующие свойства:

  • fields — содержит объект со свойствами Name и Email, значения которых должны совпадать с селекторами атрибутов id соответствующих полей web-формы.
  • landingId — содержит идентификатор лендинга в базе данных.
  • serviceUrl — содержит URL службы, по которому будут отправляться данные web-формы.
  • onSuccess — содержит функцию-обработчик успешного создания контакта. Необязательное свойство.
  • onError — содержит функцию-обработчик ошибки создания контакта. Необязательное свойство.

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

var config = {
    fields: {
        "Name": "css-selector", // Имя контакта
        "Email": "css-selector", // Email контакта
    },
    landingId: "b73790ab-acb1-4806-baea-4342a1f3b2a8",
    serviceUrl: "http://localhost:85/0/ServiceModel/GeneratedObjectWebFormService.svc/SaveWebFormObjectData",
    redirectUrl: ""
};

5. Создайте и настройте лендинг раздела [Лендинги и web-формы] ([Landing pages and web forms]) 

Чтобы создать новую запись лендинга необходимо в разделе Лендинги и web-формы (Landing pages and web forms) выбрать Contact form. Добавление записи в раздел Лендинги и web-формы (Landing pages and web forms) описано в статье "Как добавить новую запись в разделе Лендинги и web-формы".

Для создаваемой записи установите:

Для применения изменений сохраните страницу.

6. Разверните и настройте посадочную страницу, содержащую web-форму 

Чтобы создать посадочную страницу для лендинга необходимо в любом текстовом редакторе при помощи html-разметки создать обычную посадочную страницу, содержащую web-форму. Создание посадочной страницы и добавление скрипта созданного лендинга в код посадочной страницы описаны в статье "Как связать лендинг на сайте с Creatio".

Для регистрации в Creatio данных контакта, отправляемых через web-форму, в код посадочной страницы необходимо добавить следующие поля (html-элемент <input>):

  • Имя контакта.
  • Email контакта.

Для каждого поля необходимо указать атрибуты name и id.

Чтобы при отправке данных web-формы в Creatio создавался новый объект Контакт (Contact), в посадочную страницу добавьте скрипт на языке JavaScript. Исходный код скрипта скопируйте из поля ШАГ 2. Скопируйте код и настройте в нем соответствие полей (STEP 2. Copy the code and configure and map the fields) страницы лендинга (рис. 8).

Конфигурационный объект config передается в качестве аргумента функции createObject(), которая должна выполняться при отправке web-формы.

Чтобы функция createObject() была вызвана при отправке web-формы, в тег <form> web-формы посадочной страницы добавьте атрибут onSubmit="createObject(); return false" из поля ШАГ 3. Вставьте настроенный код на страницу лендинга. Настройте запуск функции создания объекта по submit формы (STEP 3. Insert the customized code into the landing page source code. Set up a function to create the object on form submit) страницы лендинга.

Исходный код посадочной страницы
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <!--ШАГ 2-->
    <!--Эту часть необходимо скопировать из поля ШАГ 2 страницы редактирования лендинга-->
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
    <script src="https://webtracking-v01.bpmonline.com/JS/track-cookies.js"></script>
    <script src="https://webtracking-v01.bpmonline.com/JS/create-object.js"></script>
    <script>
    
    /**
    * Замените выражение в кавычках "css-selector" в коде ниже значением селектора элемента на Вашей лендинговой странице.
    * Вы можете использовать #id или любой другой CSS селектор, который будет точно определять поле ввода на Вашей лендинговой странице.
    * Пример: "Email": "#MyEmailField".
    * Если Ваша лендинговая страница не содержит одного или нескольких полей из приведенных ниже – оставьте строку без изменений или удалите полностью.
    */
    var config = {
        fields: {
            "Name": "#name-field", // Имя контакта
            "Email": "#email-field", // Email контакта
        },
        landingId: "b73790ab-acb1-4806-baea-4342a1f3b2a8",
        serviceUrl: "http://localhost:85/0/ServiceModel/GeneratedObjectWebFormService.svc/SaveWebFormObjectData",
        redirectUrl: "",
        onSuccess: function(response) {
            window.alert(response.resultMessage);
        },
        onError: function(response) {
            window.alert(response.resultMessage);
        }
    };
    /**
    * Функция ниже создает объект из введенных данных.
    * Привяжите вызов этой функции к событию "onSubmit" формы или любому другому элементу события.
    * Пример: <form class="mainForm" name="landingForm" onSubmit="createObject(); return false">
    */
    function createObject() {
        landing.createObjectFromLanding(config)
    }
    /**
    * Функция ниже инициализирует лендинг из параметров URL.
    */
    function initLanding() {
        landing.initLanding(config)
    }
    jQuery(document).ready(initLanding)
    </script>
    <!--ШАГ 2-->
    
</head>
<body>
<h1>Landing web-page</h1>
<div>
    <h2>Contact form</h2>
    <form method="POST" class="mainForm" name="landingForm" onSubmit="createObject(); return false">
        Name:<br>
        <input type="text" name="Name" id="name-field"><br>
        Email:<br>
        <input type="text" name="Email" id="email-field"><br><br><br>
        <input type="submit" value="Submit">
        </font>
    </form>
</div>
</body>
</html>

Откройте посадочную страницу. Для создаваемого контакта установите:

  • [Name] — "New User";
  • [Email] — "new_user@creatio.com".

Для создания контакта нажмите Submit.

Важно. Контакт с посадочной страницы будет добавлен в Creatio только в том случае, если страница размещена на сайте, имя которого указано в поле Домены сайта (Website domains) лендинга.

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

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

7. Зарегистрируйте пользовательский объект в справочнике 

Для использования пользовательского лендинга в маркетинговых кампаниях (элемент [Добавить из лендинга] ([Landing page])), нужно зарегистрировать его в справочнике.

Регистрация объекта в справочнике [Настройки объекта для элемента кампании "Лендинг"] ([Entity settings for campaign landing element]):

  1. Перейдите в дизайнер системы по кнопке .
  2. В блоке [Настройка системы] перейдите по ссылке [Справочники] ([Lookups]).
  3. Откройте справочник [Настройки объекта для элемента кампании "Лендинг"] ([Entity settings for campaign landing element]).
  4. Нажмите [Добавить] ([Add]). Для создаваемого объекта заполните поля:
    • [Название] ([Caption]) — пользовательское название объекта.
    • [Объект] ([Entity object]) — создаваемый посадочной страницей объект системы.
    • [Путь к Контакту] ([Path to Contact]) — путь к колонке, которая связывает запись с контактом.
    • [Путь к идентификатору веб-формы] ([Path to WebForm]) — путь к колонке, которая связывает запись с посадочной страницей.
  5. Сохраните объект.

Пример заполнения полей для объектов [Лид] ([Lead]) и [Участник мероприятия] ([Event participant]) представлен в таблице.

Полей объектов [Лид] ([Lead]) и [Участник мероприятия] ([Event participant])
Имя поля Значение поля объекта
[Лид] ([Lead]) [Участник мероприятия] ([Event participant])
[Название] ([Caption]) Lead Event participant
[Объект] ([Entity object]) Lead Event participant
[Путь к Контакту] ([Path to Contact]) QualifiedContact Contact
[Путь к идентификатору веб-формы] ([Path to WebForm]) WebForm GeneratedWebForm

Для создаваемой записи установите:

  • [Название] (Caption) — "Contact";
  • [Объект] ([Entity object]) — "Lead";
  • [Путь к Контакту] ([Path to Contact]) — "QualifiedContact";
  • [Путь к идентификатору веб-формы] ([Path to WebForm]) — "WebForm".

Пользовательский лендинг "Contact" доступен к выбору в элементе [Добавить из лендинга] ([Landing page]) маркетинговых кампаний.