Posts tagged "correspondence management"

Creating Text using the Correspondence Management APIs

While the classic way of creating Text in the Correspondence Management SA is using the Text Editor UI component, one may also want to create one or more Text modules using an API.

Following are the objects/services involved in creation of a Text Module using the APIs:

Here’s a sample of how to use these:

Creating the Text Module instance

TextModule tm = new TextModule(); // no-arg constructor
text.setName(textModuleName);
text.setDesc(description); // a meaningful description of the Text
text.setComment(comment); // a comment associated with the Text
text.setLcat(subCategory); // 'subCategory' is the SubCategory for the Text, and is of type 'com.adobe.icc.dbforms.obj.Category'
text.setUcat(category); // 'category' is the main Category for the Text, and is of type 'com.adobe.icc.dbforms.obj.Category'
text.setDataDictionaryRef(dataDictionaryName); // Name of the Data Dictionary used in this Text, if any.
text.setTBXXML(tbxXMLString); // tbxXMLString is a well-formed XML, that should comply to the expectations of a Text Module XML format. You could import/read this XML from a file using any of the standard java File reading utilities. It should have details such as the Text's plain text content, flash-html text content, xfa-xhtml content, etc. See the description on the TextModule API for more...

Here’s a sample XML that could be provided:

<content>
<guid/>
<name>text_test</name>
<desc>the description</desc>
<plainText>This is a paragraph with a variable: {^var^}</plainText>
<flashRichText><TEXTFORMAT LEADING="2" TABSTOPS="36,72,108,144,180,216,252,288,324,360,396,432,468,504,540,576,612,648,684,720"> <P ALIGN="LEFT"><FONT FACE="Times New Roman" SIZE="12" COLOR="#000000" LETTERSPACING="0" KERNING="0"> This is a paragraph with a variable: {^var^}</FONT></P></TEXTFORMAT>
</flashRichText>
<xfaXhtml><body xfa:APIVersion="2.4.5277.0" xmlns="http://www.w3.org/1999/xhtml" xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"> <p xml:space="preserve" style="text-align:left"><span style="letter-spacing: 0px; color: #000000; font-size: 12px; font-family: Times New Roman; xfa-spacerun:yes"> This is a paragraph with a variable: {^var^}</span></p></body>
</xfaXhtml>
</content>

The TextModule object API also exposes a comprehensive constructor that could be used to create a Text Module.

Persisting the Text Module instance

Now, once you have defined the above ‘text‘ object, you can persist that using the DataModuleService APIs. Here’s how:

DataModule dm = dataModuleService.createDataModule(text); // the returned 'dm' is the persisted Text module. you may further cast this into a 'TextModule'.

Managing the Text Module instance

You could also perform other actions  such as activate, update, etc. on the created Text (or already existing Texts) using the DataModuleService APIs such as activateDataModule(DataModule), updateDataModule(dataModule), etc. Please refer to the DataModuleService API docs for more.

See here for a comprehensive list of the CMSA documentation.

Role based access control on the Correspondence generation interface

More often that not would there be a need to prevent Correspondence generation access for non-eligible users, i.e. the user interface for creating a correspondence (Create Correspondence aka Document Composer UI) should not allow entry to such users and throw an (Access Denied) error.

Such access control can be achieved with a quick and simple customization in the solution’s security configurations (which is, by the way, backed by Spring Security). Here’s how…

The solution exposes a security configuration XML (placed @ [LiveCycle_ES_Home]\sa_resources\SA_SDK_9.5\CorrespondenceManagement\FSIApp\Portal\resources\spring-config.xml in the Solution Template). In order to secure the Create Correspondence UI to allow access to only people with a pre-defined role, say Correspondence Management Create Correspondence User, you need to:

  1. Create the above role (Correspondence Management Create Correspondence User) using the LiveCycle Administration UI), if it does not already exist.
  2. Add the following in the security configuration file (security-config.xml, indicated above), along with the other <sec:intercept-url…> elements in it:

<sec:intercept-url pattern=“/dc” access=“lcAuth:Correspondence Management Create Correspondence User” />

The above interception basically means that, when a user tries to invoke the application (which is exposed at the URL http://server:port/cmsa/dc), the system intercepts the request to check for the mentioned roles in the current user’s roles. Hence, as per the above configuration, this would only allow those users who have the “Correspondence Management Create Correspondence User” role to access the Create Correspondence UI.

Note: You can provide access to any other or more such roles by adding those roles (comma-separated) in the access attribute in the configuration above (do remember to prefix the LC roles names with lcAuth:).

Retrieving latest ACTIVE asset in the Correspondence Management Solution Accelerator

The Correspondence Management Solution Accelerator involves the concept of activating and versioning assets; if an Active asset is chosen for EDIT, you are prompted to create an Inactive copy of the asset which can then be edited. You can edit that Inactive copy and finally Activate it once completed with the editing. This Inactive copy now becomes the Active version, and the original version will be Archived. This process may continue as the asset is edited (and activated) again and again, thereby creating multiple versions of the asset in the system.

However, at any given time, there will only be a single ACTIVE version of the asset in the system (others being in ARCHIVE state). Hence, often may arise, due to various customization requirement, the need to search for this latest ACTIVE version for a given asset in the system. The Asset Composer Building Block provides APIs to easily achieve this.

Here’s an example to fetch the latest ACTIVE version of a given Letter (identified by its name) in the system:

// Build the Query object
Query qry = new Query();
Statement st1 = new Statement();
Statement st2 = new Statement();

// Set the statement attribute 'name'
// and value to name of the Letter
st1.setAttributeName("name");
st1.setOperator(Operator.EQUALS);
st1.setAttributeValue(letterName);

// Set the statement attribute name value to state
// and value to 'ACTIVE'
st2.setAttributeName("state");
st2.setOperator(Operator.EQUALS);
st2.setAttributeValue(DBConstants.ACTIVE);

// building query
qry.addStatement(st1);
qry.addStatement(st2);

List letterList;

try {
// fetching the Letter with the query constructed above
// must have an instance of the LetterService here (may be via Spring Dependency injection).
letterList = letterService.getAllLetters(qry);

String letterId = letterList.get(0).getId();
// Obtaining Form object, as getAllLetters query does not return
// 'full' form object
Letter letter = letterService.getLetter(letterId);

} catch (Exception e) {
// handle exception
}

Re-Activating old, archived assets in the Correspondence Management Solution Accelerator

The Manage Assets user interface of the  Correspondence Management Solution Accelerator allows various operations on assets, such as Create New, Active, Edit, Delete etc. When an asset (that should be in Inactive state) is Activated, any existing Active asset by the same name is Archived and this asset becomes the new Active asset (with an incremented version number; thus creating a new version of the asset).

Now, there could be a need to re-Activate the previous (now archived) version of that asset. The Manage Assets UI does not (out-of-the-box) allow you to do so (these actions are disabled on the UI, and the APIs also restrict the same). However, there are set of server side APIs that you could use/invoke to achieve the same (perhaps, configuring it as a custom Action on the Manage Assets UI, that in-turn invokes a custom service/operation which wraps the below steps/functionality).

Here are the (logical) steps that you’d need to take to be able to do so:

  1. Firstly, move any existing Active version to Archive, since you are not allowed to have multiple Active versions of the same asset. Obviously, this Active version MUST NOT be in use by any other asset.
  2. Fetch and Update the (archived) version of the asset object (that you wish to activate), setting its state to “Active” and version to “[version of the previous active asset] + 1″.

In terms of API calls, here is what you’d do/invoke (refer the API listing for details on usage of these APIs):

  1. Fetch the latest available Active asset object (if you already do not have that) — you could use the getAll[Asset-type]() like APIs to search for such an object (Asset-type being either DataModule, Letter, Form, etc., depending upon the asset that you are working on). For example, to fetch the current Active version of a Letter, you could use the LetterService.getAllLetters(Query query) API (building the appropriate Query for this).
  2. Delete the object fetched in (step 1) above, using the delete[Asset-type]() like APIs; this will move the current Active asset to Archive. For example, to delete/archive the current Active version of a Letter, you could use the LetterService.deleteLetter(String letterID) API (where letterID is the ID of the asset to be deleted).
  3. Fetch the asset object that you wish to (re)activate — again, searching for it using the getAll[Asset-type]() like APIs, as mentioned above. You’ll need to retrieve the full object by invoking the corresponding get[Asset-type]() API; for instance, LetterService.getLetter(String letterID) if you are working with Letters (where letterID is the ID of the Letter that you have searched for).
  4. Set the state of the object fetched in (step 3) to Active, using the Asset.setState(DBConstants.STATE_ACTIVE) API.
  5. Set the version of the object fetched in (step 3) to ([version of object fetched in (step 1)] + 1)
  6. Then, update this (state and version modified) object using the update[Asset-type]() like API; for instance, LetterService.updateLetter(Letter letter).

One important point to be noted here is that it is not advisable to (re)Activate an asset that in-turn uses/references other Archive assets (reason being, the Manage Assets UI does not allow you to work with or use/select/de-select Archived assets when authoring an asset; so, it may be difficult for you to work with (EDIT, in particular) such assets on the Manage Assets UI). Hence, one should first (re)activate the dependent assets (using the above steps) and then (re)activate the parent asset.

Extending the LiveCycle ES 2.5 Correspondence Management Solution Template to enlist additional Letters

The LiveCycle Correspondence Management Solution Accelerator’s Solution Template comes with a default set of Letter Templates (a.k.a Correspondence Templates) that are enlisted on the ST as shown below:

However, one can easily extend the Solution Template (ST) to enlist more such Templates that have been designed (and present) in the system. This can be done by adding the necessary details for the Letter in the InsuranceCorrespondece.xml file of the ST (available @ [LiveCycle_ES_Home]\sa_resources\SA_SDK_9.5\CorrespondenceManagement\FSIApp\Portal\resources).  Basically, one needs to add an entry in it for the Letter to be listed, with the entry containing the  “Display name” for Letter (in the drop-down) and the actual ‘name’ of the Letter, as given during the Letter Template authoring. Here’s an example:

Obviously, when a Template is selected on the ST, the Create Correspondence (CCR) UI is invoked for that Letter with the XML data for the corresponding user. The name of the XML data file, used to invoke the CCR UI with, should be of the form: <Username>.xml and should be placed in a folder under the following structure “assets/Letter/<Letter name>/Data/<Username>.xml“, where the “assets” folder is present at the root of the ST (i.e., @ [LiveCycle_ES_Home]\sa_resources\SA_SDK_9.5\CorrespondenceManagement).

For instance, the XML file name, containing data for the user “Akira Tananka” for a Letter named “SampleLetter”, should be placed as “assets/Letter/SampleLetter/Data/AkiraTanaka.xml” (just as you would find for the other Letters).

That’s it! You could go ahead and add any number of Letters this way….

Adobe LiveCycle ES 2.5 and the Correspondence Management

Adobe LiveCycle ES 2.5 and the Correspondence Management Solution Accelerator together revolutionize the way we create, author and manage correspondence. It provides a platform that helps enterprises quickly build and deploy applications that enhance customer experiences and overall productivity via compelling interactions. The various UI tools provided enable enterprises to create a custom and enhanced user experience right from correspondence authoring to generation.

The solution accelerator, along with the LiveCycle platform, allows interactive as well as system-driven correspondence generation in the form of a single PDF document (interactive or non-interactive) or a PDF Portfolio (with the ability to arrange documents in a hierarchical folder structure), with custom navigators, cover pages, etc. A comprehensive correspondence authoring is achieved via the use of Data Dictionaries (logical, hierarchical representation of the underlying data schema), Categories/Subcategories, reusable Layouts (XDP templates that can be used to define any number of Letter templates), and complex pre-approved content.

When integrated with LiveCycle Process Management (and possibly other solution accelerators and LiveCycle components such as Managed Review & Approval), one can design and achieve a complete workflow for the enterprise. The solution also provides integration mechanism with external third party systems for correspondence generation.

Also visit the LiveCycle Developer Center for more.