Archive for September, 2011

Adobe Digital Enterprise Platform in 10 minutes!

For those of you who are new to the Adobe Digital Enterprise Platform (ADEP), the short (but concise) 10 minute video below is a MUST watch, for an introduction to the platform.

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

Customizing ADEP Solutions – simplified!

Here are some critical aspects that contribute greatly towards the ease of customization of Adobe’s Customer Experience Management (CEM) Solutions.

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!

 

Find your OSGi-ready enterprise (thirdparty) libraries

Ok, this is  going to be a short one…

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

 

 

Designing a Correspondence Draft workflow

Saving correspondences as a draft (i.e., an in-progress correspondence), and the ability to reopen the same at a later point in time, seems to be a common use case in Correspondence Management.

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.

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.

Postprocessing your correspondence

Correspondences created in enterprises would typically have to be integrated to a back-end process for further distribution (via email, fax, print), document processing (apply digital signatures, encryption, etc.) or archival of the correspondence.

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.

 

Better search using asset tagging

Tagging has always been one of the classic approaches towards categorization of assets/objects, that allows a convenient way to ‘search’ for objects based on the associated tags, at a later point in time.

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.

Transporting assets across systems/environments in CM 3.0

Correspondence Management Solution 3.0 provides this great ability to transport, via an intuitive user interface, not just the entire set of assets across environments, but also selective assets. This is one of the uber cool enhancements from how the same is achieved in the previous version of the solution, where this was somewhat limited and cumbersome.

Right from the Manage Assets user interface itself, you can now select any asset or set of (possibly related) assets, that you wish to take over or move to another environment (or physical server), and export them as a ZIP. This ZIP can then be imported over to the desired target system, and voila!…you’ll have your assets in place. Indeed! it is as simple as this.

Please take a moment to read through the published documentation to guide you through the step by step process.

Adobe Correspondence Management Solution 3.0 – Top 10 items to look out for!

If you have not already got a chance to explore the various uber cool features of the all new Correspondence Management Solution 3.0, here are my top 10 ones that you should look out for…

1. With the all new Create Correspondence (aka Document Composer) UI, composing Letters was never so easy! . The new interface provides an easy, intuitive way of composing Letters. With a lot more controls available, such as indentation adjustments, new line, free text, one can design/create a Letter exactly as required.

2. Highlighting of the currently selected asset in the PDF Preview when composing a Letter. Wouldn’t it be a great composing experience if selecting an asset on the flex app. automatically takes you to the respective page, exactly where your content lies within the PDF!? …and then highlight the selected content as well as the target in which the content lies, so you don’t have to search/scroll-over for your content within the PDF. The solution now brings along this amazingly convenient experience for the users.


3. Working on multiple assets at a time. With the all new Manage Assets interface, one can now work on multiple assets (possibly, related to each other) at a time, by virtue of each asset/editor being opened in a new tab in the Editors view. Of course, you can also switch between tabs when working with multiple assets. Here’s a snapshot:

4. Content Preview is yet another amazing addition to the asset authoring experience, wherein you can hover over your asset (in all views that present a list of assets) and see a Preview of the asset content and metadata, be it Texts, Images, Lists, Conditions, etc. So, you no longer need to go back and open the asset editor to see what’s in it. Use the Preview experience to identify the desired asset!

5. Creating numbered and bulleted list content. You can now easily design numbered and bulleted content, by authoring List assets using the List Editor. You can control indentation on paragraph(s) (or even images), specify custom prefix/suffix characters, and much more…

6. The all new Rich Text Editor, that has great text formatting capabilities that includes styling such as Bold/Italic/Underline, Font controls, letter Spacing, line height, Margin controls, Alignment controls. The editor also allows creating advanced bulleted and numbered content, using the appropriate toolbar controls.

Spell Check (English) is another great feature that enhances the text authoring experience.

7. Ability to Publish assets and enhanced version management, with the ability to create different versions of an asset, view previous versions, revert back to last published version, etc. See this post for more on publishing assets.

8. Import/ Export of selective assets is now possible using CM 3.0 via the Manage Assets interface itself. One can select the assets to be exported and simply press the “Export Assets” button. The exported ZIP can then be imported on any other system, using the “Import Assets” action on the Manage Assets interface.
Import/Export of all assets is also now possible right from the Manage Assets (Admin) interface itself, with a single click of a button (rather than the cumbersome steps in Contentspace, as in ES 2.5).

9. CM 3.0 introduces the ability to author Tables (dynamic or static) within your correspondence.

Here’s the Fund Allocation table in the Welcome Kit letter (that is part of the CM sample assets).

10. The Asset Dependencies Browser is an excellent tool/interface to view the dependencies of an asset, and be able to generate a report out of the same.

Note : Users can further drill down into the related assets by double-clicking on the asset, which will then show the dependencies for that asset. One can switch back-n-forth using the breadcrumbs on the top bar.

These are just 10 key features that you just cannot afford to miss. There is a lot more to the solution, the details of which can be seen on this post.

Solutions and the Application Context

Solutions over ADEP have introduced the concept of an application context (aka app context), which can be seen as a unique identifier, that various server side modules use to identify the execution context (from the current execution thread) and process requests in context of that solution. For instance, when persisting content/assets onto the CRX repository, the platform’s persistence module (official known as Platform Content) uses the current (invoking) app context to determine where to store the content/assets, and what configurations to use (which would typically be different for different solutions). See snapshot below, indicating the solution specific content areas.

Note that the storage location is /content/apps/cm for Correspondence Management, and /content/apps/icr for Integrated Content Review, which happen to be the app contexts for the two solutions.

Since it is essential for the server to identify the execution context, if you do not set or establish the application context before you make calls to the solution APIs, you will encounter a server error that says :  “Unable to fetch application context“. To set the app context, use one of the two methods:

App context in your Flex application

If you are invoking a solution API from a flex application, ensure that you set the app context using:


var appToken:AsyncToken = com.adobe.ep.ux.content.services.search.lccontent.LCCQueryServiceFactory.getInstance().setAppContextService("/content/apps/cm"); // setting app context for the CM solution
appToken.addResponder(new mx.rpc.Responder(<your success handler>, <your fault handler>));

App context in your Java application

If you are invoking a solution API from a java based application, ensure that you set the app context using:

com.adobe.livecycle.content.appcontext.AppContextManager.setCurrentAppContext("/content/apps/cm"); // setting app context for the CM solution

 

The app context concept is also used (or rather leveraged) in other scenarios such as driving solution specific Building Block (BB) configurations. Since a Building Block is meant to be reusable across solutions, it exposes certain configurations that can be different for different solutions. Hence, the BB needs to behave differently depending upon the context in which it is being used or invoked. Below is an example where the Data Dictionary BB is used by two solutions – CM and ICR – and has configurations specific to each solution, lying within the solution’s specific app context - /apps/cm for CM and /apps/icr for ICR.