Пример разработки простого приложения для Creatio Marketplace

Общие сведения

Приложение для Creatio Marketplace является проектным решением, расширяющим возможности базовых продуктов Creatio и имеющее дополнительную бизнес-ценность. Поэтому разработка приложения для Marketplace практически ничем не отличается от разработки обычного проектного решения. Подробности об основных принципах разработки решений для базовых продуктов Creatio можно узнать в разделе "С чего начать разработку" документации по разработке.

Поскольку приложение для Creatio Marketplace является проектным решением, предоставляемым сторонним пользователям, то необходим механизм установки этого решения в пользовательские приложения. В Creatio этот механизм реализован с помощью пакетов. Пакет Creatio — это совокупность конфигурационных элементов, которые реализуют определенный блок функциональности. Подробнее о пакетах и работе с ними можно узнать из раздела "Работа с пакетами" документации по разработке.

Количество и состав пакетов, реализующих приложение для Creatio Marketplace зависит от сложности функциональности, заложенной в приложение. Например, для вызова стороннего сервиса с существующей страницы редактирования достаточно заместить одну или несколько схем, сгруппировав их в одном пользовательском пакете. А для создания нового раздела Creatio, реализующего сложную функциональность, необходимо разработать уже несколько десятков новых схем и модулей.

Последовательность создания простого приложения:

1. Если необходимо, создать Web-сервис. Web-сервис может быть реализован с помощью конфигурационных элементов Creatio или как стороннее решение.

2. Создать пользовательский пакет.

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

4. В замещающей схеме реализовать необходимую функциональность.

Описание приложения

Создать проектное решение, реализующее на странице главного меню приложения Creatio для продукта sales enterprise вызов стороннего Web-сервиса, предоставляющего строку приветствия. Вызов Web-сервиса реализовать при помощи HTTP-запроса методом POST, передав в качестве параметра имя текущего пользователя. Результат отобразить под секцией ссылок на страницы социальных сетей.

Алгоритм реализации приложения

1. Реализация Web-сервиса

В зависимости от назначения, Web-сервис может быть реализован разными способами, с помощью различных языков программирования и на разных платформах.

Исходя из условий кейса, необходим простейший, так называемый, микросервис. Для его реализации можно использовать одну из площадок, предоставляющую возможность создания микросервисов, например open-source проект https://hook.io.

После регистрации пользователя площадки и входа в систему отобразится страница управления микросервисами, на которой можно создать новый Web-сервис (рис. 1, 1).

Рис. 1. — Страница управления микросервисами hook.io

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

Рис. 2. — Создание конечной точки

Рис. 3. — Добавление исходного кода микросервиса

После сохранения исходного кода (рис. 3, 3) сервис становится сразу же доступен для использования. Адрес конечной точки https://hook.io/academy-creatio-com/creatiohello.

Исходный код сервиса представляет собой функцию, которая на основе параметра name HTTP-запроса формирует строку приветствия и отправляет ее в качестве ответа клиентскому приложению. Полностью исходный код микросервиса:

module["exports"] = function helloWorld (hook) {
  // Формирование строки ответа.
  var result = "Добро пожаловать в микросервис creatiohello, " + hook.params.name + "!";
  // Отправка ответа клиенту.
  hook.res.end(result);
};

2. Создание пользовательского пакета

Создание и редактирование пользовательского пакета Creatio выполняется в разделе [Конфигурация]. Подробно процесс создания пользовательского пакета описан в статье "Создание пользовательского пакета".

Чтобы создать новый пользовательский пакет, необходимо в контекстном меню на панели [Пакеты] раздела [Конфигурация] выбрать действие [Добавить] (рис. 4).

Рис. 4. — Добавление пользовательского пакета

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

Рис. 5. — Основные свойства пакета

Основные свойства пакета:

• [Название] — название пакета. Обязательное для заполнения поле. Не может совпадать с названием уже существующих пакетов. В названии обязательно должен быть отображен префикс разработчика, указанный в профиле разработчика.
• [Описание] — описание пакета, например, расширенная информация о функциональности, которая реализуется в пакете. Необязательное поле.

После заполнения полей карточки и нажатия на кнопку [ОК] пакет будет создан и отобразится на вкладке [Пакеты].

Для того чтобы созданный пакет имел всю функциональность, которая заложена в систему, для него нужно определить зависимости. При этом достаточно указать самый последний пакет в иерархии предустановленных пакетов. Чтобы определить, какой из пакетов в иерархии предустановленных пакетов является последним, нужно перейти на вкладку [Зависимости пакетов] раздела [Конфигурация]. Далее необходимо найти первый пакет, который находится выше пакета [Custom]. Подробнее об основных пакетах системы и зависимостях пакетов рассказывается в статье "Зависимости пакетов. Основные пакеты системы".

Для добавления зависимости необходимо в карточке пакета на вкладке [Зависит от пакетов], нажать на кнопку [Добавить] (рис. 6, 1). Затем в справочнике пакетов выбрать необходимый пакет (рис. 6, 2) и нажать на кнопку [ОК] (рис. 6, 3). После добавления всех нужных зависимостей пакет необходимо сохранить (рис. 6, 4).

Рис. 6. — Добавление зависимости пакета

3. Создание замещающей схемы

Главное меню приложения Creatio формируется в нескольких схемах модели представления, образующих иерархию наследования:

• Базовая схема главной страницы (BaseIntroPageSchema, пакет UIv2) — родительская схема модели представления, в которой формируются основные контейнеры главной страницы. Добавляет в модель представления разделение на левую и правую части, панели отображения видео и панель ссылок на страницы социальных сетей.
• Схема главного меню для базового продукта (SimpleIntro, пакет UIv2) — наследуется от BaseIntroPageSchema. Добавляет на главную страницу ссылки блоков [Базис], [Аналитика] и [Настройка].
• Схема главного меню для продукта Enterprise (EnterpriseIntro, пакет SalesEnterprise) — наследуется от SimpleIntro. Добавляет в левую часть меню дополнительные ссылки секции [Базис], а также ссылки секции [Продажи]. Дополнительно переопределяет ссылку на видеоролик.

Для внесения пользовательских изменений в главное меню продукта Sales Enterprise необходимо заместить схему EnterpriseIntro и реализовать в ней дополнительную функциональность. Создание замещающей клиентской схемы подробно рассмотрено в статье "Создание клиентской схемы".

Чтобы создать замещающую схему, необходимо на панели [Пакеты] в разделе [Конфигурация] выбрать созданный на предыдущем шаге пакет. Затем на вкладке [Схемы] выполнить команду [Добавить] > [Замещающий клиентский модуль] (рис. 7).

Рис. 7. — Добавление замещающего клиентского модуля

В появившемся окне дизайнера клиентской схемы необходимо на вкладке [Структура] выбрать корневой элемент структуры схемы (рис. 8, 1), затем на вкладке [Структура] ввести заголовок замещаемой схемы в поле [Родительский объект]. Во время набора заголовка схемы (рис. 8, 2) система отфильтрует и предложит возможные варианты выбора заголовков (рис. 8, 3). Следует выбрать значение "Схема главного меню для продукта Enterprise".

Рис. 8. — Выбор родительской схемы

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

4. Реализация функциональности

Для реализации пользовательской функциональности в созданную схему необходимо добавить исходный код. Подробности о структуре исходного кода схемы модели представления и ее свойствах можно узнать из раздела "Клиентские схемы модели представления" документации по разработке Creatio.

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

Для реализации необходимой пользовательской логики необходимо разработать метод вызова микросервиса SetHelloAttribute(), в котором будет использован JavaScript-объект XMLHttpRequest. Этот метод необходимо вызвать при загрузке страницы. Для этого необходимо переопределить метод родительской схемы Init(), в котором вызвать SetHelloAttribute(). Результат вызова запроса к микросервису можно получить в Callback-функции, присвоенной свойству onreadystatechange объекта XMLHttpRequest. Однако вследствие асинхронности выполнения запроса, результат необходимо сохранить в атрибуте HelloAttribute схемы. Сам же атрибут необходимо связать со свойством caption надписи, отображающей запрос.

Исходный код схемы модели представления главного меню:

define("EnterpriseIntro", [], function() {
    return {
        attributes: {
            // Атрибут, содержащий сообщение от пользовательского сервиса.
            "HelloAttribute": {
                // Тип данных атрибута.
                "dataValueType": Terrasoft.DataValueType.TEXT,
                // Тип атрибута — виртуальная колонка.
                "type": Terrasoft.ViewModelColumnType.VIRTUAL_COLUMN,
                // Значение по умолчанию.
                "value": ""
            }
        },
        methods: {
            // Метод инициализации схемы.
            init: function() {
                // Вызов базовой функциональности.
                this.callParent(arguments);
                // Вызов пользовательского сервиса.
                this.SetHelloAttribute();
            },
            // Метод вызова пользовательского сервиса.
            SetHelloAttribute: function() {
                // Создание HTTP-запроса.
                var xhr = new XMLHttpRequest();
                // URL вызова пользовательского сервиса.
                var url = "https://hook.io/academy-creatio-com/creatiohello";
                // Определение имени текущего пользователя.
                var currUser = Terrasoft.SysValue.CURRENT_USER_CONTACT.displayValue;
                // Формирование параметров HTTP-запроса.
                var params = "name=" + currUser;
                xhr.open("POST", url, true);
                xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
                // Сохранение контекста.
                var self = this;
                // Callback-функция, вызываемая при получении ответа.
                xhr.onreadystatechange = function() {
                    // Если получен ответ с необходимым статусом.
                    if (xhr.readyState === 4 && xhr.status === 200) {
                        // Установка значения атрибута.
                        self.set("HelloAttribute", xhr.responseText);
                    }
                    else {
                        self.set("HelloAttribute", "Микросервис creatiohello недоступен!");
                    }
                };
                // Отправка HTTP-запроса.
                xhr.send(params);
            }
        },
        diff: [
            // Пользовательский контейнер, в котором будет содержаться приветствие.
            {
                // Операция добавления.
                "operation": "insert",
                // Имя элемента.
                "name": "HelloContainer",
                // Имя родительского элемента-контейнера.
                "parentName": "RightContainer",
                // Имя свойства родительского элемента для вложенных элементов.
                "propertyName": "items",
                // Конфигурационный объект свойств элемента.
                "values": {
                    // Тип элемента — контейнер.
                    "itemType": Terrasoft.ViewItemType.CONTAINER,
                    // Массив вложенных элементов.
                    "items": []
                }
            },
            // Надпись для отображения приветствия.
            {
                "operation": "insert",
                "name": "HelloLabel",
                "parentName": "HelloContainer",
                "propertyName": "items",
                "values": {
                    // Тип элемента — надпись.
                    "itemType": this.Terrasoft.ViewItemType.LABEL,
                    // Ссылка на атрибут с текстом надписи.
                    "caption": { "bindTo": "HelloAttribute" }
                }
            }
        ]
    };
});

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

Рис. 9. — Результат выполнения кейса