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

Настройка интеграции системы 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 через Администрирование – Система – Внешние приложения.

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
  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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
   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:

1
2
3
4
5
6
7
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 и его используем при создании задачи:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
    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), если база данных находится на одном компьютере с вашим сайтом.

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

1
2
3
4
5
6
7
8
9
10
11
// прочитаем конфигурацию для соединения с базой данных
    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 дан во вложении.

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