logo
ELMA Framework › ELMA WebAPI › Integrating ELMA with an external website

Integrating ELMA with an external website

This article provides an example of integrating ELMA with an external website. It is necessary for data exchange between the system and external information systems, e.g. sending and receiving control messages.

Information sources:

  1. Structure of ELMA Web API: http://demo.elma-bpm.com/API/Help/ (to access your system, replace "demo.elma-bpm.com" with your host, e.g. 192.168.0.100:8000)
  2. Web API (knowledge base article):  https://kb.elma-bpm.com/article-1153.html
  3. Silverlight: http://www.microsoft.com/silverlight/
  4. Examples of using HTTP requests to start business processes: https://kb.elma-bpm.com/article-3392.html

Consider integrating your website (or another information system) with ELMA, using an example of a website, created in Silverlight.

Prepare the system to work with the website. For this, add ApplicationToken in Administration - System - External Applications.

Now go back to the website.

// ApplicationToken – used to identify the website in ELMA                
string ApplicationToken = "F561BE887749B468A803ED18EDDEAD3BE02C8402943B9547A42BE843D85A54B86FC782C49656A28AC9761D95C32B42FB92B5CC15658397AA5F5A148006954389"; // copy ApplicationToken from ELMA settings (Administration - System - External Applications)
// ELMA Host – used to identify the ELMA website address                
string HostElma = "http://localhost:8001/"; // instead of localhost, specify your ELMA website

Prepare data and methods for working with ELMA:

  public class ItemWebAPI
  {
   public ItemsWebAPI Data = null;
   public List<ItemsWebAPI> DataArray = new List<ItemsWebAPI>();
   public string Name;
   public string Value;
  }
// implementation of 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;
 
// Convert the created ItemsWebAPI data to the 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();
    }
   }
  }

The first thing you need to do is get access to the ELMA service. You can use two formats for data exchange: XML and JSON. Select JSON, for example.

   WebClient wc = new WebClient();
// assign a call handler
   wc.UploadStringCompleted += wc_UploadStringCompleted;
   // sign in to the system
      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";
// asynchronously start authentication and in the query specify the password in quotation marks
   wc.UploadStringAsync(serviceUri, "POST", string.Format("\"{0}\"", password));
 
// process the system response
  void wc_UploadStringCompleted(object sender, UploadStringCompletedEventArgs e)
  {
   if (e.Error == null)
   {
    string s = e.Result;
        // process the Json response to authentication from ELMA
    DataContractJsonSerializer serializer = new DataContractJsonSerializer(typeof(ResponseAuth));
    MemoryStream stream = new MemoryStream();
    StreamWriter writer = new StreamWriter(stream);
    writer.Write(s);
    writer.Flush();
    stream.Position = 0;
// get the authentication response as described in Web API (http://demo.elma-bpm.com/API/REST/Authorization/help/operations/LoginWithUserName)
    CurrentUser = (ResponseAuth)serializer.ReadObject(stream);
 
   }
    
  }

Now you have UserId and AuthenticationToken and you can take the information about the user and start processes and tasks on the user's behalf.

To find out how to create a task and attach a file, read the description of Web API for working with tasks: http://demo.elma-bpm.com/API/Help/Service?uid=895e5ab8-b31a-4696-bd55-fe2ea6988c11

Pass the text as a file to the Silverlight website:

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);

On the output of passing the file, you get a GUID in the regGuid variable. Use it when creating a task:

    WebClient wc = new WebClient();
// Assign the server response handler
    wc.UploadStringCompleted += wc_UploadStringCompletedTask;
 Uri serviceUri = new Uri(HostElma + "API/REST/Tasks/Create");
// Specify the required header parameters
    wc.Headers["ApplicationToken"] = ApplicationToken;
    wc.Headers["AuthToken"] = CurrentUser.AuthToken;
    wc.Headers["Content-Type"] = "application/json";
 
// Create a task of the type CLR: EleWise.ELMA.Common.Models.WebData
ItemsWebAPI items = new ItemsWebAPI();
// Specify the task subject
    ItemWebAPI itemSubject = new ItemWebAPI();
    itemSubject.Name = "Subject";
    itemSubject.Value = "Approved";
    items.Items.Add(itemSubject);
 
// Create the task executors (one, in this case)
    itemExecutors = new ItemWebAPI();
    ItemsWebAPI itemExecutor = new ItemsWebAPI();
    itemExecutor.Items.Add(new ItemWebAPI());
    itemExecutor.Items[0].Name = "Id";
    itemExecutor.Items[0].Value = "5"; // Task executor ID
    itemExecutors.Data = itemExecutor;
 
    itemExecutors.Name = "Executor";
    itemExecutors.Value = null;
    items.Items.Add(itemExecutors);
 
// Attach a file
    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; // specify the file Guid returned by the file creation method here
    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);
 
// Specify the Task parameters
    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);
 
// Specify the task description 
    itemDesc = new ItemWebAPI();
    itemDesc.Name = "Description";
    itemDesc.Value = "Task desciption goes here."
;
 
    string jsonStr = structToJson(items);
    wc.UploadStringAsync(serviceUri, "POST", jsonStr);
 
// ELMA server response on task creation
  void wc_UploadStringCompletedTask(object sender, UploadStringCompletedEventArgs e)
  {
   if (e.Error == null)
   {
    // Task created
   }
  }

There are exceptions when you need to update a large amount of date or create numerous new entries (e.g. when importing). For this, you can use direct access to the database and you need to know SQL.

Create a connection with the database on the website. Add the following lines to web.config:

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

In Data Source, specify the SQL Server instance or (local), of the database is on the same computer as your website.

Example of updating a field in the system database:

// read the configuration for connecting with the database
    SqlConnection _sqlConnection = new SqlConnection();
    _sqlConnection.ConnectionString = ConfigurationManager.ConnectionStrings["ElmaConnectionString"].ToString();
    _sqlConnection.Open(); // set a connection
 SqlDataAdapter da = new SqlDataAdapter();
// assign the NULL value to all the values of the Type fiels in the Reservation user table 
    string sqlCommand = "UPDATE Reservation SET Type = NULL";
    da.UpdateCommand = new SqlCommand(sqlCommand, _sqlConnection);
    da.UpdateCommand.ExecuteNonQuery();
 
    _sqlConnection.Close();
 
Note
Keep in mind, that the database management rules set in the Designer will not work. For example, if you specify in a script that TIN will be checked for all the contractors (only 10 or 12 digits), then this check will not work.
You can find out about the database structure in the Designer.

An example of an external website integration with ELMA is in the attachment.

Attachments