Posts tagged "solution template"

Understanding and Configuring the Correspondence Management Manage Assets interface

While the out-of-the-box experience of the Manage Assets interface will blow you away, it is worth noting that the interface itself is highly configurable, given that deployments of the Correspondence Management solution may need a different/customized look-n-feel of this interface, based on specific customer requirements.

The overall knitting of the UI components on the interface is done using the AMApplicationSkin.mxml which you can find in the CM Solution Template @ CorrespondenceManagementSolutionTemplate\ManageAssets\src\com\adobe\solutions\cmg\manage\skins\AMApplicationSkin.mxml.

Here’s a quick look at the high-level components:

 

 

 

 

 

 

While what’s shown on the Application Header (the various tab navigators) is largely governed by the (customizable) application’s skin (AMApplicationSkin), the rest of the UI components (i.e., which actions/buttons to be shown on the Application Toolbar, which columns to be shown in the Search Results Grid and which properties to be shown in the Advanced Search panel when searching) are driven by an XML definition, i.e. asset definition FMLs, which require almost no code changes to get yourself a customized UI experience. You will find these asset definition FMLs under /apps/solutions/cm/assetDefinitions in the CRX repository. See snapshot below:

 

 

 

 

 

 

 

 

 

 

 

Note that you will find two sets of FMLs there. Ones that are named [Asset type].fml and ones that are named [Asset type]-publish.fml – the former being the definitions used for the solution’s Author instance and the latter for the Publish instance.

The initial view of the Manage Assets interface lists all assets in the system. That is because the default view has all assets selected for search (“Search all assets” in the Advanced Search panel- see snapshot above). This view uses the Asset.fml descriptor as the UI definition/design. The same descriptor is used when searching for assets across multiple asset types. However, when searching for a specific type of asset (i.e., only Texts or only Conditions, and so on…), the descriptor for that asset type drives the UI definition/design. For example, when searching for Texts only (all other checkboxes deselected), the TextModule.fml drives how the interface looks like.

The FMLs are part of the CM Solution Template (@ CorrespondenceManagementSolutionTemplate\package-resources\apps\solutions\cm\assetDefinitions), and can be modified as required. Once modified, follow the steps to build and deploy the solution template for changes to take effect.

 

Understanding the Asset Definition descriptors (FMLs)

Now that we know the significance of these FMLs, let’s take a look at what’s in there…

The FML has a lot inside it, but we will only focus on what’s relevant towards the Manage Assets UI definition. Let’s take the TextModule.fml as an example here.

The first section of interest is the assetActions item, which defines what action buttons are available on the Application Toolbar when searching for Texts (only). Here’s how the section looks like for Texts:

 

 

 

 

Note the list of actions highlighted (within the grey boundary). Each <action> also defines the User Groups (names) who can perform that action (groupName=”…”),  whether the action is enabled by default or not (defaultEnabled=”…”), and other styling configurations such as the icons to be used in enabled or disabled states, tooltip and label (enabledIcon, disabledIcon, tooltip, label).

The next section of interest would be the various <property> tags. Here’s a snapshot of the name property for Texts:

 

 

 

The set of <property> tags define the properties/attributes that are part of that asset. Each <property> may define whether it is visible as a column in the Search Results Grid (note the visible attribute highlighted in RED), whether it is available as a searchable property in the Advanced Search panel (note the searchable attribute highlighted in GREEN), and other attributes such as the displayName, columnOrder, etc.

So, to add a column in the Manage Assets UI (in the Search Results Grid), you would need to add an additional <property> node for that property (if it does not exist already). Properties could either be one of the existing ones for the asset or a custom property added for that asset.

Overall, to configure the properties to be shown in the Search Results Grid and the Advanced Search panel, you may tweak existing properties and/or add/remove properties to the concerned FML.

 

This was a very generic description of such configurations. You may check out my post which adds a Tags column to the Manage Assets UI for all assets, as an example. You should also check out the public documentation which adds custom properties to assets and displays them on the Manage Assets interface.

Adding a new Tab to the Manage Assets interface

The Manage Assets user interface presents three main tabs for users to work with:

  • Assets :  This is the tab where the Correspondence Management assets are listed, can be searched for (based on basic/advanced search criteria), or acted upon using the various actions available in the toolbar.
  • Editors : This is the tab where the editor for an asset is presented (opens up), when opened for Edit or View or Copy or other such actions using the asset toolbar.
  • Admin : This tab is meant for users with administrator-like roles, wherein they can author the administrative assets, i.e. Data Dictionaries and Categories. The tab also allows users to export all assets in the system as an archive (ZIP), that can then be imported onto another system; thus allowing asset transport across systems.

While the above is available out-of-the-box, one can easily extend/customize the Manage Assets interface to introduce a new tab (alongside the above three tabs) that may be required to display a custom user interface (what’s displayed within the tab would be customer specific, based on the exact use case). We will see how…

Before you start with any customization(s) on the solution, ensure that you have correctly setup your development environment.

Once you have your development environment setup in your FlashBuilder, you will see a project ManageAssets in it. As the name suggests, this is the main flex project for the Manage Assets UI, and hence any client (flex) side customization to this user interface, would involve working with this project.

To start with, locate the file AMApplicationSkin.mxml. You will find it under src\com\adobe\solutions\cmg\manage\skins\AMApplicationSkin.mxml. This is the Skin file for the Manage Assets interface, where you will find the declaration for the above three tabs, as shown below:

 

 

 

 

 

We will add our new tab (named “My New Tab“) before the Assets tab by adding an additional Spark NavigatorContent (s:NavigatorContent) as shown below:

 

 

 

 

 

Note that for now we have specified the label for the tab (… label=”My New Tab” …) within the skin itself, for simplicity. This should ideally be externalized to the resource bundle, just as the other tabs’ labels are.

That’s it! Once done with the above change in the skin, re-build and deploy the solution, after which, when you open the Manage Assets UI (@ http://server:port/cm/manageassets.html), you will see this:

 

 

(our new tab indicated in RED)

Of course, our new tab does not have anything to show inside it and appears as an empty canvas at this time, because we haven’t added any view within it yet. However, that should be easy, as you now need to add standard Flex components within our additional NavigatorContent, depending upon what view you wish to show up within this tab. Additional code may be needed to implement the overall business use case, the extent of which would depend upon the complexity of the same.

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