The ProcessEngineService.svc web service
Glossary Item Box
Introduction
Running the business processes is one of the purpose of integration the external application with bpm’online. The ProcessEngineService.svc web service that allows to start business processes from outside is implemented for this. The ProcessEngineService.svc web service is available by following URL:
http[s]://<bpm'online_application_address>/0/ServiceModel/ProcessEngineService.svc
ATTENTION
Before calling a web-service via external tools, authenticate the user, whose name will be used to execute queries. For this, use the AuthService.svc service (see. "The AuthService.svc authentication service" and "External requests authentication to bpm'online services" articles). This service will return the correspondent cookies, which you have to use when querying the ProcessEngineService.svc.
Moreover, if the SCRF attacks defense is enabled in your application, add the BPMCSRF token to the query headers (see. "Protection from CSRF attacks during integration with bpm'online").
See the examples of executing queries to bpm'online web-services after user authentication in the "Executing OData queries using Fiddler".
NOTE
A ProcessEngineService.svc use case is available in the "How to run bpm'online processes via web service" article. The full list of the web service methods can be found in the .NET class libraries of platform core documentation.
ProcessEngineService.svc methods
Business process launch
To start specific business process you will need to call the Execute() method of the service. You can call the Execute() method via GET and POST HTTP requests. General format of the Execute() method:
http[s]://<bpm'online_application_address>/0/ServiceModel/ProcessEngineService.svc/PROCESSSCHEMANAME/Execute[?<optional incoming parameters of the business process>]
Where PROCESSSCHEMANAME – the name of the business process schema in the bpm’online.
NOTE
The name of the business process schema can be found in the [Configuration] section.
For example, start the UsrSomeProcess process. The procParam parameter with the 15 as a value is passed to the process. The GET string will be as follows:
.../0/ServiceModel/ProcessEngineService.svc/UsrSomeProcess/Execute?procParam=15
The ProcessEngineService.svc process enables to start specific business process and get the result of execution of this process with the specific parameter. For this, call the Execute() method in the following format:
http[s]://<bpm'online_application_address>/0/ServiceModel/ProcessEngineService.svc/PROCESSSCHEMANAME/Execute?ResultParameterName=RESULTPARAMETERNAME[&<optional incoming parameters of the business process>],
where
- PROCESSSCHEMANAME – the name of the business process schema which instance will be launched
- RESULTPARAMETERNAME – the name of the process parameter, that stores the result of the process execution. If this parameter is not specified, the web service will launch the specified business process without waiting its execution result.
ATTENTION
If the RESULTPARAMETERNAME parameter is disabled in the called process, the web service will return null.
For example, start the CustomProcess process. The process result is stored in the CustomProcessResult outgoing process parameter. In addition, the incomeParam parameter with the "IncomeParamValue” value is passed to the CustomProcess process. The GET string will as follows:
.../0/ServiceModel/ProcessEngineService.svc/CustomProcess/Execute?ResultParameterName=CustomProcessResult&incomeParam=IncomeParamValue
The result of executing the Execute() method is returned as a string containing the JSON object (it is possible to get the null). Deserialization of the JSON object and bringing the result to a specific type of data must be performed in the code that calls the web service.
Executing a separate element of the business process
To execute a separate element of the business process, call the ExecProcElByUId() web service method. This method accepts the Id of the executed process element as a parameter. The format of the ExecProcElByUId()method call:
http[s]://<bpm'online_application_address>/0/ServiceModel/ProcessEngineService.svc/ExecProcElByUId/PROCELUID
where PROCELUID – id of the executed process element.
ATTENTION
Only the element of the launched process can be executed.
If the ExecProcElByUId() process element has been already completed at the moment of calling the method, this element will not be executed.
