How to run bpm'online processes via web service

Introduction

The ProcessEngineService.svc web service is used to run business processes from the third-party applications. Main features of the ProcessEngineService.svc web service are described in “The ProcessEngineService.svc web service” article.

Case description

Run a demo business processes of creating and reading bpm’online contacts from the browser address bar or third-party application via the ProcessEngineService.svc web service.

Case implementation algorithm

To implement the case:

1. Create the demo processes of adding new contact and reading all contacts.

2. Check the operability of the ProcessEngineService.svc web service from the browser address bar.

3. In the third-party application, create a class and implement logic of interaction with the ProcessEngineServise.svc web service in this class.

1. Creating the demo business processes

1.1. Creating the process of adding a new contact

The business process of adding a new contact has start event, end event and [ScriptTask] element in which the logic of adding a new contact is implemented. The values of business process properties (Fig. 1):

• [Name] – "Add New External Contact"
• [Code] – "UsrAddNewExternalContact".

Default values may be used for the other properties.

Fig. 1. Properties of the UsrAddNewExternalContact business process

The business process contains two text parameters (Fig. 2). The contact details are sent to the process via these parameters:

• ContactName – contains a name of the new contact
• ContactPhone – contains a phone number of the new contact.

Fig. 2. The parameters of the business process.

Logic of adding a new contact is implemented in the [ScriptTask] element. The values of element properties (Fig. 3):

• [Name] – "Add contact"
• [Code] – "ScriptTaskAddContact"
• [For interpreted process] – checkbox unchecked.

Fig. 3. [ScriptTask] element properties

The source code for the ScriptTaskAddContact element:

// Create an instance of the schema of the "Contact" object.
var schema = UserConnection.EntitySchemaManager.GetInstanceByName("Contact");
// Create an instance of a new object.
var entity = schema.CreateEntity(UserConnection);
// Set the default values for the object columns.
entity.SetDefColumnValues();
// Set the value of the "Name" column from the process parameter.
entity.SetColumnValue("Name", ContactName);
// Set the value of the "Phone" column from the process parameter.
entity.SetColumnValue("Phone", ContactPhone);
// Saving a new contact.
entity.Save();
return true;

Save the business process to apply changes.

Creating the process of reading contacts

Business process that generates a list of all contacts is also contains one [ScriptTask] element in which the necessary logic is implemented. The values of business process properties (Fig. 4):

• [Name] – "Get All Contacts"
• [Code] – "UsrGetAllContacts"
• [Force compile] – checkbox checked.

Default values may be used for the other properties.

Fig. 4. Properties of the contacts reading business process

The UsrGetAllContacts process contains the ContactList parameter. The process will get a list of all contacts as a JSON object through this parameter. Parameter type – unlimited length string. Parameter properties are listed on Fig. 5.

Fig. 5. Parameter properties

Logic of getting contacts is implemented in the [ScriptTask] process element. The values of element properties (Fig. 6):

• [Name] – "Get all contatcs"
• [Code] – "ScriptTaskGetAllContacts"
• [For interpreted process] – checkbox unchecked.

Fig. 6. [ScriptTask] element properties

The source code for the ScriptTaskGetAllContacts element:

// Create an EntitySchemaQuery instance.
EntitySchemaQuery query = new EntitySchemaQuery(UserConnection.EntitySchemaManager, "Contact");
// A flag for required selection of the primary column (Id).
query.PrimaryQueryColumn.IsAlwaysSelect = true;
// Adding columns to the request.
query.AddColumn("Name");
query.AddColumn("Phone");
// Getting the result collection.
var list = query.GetEntityCollection(UserConnection);
// Creating a list of contacts for serialization in JSON.
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);
}
// Save the serialized JSON collection of contacts to the ContactList parameter.
ContactList = JsonConvert.SerializeObject(contacts);
return true;

Save the business process to apply changes.

2. Run business processes from the browser address bar

The call to the service method is possible using an HTTP GET request and you can use a standard browser to start a business process. General URL formats of calling a service for business processes with parameters are described in the “The ProcessEngineService.svc web service” article.

To launch the process of creation a new contact, enter the following URL in the browser address bar:

http[s]://<bpm'online_application_address>/0/ServiceModel/ProcessEngineService.svc/UsrAddNewExternalContact/Execute?ContactName=John Johanson&ContactPhone=+1 111 111 1111

After executing the request, a new contact will be added to bpm’online (Fig. 7).

Fig. 7. New contact

To launch the process of reading all contacts, enter the following URL in the browser address bar:

http[s]://<bpm'online_application_address>/0/ServiceModel/ProcessEngineService.svc/UsrGetAllContacts/Execute?ResultParameterName=ContactList

After executing the request, a JSON object with collection of contacts will be displayed in the browser window (Fig. 8).

Fig. 8. Result of the contacts reading process

3. Run business processes from the third-party application

Before making requests to ProcessEngineService.svc, a third party application must be authenticated. Use the AuthService.svc authentication service for this. Information and examples of authentication of third-party application can be found in the “The AuthService.svc authentication service” article. Console application created according the example can be used for the case below.

To generate requests to the ProcessEngineService.svc service, add a string field that contains base service URL to the Program class source code:

private const string processServiceUri = baseUri + @"/0/ServiceModel/ProcessEngineService.svc/";

To run the business process of adding a new contact, add the following method to the source code of the Program class:

public static void AddContact(string contactName, string contactPhone)
{
    // Generating the URL request.
    string requestString = string.Format(processServiceUri +
            "UsrAddNewExternalContact/Execute?ContactName={0}&ContactPhone={1}",
                             contactName, contactPhone);
    // Generating Http request.
    HttpWebRequest request = HttpWebRequest.Create(requestString) as HttpWebRequest;
    request.Method = "GET";
    request.CookieContainer = AuthCookie;
    // Execute the request and analyze the Http response.
    using (var response = request.GetResponse())
    {
        // Because the service returns an empty string, 
        // you can display the http response properties.
        Console.WriteLine(response.ContentLength);
        Console.WriteLine(response.Headers.Count);
    }
}

Add a method of starting the process of reading contacts:

 public static void GetAllContacts()
{
    // Generating the URL request.
    string requestString = processServiceUri +
                       "UsrGetAllContacts/Execute?ResultParameterName=ContactList";
    HttpWebRequest request = HttpWebRequest.Create(requestString) as HttpWebRequest;
    request.Method = "GET";
    request.CookieContainer = AuthCookie;
    // Generating Http request.
    using (var response = request.GetResponse())
    {
        // Executing the request and output the result.
        using (var reader = new StreamReader(response.GetResponseStream()))
        {
            string responseText = reader.ReadToEnd();
            Console.WriteLine(responseText);
        }
    }
}

The added methods can be called in the main program method after successful authentication:

static void Main(string[] args)
{
    if (!TryLogin("Supervisor", "Supervisor"))
    {
        Console.WriteLine("Wrong login or password. Application will be terminated.");
    }
    else
    {
        try
        {
            // Calling methods for starting business processes.
            AddContact("John Johanson", "+1 111 111 1111");
            GetAllContacts();
        }
        catch (Exception)
        {
            // Exception Handling.
            throw;
        }
    };
    Console.WriteLine("Press ENTER to exit...");
    Console.ReadLine();
}

The program result is shown in Fig. 9.

Fig. 9. Result of executing the application