Extending your forms for use inside of Adobe LiveCycle Workspace ES by adding reader rights

Additional Requirements

LiveCycle ES

• Try
• Buy

LiveCycle Workbench ES

• Try
• Learn

LiveCycle Reader Extensions ES

• Try
• Learn

In many cases users want to be able to render a PDF form (with advanced functionalities) inside of Adobe LiveCycle Workspace ES, but they are limited to using Adobe Reader to view the form. Adobe LiveCycle Reader Extensions ES enables form designer to extend the use of Adobe Reader to allow for any advanced functionalities that they put into their forms. In this article I will show you how to extend your forms for use inside of LiveCycle Workspace ES.

The concept of the renderer

When a user-based process is created, the process creator will declare an input variable that is used to hold the inbound transmission when the user clicks Submit. This variable also will contain a pointer to the location of the template file that will be used to show the form to the user as well as a link to a special process (sometimes called an orchestration) that will tell the system how to combine that data and template together to show the form to the user. This special process is called a renderer, because it tells the system how to render the form to the user. Different renderers will be used depending on the type of template (XDP versus PDF), data format to be merged, and type of form being generated (PDFForm, Guide, or HTML). Adobe provides numerous samples and standard renderers for your use. Figure 1 shows an example:

All of the renderers follow the same format. They start with a SetValue service, which will modify parameters that are fed into the render operation. This is followed by the RenderForm operation, which is the actual call to LiveCycle Forms ES (which creates the form). Finally, there is an optional step (if the form is being used with LiveCycle Workspace ES) that will inject the FormBridge code into the form to enable it to communicate with the workspace application.

Creating your own render orchestration

Now that you understand how to render a form, you can create your own renderer. A number of excellent examples ship with the product that you can use as a base. In this case, I will assume that you are starting with an XDP form template and will use the renderPDFForm service that is in the Samples/Forms category.

1. In LiveCycle Workbench ES, locate the Samples-Forms category in the Process view. Note that there are many different Render and Submit services for different form types. You will want to use the RenderPDFForm service as your base.
2. Make sure the Samples-Forms category is selected and right-click it and choose the New Process option. The New Process wizard will start.
3. Choose the Copy an existing process option and click Next. Give your new process a name (I chose MyRenderer_RE). Change the category name wherein your orchestration is to reside, if you like.
4. Browse to the process that you want to copy (Samples – Forms/Render PDF Form/Render PDF Form – 1.0) (see Figure 2).
5. Click OK, and then click Finish.

6. Your new process has been created. Locate your new process and edit it. You will need to add the Reader Extensions (RE) step to the renderer.
7. Open the Services view and navigate to the Reader Extensions category.
8. Open that category and drag the Apply Usage Rights operation onto your canvas (after LiveCycle Workspace ES enables form operation).
9. Connect the Workspace enable form operation to the Apply Usage Rights operation. Now you are ready to define the properties for your Apply Usage Rights operation.
10. Click the Apply Usage Rights operation. Open the Properties view. You are now viewing properties for the Apply Usage Rights service (see Figure 3).

11. You can rename your operation to a more meaningful name if you wish (I chose Apply Rights).
12. Expand the Input options by clicking the triangle to the left of the tag.
13. In the Input PDF parameter, you need to indicate which variable contains the document to which you want to apply rights. This is the output variable from the previous step (outFormDoc). To set this, you need to change the parameter to accept a variable instead of a literal value (the default). Click the downward – pointing arrow to open the list of Input options. Choose variable (see Figure 4). You have now indicated that your input document is contained with a system variable.

14. To indicate which variable is to be used, pick outFormDoc from the dropdown list for Input.
15. Next, you need to indicate which Credential Alias will be used. When LiveCycle Reader Extensions ES was installed, a certificate was installed and a Credential Alias referring to this certificate was established. You need to indicate that name in the Credential Alias parameter (in my case it is ARES_CERT). Note that this is a literal value.
16. Now you can choose the appropriate rights that you want to apply.
17. You need to store the resultant document in a variable for use in your process. You will simply overwrite the variable you used for the input (as you do not need it anymore). Repeat for the Output PDF parameter the steps that you did for Input PDF.

     The properties should look like Figure 5:

18. Finally, edit the render Form step. In the Input Properties, set Render At Client to No.

Save your process and activate it. Note that if you do not reference the correct Credential Alias or you try to turn on rights for which you do not have the associated server product (for instance, 2D Barcode), then your process will fail and an error message will be written to the application server log file.

Calling the renderer

Now that you know how to render your forms, how do you call it in your process? When designing your process, you need to create a variable that will hold the data that is merged with the form. If you are using XDPs from Designer, then you need to define a variable of type xfaForm. The xfaForm variable gets associated with a particular template that is in the repository. This association is held in the definition of the xfaForm variable's template URI parameter. You can create the variable by hand and associate the template by browsing to the appropriate template (using the Browse button), or you can simply drag the desired template onto the variables view and it will create the variable and make the association for you (see Figure 6).

If this is the variable that will be used as the first step in your process, it must be set as an input variable. Now that you have defined a variable to hold your data and associated it with a template, you must tell it how to render this form and associate it to a renderer. This is done under the Advanced Settings button.

1. There are two tabs at the top of the dialog box that reflect the Render service to use as well as the Submit service to use. In this case, choose the Render service tab.
2. Make sure that the Enable Render Service checkbox is checked.
3. Now you can browse to the render service that you have created and set it to be used by this variable.

Where to go from here

The ability to customize renderers is not limited to adding LiveCycle Reader Extensions ES. You can modify the renderer to certify forms before delivery to the user. The beginning of the renderer can also be modified to get additional data to merge onto the form (database lookups, web service calls or LDAP queries, to name a few).