Настройка интеграции системы ELMA с внешним сайтом

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

Источники информации:

  1. Описание структуры внешнего API ELMA: http://bpm-demo.elma-bpm.ru/API/Help/ (для доступа к своей системе замените «bpm-demo.elma-bpm.ru» на свой хост, например, «192.168.0.100:8000»).
  2. Внешнее API (статья из базы знаний):  https://www.elma-bpm.ru/kb/article-137.html.
  3. Silverlight: http://www.microsoft.com/silverlight/.
  4. Примеры использования HTTP-запросов для запуска бизнес-процессов: https://www.elma-bpm.ru/kb/article-414.html.

Вы решили интегрировать свой сайт (или другую информационную систему) с системой. Давайте рассмотрим этот сценарий на примере сайта, сделанного с помощью Silverlight.

Подготовим систему для работы с нашим сайтом. Для этого добавим ApplicationToken через Администрирование – Система – Внешние приложения.

Теперь вернёмся к нашему сайту.

// ApplicationToken – служит для идентификации нашего сайта в Elma                
string ApplicationToken = "F561BE887749B468A803ED18EDDEAD3BE02C8402943B9547A42BE843D85A54B86FC782C49656A28AC9761D95C32B42FB92B5CC15658397AA5F5A148006954389"; // скопируйте ApplicationToken из настроек Элмы (Администрирование/Система/Внешние приложения)
// Хост Elma – служит для определения адреса сайта Elma                
string HostElma = "http://localhost:8001/"; // вместо localhost укажите сайт, на котором размещается ваш экземпляр Элмы 

Подготовим данные и методы для работы с ELMA:

  public class ItemWebAPI
  {
   public ItemsWebAPI Data = null;
   public List<ItemsWebAPI> DataArray = new List<ItemsWebAPI>();
   public string Name;
   public string Value;
  }
// реализация EleWise.ELMA.Common.Models.WebData
  public class ItemsWebAPI
  {
   public List<ItemWebAPI> Items = new List<ItemWebAPI>();
  }

  public class ResponseAuth
  {
   public string AuthToken;
   public string CurrentUserId;
   public string SessionToken;
  }

  ResponseAuth CurrentUser;

// Перевести созданные данные ItemsWebAPI в Json формат 
  string structToJson(ItemsWebAPI item)
  {
   using (MemoryStream ms = new MemoryStream())
   {
    DataContractJsonSerializer serializer =
      new DataContractJsonSerializer(item.GetType());
    serializer.WriteObject(ms, item);
    ms.Position = 0;

    using (StreamReader reader = new StreamReader(ms))
    {
     return reader.ReadToEnd();
    }
   }
  }

Первое, что необходимо сделать, это получить доступ к сервису ELMA. У нас есть возможность работать при обмене с форматами XML и Json. Выберем, для примера, Json.

   WebClient wc = new WebClient();
// назначить обработчик вызова
   wc.UploadStringCompleted += wc_UploadStringCompleted;
   // пройти авторизацию с системой
	  string login = "admin";
   string password = "password";
   Uri serviceUri = new Uri(HostElma + "API/REST/Authorization/LoginWith?username=" + login);
   wc.Headers["ApplicationToken"] = ApplicationToken;
   wc.Headers["Content-Type"] = "application/json";
// асинхронно запускаем авторизацию и в теле запроса указываем пароль в двойных кавычках
   wc.UploadStringAsync(serviceUri, "POST", string.Format("\"{0}\"", password));

// обрабатываем ответ от системы
  void wc_UploadStringCompleted(object sender, UploadStringCompletedEventArgs e)
  {
   if (e.Error == null)
   {
    string s = e.Result;
		// обработать Json ответ на авторизацию от Элмы
    DataContractJsonSerializer serializer = new DataContractJsonSerializer(typeof(ResponseAuth));
    MemoryStream stream = new MemoryStream();
    StreamWriter writer = new StreamWriter(stream);
    writer.Write(s);
    writer.Flush();
    stream.Position = 0;
// получаем ответ авторизации как описано во внешнем API (http://bpm-demo.elma-bpm.ru/API/REST/Authorization/help/operations/LoginWithUserName)
    CurrentUser = (ResponseAuth)serializer.ReadObject(stream);

   }
   
  }

 

Теперь у нас есть UserId и AuthenticationToken, и мы можем взять информацию о пользователе, запускать процессы и задачи от его имени.

Как создать задачу и приложить файл? В этом нам поможет описание внешнего API для работы с задачами: http://bpm-demo.elma-bpm.ru/API/Help/Service?uid=895e5ab8-b31a-4696-bd55-fe2ea6988c11

Передадим текст в виде файла на сайт Silverlight:

   WebClient wc = new WebClient();
   Uri serviceUri = new Uri(HostElma + "API/REST/Files/Upload");
   wc.Headers["ApplicationToken"] = ApplicationToken;
   wc.Headers["AuthToken"] = CurrentUser.AuthToken;
   wc.Headers["Content-Type"] = "application/json";
   wc.Headers["FileName"] = "SimpleFile.txt";
   string retGuid = wc.UploadString(serviceUri, "POST", dataStr); 

На выходе передачи файла получаем GUID в переменной regGuid и его используем при создании задачи:

    WebClient wc = new WebClient();
// Назначить обработчик ответа от сервера
    wc.UploadStringCompleted += wc_UploadStringCompletedTask;
 Uri serviceUri = new Uri(HostElma + "API/REST/Tasks/Create");
// Заполнить необходимые параметры заголовка
    wc.Headers["ApplicationToken"] = ApplicationToken;
    wc.Headers["AuthToken"] = CurrentUser.AuthToken;
    wc.Headers["Content-Type"] = "application/json";

// Создание задачи типа CLR: EleWise.ELMA.Common.Models.WebData
ItemsWebAPI items = new ItemsWebAPI();
// Указать тему задачи
    ItemWebAPI itemSubject = new ItemWebAPI();
    itemSubject.Name = "Subject";
    itemSubject.Value = "Стенд согласован";
    items.Items.Add(itemSubject);

// Задать исполнителей задачи (в данном случае одного)
    itemExecutors = new ItemWebAPI();
    ItemsWebAPI itemExecutor = new ItemsWebAPI();
    itemExecutor.Items.Add(new ItemWebAPI());
    itemExecutor.Items[0].Name = "Id";
    itemExecutor.Items[0].Value = "5"; // Id пользователя-исполнителя задачи
    itemExecutors.Data = itemExecutor;

    itemExecutors.Name = "Executor";
    itemExecutors.Value = null;
    items.Items.Add(itemExecutors);

// Приложить файл во вложении
    item = new ItemWebAPI();
    List<ItemsWebAPI> itemAttachs = new List<ItemsWebAPI>();
    ItemsWebAPI itemAttach = new ItemsWebAPI();

    ItemsWebAPI itemUid = new ItemsWebAPI();
    itemUid.Items.Add(new ItemWebAPI());
    itemUid.Items[0].Name = "Uid";
    itemUid.Items[0].Value = retGuid; // здесь указываем Guid файла, который вернул метод создания файла
    ItemWebAPI itemFile = new ItemWebAPI();
    itemFile.Data = itemUid;
    itemFile.Name = "File";
    itemFile.Value = null;
    itemAttach.Items.Add(itemFile);

    itemAttachs.Add(itemAttach);
    item.DataArray = itemAttachs;
    item.Name = "Attachments";
    item.Value = null;
    items.Items.Add(item);

// Задать параметры Задачи
    itemStartDate = new ItemWebAPI();
    itemStartDate.Name = "StartDate";
    itemStartDate.Value = DateTime.Now.ToString();
    items.Items.Add(itemStartDate);
    itemEndDate = new ItemWebAPI();
    itemEndDate.Name = "EndDate";
    itemEndDate.Value = DateTime.Now.AddDays(1).ToString();
    items.Items.Add(itemEndDate);

// Задать описание Задачи 
    itemDesc = new ItemWebAPI();
    itemDesc.Name = "Description";
    itemDesc.Value = "Здесь укажите описание задачи."
;

    string jsonStr = structToJson(items);
    wc.UploadStringAsync(serviceUri, "POST", jsonStr);

// Ответ от сервера Элмы на создание задачи
  void wc_UploadStringCompletedTask(object sender, UploadStringCompletedEventArgs e)
  {
   if (e.Error == null)
   {
    // Задача создана
   }
  } 

Существуют исключительные случаи, когда необходимо быстро обновить большой объём данных или создать много новых записей (при импорте, например). Для этого можно использовать прямой доступ к базе данных и необходимо знать SQL.

Тогда на сайте сделайте соединение с базой данных. Для этого в web.config добавьте строки:

    <connectionStrings>
      <add name="ElmaConnectionString" connectionString="Data Source= (local);Initial Catalog=ELMA3;Integrated Security=true;"/>
    </connectionStrings>

В Data Source укажите название экземпляра SQL Server или (local), если база данных находится на одном компьютере с вашим сайтом.

Пример обновления поля в базе данных системы:

// прочитаем конфигурацию для соединения с базой данных
    SqlConnection _sqlConnection = new SqlConnection();
    _sqlConnection.ConnectionString = ConfigurationManager.ConnectionStrings["ElmaConnectionString"].ToString();
    _sqlConnection.Open(); // установим соединение
 SqlDataAdapter da = new SqlDataAdapter();
// присвоить значение NULL всем значениям поля Type в пользовательской таблице Reservation 
    string sqlCommand = "UPDATE Reservation SET Type = NULL";
    da.UpdateCommand = new SqlCommand(sqlCommand, _sqlConnection);
    da.UpdateCommand.ExecuteNonQuery();

    _sqlConnection.Close(); 
Замечание
При этом надо учитывать, что правила, заданные в Дизайнере для работы с базой данных, работать не будут. Например, если вы указали в сценарии, что для всех контрагентов будет проверяться ИНН у контрагентов на правильность (10 или 12 только цифр), то эта проверка не сработает.
Структуру базы данных можно узнать в Дизайнере системы.

Пример интеграции внешнего сайта с системой ELMA дан во вложении.

Прикрепленные файлы