Archive for November, 2010

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….