Establishing a Process Engine session

To establish or log on to a PE session, the following elements are required: 򐂰 A connection point must be specified.

򐂰 The Content Engine (CE) host must be accessible.

򐂰 The CE host Uniform Resource Identifier (URI) must be set.

Connection point

A connection point name identifies a specific isolated region in the workflow database connecting the PE API to an associated isolated region. A defined connection point consists of a PE server, communications port, and isolated region number.

For Process Engine Web Service (PEWS) clients, the PE connection point must be specified in the SOAP header request using the

router

element. If no router value is specified, the default value is used. The default connection point for the Process Engine Web Service is

PEWSConnectionPoint

5.2.1 Java API scenario

The VWSession object establishes a session and logs onto the PE. This object allows the caller to query rosters and queues, retrieve lists of roster and queue names, and administer the system.

PE relies on CE for authentication and directory service access operations. For further details about the available transport protocols, see the CE transport protocols from Chapter 3, “Introduction to Content Engine API programming” on page 39.

The PE Java API offers two data transport layers for connecting to CE, the native Enterprise JavaBeans (EJB) transport that is offered by the application server or the Content Engine Web Services (CEWS) transport.

Note: The CE URI is not needed for Process Engine Web Service (PEWS)

connections. The PEWS is deployed as part of the CE enterprise application.

PE API usage tips: Performance improvements can be achieved by

minimizing the number of Remote Procedure Calls (RPCs) to the PE. Methods that fetch data or cause certain action to occur typically cause RPCs to the PE server, whereas methods that get and set data are local to the object.

Setting the Content Engine URI

The CE URI can be specified in any of the following ways:

򐂰 Call VWSession.setBootstrapCEURI to specify the URI as a String. 򐂰 Call VWSession.setBootstrapConfiguration to specify the URI as an

InputStream.

򐂰 Specify the value of the system property filenet.pe.bootstrap.ceuri. 򐂰 Specify the value of the

RemoteServerUrl

WcmApiConfig.properties located in your application's class path.

Table 5-4 shows the possible CE URIs to be used depending on the selected connection transport and application server where CE is deployed.

Table 5-4 Content Engine connection URIs

Authentication

This section assumes the authentication mechanism between CE and the directory service is properly configured.

Example 5-1 on page 121 shows how to create the VWSession object, set the CE URI, and log on to the PE passing the required parameters.

Protocol URI

Web services http://<server>:<port>/wsi/FNCEWS40MTOM/ EJB/WebSphere iiop://<server>:<port>/FileNet/Engine

EJB/Weblogic t3://<server>:<port>/FileNet/Engine EJB/Jboss jnp://<server>:<port>/FileNet/Engine

Note: You might sometimes see CE connection URIs with a prefix of cemp:. This prefix is for historical purposes only and is ignored by the PE APIs. When you are specifying URIs directly, there is no reason to use that prefix.

Example 5-1 Getting the initial connection using Java API

// User Information

String userName = "Administrator"; String password = "filenet"; // Connection Point

String connectionPoint = "CEPoint"; // Create a Process Engine Session Object VWSession myPESession = new VWSession(); // Set Bootstrap Content Engine URI

myPESession.setBootstrapCEURI("iiop://ceserver:2809/FileNet/Engine"); // Log onto the Process Engine Server

myPESession.logon(userName, password, connectionPoint);

Session logoff

The session’s logoff method ends the session with the PE and frees all resources.

Although the system calls this method internally, an explicit call makes

finalization more immediate and certain, as shown in Example 5-2. Otherwise, finalization is uncertain even when the Java virtual machine (JVM) shuts down.

Example 5-2 Log off from Process Engine using Java API

// Log off from the Process Engine myPESession.logoff();

5.2.2 PEWS API scenario

Unlike the PE Java API, the Process Engine Web Service (PEWS) API

implements only the Web services transport for communicating with the CE. In fact, that connectivity is implicit because the PEWS server is collocated in the same J2EE application as the CEWS server.

The PEWS URL must be specified by the client in order to lookup for the PEWS Web Service Description Language (WSDL) available through the CE.

The URL for the Process Engine Web Service is as follows: http://content_engine_host:port/wsi/ProcessEngineWS

The SOAP header request must include the correct elements and values, such as account credentials. These credentials are verified when functional operations are attempted. Example 5-3 shows how to initialize the PEWS object and set the correct parameter values including the request SOAP context.

Example 5-3 Creating a PEWS RequestSoapContext header using a C# client

// User Information

string userName = "Administrator"; string password = "filenet"; // Connection Point Value

string connectionPoint = "CEPoint"; // URL for the PEWS

string wsUrl = "http://ceserver:9080/wsi/ProcessEngineWS"; // PE Web Service Policy

private static Policy pePolicy = new Policy(new PolicyAssertion[] {new PEAssertion(),new PESecurityAssertion()}); // Create the WS Service Port object

peWS.ProcessEngineServiceWse peWSServicePort = new peWS.ProcessEngineServiceWse();

// Set PE Web Service Policy

peWSServicePort.SetPolicy(pePolicy);

// Set connection point name and wsURL parameters

peWSServicePort.RequestSoapContext["router"]=connectionPoint; peWSServicePort.Url = wsUrl;

// Create User Context for the RequestSoapContext

SecurityToken tok = new UsernameToken(userName, password, PasswordOption.SendPlainText);

UserContext.SetProcessSecurityToken(tok);

See Chapter 7, “Sample applications for Fictional Auto Rental Company A” on page 223.

5.2.3 REST API scenario

For the REST API, there is no explicit PE logon action, however, the REST API resource requests require the calling client to be authenticated with the

application server container. The HTTP Basic authentication is supported as the default authentication method. The HTTP Basic authentication passes credentials in the clear, so you should secure the connection with Transport Layer Security and Secure Sockets Layer (TLS/SSL) or other means.

The client's authorization for accessing REST operations on a specified resource is determined by the permissions that are assigned to the resource.