Adding SMS, fax, e-mail, and voice notifications to LiveCycle ES processes

Many business processes can be made more intuitive and engaging (and ultimately easier to use) by including SMS, fax, voice, and other notifications to their participants throughout the process. Regardless of the nature of the business process, making it more engaging can lead to reduced user abandonment of applications, fewer support calls, more repeat business, and higher overall satisfaction for process participants. Very simply, people just feel better about the organization they are working with when they receive consistent and expected updates about the status of an important process in which they are engaged.

A classic example is applying for a loan. Like many people, I've bought and refinanced property a few times, and I’ve always appreciated lenders that kept me informed about where I was in the overall process. For example, some lenders notified me when they received my application, preapproved the loan, performed the appraisal, completed the title work, issued the final approval, and scheduled the closing date.

To help you build communications-enabled business processes, Premiere Global Services (PGi), an Adobe partner, has released a set of components that make it very easy to add electronic notifications to Adobe LiveCycle ES (Enterprise Suite) applications. The PGi components for LiveCycle ES provide interfaces that you can use to add SMS, fax, e-mail, and voice communications to your processes. The PGi components function by interfacing with the Premiere Global Communications Operating System (PGiCOS), a SaaS-based platform supporting various types of business-critical communications.

In this article, I’ll walk you through the steps of adding a PGi communication service to a LiveCycle ES process. You’ll start by opening the Mortgage Loan sample application included with LiveCycle ES, which you may already be familiar with. Then, you’ll extend it by adding an SMS notification to the loan applicant at the end. When you’re finished, you should have the knowledge and tools needed to include any of the PGi notification services in your LiveCycle ES processes.

Installing PGi Components for LiveCycle ES

To complete this tutorial, you’ll need access to an instance of LiveCycle ES Update 1 and LiveCycle Workbench ES. The LiveCycle ES instance also needs to have the sample applications installed. You can download a free trial of LiveCycle ES, which includes LiveCycle Workbench ES and the sample applications, from Adobe’s website.

In addition, you’ll need a copy of the PGi components for LiveCycle ES, which are packaged in a Java archive (JAR) file. The JAR file is available from PGi.

If you plan to execute the process developed in this tutorial, you’ll need an active PGi account with messaging capabilities. To obtain one for testing, send an e-mail with your request to adobecomponents@pgi.com.

Before starting the development process, you need to install the PGi components for LiveCycle ES. To perform the installation, follow these steps:

1. Open LiveCycle Workbench ES and connect to the LiveCycle ES instance you’ll be working with.
2. Navigate to the Components view, right-click the Components folder, and select Install Component (see Figure 1).

3. In the dialog box that appears, navigate your local file system and select the JAR file containing the PGi components (see Figure 2).

The initial state of the component after installation will be stopped (note the red icons). This is expected. To start the component, right-click the component and select Start Component (see Figure 3).

Once started, the component and its services will have green icons (see Figure 4).

Opening the Mortgage Loan process

Now that the PGi components are installed and ready to use, you can select and open the LiveCycle ES process that you want to extend. In this tutorial, you will extend the MortgageLoan - Prebuilt sample process that comes with LiveCycle ES. It can be found in the Samples – LiveCycle ES category. To open it, right-click the process in the LiveCycle Workbench ES Processes view and choose Edit (see Figure 5).

Note: This is the same process that is built if you perform the quick start tutorial titled Creating Your First LiveCycle ES Application. The quick start tutorial is part of the LiveCycle ES online documentation. Refer to this quick start tutorial if you want more information about how this process is constructed.

For this PGi component tutorial, you need to work with an unmodified version of this sample process, to ensure you get the expected results. After opening the MortgageLoan - Prebuilt sample, you should see the initial process diagram (see Figure 6).

This process is invoked when a user submits a loan application form using Adobe LiveCycle Workspace ES. In summary, the first operation in the process (Get Form Information) retrieves values from the submitted form. If the loan amount on the form is less than $500,000, then the form is routed to a loan officer for review. Otherwise, the form is routed to the bank manager. Either the loan officer or the bank manager then makes an approve/decline decision.

Although not required for this tutorial, you may want to view the form that supports this process. To do this:

1. Navigate to the Form Design perspective of LiveCycle Workbench ES.
2. In the Resources view, navigate to the Samples folder and find the file named MortgageAppForm.pdf (see Figure 7).

3. Open the form (see Figure 8), but do not change it.

Retrieving the phone number from the submitted form

To begin modifying the process, navigate back to the Process Design perspective in LiveCycle Workbench ES. The first change to make is to retrieve the phone number from the submitted form (the process already retrieves the loan amount). The phone number value needs to be set in a variable so it can be passed to the SMS operation that you’ll be adding in a subsequent step. To keep the tutorial simpler, I’ll assume the customer will input a mobile number into the form’s phone field. You can change the label (caption) on the phone number field to read Mobile Number if you wish.

Follow these steps to retrieve the phone number from the form:

1. Create a process variable in which to store the mobile number by clicking the new variable icon in the Variables view (see Figure 9).

2. Set the variable’s Name to PhoneNbr, its Title to Phone Number, and its Type to string. Type a description. Define it as a required process variable and set its maximum length to 14 (see Figure 10).
3. Click OK.

Now that the phone number variable is created, you can update the mapping property of the Get Form Information operation to perform the retrieve. To do this:

1. Select the first operation in the process (that is, the SetValue operation named Get Form Information).
2. With this operation selected, navigate to the Properties view. In the mappings section of the Properties view, click the plus button to add an entry to the list (see Figure 11).

3. Define the new entry’s location by using an XPath expression that points to the new phone number variable (see Figure 12).

4. Define the new entry’s expression by using an XPath expression that points to the phone number field object in the loan form (see Figure 13).

The new entry will be added to the list of mappings (see Figure 14).

Adding SMS notification to the process

Now that you have defined the phone number variable and configured it to be populated by the process, you can add the SMS notification operation to the mortgage loan process. To add the SMS operation:

1. Drag a new activity object onto one of the process swim lanes (doesn’t matter which one). This will open the Define Activity dialog box (see Figure 15).
2. If it’s not already selected, click the radio button allowing you to select a service operation or process.
3. In the Find text box, type SMS. The list of services is now constrained to those with the string “SMS” in their name.
4. Select the service named SMS Service and click OK.

5. In the process diagram, select the newly added SMS operation, navigate to its Properties view, and define the following properties (be sure to define these as literal values):
   • Name: Notify customer of results via SMS
   • Description: Send text message with results to customer's mobile phone
   • User Name: (type your personal PGi user name)
   • Password: (type your personal PGi password)
   • Receiver Key: http://financecorp.com
   • Note: Any valid HTTP string is acceptable here. Although this field is required, its value is not meaningful for the tutorial.
   • SMS Message: Thank you for your loan application. A FinanceCorp representative will be contacting you shortly.

To actually execute this operation, you’ll need your own PGi account with messaging capabilities. You can obtain an account for testing by sending an e-mail with your request to adobecomponents@pgi.com.

To keep the tutorial simple, I set the SMS Message property to be a literal, hard-coded value. This property defines the actual text that will be displayed on the recipient’s mobile phone. You can define any text message you wish for the tutorial. In a real, production business process, the text message would be defined dynamically by LiveCycle ES based on the results of the loan review. An example of how to construct a dynamic message is included in the Test and Demo Processes document posted on PGi's Adobe LiveCycle Components group page. Refer to the demo process named LoanAppWithNotify in that document for more details.

The next properties to define on the SMS operation are the SMS Recipients and the Result type:

1. To configure the SMS Recipients property, click the down arrow and select Variable (see Figure 16).

2. Then, from the drop-down menu, select PhoneNbr, the phone number variable you defined earlier (see Figure 17).

3. To define the result type, start by clicking the down arrow and selecting Variable as the result property type.

   You now need another variable to contain the results returned by the SMS operation.

4. To create a variable in context, click the plus button located to the right of the property’s text input (see Figure 18).

5. In the Variable dialog box that appears, type SMSRequestResult as the Name and Results from SMS service request as the Title. The Type should already be set to SMSServiceResultType (see Figure 19)
6. Click OK.

Note that the variable’s data type (SMSServiceResultType) was selected by default. One benefit of defining the variable in context is that LiveCycle Workbench ES can preselect the data type based on the property you are currently defining.

You are now finished configuring the SMS notification operation. Except for the user name property (“truhl” is my user name—substitute your own here), your operation’s properties should appear as shown in Figure 20.

To complete the process definition, create connections (routes) between both the loan officer and bank manager operations with the SMS notification operation (see Figure 21).

Testing the updated LiveCycle ES Process

After saving the work you’ve completed thus far, you are ready to test the loan process with the newly added SMS notification.

1. In your browser, open the LiveCycle Workspace ES web application located at http://<LiveCycle-host>:<port-nbr>/workspace/. For example, the LiveCycle ES instance I’m using is running on my local computer using port 8080, so the URL to my LiveCycle Workspace ES application is http://localhost:8080/workspace/.
2. When the LiveCycle Workspace ES login page appears, type apink as the User ID (see Figure 22). Alex Pink (apink) is a demo user included in the LiveCycle ES samples. For the password, type password (unless you know the password has been changed to some other value).

3. After logging in, navigate to the Start Process page and click the category named Samples. Several processes should be displayed in the list.
4. Click the process named MortgageLoan – Prebuilt to initiate the loan application process (see Figure 23).

5. After the application form supporting this process is rendered and displayed in LiveCycle Workspace ES, complete the form using your own mobile phone number and a loan value less than $500,000 (see Figure 24)

Note: You’ll need to input a real, working mobile phone number for your test. Also, notice that after you tab away from the phone number field, the value will be formatted automatically to include parentheses and a hyphen.

6. Click Complete to submit the loan application to (the fictitious) Fin@nce Corp for review.

In this sample process, Alex Pink is the loan officer who handles loan applications under $500,000, such as the one you just submitted. Conveniently, you’re logged into LiveCycle Workspace ES as user apink, so you can now review the submitted application. Navigate to the To Do page, and in a few moments, you should see a loan review task arrive in Alex’s queue (see Figure 25).

To take ownership of and complete the task, follow these steps:

1. Click on the task card; the submitted loan application will be displayed.
2. Select either the Approved or Declined check boxes (for this tutorial it does not matter).
3. Click Complete (see Figure 26).

If everything executed correctly, you should receive the text message on your mobile phone within just a few seconds (see Figure 27).

The result from the SMS service request (that is, the response from PGiCOS to your SMS request) is stored in the SMSRequestResult variable you previously defined. The easiest way to view the values of the result is to use the record and playback feature of LiveCycle Workbench ES. To do this, you must first start recording the executions of the process. Right-click the process diagram and select Start Recording (see Figure 28).

With the Start Recording option set, all future instantiations of this process will be recorded until you select Stop Recording. If you wish to play back a recording of your loan process, you’ll need to perform your test again with the recording option turned on.

To play a recording of a previous process execution and view the request response values:

1. Right-click the process diagram, and this time select Play Process Recording (see Figure 29).

2. Select the process instance you wish to playback and click OK (see Figure 30).

3. After the playback is complete, remain in playback mode and navigate to the Variables view.
4. In this view, click the ellipsis button in the Value column of the SMSRequestResult variable (see Figure 31).

5. A Variable dialog box will open and display the result values. Assuming the request was successful, you will see a status code of 0 (zero) among the results (see Figure 32).

Where to go from here

In this tutorial you saw how to install the PGi component for LiveCycle ES and modify an existing LiveCycle ES process to get a phone number value from the form. More importantly, you’ve learned how to change the process by adding an SMS notification operation, employing one of the services included in the PGi component. Finally, if you have a PGi account, you saw how to test the process.

To keep the tutorial brief, I included instructions for adding only an SMS notification to the process, but the same basic steps could be used to add fax, e-mail, and voice notifications as well. Each communication operation requires different values to be passed to it, so you would need to define and populate additional variables. However, the same basic flow used in this tutorial would apply.

Be sure to check out the documents and discussions about the PGi components on PGi's developer community group website, where you’ll also find complete examples, test processes, and demos for each type of communication service.