Home » The XForms cookbook

XForms and OpenWFE - Part 2

Submitted by alexsansom on Wed, 2007-07-11 13:06.

So far (in part 1) we have looked at the general system architecture and also two major components that make up the Xrai environment. The idea of this next article is to describe in some more detail how the XForm interacts with those components.

The worklist

The form is designed to work in a way such that a user will navigate to the XForm in their browser and, after creating (registering) a username/password, will fill in their details. After correctly submitting their details the user is met with their worklist. The worklist is made up of 3 sections describing which tasks they are allowed to launch, currently launched tasks and also a task history. All of the information that the user sees in the worklist is the result of queries to the open workflow engine.

The first section of the form, 'Launch a New Process', is retrieved from the workflow engine by a GET HTTP request, to the REST interface, that asks the workflow engine for a list of items that this user has been granted permission to launch.

An example URL for this would be:

http://hostname:5080/worklist/Store.sshrc?session=1157983906796&action=listLaunchables&time=2006%2D09%2D11T14%

The HTTP response from the workflow engine being (for an applicant user):

<?xml version="1.0" encoding="ISO-8859-1"?>
<launchables>
	<launchable engine-id="mainEngine" url="http://localhost:8080/workdefs/sshrc-apply-for-doctoral-fellowship__..."/>
	<launchable engine-id="mainEngine" url="http://xrai.x-port.net:8080/workdefs/launchitems/sshrc-apply-for-... />
</launchables>

The contents of the HTTP response are then used in the XForm as instance data that an XForms repeat control binds to and is then displayed to the user.

The second section of the worklist, 'Open Current Process', is retreived by exactly the same process, except this time the request to the REST interface will be something like:

http://hostname:5080/worklist/Store.sshrc?session=1157983906796&action=getHeaders&limit=30&time=2006%2D09%

The 'action=getHeaders' part of the request asks OpenWFE to return some XML that is a list of currently in progress work items for a user. An example of the response would be:

<?xml version="1.0" encoding="ISO-8859-1"?>
<headers>
	<header last-modified="2006-08-18 14:41:11+0100" locked="false">
		<flow-expression-id owfe-version="1.7.0b" engine-id="mainEngine" initial-engine-id="mainEngine" workflow-...
			<attributes>
				<smap>
					<entry>
						<key>
							<string>__wfi_id__</string>
						</key>
						<value>
							<string>1155805432546</string>
						</value>
					</entry>
					<entry>
						<key>
							<string>__wfd_name__</string>
						</key>
						<value>
							<string>SSHRC Apply for Doctoral Fellowship Flow</string>
						</value>
					</entry>
					<entry>
						<key>
							<string>__wfd_revision__</string>
						</key>
						<value>
							<string>1.1</string>
						</value>
					</entry>
					<entry>
						<key>
							<string>__wfd_url__</string>
						</key>
						<value>
							<string>http://localhost:8080/workdefs/sshrc-apply-for-doctoral-fellowship__1.0.xml</string>
						</value>
					</entry>
					<entry>
						<key>
							<string>__dispatch_time__</string>
						</key>
						<value>
							<string>2006-08-18 14:41:11+0100</string>
						</value>
					</entry>
					...
				</smap>
			</atributes>
		</flow-expression-id>
	</header>
</headers>

Again this is used in the XForm instance data, with a repeat control for display to the user.

The two requests to the workflow engine are periodically run using a timed Javascript function so that the listed launchable items and current items are updated (and the underlying instance data). This means that if a user has a work item proceeded to them it will show up almost instantly in their lists.

Current work item

When a user clicks on one of their 'in progress' work items another HTTP request is sent to the REST interface. This asks OpenWFE for all the details of a particular work item, it's state, and any other values that are associated with it.

The POSTed request is something like:

http://hostname:5080/worklist/Store.sshrc?session=1157983906796&action=getWorkItem&time=2006-09-11T14:36:38+

The body of the POST being something like:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<flow-expression-id
	owfe-version="1.7.0b"
	engine-id="mainEngine"
	initial-engine-id="mainEngine"
	workflow-definition-url="http://localhost:8080/workdefs/sshrc-apply-for-doctoral-fellowship__1.0.xml"
	workflow-definition-name="SSHRC Apply for Doctoral Fellowship Flow"
	workflow-definition-revision="1.1"
	workflow-instance-id="1155746373218"
	expression-name="participant"
	expression-id="0.0.42.0">
</flow-expression-id>

The response that comes from OpenWFE is a chunk of XML that is used as XForm instance data. The contents of the response include status of documents in the folder, URL's of where to obtain extra instance data, values that are used to implement business rules and also historical information of the work item itself. Full details can be found in the OpenWFE documentation.

An example of the returned XML is:

<?xml version="1.0" encoding="ISO-8859-1"?>
<workitem last-modified="2006-08-18 15:19:48+0100" participant-name="xrai-user-alex10" dispatch-time="2006...>
	<attributes>
		<smap>
			<entry>
				<key>
					<string>applicant_name</string>
				</key>
				<value>
					<string>alex10</string>
				</value>
			</entry>
			<entry>
				<key>
					<string>applicant_email</string>
				</key>
				<value>
					<string>Not used yet</string>
				</value>
			</entry>
			<entry>
				<key>
					<string>__subject__</string>
				</key>
				<value>
					<string>Application for Doctoral Fellowship</string>
				</value>
			</entry>
			<entry>
				<key>
					<string>status_document_eligibility</string>
				</key>
				<value>
					<string>complete</string>
				</value>
			</entry>
			<entry>
				<key>
					status_document_cv</string>
				</key>
				<value>
					<string>started</string>
				</value>
			</entry>
			...
		</smap>
	</attrbiutes>
</workitem>

Further calls to the OpenWFE REST interface are used in the form to carry out further actions on a work item such as proceeding the work item to the next stage, updating values for 'variables' in the flow and locking the work item. The recommended reading is the OpenWFE REST interface online documentation.

Saving/loading Xrai documents to eXist

When a user partially completes a document and has decided to save their progress, we save the document instance data in the the eXist database (POSTed to the eXist REST interface). At the same time as saving to the database we also update and save the workitem instance data (via the REST interface again) with the URL that can be used to retrieve the document instance data via the eXist REST interface. As you can see in the previous section's XML there is an element 'entry/key/string' with the value 'url_document_eligibility'. To go with the 'entry/key/string' element there is also 'entry/value/string' which contains a URL to where the partially complete instance data for the Eligibility Assesment document can be found (this is test data and there is no actual data located at that URL).

When the user loads the work item the XForm checks for any document URLs in the work item and, when it finds one, sends a submission to eXist that retrieves the instance data to replace the default data. The result is that the user then sees the form controls populated with the data they previously entered.

Again, it's advisable to read up on the OpenWFE and eXist REST interfaces. See links below.

Summary

Although this article describes the usage of eXist and OpenWFE in the SSHRC XForm it does not explain how the submissions to the REST interfaces are triggered. Further reading about XForms events and also the if/while/iterate extended XForms functionality is required. See the 'Links' section below.

Links

‹ XForms and OpenWFE - Part 1upXForms patterns ›
»