Общие положения

Веб-служба DataService приложения Creatio является RESTful-сервисом, т.е. поддерживает передачу состояния представления (Representational State Transfer, REST). В общем случае REST является очень простым интерфейсом управления информацией без использования каких-то дополнительных внутренних прослоек, т.е. данные не нужно преобразовывать в какой-либо сторонний формат, например, XML. В простом RESTful-сервисе каждая единица информации однозначно определяется глобальным идентификатором, таким как URL. Каждый URL, в свою очередь, имеет строго заданный формат. Однако это не всегда удобно для передачи больших массивов данных.

В DataService данные автоматичеcки могут быть сконфигурированы в различные форматы данных, такие как XML, JSON, HTML, CSV и JSV. Структура данных определяется так называемыми контрактами данных. Полный перечень контрактов данных, используемых службой DataService, изложен в статье "Веб-служба DataService".

Контракт данных InsertQuery

Для добавления записей в раздел используется контракт данных InsertQuery. Передача непосредственно данных в службу DataService осуществляется по HTTP протоколу при помощи POST-запроса по следующему URL:

// Формат URL для POST-запроса на добавление данных к DataService.
http(s)://[Адрес приложения Creatio]/[Номер конфигурации]/dataservice/[Формат данных]/reply/InsertQuery
// Пример URL для POST-запроса на добавление данных к DataService.
http(s)://example.creatio.com/0/dataservice/json/reply/InsertQuery

Контракт данных InsertQuery имеет иерархическую структуру с несколькими уровнями вложенности. В серверной части ядра приложения Creatio он представлен классом InsertQuery пространства имен Terrasoft.Nui.ServiceModel.DataContract библиотеки классов Terrasoft.Nui.ServiceModel.dll. Однако для простоты восприятия иерархическую структуру контракта данных InsertQuery удобно представить в формате объекта JSON:

{
    "RootSchemaName":"[Имя корневой схемы объекта]",
    "OperationType":[Тип операции с записью],
    "ColumnValues":{
        "Items":{
            "Имя добавляемой колонки":{
                "ExpressionType":[Тип выражения],
                "Parameter":{
                    "DataValueType":[Тип данных],
                    "Value":"[Значение колонки]"
                }
            }...
        }
    }
}

Основные свойства класса InsertQuery и их возможные значения представлены в таблице 1.

Табл. 1. — Свойства класса InsertQuery

Класс ColumnValues имеет единственное свойство Items, которое определено как коллекция ключей и значений Dictionary<string, ColumnExpression>. Ключом является строка с названием добавляемой колонки, а значением — объект типа ColumnExpression, определенный в пространстве имен Terrasoft.Nui.ServiceModel.DataContract. Основные свойства класса ColumnExpression, используемые при добавлении записей, приведены в табл. 2.

Табл. 2. — Основные свойства класса ColumnExpression

Класс Parameter имеет несколько свойств, из которых только два используются для добавления записи (табл.3).

Табл. 3. — Основные свойства класса Parameter

Пример создания записи в приложении Creatio

Описание кейса

Добавить в раздел [Контакт] кнопку при нажатии на которую вызывается метод, который, используя класс InsertQuery, добавляет запись со следующими данными:

• ФИО — Иванов Иван Иванович;
• Должность — Разработчик;
• Рабочий телефон — +12 345 678 00 00.

Пример реализации

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

Алгоритм реализации кейса

1. Добавить в раздел [Контакты] кнопку

Процесс добавления кнопки в раздел подробно описан в статье "Добавление кнопки в раздел".

Для рассматриваемого кейса необходимо создать замещающий клиентский модуль раздела [Контакты] (рис. 1).

Рис. 1. — Свойства замещающего клиентского модуля

В созданной клиентской схеме добавить локализуемую строку InsertQueryContactButtonCaption, для которой установить значение "Добавить контакт" (рис. 2).

Рис. 2. — Свойства локализуемой строки

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

diff: /**SCHEMA_DIFF*/[
    // Метаданные для добавления в раздел пользовательской кнопки.
    {
        // Выполняется операция добавления элемента на страницу.
        "operation": "insert",
        // Название родительского элемента управления, в который добавляется кнопка.
        "parentName": "ActionButtonsContainer",
        // Кнопка добавляется в коллекцию элементов управления
        // родительского элемента (мета-имя которого указано в parentName).
        "propertyName": "items",
        // Мета-имя добавляемой кнопки.
        "name": "InsertQueryContactButton",
        // Дополнительные свойства элемента.
        "values": {
            // Тип добавляемого элемента — кнопка.
            itemType: Terrasoft.ViewItemType.BUTTON,
            // Привязка заголовка кнопки к локализуемой строке схемы.
            caption: { bindTo: "Resources.Strings.InsertQueryContactButtonCaption" },
            // Привязка метода-обработчика нажатия кнопки.
            click: { bindTo: "onInsertQueryContactClick" },
            "layout": {
                "column": 1,
                "row": 6,
                "colSpan": 1
            }
        }
    }
]/**SCHEMA_DIFF*/

2. Добавить метод-обработчик события нажатия кнопки

Для того чтобы при нажатии на созданную в разделе кнопку добавлялась запись с необходимыми данными, в секцию methods замещающей клиентской схемы необходимо добавить следующий метод:

methods: {
    // Метод-обработчик нажатия кнопки.
    onInsertQueryContactClick: function() {
        // Создание экземпляра класса Terrasoft.InsertQuery.
        var insert = Ext.create("Terrasoft.InsertQuery", {
            // Название корневой схемы.
            rootSchemaName: "Contact"
        });
        // Установка значений-параметров Terrasoft.ParameterExpression.
        // Создается экземпляр значения-параметра и добавляется в коллекцию значений колонок.
        // Создание экземпляра значения-параметра для колонки [ФИО].
        insert.setParameterValue("Name", "Иванов Иван Иванович", Terrasoft.DataValueType.TEXT);
        // Создание экземпляра значения-параметра для колонки [Рабочий телефон].
        insert.setParameterValue("Phone", "+12 345 678 00 00", Terrasoft.DataValueType.TEXT);
        // Создание экземпляра значения-параметра для колонки [Должность].
        insert.setParameterValue("Job", "11D68189-CED6-DF11-9B2A-001D60E938C6", Terrasoft.DataValueType.GUID);
        // Запрос к серверу на обновление данных
        insert.execute(function(response) {
            // Вывод ответа от сервера в консоль браузера.
            window.console.log(response);
        });
        // Обновление данных реестра.
        this.reloadGridData();
    }
}

Реализация класса InsertQuery для клиентской части ядра приложения несколько отличается от реализации класса InsertQuery в его серверной части. Так, для создания параметров предусмотрен метод setParameterValue, а для выполнения запроса — метод execute. Узнать обо всех доступных свойствах и методах класса InsertQuery, реализованного в клиентской части ядра приложения, можно в документации по API здесь.

Смотрите также