Process Reference for Policy Manager 7.x

Learn to create a process and use process activities.

Getting Started (PM7x) Managing Processes (PM7x)

Table of Contents

  1. About Processes
  2. Process Editor
  3. Fault Sequence Editor
  4. Variable Editor
  5. Receive Activity
  6. Reply Activity
  7. Invoke Activity
  8. Script Activity
  9. Branch Activity
  10. Transformation Activity
  11. Audit Activity
  12. Insert Content Activity
  13. Process Activity

About Processes

A process is an ordered graph of activities that can be performed by a container that supports the virtualization capability, like the Network Director. The logic performed in a virtual service operation is defined as a process. When a message is received by the container, once the virtual service operation is identified, its process is executed. As dictated by the activities in the process, down-stream services may be invoked. As a result of process execution, a response to the original message is generated.

An example of a process is the default process of a virtual service operation. In that process a message is received using a Receive Activity, an Invoke Activity is executed that calls the virtualized service operation, and a Reply responds with the response from the Invoke Activity.

Processes can get much more complex to perform functions like transformation and content based routing. The author of the process can assemble activities to achieve the results they would like.

Policy Manager allows the creation of processes within two different contexts, as the implementation of a virtual service operation (Services > Operation > Process or Services > Operation > Fault section), and as a standalone process (Processes Folder) that can be invoked by another process to achieve reusability. In all contexts, a graphical editor is provided to construct the process.

Back to top

Process Editor

The Process Editor allows you to create a process in a graphical drag-and-drop environment. The process begins by receiving a message (see the Receive Activity) and the process ends when a message is returned (see the Reply Activity) to the caller.

Figure. Process Editor Activity Palette

Activities

The activities available to be called from within a process are available on an Activity Palette located on the upper left hand side of the editor graph. An activity icon in the palette can be selected and dragged on to the process editor graph. Activities are called in order and are linked together by directional connectors. To link two activities select the middle of the activity that will be executed first. A circle with an error should appear.

Figure. Starting a Link Between Activities

Drag your mouse to the center of the activity to be executed next and release. A directional connector should be drawn linking the two activities.

Figure. Completing a Link Between Activities

Sequence

A series of activities linked together is called a Sequence. A sequence is terminated by either a Branch Activity (see below) or by a Reply Activity (see below). A set of linked activities from the Receive Activity to a Reply Activity may contain several sequences separated by Branch Activities. That entire set of linked activities is called a Flow.

Functions that can be performed on the entire process are available on a toolbar located on the lower left hand side of the editor graph.

Figure. Process Editor Toolbar

The toolbar has functions such as saving the process, editing the variables used in the process (see Variable Editor), refreshing the page, or undoing the last action.

Back to top

Fault Sequence Editor

Next to the Process Editor tab is a tab labeled Fault. On this tab you define a sequence of activities you want executed when a fault is encountered at any point of your main process. In the main process once a fault is encountered, the process execution immediately stops and the activity sequence in the Fault tab is executed.

Figure. Fault Sequence Editor

The Fault Sequence Editor works exactly like the main Process Editor except that the sequence does not need to begin with a Receive Activity. The Receive from the external client has already been executed in the main process. At this point we are just executing activities within the same process context.

When the fault sequence is executed, the reserved variable name “fault” will contain the fault message that is triggering the sequence. Activities that reference variables can use this fault variable.

A fault sequence is not required. If there is no fault sequence the system will simply return the fault back to the client. If a sequence is constructed, at a minimum a Reply Activity must be present at the end. Any of the activities in the activity palette can be used in the fault sequence including Branch activities. Each branch however must end with a Reply Activity.

The Reply Activity can be configured to return a fault message or a regular message as controlled by Fault field in the Reply Activity Editor (see the Reply Activity section below). The reserved fault name “CurrentFault” as seen in the fault name pull-down indicates that the fault name for the content of the fault variable will be used as-is. The name can be changed however to any of the operation faults or to a Binding Fault instead. This will allow you to perform fault mediation.

Back to top

Variable Editor

The Variable Editor is an interface for defining variables that can be used in the process. Variables can be used in different activities to dictate behavior, such as using a variable to identify the endpoint of a service to invoke. Variables can also be used to store the output from web service invocations or provide input to web service invocations.

Figure. Variable Editor

A variable is identified by a name and defined by a type, or syntax. The types recognized by the system are message (used for input or output of a web service invocation, request, or reply activity), string, int, long, boolean, float, or any (can hold any content). Activities that support the use of variables in their configurations will often restrict the use of variables based on type. Optionally a default value can be given to a variable. If there is a default, at the beginning of process execution the variable will be given that value.

Back to top

Receive Activity

The Receive Activity provides the entry point into the process. The caller will invoke the process by providing it with a message. That message will be stored in the variable selected in the activity’s configuration screen. Only variables of type message can be used. There can only be one Receive activity in a process.

Figure. Receive Activity Editor

Back to top

Reply Activity

The Reply Activity provides the exit point from a process. Every flow through the process must have one and only one Reply Activity. This means if there are multiple branches created from a Branch Activity, each branch must be terminated with a Reply Activity. The Reply Activity can return a message to the caller. It is not required for one-way operation processes. Only variables of type message can be used.

Figure. Reply Activity Editor

Application and Binding Faults

In addition to specifying the variable holding the message to return you can also indicate that the message is a fault by providing a Fault Name. Faults fall into two main categories, application faults and binding faults.

  • An application fault is caused by a problem in the business process of the operation. For example if the operation was to withdraw funds an application fault may be for identifying there were insufficient funds.
  • A binding fault is not specific to the business function of the operation. It a problem at the protocol layer itself. Binding faults are general to all operations. Examples would be security failures, communication failures, message parsing errors, etc.

An application fault will be defined in the WSDL document for the operation. Policies can be attached to them. A binding fault is typically not referenced anywhere. In the Reply Activity Editor a Fault Name pull-down is provided that will contain the application faults found in the WSDL document for the operation as well as a reserved fault name of “BindingFault.” You can choose what the message being returned represents. One other option is provided that is called “CurrentFault.” That option is available only in the Fault Sequence Editor. It requires the reserved fault variable to be filled with a message and its fault name to be already known and used here.

Figure. Fault Reply Activity

Back to top

Invoke Activity

The Invoke Activity invokes the operation of a service registered in the system. The operation is invoked by sending a message that is specified as an input variable to the activity. The response from the operation invocation is stored in an output variable. The input and output variables can both be the same variable.

Figure. Invoke Activity Input and Output Variables

The operation that will get invoked can be specified either statically or dynamically through the use of variables. To statically identify the operation to invoke, first start by searching for the service with the operation.

Figure. Invoked Service Search

The search is performed using QNames. When the Search button is clicked the system searches for any service with a QName that contains what is typed in the Service QName field. If nothing is entered all services will be returned.

Figure. Invoked Service Search Result

The search results are listed in the Service pull-down. Once the correct service is selected the interface pull-down will be populated with the interfaces defined for the selected service. Then once the correct interface is selected the operations in the selected interface will populate the Operation pull-down. Finally the operation can be selected.

Figure. Static Operation Selection

Variables can be used for specifying the service, interface, and/or operation. The variable must be a string typed variable. For service and operation the string must be in a QName format of {namespace}localpart. If at runtime any of the variable values do not match with what is registered in Policy Manager the invocation will fail. You can mix static selections with variables but once a variable is used the remaining selections must also be variables. For example, if you use a variable for interface you must use a variable for operation.

Figure. Static and Dynamic (Variable) Operation Selection

By default the access point (endpoint) that is called when invoking the operation is selected by the runtime container using its selection strategy. You can dictate what access point is called by selecting the Invoke Access Point Directly checkbox. Once selected you can either enter a URL directly or an access point by name. Just as you can for service, interface, and operation, you can select the access point from its pull-down or use a string variable that will be resolved at runtime.

Figure. Direct Access Point Invocation

By default the identities used when invoking the operation are dictated by the outbound identity configuration of the virtual service. It is possible to change those identities for the individual Invoke activity by selecting the Custom Mapping radio button in the Identity section.

Figure. Custom Identity Mapping Selection

Once selected the Next button of the activity wizard will be enabled. Select Next and the Outbound Identity Configuration page will be displayed. This page works similarly to the Outbound Identity Configuration page for the virtual service. You select source and outbound subject categories to create mappings.

Figure. Custom Outbound Identity Configuration

Auditing the message as it is sent over the wire to the access point can be achieved by simply selecting the Audit checkbox. The virtual service operation invocation that is executing the process must be currently being audited by use of an auditing policy for the downstream message to be audited.

Back to top

Script Activity

The Script Activity provides the ability to execute a script at the point in the process the activity is connected. The script can be written in either JavaScript, Jython, or BeanShell.

The Script Details Editor is organized into two separate areas, Imports and Source. The Source has a pull-down where you can select the script language. It also has a large source code editor text area.

Figure. Script Activity Source Area

Common functions that you may need to perform in your scripts can be saved in Script objects using the Add Script function in the Scripts section of each Organization in the Policy Manager Workbench. To make use of those common functions from the Script Activity the Script objects defining those functions must be imported. The Imports area is where those scripts are identified for import. The available scripts are listed in the Available Scripts tree. Any number of Scripts in that tree can be moved to the Imported Scripts list box. Only scripts that match the language type will be available for selection in the tree. The script does not return a value.



Figure. Script Activity Imports Area

In the figure above the json2 Script from the Registry Scripts folder is imported. Any functions defined in json2 can be used within the Script Activity source code.

The following pre-defined variables are provided. For more information refer to the Policy Manager Scripting API located in the \sm70\docs\scriptDocs folder of the Policy Manager 7.2 release folder.

You can also access the applicable version of the scripting API here: Policy Manager Scripting API.

Click index.htm to launch the documentation:

  • processContext—Provides functions for retrieving and changing information about the currently running process, such as the variables defined in the process and the authenticated subject(s) of the process.
  • systemLog: Provides logging functions to the container’s log. The statements logged with this interface are mixed with the other system log statements.
  • auditLog: Provides logging functions to the process audit log. If auditing is enabled for the virtual service operation that is invoking the process statements logged using this variable log information will be inserted into the audited message log for the operation’s execution. This can be found on the service’s Monitoring tab in the Logs sub-tab.
  • alerter: Provides an interface for generating alerts that are displayed in on the Policy Manager alert pages.
  • recorder: Provides an interface for recording content in the Policy Manager usage log pages.
  • msgFactory: Providers functions for create message variables. A message variable cannot simply be assigned content like a simple string or int variable. It must be initialized using one of the functions in the msgFactory.
Normalized Copy Example

The following is a script that creates a normalized copy of a message and saves it as a variable.

On line 1 the processContext is used to get the message variable named “message”. On line 2 a normalized copy is made of the message. Finally on line 3 the processContext is used to save the normalized copy as a variable named “copy” that can be used in other activities that execute after this one in the process.

Normalized Message Creation Example

The next script illustrates the use of the msgFactory to create a normalized message. A normalized message contains the XML element referenced in the wsdl:Message element in a WSDL document.

On line 3 the msgFactory is used to create a normalized message named temp. On line 4 the content from line 1 is set as the temp message content. On line 5 the processContext is used to save the new message as a variable named temp.

Protocol Message Creation Example

Message creation is not limited to normalized messages. Protocol specific messages of any content-type can be constructed using the msgFactory. The following example shows the creation of a JSON message.

Note on line 2 the call on the msgFactory to create the message is different, both in function name and the need for specifying the content-type of the message, application/json in this case.

Back to top

Branch Activity

The Branch Activity provides a mechanism to have alternate process flows, or branches, based on boolean conditions. Drop the Branch Activity on the Process page and connect the last activity to be executed before the branch to the Branch Activity.

Figure. Adding a Branch Activity

The Branch Activity itself has very little configuration. It is the branch conditions themselves that have most of the information. If you double click on the Branch Activity you can see a list of the conditions and most importantly you can establish what expression language each branch condition will use. All branch conditions must use the same language. The supported languages are XPath, JavaScript, Jython, or BeanShell.

Figure. Branch Activity Editor

To create a branch add the next activity to be performed to the process graph, select the Branch Activity and connect it to the next activity.

Figure. Creating a Branch

A Branch Activity is similar to a Java switch statement. It can support multiple branches. Only one branch will be followed. The branches have boolean conditions defined either by an XPath expression or a script.  Each branch is evaluated in order. The first to evaluate to true is selected and the sequence of activities associated with the branch are performed.

Branch conditions are defined separately from the main Branch Activity in the Condition Details Editor. You add a branch condition by adding a new activity to the sequence (e.g., Script Activity, Invoke Activity, etc. ) and dragging a connector from the main Branch Activity to the target activity. There must always be a default branch that can be selected if no other branch conditions evaluate to true. This default branch condition is named "Otherwise" and must be added and set for each Branch Activity configuration.

A branch condition can be written in any of the languages in the drop-down, is set in the Branch Details Editor and can only be changed there. The language selected will apply to all conditions within the branch.

Note that if you have branch conditions defined and you choose to change the language all source will be deleted.  It is recommended that you make a copy of your source content prior to changing the language.

After you select the language for case conditions, you then save and exit your Branch Activity and add your connections.

The result of the condition must be either true or false. If there are multiple conditions for a branch, the order in which they are executed can be changed by moving each condition up or down in the Case Conditions table. Note that the "Otherwise" condition does not display in the Case Conditions table but must still be defined.

The first branch created in most cases will become the Otherwise branch although that can be changed. To change a branch’s condition double click on the connector between the Branch Activity and the next activity in the branch sequence. The branch condition can be written in either XPath, JavaScript, Jython, or BeanShell. The result of the condition must be either true or false.

Figure. Branch Condition Editor

In the figure above the condition is configured to use XPath as the language for the boolean expression. The expression checks for the first price element found in the content of the message named “message” and if its value is greater than 100 then this condition is met. Note the namespace prefix is defined at the bottom of the page.

When using XPath as the expression language a field for selecting a message variable to use as the context of the expression is displayed. The expression will be evaluated against that variable’s content. The variable’s content must be XML or an error will be generated at runtime.

When using a script language the script is evaluated and the last line of execution is expected to result in a boolean true or false. The context of the script is provided with a subset of the variables described in the Script Activity above:

  • processContext: Provides functions for retrieving and changing information about the currently running process, such as the variables defined in the process and the authenticated subject(s) of the process.
  • systemLog: Provides logging functions to the container’s log. The statements logged with this interface are mixed with the other system log statements.
  • auditLog: Provides logging functions to the process audit log. If auditing is enabled for the virtual service operation that is invoking the process statements logged using this variable will be inserted into the audited message log for the operation’s execution. This can be found on the service’s Monitoring tab in the Logs sub-tab.

In the following figure the condition is triggered when the value of the price variable is greater than 100.

Figure. JavaScript Branch Condition

Back to top

Transformation Activity

The Transformation Activity provides a mechanism for transforming XML message or string content. The transformation is based on XSLT. The input to the activity can be a message or string variable. The transformed content will replace the input variable content at the completion of the activity.

Figure. Transformation Activity Example

In the figure above, the XSL Stylesheet will remove the BankId element and prefix the account id of each account with the bank id. If the message variable had the following content:


After executing this Transformation Activity the content of the message variable will be:


Audit Activity

The Audit Activity provides a mechanism for auditing a message. The audited message content is recorded and displayed as audited message content from an Auditing Policy. This information displays on the Monitoring pages of a service (i.e., Services > Monitoring). The input to the activity can be a message variable.

There are several options for what portion of the message variable content will be audited. In the Capture Details section of the Activity Editor there are two primary options; to capture the complete message or a portion of the message.

Figure. Auditing Complete Message

If the "Capture complete message" option is selected only a record name, or label, needs to be specified. If the "Capture message at the following expressions" option is selected a list of expressions can be entered.

Figure. Auditing Portions of Message

Each expression can use a different language. The supported languages are XPath, JSONPath, and Regular Expression. The XPath expressions are used when the input content is XML. The JSONPath expressions are used when the input content is JSON. The Regular Expressions are used for all other types of content. Each expression will have its own Record Name, or label.

In case there is content that should not be viewable by others in the audit log there is an option for masking content. In the Masked Elements section you specify a mask (e.g., password, account number) and a list of expressions that identify the content to be masked.

Figure. Masking Audited Elements

The expressions in the Masked Elements section are similar to those in the Capture Details section. The same languages are supported for masking and the same mapping of message content type to expression language. The results of the expressions will be replaced by the mask string.

If we look at the entire activity definition we can see that we are auditing just the account elements/properties of XML and JSON messages but we are masking out the account id’s with a mask of *******.

Figure. Audit Activity Example

Note the XPath expressions require namespace prefix definitions that are specified at the bottom of the editor.

Back to top

Insert Content Activity

The Insert Content Activity can be used to fill the content of a String or Message variable. The source of the content can be either statically defined content or an existing variable.

The From section of the activity editor identifies the source of the content. To specify static content to be inserted select the Static Content radio button. Once selected a text area will be displayed where content of any type, XML, JSON, text, etc. can be entered. A text field will also be displayed where you must enter the mime content type of the static content you entered in the text area (i.e., application/xml or application/json).

Figure. Static Content

To use content from a variable as input select the Variable radio button. Once selected a Filter section is displayed. Select the Filter check box if you would like only a portion of the variable’s content to be inserted. To insert the entire content of the variable do not select the checkbox.

A filter is defined using a filter expression written in a selected language. The languages supported are XPath (for XML content), JSONPath (for JSON content), or Regular Expression (for any content). The result of the filter expression applied to the input variable will be inserted. It is possible that the filter expression results in multiple elements or properties being used as input.

Figure. Filtered Variable Content

When defining XPath filter expressions the namespaces of specified elements must be included. That is done by using a namespace prefix in the expression. All namespace prefixes must be mapped to a namespace in the Namespace Prefixes table at the bottom of the activity page.

Figure. Namespace Prefixes

The To section of the activity identifies the target of the content specified in the From section. The target of the inserted content must be a variable. The From content can either initialize/replace the content of the variable in the To section or it can be inserted into the existing content of the target variable. If replacing the entire content of a variable and the variable has not yet been initialized it will be initialized as a result of the activity.

To insert into existing content the target location must be identified using a filter similar to the one described in the To section. Based on the filter expression it is possible that multiple target locations can be found. Once a target location can be identified the choice of whether the source content should be inserted/added to that location or the source content should replace what is at that location needs to be made. That choice is made by selecting either the Append or Replace radio button. Note, only the Replace option is available when using the Regular Expression language.

Figure. Filtered Content Target

The following figure illustrates the use of the Insert Content to initialize a message with static XML content.

Figure. Static Content Example

Since no filter is defined in the To section the static XML content will replace the content of var1, but if var1 has not yet been initialized in the process the static XML content will be used to initialize var1.

The next figure illustrates using the Insert Content Activity to extract a portion of a source variable and append it to a target variable in a specified location.

Figure. Append Content Example

All account elements in the message variable will be appended to the accounts element in var1. If no accounts element is found at the root of var1 an error will be generated. To see how this activity would perform at runtime take the following content for the message variable:

And the following content for the var1 variable:

As a result of the activity var1 would have the following content:

Back to top

Process Activity

The Process Activity allows you to call one process from another so that you can create processes with common activities and then call those processes at an appropriate point of another process. These processes with common activities are reusable and are organized in the Processes folder of each Organization in the Policy Manager Workbench. Reusable processes can themselves have Process activities so that they can call other reusable processes.

The configuration of a Process Activity is simple. The editor presents a tree of reusable processes in the Processes folder of each Organization in the Policy Manager Workbench. You simply select one.

Figure. Process Activity Editor

When a process is called from another process, the calling process’s context is passed to the called process. All the variables and their values from the calling process are passed through. If the called process defines variables with the same names as ones in the calling process, the calling process’s variables will be used.

Back to top