Story: Mass Printing a Correspondence

Narrative
Implementation overview
- getLetterDataElements
- serializeDataElementsToXML
Team members
Best practices/tips and tricks

Narrative

Often a company has the need to send out a mass mailing list to update their customers on new products or services. This user story describes how you can create a letter template and use the mass printing APIs to retrieve data from a data source, and merge these to perform a mass printing of a correspondence.

Implementation overview

For instruction on how to use the Document Composer to create or modify a letter template see Using the Solution Accelerator .

You must already have a data store with the information that you need to populate the fields in your letter template. You must have already created a data dictionary in order to link the data from the data source into your solution, for more information see Story: Creating a data dictionary .

getLetterDataElements

The getLetterDataElements class is used to retrieve the required metadata for your letter, it returns a map with the following string keys:

Key	Description
DDE	This key is mapped with a list of data dictionary elements for this letter. For differentiating between Collection DDEs and other DDEs, Collection DDEs will use a collection marker “[]” to differentiiate them. For example, if DDE "person" has "account" as collection which has composite "accNumber" then path will be set as "person.account[].accNumber" where "[]" indicates that "account" is of type collection.
PH	This key is mapped with a list of Variables ( List<Variable> ) which are used in this letter and for which data need to be provided. All place-holder variables having following binding in this letter will be added into this list: Place holder variables bound to type "User". Place holder variables bound to Data Dictionary of type unprotected in this letter. Any PH variables which are bound as "Literal" or "Variable" or "Field" or "Content" or "Data Dictionary (protected)" will be not be added into this list.
Field	This key is mapped with a list of Fields object (List<Field> ) which are used in this letter and for which data need to be provided. All fields having following binding in this letter will be added into this list: Field bound to type "User". Field bound to Data Dictionary of type unprotected in this letter. Any Field which are bound as "Literal" or "Variable" or "Content" or "Ignore" or "Data Dictionary (protected)" will be not be added into this list.

The getLetterDataElements syntax is as follows:

public Map<String,List> getLetterDataElements(String letterID) throws ICCException;

serializeDataElementsToXML

The serializeDataElements class is used to serialize XML data by setting values of all DDEs, PH and Field elements. This serialized XML can then be consumed by the Generate a Letter PDF API to render the letter. This appends PH and Field data (provided as maps) to the DDI (provided as XML). You can use this API to provide variable and field values before rendering the letter. The values of DDEs are described in this table:

DDE	Description
ddiDataAsXml	The DDI data as XML.
phValues	A map containing the variable name versus its value.
fieldValues	A map containing the somExpr of Field versus the value of the Field.

The serializeDataElements syntax is as follows:

public String serializeDataElementsToXML(String ddiDataAsXml,Map<String,Object> phValues,Map<String,Object> fieldValues)

The XML data given to LetterRenderService.renderLetter() APIs data will have additional elements in following format, where values of place holder variables and fields will be provided.

<data-root> 
... 
   <fields>  <!--starting element for fields --> 
      <field name="field1">value1</field> <!-- field's display-name is field1 and its value is set to value1. --> 
      <field name="field2" somExpr="xfa[0].template[0].field2">value2</field> <!-- Attribute somexpr is optional and can be used when display name is not sufficient to identify field uniquely --> 
      ... 
   </fields> 
 
   <variables> <!--starting element for place holder variables--> 
         <variable name="var1">value1</variable> <!-- variable name is var1 and its value is set to value1 --> 
         ....  
    </variables> 
</data-root>

The DDEs values are provided as part of XML data. The renderLetter() will consider values provided with XML data and if there is value available for corresponding DDE/PH/Field then these values will be set for these DDE/PH/Field. All other values will be resolved through Binding. The field/variable binding will not be considered if XML data is available for variables or fields. For example if a Field is bound to unprotected DD, and if the value for that Field is specified in the xml data then specified value will be used for rendering letter.When no value is set as part of XML data, in that case values of variables/Fields will be set as was previously the case (using bindings if present) and empty in case of binding "User". For example if a Variable is bound to unprotected DD, and no value specified (not xml node for the variable) in xml data, in that case as per binding the DD value will be used when rendering letter.

Team members

The Middleware Developer creates the post process required for this user story. The Application Specialist creates letter templates.

Best practices/tips and tricks

Not applicable to this user story.