Chapter 7   Web Services

This chapter describes how you can create client applications that use web services to communicate with iPlanet Process Manager applications. It provides an overview of the Simple Object Access Protocol (SOAP), describes the type of web services functionality provided by Process Manager, and shows how to create SOAP client applications.

Overview of SOAP and WSDL

---

iPlanet Process Manager provides web services using the Apache implementation of the Simple Object Access Protocol (SOAP) specification. SOAP is an XML-based protocol for the exchange of information in a decentralized, distributed environment. Refer to the iPlanet Process Manager Release Notes for the version of Apache SOAP that is supported for this release.

SOAP messages are XML documents that are typically exchanged over the HTTP transport. SOAP messages consist of a SOAP envelope (which defines the framework for the contents of a message), SOAP encoding rules (which define how instances of objects are serialized and marshalled between applications), and the SOAP RPC representation (which defines the conventions for remote procedure calls and responses). Process Manager handles the details of creating SOAP messages for you, including specifying the SOAP encoding rules and building the SOAP remote procedure calls and responses.

The Web Services Description Language (WSDL) is a specification that uses XML documents to describe web services. A WSDL file encodes network service information such as ports, messages, operations, and binding. You typically use a WSDL file as input to third-party utilities to generate stub code, which can then be used to create SOAP client applications.

For more information about the SOAP protocol, refer to http://www.w3.org/TR/SOAP. For information on the version of SOAP implemented by iPlanet Process Manager, refer to the iAS EPE Release Notes, available at http://docs.sun.com/prod/s1.ipaspro/. For more information on the WSDL specification, refer to http://www.w3.org/TR/wsdl.

Terminology

Compound Data Type   

In SOAP encoding style, a compound type is a composite type, with each part being either a SOAP basic type or another compound type ultimately derived from SOAP basic types. SOAP uses compound data types to serialize objects passed in SOAP messages.

Simple Data Type   

In SOAP encoding style, a simple type is scalar data type.

SOAP   

The Simple Object Access Protocol specifies a way to exchange information in a decentralized, distributed environment. SOAP encodes messages as XML documents containing three parts: an envelope providing information about the message and how to process it, a set of encoding rules that defines objects included in the message, and a convention for representing remote procedure calls and responses. SOAP messages are typically sent using the HTTP/HTTPS protocols. iPlanet Process Manager handles the creation, sending, and decoding of SOAP messages for iPM applications. For more information on SOAP, refer to http://www.w3.org/TR/SOAP.

Skeleton   

Code generated when compiling a WSDL file. Skeleton code can be used to implement a server application that exports web services. WSDL compilers are available from various vendors and for various programming languages.

SOAP Fault   

A SOAP Fault is an element of a SOAP message that contains error and/or status information. If present, the SOAP Fault appears within the body of a SOAP message.

Stub   

Code generated from compiling a WSDL file. Stub code can be used to implement a client application that accesses web services made available from a server application. WSDL compilers are available from various vendors and for various programming languages.

WSDL   

The Web Services Description Language is a specification that uses XML documents to describe Web services. A WSDL file typically encodes network service information such as ports, messages, operations, and binding. iPlanet Process Manager provides a WSDL file that you can use as a starting point for creating your own SOAP clients to Process Manager. For more information on the WSDL specification, refer to http://www.w3.org/TR/wsdl.

iPM Web Services Architecture

---

Figure 7-1 illustrates how SOAP client applications access a Process Manager application.

Figure 7-1    iPM Web Services Architecture

Process Manager exposes web services that allows SOAP clients to perform operations on a process in an iPM cluster. SOAP clients call into the web services using Apache SOAP.

An Apache SOAP client is a Java application that uses Apache SOAP services to call into the Web Services API. A WSDL SOAP client is a client application created from stubs generated when compiling the iPM WSDL file provided with your Process Manager distribution. The following section, "Web Services Environment," describes the configuration files provided with your distribution to set up Process Manager for web services.

Web Services Environment

---

This section describes how to set up Process Manager to implement web services. It first discusses the configuration files provided with your distribution. It then describes how to configure your environment to use iPM Web Services.

Web Services Configuration Files

Table 7-1 lists configuration files that are provided with your Process Manager distribution. The following section, "Environment Setup," describes how these files are used when setting up your web services environment. In this table, <IPM_ROOT> indicates the root of your Process Manager installation.

Table 7-1    iPM Web Services Configuration Files  

File	Location (relative to <IPM_ROOT>)	Description
DeploymentDescriptor.xml	bpm/soap/apache-2_2	Used by Process Manager to export web services for iPM applications.
PMService-service.wsdl	bpm/soap/wsdl/	Used to generate stubs for WSDL clients. You must customize this file to indicate the host name and port for your installation.
PMService.wsdl	bpm/soap/wsdl/	Used when generating stubs for WSDL clients. This file specifies the iPM operations available as web services.
PMService.xsd	bpm/soap/wsdl/	Used when generating stubs for WSDL clients. This file specifies the iPM data types available for web services.
ipmsoap-2_2.jar	bpm/soap/	Process Manager supplied patch to Apache SOAP.
pm65soap.jar	bpm/soap/	Used by Apache SOAP clients to access web services classes exported by Process Manager.

Environment Setup

Configuring your environment to use Process Manager Web Services consists of the following steps:

• Setting up Process Manager to use web services
• Setting up the development environment for Apache SOAP client applications
• Setting up the runtime environment for Apache SOAP client applications
• Editing the provided WSDL file for WSDL client applications

Setting Up iPM to use Web Services

The following procedure describes how to set up Process Manager to use web services.

To Set Up Process Manager to Use Web Services:

1. Create a default iPM cluster.
2. Unjar ipmsoap-22.jar into the directory listed below:

<IAS_ROOT>/ias/APPS/modules/soap/WEB-INF/classes

IAS_ROOT is the root of your application server installation.

3. Edit the deploy script in your Apache SOAP installation as follows:

On Windows platforms, edit the deploy.bat file. On Solaris, edit the deploy script. In each case, change IAS_HOME and CLASSPATH to point to the correct path in your environment.

4. Deploy iPM Web Services by doing the following:

cd <IPM_ROOT>/bpm/soap/apache-2_2/
deploy DeploymentDescriptor.xml

IPM_ROOT is typically located at <IAS_ROOT>/iplanet/ipm65.

5. Verify that iPM Web Services is installed by launching the Apache SOAP Administrator, available at the following URL:

http://<host>/NASApp/soap/admin/

The service iPM65WS should be listed in this screen.

Development Environment for Apache SOAP Clients

For developing (compiling) Apache SOAP clients, environment considerations include the following:

• Java Development Kit (JDK) version
• SOAP implementation version
• XML parser
• CLASSPATH properly configured to access SOAP and XML parser libraries
• ipmsoap-2_2.jar must appear before pm65soap.jar in your CLASSPATH

For information on specific versions supported, refer to the Process Manager Release Notes available at the following location:

http://docs.sun.com/prod/s1.ipaspro/

Runtime Environment for Apache SOAP Clients

The runtime environment considerations for Apache SOAP clients include the following:

• Java Runtime Environment (JRE) version
• CLASSPATH properly configured to access pm65soap.jar

For information on specific versions supported, refer to the Process Manager Release Notes available at the following location:

http://docs.sun.com/prod/s1.ipaspro/

Environment for WSDL Clients

You must modify the PMService-service.wsdl file provided with your distribution to specify the host and port for web services. In this file, edit the following line so host:port reflect the URL of the Apache SOAP service running on an iAS cluster.

<soap:address location="http:/host:port/NASApp/soap/rpcrouter"/>

Limitations Using SOAP with iPlanet Process Manager

When using SOAP services to access the process manager, keep in mind the following limitations:

• iPM expects SOAP messages in the SOAPRPC style, not the document style
• SOAP header and SOAP message chaining are not supported
• Functionality is limited to the web services exposed by Process Manager
• Data type conversion is limited to corresponding Process Manager data types
• Digital signature fields and file attachments for data elements are not supported
• Serialization and deserialization of iPM custom fields is not supported

This means custom fields cannot be used in a SOAP call involving saveActivity or completeActivity

• There is no authentication associated with calls to iPM Web Services

However, iPM Web Services does performs role resolution and allows (or disallows) certain tasks based on the AccessControl mechanism built into the Form ACL in the Process Builder. For example, a call to completeActivity succeeds only if the remoteUser passed in is actually an assignee or belongs to a Role that is an assignee to the Activity being completed.

• The completeActivity method can only be used with activities that have simple assignments (that is, a single user assigned to the activity)

WorkItems that have group assignments (use toGroup) or dynamic assignments that have resulted through the use of addAssignee calls cannot be handled by web services clients.

Creating Web Services Clients

---

You can create web services clients for iPlanet Process Manager either by creating an Apache SOAP client or by using code generated when compiling the iPM WSDL file provided with your Process Manager distribution. The following section, "Creating a Client Using the WSDL File", describes the procedure for creating a WSDL client. The section, "Creating an Apache SOAP Client" describes how to create an Apache SOAP client.

Typical Web Services Client Application

Typically, an iPM web services client creates a process instance for a specific entry point in a process. The client then performs an available activity for that process. The following steps list key iPM Web Services calls you make in the client to complete an activity for a process instance.

1. Get the entry point into your Process Manager application.

Here are a series of method calls that are useful in finding an entry point into a Process Manager application, creating a process instance, and completing the activity.

• getClusterNames

To get a list of the cluster names running in an iAS process instance.

• getApplicationNames

From a specific cluster, get a list of the applications deployed on that cluster.

• getEntryPointNames

From a specific application, get a list of the entry points into the application.

• getEntryPointData

From a specific entry point, gets a list of the editable data elements.

2. Create a process instance.

Using information from the previous step, call createProcessInstance to create a process instance.

3. For the given process, complete an activity.

Here are a series of calls that are useful in finding and completing an activity for a process instance.

• getActivityInfoList

Returns the worklist on a given cluster for a user. You can use this list to find specific activities.

• getActivityData

Returns a list of data elements associated with an activity. You can use this list to perform work on the given activity.

• completeActivity

Performs the specified action for a user activity.

Creating a Client Using the WSDL File

This section describes how to create a web services client using the following WSDL files provided with your distribution at iASROOT/soap/wsdl/.

• PMService.wsdl

Describes the web services methods available to access any iPM application.

• PMService.xsd

Describes the data types available to web services clients.

• PMService-service.wsdl

Used by third party applications to compile the WSDL files into stubs that can be used to create web services client applications. This file must be edited to reflect your iPM application's host name and port number, as described in "Environment for WSDL Clients".

To create a web services client, compile PMService-service.wsdl using a WSDL compiler compliant with the version of SOAP certified for this release. Using the stub files generated by the WSDL compiler, create your web services client application.

Creating an Apache SOAP Client

This section describes how to create an Apache SOAP client application. It lists the Java methods and classes available to clients from the iPM Web Services API. It also contains a running code example that shows how an Apache web services client can call into an iPM application. This example assumes you have set up your environment to use Apache SOAP, as described in "Development Environment for Apache SOAP Clients", and that you have deployed an iPM application to be invoked by a web services client. Finally, this section contains a description of the sample Apache SOAP client application provided with your Process Manager distribution.

iPM Web Services API for Apache SOAP Clients

This section lists the iPM Web Services methods available to Apache SOAP client applications. Table 7-2 lists the methods available to your client applications.

Table 7-2    iPM Web Services Methods available to Apache SOAP Clients 

completeActivity	getClusterInfo
createProcessInstance	getClusterNames
getActivityData	getEntryPointData
getActivityInfo	getEntryPointNames
getActivityInfoList	getProcessInfo
getApplicationNames	saveActivity

completeActivity

Completes the specified action associated with a user activity, saving the data associated with the activity. This action corresponds to a remote user completing and submitting a form, and then moving the process to the next stage.

Typically, you first call getActivityData to get a list of data elements for the activity, set the data for each element in the returned data list, and then call completeActivity.

void completeActivity(IWFActivityID activityID, String remoteUser,
IWFDataList datalist, String action)  

activityID	ID of the activity.
remoteUser	Authorized user for the application.
datalist	List of IWFData elements associated with the activity. This list of data elements should be obtained by a prior call to getActivityData. You should first call IWFData.setValue on each data element in the list before completing the activity. For more information on setValue, refer to "IWFData".
action	Name of the action being performed.
Exception	Generates a SOAP fault if the operation does not succeed.

createProcessInstance

Creates a process instance at a specific entry point in the process.

Typically, you first call getEntryPointData to get a list of data elements for the specified action in the process, set the data for each element in the returned data list, and then call createProcessInstance.

IWFProcessInfo createProcessInstance (String clusterName, String appName,
String entryNodeName, String remoteUser,
String actionName, IWFDataList datalist)  

clusterName	Name of the cluster containing the deployed applications. Specify "PMCluster" if you are working with process applications deployed to a default cluster, otherwise specify the name of the named cluster.
appName	Name of the application deployed to the cluster.
entryNodeName	Entry point name of the application (previously returned by a call to getEntryPointNames).
remoteUser	Authorized user for the application.
actionName	Name of the action being performed at the entry point. This represents one possible transition emanating from the entry point node.
datalist	List of IWFData elements associated with the action. This list of data elements should be obtained by a prior call to getEntryPointData. You should first call IWFData.setValue for each element in the list before creating the process instance. For more information on setValue, refer to "IWFData".
Exception	Generates a SOAP fault if the operation does not succeed.

getActivityData

Returns the list of editable data elements associated with a user activity. You can change the value of these data elements and then pass the list into a call to saveActivity or completeActivity. Before calling saveActivity or completeActivity, you should first call IWFData.setValue for each item in the returned list. For more information on setValue, refer to "IWFData".

IWFDataList getActivityData(IWFActivityID activityID, String remoteUser)  

activityID	ID of the activity.
remoteUser	Authorized user for the application.
Exception	Generates a SOAP fault if the operation does not succeed.

getActivityInfo

Returns a user activity based on a primary key and a remote user (for role resolution). For more information on the IWFActivityInfo class, refer to "IWFActivityInfo"

IWFActivityInfo getActivityInfo(IWFActivityID activityID, String remoteUser)  

activityID	ID of the activity.
remoteUser	Authorized user for the application.
Exception	Generates a SOAP fault if the operation does not succeed.

getActivityInfoList

Returns the worklist for a remote user within the context of a given iPM cluster.

IWFActivityInfoList getActivityInfoList(String clusterName, String remoteUser)  

clusterName	Name of the cluster containing the deployed applications. Specify "PMCluster" if you are working with process applications deployed to a default cluster, otherwise specify the name of the named cluster.
remoteUser	Authorized user for the application.
Exception	Generates a SOAP fault if the operation does not succeed.

getApplicationNames

Returns the list of strings representing the names of deployed applications available on an iPM cluster.

IWFAppNamesList getApplicationNames(String clusterName)  

clusterName	Name of the cluster containing the deployed applications. Specify "PMCluster" if you are working with process applications deployed to a default cluster, otherwise specify the name of the named cluster.
Exception	Generates a SOAP fault if the operation does not succeed.

getClusterInfo

Returns the properties of a given cluster. For more information on cluster properties, refer to "IPMClusterProperty". This method returns a limited list of cluster properties

For more information on the IWFClusterInfo class, refer to "IWFClusterInfo".

IWFClusterInfo getClusterInfo(String clusterName)  

clusterName	Name of the cluster containing the deployed applications. Specify "PMCluster" if you are working with process applications deployed to a default cluster, otherwise specify the name of the named cluster.
Exception	Generates a SOAP fault if the operation does not succeed.

getClusterNames

Returns the names of iPM clusters available on an iAS cluster.

IWFClusterNamesList getClusterNames()  

Exception

Generates a SOAP fault if the operation does not succeed.

getEntryPointData

Returns a list of editable data elements associated with a specific entry point node of a process application. Role resolution is performed to check if the remote user has access at the entry point. From the returned IWFDataList, you should change only the value of elements in the IWFDataList.

You typically use the returned data list when creating a process instance (by calling createProcessInstance). Before creating the process instance, you should first call IWFData.setValue on each element of the returned list. For more information on setValue, refer to "IWFData".

IWFDataList getEntryPointData(String clusterName, String applicationName,
String entryPointName, String remoteUser)  

clusterName	Name of the cluster containing the deployed applications. Specify "PMCluster" if you are working with process applications deployed to a default cluster, otherwise specify the name of the named cluster.
applicationName	Name of the application deployed to the cluster.
entryPointName	Entry point for the application.
remoteUser	Authorized user for the application.
Exception	Generates a SOAP fault if the operation does not succeed.

getEntryPointNames

Returns the list of entry point names for the given application, which is deployed on the given cluster for the given user

IWFEntryPointNamesList getEntryPointNames(String clusterName,
String applicationName, String remoteUser)  

clusterName	Name of the cluster containing the deployed applications. Specify "PMCluster" if you are working with process applications deployed to a default cluster, otherwise specify the name of the named cluster.
applicationName	Name of the application deployed to the cluster.
remoteUser	Authorized user for the application.
Exception	Generates a SOAP fault if the operation does not succeed.

getProcessInfo

Returns the information in a Process Instance, based on the Process Instance primary key. For more information on the IWFProcessInfo class, refer to "IWFProcessInfo".

IWFProcessInfo getProcessInfo(IWFProcessID processID)  

processID	ID of the process instance.
Exception	Generates a SOAP fault if the operation does not succeed.

saveActivity

Saves the data associated with a user activity. saveActivity does not complete the activity (move it to the next step).

Typically, you first call getActivityData to get a list of data elements for the activity, set the data for each element in the returned data list, and then call saveActivity.

void saveActivity(IWFActivityID activityID, IWFDataList datalist, String remoteUser)  

activityID	ID of the activity.
data	List of data elements associated with the activity. This list of data elements should be obtained by a prior call to getActivityData. You should first call IWFData.setValue on each data element in the list before saving the activity. For more information on setValue, refer to "IWFData".
remoteUser	Authorized user for the application.
Exception	Generates a SOAP fault if the operation does not succeed.

iPM Web Services Classes for Apache SOAP Clients

This section describes the classes used by Apache SOAP clients that access the iPM Web Services API. It provides a brief description of the class and lists the available accessor and mutator methods.

Table 7-3    iPM Web Services Classes for Apache SOAP Clients 

IWFActivityID	IWFClusterNamesList
IWFActivityInfo	IWFData
IWFActivityInfoList	IWFDataList
IWFAppNamesList	IWFEntryPointNamesList
IWFAssignee	IWFProcessID
IWFAssigneeList	IWFProcessInfo
IWFClusterInfo

IWFActivityID

Represents the unique identifier of a process activity in a running cluster.

Methods	Description
String getActivityName()	Returns the name of the node the activity belongs to.
String getApplicationName()	Returns the name of the application that this activity belongs to.
String getClusterName()	Returns the name of the cluster that the activity belongs to.
String getForkId()	Returns the fork Id of the activity.
long getInstanceId()	Returns the ID of the Process Instance that this activity belongs to.

IWFActivityInfo

Represents a process activity inside a cluster.

Methods	Description
IWFActivityID getActivityId()	Returns the unique identifier of the activity.
String getApplicationName()	Returns the name of the application that the activity belongs to.
IWFAssigneeList getAssignees()	Returns a list of current assignees of the activity.
java.util.Date    getCreationDate()	Returns the creation date of the activity.
java.util.Date    getExpirationDate()	Returns the expiration date of the activity (if one has been set).
IWFProcessInfo    getProcessInfo()	Returns the process instance that this activity belongs to.
int getState()	Returns the running state of the activity.
boolean hasExpired()	Tests whether the activity has expired.
boolean isAutomated()	Tests whether the activity is automated.
boolean isInExceptionState()	Tests whether the activity is in exception state.

IWFActivityInfoList

List of IWFActivityInfo elements.

Methods	Description
void addElement(IWFActivityInfo data)	Adds an IWFActivityInfo element to the list.
Iterator elements()	Returns an iterator for the list.
boolean exists(IWFActivityInfo data)	Tests whether the specified IWFActivityInfo element exists in the list.
IWFActivityInfo getElement(IWFActivityID id)	Returns the IWFActivityInfo element from the list specified by the given ID.
boolean isEmpty()	Tests if the list is empty.
void removeElement(IWFActivityInfo data)	Removes an IWFActivityInfo element from the list.

IWFAppNamesList

The list of application names on an iPM cluster. Typically, you do not make any modifications to this list.

Methods	Description
void addElement(String data)	Adds an application name to the list.
Iterator elements()	Returns an iterator for the list.
boolean exists(String name)	Tests whether the named application exists in the list.
boolean isEmpty()	Tests if the list is empty.
void removeElement(String data)	Removes an application name from the list.

IWFAssignee

An abstraction for a Process Manager role or user.

Methods	Description
String getType()	Returns the role or user.
String getValue()	Returns the name of the role or user.

IWFAssigneeList

List of IWFAssignee elements.

Methods	Description
void addElement(IWFAssignee data)	Adds an IWFAssignee element to the list.
Iterator elements()	Returns an iterator for the list.
boolean exists(IWFAssignee data)	Tests whether the specified IWFAssignee element exists in the list.
IWFAssignee getElement(String name,    String type)	Returns the IWFAssignee element from the list that is specified by both name and role/user.
boolean isEmpty()	Tests if the list is empty.
void removeElement(IWFAssignee data)	Removes an IWFAssignee element from the list.

IWFClusterInfo

The properties of a cluster.

Methods	Description
String getProperty(String key)	Returns the value of a cluster property specified by the given key. Valid values for key are listed in Table 7-4.
Enumeration properties()	Returns an enumeration of the cluster properties.

Table 7-4    Key List of Cluster Properties  

CLUSTER_DN	DATABASE_IDENTIFIER
CLUSTER_NAME	DATABASE_NAME
CONFIGURATION_DIRECTORY_SERVER	DATABASE_USER_NAME
CONFIGURATION_DIRECTORY_PORT	DATASOURCE_NAME
CONFIGURATION_DIRECTORY_BIND_DN	DESCRIPTION
CORPORATE_DIRECTORY_SERVER	PRETTY_NAME
CORPORATE_DIRECTORY_PORT	SMTP_SERVER
CORPORATE_DIRECTORY_BASE	SMTP_PORT
CORPORATE_DIRECTORY_BIND_DN	SMTP_REPLY_TO
DATABASE_TYPE	EVENT_USER

IWFClusterNamesList

A list of cluster names on an iPM installation. Typically, you do not make any modifications to this list.

Methods	Description
void addElement(String data)	Adds the specified element to the list.
Iterator elements()	Returns an iterator for the list.
boolean exists(String name)	Tests whether the named cluster exists in the list.
boolean isEmpty()	Tests if the list is empty.
void removeElement(String data)	Removes an cluster name from the list.

IWFData

Represents a data dictionary element of the process application. The getActivityData and getEntryPointData methods of the iPM Web Service API returns a list containing these data elements (an IWFDataList). The IWFDataList represents fields in an HTML form or Process Manager activity.

Before using an IWFDataList in subsequent calls, you must set the data for each element in the list using IWFData.setValue.

---

Note

When calling setValue, make sure the value passed in is a valid value for the data field. Process Manager throws an exception only if the value does not match the allowed type, as described in Table 7-5. For example, if you specify text for the value of a CheckBox, an exception is thrown. However if you specify the value 2 for the value of a CheckBox, the error will not be caught or reported, and may cause the process to misbehave.

---

setValue must be called before you do the following:

• Create a process instance (using the iPM Web Services API createProcessInstance), to initialize the values of data fields for work items in the process
• Complete or save an activity (using the iPM Web Services APIs completeActivity or saveActivity), to first load the values of data fields for work items before completing or saving an activity.

For more information on the iPM Web Services API, refer to "iPM Web Services API for Apache SOAP Clients".

Methods	Description
String getName()	Returns the name of the data element.
String getType()	Returns the type of the data element, for example TYPE_TEXT. The type is typically built dynamically by the server and returned by calls to iPM Web Service APIs such as getActivityData.
Object getValue()	Returns a String representation of the data element in the process dictionary. Complex types represented by custom fields are not supported.
void setValue(String name,              Object value)	Initializes or sets the data element in the process dictionary. name is the name of the field for the data element, value is the value associated with the field. value must correspond to allowed values for the field represented by the data element, otherwise an exception is thrown. Refer to the following table for expected values for different data fields.

Table 7-5    Valid Values for Data Fields  

iPM Field Type	Significance	Allowed Types	Valid Values
CheckBox	checked/unchecked	Integer	0 - not checked 1 - checked
ComputedField	value	Text LongText Date DateTime Integer Float	Valid value for the specified type
Date	date	Date	a date in the format: DDMMYY or MMDDYY
DateTime	date time	Date	date in the format: DDMMYY:HHMMSS or MMDDYY:HHMMSS
Password	password	Text	Clear text password
Radio Buttons	valid option from the list	Text LongText Date DateTime Integer Float	Valid value for the specified type
Select List	valid selection from the list	Text LongText Date DateTime Integer Float	Valid value for the specified type
TextArea	value from text area	Text	Text data. For size limitations on this field, refer to the Process Builder's Guide.
TextField	value from the text field	Text	Text data. For size limitations on this field, refer to the Process Builder's Guide.
URL	value from the URL field	Text	A valid URL, for example: http://www.sun.com
UserPickerWidget	user ID	Text	A valid corporate directory user ID, for example: admin/admin21

IWFDataList

Represents a list of IWFData elements. Refer to "IWFData" for more information on using an IWFDataList.

Methods	Description
void addElement(IWFData data)	Adds an IWFData element to the list.
Iterator elements()	Returns an iterator for the list.
boolean exists(IWFData data)	Checks if a specified IWFData element is in the list.
IWFData getElement(String name)	Returns a specified IWFData element from the list.
boolean isEmpty()	Test if the list is empty.
void removeElement(IWFData data)	Removes a IWFData element from the list.

IWFEntryPointNamesList

List of entry point names on an iPM Application. Typically, you do not make any modifications to this list.

Methods	Description
void addElement(String data)	Adds the specified element to the list.
Iterator elements()	Returns an iterator for the list.
boolean exists(String name)	Tests whether the named entry point exists in the list.
boolean isEmpty()	Tests if the list is empty.
void removeElement(String data)	Removes an entry point name from the list.

IWFProcessID

The unique identifier of a process instance in a running cluster.

Methods	Description
String getApplicationName()	(Optional) Returns the name of the process application this instance belongs to.
String getClusterName()	Returns the name of the cluster this instance was created in.
long getInstanceID()	Returns the ID of the process instance.

IWFProcessInfo

Represents an instance of a process.

Methods	Description
java.util.Date    getCreationDate()	Returns the date the process instance was created.
String getCreator()	Returns the ID of the creator of the process.
String getApplicationName()	Returns the name of the application that the process belongs.
String getEntryPointName()	Returns the entry point at which the process instance was initiated.
String getExitPointName()	Returns the exit point at which the process completed.
java.util.Date    getLastModifiedDate()	Returns the date of the last modification to data of the process instance.
IWFActivityID    getParentProcessId()	Returns a unique identifier of the parent process (relevant only for subprocesses)
IWFProcessID getProcessId()	Returns a unique identifier of the process instance.
int getState()	Returns the running state of the process instance (for more information, refer to the Javadoc API documentation for com.netscape.pm.model.IProcessInstance)

Creating an Apache SOAP Client Application

This section contains code examples that illustrate the basic steps in creating an Apache SOAP client.

Set Up the Web Services Class

The first step is to set up import statements and declare your class, as you would for any Java application. Code Example 7-1 shows one way to do this.

---

Code Example 7-1    Building a Web Services Call—Set up the Web Services Class  

package samples.wstest;

import java.io.*;

import java.net.*;

import java.util.*;

import org.apache.soap.*;

import org.apache.soap.rpc.*;

public class wstest {

public static void main (String[] args) throws Exception {

if (args.length != 1 ) {

System.err.println ("Usage: java " +

wstest.class.getName() +

"SOAP-router-URL");

System.exit (1);

}

// Process the arguments.

URL url = new URL (args[0]);

. . .

---

Create a Call Object

Next, create a Call object that you later use to invoke iPM Web Services API methods.

---

Code Example 7-2    Building a Web Services Call—Create a Call Object  

. . .

// Set up the call

Call call = new Call ();

SOAPMappingRegistry smr = call.getSOAPMappingRegistry() ;

String pmNsURI =

"http://www.iplanet.com/ipm6/serviceapi/wsdl";

String encodingStyle =

"http://schemas.xmlsoap.org/soap/encoding/";

. . .

---

Map the Data Type for the Call

You must specify each iPM Web Services data type that you will be using in your call. For more information, refer to the section "IWFData".

---

Code Example 7-3    Building a Web Services Call—Map Data Types  

. . .

// Base Serializer for all iPM complex types .

BaseSerializer ser_0 = new BaseSerializer() ;

// WFDataList Serializer

smr.mapTypes(encodingStyle,

new QName( pmNsURI, "IWFDataList"),

com.sun.processmgr.serviceapi.types.IWFDataList.class,

ser_0, ser_0);

// . . . additional types

. . .

---

Set the Method and Parameters to the Call

Code Example 7-4 sets the method name and builds the parameter list to the method. After building the parameter list, it sets the parameters for the call. In this example, the value for the dataList parameter for the method createProcessInstance should be obtained by a prior call to either getActivityData or getEntryPointData.

Refer to "iPM Web Services API for Apache SOAP Clients" for more information on web services methods exposed by Process Manager. Refer to "iPM Web Services Classes for Apache SOAP Clients" for more information on using iPM Web Services data types.

---

Code Example 7-4    Building a Web Services Call—Set Method  

. . .

call.setTargetObjectURI ( service );

call.setMethodName ( "createProcessInstance" );

String encodingStyleURI = Constants.NS_URI_SOAP_ENC;

call.setEncodingStyleURI(encodingStyleURI);

// Build the data list for the entry point,

// which is needed as a parameter to the method

IWFDataList piData;

piData = new WFDataList ();

piData.addElement(new WFData("title", "TITLE_TEXT",

"My Credit Check"));

piData.addElement(new WFData("person", "TITLE_TEXT",

"admin21"));

// PARAMETERS TO THE CALL

Vector params = new Vector ();

params.addElement (new Parameter("defaultCluster",

String.class, "PMCluster", null));

params.addElement (new Parameter("iPMapp",

String.class, "CreditHistory", null));

params.addElement (new Parameter("entryNode",

String.class, "", null));

params.addElement (new Parameter("remoteUser",

String.class, "", null));

params.addElement (new Parameter("action",

String.class, "PMCluster", null));

params.addElement (new Parameter("dataList",

IWFDataList.class, piData, null));

call.setParams(params);

. . .

---

Invoke the Method and Capture the Return Value

Now invoke the method on the iPM, check for errors, and capture information returned by the method call.

---

Code Example 7-5    Building a Web Services Call—Invoke Method 

. . .

Response resp = call.invoke (url,"" );

Parameter ack = null ;

// Check the response.

if (resp.generatedFault ()) {

Fault fault = resp.getFault ();

System.out.println("Soap Call failure: ");

System.out.println("Fault Code = " +

fault.getFaultCode ());

System.out.println("Fault String = " +

fault.getFaultString ());

throw new Exception (" SOAP Service Exception :" +

fault.getFaultCode () + ":" +

fault.getFaultString () ) ;

}

else {

ack = resp.getReturnValue ();

}

// process the return data

IWFProcessInfo pi = ack.getValue( ) ;

System.out.println ("Process Instance Id:" +

pi.getProcessId().getInstanceId());

System.out.println ("Process Instance Creation Date :" +

pi.getCreationDate()) ;

System.out.println ("Process Instance Creator :" +

pi.getCreator()) ;

. . .

---

Apache SOAP Client Sample

Your Process Manager distribution includes a sample Apache SOAP client application that instantiates the Credit History application, allowing the user to complete the Check Authorization activity. The sample can be found at the following location in your Process Manager installation:

<IPM_ROOT>/bpm/soap/sample/

This SOAP client provides the same functionality as Process Express for creating and completing the Credit History application. The initial data for process instantiation is pre-configured in a properties file. The sample application then uses the data generated by the Process Engine to complete the activity.

For more information on the Credit History application, refer to the Process Builder's Guide. For more information on calling iPM Web Services APIs in Apache SOAP clients, refer to "iPM Web Services API for Apache SOAP Clients".

Setting Up the Apache SOAP Client Sample

The Apache SOAP client sample assumes the Credit History process definition has been deployed successfully using the Process Builder. It also assumes that the SOAP service related parameters, such as SOAP service location URL and name are specified in the SOAPProperties.conf file. Also, the initial parameters for process instantiation are specified in the CALLParameters.conf file.

The CLASSPATH for the sample should contain pm65soap.jar, to specify SOAP data types and (de)serializers for these types. The CLASSPATH should also include xerces.jar and soap.jar.

iPM Web Services API

The Apache SOAP Client sample creates a process instance and completes the intermediate activities by calling the following iPM Web Services APIs (in the following order):

• getEntryPointData

Specifies the following parameters:

• remoteUser
• defaultCluster
• appName
• entryNodeName

Returns IWFDataList containing the default entry point data, Person, and Title. To override the default entry point data, specify the desired Person name and Title in the CALLParameters.conf file.

• createProcessInstance

Creates a process instance specifying the following:

• configuration data: defaultCluster, appName, entryNodeName
• user data: actionName (for example, Submit) and the entry point data returned from the call to getEntryPointData.

After creating the process instance, the Process Instance Id is displayed. The assignee of the activity can log in through Process Express and verify that a work item has been created corresponding to the user activity node "Check Authorization."

The sample then prompts whether you want to complete the Check Authorization activity (that is, take action on the work item generated). If you specify to not take action, the sample application exits. If you specify to take action, the following choices are displayed:

• Create Report (approval to check authorization)
• Cancel Report (deny authorization request)

When completing the activity, the sample calls the following iPM Web Services APIs (in the following order):

• getActivityData

Returns the activity data corresponding to the user activity "Check Authorization" for this process instance.

• completeActivity

Using the data returned by getActivityData and the actionName (create/cancel report), completes the user activity.

• getProcessInfo

Returns the final state of the process instance.