The workflow engine includes a Web Service for gathering workflow metrics. The addition of the Metrics Web Service to the workflow engine lets you monitor an approval flow process. In addition, it provides indicators the business manager can use to modify the process for optimal performance.
The metrics are based on traditional business process flow management principles, which emphasize the need for metrics to be actionable. This ensures that the metrics provided match what an operations manager usually looks for when analyzing and optimizing business flows. Therefore, the metrics identify bottlenecks and provide other capacity indicators. The Metrics Web Service allows you to narrow down the metrics to a common and established set of data, instead of trying to anticipate the myriad of metrics and reports that can be created for a business process flow.
When working with the Metrics Web Service, you should keep in mind that the service is not intended to be an all-purpose metrics system:
The Metrics Web Service is not a reporting tool or reporting engine. Consequently it does not use a complex query language.
The Metrics Web Service is not designed as an all-purpose performance management system. This helps to limit the impact of the needed queries against the live system being monitored.
Operations management stresses three key internal process performance measures that together capture the essence of process flow. These three measures can serve as leading indicators of customer satisfaction: flow time, flow rate, and inventory.
With these measures, an operations manager can answer the following questions:
On average, how much time does a provisioning request spend within the process boundaries? (Flow time)
On average, how many provisioning requests pass through the process per unit of time? (Flow rate)
On average, how many provisioning requests are within the process boundaries at any point in time? (Inventory)
These three measures are related by Little's law:
Inventory=Flow Rate*Flow Time
The following semantics apply to the use of the Metrics Web Service:
Activities in the Metrics Web Service refer only to user-facing activities (Approval Activities). Negligible running time and the impossibility of controlling the other activities make collecting metrics for these inappropriate.
The Metrics Web Service distinguishes between Working Days and Calendar Days. Calendar Days refer to all days between two dates. Working Days refer only to working days between two dates. Since working days may be specified differently in different environments, all Working Days methods return a raw data set that can be used to compute what is appropriate. If no such detail is required, the Calendar Days method will readily return the appropriate metric.
The Metrics Web Service endpoint can be accessed at the following URL:
http://server:port/warcontext/metrics/service
You can also access the SOAP endpoint by going to the
tab within the User Application. To do this, you need to select the tab, then select from the left-navigation menu. After selecting , pick the Web Service endpoint you want from the list.WARNING:The test page is disabled by default. Since some of the methods allow data to be updated, the test page presents a potential security vulnerability and should not be allowed in a production environment. For details on enabling the test page, see the instructions provided for the Role Service in Enabling the Test Page.
The service is secured using Basic Authentication. Therefore, you should use SSL to connect to the service. The service uses the same security layer as the User Application and consequently not all service operations are allowed to all users. Only a Provisioning Administrator will have unconditional access to all the methods. On the other hand team managers will only have access to metrics that pertain to their team and team members.
Hence the Metrics Web Service operations are divided into 3 categories according to role and security permissions:
Team manager operations
Provisioning Application Administrator operations
Utility operations
Team managers can only retrieve metrics on a team for which they are managers. These are the methods are available to team managers:
Table 21-1 Team Metrics Methods
This role is unrestricted and may perform any of the service's operations. These are the methods that are only available to Provisioning Administrators.
Table 21-2 Provisioning Administrator Metrics Methods
Both team managers and administrators may perform these operations:
Table 21-3 Utility Operations
As mentioned above, the Metrics Webservice does not use a complex query language. Instead filters can be use to narrow results by criteria such as date ranges or approval statuses.
These are the filters you can specify (see type FilterConstants in service’s WSDL):
Table 21-4 Filters for Narrowing Metric Results
Here is a Java example. Note that your code will obviously differ depending on the platform you use for your Web Service client:
HashMap map=new HashMap();
map.put(MetricsFilter.KEY_PROCESS_STATUS,
MetricsFilter.ProcessStatusRunning);
double flowtime = metrics.getFlowTimeCalendarDays(processId,
processVer, activity, 5, calendar1.getTime(),
calendar2.getTime(), MetricsFilter.ACTIVITY_CLAIMED,
MetricsFilter.ACTIVITY_FORWARDED, map);
...
Please consult the WebService WSDL for more information:
http://server:port/warcontext/metrics/service?WSDL
Before using the Web Service, you need to use the WSSDK tool or another SOAP tool kit to generate the stub classes. To allow your code to find the stub classes, you also need to add the JAR that contains the stub classes to your classpath.
If you want to use the Novell WSSDK tool, you can generate the client stubs by extracting the WSDL and running the wsdl2java utility. For example, you could run this command to generate the stubs in a package called com.novell.soa.af.metrics.soap.impl:
"C:\Program Files\Java\jdk1.5.0_14\bin\java" -cp "../lib/wssdk.jar;../lib/jaxrpc-api.jar";"../lib/mail.jar";"../lib/activation.jar";"c:\Program Files\Java\jdk1.5.0_14\lib\tools.jar"; com.novell.soa.ws.impl.tools.wsdl2java.Main -verbose -ds gensrc -d C:\ -noskel -notie -genclient -keep -package com.novell.soa.af.metrics.soap.impl -javadoc metrics.wsdl
You can change the wsdl2java parameters to suit your requirements.
Before you can begin calling methods on the Metrics Web Service, you need to have a reference to the remote interface.
The code below shows how to obtain the remote interface.
import java.util.Locale; import java.util.Properties; import javax.naming.Context; import javax.naming.InitialContext; import javax.xml.rpc.Stub; import com.novell.qa.soap.common.util.LoggerUtils; import com.novell.qa.soap.common.util.LoginData; import com.novell.qa.soap.common.util.ServiceUtils; import com.novell.soa.af.ClusterException; import com.novell.soa.af.impl.soap.Provisioning; import com.novell.soa.af.impl.soap.ProvisioningService; import com.novell.test.automator.framework.TestProgramException; import com.rational.test.ft.script.RationalTestScript; import com.novell.soa.af.metrics.soap.MetricsClientHelper; import com.novell.soa.af.metrics.soap.MetricsStubWrapper; import com.novell.soa.af.metrics.soap.impl.MetricsService; import com.novell.soa.af.metrics.soap.impl.MetricsServiceException; import com.novell.soa.af.metrics.soap.impl.IRemoteMetrics; /** * Method to obtain the remote interface to the Metrics endpoint * @param _url * @param _username * @param _password * @return IRemoteMetrics interface * @throws Exception */ private IRemoteMetrics getStub(String _url, String _username, String _password) throws Exception { Properties properties = new Properties(); properties.put(Context.INITIAL_CONTEXT_FACTORY, "org.jnp.interfaces.NamingContextFactory"); String lookup = "xmlrpc:soap:com.novell.soa.af.metrics.soap.impl.MetricsService"; InitialContext ctx = new InitialContext(); MetricsService svc = (MetricsService) ctx.lookup(lookup); Stub stub = (Stub)svc.getIRemoteMetricsPort(); stub._setProperty(Stub.USERNAME_PROPERTY, _username); stub._setProperty(Stub.PASSWORD_PROPERTY, _password); stub._setProperty(Stub.SESSION_MAINTAIN_PROPERTY, Boolean.TRUE); stub._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, _url); return (IRemoteMetrics) stub; }
Here’s the code to call the method defined above:
IRemoteMetrics stub = null; try { // // Get the stub String url = m_loginData.getURL(); stub = getStub(url,_username,_password); } catch(Exception e) { String msg = e.getMessage(); LoggerUtils.logError(msg); throw new TestProgramException(msg); } return stub;
In order for this code to work, the URL passed to the getStub() method would need to point to the SOAP endpoint, as shown below:
http://myserver:8080/IDMProv/metrics/service
The user name needs to be a fully qualified DN such as the following:
"cn=admin,ou=idmsample,o=novell"
The Metrics Web Service impact on the live system is limited by 4 settings that may be modified in the IDMfw.jar/WorkflowService-conf/config.xml file:
Table 21-5 Metrics Configuration Settings
When the limit has been reached for any of these settings a Web Service fault is generated indicating the problem. In addition, for settings 1 and 2, the fault includes an error code.
If the fault is caused by a TimeRequiredBetweenClientRequests error, the error code is 100.
If the fault is caused by a MaxClients errors, the error code is 200.
If the fault is caused by a closed client connection error, the error code is 300.
Client consumers of the Metrics Web Service will have to include in their code provisions for retrying a request. Here is a simple Java listing that shows how this can be achieved:
try { for (int i = 0; i < retries; i++) { try { return metrics.getFlowCount(strDN, strId, new HashMap()); } catch (MetricsServiceException e) { if (e.getErrorCode() == 100 //subsequent call error || e.getErrorCode() == 200) { //too many clients try { Thread.sleep(retryPause); } catch (Exception ex) { // to nothing } } else { throw e2; } } else { throw new RuntimeException(e); } } catch (Exception e) { throw e; } } throw new RuntimeException("Did not succeed making webservice call"); } catch (Exception e) { throw e; } } ...