Authoring LiveCycle forms for the iPhone

Additional Requirements

LiveCycle ES 2

• Try
• Buy

Note: If you are installing LiveCycle ES2 for this article, select a turnkey install. See http://help.adobe.com/en_US/livecycle/9.0/installturnkey.pdf for more details.

Sample files:

Note: This file contains JavaScript libraries, HTML samples, and a LiveCycle Archive.

The release of Adobe LiveCycle Workspace ES2 Mobile brought about Adobe’s first application for the Apple iPhone. It allows users to participate in approval workflows from their mobile devices. This article explores how to extend the mobile capabilities of LiveCycle ES2 by creating an HTML-based mobile application that can initiate a business process. Initiating a process involves capturing data from the user, in this case via a form, then relaying that data to a back-end LiveCycle process. To complete the picture this article will also cover creating a process with an approval step that leverages the Adobe LiveCycle Workspace ES2 Mobile client for iPhone.

The sample application demonstrates how to initiate a LiveCycle process from an iPhone using HTML and JavaScript. The provided web code leverages IUI, a JavaScript library by Joe Hewitt that delivers a native iPhone look-and-feel to your application.

Building the user experience will involve the creation of a forms list as well as the individual forms themselves. Once deployed to the server, users can access the application via the Safari browser on their iPhone.

The first screen presents the user with a login screen (see Figure 1). Actually, the user’s credentials are only captured at this point, and then used for authentication when data is submitted to the server. Alternatively, if you wish to target users outside your organization you may choose to allow anonymous access to your applications and services.

The second screen displays a list of available forms (see Figure 2). Upon selection of a form the application will transition to the form page allowing for data capture and submission to the back-end service. Data is passed to the server in XML format. That data will then be pushed into a LiveCycle process and enter into a user step. Next, a new approval task will be queued up for a second user participating in the workflow via the LiveCycle Workspace ES2 Mobile application. When the approver opens their iPhone application they will be presented with the new task with options to approve or reject the request. A side-car PDF view of the request is also available if the user wishes to view additional details of the request. Once the request is approved (or rejected) the task will disappear from their list and the process will continue on the server. For the sake of simplicity, the sample process provided for this article ends there, but feel free to let your imagination run wild.

Coding the HTML Forms

Mobile forms are not all that dissimilar from any other HTML form, however, there are a few exceptions. Those differences account for a targeted visual experience as well as conventions for facilitating data collection for server processing. When a form is submitted from a mobile device, the provided JavaScript library walks the document object model (DOM) and collects all form elements encased in a DIV tag with a class name of node. Each node represents an element within the resulting XML data model structure that is sent to the LiveCycle process.

Note: If you wish to nest XML nodes, simply nest your DIV tags within your HTML code.

First and foremost, your form must also have a unique id, title (visible at runtime), class (panel and iuiForm), and action, and its selected attribute must be set to true (required by the IUI framework to be visible). For example:

A root node is required to encompass all other elements you wish to have processed by the parser. In other words, all DIV tags designated with a class attribute of node must be encased by a top level DIV tag with an id of rootnode:

The node parser supports hierarchical structures as well. The following example demonstrates such a nested relationship:

Within each node DIV the parser will look for elements with either a nodeName or nodeValue class. The nodeValue elements will usually refer to the input element. The name of the XML node created will be taken from the id of this element, and the value from its value attribute. If no nodeValue exists then it is assumed that this node has other children and the parser will continue recursively through the DOM.

Your form must also have a submit button as shown below:

When the form is rendered in the Safari browser on the iPhone (see Figure 3), the underlying node structure is invisible.

After your forms are created and uploaded to your LiveCycle application server, users can access them by directing their Safari browser to the appropriate URL. This will vary based on where the HTML files have been deployed. You may opt to simply drop your HTML files into a web accessible folder, or package your HTML and JavaScript in a Web Application Archive (WAR) file and deploy alongside LiveCycle. If you are running the LiveCycle turnkey install, you can drop the WAR inside the JBoss deploy directory. The resulting URL will depend on your server’s host name, port, and context as defined in web.xml file. The web.xml file included in the sample specifies a context of lcmobile, so the URL would be, for example: http://your.server:port/lcmobile/index.html.

The IUI library provides the iPhone specific look and sliding animations. Due to the way IUI works, all pages after the main landing page (index.html) are built as includes. When viewing the other HTML files you will notice they have no header or body, just HTML text.

After a user completes a form and clicks Submit (JavaScript onchange events check for valid input), two functions will fire: the post action (which fires the action event of the form) and the onclick event handler, which will invoke the parser causing the XML data model to be built and relayed to the LiveCycle process.

After the onclick event is fired all inputs belonging to the form are checked for invalid characters. If there are any, the XML is not created or sent; and the user is told that there is a problem with the form’s contents. If there are no invalid characters in any input fields, then the JavaScript code will browse through the DOM of the HTML page looking for all nodes, nodenames, and nodeValues of the form being submitted (see Figure 4). From these values an XML string will be formed and sent to the appropriate server endpoint. Credentials set on the index.html page will be sent with the request, and if they are valid, the server will return a message stating the request was accepted and processed. If the credentials are incorrect the page will alert the user to a possible problem with the credentials.

The next phase involves creating the server-side LiveCycle process. This process will accept the form submission from the mobile client and route a user task to a second user for approval. The first step is to create an Adobe Data Model that will represent the data you want to capture. Data coming from the mobile clients must conform to the schema of your data model.

Once the data exists within a running process as a process variable it will be used to populate a PDF document that will serve as a detail view within the LiveCycle mobile application.

To create an Adobe Data Model (Figure 5):

1. Start Adobe LiveCycle Workbench ES2.
2. Create a new application and name it MobileGuide.
3. Right-click the application and select New > Data Model.
4. In the New Data Model dialog box, type ServiceRequestModel as the Name.
5. Right-click in design view and select New Entity. Type ServiceRequest as the name.
6. Right-click the new entity and select New ID to add a requestId property.
7. Right-click the entity and select New Property to add each of the following properties: firstName, lastName, email, requestType, comments (see Figure 5).
8. Select the entity and under the General tab select Create LiveCycle Datatypes On Deploy.
9. Choose File > Save.

For more details on defining entities and the relationships between them, see the Adobe Application Modeling Technology Reference.

The next step is to create a PDF file to be delivered to the mobile client providing a detailed view. For this task you’ll be using Adobe LiveCycle Designer ES2.

1. Right-click the application and select New > Form.
2. For the name, type ServiceRequestDocument.
3. Click Next.
4. For the form’s data model, choose Select A Data Model From A LiveCycle Application.
5. Expand your MobileGuide application and select ServiceRequestModel (see Figure 6).
6. Click Next.

7. In the New Form Assistant, select Use A Blank Form.
8. Click Next.
9. Click Next again, and then click Finish
10. With your blank document open in Adobe LiveCycle Designer, click the Data View palette on the left hand side.
11. Drag the ServiceRequest model onto the form.
12. At this point you may choose to orient the fields as you wish. In the provided sample the fields are vertically aligned (see Figure 7).
13. Choose File > Save and then close LiveCycle Designer.

For more information on creating the form design in LiveCycle Designer see Creating Forms in the documentation.

The next step involves creating the actual process, which will leverage both the data model and the service request form.

1. Right-click your application and select New > Process.
2. In the New Process dialog box, type ServiceRequestProcess as the name and click Finish.
3. In the Variables tab, click the "+" icon to add a new process variable.
4. For the name, type mobileXML.
5. Set the Type to xml.
6. Select Process Variable, and then select the Input and Required options.
7. Click Import Asset, and select the data model (ServiceRequestModel) from your application.
8. Uncheck Store Form Data As Xdp (see Figure 8).
9. Click OK.

10. Rename your default programmatic start point to Mobile Startpoint.
11. Add a user step by dragging an Assign Task icon onto your process and connecting it to your start point. When prompted to change your process to long-lived, click Yes. Rename the step as Service Request Approval.
12. Click on the user step and expand the Presentation & Data Settings property group in the Process Properties view.
13. Select Use Application Asset.
14. Set ServiceRequestDocument.xdp as the asset.
15. Set the Variable to mobileXML (see Figure 9).
16. On the Workspace User Interface tab uncheck Form Must Be Displayed When Completing.

Including meaningful text on the Task Instructions tab will help provide context to mobile users participating in workflows. Your text can include expressions that include data references from your process variable. The process variable in this case, named mobileXML, is the data received from the mobile form.

17. To insert an expression at any point within your text, click Insert Expression in the Task Instruction property group to launch the XPath Builder.
18. Use the XPath Builder to create an appropriate task instruction for the service request. For example:

19. Next, add actions to your process by dragging two Abstract Activity icons onto your canvas.
20. Name one activity "approve" and the second "reject".
21. Connect them both to the Service Request Approval step as shown in Figure 10.

22. Select the Service Request Approval step and expand the User Actions properties group.
23. Add an action named Approve and associate it with the approve destination.
24. Add an action named Reject and associate it with the reject destination (see Figure 11).
25. Choose File > Save.

Now you can deploy your application to the server:

1. Right-click the application and select Deploy.
2. Select Check In All Files
3. Click OK.

For more information on designing human-centric processes see Application Development Using LiveCycle Workbench ES2.

Configuring security for your process

How you choose to secure your process is entirely up to you. For internal business processes you might choose to secure your service and authenticate users against a corporate LDAP directory. For mobile forms deployed for customer use, you may choose to allow anonymous access.

To configure security:

1. Log into your LiveCycle ES2 administration console.
2. Click Services.
3. Click Application and Services.
4. Click Service Management.
5. Filter by category or by name. For this example, find the MobileGuide service.
6. Click the service name to edit it.
7. Click the Security tab.

   For the sample application ’you’ll require clients to supply credentials when invoking a service.

8. Select Yes for Require Callers To Authenticate.
9. Next, select Specify Run As and select System (see Figure 12).
10. Click Save.

For detailed information on modifying security settings for a service, refer to LiveCycle ES2 Administration Help.

After submitting the service request form (Figure 3), a new LiveCycle user task will be assigned for that request. Launch LiveCycle Workspace ES2 Mobile on your iPhone and you should now see a new task in your list corresponding to the service request form submitted from your mobile device (see Figure 13).

You can open the task (see Figure 14), view details via the PDF icon (see Figure 15), and then approve or reject the request.

When you approve the request you’ll see a confirmation notice (see Figure 16).

Where to go from here

While HTML is certainly more approachable than native development on mobile devices, it has significant drawbacks. For example, HTML offers little or no access to device capabilities such as built-in cameras, accelerometers, and so on. Looking beyond the iPhone, developing cross-device applications will cause the age-old browser compatibility issue to once again rear its ugly head. Looking forward, our enterprise product group is eagerly awaiting Adobe Flash and Adobe AIR for mobile devices. For more information and updates on the mobile space, see Adobe’s mobile and digital home.

For more information on the iPhone client, see Adobe LiveCycle Workspace ES2 Mobile client for iPhone.