Web Services API

Overview
Most runtime and design time workflow operations can be operated via the web services API, such as:
Retrieving requests and action data and statuses
Launching new requests and updating request data
Completing workflow actions
Managing users, groups, participants, and delegations
Importing and exporting process definitions.
For more flexibility, all of the API web methods can be called by using POST, GET, or SOAP.
The authentication method is HTTP basic (over HTTPS) or can be customized according to your requirements (SSO, token, etc.) by using your own custom .NET HTTP authentication module.
Impersonation and delegation mode is also supported on selected web methods (e.g. completing an action on behalf of a WorkflowGen user).
API methods
The API web methods are located in http://localhost/wfgen/ws/processesruntime.asmx. See the WorkflowGen Web Services API Reference Guide for more information.
WorkflowContext
The WorkflowGen web services API uses the WorkflowContext data structure in some important web methods such as:
CompleteActivityInstance
GetActivityInstanceContext
StartProcess
WorkflowContext is an XML data structure used to exchange parameters with WorkflowGen. The XML data structure is based on ADO.NET DataSet object (serialized in XML). As such, the structure is similar to database tables and records.
📌 XML ADO.NET DataSet context example
1
<NewDataSet>
2
    <parameter>
3
        <name>COMPANY</name>
4
        <dataType>TEXT</dataType>
5
        <direction>OUT</direction>
6
        <textValue>My company</textValue>
7
    </parameter>
8
    <parameter>
9
        <name>AMOUNT</name>
10
        <dataType>NUMERIC</dataType>
11
        <direction>OUT</direction>
12
        <numericValue>1000</numericValue>
13
    </parameter>
14
    <parameter>
15
        <name>APPROVAL_DATE</name>
16
        <dataType>DATETIME</dataType>
17
        <direction>OUT</direction>
18
        <dateTimeValue>2017-02-17T02:07:43Z</dateTimeValue>
19
    </parameter>
20
    <parameter>
21
        <name>ATTACHMENT</name>
22
        <dataType>FILE</dataType>
23
        <direction>OUT</direction>
24
        <fileName>report.xls</fileName>
25
        <fileDescription>My report</fileDescription>
26
        <fileSize>202345</fileSize>
27
        <fileContentType>application/vnd.ms-excel</fileContentType>      
28
        <fileDateLastModified>2017-02-17T02:07:43Z</fileDateLastModified>
29
        <fileOriginalPath>C:\myfolder\report.xls</fileOriginalPath>
30
        <filePath>C:\myfolder\report.xls</filePath>
31
    </parameter>
32
</NewDataSet>
Copied!
Nodes
<NewDataSet> node
The <NewDataSet> node is a Dataset object that contains a set of parameters (parameter nodes) and one session information (session node).
<Parameter> node
The <Parameter> node contains information about the parameter to exchange with WorkflowGen web method:
Node
Description
<name>
Name of the parameter defined in the workflow action
<dataType>
Possible values:
TEXT
NUMERIC
DATETIME
FILE
<direction>
Possible values:
IN
OUT
INOUT
<textValue>
Text value of the parameter
<numericValue>
Numeric value of the parameter
<dateTimeValue>
Datetime value of the parameter in the format xsd:dateTime and stored in GMT (see the Time Zone IDs and GMT Values Mapping appendix)
<fileName>
File name
<fileDescription>
File description
<fileSize>
File size in bytes
<fileDateLastModified>
Date of last modification to the file in the format xsd:dateTime
<fileContentType>
File MIME type
<fileOriginalPath>
Original file path (for information only)
<filePath>
File path that WorkflowGen uses to retrieve the file
WorkflowContext creation with WorkflowGen.My
To simplify WorkflowContext creation and modification, you can use WorkflowGen.My and its WorkflowGen.My.Data.ContextParameters class:
1
WorkflowGen.My.Data.ContextParameters myWorkflowContextParameters = new WorkflowGen.My.Data.ContextParameters();
2
​
3
WorkflowGen.My.Data.ContextParameter contextParamApproval = new WorkflowGen.My.Data.ContextParameter();
4
​
5
contextParamApproval.Name = "DECISION";
6
​
7
contextParamApproval.Direction = WorkflowGen.My.Data.ContextParameter.Directions.Out;
8
​
9
contextParamApproval.Type = typeof(string);
10
​
11
contextParamApproval.Value = "YES";
12
​
13
myWorkflowContextParameters.Add(contextParamApproval);
14
​
15
myWorkflowContextParameters.Update();
16
​
17
string workflowContext = myWorkflowContextParameters.GetXml();
Copied!
For more detailed examples, see WorkflowContext creation with WorkflowGen.My.
Invoking a WorkflowGen API using .NET code
Before invoking a WorkflowGen API using .NET code, first verify that you have access to the APIs by doing the following:
1.Open a new web browser.

2.Connect to your web service with your WorkflowGen URL: http://yourserver:port/wfgen/ws/ProcessesRuntime.asmx.

3.Authenticate with your WorkflowGen account.

4.The above URL will provide you with a list of available web service APIs.
Use the sample code below to invoke a web service API from within your code. This example demonstrates how to call the CompleteActivityInstance API, which is used to complete an open action.
Prior to implementing the code below, do the following:
1.Open your existing web project (or create a new web project) for which you would like to implement the API web service call.

2.Add a web reference to your website by performing the following steps:

1.In Visual Studio, choose Website > Add Web Reference...

2.Enter the web service URL (http://yourserver:port/wfgen/ws/ProcessesRuntime.asmx) and click Add Reference. You will likely be prompted by the server to authenticate your request. Enter the appropriate username, password, and domain (if necessary). Once submitted, you should see the same screen as when you verified your access to the APIs, with a list of available APIs.

3.You will be prompted to give the web reference a name. The sample below uses the web reference name WFG_APIs.

4.Click Add reference. You should now see the reference within your Solution Explorer.

3.Add the following code, or incorporate the code into your existing code as required:
C#
1
using System;
2
using System.Data;
3
using System.Configuration;
4
using System.Web;
5
using System.Web.Security;
6
using System.Web.UI;
7
using System.Web.UI.WebControls;
8
using System.Web.UI.WebControls.WebParts;
9
using System.Web.UI.HtmlControls;
10
using WorkflowGen.My.Web.UI.WebForms;
11
using WorkflowGen.My.Data;
12
using System.Net;
13
​
14
​
15
public partial class _Default : WorkflowPage
16
{
17
​
18
   private WFG_APIs.RuntimeService wsAPI;
19
​
20
   protected void Page_Load(object sender, EventArgs e)
21
   {
22
​
23
   }
24
​
25
​
26
   protected void Button1_Click(object sender, EventArgs e)
27
   {
28
​
29
      string workflowContextXml; // string to get the xml context data
30
​
31
      // Create a new WorkflowGen object for context parameters
32
      WorkflowGen.My.Data.ContextParameters myWorkflowContextParameters = new WorkflowGen.My.Data.ContextParameters();
33
​
34
​
35
      // Get the xml context data into variable
36
      workflowContextXml = myWorkflowContextParameters.GetXml();
37
​
38
      // ID of the request to cancel
39
      string RequestID = "1374"
40
​
41
      //ID of the activity to cancel (Current Action ID) 
42
      string ActivityID = "4"
43
​
44
      wsAPI = new WFG_APIs.RuntimeService();
45
​
46
      wsAPI.Credentials = new NetworkCredential("USERNAME", "PASSWORD","");
47
​
48
      try
49
      {
50
            wsAPI.CompleteActivityInstance(Convert.ToInt16(RequestID), Convert.ToInt16(ActivityID), workflowContextXml.ToString());
51
            Response.Write("OK – Action Completed");
52
      }
53
      catch (Exception exN)
54
      {
55
             Response.Write("Error = " + exN.Message.ToString() + exN.StackTrace.ToString());
56
      }
57
​
58
   }
59
​
60
}
Copied!
📌 Sample code to complete a request action
1
string workflowContextXml; // string to get the xml context data
2
​
3
// Create a new WorkflowGen object for context parameters
4
WorkflowGen.My.Data.ContextParameters myWorkflowContextParameters = new WorkflowGen.My.Data.ContextParameters();
5
​
6
// Get the xml context data into variable
7
workflowContextXml = myWorkflowContextParameters.GetXml();
8
​
9
// ID of the request
10
int RequestID = 1374
11
​
12
// ID of the activity to complete
13
int ActivityID = 4
14
​
15
wsAPI = new WFG_APIs.RuntimeService();
16
wsAPI.Credentials = new NetworkCredential("USERNAME", "PASSWORD","");
17
​
18
try
19
{
20
​
21
    wsAPI.CompleteActivityInstance(RequestID, ActivityID, workflowContextXml.ToString());
22
​
23
    Response.Write("OK – Action Completed");
24
​
25
}
26
​
27
catch (Exception exN)
28
{
29
    Response.Write("Error = " + exN.Message.ToString() + exN.StackTrace.ToString());
30
}
Copied!
StartProcess
StartProcess lets you launch a new request with context parameters from an external application via the web service API using SOAP. This web method lets you launch a new process from another application using HTTP parameters.
Method definition
public int StartProcess(string processName, bool test, string context): Returns the created request ID if successful
Required parameters
Parameter
Type
Description
processName
String
Name of the process to launch
test
Bool
Launch process in test mode?
Y: Launch a test version
N: Launch the active version
context
String
XML structured INOUT parameters to send to the process start (see the WorkflowContext section above for more information)
Optional parameters (StartProcessHeader)
Parameter
Type
Description
ImpersonateUsername
String
Username of impersonating user
ProcessId
Int
Process ID (to be used independently without the processName and test parameters)
ProcessVersion
Int
Process version (to be used processName only)
For an example of usage, download SDK_CS_RemoteLaunchSOAP_v6_1.zip, unzip it, and follow the instructions in the included setup.txt file.
Impersonation
The StartProcess web method supports impersonation, so an authorized user can launch a process on behalf of another user with this web method call. This impersonation feature is restricted to allowed users (defined in the ProcessesRuntimeWebServiceAllowedUsers entry in the \wfgen\ws\web.config file). This feature is useful when an external application doesn't have the user's credentials and wants to instantiate a process on their behalf. For more information, see the Impersonate username section below and the Web Services API: StartProcess: Launch a process on behalf of another user topic on the WorkflowGen Forum & Knowledge Base.
Security
If you receive the message SoapException "Security: You are not authorized to use this web service", it's because some WorkflowGen web service methods require an additional configuration setting to be called by a user. In the \wfgen\ws\web.config file, you can edit the following key to authorize WorkflowGen administrators to use the secured web methods:
1
<add key="ProcessesRuntimeWebServiceAllowedUsers" value="wfgen_admin,MYDOMAIN\myusername" />
Copied!
The value contains a comma separated list of usernames. The username must be prefixed by the domain name according to your authentication method.
The following web service API methods are secured by this setting:
RaiseCancelExceptionOnActivityInstance
RaiseCancelExceptionOnActivityInstanceByName
RaiseExceptionOnActivityInstance
RaiseExceptionOnActivityInstanceByName
UpdateProcessInstanceData
StartProcess, with the ImpersonateUsername SOAP or GET/POST parameter
Performance
By default, the GetProcessInstanceList and GetActivityInstanceList web methods retrieve all the process data associated to the requests/actions. If you don't need process data values, you only need to add a SOAP header or query string parameter:
ShowData=False
If you only need a subset of the associated process data, you can specify the list of process data to be retrieved with the DataList SOAP header or query string parameter:
DataList=AMOUNT,APPROVAL,COMPANY
This will significantly improve performance.
📌 Example of a query string
1
http://localhost/wfgen/ws/ProcessesRuntime.asmx/GetActivityInstanceList?query=closed&datalist=REQUEST_SUBJECT,FORM_ARCHIVE
Copied!
Process data
Get associated data of a request and download the associated attachments.
If you are a process supervisor, manager, or administrator, you can use the web API to get the data of a specific request and download the associated attachments using the URLs below, with the request number as the value of ProcessInstanceId (these examples use request 17).
If the request is still ongoing:
1
http://mywebserver/wfgen/ws/processesruntime.asmx/GetProcessInstanceList?query=supervisedinprogress&ProcessInstanceId=17&Template=ProcessesRuntime.ProcessInstanceListRss.txt
Copied!
If the request is closed:
1
http://mywebserver/wfgen/ws/processesruntime.asmx/GetProcessInstanceList?query=supervisedclosed&ProcessInstanceId=17&Template=ProcessesRuntime.ProcessInstanceListRss.txt
Copied!
Inside the retrieved XML output (RSS, XML, or ATOM, depending on the template you're using; see \wfgen\ws\App_Data for the templates), you'll see a specific URL for each data file, which you can download using an HTTP GET/POST or an AJAX call from your web form.
📌 Example
1
<wfg:processInstanceRelData>
2
    <FORM_HTML description="Form" dataType="FILE" fileName="3429158-1.html" fileContentType="text/html" fileSize="9236″>http://mywebserver/wfgen/show.aspx?QUERY=DATASET_FILE_DOWNLOAD&ID_PROCESS=206&ID_RELDATA=2812&ID_DATASET=3429162&NUM_VALUE=1&NO_CHARSET=Y&NO_REDIRECTION=Y</FORM_HTML>
3
    <FORM_DATA description="Form data" dataType="FILE" fileName="dataOUT.xml" fileContentType="application/xml" fileSize="3646″>http://mywebserver/wfgen/show.aspx?QUERY=DATASET_FILE_DOWNLOAD&ID_PROCESS=206&ID_RELDATA=2813&ID_DATASET=3429163&NUM_VALUE=1&NO_CHARSET=Y&NO_REDIRECTION=Y</FORM_DATA>
4
    <FORM_ARCHIVE description="Form archive" dataType="FILE" fileName="form_archive.htm" fileContentType="application/octet-stream" fileSize="17805″>http://mywebserver/wfgen/show.aspx?QUERY=DATASET_FILE_DOWNLOAD&ID_PROCESS=206&ID_RELDATA=2814&ID_DATASET=3429164&NUM_VALUE=1&NO_CHARSET=Y&NO_REDIRECTION=Y</FORM_ARCHIVE>
5
    <FORM_DRAFT description="Form draft" dataType="TEXT" fileName="" fileContentType="" fileSize="">N</FORM_DRAFT>
6
</wfg:processInstanceRelData>
Copied!
UpdateProcessInstanceData
The UpdateProcessInstanceData web method allows you to update the associated data of a request in progress from an external application. It is restricted to allowed users as defined in the ProcessesRuntimeWebServiceAllowedUsers entry in the \wfgen\ws\web.config file.
Only requests in progress can be updated. If a process data to update is locked by another user (such as when a user is filling in a web form that will update one of the process data), the web method triggers a SOAP exception.
Parameters
The web method parameters (SOAP or GET/POST) are:
processInstanceId
📌 Example: 12345 

activityInstanceId
📌 Example: 2
​
workflowContext
📌 Example:
1
MYTEXTDATAHello
2
  MYNUMDATA1000
Copied!
Here, MYTEXTDATA and MYNUMDATA are the process data names to update.
Usage
By updating process data associated to requests in progress, you might impact the ongoing workflow with side effects such as loops or stuck requests, so you should be careful when updating process data used in conditions.
If you need more security and traceability, we recommend using workflow actions to update process data (for more information, see Workflow Design: Update a process data from an external application on the WorkflowGen Forum & Knowledge Base).
Impersonate username
All user context-based API web methods support impersonation, so an authorized user can call a web method on behalf of another user.
Security
The impersonation feature is restricted to allowed users as defined in the ProcessesRuntimeWebServiceAllowedUsers entry in the \wfgen\ws\web.config file.
Usage
There are two ways to set the ImpersonateUsername value:
As a querystring parameter; in this example, a list of todo actions for jsmith:
1
http://myserver/wfgen/ws/ProcessesRuntime.asmx/GetActivityInstanceList?query=todo&impersonateusername=jsmith
Copied!
As a SOAP header parameter; in this example, to complete an action on behalf of jsmith:
1
// Settings and parameters
2
CompleteActivityInstanceHeader myCompleteActivityInstanceHeader = new CompleteActivityInstanceHeader();
3
​
4
myCompleteActivityInstanceHeader.ImpersonateUsername="jsmith";
5
​
6
// Set NetworkCredentials with the credentials of the current connected user
7
RuntimeService myRuntimeService = new RuntimeService();
8
myRuntimeService.CompleteActivityInstanceHeaderValue = myCompleteActivityInstanceHeader;
9
myRuntimeService.Credentials = CredentialCache.DefaultCredentials;
10
​
11
// Call the Web Service API method
12
myRuntimeService.CompleteActivityInstance(1,2,wfgContext);
Copied!
​