Archive for February, 2011

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