Story: Integrating the Create Correspondence UI with your enterprise system

Narrative

Depending on your organization’s requirements, you may decide to invoke the Create Correspondence UI with data from an external source.

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

Before you do any customization work, you must set up your development environment. For information, see Setting up the Development Environment in the Asset Manager Building Block Technical Guide.

There are two ways to invoke the Create Correspondence UI with data from an external source. You can use a custom servlet or use a LiveCycle process.

Using a custom servlet

The URL to the Create Correspondence UI accepts a request parameter named cmDataUrl, which is a URL that returns an XML data in response. The Create Correspondence UI uses this data as the Initial XML Data (IXD) to render the Letter.

To integrate the Create Correspondence UI to fetch and render the letter using data from an external data source:

  1. Write a custom HTTP servlet that retrieves the XML data from the external data source. Return the retrieved XML data in the servlet's "response".

  2. When invoking the Create Correspondence URL, set the value of the cmDataUrl as the URL to your servlet created in step 1.

You can define the servlet in the correspondence management application itself, or expose it on another web server.

For example, if the servlet is created within the correspondence management application and is mapped to the URL /CustomDataUrl, then the URL to the Create Correspondence UI would be http://<server>:<port>/cmsa/dc?<usual request parameters>&cmDataUrl=http://<server>:<port>/cmsa/CustomDataUrl

Since the URL given as the cmDataUrl is just another HTTP URL, it can have its own set of request parameters that may be necessary to fetch data from the external data source. For example, to fetch the data for a customer with the SSN "1234", the URL to the Create Correspondence UI would be http://<server>:<port>/cmsa/dc?<usual request parameters>&cmDataUrl=http://<server>:<port>/cmsa/CustomDataUrl?ssn=1234.This is a sample servlet that returns a hard-coded XML:

package sample; 
 
import javax.servlet.ServletException; 
import javax.servlet.http.*; 
import java.io.*; 
 
 
public class ReturnXml extends HttpServlet { 
    public void doGet(HttpServletRequest request, 
             HttpServletResponse response) 
                throws ServletException, IOException 
          { 
            response.setContentType("text/xml"); 
            PrintWriter out = response.getWriter(); 
 
                // Replace the below line with an invocation to an external/legacy data source/API. 
                String xml = "<?xml version='1.0' encoding='UTF-8'?><F><P1><WCCFileNumber>9875</WCCFileNumber><SSN>3459837</SSN></P1></F>"; 
 
                // Write to the response stream 
            out.println(xml); 
            out.close(); 
          } 
 
 
}

Using a LiveCycle process

To feed the Create Correspondence UI with an appropriate Initial XML Data to render the letter, you could also use a LiveCycle process-based approach:

  1. Write a process that retrieves the XML data from the external data source (if not already available in the process) and saves this XML data on a physical (disk) location on the server.

    The process then returns the URL to the data file (the filepath of the saved file, which would be something like file:///c:/data/sample.xml).

  2. Before invoking the Create Correspondence UI, your correspondence management application needs to invoke the LiveCycle process, and capture the response/output of the process (the filepath to the data file).

  3. Invoke the Create Correspondence UI by setting the value of the cmDataUrl as the returned filepath.

    The URL to the Create Correspondence UI would look something like *http://<server>:<port>/cmsa/dc?<usual request parameters>&cmDataUrl=file:///c:/data/sample.xml*

Team members

This user story would be performed by a Flex Developer.

Best practices/tips and tricks

Not applicable to this user story.