Lists

Lists are a great way to group content, i.e. Texts, Images, nested Lists and Conditions (read on, if you are new to Conditions) together into logical groups. For instance, when you wish to mandate the inclusion of a Text paragraph A with Text paragraph B, you could create List, and include Texts A and B within the List, marking them as mandatory content.

Apart from this, you could also set advanced Styles on Lists, so as to specify if and how the content should be bulleted or numbered, set indentation on individual content, and much more. You could also specify advanced rules for the List to control whether the List can accept more content than what is originally assigned to it (during correspondence creation), or whether content within it can be re-ordered, and so on.

Visit the official document to see how to work with Lists using the List Editor.

Conditions

Conditions are a great way to specify inclusion rules of content within a correspondence. One could define expressions on control variables (placeholders and/or Data Dictionary elements), such that appropriate content may be selected into the correspondence,  based on runtime values of these variables. Content may be Texts, Images, Lists or Conditions (thereby allowing deeply nested conditions).

Conditions are defined similar to SWITCH-CASE statements. Each expression has a result content associated with it. The first expression that evaluates to TRUE is chosen as the result and the content associated with it is included in the final correspondence.

Note that you can choose to return multiple content against an expression by wrapping (grouping) them within a List and then select the List as the result of that expression.

Visit the official document to see how to work with Conditions using the Condition Editor.

As you can see, Lists can be included within other Lists or Conditions and vice-versa. Thus allowing users to create complex rules for their templates, optionally combined with styles.

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.

The container obviously brings along the great capabilities of OSGi as a dynamic component model, where components (and services) can be remotely installed, started, stopped, updated and uninstalled without requiring a reboot. However, one of the other very cool aspect of the container is the ability to Stop and/or Restart  the entire OSGi framework remotely, to help resolve/refresh the installed bundles, their bundle contexts and dependencies, etc.

To do so, you just need to go to the Felix Web Console @ the URL – http://server:port/system/console. Go to the System Information tab, where you will something like this:

Note the Restart and Stop options indicated in green.

The System Information tab is also useful to gather other system related information such as the JVM details, memory consumption (with the ability to perform a forced Garbage Collection), etc.

Watch out for the ADEP Developers Channel on YouTube for more…

No EAR deployments and Application server overheads!

The fact that the CEM solutions sit over the OSGi framework (the Apache Felix OSGi container), has completely changed the way they are built and deployed. As compared to the conventional application server model, where one would typically deploy an EAR file, restart the server and wait for an awful long time for the complete server startup, the OSGi model and the new platform brings in the capability to deploy artifacts (bundles and packages) at runtime, without having to bounce the entire server (which anyway is much, much faster). If at all, there may be cases where you would have to restart the OSGi bundles, but that’s a piece of cake given that you have a sophisticated console to do this from, within a few seconds.

Simplified UI changes – Great separation of concerns!

The UI components of all CEM solutions are based on what is known as the Experience Oriented (XOA) architecture. These UI components are popularly known as UX Components, which by definition is a combination of MXML and ActionScript classes that is bundled into SWC files that separate concerns and encapsulate each concern behind an interface. Interfaces make the implementation of concerns (i.e. presentation, domain, etc.) replaceable and extensible. The Presentation layer of each component, further has the separation of a HostComponent and the Skin, such that one can change the UI look-and-feel (for example, re-ordering of UI elements) by simply modifying the Skin of that component, without having to worry about the overall presentation logic (which lies in the HostComponent). Similarly, the component’s Styles are externalized into CSS files, such that one can change the themes, colors, fonts, etc. by simply changing these CSS files. This allows changes to the solutions while still retaining supportability. Apart from these, other enhanced customizations may involve changes to the HostComponents or the Domain layer, as per the desired use case.

Apart from these, the overall development model around customizations on the UI layer, takes-away the overhead of making changes in various different projects. One can now just add the necessary customized artifacts (MXML, Actionscript, CSS, etc.) to the Solution Template projects itself and override the default implementations via CSS definitions and/or standard inheritance. To learn more, refer to this sample scenario from the Correspondence Management solution.

CRX as the Content repository – Ease of debugging!

The solution assets are now stored in CRX, which provides an Apache Jackrabbit based content repository. The nice and intuitive Content Explorer allows an easy way to navigate across the repository to search for your assets (that are clearly visible as nodes, by their names). Users can select an asset or one of its child nodes to see/investigate the properties associated with the asset. One can also download asset content by selecting an asset and clicking on the data property of that asset (for example, for a Layout asset in CM, it is the filexdp property on the layout node). This greatly helps in debugging/troubleshooting assets within the system.

Apart from this, there is also the CRXDE Lite interface that enables you to perform standard development tasks from the browser.

Check out the links to some of these common interfaces in ADEP,  that you would need frequently during development.

OSGi Services – Possibility of isolated server-side customizations!

Since services deployed in the container are classic OSGi services, one can choose to build/deploy his/her own service as a separate OSGi bundle. Thus, allowing clear separation of custom services vs. the out-of-the-box ones.

Great overall Development Platform!

The Adobe Digital Enterprise Platform (ADEP) offers great tools to support development with ADEP Experience Services. The tools include a set of additional extensions for Flash Builder and a rich SDK (Flex, Java, Mobile) for building applications. The Experience Services SDK is an Experience Package distributed and downloadable using Adobe Package Share.

Overall, since the solutions are built on top of the Adobe Digital Enterprise Platform, they leverage these great capabilities of the platform itself, such that one can build custom applications around it that solves one or more end-to-end use cases.

Comprehensive Help Content!

The solutions publish comprehensive documentation around the usage of the solution, steps to customize areas within the solution, sample customization scenarios, etc. – all of which are a great set of resources to learn about the solution and provide helpful starting points/references for customizations. These learning resources keep evolving as more features are added to the solution, and more scenarios are identified. So, keep an eye on them!

While building custom OSGi bundles or components over the Adobe Digital Enterprise Platform (which contains the Apache Felix OSGi container) or any other OSGi container for that matter, you may often come across a need to access and hence introduce OSGi bundles of other enterprise thirdparty libraries within the container.

A common way to achieve this is to create a wrapper bundle for these libraries using the BND  tool. However, thanks to SpringSource, we already have the OSGi-ready versions of hundreds of open source enterprise libraries that are commonly used/needed, hosted for public use.  So, you can easily search for the library you are looking for here, before creating one on your own (in case the one you are looking for does not exist – which should be quite rare).

While it is known that the Adobe CM solution can be easily extended to save correspondence drafts by following some very simple steps, I would like to enlighten as to how one could extend beyond that to design an end-to-end workflow around it.

Summary

In a nutshell, this post talks about the steps you could follow to Save your correspondence drafts (in the CRX repository), load the (list of) saved drafts on the Manage Assets interface and then (usually at a later point in time) choose a particular draft to be re-opened in the Create Correspondence interface.

The same workflow can have multiple iterations, depending upon the number of steps taken to author the final correspondence.

Details

Here are the steps that you could follow to design such a correspondence draft workflow :

The steps below involve code changes (both Flex and Java), so please ensure that you have setup your development environment correctly, before proceeding.

Step 1 : Save correspondence drafts from Create Correspondence

Your first step would be to enable Save As Draft functionality on the Create Correspondence UI. After these changes, you will have a new SaveAsDraft button on your Create Correspondence UI, that can be clicked to invoke the postprocess (an ADEP process) designed and configured for that button.

If you are new to designing postprocesses for the solution, it is highly recommended that you read more on designing postprocesses.

We will now look into what needs to be done in the process…

Step 2 : Postprocess definition to save drafts

In the ADEP process that you design for Step 1, save the XML data (given to the postprocess) onto a given location in the CRX repository as a node (of type XML), with the Letter template name as a property on that node. You may add other details (properties) to the node such as the username who saved the correspondence , timestamp when the draft was saved, comments captured from the user when saving the draft, etc.

Your saved draft nodes may look like this (assuming you save them under /content/CMDrafts) :

Step 3: Custom OSGi Service to fetch drafts

Now that you have a process that saves your correspondences in the CRX repository as nodes, you need the ability to fetch those from CRX (so that they can be enlisted).

Use/customize the CM Solution Template’s Services (Java) project to define an OSGi service that can fetch the XML data nodes (and their details/properties) from CRX. The first couple of steps in this post indicate how to write an OSGi service and expose it over Flex and Spring remoting (note that you do not need the other steps, since the Services project is already configured to do that for you).

Your service would return a List of a custom value object, say DraftVO, which contains the XML data URL string (URL to node in the CRX repository, which would be something like crx:///content/CMDrafts/SampleLetterDraft1.xml) and the other properties attached to the draft’s node (created in Step 2).

Additionally, your service could filter the list of drafts based on the logged in user, so that a user only sees the drafts saved by him/her. Of course, you need to ensure that Step 2 persists the username within the node properties (to filter the appropriate nodes).

Step 4: List Drafts on the Manage Assets

Now that you have a service which can return you a list of drafts saved in the system, you can customize the Manage Assets UI to enlist these drafts.

To do so, you can start by adding a new tab, say “Drafts“, alongside the existing tabs on the Manage Assets interface. When you launch the Manage Assets UI after these changes, it should look something like this:

The Drafts tab can be designed such that it contains a DataGrid which will enlist the saved drafts within the grid, by invoking the service, that we defined in Step 3, as the data provider. The columns to be shown in the grid would depend on what properties you have saved (in Step 2) for a given draft item.

The below snapshot is a sample that shows two columns for the drafts list – the Letter template used for the draft, and the time when the draft was saved (assuming that the user is only seeing drafts loaded by him/her).

Step 5: Reload selected draft

Before you proceed, if you are not already aware of reloading correspondences in CM, please ensure that you read through how to reload a correspondence in CM.

So, now that you have fetched the list of drafts on the UI, you would add a toolbar above your data grid, that has a button Reload (see snapshot above). The button should have a click handler, such that when you select a draft item, and click Reload, it launches the CCR UI with the URL http://server:port/cm/createcorrespondence.html?cmDataUrl=<the data URL for the selected Draft item>. The data URL would be available to you for each item through the DraftVO that your service returns in Step 3.

That’s it, you now have an end-to-end workflow for saving and reloading correspondence drafts!

Note that this is just an example that shows the solution’s extension and core capabilities to design such a workflow. You may tweak this to have more steps within it, design a more sophisticated UI, or extend this further depending upon the actual requirements.

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

The Adobe Correspondence Management solution provides a convenient way to achieve this by leveraging orchestrations/processes on the ADEP Document Services platform for defining the back-end process (that can use one or more Document Services, based on the enterprise requirements), and providing the ability to easily bind them to a given correspondence template.

Read more about creating a postprocess for the CM solution on the Document Server.

Once such processes are created on the Document Server, can then be mapped to a Letter template in the  Postprocess drop down of the Letter Template Editor (as shown below), where the available postprocesses (as defined on the Document Server) are listed:

Tip: If you create a new process, with an existing Manage Assets UI session opened, your process will not be listed in the Postprocesses dropdown until you relaunch or refresh (F5) the Manage Assets browser window (or open the Manage Assets UI in a new browser window).

When the correspondence creation is complete (using the Create Correspondence UI), users can Submit the correspondence (see snapshot below indicating the Submit button), which invokes the associated/mapped postprocess for that Letter template, with the final correspondence PDF and XML data (used to generate the PDF). The postprocess, which would be an orchestration, can then act upon the document (PDF) as necessary.

While the Correspondence Management Solution provides advanced search capabilities, wherein one can search over asset properties such as name, description, content, etc., users (customers) may want to associate custom tag(s) with an asset so that assets can then be more easily (and even, logically) searched using these tags.

Now, the obvious question…how to achieve this??

Here goes the answer…

As part of the various extensions points, the solution provides the capability to add custom attributes/properties to an asset, which can then be searched upon (and used in any other asset management workflows). We can leverage this aspect and add a custom property, say ‘tag’, to the desired asset types, which will be used to associate tags with any asset created of that type.

For details and samples around adding a custom attribute/property to an asset type, refer to the ADEP documentation.

Below are the key changes done (snippets) to enable tagging on Letter templates. The same can be applied on other asset types (Texts, Images, etc.) as well.

1. Here’s the addition to the Letter.fml that drives the Manage Assets UI look when searching for Letter Templates:

[Note: Letter.fml can be found in the Services project of the Solution Template]

<property name="tags" type="string">
<annotation name="DDS">
<item name="displayName">Tags</item>
     <item name="visible">true</item>
     <item name="searchable">true</item>
     <item name="columnOrder">11</item>
     <item name="searchRendererOrder">11</item>    
     <item name="searchPath">Letter.extendedProperties.tags</item>
     <item name="assetPropertyType">extended</item>
     <item name="extendedPropertyPath">Letter.extendedProperties.tags</item>
</annotation>
</property>

… which basically is adding a property named ‘tags‘ to the Manage Assets UI, such that it can appear in the Advanced Search, and as a column in the Letters view data grid. Note the entries in purple.

2. The new/extended Host Component for the Letter Editor that extends the out-of-the-box Host Component to add UI logic specific to our new attribute ‘tags’:

3. A new Skin would be created for the Letter Editor that adds a Text Input to the Properties Editor where users can supply values for the applicable tags on a template:

…which basically, would lead to the Letter Editor showing up like this:
[note the additional text box for entering tags]

Users can now add comma-separated (you are free to use a different separator) tags when creating their Letter templates. Once added, these tags can be used to search for templates on the basis of these tags. See the below snapshot, where a search for templates with the tag ‘noida‘, lists the Letter template that was created with that tag.

As mentioned before, the above snippets just give you an idea of the capability and the necessary changes to get the desired results. There are other (though minor) changes needed as part of this customization, which are similar to the way custom attributes are added to an asset type in general. So, please refer to that documentation for comprehensive steps and details.

Also, you could implement more complex logic within your customized solution to further enhance tagging on assets.