LiveCycle Developer Center

Routing a form to a user's manager

This document outlines the process of creating a workflow that routes a form to a user's manager. Based on two fields of a PDF Form that contain the first and last name of the form filler, you'll use two Quick Process Action Components (QPACs) to query an LDAP server for the user's manager, then route the form to the manager's worklist in Adobe LiveCycle Form Manager.

To complete the task, you'll need to do the following:

• Set up the LDAP Search QPAC
• Prepare your workflow
• Use the LDAP Search QPAC
• Modify the LDAP Search QPAC to work with process data
• Route the form to the manager using the User QPAC
• Customize the instructions

You'll also need the following LiveCycle software:

• LiveCycle Designer
• LiveCycle Forms
• LiveCycle Form Manager
• LiveCycle Workflow

Note: This document assumes that you understand the basics of LiveCycle Workflow 7, LiveCycle Form Manager 7, and LiveCycle Designer 7. It also assumes that you understand the basic concepts of LDAP.

The LDAP environment used is Microsoft Windows 2003 with Active Directory providing the user details and organizational structure. Other LDAP systems can be used, such as Sun One, with the appropriate syntax changes.

Setting up the LDAP Search QPAC

The LDAP Search QPAC requires that its deployment settings be set up before it can be used in one of your workflows.

1. Right-click the LDAP Search QPAC in your Components palette and select Component Properties.

2. On the Deployment Settings tab, enter your connection settings to your LDAP server as follows:

   • Initial context factory: com.sun.jndi.ldap.LdapCtxFactory
   • Provider url: Enter the URL of your LDAP server.
     For example, ldap://192.168.1.1:389.
   • Username: Enter a user on the LDAP system that has "read" access to the directory. For example, MYDOMAIN\livecyclesystem where the account livecyclesystem is part of the MYDOMAIN domain.
   • Password: Enter the password for the user you have defined in the Username field.

Your LDAP Search Component Properties dialog box should look like Figure 1.

Figure 1. Enter your connection settings to your LDAP server

Preparing your workflow

You need to create a process variable of type string to store your manager's account name. Click the + sign, enter a variable name, and change the type to string (see Figure 2).

Figure 2. Prepare your workflow

Using the LDAP Search QPAC

Now you can start setting up your LDAP Search QPAC as part of your workflow. Drag a new instance of the LDAP Search QPAC on to your workflow. A new dialog box will appear as shown in Figure 3.

Figure 3. Action Properties settings

Open the Settings tab and click the Refresh button to populate the Base DN pull-down menu with the default values. Choose the appropriate Base DN. For example, DC=mydomain,DC=com.

Note: If you cannot see anything in the pull-down menu, you may have incorrectly set up your deployment settings for this component.

Next you can set the Search context, which defines the starting point of your LDAP search. You can also use the Browse button to point and click from your LDAP tree. For example, CN=Users, DC=mydomain, DC=com.

The Search filter allows you to enter the LDAP query. For testing purposes at this stage, it is a good idea to enter a search that you know will return the results that you require.

In this instance, you are trying to find out the manager for the user who filled out the form. By taking the First and Last Name field data submitted from the form, you can query LDAP to find out which manager has that user listed in the directReports entry.

If you are using Microsoft Active Directory, the data is entered via the Active Directory Users and Computers tool found in the Administration Tools. Change the entries on the Organization tab.

Figure 4. Data entries on the Organization tab

This LDAP data is viewable in many utilities, such as in Softerra LDAP Browser as shown in Figure 5.

Figure 5. Viewing directReports data entries

Here you can see the exact name and value that you need to query.

To find the entry in the snapshot, use the following query:

directReports=CN=Mark Szulc,CN=Users,DC=mszulc,DC=com

Now that you have specified your search, select the data that you want the LDAP query to return. In this case, you want the manager's user ID so you can route the form accordingly. See Figure 6.

Figure 6. Specifying the attributes you want to capture

By clicking the Refresh button on the bottom left, the available attributes are displayed in the left pane.

The only attribute you need is the sAMAccountName, which is the account ID of the manager. Select that attribute in the left pane, then click the > arrow to move it to the Selected pane.

You can now test your query to make sure that you are getting the expected results. Click the Test tab, then click the Test button on the bottom right.

Figure 7 shows the expected results for your query.

Figure 7. The expected results for your query

Modifying the LDAP Search QPAC to work with process data

Now that you know your query works, you can customize the query using field values from your form (see Figure 8).

Figure 8. Field values from your form

First, merge your field values with your Search filter:

Field values:

The following lists the path to the form field data, which is currently held in a Process Variable called varForm.

{$/process _ data/varForm/form data/data/xdp/datasets/data/
TravelAuthorisation/Traveller/FirstName$}

{$/process _ data/varForm/form data/data/xdp/datasets/data/
TravelAuthorisation/Traveller/LastName$}

Search filter:

directReports=CN=Mark Szulc, CN=Users, DC=mszulc, DC=com

What you get:

directReports=CN={$/process _ data/varForm/form data/data/
xdp/datasets/data/TravelAuthorisation/Traveller/FirstName$}
{$/process _ data/varForm/form data/data/xdp/datasets/data/
TravelAuthorisation/Traveller/LastName$},CN=Users,DC=mszulc,DC=com

Next, on the Output tab, take the result of the query and assign it to your process variable, varManager as shown in Figure 9.

Figure 9. Assigning a process variable

On the Output tab of the LDAP Search QPAC, you can assign a process variable to hold the output of the LDAP attribute.

It is also good practice to capture the Result Count, which captures the amount of results. Ideally this should be 1, meaning there is only one match, but you should build logic into your workflow to handle the event where there is no match or more than one match. Failure to do this may cause a stalled process later when you try to assign a task to a nonexistent manager.

Figure 10 shows the Search Filter with the custom search in place.

Figure 10. The Search Filter with the custom search in place

Routing the form to the manager using the User QPAC

You now have your manager's account name stored in your process variable. To select who the form should be routed to, use the following steps:

1. Open the Initial User tab.
2. Select the Use XPath Expression option.
3. Enter the XPath expression that specifies the process variable holding the manager's account name.

In this case, the varManager process variable is used. See Figure 11 below.

Figure 11. Routing the form to the manager

Customizing the instructions

You can also customize the instructions given to the manager simply by adding process variable data into the Instructions field. This example uses the same two variables from your form:

"Please review this Travel Request for {$/process _ data/
varForm/form-data/data/xdp/datasets/data/
TravelAuthorisation/Traveller/FirstName$} {$/process _
data/varForm/form-data/data/xdp/datasets/data/
TravelAuthorisation/Traveller/LastName$}"

Then, save your workflow and deploy. Your completed workflow should look like Figure 12 below.

Figure 12. Your completed workflow

This simple example demonstrates the ability to route information to users based on the organizational structure.

There are many ways to query LDAP information, and these methods should be investigated to ensure that optimum performance is achieved. With a large LDAP database it would be far simpler and quicker to navigate the relationship the other way, which is to find your record in LDAP, and then find your manager.

One way to do this is to use two LDAP QPACs in succession. Another way to do this is to use the recursive feature on the advanced tab. By entering "manager" into that field, it will return the record referenced by the manager DN, rather than the initial record it finds. Effectively, it will do the second lookup for you.

About the author