Пользовательские веб-сервисы

1. Создать схему Исходный код 

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

2. На панели инструментов реестра раздела нажмите Добавить —> Исходный код (Add —> Source code).

   

3. В дизайнере схем заполните свойства схемы:

   • Код (Code) — "UsrCustomConfigurationService".
   • Заголовок (Title) — "CustomConfigurationService".
   

   Для применения заданных свойств нажмите Применить (Apply).

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

1. В дизайнере схем добавьте пространство имен, вложенное в Terrasoft.Configuration. Название может быть любым, например, UsrCustomConfigurationServiceNamespace.
2. C помощью директивы using добавьте пространства имен, типы данных которых будут задействованы в классе.
3. Добавьте название класса, которое соответствует названию схемы (свойство Код (Code)).
4. В качестве родительского класса укажите класс Terrasoft.Nui.ServiceModel.WebService.BaseService.
5. Для класса добавьте атрибуты [ServiceContract] и [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)].

3. Реализовать метод класса 

В дизайнере схем добавьте в класс метод public string GetContactIdByName(string Name), который реализует конечную точку пользовательского веб-сервиса. С помощью EntitySchemaQuery метод отправит запрос к базе данных. В зависимости от значения параметра Name, отправленного в строке запроса, тело ответа на запрос будет содержать:

• Идентификатор контакта (типа строка) — если контакт найден.
• Идентификатор первого найденного контакта (типа строка) — если найдено несколько контактов.
• Пустую строку — если контакт не найден.

Исходный код пользовательского веб-сервиса UsrCustomConfigurationService представлен ниже.

namespace Terrasoft.Configuration.UsrCustomConfigurationServiceNamespace
{
    using System;
    using System.ServiceModel;
    using System.ServiceModel.Web;
    using System.ServiceModel.Activation;
    using Terrasoft.Core;
    using Terrasoft.Web.Common;
    using Terrasoft.Core.Entities; 

    [ServiceContract]
    [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]
    public class UsrCustomConfigurationService: BaseService
    {
        
        /* Метод, возвращающий идентификатор контакта по имени контакта. */
        [OperationContract]
        [WebInvoke(Method = "GET", RequestFormat = WebMessageFormat.Json, BodyStyle = WebMessageBodyStyle.Wrapped,
        ResponseFormat = WebMessageFormat.Json)]
        public string GetContactIdByName(string Name) {
            /* Результат по умолчанию. */
            var result = "";
            /* Экземпляр EntitySchemaQuery, обращающийся в таблицу Contact базы данных. */
            var esq = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "Contact");
            /* Добавление колонок в запрос. */
            var colId = esq.AddColumn("Id");
            var colName = esq.AddColumn("Name");
            /* Фильтрация данных запроса. */
            var esqFilter = esq.CreateFilterWithParameters(FilterComparisonType.Equal, "Name", Name);
            esq.Filters.Add(esqFilter);
            /* Получение результата запроса. */
            var entities = esq.GetEntityCollection(UserConnection);
            /* Если данные получены. */
            if (entities.Count > 0)
            {
                /* Возвратить значение колонки "Id" первой записи результата запроса. */
                result = entities[0].GetColumnValue(colId.Name).ToString();
                /* Также можно использовать такой вариант:
                result = entities[0].GetTypedColumnValue<string>(colId.Name); */
            }
            /* Возвратить результат. */
            return result;
        }
    }
}

На панели инструментов дизайнера нажмите Сохранить (Save), а затем Опубликовать (Publish).

Результат выполнения примера 

В результате выполнения примера в Creatio появится пользовательский веб-сервис UsrCustomConfigurationService типа REST с конечной точкой GetContactIdByName.

Из браузера обратитесь к конечной точке GetContactIdByName веб-сервиса и в параметре Name передайте имя контакта.

http://myсreatio.com/0/rest/UsrCustomConfigurationService/GetContactIdByName?Name=Andrew%20Baker

При обращении к веб-сервису без предварительной авторизации возникнет ошибка.

Авторизуйтесь в приложении и выполните запрос еще раз. Если контакт, указанный в параметре Name, найден в базе данных, то в свойстве GetContactIdByNameResult будет возвращено значение идентификатора контакта.

Если контакт, указанный в параметре Name, не найден в базе данных, то в свойстве GetContactIdByNameResult будет возвращена пустая строка.

http://myсreatio.com/0/rest/UsrCustomConfigurationService/GetContactIdByName?Name=Andrew%20Bake

1. Создать схему Исходный код 

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

2. На панели инструментов реестра раздела нажмите Добавить —> Исходный код (Add —> Source code).

   

3. В дизайнере схем заполните свойства схемы:

   • Код (Code) — "UsrAnonymousConfigurationService".
   • Заголовок (Title) — "AnonymousConfigurationService".
   

   Для применения заданных свойств нажмите Применить (Apply).

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

1. В дизайнере схем добавьте пространство имен, вложенное в Terrasoft.Configuration. Название может быть любым, например, UsrAnonymousConfigurationServiceNamespace.
2. C помощью директивы using добавьте пространства имен, типы данных которых будут задействованы в классе.
3. Добавьте название класса, которое соответствует названию схемы (свойство Код (Code)).
4. В качестве родительского класса укажите класс Terrasoft.Nui.ServiceModel.WebService.BaseService.
5. Для класса добавьте атрибуты [ServiceContract] и [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)].
6. Для анонимного доступа к пользовательскому веб-сервису добавьте системное подключение SystemUserConnection.

3. Реализовать метод класса 

В дизайнере схем добавьте в класс метод public string GetContactIdByName(string Name), который реализует конечную точку пользовательского веб-сервиса. С помощью EntitySchemaQuery метод отправит запрос к базе данных. В зависимости от значения параметра Name, отправленного в строке запроса, тело ответа на запрос будет содержать:

• Идентификатор контакта (типа строка) — если контакт найден.
• Идентификатор первого найденного контакта (типа строка) — если найдено несколько контактов.
• Пустую строку — если контакт не найден.

Укажите пользователя, от имени которого будет выполняться обработка данного http-запроса. Для этого после получения SystemUserConnection вызовите метод SessionHelper.SpecifyWebOperationIdentity пространства имен Terrasoft.Web.Common. Этот метод обеспечивает работоспособность бизнес-процессов при работе с сущностью (Entity) базы данных из пользовательского веб-сервиса с анонимной аутентификацией.

Terrasoft.Web.Common.SessionHelper.SpecifyWebOperationIdentity(HttpContextAccessor.GetInstance(), SystemUserConnection.CurrentUser);

Исходный код пользовательского веб-сервиса UsrAnonymousConfigurationService представлен ниже.

/* Пользовательское пространство имен. */
namespace Terrasoft.Configuration.UsrAnonymousConfigurationServiceNamespace
{
    using System;
    using System.ServiceModel;
    using System.ServiceModel.Web;
    using System.ServiceModel.Activation;
    using Terrasoft.Core;
    using Terrasoft.Web.Common;
    using Terrasoft.Core.Entities; 

    [ServiceContract]
    [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]
    public class UsrAnonymousConfigurationService: BaseService
    {
        /* Ссылка на экземпляр UserConnection, требуемый для обращения к базе данных. */
        private SystemUserConnection _systemUserConnection;
        private SystemUserConnection SystemUserConnection {
            get {
                return _systemUserConnection ?? (_systemUserConnection = (SystemUserConnection)AppConnection.SystemUserConnection);
            }
        }
        
        /* Метод, возвращающий идентификатор контакта по имени контакта. */
        [OperationContract]
        [WebInvoke(Method = "GET", RequestFormat = WebMessageFormat.Json, BodyStyle = WebMessageBodyStyle.Wrapped,
        ResponseFormat = WebMessageFormat.Json)]
        public string GetContactIdByName(string Name){
            /* Указывается пользователь, от имени которого выполняется обработка данного http-запроса. */
            SessionHelper.SpecifyWebOperationIdentity(HttpContextAccessor.GetInstance(), SystemUserConnection.CurrentUser);
            /* Результат по умолчанию. */
            var result = "";
            /* Экземпляр EntitySchemaQuery, обращающийся в таблицу Contact базы данных. */
            var esq = new EntitySchemaQuery(SystemUserConnection.EntitySchemaManager, "Contact");
            /* Добавление колонок в запрос. */
            var colId = esq.AddColumn("Id");
            var colName = esq.AddColumn("Name");
            //* Фильтрация данных запроса. */
            var esqFilter = esq.CreateFilterWithParameters(FilterComparisonType.Equal, "Name", Name);
            esq.Filters.Add(esqFilter);
            /* Получение результата запроса. */
            var entities = esq.GetEntityCollection(SystemUserConnection);
            /* Если данные получены. */
            if (entities.Count > 0)
            {
                /* Возвратить значение колонки "Id" первой записи результата запроса. */
                result = entities[0].GetColumnValue(colId.Name).ToString();
                /* Также можно использовать такой вариант:
                result = entities[0].GetTypedColumnValue<string>(colId.Name); */
            }
            /* Возвратить результат. */
            return result;
        }
    }
}

На панели инструментов дизайнера нажмите Сохранить (Save), а затем Опубликовать (Publish).

4. Зарегистрировать пользовательский веб-сервис с анонимной аутентификацией 

1. Перейдите в каталог ..\Terrasoft.WebApp\ServiceModel.

2. Создайте файл UsrAnonymousConfigurationService.svc и добавьте в него запись.

   <% @ServiceHost
       Service = "Terrasoft.Configuration.UsrAnonymousConfigurationServiceNamespace.UsrAnonymousConfigurationService"
       Debug = "true"
       Language = "C#"
   %>
   

   Атрибут Service содержит полное имя класса веб-сервиса с указанием пространства имен.

5. Настроить пользовательский веб-сервис с анонимной аутентификацией для работы по протоколам http и https 

1. Откройте файл ..\Terrasoft.WebApp\ServiceModel\http\services.config и добавьте в него запись.

   Файл ..\Terrasoft.WebApp\ServiceModel\http\services.config

   <services>
       ...
       <service name="Terrasoft.Configuration.UsrAnonymousConfigurationServiceNamespace.UsrAnonymousConfigurationService">
           <endpoint name="[Service name]EndPoint"
               address=""
               binding="webHttpBinding"
               behaviorConfiguration="RestServiceBehavior"
               bindingNamespace="http://Terrasoft.WebApp.ServiceModel"
               contract="Terrasoft.Configuration.UsrAnonymousConfigurationServiceNamespace.UsrAnonymousConfigurationService" />
       </service>
   </services>
   

2. Аналогичную запись добавьте в файл ..\Terrasoft.WebApp\ServiceModel\https\services.config.

6. Настроить доступ к пользовательскому веб-сервису с анонимной аутентификацией для всех пользователей 

1. Откройте файл ..\Terrasoft.WebApp\Web.config.

2. Добавьте элемент <location>, определяющий относительный путь и права доступа к веб-сервису.

   Файл ..\Terrasoft.WebApp\Web.config

   <configuration>
       ...
       <location path="ServiceModel/UsrAnonymousConfigurationService.svc">
           <system.web>
               <authorization>
                   <allow users="*" />
               </authorization>
           </system.web>
       </location>
       ...
   </configuration>
   

3. В атрибут value ключа AllowedLocations элемента <appSettings> добавьте относительный путь к веб-сервису.

   Файл ..\Terrasoft.WebApp\Web.config

   <configuration>
       ...
       <appSettings>
       ...
           <add key="AllowedLocations" value="[Предыдущие значения];ServiceModel/UsrAnonymousConfigurationService.svc"  />
       ...
       </appSettings>
       ...
   </configuration>
   

7. Перезапустить приложение в IIS 

Для применения изменений перезапустите приложение в IIS.

Результат выполнения примера 

В результате выполнения примера в Creatio появится пользовательский веб-сервис UsrAnonymousConfigurationService с конечной точкой GetContactIdByName. К веб-сервису можно обращаться из браузера, как с предварительным вводом логина и пароля, так и без их использования.

Из браузера обратитесь к конечной точке GetContactIdByName веб-сервиса и в параметре Name передайте имя контакта.

http://myсreatio.com/0/ServiceModel/UsrAnonymousConfigurationService/GetContactIdByName?Name=Andrew%20Baker

Если контакт, указанный в параметре Name, найден в базе данных, то в свойстве GetContactIdByNameResult будет возвращено значение идентификатора контакта.

Если контакт, указанный в параметре Name, не найден в базе данных, то в свойстве GetContactIdByNameResult будет возвращена пустая строка.

http://myсreatio.com/0/ServiceModel/UsrAnonymousConfigurationService/GetContactIdByName?Name=Andrew%20Bake

1. Создать схему Исходный код 

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

2. На панели инструментов реестра раздела нажмите Добавить —> Исходный код (Add —> Source code).

   

3. В дизайнере исходного кода заполните свойства схемы:

   • Код (Code) — "UsrEncodingService".
   • Заголовок (Title) — "Сервис с нестандартной кодировкой" ("Service with custom encoding").
   

   Для применения заданных свойств нажмите Применить (Apply).

2. Создать класс веб-сервиса 

1. В дизайнере схем добавьте пространство имен, которое вложено в Terrasoft.Configuration. Например, UsrEncodingServiceNamespace.
2. C помощью директивы using добавьте пространства имен, типы данных которых задействованы в классе.
3. Добавьте название класса, которое соответствует названию схемы (свойство Код (Code)).
4. В качестве родительского класса укажите класс Terrasoft.Nui.ServiceModel.WebService.BaseService.
5. Для класса добавьте атрибуты [ServiceContract] и [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)].
6. Для анонимного доступа к пользовательскому веб-сервису добавьте системное подключение SystemUserConnection.

3. Реализовать метод класса веб-сервиса 

1. Реализуйте конечную точку пользовательского веб-сервиса. Для этого в дизайнере исходного кода добавьте в класс метод public string Test(string Name). В зависимости от значения параметра Name, которое указано в текстовой кодировке ISO-8859-1 и отправляется в строке запроса, тело ответа на запрос содержит значение этого же параметра в той же кодировке.

2. Укажите пользователя, от имени которого выполняется обработка текущего http-запроса. Для этого после получения SystemUserConnection вызовите метод SessionHelper.SpecifyWebOperationIdentity пространства имен Terrasoft.Web.Common. Этот метод обеспечивает работоспособность бизнес-процессов при работе с сущностью (Entity) базы данных из пользовательского веб-сервиса с анонимной аутентификацией.

   Terrasoft.Web.Common.SessionHelper.SpecifyWebOperationIdentity(HttpContextAccessor.GetInstance(), SystemUserConnection.CurrentUser);
   

Исходный код пользовательского веб-сервиса UsrEncodingService представлен ниже.

/* Пользовательское пространство имен. */
namespace Terrasoft.Configuration.UsrEncodingServiceNamespace
{
    using System;
    using System.ServiceModel;
    using System.ServiceModel.Web;
    using System.ServiceModel.Activation;
    using Terrasoft.Core;
    using Terrasoft.Web.Common;
    using Terrasoft.Core.Entities;

    [ServiceContract]
    [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]
    public class UsrEncodingService: BaseService
    {
        /* Ссылка на экземпляр UserConnection, который требует для обращения к базе данных. */
        private SystemUserConnection _systemUserConnection;
        private SystemUserConnection SystemUserConnection {
            get {
                return _systemUserConnection ?? (_systemUserConnection = (SystemUserConnection)AppConnection.SystemUserConnection);
            }
        }
        
        /* Метод, который возвращает значение переданного параметра в указанной кодировке. */
        [OperationContract]
        [WebInvoke(Method = "POST", RequestFormat = WebMessageFormat.Xml, BodyStyle = WebMessageBodyStyle.Wrapped, ResponseFormat = WebMessageFormat.Xml)]
        public string Test(string Name){
            /* Указывает пользователя, от имени которого выполняется обработка данного http-запроса. */
            SessionHelper.SpecifyWebOperationIdentity(HttpContextAccessor.GetInstance(), SystemUserConnection.CurrentUser);
            /* Возвращает результат. */
            return Name;
        }
    }
}

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

4. Зарегистрировать веб-сервис 

1. В каталоге ..\Terrasoft.WebApp\ServiceModel создайте файл UsrEncodingService.svc.

2. В файл UsrEncodingService.svc добавьте запись.

   <% @ServiceHost
       Service = "Terrasoft.Configuration.UsrEncodingServiceNamespace.UsrEncodingService"
       Debug = "true"
       Language = "C#"
   %>
   

   Атрибут Service содержит полное имя класса веб-сервиса с указанием пространства имен.

3. Сохраните файл.

5. Зарегистрировать нестандартную текстовую кодировку 

1. В файл ..\Terrasoft.WebApp\ServiceModel\http\bindings.config добавьте секцию <customBinding>.

2. В секцию <customBinding> добавьте атрибуты:

   • name элемента <binding> — "ISO88591Encoding".
   • encoding элемента <customTextMessageEncoding> — "ISO-8859-1".
   • manualAddressing элемента <httpTransport> — "true".
   Файл ..\Terrasoft.WebApp\ServiceModel\http\bindings.config

   <bindings>
       ...
       <customBinding>
           <binding name="ISO88591Encoding">
               <customTextMessageEncoding encoding="ISO-8859-1" />
               <httpTransport manualAddressing="true"/>
           </binding>
           ...
       </customBinding>
   </bindings>
   

3. Сохраните файл.
4. В файл ..\Terrasoft.WebApp\ServiceModel\https\bindings.config добавьте аналогичную запись.

6. Настроить веб-сервис для работы по протоколам http и https 

1. В файл ..\Terrasoft.WebApp\ServiceModel\http\services.config добавьте запись.

   Файл ..\Terrasoft.WebApp\ServiceModel\http\services.config

   <services>
       ...
       <service name="Terrasoft.Configuration.UsrEncodingServiceNamespace.UsrEncodingService">
           <endpoint name="UsrEncodingServiceEndPoint"
               address=""
               binding="customBinding"
               bindingConfiguration="ISO88591Encoding"
               behaviorConfiguration="RestServiceBehavior"
               bindingNamespace="http://Terrasoft.WebApp.ServiceModel"
               contract="Terrasoft.Configuration.UsrEncodingServiceNamespace.UsrEncodingService" />
       </service>
   </services>
   

   Атрибут binding содержит значение "<customBinding>", которое соответствует названию секции <customBinding> с регистрацией текстовой кодировки.

   Атрибут bindingConfiguration содержит название зарегистрированной текстовой кодировки. Совпадает со значением атрибута name элемента <binding>, который задан на предыдущем шаге.

2. Сохраните файл.
3. В файл ..\Terrasoft.WebApp\ServiceModel\https\services.config добавьте аналогичную запись.

7. Настроить доступ к веб-сервису для всех пользователей 

1. В файл ..\Terrasoft.WebApp\Web.config добавьте элемент <location>, который определяет относительный путь и права доступа к веб-сервису.

   Файл ..\Terrasoft.WebApp\Web.config

   <configuration>
       ...
       <location path="ServiceModel/UsrEncodingService.svc">
           <system.web>
               <authorization>
                   <allow users="*" />
               </authorization>
           </system.web>
       </location>
       ...
   </configuration>
   

2. В файле ..\Terrasoft.WebApp\Web.config в атрибут value ключа AllowedLocations элемента <appSettings> добавьте относительный путь к веб-сервису.

   Файл ..\Terrasoft.WebApp\Web.config

   <configuration>
       ...
       <appSettings>
       ...
           <add key="AllowedLocations" value="[Предыдущие значения];ServiceModel/UsrEncodingService.svc"  />
       ...
       </appSettings>
       ...
   </configuration>
   

3. Сохраните файл.

8. Перезапустить приложение в IIS 

Для применения изменений перезапустите приложение в IIS.

Результат выполнения примера 

Для демонстрации результата выполнения примера используем инструмент тестирования запросов Postman. Работа с Postman описана в официальной документации Postman. Инструкция по использованию Postman для выполнения запросов к Creatio содержится в статье Выполнить запрос к Creatio в Postman. Инструкция по использованию Postman для вызова веб-сервиса содержится в статье Вызвать пользовательский веб-сервис с помощью Postman.

Чтобы посмотреть результат выполнения примера, выполните запрос к веб-сервису UsrEncodingService.

Настройки запроса, которые необходимо установить в Postman:

• Метод запроса: POST.

• Строка запроса к методу Test пользовательского веб-сервиса UsrEncodingService.

  Строка запроса к веб-сервису UsrEncodingService

  http://myсreatio.com/0/ServiceModel/UsrEncodingService.svc/Test
  

• Формат данных запроса (настраивается на вкладке Body).

  1. Установите опцию "raw".
  2. Выберите тип "XML".
  3. Заполните тело POST запроса. В теле запроса передайте символы в текстовой кодировке ISO-8859-1. О символах, которые используются в текстовой кодировке ISO-8859-1, читайте в Википедии.
  

В результате выполнения примера получен ответ на POST запрос. Формат ответа — XML, код — 200 OK. Тело ответа отображается на вкладке Body и содержит значение параметра Name тела запроса в текстовой кодировке ISO-8859-1.

1. Создать пользовательский веб-сервис 

В примере используется пользовательский веб-сервис UsrCustomConfigurationService, разработка которого описана в статье Разработать пользовательский веб-сервис с аутентификацией на основе cookies.

В веб-сервисе UsrCustomConfigurationService измените параметр Method атрибута WebInvoke на POST.

Исходный код пользовательского веб-сервиса, используемого в примере, представлен ниже.

namespace Terrasoft.Configuration.UsrCustomConfigurationServiceNamespace
{
    using System;
    using System.ServiceModel;
    using System.ServiceModel.Web;
    using System.ServiceModel.Activation;
    using Terrasoft.Core;
    using Terrasoft.Web.Common;
    using Terrasoft.Core.Entities; 

    [ServiceContract]
    [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]
    public class UsrCustomConfigurationService: BaseService
    {
        
        /* Метод, возвращающий идентификатор контакта по имени контакта. */
        [OperationContract]
        [WebInvoke(Method = "POST", RequestFormat = WebMessageFormat.Json, BodyStyle = WebMessageBodyStyle.Wrapped,
        ResponseFormat = WebMessageFormat.Json)]
        public string GetContactIdByName(string Name) {
            /* Результат по умолчанию. */
            var result = "";
            /* Экземпляр EntitySchemaQuery, обращающийся в таблицу Contact базы данных. */
            var esq = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "Contact");
            /* Добавление колонок в запрос. */
            var colId = esq.AddColumn("Id");
            var colName = esq.AddColumn("Name");
            /* Фильтрация данных запроса. */
            var esqFilter = esq.CreateFilterWithParameters(FilterComparisonType.Equal, "Name", Name);
            esq.Filters.Add(esqFilter);
            /* Получение результата запроса. */
            var entities = esq.GetEntityCollection(UserConnection);
            /* Если данные получены. */
            if (entities.Count > 0)
            {
                /* Возвратить значение колонки "Id" первой записи результата запроса. */
                result = entities[0].GetColumnValue(colId.Name).ToString();
                /* Также можно использовать такой вариант:
                result = entities[0].GetTypedColumnValue<string>(colId.Name); */
            }
            /* Возвратить результат. */
            return result;
        }
    }
}

2. Создать замещающую страницу записи контакта 

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

2. На панели инструментов реестра раздела нажмите Добавить —> Замещающая модель представления (Add —> Replacing view model).

   

3. В свойстве Родительский объект (Parent object) выберите схему модели представления Схема отображения карточки контакта (Display schema — Contact card) пакета ContactPageV2, которую необходимо заместить. После подтверждения выбранного родительского объекта остальные свойства будут заполнены автоматически.

   
4. В объявлении модуля страницы записи в качестве зависимости подключите модуль ServiceHelper. Зависимости модуля описаны в статье Функция define().

3. Добавить кнопку на страницу записи контакта 

1. В блоке Локализуемые строки (Localizable strings) панели свойств нажмите кнопку и заполните свойства локализуемой строки:

   • Код (Code) — "GetServiceInfoButtonCaption".
   • Значение (Value) — "Вызвать сервис" ("Call service").

2. Добавьте обработчик кнопки.

   Для вызова веб-сервиса воспользуйтесь методом callService() модуля ServiceHelper. Параметры функции callService(), которые необходимо передать:

   • UsrCustomConfigurationService — имя класса пользовательского веб-сервиса.
   • GetContactIdByName — имя вызываемого метода пользовательского веб-сервиса.
   • Функцию обратного вызова, в которой выполните обработку результатов сервиса.
   • serviceData — объект с проинициализированными входящими параметрами для метода пользовательского веб-сервиса.
   • Контекст выполнения.

   Исходный код схемы замещающей модели представления ContactPageV2 представлен ниже.

   ContactPageV2

   define("ContactPageV2", ["ServiceHelper"],
   function(ServiceHelper) {
       return {
           /* Название схемы объекта страницы записи. */
           entitySchemaName: "Contact",
           details: /**SCHEMA_DETAILS*/{}/**SCHEMA_DETAILS*/,
           /* Методы модели представления страницы записи. */
           methods: {
               /* Проверяет, заполнено ли поле [ФИО] страницы. */
               isContactNameSet: function() {
                   return this.get("Name") ? true : false;
               },
               /* Метод-обработчик нажатия кнопки. */
               onGetServiceInfoClick: function() {
                   var name = this.get("Name");
                   /* Объект, инициализирующий входящие параметры для метода сервиса. */
                   var serviceData = { 
                       /* Название свойства совпадает с именем входящего параметра метода сервиса. */
                       Name: name
                   };
                   /*/ Вызов веб-сервиса и обработка результатов. */
                   ServiceHelper.callService("UsrCustomConfigurationService", "GetContactIdByName",
                       function(response) {
                           var result = response.GetContactIdByNameResult;
                           this.showInformationDialog(result);
                       }, serviceData, this);
               }
           },
           diff: /**SCHEMA_DIFF*/[
               /* Метаданные для добавления на страницу пользовательской кнопки. */
               {
                   /* Выполняется операция добавления элемента на страницу. */
                   "operation": "insert",
                   /* Имя родительского элемента управления, в который добавляется кнопка. */
                   "parentName": "LeftContainer",
                   /* Кнопка добавляется в коллекцию элементов управления родительского элемента, мета-имя которого указано в parentName. */
                   "propertyName": "items",
                   /* Имя добавляемой кнопки. */
                   "name": "GetServiceInfoButton", 
                   /* Дополнительные свойства поля. */
                   "values": {
                       /* Тип добавляемого элемента - кнопка. */
                       itemType: Terrasoft.ViewItemType.BUTTON,
                       /* Привязка заголовка кнопки к локализуемой строке схемы. */
                       caption: {bindTo: "Resources.Strings.GetServiceInfoButtonCaption"},
                       /* Привязка метода-обработчика нажатия кнопки. */
                       click: {bindTo: "onGetServiceInfoClick"},
                       /* Привязка свойства доступности кнопки. */
                       enabled: {bindTo: "isContactNameSet"},
                       /* Настройка расположения поля. */
                       "layout": {"column": 1, "row": 6, "colSpan": 2, "rowSpan": 1}
                   }
               }
           ]/**SCHEMA_DIFF*/
       };
   });
   

3. На панели инструментов дизайнера нажмите Сохранить (Save).

Результат выполнения примера 

В результате выполнения примера после обновления страницы приложения на странице контакта появится кнопка Вызвать сервис (Call service). При нажатии на эту кнопку вызывается метод GetContactIdByName пользовательского веб-сервиса UsrCustomConfigurationService, который возвращает значение идентификатора текущего контакта.

Для интеграции внешних приложений с пользовательскими веб-сервисами Creatio необходимо выполнять HTTP-запросы к этим сервисам. Для понимания принципа формирования запросов удобно использовать такие инструменты редактирования и отладки, как Postman или Fiddler.

Postman — это набор инструментов для тестирования запросов. Назначение Postman — тестирование отправки запросов с клиента на сервер и получения ответа от сервера. В этой статье рассмотрен пример вызова пользовательского веб-сервиса с аутентификацией на основе cookies с помощью Postman.

В примере используется пользовательский веб-сервис UsrCustomConfigurationService, разработка которого описана в статье Разработать пользовательский веб-сервис с аутентификацией на основе cookies.

Поскольку в примере используется пользовательский веб-сервис с аутентификацией на основе cookies, то предварительно необходимо выполнить аутентификацию в приложении, выполнив запрос к системному веб-сервису AuthService.svc. Описание аутентификации содержится в статье Аутентификация.

1. Создать коллекцию запросов 

1. На панели работы с запросами в Postman перейдите на вкладку Collections и нажмите + New Collection.

   

2. Заполните поля коллекции запросов:

   • Name — "Test configuration web service".

     
3. Чтобы создать коллекцию запросов, нажмите Create.

2. Настроить аутентификационный запрос 

1. На панели работы с запросами в Postman правой кнопкой мыши кликните по имени коллекции Test configuration web service —> Add request.

2. Заполните поля запроса:

   • Request name — "Authentication".

     
3. Чтобы добавить запрос в коллекцию, нажмите Save to Test configuration web service.

4. В выпадающем списке панели инструментов рабочей области Postman выберите метод запроса POST.

   

5. В поле запроса панели инструментов рабочей области Postman введите строку запроса к сервису аутентификации.

   [Адрес приложения Creatio]/ServiceModel/AuthService.svc/Login
   

   http://myсreatio.com/creatio/ServiceModel/AuthService.svc/Login
   

6. Установите формат данных запроса:

   1. Перейдите на вкладку Body.
   2. Установите опцию "raw".

   3. Выберите тип "JSON".

      

7. В рабочей области Postman перейдите на вкладку Body и заполните тело POST-запроса — JSON-объект, который содержит аутентификационные данные (логин и пароль).

   Тело POST-запроса

   {
       "UserName": "User01", 
       "UserPassword":"User01"
   }
   

3. Выполнить аутентификационный запрос 

Чтобы выполнить запрос в Postman, на панели инструментов рабочей области нажмите Send.

В результате выполнения запроса будет получен ответ, который содержит JSON-объект. Тело ответа отображается на вкладке Body в Postman.

Признаки успешного выполнения запроса:

• Получен код состояния 200 OK.
• Параметр Code тела ответа содержит значение "0".

Ответ на запрос также содержит cookie BPMLOADER, .ASPXAUTH, BPMCSRF и UserName, которые отображаются на вкладке Cookies, а также продублированы на вкладке Headers в Postman.

Эти cookie необходимо использовать в дальнейших запросах к сервисам Creatio, которые используют аутентификацию на основе cookies.

При включенной защите от CSRF-атак использование cookie BPMCSRF является обязательным для методов (POST, PUT, DELETE) запросов, которые модифицируют (добавляют, изменяют или удаляют) сущность. Если cookie BPMCSRF не будет использован, то сервер вернет код состояния 403 Forbidden. Для GET-запросов проверка cookie BPMCSRF не выполняется. Для демо-сайтов Creatio использование cookie BPMCSRF необязательно, поскольку защита от CSRF-атак по умолчанию отключена.

Запрос выполняется неуспешно, если была допущена ошибка при построении запроса или тела запроса.

Признаки неуспешного выполнения запроса:

• Параметр Code тела ответа содержит значение "1".
• Параметр Message тела ответа содержит описание причины неуспешной аутентификации.

4. Настроить запрос к пользовательскому веб-сервису с аутентификацией на основе cookies 

Пользовательский веб-сервис UsrCustomConfigurationService работает с запросами только по методу GET.

Чтобы настроить запрос к пользовательскому веб-сервису с аутентификацией на основе cookies:

1. На панели работы с запросами в Postman правой кнопкой мыши кликните по имени коллекции Test configuration web service —> Add request.

2. Заполните поля запроса:

   • Request name — "Configuration web service".

     
3. Чтобы добавить запрос в коллекцию, нажмите Save to Test configuration web service.

4. По умолчанию в Postman выбран метод GET. В поле запроса панели инструментов рабочей области Postman введите строку запроса к пользовательскому веб-сервису UsrCustomConfigurationService.

   [Адрес приложения Creatio]/0/rest/UsrCustomConfigurationService/GetContactIdByName?Name=[Имя контакта]
   

   http://myсreatio.com/creatio/0/rest/UsrCustomConfigurationService/GetContactIdByName?Name=Andrew Baker
   

5. В рабочей области Postman перейдите на вкладку Headers и в заголовки запроса к пользовательскому веб-сервису добавьте cookie, полученные в ответ на авторизационный запрос. В поле Key добавьте имя cookie, а в поле Value скопируйте соответствующее значение cookie.

   

5. Выполнить запрос к пользовательскому веб-сервису с аутентификацией на основе cookies 

Чтобы выполнить запрос в Postman, на панели инструментов рабочей области нажмите Send.

Результат выполнения примера 

В результате выполнения запроса будет получен ответ, который содержит JSON-объект. Тело ответа отображается на вкладке Body в Postman.

Если контакт, указанный в параметре Name, найден в базе данных, то в свойстве GetContactIdByNameResult будет возвращено значение идентификатора контакта.

Если контакт, указанный в параметре Name, не найден в базе данных, то в свойстве GetContactIdByNameResult будет возвращена пустая строка.