Service that runs business processes

Level: advanced

ProcessEngineService.svc is a web service implemented in the Creatio service model to run business processes. Use the web service to integrate external apps with Creatio.

Run a business process from an external app

The ProcessEngineService.svc web service grants access to Creatio objects.

ProcessEngineService.svc service URL

https://mycreatio.com/0/ServiceModel/ProcessEngineService.svc

The Terrasoft.Core.Service.Model.ProcessEngineService class implements the ProcessEngineService.svc functionality. The primary methods of the ProcessEngineService.svc service are as follows:

• Execute(). Runs a business process. Passes a set of incoming business process parameters and returns the process execution result.
• ExecProcElByUId(). Executes a specific business process element. Can only execute an element of a running process.

note

View the entire index of the web service methods in the .NET class library.

Run a business process from the front-end

You can run a business process from the front-end in the following ways:

• executeProcess() method of the PrcessModuleUtilities module
• execute() method of the Terrasoft.RunProcessRequest class

Run a business process using the executeProcess() method

To run a business process from the front-end, use the executeProcess() method of the ProcessModuleUtilities module in the NUI package. This module provides a convenient interface for executing requests to the ProcessEngineService.svc service.

To run a business process from a client module schema:

1. Add the ProcessModuleUtilities module as a dependency to the module of the page that calls the service.

2. Call the executeProcess(args) method of the ProcessModuleUtilities module. Set the args object as a parameter.

   The properties of the args object are as follows:

   • sysProcessName. The name of the called process (optional if the sysProcessId property is used).
   • sysProcessId. The ID of the called process (optional if the sysProcessName property is used).
   • parameters. The object whose properties are the incoming parameters of the called process.

Run a business process using the execute() method

1. Create the RunProcessRequest class. Set the properties of the process to run and the needed resulting parameters in this class.

   • schemaName. The name of the called process ( the Code field of the Process Designer).
   • schemaUId. The ID of the called process.
   • Parameters. The object whose properties are the incoming parameters of the called process.
   • resultParameterNames. The array of parameters whose values must be received when executing the process.

2. Call the execute() method of the RunProcessRequest class.

Run a business process from the back-end

To run a business process from the back-end, call the Execute() method of the Terrasoft.Core.Process.IProcessExecutor interface. The IProcessExecutor interface provides a set of the Execute() method overloads for solving custom tasks. View the description of the IProcessExecutor interface in the .NET class library.

Run a business process without passing or receiving parameters

View the ways to run a business process without passing or receiving parameters in the table below.

Way	Method	Method parameters
Name of the business process schema	Execute(string processSchemaName)	processSchemaName. The name of the business process schema.
ID of the business process schema	Execute(Guid processSchemaUId)	processSchemaUId. The ID of the business process schema.

Example that runs a business process by the name of the business process schema

UserConnection userConnection = Get<UserConnection>("UserConnection");
IProcessEngine processEngine = userConnection.ProcessEngine;
IProcessExecutor processExecutor = processEngine.ProcessExecutor;
processExecutor.Execute("UsrProcess2Custom1");
return true;

Run a business process with passing incoming parameters

View the ways to run a business process with passing incoming parameters in the table below.

Way	Method	Method parameters
Name of the business process schema	Execute(string processSchemaName, IReadOnlyDictionary<string, string> parameterValues)	processSchemaName. The name of the business process schema. parameterValues. The key-value collection of incoming parameters. In the parameter collection, the key is the name of the business process parameter, the value is the parameter value converted to a string type.
ID of the business process schema	Execute(Guid processSchemaUId, IReadOnlyDictionary<string, string> parameterValues)	processSchemaUId. The ID of the business process schema. parameterValues. The key-value collection of incoming parameters.

View the examples that run a business process below.

Transfer an integer parameter value

UserConnection userConnection = Get<UserConnection>("UserConnection");
IProcessEngine processEngine = userConnection.ProcessEngine;
IProcessExecutor processExecutor = processEngine.ProcessExecutor;
var nameValues = new Dictionary<string, string>();
int parameter1Value = 100;
nameValues["parameter1"] = parameter1Value.ToString();
processExecutor.Execute("UsrProcess3Custom1", nameValues);
return true;

Transfer a parameter value of the value collection type

UserConnection userConnection = Get<UserConnection>("UserConnection");
IProcessEngine processEngine = userConnection.ProcessEngine;
IProcessExecutor processExecutor = processEngine.ProcessExecutor;
ObjectList<int> values = ObjectList.Create(1, 2, 3, 4);
string serializedValue = BaseSerializableObjectUtilities.SerializeToJson(values);
var parameterNameValues = new Dictionary<string, string>();
parameterNameValues["InputValueList"] = serializedValue;
processExecutor.Execute("ProcessRunsFromScriptTask", parameterNameValues);
return true;

Transfer a parameter value of the object collection type with attributes

UserConnection userConnection = Get<UserConnection>("UserConnection");
IProcessEngine processEngine = userConnection.ProcessEngine;
IProcessExecutor processExecutor = processEngine.ProcessExecutor;
/* Creates a collection of objects. */
var list = new CompositeObjectList<CompositeObject>();
ar item1 = new CompositeObject();
/* The process parameter object contains [Id] and [Name] fields. */
item1["Id"] = new Guid("94cc536a-71a7-4bfb-87ca-13f53b23c28e");
item1["Name"] = "Name1"; list.Add(item1);
var item2 = new CompositeObject(); item2["Id"] = new Guid("e694d36e-1727-4276-9fbf-b9aa193e4f44");
item2["Name"] = "Name2";
list.Add(item2);
string serializedValue = BaseSerializableObjectUtilities.SerializeToJson(list);
var parameterNameValues = new Dictionary<string, string>();
parameterNameValues["InputObjectList"] = serializedValue;
processExecutor.Execute("ProcessRunsFromScriptTask", parameterNameValues);
return true;

Run a business process using a received single outgoing parameter

View ways to run a business process using a received single outgoing parameter in the table below.

Run a business process using a received single outgoing parameter

Way	Method	Method parameters
Name of the business process schema	Execute<TResult>(string processSchemaName, string resultParameterName)	processSchemaName. The name of the business process schema. resultParameterName. The name of the outgoing parameter.
Name of the business process schema with passing incoming parameters	Execute<TResult>(string processSchemaName, string resultParameterName, IReadOnlyDictionary<string, string> parameterValues)	processSchemaName. The name of the business process schema. resultParameterName. The name of the outgoing parameter. parameterValues. The key-value collection of incoming parameters.
ID of the business process schema	Execute<TResult>(Guid processSchemaUId, string resultParameterName)	processSchemaUId. The ID of the business process schema. resultParameterName. The name of the outgoing parameter.
ID of the business process schema with passing incoming parameters	Execute<TResult>(Guid processSchemaUId, string resultParameterName, IReadOnlyDictionary<string, string> parameterValues)`	processSchemaUId. The ID of the business process schema. resultParameterName. The name of the outgoing parameter. parameterValues. The key-value collection of incoming parameters.

View the examples that run a business process below.

Run a business process using a received single outgoing parameter

UserConnection userConnection = GetUserConnection();
IProcessExecutor processExecutor = userConnection.ProcessEngine.ProcessExecutor;
/* List of incoming parameters. */
var inputParameters = new Dictionary<string, string> {
    ["ProcessSchemaParameter1"] = "Value1",
    ["ProcessSchemaParameter2"] = "Value2"
};
string processSchemaName = "processSchemaName";
Guid processSchemaUId = Guid.Parse("00000000-0000-0000-0000-000000000000");
/* Runs the process via the schema name. Returns the text value of the [ProcessSchemaParameter3] parameter. */
string resultValue = processExecutor.Execute<string>(processSchemaName, "ProcessSchemaParameter3");
/* Runs the process via the schema ID. Returns the text value of the [ProcessSchemaParameter3] parameter. */
string resultValue = processExecutor.Execute<string>(processSchemaName, "ProcessSchemaParameter3");
/* Runs the process via the schema name using transferred parameters. Returns the text value of the [ProcessSchemaParameter3] parameter. */
string resultValue = processExecutor.Execute<string>(processSchemaName, "ProcessSchemaParameter3", inputParameters);
/* Runs the process via the schema ID using transferred parameters. Returns the text value of the [ProcessSchemaParameter3] parameter. */
string resultValue = processExecutor.Execute<string>(processSchemaUId, "ProcessSchemaParameter3", inputParameters);

Run a business process with receiving multiple outgoing parameters

View the ways to run a business process with receiving multiple outgoing parameters in the table below.

Way	Method	Method parameters
Name of the business process schema	Execute(string processSchemaName, IEnumerable<string> resultParameterNames)	processSchemaName. The name of the business process schema. resultParameterNames. The collection of outgoing parameters.
Name of the business process schema with passing incoming parameters	Execute(string processSchemaName, IReadOnlyDictionary<string, string> parameterValues, IEnumerable<string> resultParameterNames)	processSchemaName. The name of the business process schema. parameterValues. The key-value collection of incoming parameters. resultParameterNames. The collection of outgoing parameters.
ID of the business process schema	Execute(Guid processSchemaUId, IEnumerable<string> resultParameterNames)	processSchemaUId. The ID of the business process schema. resultParameterNames. The collection of outgoing parameters.
ID of the business process schema with passing incoming parameters	Execute(Guid processSchemaUId, IReadOnlyDictionary<string, string> parameterValues, IEnumerable<string> resultParameterNames)	processSchemaUId. The ID of the business process schema. parameterValues. The key-value collection of incoming parameters. resultParameterNames. The collection of outgoing parameters.

View the examples that run a business process below.

Example that runs a business process with receiving outgoing parameters

UserConnection userConnection = GetUserConnection();
IProcessExecutor processExecutor = userConnection.ProcessEngine.ProcessExecutor;
/* Collection of incoming parameters.*/
var inputParameters = new Dictionary<string, string> {
    ["ProcessSchemaParameter1"] = "Value1",
    ["ProcessSchemaParameter2"] = "Value2"
}; 
/* Collection of outgoing parameters.*/
var resultParameterNames = new string[] { 
    "ProcessSchemaParameter3",
    "ProcessSchemaParameter4"
};
string processSchemaName = "processSchemaName";
Guid processSchemaUId = Guid.Parse("00000000-0000-0000-0000-000000000000");
/* Runs the process via the schema name using received outgoing parameters.*/
ProcessDescriptor processDescriptor = processExecutor.Execute(processSchemaName, resultParameterNames);
/* Runs the process via the schema ID using received outgoing parameters.*/
ProcessDescriptor processDescriptor = processExecutor.Execute(processSchemaName, resultParameterNames);
/* Runs the process via the schema name using transferred incoming and received outgoing parameters.*/
ProcessDescriptor processDescriptor = processExecutor.Execute(processSchemaName, inputParameters, resultParameterNames);
/* Runs the process via the schema ID using transferred incoming and received outgoing parameters.*/
ProcessDescriptor processDescriptor = processExecutor.Execute(processSchemaUId, inputParameters, resultParameterNames);

Run a business process using a received collection of outgoing parameters returns an object of the ProcessDescriptor type. To receive the values of outgoing parameters, use the ResultParameterValues property of the IReadOnlyDictionary<string, object> type in the Terrasoft.Core.Process.ProcessDescriptor class. View the description of the ProcessDescriptor class in the .NET class library.

Example that receives the outgoing parameter values

ProcessDescriptor processDescriptor = processExecutor.Execute("processSchemaName", inputParameters, resultParameterNames); 
object parameter3Value = processDescriptor.ResultParameterValues["ProcessSchemaParameter3"];
if (processDescriptor.ResultParameterValues.TryGetValue("ProcessSchemaParameter4", out object parameter4value)) { 
    Console.Log(parameter4value);
}

Important

Regardless of the settings, you cannot run the business process with receiving outgoing parameters is the background.

---

See also

Integration options

Authentication

Integrations

---

Resources

Terrasoft.Core.Service.Model.ProcessEngineService class (.NET classes reference)

Terrasoft.Core.Process.IProcessExecutor interface (.NET classes reference)