Документация по разработке bpm’online

Запуск процессов bpm'online через веб-сервис

Glossary Item Box

Общая информация

Одной из задач интеграции внешнего приложения с bpm'online является выполнение каких-либо действий в системе, в том числе запуск бизнес-процессов. С этой целью в сервисной модели bpm'online реализован сервис ProcessEngineService.svc, позволяющий извне запускать бизнес-процессы в системе.

Адрес веб-сервиса ProcessEngineService.svc

http[s]://<адрес_приложения_bpm'online>/0/ServiceModel/ProcessEngineService.svc"

Методы веб–сервиса ProcessEngineService

Запуск бизнес-процесса

Чтобы запустить в системе определенный бизнес-процесс, необходимо вызвать метод Execute сервиса ProcessEngineService.  

Вызов метода Execute можно выполнять с помощью HTTP-запросов GET и POST.

Общий формат вызова метода Execute:

http[s]://<адрес_приложения_bpm'online>/0/ServiceModel/ProcessEngineService.svc/PROCESSSCHEMANAME/Execute[?<опциональные входящие параметры бизнес–процесса>]

где

PROCESSSCHEMANAME — название процесса (схемы процесса) в системе.

Пример

В данном примере выполняется запуск процесса с названием SomeBusinessProcess. Процессу передается один параметр procParam со значением 15.

.../0/ServiceModel/ProcessEngineService.svc/SomeBusinessProcess/Execute?procParam=15

Сервис ProcessEngineService.svc позволяет запустить определенный бизнес-процесс и получить результат выполнения этого процесса через заданный параметр. Для этого необходимо вызвать метод Execute в следующем формате:

http[s]://<адрес_приложения_bpm'online>/0/ServiceModel/ProcessEngineService.svc/PROCESSSCHEMANAME/Execute?ResultParameterName=RESULTPARAMETERNAME[&<опциональные входящие параметры бизнес процесса>]

где

  • PROCESSSCHEMANAME — название процесса (схемы процесса), экземпляр которого необходимо запустить на выполнение;
  • RESULTPARAMETERNAME — имя параметра процесса, который хранит результат выполнения процесса. Если этот параметр не задан, то веб-сервис запустит указанный бизнес-процесс без ожидания результата его выполнения.

Пример

В данном примере выполняется запуск процесса CustomProcess. Результат выполнения процесса хранится в исходящем параметре процесса CustomProcessResult и возвращается в запросе. Дополнительно в процесс CustomProcess передается параметр incomeParam со значением "IncomeParamValue":

.../0/ServiceModel/ProcessEngineService.svc/CustomProcess/Execute?ResultParameterName=CustomProcessResult&incomeParam=IncomeParamValue

Результат выполнения метода Execute возвращается в виде строки, содержащей JSON-сериализованное значение произвольного типа данных (допустимо получение значения null). Десериализация и приведение полученного результата к определенному типу данных должно выполняться в коде, вызывающем веб-сервис. 

Если параметр с именем RESULTPARAMETERNAME отстутствует в вызываемом процессе, веб-сервис вернет значение null.

Запуск на выполнение отдельного элемента бизнес-процесса

Для того чтобы запустить на выполнение отдельный элемент бизнес-процесса, необходимо вызывать метод ExecProcElByUId сервиса ProcessEngineService.svc. В качестве параметра данный метод принимает идентификатор запускаемого элемента процесса.

Формат вызова метода ExecProcElByUId следующий:

http[s]://<адрес_приложения_bpm'online>/0/ServiceModel/ProcessEngineService.svc/ExecProcElByUId/PROCELUID

где:

PROCELUID — идентификатор запускаемого элемента процесса.

ВАЖНО

  • Запускать на выполнение можно только элемент выполняющегося процесса.
  • Если запускаемый методом ExecProcElByUId элемент процесса уже выполнен на момент вызова метода, то этот элемент не будет выполняться повторно.

Пример запуска бизнес-процессов bpm'online из внешнего приложения

Для реализации примера запуска процессов bpm'online через веб-сервис ProcessEngineService.svc необходимо выполнить следующие действия:

1) Создать демонстрационные процессы в bpm'online:

  • AddNewContact — процесс, добавляющий новый контакт в систему. Имеет два входящих параметра:
    • ContactName — имя контакта.
    • ContactPhone — телефон контакта.
  • GetAllBpmContacts — процесс, формирующий список всех контактов системы. Имеет один исходящий параметр ContactList, в котором сохраняется сформированный список контактов системы, и через который внешнее приложение может получить доступ к этому списку.

2) Создать клиентский класс, в котором реализовать всю логику работы с веб-сервисом ProcessEngineServise.svc:

  • Реализовать логику аутентификации пользователя через аутентификационный сервис AuthService.svc.
  • Реализовать вызов методов веб-сервиса ProcessEngineService.svc для запуска процессов.

3) Использовать методы клиентского класса в приложении для запуска бизнес-процессов в системе и получения результатов их выполнения.

Создание бизнес-процессов в bpm'online

Процесс AddNewExternalContact

Бизнес-процесс AddNewExternalContact добавляет новый контакт в систему.

Процесс содержит один элемент ScriptTask, в котором реализуется логика добавления контакта в систему (рис. 1, рис. 2).

Рис. 1. — Свойства бизнес-процесса AddNewExternalContact

 

Рис. 2. — Общий вид бизнес-процесса AddNewExternalContact в дизайнере процессов

Бизнес-процесс содержит два параметра, через которые в процесс передаются реквизиты контакта — его имя и телефон:

  • ContactName — входящий параметр типа Объект(Entity), содержащий имя добавляемого контакта.
  • ContactPhone — входящий параметр типа Объект(Entity), содержащий телефон добавляемого контакта.

Логика добавления нового контакта в систему реализуется в элементе процесса — скрипте "Добавить контакт в систему" (рис.3).

Рис. 3. — Свойства скрипта "Добавить контакт в систему"

 

Код скрипта AddContact:

// Создание экземпляра схемы объекта "Контакт".
var schema = UserConnection.EntitySchemaManager.GetInstanceByName("Contact");
// Создание экземпляра нового объекта.
var entity = schema.CreateEntity(UserConnection);
// Установка значений по умолчанию для колонок объекта.
entity.SetDefColumnValues();
// Установка значения колонки "Name" из параметра процесса.
entity.SetColumnValue("Name", ContactName);
// Установка значения колонки "Phone" из параметра процесса.
entity.SetColumnValue("Phone", ContactPhone);
// Сохранение нового контакта.
entity.Save();
return true; 

Процесс GetAllBpmContacts

Бизнес-процесс GetAllBpmContacts формирует список всех контактов системы для текущего пользователя.

Процесс содержит один элемент ScriptTask, в котором реализуется логика выборки списка контактов (рис. 4, рис. 5).

Рис. 4. — Свойства бизнес-процесса GetAllBpmContacts

Рис. 5. — Общий вид бизнес-процесса GetAllBbpContacts в дизайнере процессов

 

Процесс GetAllBpmContacts имеет один параметр:

  • ContactList — исходящий параметр типа Объект(Entity), через который процесс будет возвращать список всех контактов системы.

Логика выборки списка контактов реализуется в элементе процесса — скрипте "Получение списка всех контактов системы" (рис.6).

Рис. 6. — Свойства скрипта "Получение списка всех контактов системы"

Код скрипта GetContacts:

// В скрипте создается экземпляр EntitySchemaQuery, выбирающий коллекцию контактов (имя и телефон). 
// Данная коллекция помещается в исходящий параметр ContactList.
EntitySchemaQuery query = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "Contact");
// Устанавливается признак для обязательного выбора первичной колонки (Id).
query.PrimaryQueryColumn.IsAlwaysSelect = true;
// Добавление в запрос колонки Name.
query.AddColumn("Name");
// Добавление в запрос колонки Phone.
query.AddColumn("Phone");
// Получение результирующей коллекции объектов.
var list = query.GetEntityCollection(UserConnection);
// Формирование списка контактов.
List<object> contacts = new List<object>();
foreach (var item in list)
{
    var contact = new
    {
        Id = item.GetTypedColumnValue<Guid>("Id"),
        Name = item.GetTypedColumnValue<string>("Name"),
        Phone = item.GetTypedColumnValue<string>("Phone")
    };
    contacts.Add(contact);
}
// Сохранение результирующей коллекции контактов в исходящий параметр ContactList процесса.
ContactList = contacts;
return true;  

Клиентский класс, реализующий логику работы с веб-сервисом ProcessEngineService.svc

public class BPMonlineProcessEngineExample
{
    private const string processServiceUri = 
            "<адрес приложения bpm'online>/0/ServiceModel/ProcessEngineService.svc/";
    private const string authServiceUri = 
            "<адрес приложения bpm'online>/ServiceModel/AuthService.svc/Login";

    // Cookie аутентификации bpm'online.
    private static CookieContainer AuthCookie = new CookieContainer();

    // Признак, прошла ли аутентификация пользователя на сервере bpm'online.
    // Если аутентификация прошла успешно, в свойстве AuthCookie будут лежать 
    // аутентификационные cookie, сформированные сервисом.
    public static bool IsAuthentificated
    {
        get { return (AuthCookie != null); }
    }

    // Метод для аутентификации запроса к веб-сервису bpm'online.
    // Параметры:
    // userName - имя пользователя bpm'online,
    // userPassword - пароль пользователя bpm'online.
    public static bool TryLogin(string userName, string userPassword)
    {
        // Создание экземпляра запроса к сервису аутентификации.
        var authRequest = HttpWebRequest.Create(authServiceUri) as HttpWebRequest;
        // Определение метода запроса.
        authRequest.Method = "POST";
        // Определение типа контента запроса.
        authRequest.ContentType = "application/json";

        // Включение использования cookie в запросе.
        authRequest.CookieContainer = AuthCookie;

        // Помещение в тело запроса учетной информации пользователя.
        using (var requesrStream = authRequest.GetRequestStream())
        {
            using (var writer = new StreamWriter(requesrStream))
            {
                writer.Write(@"{
                    ""UserName"":""" + userName + @""",
                    ""UserPassword"":""" + userPassword + @"""
                }");
            }
        }
        // Получение ответа от сервера. Если аутентификация проходит успешно, в свойство AuthCookie будут 
        // помещены cookie, которые могут быть использованы для последующих запросов.
        using (var response = (HttpWebResponse)authRequest.GetResponse())
        {
            if (AuthCookie.Count > 0)
            {
                return true;
            }
        }
        return false;
    }

    // Метод запускает процесс AddNewExternalContact, который добавляет в систему новый контакт. 
    // Процессу в качестве входящих параметров передаются имя и телефон контакта.
    public static bool AddContact(string contactName, string contactPhone)
    {
        // Проверка, была ли выполнена аутентификация пользователя.
        if (!IsAuthentificated)
        {
            return false;
        }
        // Формирование строки запроса к веб-сервису для запуска процесса AddNewExternalContact, 
        // которому передаются значения входящих параметров ContactName и ContactPhone.
        string requestString = string.Format(processServiceUri +
                "AddNewExternalContact/Execute?ContactName={0}&ContactPhone={1}",
                                 contactName, contactPhone);
        HttpWebRequest request = HttpWebRequest.Create(requestString) as HttpWebRequest;
        // Определение метода запроса.
        request.Method = "GET";
        // В запрос включаются аутентификационные cookie, которые были получены от 
        // сервиса аутентификации bpm'online. 
        request.CookieContainer = AuthCookie;
        // Получение ответа от сервиса и обработка результатов.
        using (var response = request.GetResponse())
        {
            // Обработка результатов выполнения запроса.
        }
        return true;
    }

    // Метод запускает процесс GetAllBpmContacts, который возвращает коллекцию контактов системы.
    public static List<BPMContact> GetAllContacts()
    {
        // Проверка, была ли выполнена аутентификация пользователя.
        if (IsAuthentificated)
        {
            // Формирование строки запроса к веб-сервису для запуска процесса GetAllBpmContacts.
            string requestString = string.Format(processServiceUri +
                                "GetAllBpmContacts/Execute?ResultParameterName=ContactList");
            HttpWebRequest request = HttpWebRequest.Create(requestString) as HttpWebRequest;
            // Определение метода запроса.
            request.Method = "GET";
            // В запрос включаются аутентификационные cookie, которые были получены от 
            // сервиса аутентификации bpm'online.
            request.CookieContainer = AuthCookie;
            // Получение и обработка ответа от сервера. 
            using (var response = request.GetResponse())
            {
                // Ответ от сервера возвращается в xml-формате и содержит строку 
                // с JSON-сериализованным значением. 
                using (XmlReader reader = XmlReader.Create(response.GetResponseStream()))
                {
                    reader.Read();
                    // Десериализация значения, полученного от сервера. 
                    // Для JSON-десериализации в данном примере используется библиотека Newtonsoft.Json.dll.
                    using (var jsonReader = new JsonTextReader
                        (new StringReader(reader.ReadElementContentAsString())))
                    {
                        var serializer = new JsonSerializer();
                        return serializer.Deserialize<List<BPMContact>>(jsonReader);
                    }
                }
            }
        }
        return null;
    }

    // Класс контакта bpm'online для десериализации списка контактов, возвращаемых бизнес-процессом.
    public class BPMContact
    {
        // Свойство, в которое будет выполняться десериализация идентификатора контакта.
        public Guid Id { get; set; }
        // Свойство, в которое будет выполняться десериализация имени контакта.
        public string Name { get; set; }
        // Свойство, в которое будет выполняться десериализация телефона контакта.
        public string Phone { get; set; }

    }
}

Реализация запуска процессов в bpm'online из программного кода внешнего приложения

Теперь для запуска процессов bpm'online из внешнего приложения достаточно реализовать вызов соответствующих методов класса BPMonlineProcessEngineExample.

Пример программного кода внешнего приложения:

// Выполнение аутентификации пользователя с имененем UserName. 
if (BPMonlineProcessEngineExample.TryLogin("UserName", "UserPassword"))
{
    try
    {
        // Добавление нового контакта через запуск бизнес-процесса в системе.
        BPMonlineProcessEngineExample.AddContact("Коваленко Петр Андреевич", "123-23-65");

        // Получение списка контактов через запуск бизнес-процесса в системе.
        List<BPMonlineProcessEngineExample.BPMContact> bpmContacts =
            BPMonlineProcessEngineExample.GetAllContacts();

        // Обработка полученного списка контактов.
        foreach (var contact in bpmContacts)
        {
            // Обработка данных контакта.
        }
    }
    catch (Exception e)
    {
        // Обработка ошибок.
    }
}

© Terrasoft 2002-2016.

Был ли данный материал полезен?

Как можно улучшить эту статью?