Web Services API

Development Web API
1

Most runtime and design time workflow operations can be operated via the Web API, such as: retrieving requests and action data and statuses; launching new requests; updating request data; completing workflow actions; managing users, groups, participants, and delegations; and importing/exporting process definitions.

For more flexibility, all of the API web methods can be called by using POST, GET, or SOAP.

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 is also supported on selected web methods (e.g. completing an action on behalf a WorkflowGen user).

Browse the API methods

The API web methods are located in \wfgen\ws\processesruntime.asmx.

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.

WorkflowContext example:

<NewDataSet>
    <parameter>
        <name>COMPANY</name>
        <dataType>TEXT</dataType>
        <direction>OUT</direction>
        <textValue>My company</textValue>
    </parameter>
    <parameter>
        <name>AMOUNT</name>
        <dataType>NUMERIC</dataType>
        <direction>OUT</direction>
        <numericValue>1000</numericValue>
    </parameter>
    <parameter>
        <name>APPROVAL_DATE</name>
        <dataType>DATETIME</dataType>
        <direction>OUT</direction>
        <dateTimeValue>2013-11-18T16:11:51-05:00</dateTimeValue>
    </parameter>
    <parameter>
        <name>ATTACHMENT</name>
        <dataType>FILE</dataType>
        <direction>OUT</direction>
        <fileName>report.xls</fileName>
        <fileDescription>My report</fileDescription>
        <fileSize>202345</fileSize>
        <fileContentType>application/vnd.ms-excel</fileContentType>      
        <fileDateLastModified>2015-10-15T16:11:51-05:00</fileDateLastModified>
        <fileOriginalPath>C:\myfolder\report.xls</fileOriginalPath>
        <filePath>C:\myfolder\report.xls</filePath>
    </parameter>
</NewDataSet>

WorkflowContext creation with WorkflowGen.My

To simplify WorkflowContext creation and modification, you can use WorkflowGen.My and its WorkflowGen.My.Data.ContextParameters class

For more information, see the Web Services API WorkflowContext specifications and usage topic.

Invoking a WorkflowGen API using .NET code

Sample code to complete a request action:

string workflowContextXml; // string to get the xml context data

// Create a new WorkflowGen object for context parameters
WorkflowGen.My.Data.ContextParameters myWorkflowContextParameters = new WorkflowGen.My.Data.ContextParameters();

// Get the xml context data into variable
workflowContextXml = myWorkflowContextParameters.GetXml();

// ID of the request
int RequestID = 1374

// ID of the activity to complete
int ActivityID = 4

wsAPI = new WFG_APIs.RuntimeService();
wsAPI.Credentials = new NetworkCredential("USERNAME", "PASSWORD","");

try
{

    wsAPI.CompleteActivityInstance(RequestID, ActivityID, workflowContextXml.ToString());
    
    Response.Write("OK – Action Completed");

}

catch (Exception exN)
{
    Response.Write("Error = " + exN.Message.ToString() + exN.StackTrace.ToString());
}

For more information, see the How to invoke a WorkflowGen API using .NET code topic.

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. It applies to WorkflowGen versions 5 and 6. See the How to launch a new request with context parameters from an external application via the web service API using SOAP topic and follow the instructions for your version of WorkflowGen.

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 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 Web Services API: StartProcess: Launch a process on behalf of another user topic.

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 web.config file, you can edit the following key to authorize WorkflowGen administrators to use the secured web methods:

<add key="ProcessesRuntimeWebServiceAllowedUsers" value="wfgen_admin,MYDOMAIN\myusername" />

The value contains a comma-separated list of usernames. The username must be prefixed by the domain name according to your authentication method. For more information, see the Web Services API: SoapException “Security: You are not authorized to use this web service” topic.

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:

http://localhost/wfgen/ws/ProcessesRuntime.asmx/GetActivityInstanceList?query=closed&datalist=REQUEST_SUBJECT,FORM_ARCHIVE

Process data

Get associated data of a request and download the associated attachments

See the Web service: How to get associated data of a request and download the associated attachments topic for information on how to do this.

Update process instance data

The UpdateProcessInstanceData web method allows you to update associated data to a request in progress from an external application. It is restricted to allowed users as defined in the ProcessesRuntimeWebServiceAllowedUsers entry in the web.config file. Only requests in progress can be updated.

See the Web Services API: Update Process Instance Data topic for more information.

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. See the Web Services API: User Impersonation with ImpersonateUsername parameter topic for more information.