Assemble flow management

Assemble flow management provides features for accessing flow definition files and monitoring flow instance status, including a REST style API for managing flow definition files and a Web based interface to list runtime information of flow instances.

Enabling flow management features

Assemble flow management features are provided with the zero.assemble.flow.management module. Add this module as a dependency in your IBM® WebSphere® sMash application using the steps in the following sections.

Configuring flow management with Eclipse

Use the following steps to configure flow management in Eclipse:

Open the ivy.xml file found in the /config directory in your project.
Under dependencies, click Add, select zero.assemble.flow.management and click OK.
To be sure the application dependencies have been resolved, right click the project and select Zero Tools -> Resolve.

Configuring flow management with the command line

Use the following steps to configure flow management with the command line interface:

Edit the ivy.xml file found in the /config directory of your project.

Make sure the


zero.assemble.flow.management

module is one of your dependencies as shown in the following example:

<dependencies>
	... 
	<dependency org="zero" name="zero.assemble.flow.management" rev="[1.0.0.0, 2.0.0.0["/>
	...
</dependencies>

Run zero resolve in your application root directory to resolve modules from repository.

After resolving, start your WebSphere sMash application. Go to the following address: http://localhost:8080/flowadmin. If your flow management is enabled successfully, the page shown in the following example is displayed.

flow-monitor-screenshot

Using the flow administration REST API

After you have a WebSphere sMash application running and set up for flows, you can use the REST API provided for flow administration. The HTTP URI syntax for accessing flow definition is shown in the following example:

{application_host}/flowadmin/flow/{path-to-your-flow}

You can perform the following operations on a flow definition:

Create: Perform an HTTP POST with the flow definition as the body to: {application_root}/flowadmin/flow/{path-to-your-flow}. Use a path and process name that are unique in your application because a POST request does not overwrite an existing file.
Example: Issuing an HTTP POST to http://localhost:8080/flowadmin/flow/myApp (with the body being a flow definition) is the same as manually putting the file in the server at the following location: {application_root_directory}/public/myApp/index.flow
Retrieve: Perform an HTTP GET against the base URL of the flow.
Example: An HTTP GET issued to http://localhost:8080/flowadmin/flow/myApp returns the flow definition to {application_root_directory}/public/myApp/index.flow.
Update: Perform an HTTP PUT with the flow definition as the body to: {application_root}/flowadmin/flow/{path-to-your-flow}. If the file already exists on the server, it is overwritten.

All active instances are not purged but run as defined in the previous flow.
Delete: Perform an HTTP DELETE against: {application_root}/flowadmin/flow/{path-to-your-flow}. If the file exists on the server, it is deleted, but all its active instances run as usual.

The default file name, if no file name is specified, is index.flow. You can also use POST and PUT entry points to pass form-encoded parameters (as an alternative to sending the flow definition as the body of the request). To do this, use a script form parameter and send the flow definition as its value. This is how the form works under the Flow Deploy link in the flow administration page.

The context root is supported in the flow administration REST API. See the configuration section for more information on context root configuration.

For example, if you specify /foo/bar as the context root, the HTTP URI syntax is {application_host}/foo/bar/flowadmin/flow.

Basic flow instance monitoring

You can access the flow monitor withthe following URL:

{application_host}/flowadmin

The following basic functions are provided:

Viewing the state of your running flow instances (variable values and instance IDs) or the flow definition with the flow monitor
Cleaning up the data from the global context. To do this, click the cleanup link following a COMPLETED, CANCELED or FAILED instance.
Canceling running a flow. To do this, click the cancel link following a SUSPENDED instance.
Getting the XML context of the variable. Do do this, look for the detail link in the value column of the variables list of an instance and click it.
Cleaning up the state of any completed flows by flushing their data from the global context. To do this, click the Cleanup link on top of the flow instances list.

The following graphic shows the basic flow instance monitor.

basic-flow-instance-monitor

The context root is supported in the flow monitor. See the configuration section for more information on context root support.

For example, if you specify /foo/bar as the context root, the flow monitor is located in the following directory: {application_host}/foo/bar/flowadmin.

Secure flow monitor

In most cases, accessing control should be performed on the flow runtime information. You can use WebSphere sMash security to secure the flow monitor.

For example, if you only want administrators to see flow runtime information or change flow definition, then add the following security rule in the zero.config file of your WebSphere sMash application:

@include "security/rule.config" {
   "conditions": "(/request/path =~ /flowadmin(/.*)?) && (/request/method =~ (GET|PUT|POST|DELETE))",
   "authType" : "Basic",
   "groups" : ["Admins"]
}

After restarting your application, the requests for URIs that start with /flowadmin will require authentication (HTTP basic authentication) and only users that are members of the "Admins" group will be allowed access. If you want more detailed information on security rules, see the security considerations information.