19.1 About the Metrics Web Service

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:

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:

These three measures are related by Little's law:

Inventory=Flow Rate*Flow Time

19.1.1 Web Service Semantics

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.

19.1.2 Accessing the Test Page

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 Administration within the User Application. To do this, you need to select the Application Configuration tab, then select Web Services from the left-navigation menu. After selecting Web Services, 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.

19.1.3 Web Service Methods Grouped by Security Permissions

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 Metrics

Team managers can only retrieve metrics on a team for which they are managers. These are the methods are available to team managers:

Table 19-1 Team Metrics Methods

Method

Description

getClaimedFlowTimeCalendarDays

Returns the average time in hours the provisioning request was claimed for within the specified time interval

getClaimedFlowTimeWorkingDays

Returns the result set required to compute the average time the provisioning request was claimed for the specified time interval

getToClaimedFlowTimeCalendarDays

Returns the average time in hours it took the provisioning request to be claimed from the moment it was available to addressees

getToClaimedFlowTimeWorkingDays

Returns the average time it took the provisioning request to be claimed from the moment it was available to addresses, within the specified time interval

getClaimedInventory

Returns the average number of provisioning requests claimed within the specified interval

getClaimedThroughputWorkingDays

Returns the average number of provisioning requests claimed within the specified interval

getTeamLongestRunning

Returns a result set of the longest running request in seconds for which members of the team acted as addressees

getTeamFlowHistory

Returns a result set of the activity outcomes, addressee and addressee messages for the specified list of provisioning requests

getTeamHistoryForInitiators

Returns a result set of the provisioning request and their status for which members of the team acted as initiators

getTeamHistoryForRecipients

Returns a result set of the provisioning request and their status for which members of the team acted as recipients

getTeamRunningTime

Returns the average time in seconds the specified provisioning requests have been running

getTeamDecisionCount

Returns the number of decisions the team made as addressees for the specified provisioning request

getTeamInitiatedCount

Returns the number of provisioning requests initiated by the team

getTeamRecipientCount

Returns the provisioning requests for which a member of the team acts as a recipient

Provisioning Administrator Metrics

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 19-2 Provisioning Administrator Metrics Methods

Method

Description

getActivityFlowTimeCalendarDays

Returns the average time in hours the user activity took to complete

getActivityFlowTimeWorkingDays

Returns the result set required to compute the average time the user activity took to complete

getActivityInventory

Returns the average number of provisioning requests at any one time for the specified user activity

getActivityThroughputCalendarDays

Returns the average number of provisioning requests per hours that exited the specified user activity within the specified time interval

getActivityThroughputWorkingDays

Returns the result set required to compute average time it takes a provisioning request to complete for the specified time interval

getFlowTimeCalendarDays

Returns average time in hours it takes a provisioning request to complete for the specified time interval

getFlowTimeWorkingDays

Returns the result set required to compute average time it takes a provisioning request to complete for the specified time interval

getInventory

Returns the average number of provisioning requests in the system at any one time for the specified time interval

getLongestClaimed

Returns a result set of the provisioning requests that have been claimed but not acted upon (time in seconds)

getLongestRunning

Returns a result set of the longest running provisioning requests (time in seconds)

getFlowCount

Returns the number of provisioning requests

getFlowHistory

Returns a result set of the activity outcomes, addressee and addressee messages for the specified list of provisioning requests

getFlowHistoryForInitiators

Returns the list of provisioning requests and their status for the specified initiators

getFlowHistoryForRecipients

Returns the list of provisioning requests and their status for the specified recipients

getRunningTime

Returns the average running time in seconds for the provisioning requests that are currently running

getThroughputCalendarDays

Returns the average number of provisioning requests per hour that completed within the specified interval

getThroughputWorkingDays

Returns the result set required to compute the average number per hour of provisioning requests that completed within the specified interval

Utility Operations

Both team managers and administrators may perform these operations:

Table 19-3 Utility Operations

Method

Description

getVersion

Returns the server version of the Web service. This should always used to ensure version matching between client and server code.

getAllProvisioningFlows

Returns the list of provisioning flows that the logged in user can see

getUserActivityOnlyFlow

Returns a GraphViz DOT (http://www.graphviz.org/) representation of the provisioning workflow

getTeams

Returns the list of teams the logged in user manages

getTeamMembers

Returns the list of team members for the specified team

19.1.4 Specifying Filters

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 19-4 Filters for Narrowing Metric Results

Filter

Description

KEY_ACTIVITY_ID

A User Activity Id as defined in the provisioning request definition

KEY_APPROVAL_STATUS

The approval status for the provisioning request. Possible values are:

  • ApprovalStatusProcessing

  • ApprovalStatusDenied

  • ApprovalStatusRefused

  • ApprovalStatusApproved

  • ApprovalStatusRetract

  • ApprovalStatusError

KEY_ENTITLEMENT_STATE

The state of the entitlement associated with the provisioning request. Possible value are:

  • EntitlementUnknown

  • EntitlementGranted

  • EntitlementRevoked

KEY_ENTITLEMENT_STATUS

The status of the entitlement associated with the provisioning request. Possible values are:

  • EntitlementSuccess

  • EntitlementWarning

  • EntitlementError

  • EntitlementFatal

KEY_INITIATOR

The user DN of the workflow initiator

KEY_L_COMPLETION_TIME

The date indicating the start of the interval for workflow completion

KEY_S_COMPLETION_TIME

The date indicating the end of the interval for workflow completion

KEY_L_ENTITLEMENT_TIME

The date indicating the start of the interval for entitlement time

KEY_S_ENTITLEMENT_TIME

The date indicating the end of the interval for entitlement time

KEY_S_START_TIME

The date indicating the start of the interval for workflow start

KEY_L_START_TIME

The date indicating the end of the interval for workflow start

KEY_PROCESS_ID

The DN of the provisioning request

KEY_PROCESS_STATUS

The status of the provisioning request. Possible values are:

  • ProcessStatusRunning

  • ProcessStatusStopped

  • ProcessStatusTerminated

  • ProcessStatusCompleted

KEY_PROCESS_VERSION

The process version associated with the workflow version

KEY_RECIPIENT

The user DN of the workflow recipient

KEY_REQUEST_ID

The unique id associated with the workflow instance

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

19.1.5 Generating the Stub Classes

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.

19.1.6 Obtaining the Remote Interface

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"

19.1.7 Metrics Configuration Settings

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 19-5 Metrics Configuration Settings

Key in config.xml

Description

<key>Metrics/TimeRequiredBetweenClientRequests</key>

Required time between client requests in ms (default is 250 ms)

<key>Metrics/MaxClients</key>

Maximum number of concurrent client sessions (default is 10)

<key>Metrics/MaxRows</key>

Maximum number of rows any query can return

<key>Metrics/MaxTeamMembers</key>

Maximum Number of Team Members

<key>Metrics/SecondsToAnythingDivider</key>

The divider used in all throughput computations (default 3600). Original values are in seconds so all throughputs are consequently per hour.

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;
      }
   } 
...