Story: Creating postprocesses

    Narrative

    Once the final correspondence is generated, it can be bound to a LiveCycle process. Depending on the project requirement, this process can perform further actions such as archiving, printing, emailing, or sending the review.

    Estimated time to implement the story

    Not applicable to this user story.

    Common questions to ask to clarify requirements

    Not applicable to this user story.

    Requirements addressed

    Not applicable to this user story.

    Implementation overview

    There are two main steps involved in this user story:

    • Creating the process

    • Binding the process to a letter template

    View full size graphic
    Letter Template Editor

    Creating the process

    The process that you bind to a letter template is invoked when the final correspondence is submitted. You can create a process that archives the letter, prints it, sends it via email, or that uses any of the other services available in Workbench.

    When you create the process in Workbench, use the following input variables:

    • inXMLDoc (xml type): This is the data submitted from the final correspondence.

    • inPDFDoc (document type): This is a rendering of the selected letter template and XML, or portfolio template and XML.

    Also use this output variable:

    • redirectURL (string type)

    Note: When you select the process in the Letter Template Editor of the Manage Assets UI, you will only be able to select from processes that use these input and output variables.

    The postprocess is invoked when the final correspondence is submitted. To submit a letter, the Submit servlet (http://<server>:<port>/cmsa/Submit) should be invoked with the letterId and xmlData as request attributes in the HTTP POST call. If xmlData is large, it can also be sent as a multipart/form-data request. The Submit servlet also accepts an optional renderInteractive request parameter used to switch between rendering an interactive or non-interactive (flat) PDF. The default is non-interactive.

    The Submit Servlet performs the following actions:

    • The Letter Submit Servlet uses the Render Service to render the letter with the data XML provided by the Create Correspondence UI. The Portfolio Submit service renders individual letters within a portfolio and then assembles them together, using Adobe Assembler.

    • The Submit service checks the letter or portfolio for the postprocess information and passes the outputs (XML and PDF) to it. For portfolios, an individual letter template’s postprocess is invoked only if it is short-lived.

    When the process is ready, deploy it using Workbench or LiveCycle Administration.

    About the submitted data XML

    As mentioned above, the Submit servlet invokes the postprocess with the letter PDF and the corresponding data XML. The data XML submitted to the postprocess also has additional metadata corresponding to the submitted letter, such as the letter name, submitted time (modificationDate), and so on. The metadata is located in the ICC Control Data section, under the <icc:meta> node. For example, this would be the structure of the XML data submitted to the postprocess:

    <DataRoot> 
    ... 
    ... 
    <!-- the usual XML data here --> 
    ... 
    <!-- ICC Control Data --> 
    <icc:icc> 
        ... 
        ... <!-- this section would contain data corresponding to the selected modules --> 
        ... 
        <!-- Metadata section --> 
        <icc:meta> 
            <!-- Any additional incoming metadata, that may have been sent from DC, and already present in the XML --> 
 
            <letter>[Letter name]</letter> 
            <modificationDate>[Letter submit date]</modificationDate> 
 
            <!-- Any other custom attributes/metada sent from DC via the "cm_" rule, will have entries in the XML here --> 
        </icc:meta> 
    </icc:icc> 
</DataRoot>

    Redirection on submit

    If you want to extend the application to allow redirection to a custom location (URL), you can design a process that performs a set of operations and returns the redirect URL as a response. The Letter or Portfolio Submit service returns XML with the following structure as its response:

    <iccSubmitResponse> 
    <redirect>{url}</redirect> 
</iccSubmitResponse>

    If the postprocess returned a URL, that URL is returned in the response as shown above. Otherwise, the <redirect> element is either not specified or empty. Note that the caller is responsible for validating the URL for security purposes.If a redirect URL is returned, the user is then redirected to the custom location, which could be a signature application that would let the user sign the finished letter or portfolio. You could also add a tag such as "requireSignature", which you could key from in the customized version of the Letter or Portfolio Submit service, to determine whether a redirect is necessary.This provides the ability to capture a signature immediately after submitting a filled letter or portfolio.

    Submitting additional metadata

    If required, you can customize the Create Correspondence UI to send additional metadata to the postprocess invoked after submitting the letter. If the Submit servlet is invoked with (request) parameters whose names start with "cm_", then those attributes are added to the <icc:meta> section, under nodes with the name following the string after cm_ and the value of the node as the value of the parameter.

    For example, if a request parameter cm_agent=Mark Robinson is sent to the servlet, the <icc:meta> node would have a child node <agent>Mark Robinson</agent>, as shown in this example:

    Example:

    <DataRoot> 
    ... 
    ... 
    <!-- the usual XML data here --> 
    ... 
    <!-- ICC Control Data --> 
    <icc:icc> 
        ... 
        ... <!-- this section would contain data corresponding to the selected modules --> 
        ... 
        <!-- Metadata section --> 
        <icc:meta> 
            <!-- Any additional incoming metadata, that may have been sent from DC, and already present in the XML --> 
 
            <letter>SampleLetter</letter> 
            <modificationDate>2010-08-28T08:55:59</modificationDate> 
                <agent>Mark Robinson</agent> 
            <!-- Any other custom attributes/metada sent from DC via the "cm_" rule, will have entries in the XML here --> 
        </icc:meta> 
    </icc:icc> 
</DataRoot>

    Configuring the parameter names

    You can configure the input parameter names for the postprocess and the output URL parameter name (if any) in cm.properties. For example: 

    # PDF Submit parameters 
# name of input parameter in the process that accepts the PDF Document 
# input variable type: org.w3c.dom.Document 
pdfDocParamName=inPDFDoc 
 
# name of input parameter in the process that accepts the XML data Document 
# input variable type: xml 
xmlDocParamName=inXMLDoc 
 
# name of output parameter in the process that returns a URL to be redirected to 
# output variable type: string 
urlParamName=redirectURL

    Note that only processes that accept the input parameters configured above (either pdfDocParamName or xmlDocParamName, or both) are available for selected in the Letter Template Editor in the Manage Assets UI. The urlParamName is optional, if there is a need to redirect.

    Binding the process to a letter template

    When you create a letter template in the Manage Assets UI, you can specify a postprocess to bind to the letter template. When the final correspondence is submitted, the process is invoked. For details on creating a letter template and adding a postprocess, see Create a letter template.

    Tools used

    This story uses Workbench to create the process, and the Manage Assets UI to bind the process to a letter template.

    Team members

    The Middleware Developer performs the tasks in this user story.

    Best practices/tips and tricks

    Not applicable to this user story.