xpression 3 xframework Developer s Guide

Transcription

1 xpression 3 xframework Developer s Guide

2 by EMC. All rights reserved. The copyright protection claimed includes all formats of copyrightable material and information governed by current or future statutory or judicial law. This includes, without limitations, any material generated by the software programs that display icons or other screen interfaces. You may not copy or transmit any part of this document in electronic or printed format without the express written permission of. xpression, CompuSet, and all other Document Sciences Corporation products mentioned in this publication are trademarks of. For complete copyright information, please see the file xpression Licensing Document.pdf located on your ebook Library CD. EMC, 5958 Priestly Drive, Carlsbad, CA

3 Table of Contents Table of Contents Introduction... 8 Boxes and Revision Bars... 8 Solution Support... 9 About xframework xpression Server Components The xpression Assembly Engine The xpression Publishers Engine Distribution Controller Engine xpression Batch Engine xframework Components Fastpath to xresponse and xrevise WebServices API Java API EAI Adapter xpression Web Services xpression Java API xpression Integration Strategies Real-Time Interaction Near-Time Interaction Batch Interaction xpression Integration Decision Tree xpression Web Services Before You Begin Initial Questions Adding Your Application Definition Configuring Your Application with xpression Admin... 24

4 4 Table of Contents Authentication and Access Control Logging Licensing Using WebServices with xpresso Packages Web Services Processing Diagram The Document Requester Web Service Requesting a Document by Customer Key Requesting a Document by XML Customer Data Request Document by Output Profile The Document Composer Web Service The Compose Document Method The xpression Request Web Service The Publish Document Method The Preview HTML Method The Preview PDF Method The View Categories for User Method The View Documents in Category Method The View Output Profiles for Document Method The getbdt Method The getassembleddocument Method The publishmsohtmldocument Method The Publish And Return Document Method xresponse Web Service The Assign Document to User Method The Retrieve Work In Progress IDs Assigned to a User Method The Reassign Work Item Method The Revise Request Web Service The Assign Document To User Method The Retrieve Work In Progress IDs Assigned to a User Method The Reassign Work Item Method The queryworkitemstatus Method The completeitem Method The querydocstatus Method The previewworkiteminpdf Method The xpressforms Web Service for Reporting getreport getreportforfields Errors... 50

5 5 Table of Contents The xpression Java API Writing an XPression Facade Java Class Objectives Dependencies Creating a Simple Properties File Connecting to xpression Retrieving Categories Retrieving Document Names Retrieving a Document Writing a Quote Generator Application Objectives Dependencies Initial Setup Creating Standard Header and Footer Pages Presenting a List of Categories Presenting a List of Documents Presenting Input Fields Generating a PDF Quote Summary Deploying an xpression Application J2EE Application Assembly J2EE Web Application Overview J2EE Enterprise JavaBeans Overview J2EE Utility Classes Overview Web Application Archive Construction Command Reference Method Name The XPressionFacade Class getappname getbusinessdocuments getcategories getdocumentpackedmsohtml getdocumentpackedmsohtml (overloaded) getdocumentpdf getdocumentpdf (overloaded) gethavestartsession getoutputprofiles getschema getstartsession initserverconnection setstatus publishdocument... 90

6 6 Table of Contents publishdocument (overloaded) removesession() The XPressionDocument Class getdocumentdata getdocumentformat getdocumentname xpression Facade Exceptions XPressionFrameworkException NoAuthorizedRightException NoStartSessionException NoSuchTargetException XPressionEJBException XPressionProcessException The xpression EAI Adapter xadapter Architectural Overview Listener Technology Request Processor xpression Batch Wrapper Transformation Engine xadapter Deployment Architecture xadapter Components Web Services Integration JMS-Based Messaging Mechanism XML Message Error Handling Transformation Engine XML File Export for Batch Execution Adapter Configuration Information Creating the Adapter Application Adding Your Application Definition Configuring Your Application with xpression Admin Associating Attribute Sets with Your Application Assigning Categories to Your Application Assigning Data Sources to Your Application Setting Up Access Rights for Your Application Configure Your Batch Scripts Verifying Your Installation JMS

7 7 Table of Contents XML Files Publish Document Preview with PDF Post for Batch Error Messages Error Descriptions Event Descriptions Appendix A. The Webtool Utility Registering Webtool.dll The Encryption Utility encrypt decrypt The Pack Utility pack unpack Appendix B. Document Type Definitions The AppList DTD The Complete AppList.dtd A Complete AppList.xml Example The xpression Design DTD The Complete xdesign.dtd A Complete xdesign Example The Business Document Template DTD The Complete BDT.dtd A Complete BDT Example Appendix C. The AppList DTD The Complete AppList.dtd The AppList and Application Elements The WorkFlow Element The AccessRights Element The RequiredAttributes and Attr Elements A Complete AppList.xml Example

8 Chapter 1 Introduction 1 Welcome to xpression Framework. This book is geared towards an intermediate or higher level programmer. With xpression Framework, you can write applications using the xpression Web services. Web services enable you develop an integrated xpression solution quickly and easily. Boxes and Revision Bars The following colored boxes alert you to special information in the documentation. The Caution box: Caution: The caution boc warns you that a fatal error, unsatisfactory output, or loss of data may occur if you do not follow the directions carefully. The Tip box: Tip: A tip offers suggestions to simplify a task or describes a useful shortcut. They may also describe an alternate way to use the techniques described in the text. The Note box: Note: A note offers information that emphasizes or supplements important points of the main text. Revision bars help you locate new or changed information. Look for these revision bars in the right margin of each affected page.

9 9 Chapter 1 - Introduction Solution Support For more information or to solve a problem, contact Document Sciences Solution Support: Telephone: (760) Fax: (760) World Wide Web: support@docscience.com

10 Chapter 2 About xframework 2 Welcome to xframework. xframework covers all of the information an intermediate or high-level developer will need when using the xpression Web services, the high-level xpression Java API, or the xpression EAI Adapter. xpression is a suite of applications that provide universal content processing for your enterprise. The system was designed with an open, component-based architecture based on standards like J2EE, Web Services, JMS, MS.NET, and XML. Figure 1. xpression architecture

11 11 Chapter 2 - About xframework xpression integrates with enterprise information systems, data, and distribution channels. The xprs Server utilizes industry leading J2EE application servers and the standards-based architecture they leverage. This provides for: Extensible component based design Worldwide compatibility with Unicode Enterprise scalability with J2EE Integration flexibility with databases, XML, Web Services, HTTP and APIs Multi-channel distribution (print, web, , archive) xpression Framework exposes xprs Server capabilities to systems utilizing Java or Microsoft technologies. xpression Server Components The xpression Server is the core of the xpression suite. It consists of the components required for assembling, formatting, and distributing personalized documents. These components are written in Java and are hosted on your application server. The use of Java in both the xpression components and the application server allows xpression to deliver a multiplatform compatible application that runs on several different operating systems, including: Windows, UNIX, and Linux systems. For a full list of supported operating systems and servers, see your installation documentation. Figure 2. xprs Server Engine Simplified Data Flow.

12 12 Chapter 2 - About xframework The xprs server engines are: The xpression assembly engine The xpression publishers engine The xpression controllers xpression Batch The xpression Assembly Engine The xpression assembly engine assembles a document by combining a BDT (Business Document Template), customer data, and content. The BDT is the result of the Generate XML function in xdesign. Output of a document assembly is a set of assembled content appropriate for your composition engine of choice. The xpression Publishers Engine The xpression publishers engine is a wrapper for the two Document Sciences Composition Engines: CompuSet and xpublish. The publishers engine looks at the composition engine setting in the BDT/ASL and forwards the document publication request to the appropriate composition engine. The publishers engine outputs PDL (Page Description Language) documents according to your xadmin settings. The CompuSet Publishing Engine CompuSet is a complex, highly configurable tagging language that extends the formatting capabilities of Microsoft Word. It enables advanced output processing functionality such as sorting, grouping, and recipient processing,

13 13 Chapter 2 - About xframework provides for the addition of barcodes, and supports PCL and Metacode output. However, CompuSet does require extensive configuration. Figure 3. CompuSet Engine Simplified Data Flow. Components: CompuSet Composer - Composes CompuSet Tagged Text commands and content into pages Output Processing Pre-Processor - Prepares composed pages for output processing actions. For example, adds index records so Output Processing Engine can efficiently sort output Packages into CCF (Container for CompuSet Intermediate Format) file Output Processing Engine - Applies various output processing directives (sorting, merging, bar codes, ) to CCF and streams content to the Emitter Emitter - Transforms CompuSet Intermediate Format record stream to a particular PDL

14 14 Chapter 2 - About xframework The xpublish Engine The xpublish is an easy to use composition engine that performs many of the formatting functions available from Microsoft Word. It enables you to create dynamic charts based on your customer data, and to import printer PDL files to access print device functions. xpublish also performs output processing functions such as sorting and recipient processing, and supports PCL output. Metacode output is not supported. xpublish provides almost effortless configuration. Figure 4. xpublish Engine simplified data flow. Components: Instantiater - Assembly Engine which feeds the Composer Styled Documents Composer - Transforms Styled Documents into composed pages of content in DIF (Device Independent Format) streams Streamer - Applies necessary output processing logic to a DIF stream and sends to Emitter Local or Remote Emitter The emitter generates a PDL by transforming a DIF stream to a specified PDL format and invoking the Controller to send the desired document to the distribution channel.

15 15 Chapter 2 - About xframework Distribution Controller Engine The distribution controller engine processes requests from the composition engines and distributes personalized documents to print, archive, and distribution channels. Execution Architecture The distribution controller engine runs as a background thread in each xprs Server node. It wakes up every 30 seconds (a configurable option) and looks for work to do in xpression Database distribution tables. When there is work to do, it sends s, archive packages, and executes print scripts according to distribution definitions configured in xadmin. Distribution Types The distribution controller engine supports both online and offline distribution. In online distribution, the distribution controller s background process relays published documents directly to the target distribution channel, which can be (via SMTP), Print (via print script), or Documentum Archive (via DFC APIs). In offline distribution, the distribution controller writes documents and indexes (information about the documents published) to the file system. Supports very high volumes and specialized archival systems: FileNet Capture FileNet HPII DocFinity IBM Content Manager OnDemand xpression Batch Engine The xpression batch engine process large volumes of personalized documents, taking advantage of all xpression output management features. The batch engine requires xprs Server installation files and connectivity to xprs

16 16 Chapter 2 - About xframework Server EJBs. It may be invoked via command shell batch file, Java class main method call, or the xdashboard user interface. Figure 5. Batch engine execution architecture. The batch engine returns standard batch architecture error codes (zero for successful run, non-zero for warnings or failure). xpression batch jobs can be called and monitored by enterprise-class job management software. Several xbatch functions execute in parallel and can be tuned for optimal job execution. xframework Components xframework is the Application Programming Interface (API) for xpression. It enables you to build a custom interface to xpression assembly and distribution related services. The xframework components are: fastpath, the Web services API, the JAVA API, and the EAI Adapter. Fastpath to xresponse and xrevise Fastpath enables you to integrate xpression web applications with client web applications. WebServices API xpression ships two Web services: a document requester and a document composer. The document requester enables you to retrieve an assembled document from the content repository, and the document composer enables you to distribute a document stored in the content repository.

17 17 Chapter 2 - About xframework In order to utilize a Web Service, you must obtain a description of the Web Service interface via the WSDL. The Web services API is a platform independent API callable by Java code and.net Visual Studio. Java API The Java API is available for Java client code only. In order to use the xpression Java API, you must precisely match the Java client program you write with the xpression Server you will connect to by copying the Java Archive (JAR) files. xpression supports near-time messaging through the JMS standard. EAI Adapter Used for enhanced integration scenarios, for example, JMS and file loading. xpression Web Services Web services enable you develop an integrated xpression solution quickly and easily. Web services are a recent technology that enable you to run programs on remote computers over the Web. However, unlike traditional distributed applications, Web services can be invoked across different hardware and software platforms. Practically speaking, this means a Web service written in Java and stored on a UNIX computer can be invoked from a Windows application written in Visual Basic, Visual C++, or C#. For more information about the xpression Web Services, see xpression Web Services. The technology that makes invoking remote components possible is called Simple Object Access Protocol (SOAP). The client application constructs a SOAP message in XML format that includes the name of the service, the method the client is invoking, and all required parameters. It then sends the message over the Web to the remote computer. The remote computer processes the request and sends back a SOAP response, indicating whether the call completed successfully and including attachments, if necessary. xpression Java API The xpression Java API chapter helps you write xpression applications using the xpression high-level Java API. The purpose of this chapter is to provide you with complete documentation for developing and implementing an xpression application solution. This chapter includes sample Java code, implementation and deployment instructions, and a complete command reference.

18 18 Chapter 2 - About xframework xpression Integration Strategies There are three main xpression integration strategies: Real-Time (Request/Reply), Near-Time, and Batch. Figure 6. This diagram shows how xframework integrates with the xprs server. Real-Time Interaction Real-Time interaction is done with APIs and Portals. It is the least efficient method, but it is required when you want to serve immediate needs of end users waiting on documents to be published. Real-Time Interaction - APIs xframework offers two APIs for real-time integration. All APIs are request/reply in nature. High Level Java API - Only applicable if calling application technology is Java-based. For more information, see The xpression Java API. Web Services API - Can be used by either Java or non-java calling applications. xpression Web Services.

19 19 Chapter 2 - About xframework Real-Time Interaction - Portals xresponse and xrevise support a FastPath method of integrating these products into your web-based portals. FastPath is an HTTP Post to a xresponse or xrevise JSP page. There are a variety of HTTP parameters available to customize the behavior of xresponse or xrevise. For example: Bypass user name/password login Customer data to compose a new document Initial screen to display in the browser Work In Progress document to work with For more information, see the xresponse and xrevise fastpath chapters. Near-Time Interaction Near-time interaction is accomplished through JMS. It guarantees more efficient messaging because processing concurrency can be restricted to the maximum amount the hardware can support. Messages in excess of processing concurrency are queued and processed when resources become available. The xpression EAI Adapter supports the JMS (Java Message Service) specification. Vendor products like IBM WebSphere MQ support JMS for guaranteed delivery of messages between systems. The EAI Adapter provides Message-Driven EJBs (MDBs) to process 3 types of messages: Publish Document Preview PDF Post For Batch MDBs are configured to pull messages off an input queue, process messages, and put results on an output queue. Multiple MDBs can work in parallel on the same input queue if supported by the Application Server vendor. Batch Interaction Batch is the most efficient method for producing high volumes of documents. This strategy requires large batches of data to be accumulated for bulk processing before you start the interaction. The xpression EAI Adapter can watch for XML files and accumulate them for submission to a larger batch job. These XML files can be directly placed in a watched file directory or relayed via web services or JMS messages. At intervals defined by a batch job scheduler, the EAI Adapter gathers XML files for processing a particular batch job and optionally transforms them to xpression streamlined XML. The XML files are merged into one large XML file and submitted to xbatch for high throughput processing.

20 20 Chapter 2 - About xframework xpression Integration Decision Tree The xpression decision tree helps you decide which type of integration is best for your needs.

21 Chapter 3 xpression Web Services 3 Web services are a recent technology that enable you to run programs on remote computers over the Web. However, unlike traditional distributed applications, Web services can be invoked across different hardware and software platforms. Practically speaking, this means a Web service written in Java and stored on a UNIX computer can be invoked from a Windows application written in Visual Basic, Visual C++, or C#. The technology that makes invoking remote components possible is called Simple Object Access Protocol (SOAP). The client application constructs a SOAP message in XML format that includes the name of the service, the method the client is invoking, and all required parameters. It then sends the message over the Web to the remote computer. The remote computer processes the request and sends back a SOAP response, indicating whether the call completed successfully and including attachments, if necessary. Before You Begin Before you can develop and deploy custom xpression applications, you must first configure your environment. You do this by adding your application definition to AppList.xml and configuring it using xpression Admin. Additionally, you must ensure your environment is configured to work withh Axis version 1.3. In this section, we ll show you how to get everything set up. Caution: We strongly urge you not to make changes to AppList.xml on a production xpression server until you re sure your application works as intended in a test environment. Initial Questions There are several options involved in setting up applications in xpression, so you should answer the following questions while planning your application: What type of application are you developing? Is it a design tool or a production application? Will your application support workflow (approval)? If so, do you know what actions your application will have?

22 22 Chapter 3 - xpression Web Services What access rights will your application require? Are they hierarchical? Will your application have any required attributes? Will you use your applicaton to populate the xrevise Work in Progress page with content items? If so, you must set STATUS of the content items to APPROVED. Adding Your Application Definition To add the application definition to AppList.xml: 1. Locate AppList.xml on your xpression server. You should find it in C:\xPression. 2. Open the file in a text editor. 3. Type the application element between the <AppList></AppList> tags. Your application name must not contain apostrophes ( ). For example: <AppList> <Application name= xpression Custom Application > </Application> </AppList> 4. If your application supports workflow, type the workflow element. For example: <AppList> <Application name= xpression Custom Application > <WorkFlow fromstatus="submitted" tostatus="approved" enteraction="write" promoteaction="approve" /> </Application> </AppList> 5. Type the access rights your application supports, including whether or not they re hierarchical. For example: <AccessRights heirarchical="yes"> <Access name="read" /> <Access name="write" /> <Access name="approve" /> </AccessRights> 6. Type the required attributes, if any.

23 23 Chapter 3 - xpression Web Services For example: <RequiredAttributes> <Attr name="textclass_id" type="integer" min="0" max="0" ValidValueExist="0" Default_Value="" ismappable="0" stringlength="0" RangeExist="0" DefaultExist="0" multisingle="single" validvalue=""/> <Attr name="product_id" type="integer" min="0" max="0" ValidValueExist="0" Default_Value="" ismappable="0" stringlength="0" RangeExist="0" DefaultExist="0" multisingle="single" validvalue=""/> </RequiredAttributes> <RequiredAttributes condition="supportapproval"> <Attr name="status" type="string" min="0" max="0" ValidValueExist="1" Default_Value="PENDING" ismappable="0" stringlength="255" RangeExist="0" DefaultExist="0" multisingle="multi" validvalue="pending;submitted;approved"/> <Attr name="effective_date" type="datetime" min="0" max="0" ValidValueExist="0" Default_Value="" ismappable="1" stringlength="0" RangeExist="0" DefaultExist="0" multisingle="multi" validvalue=""/> <Attr name="withdraw_date" type="datetime" min="0" max="0" ValidValueExist="0" Default_Value="" ismappable="1" stringlength="0" RangeExist="0" DefaultExist="0" multisingle="multi" validvalue=""/> </RequiredAttributes> 7. Type the closing </Application> element at the bottom of your application definition. 8. Save AppList.xml and exit your text editor. Once complete, your application definition should appear similar to the following: <Application name="xpression Custom Application"> <WorkFlow fromstatus="submitted" tostatus="approved" enteraction="write" promoteaction="approve" /> <AccessRights heirarchical="yes"> <Access name="read" /> <Access name="write" /> <Access name="approve" /> </AccessRights> </Application> This sample application definition has workflow and access rights, but no required attributes.

24 24 Chapter 3 - xpression Web Services Configuring Your Application with xpression Admin Now that you ve added your application definition to AppList.xml, it s time to configure it with xpression Admin. To configure your application in xadmin, complete the following steps: 1. Associating Attribute Sets with Your Application 2. Assigning Data Sources to Your Application 3. Setting Up Access Rights for Your Application 4. Configuring Workflow for Your Application (optional) Associating Attribute Sets with Your Application Before you can configure categories, data sources, access rights, and workflow for your application, you must first associate one or more attribute sets with your application. To associate attributes with your application: 1. Start xadmin. 2. Click Category Management, then Attribute Sets. 3. Click an attribute set that you want to associate with your application. When you click the attribute set name, the Attribute Set page appears. Alternatively, you can also create a new attribute set. For more information about creating attribute sets, see the xadmin Enterprise Edition User Guide. 4. Select your application from the list and click Save. 5. To assign more categories to your application, repeat steps 1-4. Assigning Data Sources to Your Application To assign data sources to your application: 1. Select a category you ve already assigned to your application. 2. Click the Data Sources tab. 3. Select a data source group from the list and click Set Application. 4. Select your application from the drop-down list. 5. A page appears that enables you to associate your available data sources with your application. Select the data sources you want to assign to your application and click Add. 6. In the Default Data Source list, select a default data source for your application and click Save. 7. To assign additional data sources to your application, repeat steps 2-7.

25 25 Chapter 3 - xpression Web Services Setting Up Access Rights for Your Application To set up access rights for your application: 1. Click the Access Rights tab for a category you ve assigned to your application. 2. Click view/change for your application, then click Add. 3. Select users from the list of available users and click Add. The users will appear in the Selected Users list. 4. Click Save. The selected users for the category now have access to your application. 5. When the list of users reappears, select the access levels for each user and click Save. 6. To add additional users, repeat steps 1 through 5. Configuring Workflow for Your Application If your application supports workflow, you can configure your application to assign users as submitters and approvers. Please consult the xadmin Enterprise Edition User Guide to assist you in setting up workflow for your application. Authentication and Access Control When a user invokes either the document requester or document composer Web services, xpression authenticates the user on the server and checks the user s access to the document. Both Web services use the existing xpression security mechanism to perform authentication and access control. Let s take a closer look at what authentication and access control mean in xpression. Authentication The network user name and password are passed to the Web service, which in turn calls the authenticate method of the DSCSecuritySL object. If the method returns a string array containing the user name and groups, the user is authenticated on the server. However, if an empty string array is returned, the user is not authorized to retrieve documents from the xpression server. Access Control After the user is authenticated on the server, xpression determines if the user has at least READ access to the category where the requested document resides. If the user does not have access to the document, an error is returned to the user. Logging The document requester and document composer Web services use the existing xpression logging system. All xpression activity is stored in log files on the xpression server.

26 26 Chapter 3 - xpression Web Services Licensing The xpression Web services use the existing xpression licensing system. Licensing is handled on the xpression server from which the user is requesting documents. If you re an existing xpression customer, you ll need a separate license to enable Web services on your server. If you re a new xpression customer, you ll need to explicitly request the Web service feature when purchasing your xpression software. For more information, see the xadmin Enterprise Edition User Guide. Using WebServices with xpresso Packages The xpressionrequest web service is the only web service that suppports xpresso packages. The Document Requester, Revise Request, and xresponse web services cannot retrieve xpresso packages. Web Services Processing Diagram To understand how xpression processes Web service requests, the following functional diagram illustrates the flow of the document requester service. Figure 7. Document Requester Functional Flow

27 27 Chapter 3 - xpression Web Services 1. SOAP Request The document requester client generates a SOAP request and sends the request by means of an HTTP POST. The client request specifies the DocumentRequester service and the requestdocuments method. The request also includes parameters such as documentname. 2. Request Routed to Servlet The application server receives the incoming request and forwards it to the Apache rpcrouter servlet. 3. Servlet Looks Up DocumentRequester The rpcrouter looks up the DocumentRequester, instantiates a DocumentRequester object and invokes the requestdocuments method. 4. requestdocuments Calls EJBs The requestdocuments method calls the AssemblyEngine Enterprise Java Bean (EJB) and other Java Beans to assemble the requested document and return an array of streams. 5. Rpcrouter Returns SOAP Response The rpcrouter captures the results, packages them into a SOAP response, and returns the response to the client. The Document Requester Web Service The document requester Web service enables you to retrieve an assembled xpression document in the format you specify by passing an output profile name. If successful, the xpression server passes back an array containing the document (or stream) name, the output format name, and the assembled document stored in a byte array. The format of the returned byte array depends on the output profile you provide. Note: For the CompuSet engine, be aware that if you select HTML as the format you want returned, the document requester will pass back packed MSOHTML. The calling program must convert the returned byte array to a logical file. There are two methods you can invoke to retrieve a document using the document requester: requestdocuments and requestdocumentswithdata. The first method requires you to pass the customer key values. The second accepts an XML stream containing a customer record. We ll discuss both methods. Caution: This web service does not support xpresso packages. The wsdl description for DocumentRequester can be viewed at following location:

28 28 Chapter 3 - xpression Web Services Substitute the server name and server port number where web services is installed. The document requester contains the following two methods: Requesting a Document by Customer Key Requesting a Document by XML Customer Data Request Document by Output Profile Requesting a Document by Customer Key The requestdocuments method enables you to retrieve a document from the content repository by passing the customer data key values. Use this method only if the category your document is associated with has an RDB data source. This method returns an object that contains the stream name, format, and a byte array containing the returned document. It is up to the calling program to save the byte array as a file. Note: All input parameters are case sensitive. For example, if your output profile is PDF to File, but you pass PDF to file, the SOAP request will fail. Syntax OPStream[] = requestdocuments(documentname, customerkey, outputprofilename, username, password[], appname) Parameters documentname : String Specifies the name of the document you re retrieving from the content repository. customerkey : String An XML string containing the key values for a specific customer record. Customer key values are always stored in the primary table of the data source. The following samples show how the XML should be formatted: <Keys> <Key name="autopay_key">1</key> </Keys> -or- <Keys> <Key name="autopay_key">1</key> <Key name="language">english</key> </Keys>

29 29 Chapter 3 - xpression Web Services outputprofilename : String Specifies the name of the output profile you re using to retrieve a document. username : String A string specifying the user who has been granted access rights to the category and application in xpression Admin. password[] : Byte An encrypted byte array specifying the password for the user who has been granted access rights to the category and application in xpression Admin. Use the webtool.jar utility to convert a text password to an encrypted byte array. appname : String A string specifying the application name defined in AppList.xml. You must associate the application with a category accessed by the Web service. For example, if you defined "xpression WebService" in AppList.xml, be sure to associate it with the category that contains the document you're retrieving from the content repository. Requesting a Document by XML Customer Data The requestdocumentswithdata method enables you to retrieve a document from the content repository by passing an XML string containing a single customer record. When invoking this method, xpression overrides the primary data source with the supplied XML string. Use this method only if the category your document is associated with has an XML data source. This method returns an object that contains the stream name, format, and a byte array containing the returned document. It is up to the calling program to save the byte array as a file. Note: All input parameters are case sensitive. For example, if your output profile is PDF to File, but you pass PDF to file, the SOAP request will fail. Syntax OPStream[] = requestdocumentswithdata(documentname, customerkey, customerdata, datasourcename, outputprofilename, username, password, appname) Parameters documentname : String Specifies the name of the document you re retrieving from the content repository. customerkey : String An XML string containing the key values for a specific customer record. Customer key values are always stored in the primary table of the data source. The following samples show how the XML should be formatted: <Keys> <Key name="autopay_key">1</key> </Keys> -or-

30 30 Chapter 3 - xpression Web Services <Keys> <Key name="autopay_key">1</key> <Key name="language">english</key> </Keys> customerdata : String A string containing a customer record in XML format. The XML stream can contain a single record from the primary table and, optionally, additional related records from secondary tables in your data source. For example, if you were requesting the Withdrawal Notice Letter document, your XML stream would contain a single record from the primary table. <?xml version="1.0" encoding="utf-8"?> <CustomerData> <WITHDRAWAL> <KEY>1</KEY> <NAME>Sara Jones</NAME> <STREET_ADDRESS>6732 River Run</STREET_ADDRESS> <CITY_STATE_ZIP>University City, CA 22445</CITY_STATE_ZIP> <LETTER_DATE>August 5, 2002</LETTER_DATE> <POLICY_PURCHASED>Flexible Premium Variable Life Insurance Policy</ POLICY_PURCHASED> <SALES_LOAD>2.5%</SALES_LOAD> <STATE_PREMIUM_TAX>2.5%</STATE_PREMIUM_TAX> <POLICY_NUMBER> </POLICY_NUMBER> <LANGUAGE>English</LANGUAGE> <JURISDICTION>CA</JURISDICTION> <EFFDATE> </EFFDATE> </WITHDRAWAL> </CustomerData> The value of the key for the customerkey parameter must be the same value referenced in the customerdata parameter. For example, if the customerkey parameter has a value of 1 but the customerdata references a different value, the call to request DocumentsWithData will fail. datasourcename : String A string specifying an XML data source you associated with a category in xpression Admin. To invoke requestdocumentswithdata, you must provide an XML data source here. Otherwise, the method will return a SOAP Fault. outputprofilename : String Specifies the name of the output profile you re using to retrieve a document. username : String A string specifying the user who has been granted access rights to the category and application in xpression Admin.

31 31 Chapter 3 - xpression Web Services password : Byte[] An encrypted byte array specifying the password for the user who has been granted access rights to the category and application in xpression Admin. Use the webtool.jar utility to convert a text password to an encrypted byte array. appname : String A string specifying the application name defined in AppList.xml. You must associate the application with a category accessed by the Web service. For example, if you defined "xpression WebService" in AppList.xml, be sure to associate it with the category that contains the document you're retrieving from the content repository. Request Document by Output Profile This method publishes a document to an output profile given as input. If For all return to caller streams in the output profile the Stream Name, Stream format and Stream Output will be returned.. The return parameter will be null if no return to calling application output streams are found. This method is a new method to the Document Requester web service. It is a hybrid of the Document Requester requestdocumentswithdata method and the xpressionrequest publishandreturndocument Method. The methods used to return the datasource in xpressionrequest should be used similarly in this method. Also please note there is not a need for an encrypted password in this method. It is very important that the returned data includes not only the output but the stream name and format so the client can differentiate between the different streams and operate on them properly based on the format. Should the method fail, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. Syntax OPStream [] streamarray = requestdocumentsbyoutputprofile(documentname, username, password, outputprofile, customerdata, applicationname) Parameters documentname : String The name of the document to publish. username : String The user name that the method will use to validate that the user has permission to publish the document requested. If the user does not have permission to read the document according to its category and application name given as input, the request will be rejected. password : String The password that corresponds to the username, authenticated by xpression platform security. outputprofile : String The output profile the document will be published to.

32 32 Chapter 3 - xpression Web Services customerdata : String An XML document containing data required to assemble the document given as input. This data must match an XML data source defined in xadmin as the default data source for the document category and application name given as input. applicationname : String The xpression Application Name defined and configured in xadmin for the category the document belongs to. The Document Composer Web Service The document composer service enables you to distribute a previously assembled document, using any output profile defined in xpression Admin. You can use this service in tandem with the document requester by invoking either requestdocuments or requestdocumentswithdata to retrieve a document. Then you d pass the returned document to the document composer service. The wsdl description for the document Composer can be viewed at following location: Substitute the server name and server port number where web services is installed. The Compose Document Method The method returns a 0 if the service successfully processes the request. Otherwise, the method returns a SOAP Fault, indicating the reason for the failure. For more information, see Errors. Note: All input parameters are case sensitive. For example, if your output profile is PDF to File, but you pass PDF to file, the SOAP request will fail. Syntax returnval = Compose(msoHtmlDoc, documentname, outputprofilename, username, password) Parameters msohtmldoc: Byte[] A byte array containing an assembled document. documentname : String Specifies the name of the document you re distributing. outputprofilename : String Specifies the name of the output profile you re using to distribute the supplied document. For more information, see

33 33 Chapter 3 - xpression Web Services the xpression System Administrator s Guide. username : String A string specifying the user who has been granted access rights to the category and application in xpression Admin. password : Byte[] An encrypted byte array specifying the password for the user who has been granted access rights to the category and application in xpression Admin. Use the webtool.jar utility to convert a text password to an encrypted byte array. The xpression Request Web Service The xpression Request web service contains methods to conveniently access some of the most common xpression services. The wsdl description for xpressionrequest can be viewed at following location: Substitute the server name and server port number where web services is installed. xpression Request contains the following methods: The Publish Document Method The Preview PDF Method The View Categories for User Method The View Documents in Category Method The View Output Profiles for Document Method The getbdt Method The getassembleddocument Method The publishmsohtmldocument Method The Publish And Return Document Method The Publish Document Method The Publish Document web service method allows you to input an XML document as a customer data source override. The XML document must match the default data source group assigned to the document's category. The web service method will override the customer data source with the provided XML document and publish that document to the output profile specified. Return to calling application output streams will not be returned. The

34 34 Chapter 3 - xpression Web Services method returns a String as an output parameter if the method completes successfully. The output string will have the following format: Message <messageid> was successfully published to output profile <outputprofile> where <messageid> is the primary key of the primary table in the data source and <outputprofile> is the name of the output profile specified in the method. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For more information, see Errors. This method supports xdesign documents and all xpresso packages with one exception. If you are producing HTML output, xpresso for InDesign packages are not supported. Syntax publishdocument(documentname, UserName, Password, OutputProfile, CustomerData, AppName) Parameters documentname: String Specifies the name of the document you are retrieving from the content repository. username : String A string specifying the user who has been granted access rights to the category and application in xpression Admin. password : String A string specifying the password for the corresponding user name. outputprofile : String Specifies the name of the output profile you re using to distribute the supplied document. customerdata : String The xml phrase that contains the data defined by XML data source. appname : String Specifies the name of the xpression application.

35 35 Chapter 3 - xpression Web Services The Preview HTML Method The preview HTML service enables you to publish an xpresso for Dreamweaver package in HTML format and return the file back to the adapter as an HTML Return to Application stream. The method returns a published HTML document as a Byte array. The array is serialized with BASE64 encoding/decoding according to the SOAP standard. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For more information, see Errors. xdesign documents and other xpresso packages are not supported with this web service. Syntax previewhtml(documentname, UserName, Password, CustomerData, AppName) Parameters documentname: String Specifies the name of the document you are retrieving from the content repository. username : String A string specifying the user who has been granted access rights to the category and application in xpression Admin. password : String A string specifying the password for the corresponding user name. customerdata : String The xml phrase that contains the data defined by XML data source. appname : String Specifies the name of the xpression application. The Preview PDF Method The preview PDF service enables you to publish an xdesign document or xpresso for Adobe InDesign package in PDF format and return the file back to the adapter as a PDF Return to Application stream. The method returns a published PDF document as a Byte array. The array is serialized with BASE64 encoding/decoding according to the SOAP standard. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For more information, see Errors. xpresso for Dreamweaver packages are not supported with this web service. When Used with xpublish Documents When this method is called for an xpublish document, the Web Service uses the default PDF output definition. When Used with CompuSet Documents When this method is called for a CompuSet document, the web service determines if there is a format definition named PDF. If your system does contain a format definition named PDF, the web service creates a PDF based off the pdef file and the font files associated with that format definition. If a PDF format definition is not available, xpression creates a basic PDF format definition.

36 36 Chapter 3 - xpression Web Services If your system does not contain a format definition named PDF, you can create one that uses pdef and font files of your choice. If your system does not contain a format definition named PDF, you can modify the format definition to use the pdef and font files of your choice. Username and Password Filter Prior to xpression 3 build 30, it was possible to pass incorrect information for the username and password. Under certain circumstances, such as passing a data source for username, it was possible to cause the native code authentication software to abort and so shut down the server. To prevent this, username and password are now filtered as part of authentication and will not be passed if they do not meet these minimum standards: Maximum string length 256 characters No embedded EOL characters No leading or trailing blanks Syntax previewpdf(documentname, UserName, Password, CustomerData, AppName) Parameters documentname: String Specifies the name of the document you are retrieving from the content repository. username : String A string specifying the user who has been granted access rights to the category and application in xpression Admin. password : String A string specifying the password for the corresponding user name. customerdata : String The xml phrase that contains the data defined by XML data source. appname : String Specifies the name of the xpression application. The View Categories for User Method The view categories for user service returns a list of categories available to the defined user. The method can complete successfully without returning any category names. This indicates that the user has not been given access rights to any xpression categories. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For more information, see Errors.

37 37 Chapter 3 - xpression Web Services Syntax categoryforuser(username, Password, AppName) Parameters username : String A string specifying the user who has been granted access rights to the category and application in xpression Admin. password : String A string specifying the password for the corresponding user name. appname : String Specifies the name of the xpression application. The View Documents in Category Method The view documents in category service returns a list of all xdesign documents and xpresso packages contained in the defined category. This list is returned as a String array that contains one document name for every document that resides in the defined category. This method can complete successfully without returning any document names, indicating that the category is empty. If the method fails, it returns a SOAP Fault that indicates the reason for the failure. For more information, see Errors. Syntax documentsforcategory(username, Password, AppName) Parameters documentcategory : String A string specifying the name of the category whose contents you want to view. username : String A string specifying the user who has been granted access rights to the category and application in xpression Admin. password : String A string specifying the password for the corresponding user name. appname : String Specifies the name of the xpression application. The View Output Profiles for Document Method The view output profiles for document service returns a list of output profiles assigned to the document from xdesign. This list is returned as a String array that contains one output profile name for every output profile assigned to the defined document. This method can complete successfully without returning any output profiles, indicating that no output profiles are assigned to the document. If the method fails, it returns a SOAP Fault that

38 38 Chapter 3 - xpression Web Services indicates the reason for the failure. For more information, see Errors. This web service can only be used with xdesign documents. xpresso packages are not supported with this function. Syntax outputprofilesfordocument(documentname, UserName, Password, AppName) Parameters documentname : String A string specifying the name of the document whose output profiles you want to view. username : String A string specifying the user who has been granted access rights to the category and application in xpression Admin. password : String A string specifying the password for the corresponding user name. appname : String Specifies the name of the xpression application. The getbdt Method The getbdt web service returns a string that is an assembled list using the xdesign document name and customer data. The assembled list is the xdesign BDT that has already been updated with variables. This web service can only be used with xdesign documents. xpresso packages are not supported with this function. Syntax getbdt (documentname, customerdata, username, password, appname) Parameters documentname: String Specifies the name of the document you are retrieving from the content repository. customerdata: String The xml phrase that contains the data defined by XML data source. username : String A string specifying the user who has been granted access rights to the category and application in xpression Admin. password : String A string specifying the password for the corresponding user name. appname: String Specifies the name of the xpression application.

39 39 Chapter 3 - xpression Web Services The getassembleddocument Method The getassembleddocument web service returns a byte array that is an assembled xdesign document in MSOHTML format. This web service can only be used with xdesign documents. xpresso packages are not supported with this function. Syntax getassembleddocument (documentname, customerdata, username, password, appname) Parameters documentname: String Specifies the name of the document you are retrieving from the content repository. customerdata: String The xml phrase that contains the data defined by XML data source. username : String A string specifying the user who has been granted access rights to the category and application in xpression Admin. password : String A string specifying the password for the corresponding user name. appname: String Specifies the name of the xpression application. The publishmsohtmldocument Method The publishmsohtmldocument web service returns a string array that is an assembled xdesign document in MSOHTML format. If the distribution defintion is return to caller, the return value will include the output format. If the distribution definitions is not return to caller, the return value will be empty. This web service does not support xpresso packages. Syntax publishmsohtmldocument (documentname, customerdata, msohtml, outputprofilename, username, password, appname) Parameters documentname: String Specifies the name of the document you are retrieving from the content repository. customerdata: String The xml phrase that contains the data defined by XML data source.

40 40 Chapter 3 - xpression Web Services msohtml: byte[] A byte array containing an assembled document. outputprofilename: String Specifies the name of the output profile you re using to retrieve a document. username : String A string specifying the user who has been granted access rights to the category and application in xpression Admin. password : String A string specifying the password for the corresponding user name. appname: String Specifies the name of the xpression application. The Publish And Return Document Method This method publishes a document to an output profile given as input. If the output profile has a single return to calling application distribution definition defined in the output profile, that stream will be returned to the caller. The return parameter will be null if no return to calling application output streams are found. If more than one return to caller output stream is found, the method will return the first stream found (order not guaranteed) so you should be certain that if you expect a document to be returned of a particular format, you only call an output profile which has one and only one output stream returned. Should the method fail, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. Syntax byte[] publisheddocument = publishandreturndocument(documentname, username, password, outputprofile, customerdata, applicationname) Parameters documentname : String The name of the document to publish. username : String The user name that the method will use to validate that the user has permission to publish the document requested. If the user does not have permission to read the document according to its category and application name given as input, the request will be rejected. password : String The password that corresponds to the username, authenticated by xpression platform security.

41 41 Chapter 3 - xpression Web Services outputprofile : String The output profile the document will be published to. customerdata : String An XML document containing data required to assemble the document given as input. This data must match an XML data source defined in xadmin as the default data source for the document category and application name given as input. applicationname : String The xpression Application Name defined and configured in xadmin for the category the document belongs to. xresponse Web Service The xpression Response Web Service contains the following methods: The Assign Document to User Method The Retrieve Work In Progress IDs Assigned to a User Method The Reassign Work Item Method Caution: This web service does not support xpresso packages. The Assign Document to User Method This method creates a work in progress ID (WIP ID) for the document and assigns the WIP ID to the xpression Response user s Work in Progress queue. If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. The method returns the WIP ID as a string if the method completes successfully. Caution: If you use the Assign Document to User method you will not be able to use optional paragraphs. To use optional paragraphs, you must either use FastPath or direct response. The caller can call the "assigndocumenttouser" web service method with the following URL: assigndocumenttouser

42 42 Chapter 3 - xpression Web Services Syntax assigndocumenttouser(documentname, AdminUserName, AdminPassword, AssignToUserName, CustomerData) Parameters DocumentName : String The name of the xpression Document you want to assign. AdminUserName : String The username that the method will use to log in as the xpression Response work administrator. This user must have Write_Document permission for the category that contains the requested document. If the user does not have the correct permissions, the request will be rejected. AdminPassword : String The password that corresponds to the AdminUserName, authenticated by xpression platform security. AssignToUserName: String The user name to whom you are assigning the document. The document will be listed as a work in progress item when the user logs into xpression Response. CustomerData : String The assigndocumenttouser web service locates the primary data source defined for the category that contains the document you want to assign. The web service then locates the default data source for the primary data source definition. Both the primary data source and the default data source must be in XML format. The input for this parameter is the XML document for the default data source. This data source must be a valid XML document according to the xpression data source definition. The Retrieve Work In Progress IDs Assigned to a User Method This method returns a String array of WIP IDs assigned to the xpression Response user s work in progress queue. Note: This method does not authenticate the WIPUserName parameter. If you provide a bad user name as input, the method will simply return an empty string array of WIP IDs. If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. The caller can call the "wipidsforuser" web service method with the following URL: wipidsforuser Syntax wipidsforuser(adminusername, AdminPassword, WIPUserName)

43 43 Chapter 3 - xpression Web Services Parameters AdminUserName : String The username that the method will use to log in as the xpression Response work administrator. This user must have permission to approve documents in xpression Response. AdminPassword : String The password that corresponds to the AdminUserName, authenticated by xpression platform security. WIPUserName : String The user name for whom the method should look up WIP IDs. The Reassign Work Item Method If this method completes successfully, it returns the following String as an output parameter: Work item ID '<WorkItemID>' was successfully reassigned to the work in progress queue for user '<AssignToUserName>' where WorkItemID is the WIP ID of the work item you want to reassign, and AssignToUserName is the user name to whom you are assigning the work item. If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. The caller can call the "reassignworkitem" web service method with the following URL: reassignworkitem Syntax reassignworkitem(adminusername, AdminPassword, AssignToUserName, WIPID) Parameters AdminUserName : String The username that the method will use to log in as the xpression Response work administrator. This user must have Write_Document permission for the category that contains the requested document. If the user does not have the correct permissions, the request will be rejected. AdminPassword : String The password that corresponds to the AdminUserName, authenticated by xpression platform security. AssignToUserName : String The user name to whom you are assigning the document. The document will be listed as a work in progress item when the user logs into xpression Response.

44 44 Chapter 3 - xpression Web Services WIPID : String The WIP ID that you want to reassign. This work item will be reassigned to the AssignToUserName specified above. The Revise Request Web Service The Revise request web service contains the following methods: The Assign Document To User Method The Retrieve Work In Progress IDs Assigned to a User Method The Reassign Work Item Method The queryworkitemstatus Method The completeitem Method The querydocstatus Method Caution: This web service does not support xpresso packages. The Assign Document To User Method This method creates a work in progress ID (WIP ID) for the document and assigns the WIP ID to the xpression Revise user s Work in Progress queue. If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. The method returns the WIP ID as a string if the method completes successfully. The caller can call the "assigndocumenttouser" web service method with the following URL: assigndocumenttouser Syntax assigndocumenttouser(documentname, AdminUserName, AdminPassword, AssignToUserName, CustomerData) Parameters DocumentName : String The name of the xpression Document you want to assign. AdminUserName : String The username that the method will use to log in as the xpression Response work administrator. This user must have xpression Revise "Admin" privilege for the category that contains the requested document. If the user does not have the correct permissions, the request will be rejected.

45 45 Chapter 3 - xpression Web Services AdminPassword : String The password that corresponds to the AdminUserName, authenticated by xpression platform security. AssignToUserName : String The user name to whom you are assigning the document. The document will be listed as a work in progress item when the user logs into xpression Response Revise. CustomerData : String The assigndocumenttouser web service locates the primary data source defined for the category that contains the document you want to assign. The web service then locates the default data source for the primary data source definition. Both the primary data source and the default data source must be in XML format. The input for this parameter is the XML document for the default data source. This data source must be a valid XML document according to the xpression data source definition. The Retrieve Work In Progress IDs Assigned to a User Method This method returns a String array of WIP IDs assigned to the xpression Revise user s work in progress queue. Note: This method does not authenticate the WIPUserName parameter. If you provide a bad user name as input, the method will simply return an empty string array of WIP IDs. If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. The caller can call the "wipidsforuser" web service method with the following URL: wipidsforuser Syntax wipidsforuser(adminusername, AdminPassword, WIPUserName) Parameters AdminUserName : String The username that the method will use to log in as the xpression Revise work administrator. This user must have permission to approve documents in xpression Revise. AdminPassword : String The password that corresponds to the AdminUserName, authenticated by xpression platform security. WIPUserName : String The user name for whom the method should look up WIP IDs.

46 46 Chapter 3 - xpression Web Services The Reassign Work Item Method If this method completes successfully, it returns the following String as an output parameter: Work item ID '<WorkItemID>' was successfully reassigned to the work in progress queue for user '<AssignToUserName>' where WorkItemID is the WIP ID of the work item you want to reassign. and AssignToUserName is the user name to whom you are assigning the work item. If the method fails, it returns a Simple Object Access Protocol (SOAP) fault. The text of the SOAP fault contains a unique identifier error code and accompanying error message with details and data related to the error. The caller can call the "reassignworkitem" web service method with the following URL: reassignworkitem Syntax reassignworkitem(adminusername, AdminPassword, AssignToUserName, WorkItemID) Parameters AdminUserName : String The username that the method will use to log in as the xpression Response work administrator. This user must have the xpression Revise "Admin" priviliege for the category that contains the requested document. If the user does not have the correct permissions, the request will be rejected. AdminPassword: String The password that corresponds to the AdminUserName, authenticated by xpression platform security. AssignToUserName The user name to whom you are assigning the document. The document will be listed as a work in progress item when the user logs into xpression Revise. WorkItemID The WIP ID that you want to reassign. This work item will be reassigned to the AssignToUserName specified above. The queryworkitemstatus Method The output of this web service is "Pending", "Approved", or "Rejected" if work item is not completed. If the work item is completed, the output is "Completed". Syntax String queryworkitemstatus(string wipid, String username, String password)

47 47 Chapter 3 - xpression Web Services Parameters wipid : String The ID of the work item. username : String The current username. The user must have access to perform the required function. password : String The user s password. The completeitem Method The output of this web service is "Work item (name) has been completed." This web service moves work item to completed item's queue, and delete unused RU revisions. Syntax String completeitem(string wipid, String username, String password) Parameters wipid : String The ID of the work item. username : String The current username. The user must be the work item owner to use this web service. password : String The user s password. The querydocstatus Method The output of this web service is "PENDING" or "APPROVED" or NULL based on effectivedate.. Syntax String querydocstatus(string categoryname, String docname, String effectivedate, String username, String password) Parameters categoryname : String The document s category. docname : String The document s name.

48 48 Chapter 3 - xpression Web Services effictivedate : String This parameter must be a number in the format "YYYYMMDD". If effectivedate is a negative number, return the status of the latest BDT. username : String The name of the user. The user must have access to perform the required function. password : String The user s password. The previewworkiteminpdf Method This method overrides data when previewing a WIP work item. Syntax String previewworkiteminpdf(string wipid, String customerdata, String username, String password) Parameters wipid : String The work in progress work item ID. customerdata : String The data source must use the same schema as the primary data source. Note: If customerdata is set as null, this web service works just as previewing the work item as PDF. username : String The name of the user. The user must have at least read premission to perform the required function. password : String The user s password.

49 49 Chapter 3 - xpression Web Services The xpressforms Web Service for Reporting The xpressforms Web Service for reporting contains the following methods: getreport getreportforfields getreport This method returns a report on the specified documents. Syntax getreport( string docnames, string format ) Parameters docnames : String The name of the documents on which to create a report. You can specify more than one document name. The document names are separated by a comma and enclosed in quotes. format : String The format of the report. You can choose XML or CSV (comma delimited variable file) The following example shows the method creating an XML formatted report for three specific documents. getreport( document1, document2, document3, XML ) getreportforfields This method returns a report for certain fields (XML element names) in specified documents. The method will only return information about the specified fields in the specified document. You can specify more than one document name and more than one field. The document names are separated by a comma and enclosed in quotes. The field names are also separated by a comma and enclosed in quotes. Syntax getreportforfields( string docnames, string format, string fields ) Parameters docnames : String The name of the documents on which to create a report. You can specify more than one document name. The document names are separated by a comma and enclosed in quotes. format : String

50 50 Chapter 3 - xpression Web Services The format of the report. You can choose XML or CSV (comma delimited variable file) fields: String The XML element names that this report will include. This value is case sensitive. The following example shows the method creating an XML formatted report for three specific documents. getreport( document1, document2, document3, XML, Form, Description, Status, Object_Type ) Errors If an error occurs while either the document requester or document composer Web services are processing a request, the method returns a SOAP Fault to the client, indicating the reason for the error. The following is an example of a SOAP Fault: <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:xsi=" xmlns:xsd=" <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>9005</faultcode> <faultstring>document not found</faultstring> <faultactor>/soap/servlet/rpcrouter</faultactor> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope> To display the fault string to the user, you need to parse the XML response using an XML parser. XML parsers are widely available from a number of vendors, including Microsoft and Sun Microsystems. For COM or.net applications, the SOAP Toolkit provides methods for displaying fault codes and strings. The following table presents all the errors xpression Web services return. Fault Code Fault String 9000 An error occurred while executing the web service Access denied. The user name or password are incorrect User is not authorized to access the required document Output profile not found.

51 51 Chapter 3 - xpression Web Services Fault Code Fault String 9005 Document not found No Web service license available Invalid customer key Application not defined Customer data source not defined Data source not found Failed to get connection to the database.

52 Chapter 4 The xpression Java API 4 In this chapter, we ll show you how to write Java classesthat encapsulates the most common methods in the highlevel xpression Java API. We ll also show you how to create an application that generates instant auto and homeowners insurance quotes and discuss various approaches to packaging and deploying your J2EE xpression application. Writing an XPression Facade Java Class In this section, we ll show you how to connect to an xpression server, retrieve categories, retrieve documents associated with a specific category, and assemble and retrieve a PDF document stored in the content repository. The complete application we re going to create is an automatic insurance quote generator. In the next chapter, we ll show you how to create the thin client piece of the application that calls the Java class we re writing in this chapter. Objectives In this chapter, we ll cover the following: Dependencies Creating a Simple Properties File Connecting to xpression Retrieving Categories Retrieving Document Names Retrieving a Document

53 53 Chapter 4 - The xpression Java API Dependencies To complete the sample Java class in this chapter, you ll need to include the xpressionjavaapi.jar library in the classpath for your development environment. We re now ready to create our Java class and add several methods to it. Creating a Simple Properties File In your Quote Generator application, you ll need to have a readable and writable path where xpression will store PDF documents. To avoid hard coding a path in the Java class, let s create a simple properties file called XDK.properties in a text editor. Add the following line to the file: temppath=c:\\websphere\\appserver\\installedapps\\xpression.ear\\quote_gen.war\\xpressiondocs\\ In the above example, we re assuming you re using WebSphere and that it s installed on the C drive. Also, we re assuming you re deploying the application to the xpression.ear enterprise application. Both these assumptions may not reflect your actual environment. For example, you may use BEA WebLogic as your application server and you may deploy the Quote Generator application to a different enterprise application than xpression. Therefore, your temppath setting would be different from the above example. Keep in mind that the required section of the path is \\Quote_Gen.war\\xPressionDocs\\. Connecting to xpression Launch your Java development environment and create a new class called quote_gen.java. Add the following code to the top of the class: package quote_gen; import java.util.*; import java.io.*; import com.docscience.xpression.framework.xpressionfacade; public class quote_gen { private XPressionFacade facade = null; private String temppath = ""; private byte[] bdoc = null;

54 54 Chapter 4 - The xpression Java API You can change the package statement if you intend to nest your Java classes at a deeper directory level. Now add the connect method below the variable declarations: public void connect(string url, String context, String username, String password, String appname) { try { //init the xpression server facade = new XPressionFacade(); facade.initserverconnection(url, context); //start session facade.getstartsession(username, password, appname); //set the temp path for docs temppath = gettemppath(); catch (Exception e) { e.printstacktrace(); The initserverconnection method requires a URL that consists of a server name and port number. Be sure to supply a URL that s valid for your own environment. Look at the servers.xml file in your xpression home directory for valid entries. You ll also notice we re calling a method to retrieve the temppath from XDK.properties. Add the gettemppath method below the connect method: private String gettemppath() { String path = ""; try { InputStream fileinputstream = this.getclass().getclassloader().getresourceasstream("xdk.properties"); Properties xdkproperties = new Properties(); xdkproperties.load(fileinputstream); path = xdkproperties.getproperty("temppath"); catch (Exception e) { e.printstacktrace(); return path;

55 55 Chapter 4 - The xpression Java API Retrieving Categories We ll now add the method to retrieve all the category names stored in the content repository. Add the getcategories method: public String[] getcategories() { String[] returnvals = null; try { returnvals = facade.getcategories(); catch (Exception e) { e.printstacktrace(); return returnvals; Retrieving Document Names Let s now add the method to retrieve documents that "live" in a specific category. Add the getdocumentnames method: public String[] getdocumentnames(string categoryname) { String[] returnvals = null; try { returnvals = facade.getbusinessdocuments(categoryname); catch (Exception e) { e.printstacktrace(); return returnvals;

56 56 Chapter 4 - The xpression Java API Retrieving a Document Now we re going to write some code to retrieve a document in PDF format. Add the getdocument method: public String getdocument(string docname, String xmldata, String xmldatasource) { String filename = null; try { bdoc = facade.getdocumentpdf(docname, xmldata, xmldatasource); filename = savedoc(); catch (Exception e) { e.printstacktrace(); return filename; Notice that this method requires that we pass both the XML data source name and the XML data stream in order to assemble the document with the data you ll pass from your own application. Finally, we need to add the savedoc method: private String savedoc() { String returnvalue = null; File file = null; try { // create the file name String filename=string.valueof(system.currenttimemillis()); file=new File(tempPath+fileName+".pdf"); FileOutputStream out = new FileOutputStream(file); out.write(bdoc); out.close(); returnvalue=filename; catch (Exception e) { e.printstacktrace(); return returnvalue; In the savedoc method, we re saving the byte array returned by the getdocumentpdf method to a file on the server. That s all there is to the Java class. Compile and test it on your own if you want.

57 57 Chapter 4 - The xpression Java API Writing a Quote Generator Application In this section, we ll show you how to create an application that generates instant auto and homeowners insurance quotes. The application will consist of several JSP pages that call the quote_gen class we wrote in the last chapter. Specifically, the application will present the user a list of insurance types, either auto or homeowner. The user will select an insurance type, select a quote document, enter several values required to generate the quote, and receive an instant quote document in PDF format. Objectives In this chapter, we ll cover the following: Dependencies Initial Setup Creating Standard Header and Footer Pages Presenting a List of Categories Presenting a List of Documents Presenting Input Fields Generating a PDF Quote Summary Dependencies To complete the Quote Generator application, you ll need to include quote_gen.class in the classpath for your development environment. Additionally, the application uses two documents you ll need to import into the xpression content repository you re using for development, as well as sample data for each document. You ll find the PDP on the ebooks CD in \\xpression Framework\XDK\Documents\. You ll find the XML data files for each document in \\xpression Framework\XDK\Documents\ CustomerData.

58 58 Chapter 4 - The xpression Java API Initial Setup In this chapter, we re creating a Java Web application (WAR) that you can deploy on any computer with either WebSphere or WebLogic client. On your development machine create a folder structure that resembles Figure 8. Figure 8. The Quote_Gen.war folder structure. Be sure to copy the XDK.properties file you created in the last chapter to \Quote_Gen.war\WEB-INF\classes. Let s take a closer look at what goes in each folder. Folder name Quote_Gen.war Quote_Gen.war\css Quote_Gen.war\images Quote_Gen.war\META-INF Quote_Gen.war\WEB-INF Quote_Gen.war\WEB- INF\classes Quote_Gen.war\WEB- INF\classes\quote_gen Contents Contains all the JSP pages that comprise that Quote Generator application. Contains the css.css stylesheet we ll use for minor formatting of the JSP pages. You ll find the stylesheet on the ebooks CD in \\xpression Framework\XDK\source\css. Contains the image files we ll use for minor formatting of the JSP pages. You ll find the images on the ebooks CD in \\xpression Framework\XDK\source\images. Contains the MANIFEST.MF file that is generated when you create a WAR with a J2EE development tool like WebSphere Studio. For more information, see Deploying an xpression Application. Contains files describing your application. For more information, see Deploying an xpression Application. Contains the XDK.properties file we created in chapter 2. Contains the Java class file we created in chapter 2.

59 59 Chapter 4 - The xpression Java API Folder name Quote_Gen.war\WEB-INF\lib Quote_Gen.war\xPressionDocs Contents Contains all the Java libraries (JAR files) your application needs. For this application, we re only using xpressionjavaapi.jar. You ll find this file in your xrevise and xresponse EAR files. Contains the PDF documents your application generates when a user requests an instant quote. Creating Standard Header and Footer Pages To avoid creating the same headers and footers on each page in our application, we ll create a couple standard JSP pages we can include in all our main JSPs. Open your JSP editor and create three new JSP pages. Name them hdr.jsp, ftr.jsp, and preview_top.jsp. 1. Add the following code to hdr.jsp: <HTML> <HEAD> <TITLE>xPression Quote Generator</TITLE> <LINK rel="stylesheet" href="./css/css.css" type="text/css"> </HEAD> <BODY BGCOLOR="WHITE" TEXT="BLACK" TOPMARGIN="0" LEFTMARGIN="0" MARGINHEIGHT="0" MARGINWIDTH="0"> <TABLE width="100%" border="0" cellspacing="0" cellpadding="0"> <tr> <TD class="title1_13" align="center"><br>xpression Quote Generator</TD> </tr> <TR> <TD valign="bottom" align="center" width="90%"><img src="images/pixel-blue.gif" width="99%" height="1" vspace="4"></td> </TR> </TABLE> 2. Now add the code for preview_top.jsp: <%@ include file="hdr.jsp" %> <DIV align="center"> <FORM ACTION="index.jsp" METHOD="post" name="postform" target="_top"> <A HREF="index.jsp" TARGET="_top"><SPAN class="no_dec">[start Over]</SPAN></A> </FORM> </DIV> </BODY> </HTML>

60 60 Chapter 4 - The xpression Java API 3. Finally, add the code for ftr.jsp: <LINK rel="stylesheet" href="./css/css.css" type="text/css"> <TABLE width="100%" border="0" cellspacing="0" cellpadding="0"> <TR> <TD valign="bottom" align="center" width="90%"><img src="images/pixel-blue.gif" width="99%" height="1" vspace="4"></td> </TR> <TR> <TD colspan=2 align="right" class="c"> All rights reserved. </TD> </TR> </TABLE> </BODY> </HTML> Presenting a List of Categories We ll now create a JSP page that displays the policy types the user will choose from to generate a quote. In your JSP editor, create a new page called index.jsp. Add the following code to index.jsp: <jsp:usebean class="quote_gen.quote_gen" id="quote_gen" scope="session"/> <%@ include file="hdr.jsp" %> <% //replace with appropriate values depending on environment String url = "iiop://localhost:9081"; String context = "com.ibm.websphere.naming.wsninitialcontextfactory"; String username = "xpression"; //for security purposes, use an encrypted password that you //decrypt here String password = "xpression"; String appname = "xpression Response"; //connect to xpression quote_gen.connect(url,context,username,password,appname); %> //get categories String categories[] = quote_gen.getcategories(); <FORM name="postform" method="post" action="getdocuments.jsp"> <TABLE align="center" border="0" cellspacing="0" cellpadding="0"> <TR><TD class="copy"> </TD></TR>

61 61 Chapter 4 - The xpression Java API <TR> <TD class="table_copy"> <SPAN class="subtitle">select a policy type:</span><br> <SELECT size="1" name="categoryname"> <% for (int i=0;i<categories.length;i++) { %> <OPTION value="<%=categories[i]%>"><%=categories[i]%></option> <% %> </SELECT><P> <input type="submit" NAME="getDoc" value="next >>" /> </TD> </tr> </TABLE> </FORM> <%@ include file="ftr.jsp" %> Let s take a look at the code is doing: We re including a reference to our Java class at the top of the page. We re adding an include statement to insert the code in hdr.jsp into index.jsp. In the script block, we re initializing the variables we need to start the xpression session. Observe that we re making certain assumptions about the xpression environment. You ll need to modify these variables in your own environment. For example, the context factory value will be different if you re using BEA WebLogic as your application server. We re also getting a list of categories the current user has access to. Note: Do you want to test the Quote Generator application? We suggest you grant read access to a "test" user for the two categories you created when you imported the quote documents. In the bottom block of HTML code, we re populating an option list with all the category names retrieved from the getcategories method.

62 62 Chapter 4 - The xpression Java API The resulting page should look like this when launched in your browser. Figure 9. The index.jsp page. Presenting a List of Documents On the index.jsp page, we indicated that the form action launched a page called getdocuments.jsp. Let s now create that new page. Add the following code to the getdocuments page: <jsp:usebean class="quote_gen.quote_gen" id="quote_gen" scope="session"/> <%@ include file="hdr.jsp" %> <% String categoryname = request.getparameter("categoryname"); String docs[] = quote_gen.getdocumentnames(categoryname); session.setattribute("categoryname",categoryname); %> <FORM name="postform" method="post" action="getinputs.jsp"> <TABLE align="center" border="0" cellspacing="0" cellpadding="0"> <TR><TD class="copy"> </TD></TR> <TR> <TD class="table_copy"> <SPAN class="subtitle">select a quote:</span><br> <SELECT size="1" name="docname"> <% for (int i=0;i<docs.length;i++) { %> <OPTION value="<%=docs[i]%>"><%=docs[i]%></option> <% %> </SELECT><P> <input type="submit" NAME="getInputs" value="next >>" /> </TD> </tr> </TABLE> </FORM> <%@ include file="ftr.jsp" %>

63 63 Chapter 4 - The xpression Java API This page should look similar to index.jsp, with a few differences: We re retrieving the category name from the form field on the index.jsp page. We re retrieving all the associated document names for the selected category by calling the getdocumentnames method in the quote_gen Java class. We re setting a session variable for the category. In subsequent pages, we ll need to know which category the user has selected. Finally, we re populating a drop-down list with all the document names returned by the getdocumentnames method. The resulting page should look like this when launched in your browser. Figure 10. The GetDocuments.jsp page. Presenting Input Fields If you imported PolicyQuotePDP.zip, you ll see that the two new documents each have their own data sources. Therefore, our quote application will present different input fields based on the category the user selects. Let s now add the code for getinputs.jsp: <%@ include file="hdr.jsp" %> <% String categoryname = session.getattribute("categoryname").tostring(); String docname = request.getparameter("docname"); session.setattribute("docname",docname); %> <FORM name="postform" method="post" action="getquote.jsp"> <TABLE align="center" border="0" cellspacing="0" cellpadding="0"> <TR><TD> <SPAN class="subtitle">please provide values in the following fields:</span><br / ><BR /><BR />

64 64 Chapter 4 - The xpression Java API <% if (categoryname.equals("auto")) { %> <SPAN class="subtitle">first Name:</SPAN><BR /> <INPUT name="f_name" size="50" value=""> <P> <SPAN class="subtitle">middle Initial:</SPAN><BR /> <INPUT name="m_init" size="50" value=""> <P> <SPAN class="subtitle">last Name:</SPAN><BR /> <INPUT name="l_name" size="50" value=""> <P> <SPAN class="subtitle">address:</span><br /> <INPUT name="prop_addr_1" size="50" value=""> <P> <SPAN class="subtitle">city:</span><br /> <INPUT name="prop_city" size="50" value=""> <P> <SPAN class="subtitle">state:</span><br /> <INPUT name="prop_state" size="50" value=""> <P> <SPAN class="subtitle">zip:</span><br /> <INPUT name="prop_zip" size="50" value=""> <P> <SPAN class="subtitle">make:</span><br /> <INPUT name="make" size="50" value=""> <P> <SPAN class="subtitle">model:</span><br /> <INPUT name="model" size="50" value=""> <P> <SPAN class="subtitle">model Year:</SPAN><BR /> <INPUT name="year" size="50" value=""> <P> <SPAN class="subtitle">deductible:</span><br /> <INPUT name="deductible" size="50" value=""> <P> <SPAN class="subtitle">auto Coverage Limit:</SPAN><BR /> <INPUT name="auto_cvg_limit" size="50" value=""> <P> <SPAN class="subtitle">personal Property Coverage Limit:</SPAN><BR /> <INPUT name="pers_prop_cvg_limit" size="50" value=""> <P> <SPAN class="subtitle">loss of Use Limit:</SPAN><BR /> <INPUT name="loss_use_cvg_limit" size="50" value=""> <P> <SPAN class="subtitle">liability Protection (each occurrence):</span><br /> <INPUT name="liab_prot_limit" size="50" value=""> <P> <SPAN class="subtitle">medical Payments to Others (each person):</span><br /> <INPUT name="med_pay_limit" size="50" value=""> <P> <% else {%> <SPAN class="subtitle">first Name:</SPAN><BR /> <INPUT name="f_name" size="50" value=""> <P> <SPAN class="subtitle">middle Initial:</SPAN><BR /> <INPUT name="m_init" size="50" value=""> <P> <SPAN class="subtitle">last Name:</SPAN><BR /> <INPUT name="l_name" size="50" value=""> <P> <SPAN class="subtitle">address:</span><br /> <INPUT name="prop_addr_1" size="50" value=""> <P> <SPAN class="subtitle">city:</span><br />

65 65 Chapter 4 - The xpression Java API <INPUT name="prop_city" size="50" value=""> <P> <SPAN class="subtitle">state:</span><br /> <INPUT name="prop_state" size="50" value=""> <P> <SPAN class="subtitle">zip:</span><br /> <INPUT name="prop_zip" size="50" value=""> <P> <SPAN class="subtitle">deductible:</span><br /> <INPUT name="deductible" size="50" value=""> <P> <SPAN class="subtitle">dwelling Coverage Limit:</SPAN><BR /> <INPUT name="dwel_cvg_limit" size="50" value=""> <P> <SPAN class="subtitle">other Structures Coverage Limit:</SPAN><BR /> <INPUT name="oth_str_cvg_limit" size="50" value=""> <P> <SPAN class="subtitle">personal Property Coverage Limit:</SPAN><BR /> <INPUT name="pers_prop_cvg_limit" size="50" value=""> <P> <SPAN class="subtitle">loss of Use Limit:</SPAN><BR /> <INPUT name="loss_use_cvg_limit" size="50" value=""> <P> <SPAN class="subtitle">liability Protection (each occurrence):</span><br /> <INPUT name="liab_prot_limit" size="50" value=""> <P> <SPAN class="subtitle">medical Payments to Others (each person):</span><br /> <INPUT name="med_pay_limit" size="50" value=""> <P> <%%> <input type="submit" NAME="getQuote" value="get Instant Quote" /> </TD> </tr> </TABLE> </FORM> <%@ include file="ftr.jsp" %> This page is lengthy, but simple: We re retrieving the category name from a session variable. We re retrieving the document name from the previous page. We re storing the document name in a session variable for later use. Finally, we re adding input fields to the page based on the category the user selected.

66 66 Chapter 4 - The xpression Java API The resulting page should look like this when launched in your browser. Figure 11. The GetInputs.jsp page. This graphic only shows a sampling of the user input fields displayed on getinputs.jsp. Generating a PDF Quote After the user has entered values for all the input fields and clicks the Get Instant Quote button, the getquote.jsp page is executed. Let s now add the code for getquote.jsp: <jsp:usebean class="quote_gen.quote_gen" id="quote_gen" scope="session"/> <%! public static String markup(string text) { if (text == null) { return null; StringBuffer buffer = new StringBuffer(); for (int i = 0; i < text.length(); i++) { char c = text.charat(i); switch (c) { case '<': buffer.append("<"); break; case '&': buffer.append("&"); break; case '>': buffer.append(">"); break; case '"':

67 67 Chapter 4 - The xpression Java API buffer.append("""); break; default: buffer.append(c); break; return buffer.tostring(); %> <% String filename=""; try{ // get session values String categoryname=session.getattribute("categoryname").tostring(); String docname = session.getattribute("docname").tostring(); //init vars String xmldatasource = ""; String xmldata = ""; String extension = ".pdf"; //this is an arbitrary number - obviously some calculation is necessary String annualpremium = " "; String fname = ""; String minit = ""; String lname = ""; String address = ""; String city = ""; String state = ""; String zip = ""; String clientnum = ""; String make = ""; String model = ""; String modelyear = ""; String deductible = ""; String liabprotlimit = ""; String medpaylimit = ""; String autocvglimit = ""; String perspropcvglimit = ""; String lossusecvglimit = ""; String dwelcvglimit = "";

68 68 Chapter 4 - The xpression Java API String othstrcvglimit = ""; //get form values and create XML string if (categoryname.equals("auto")) { xmldatasource = "AutoQuoteDS"; fname = request.getparameter("f_name"); minit = request.getparameter("m_init"); lname = request.getparameter("l_name"); address = request.getparameter("prop_addr_1"); city = request.getparameter("prop_city"); state = request.getparameter("prop_state"); zip = request.getparameter("prop_zip"); make = request.getparameter("make"); model = request.getparameter("model"); modelyear = request.getparameter("year"); deductible = request.getparameter("deductible"); liabprotlimit = request.getparameter("liab_prot_limit"); medpaylimit = request.getparameter("med_pay_limit"); autocvglimit = request.getparameter("auto_cvg_limit"); perspropcvglimit = request.getparameter("pers_prop_cvg_limit"); lossusecvglimit = request.getparameter("loss_use_cvg_limit"); //create XML string xmldata = "<dataroot><record><auto_client><client_no>" + zip + fname + "</ CLIENT_NO>"; xmldata += "<F_NAME>" + fname + "</F_NAME>"; xmldata += "<M_INIT>" + minit + "</M_INIT>"; xmldata += "<L_NAME>" + lname + "</L_NAME>"; xmldata += "<STATE>" + state + "</STATE>"; xmldata += "<ZIP>" + zip + "</ZIP></AUTO_CLIENT><AUTO_PROP>"; xmldata += "<CLIENT_NO>" + zip + fname + "</CLIENT_NO>"; xmldata += "<PROP_ADDR_1>" + address + "</PROP_ADDR_1>"; xmldata += "<PROP_CITY>" + city + "</PROP_CITY>"; xmldata += "<PROP_STATE>" + state + "</PROP_STATE>"; xmldata += "<PROP_ZIP>" + zip + "</PROP_ZIP>"; xmldata += "<MAKE>" + make + "</MAKE>"; xmldata += "<MODEL>" + model + "</MODEL>"; xmldata += "<YEAR>" + modelyear + "</YEAR>"; xmldata += "<DEDUCTIBLE>" + deductible + "</DEDUCTIBLE>"; xmldata += "<LIAB_PROT_LIMIT>" + liabprotlimit + "</LIAB_PROT_LIMIT>"; xmldata += "<MED_PAY_LIMIT>" + medpaylimit + "</MED_PAY_LIMIT>" xmldata += "<AUTO_CVG_LIMIT>" + autocvglimit + "</AUTO_CVG_LIMIT>"; xmldata += "<PERS_PROP_CVG_LIMIT>" + perspropcvglimit + "</ PERS_PROP_CVG_LIMIT>"; xmldata += "<LOSS_USE_CVG_LIMIT>" + lossusecvglimit + "</LOSS_USE_CVG_LIMIT>"; xmldata += "<IQ_TOT_PREM>" + annualpremium + "</IQ_TOT_PREM>";

69 69 Chapter 4 - The xpression Java API xmldata += "</AUTO_PROP></RECORD></dataroot>"; else { xmldatasource = "HomeownerQuoteDS"; fname = request.getparameter("f_name"); minit = request.getparameter("m_init"); lname = request.getparameter("l_name"); address = request.getparameter("prop_addr_1"); city = request.getparameter("prop_city"); state = request.getparameter("prop_state"); zip = request.getparameter("prop_zip"); deductible = request.getparameter("deductible"); liabprotlimit = request.getparameter("liab_prot_limit"); medpaylimit = request.getparameter("med_pay_limit"); dwelcvglimit = request.getparameter("dwel_cvg_limit"); perspropcvglimit = request.getparameter("pers_prop_cvg_limit"); lossusecvglimit = request.getparameter("loss_use_cvg_limit"); othstrcvglimit = request.getparameter("oth_str_cvg_limit"); //create XML string xmldata = "<dataroot><record><ho_client><client_no>" + zip + fname + "</ CLIENT_NO>"; xmldata += "<F_NAME>" + fname + "</F_NAME>"; xmldata += "<M_INIT>" + minit + "</M_INIT>"; xmldata += "<L_NAME>" + lname + "</L_NAME>"; xmldata += "<STATE>" + state + "</STATE>"; xmldata += "<ZIP>" + zip + "</ZIP></HO_CLIENT><HO_PROP>"; xmldata += "<CLIENT_NO>" + zip + fname + "</CLIENT_NO>"; xmldata += "<PROP_ADDR_1>" + address + "</PROP_ADDR_1>"; xmldata += "<PROP_CITY>" + city + "</PROP_CITY>"; xmldata += "<PROP_STATE>" + state + "</PROP_STATE>"; xmldata += "<PROP_ZIP>" + zip + "</PROP_ZIP>"; xmldata += "<DEDUCTIBLE>" + deductible + "</DEDUCTIBLE>"; xmldata += "<LIAB_PROT_LIMIT>" + liabprotlimit + "</LIAB_PROT_LIMIT>"; xmldata += "<MED_PAY_LIMIT>" + medpaylimit + "</MED_PAY_LIMIT>" xmldata += "<DWEL_CVG_LIMIT>" + dwelcvglimit + "</DWEL_CVG_LIMIT>"; xmldata += "<OTH_STR_CVG_LIMIT>" + othstrcvglimit + "</OTH_STR_CVG_LIMIT>"; xmldata += "<PERS_PROP_CVG_LIMIT>" + perspropcvglimit + "</ PERS_PROP_CVG_LIMIT>"; xmldata += "<LOSS_USE_CVG_LIMIT>" + lossusecvglimit + "</LOSS_USE_CVG_LIMIT>"; xmldata += "<IQ_TOT_PREM>" + annualpremium + "</IQ_TOT_PREM>"; xmldata += "</HO_PROP></RECORD></dataroot>";

70 70 Chapter 4 - The xpression Java API //replace reserved characters in XML data String xmldatamarkup = markup(xmldata); filename = quote_gen.getdocument(docname, xmldata, xmldatasource); //redirect to preview page if (filename!=null) { session.setattribute("filename",filename); //set path session.setattribute("filepath","./xpressiondocs/"+filename+extension); //go to preview page response.sendredirect("preview.jsp"); else { response.sendredirect("index.jsp"); catch(exception e){ e.printstacktrace(); %> Let s look at what the code is doing: We re creating a method to strip reserved HTML characters from a string of data and replace them with valid characters. We re retrieving the category and document names stored in session variables. We need the category name to determine how to assign values to the variables declared on this page. We ll pass the document name to the Java class method that returns a PDF document. Next, we re initializing several variables, including annualpremium. Here we re using a hard coded value. In your own applications, you d want to calculate the annual premium. We then check which category the user selected and assign values to the variables. Then we create an XML data string. This is the how xpression generates an instant quote using data the user has entered. While we re using a simple approach to generating XML, we strongly recommend you use a formal XML parsing engine to generate your data streams. Next we call the markup method and the getdocument method, passing the document name, the XML data, and the XML data source name. Finally, if the quote document is successfully created, we redirect the browser to the preview.jsp page.

71 71 Chapter 4 - The xpression Java API Let s now create the final page in the Quote Generator application: preview.jsp. Add the following code: <% String pagename = "Preview"; //get path String filepath=session.getattribute("filepath").tostring(); %> <html> <head> <title><%=pagename%></title> <meta http-equiv="content-type" content="text/html; charset=iso "> </head> <frameset rows="220,350*" frameborder="0" border="0" framespacing="0"> <frame name="topframe" scrolling="no" noresize src="preview_top.jsp"> <frameset rows="350,60" frameborder="0" border="0" framespacing="0"> <frame name="mainframe" scrolling="auto" src="<%=filepath%>"> <frame name="bottomframe" scrolling="no" src="ftr.jsp"> </frameset> <noframes> <body bgcolor="#ffffff"> </body> </noframes> </frameset> </html> You ll notice that the page only needs a bit of script to set the page name and the path for the PDF document. The remaining code creates three frames, which consist of: A header frame that includes a Start Over link to return the user to the main page in the application. A middle frame that displays the instant quote in PDF format. A footer frame that shows the HTML we ve used to format all the pages in the application.

72 72 Chapter 4 - The xpression Java API The resulting page should look like this when launched in your browser. Figure 12. The Preview.jsp page. Summary Now that we ve finished writing the code for our Quote Generator application, you ll want to deploy it on your client workstation or server. In the next chapter, we ll show you how to generate a WAR file for your application so you can deploy it either on a client workstation or a server. Deploying an xpression Application In this chapter, we ll discuss various approaches to packaging and deploying your J2EE xpression application. While we re suggesting you package the Quote Generator application in a WAR file, you might prefer packaging a pure Java application in a JAR file, or an enterprise application in an EAR file. This chapter discusses the following topics: J2EE Application Assembly J2EE Web Application Overview J2EE Enterprise JavaBeans Overview J2EE Utility Classes Overview

73 73 Chapter 4 - The xpression Java API Web Application Archive Construction J2EE Application Assembly Before we begin packaging the Quote Generator, let s discuss the various approaches to J2EE application assembly. There are three different types of J2EE applications: J2EE Web Applications J2EE Enterprise JavaBeans (EJBs) J2EE Utility Class Archives You can combine one or more of these applications into a single J2EE Enterprise Archive, as seen in Figure 13. We ll discuss each of the applications at a high level before we get into the details of assembling the Quote Generator application. Figure 13. J2EE Application Assembly J2EE Web Application Overview J2EE Web Applications are the easiest to understand and work with if you know how to construct Web-enabled applications. J2EE Web Applications contain HTML, GIF, JPEG, and other files appropriate for building Webenabled applications. Web browsers serve up these files through a Web server like Microsoft's Internet Information or Apache's Apache Web Server. J2EE application servers typically integrate with these external Web servers. They may also have their own Web server capabilities.

74 74 Chapter 4 - The xpression Java API External Web servers cannot easily serve up dynamic content, so J2EE Web applications that use Servlets and JSP pages require a link between an external Web server and an application server. J2EE application servers use these technologies in a Web application to serve dynamic content in addition to any static content in the Web application. J2EE Web Applications are packaged into WAR (Web application archive) files for easier deployment to an application server. WAR files must also have an XML-based deployment descriptor file (web.xml) to describe their contents. J2EE Enterprise JavaBeans Overview The Enterprise JavaBeans (EJB) technology provides the ability to rapidly code and deploy specialized components inside the application server. EJBs come in several different types according to the routine tasks a J2EE application developer needs to perform. For example, EJB Entity Beans are designed to help a developer work with persistent data in a transactional database, and EJB Message-Driven Beans are designed to help a developer work with message queues. EJB components are packaged into JAR (Java ARchive) files for easier deployment to an application server. A single JAR file may contain one or many EJBs, with each EJB composed of an XML-based deployment descriptor, an EJB Home Interface class, an EJB Remote Interface class, and an EJB Implementation class. J2EE Utility Classes Overview J2EE Utility Class archives are collections of Java classes and associated resources you can use in Web applications and EJBs. This mechanism provides an easy way to use third-party utility libraries. For example, xpression makes use of the popular Apache open source log4j utility library, and adding the library once to the J2EE Enterprise Archive makes its capabilities available for use by xpression's various Web applications and EJBs. J2EE Utility Classes are packaged into JAR (Java ARchive) files for easier deployment to an application server. They can contain any file loaded through a Java CLASSPATH, most notably, Java class files, properties files, and locale-specific resource files. Web Application Archive Construction Let s now use our Quote Generator application to demonstrate how to assemble a Web application archive. The application uses the following files and folder structure for a WAR file: ftr.jsp getdocuments.jsp getinputs.jsp getquote.jsp hdr.jsp

75 75 Chapter 4 - The xpression Java API index.jsp preview.jsp preview_top.jsp css\css.css images\global_clear.gif images\pixel-blue.gif WEB-INF\web.xml WEB-INF\classes\XDK.properties WEB-INF\classes\quote_gen\quote_gen.class WEB-INF\lib\xPressionJavaAPI.jar Let s look at what these files do. The first eight files are JSPs at the root of the Web application. The next file is a cascading style sheet, something familiar to Web site designers. In the overview of a WAR, we discussed that a Web application can contain any type of file normally present in a good Web site. The next two files are images, which are also customary for a good Web application. An images folder is commonly used to enable Web applications to share image files across multiple Web pages. The Web application could contain any number of other files and directories, nested as deeply as you want for good Web site design. In J2EE Web applications, the WEB-INF folder is reserved for a web.xml file. The web.xml document must be in the WEB-INF directory so the J2EE server can recognize the WAR properly. The web.xml file is called a web application deployment descriptor, that is, an XML document that describes the contents and configuration of the web application. J2EE specifications dictate the structure and contents of this file. The most common use of this file is to register servlets you ve written so the container knows what URL calls which Java servlet class. Next is the XDK.properties file, which contains a path where xpression Framework stores PDF documents. The next file is the quote_gen.class file required for the Quote Generator application to operate properly. You may recall from a beginning Java course that each class should be part of a package so classes can be organized into folders and quickly found in the CLASSPATH. WEB-INF\classes is a sort of CLASSPATH storage area for classes only your Web application uses. Finally, we must place the xpressionjavaapi.jar file in a lib folder inside WEB-INF so your Web application can gain access to the xpression API.

76 76 Chapter 4 - The xpression Java API After you ve completed the folder structure according to the above rules, you can easily create a WAR file by using the Java "jar" utility, which comes with the Java JDK. From a command prompt, change to the root folder of the Quote_Gen application structure (where the JSP files are) and execute: jar cvf..\quote_gen.war *.* This command will create a proper WAR file in the parent folder of the application structure. That way, you ll avoid including the WAR file in subsequent executions of the command. Now that you ve created a WAR file for your application, feel free to deploy the Web application on your client workstation or server. Command Reference The xpression Framework Command Reference documents the two public classes and their methods in the highlevel JFramework API. There are a few conventions we follow throughout this chapter. Each class has an introductory paragraph explaining its general purpose. All members of each class are explained fully, including the proper syntax, parameters, and code examples. All code examples are written in Java. This chapter is intended as a glossary for the high-level JFramework API. For complete instructions on how to use the API, see Writing an XPression Facade Java Class. Each method is formatted as follows: Method Name Descriptive paragraph. Syntax Object.methodName parm1, parm2 Parameters Parm1 : Data Type Descriptive text. parm2 : Data Type Descriptive text.

77 77 Chapter 4 - The xpression Java API Sample public class CodeSample { public void samplemethod() { try { //sample code here catch { //sample error code here The XPressionFacade Class The XPressionFacade class contains the all the methods you ll need for your xpression Framework applications. For information about exceptions that each method generates, see xpression Facade Exceptions. This section includes these methods: getappname getbusinessdocuments getcategories getdocumentpackedmsohtml getdocumentpackedmsohtml (overloaded) getdocumentpdf getdocumentpdf (overloaded) gethavestartsession getoutputprofiles getschema getstartsession initserverconnection setstatus publishdocument publishdocument (overloaded)

78 78 Chapter 4 - The xpression Java API getappname This method, which returns a string, enables you to retrieve the xpression application name you re using for your Framework session. The application name is set when you initialize a server connection. For more information, see initserverconnection. Syntax appname = XPressionFacade.getAppName(); Sample import com.docscience.xpression.framework.xpressionfacade; public class FacadeTest { public String getappname() { String returnval = ""; facade = new XPressionFacade(); try { returnval = facade.getappname(); catch { System.out.println("An error occurred getting the app name."); return returnval; getbusinessdocuments This method, which returns a string array, enables you to retrieve all business document names for the supplied category. Syntax docs[] = XPressionFacade.getBusinessDocuments(categoryName); Parameters categoryname : String An input parameter containing the category name whose documents you re retrieving.

79 79 Chapter 4 - The xpression Java API Sample import com.docscience.xpression.framework.xpressionfacade; public class FacadeTest { public String[] getbusinessdocuments(string categoryname) { String[] returnvals = null; facade = new XPressionFacade(); try { returnvals = facade.getbusinessdocuments(categoryname); catch { System.out.println("An error occurred getting the document names."); return returnvals; getcategories This method, which returns a string array, enables you to retrieve all the categories the signed on user has access to. Syntax categories[] = XPressionFacade.getCategories(); Sample import com.docscience.xpression.framework.xpressionfacade; public class FacadeTest { public String[] getcategories() { String[] returnvals = null; facade = new XPressionFacade(); try { returnvals = facade.getcategories(); catch { System.out.println("An error occurred getting the categories."); return returnvals;

80 80 Chapter 4 - The xpression Java API getdocumentpackedmsohtml This method, which returns a byte array, enables you to retrieve an assembled document from the content repository in packed (or compressed) MSOHTML format. For more information on unpacking MSOHTML, see The Webtool Utility. You must then convert the byte array to a logical file and unpack (decompress) the file. Syntax document[] = XPressionFacade.getDocumentPackedMSOHTML(documentName, customerkey); Parameters documentname : String An input parameter containing the document name you re assembling. customerkey : String An XML string containing the key values for a specific customer record. Customer key values are always stored in the primary table of the data source. The following samples show how the XML should be formatted: <Keys> <Key name="autopay_key">1</key> </Keys> -or- <Keys> <Key name="autopay_key">1</key> <Key name="language">english</key> </Keys>

81 81 Chapter 4 - The xpression Java API Sample import com.docscience.xpression.framework.xpressionfacade; public class FacadeTest { public byte[] getmsohtmldoc(string documentname, String customerkey) { byte[] returnvals = null; facade = new XPressionFacade(); try { returnvals = facade.getdocumentpackedmsohtml(documentname, customerkey); catch { System.out.println("An error occurred getting the document."); return returnvals; When the document you specify contains a sub-document, the sub-document will use customer data from the default data source instead of the customerdata you provide. The customer data you specify only works for the master document, not the subdocument. getdocumentpackedmsohtml (overloaded) This method, which returns a byte array, enables you to retrieve an assembled document from the content repository in packed (or compressed) MSOHTML format. For more information on unpacking MSOHTML, see The Webtool Utility. Calling this overloaded method is perfect when you want to pass XML customer data that you generate on the fly in transactional applications. You must then convert the byte array to a logical file and unpack (decompress) the file. Syntax document[] = XPressionFacade.getDocumentPackedMSOHTML(documentName, customerdata, xmldatasourcename); Parameters documentname : String An input parameter containing the document name you re assembling. customerdata : String A string containing a customer record in XML format. The XML stream can contain a single record from the primary table and, optionally, additional related records from secondary tables in your data source. In the following example,

82 82 Chapter 4 - The xpression Java API the customer data is a single record from the primary table. <?xml version="1.0" encoding="utf-8"?> <CustomerData> <WITHDRAWAL> <KEY>1</KEY> <NAME>Sara Jones</NAME> <STREET_ADDRESS>6732 River Run</STREET_ADDRESS> <CITY_STATE_ZIP>University City, CA 22445</CITY_STATE_ZIP> <LETTER_DATE>August 5, 2002</LETTER_DATE> <POLICY_PURCHASED>Flexible Premium Variable Life Insurance Policy</ POLICY_PURCHASED> <SALES_LOAD>2.5%</SALES_LOAD> <STATE_PREMIUM_TAX>2.5%</STATE_PREMIUM_TAX> <POLICY_NUMBER> </POLICY_NUMBER> <LANGUAGE>English</LANGUAGE> <JURISDICTION>CA</JURISDICTION> <EFFDATE> </EFFDATE> </WITHDRAWAL> </CustomerData> xmldatasourcename : String An input parameter containing the name of an XML data source you re using to assemble the document.

83 83 Chapter 4 - The xpression Java API Sample import com.docscience.xpression.framework.xpressionfacade; public class FacadeTest { public byte[] getmsohtmldoc(string documentname, String customerdata, String xmldatasourcename) { byte[] returnvals = null; facade = new XPressionFacade(); try { returnvals = facade.getdocumentpackedmsohtml(documentname, customerdata, xmldatasourcename); catch { System.out.println("An error occurred getting the document."); return returnvals; getdocumentpdf This method, which returns a byte array, enables you to retrieve an assembled document from the content repository in PDF format. You must then convert the byte array to a logical file on your own. Syntax document[] = XPressionFacade.getDocumentPDF(documentName, customerkey); Parameters documentname : String An input parameter containing the document name you re assembling. customerkey : String An XML string containing the key values for a specific customer record. Customer key values are always stored in the primary table of the data source. The following samples show how the XML should be formatted: <Keys> <Key name="autopay_key">1</key> </Keys> -or- <Keys> <Key name="autopay_key">1</key> <Key name="language">english</key> </Keys>

84 84 Chapter 4 - The xpression Java API Sample import com.docscience.xpression.framework.xpressionfacade; public class FacadeTest { public byte[] getpdfdoc(string documentname, String customerkey) { byte[] returnvals = null; facade = new XPressionFacade(); try { returnvals = facade.getdocumentpdf(documentname, customerkey); catch { System.out.println("An error occurred getting the document."); return returnvals; When the document you specify contains a sub-document, the sub-document will use customer data from the default data source instead of the customerdata you provide. The customer data you specify only works for the master document, not the subdocument. getdocumentpdf (overloaded) This method, which returns a byte array, enables you to retrieve an assembled document from the content repository in PDF format. Calling this overloaded method is perfect when you want to pass XML customer data that you generate on the fly in transactional applications. You must then convert the byte array to a logical file on your own. Syntax document[] = XPressionFacade.getDocumentPDF(documentName, customerdata, xmldatasourcename); Parameters documentname : String An input parameter containing the document name you re assembling. customerdata : String A string containing a customer record in XML format. The XML stream can contain a single record from the primary table and, optionally, additional related records from secondary tables in your data source. In the following example,

85 85 Chapter 4 - The xpression Java API the customer data is a single record from the primary table. <?xml version="1.0" encoding="utf-8"?> <CustomerData> <WITHDRAWAL> <KEY>1</KEY> <NAME>Sara Jones</NAME> <STREET_ADDRESS>6732 River Run</STREET_ADDRESS> <CITY_STATE_ZIP>University City, CA 22445</CITY_STATE_ZIP> <LETTER_DATE>August 5, 2002</LETTER_DATE> <POLICY_PURCHASED>Flexible Premium Variable Life Insurance Policy</ POLICY_PURCHASED> <SALES_LOAD>2.5%</SALES_LOAD> <STATE_PREMIUM_TAX>2.5%</STATE_PREMIUM_TAX> <POLICY_NUMBER> </POLICY_NUMBER> <LANGUAGE>English</LANGUAGE> <JURISDICTION>CA</JURISDICTION> <EFFDATE> </EFFDATE> </WITHDRAWAL> </CustomerData> xmldatasourcename : String An input parameter containing the name of an XML data source you re using to assemble the document. Sample import com.docscience.xpression.framework.xpressionfacade; public class FacadeTest { public byte[] getpdfdoc(string documentname, String customerdata, String xmldatasourcename) { byte[] returnvals = null; facade = new XPressionFacade(); try { returnvals = facade.getdocumentpdf(documentname, customerdata, xmldatasourcename); catch { System.out.println("An error occurred getting the document."); return returnvals;

86 86 Chapter 4 - The xpression Java API gethavestartsession The method, which returns a true or false value, determines if your xpression session is started. Syntax isstarted = XPressionFacade.getHaveStartSession(); Sample import com.docscience.xpression.framework.xpressionfacade; public class FacadeTest { public boolean issessionstarted() { boolean returnval = null; facade = new XPressionFacade(); try { returnval = facade.gethavestartsession(); catch { System.out.println("An error occurred determining if your xpression session is started."); return returnval; getoutputprofiles This method, which returns a two-dimensional string array, enables you to retrieve output profile names and IDs from the content repository. The following table illustrates the values contained in the returned array. Column Sample Value 0 (ID) (name) PDF to File Syntax outputprofiles[][] = XPressionFacade.getOutputProfiles();

87 87 Chapter 4 - The xpression Java API Sample import com.docscience.xpression.framework.xpressionfacade; public class FacadeTest { public String[][] getoutputprofiles() { String[][] returnvals = null; facade = new XPressionFacade(); try { returnvals = facade.getoutputprofiles(); catch { System.out.println("An error occurred getting output profiles."); return returnvals; getschema This method, which returns a byte array, enables you to retrieve the primary data source group schema in XML format for the category you supply. Syntax schema[] = XPressionFacade.getSchema(categoryName); Parameters categoryname : String Sample An input parameter containing the category name. import com.docscience.xpression.framework.xpressionfacade; public class FacadeTest { public byte[] getschema(string categoryname) { byte[] returnvals = null; facade = new XPressionFacade(); try { returnvals = facade.getschema(categoryname); catch { System.out.println("An error occurred getting the schema."); return returnvals;

88 88 Chapter 4 - The xpression Java API getstartsession This method enables you to start an xpression session for a specific user and application, such as xpression Response or a custom application of your own. Syntax XPressionFacade.getStartSession(userName, password, appname); Parameters username : String Sample An input parameter containing the user name. password : String An input parameter containing the user password. appname : String An input parameter containing the application name. import com.docscience.xpression.framework.xpressionfacade; public class FacadeTest { public void startsession(string username, String password, String appname) { facade = new XPressionFacade(); try { facade.getstartsession(username, password, appname); catch { System.out.println("An error starting your xpression session."); initserverconnection This method enables you to establish a connection with your xpression server. One of the parameters you supply for this method is the "contextfactory," which refers to the context object path for the application server you re using, either IBM WebSphere or BEA WebLogic. Syntax XPressionFacade.initServerConnection(serverProtocolURL, contextfactory);

89 89 Chapter 4 - The xpression Java API Parameters serverprotocolurl : String Sample An input parameter containing the URL for your xpression server. contextfactory : String An input parameter containing the context object path for your application server. import com.docscience.xpression.framework.xpressionfacade; public class FacadeTest { public void initserver() { facade = new XPressionFacade(); String url = "iiop://localhost:2809"; String context = "com.ibm.websphere.naming.wsninitialcontextfactory"; try { facade.initserverconnection(url, context); catch { System.out.println("An error occurred initializing the xpression server."); setstatus The setstatus API parameter was added to the XPressionFacade class to enable users to specify which document status is eligible for publishing. Valid values are ANY and APPROVED. The default value is approved. Because the default status is APPROVED, you do not need to use this API if your document is approved. Syntax setstatus (stringvalue) Parameters stringvalue

90 90 Chapter 4 - The xpression Java API You can set this value to either ANY or APPROVED. public class FacadeTest{ public void testpublishdocument(){ XPressionFacade facade = new XPressionFacade(); String documentname = ""; String customerkey = ""; String outputprofilename = ""; facade.setstatus(xpressionfacade.status_any); facade.publishdocument(documentname, customerkey, outputprofilename); publishdocument This method, which returns an XPressionDocument object, enables you to assemble and publish a document from the content repository using an output profile you supply. Syntax XPressionDocument[] = XPressionFacade.publishDocument(documentName, customerkey, outputprofilename); Parameters documentname : String An input parameter containing the document name you re publishing. customerkey : String An XML string containing the key values for a specific customer record. Customer key values are always stored in the primary table of the data source. The following samples show how the XML should be formatted: <Keys> <Key name="autopay_key">1</key> </Keys> -or- <Keys> <Key name="autopay_key">1</key> <Key name="language">english</key> </Keys> outputprofilename : String An input parameter containing the output profile name. To retrieve output profiles, use the getoutputprofiles method.

91 91 Chapter 4 - The xpression Java API Sample import com.docscience.xpression.framework.xpressionfacade; import com.docscience.xpression.framework.xpressiondocument; import java.io.fileoutputstream; import java.io.fileinputstream; public class FacadeTest { public void publishdocument(string documentname, String customerkey, String outputprofile) { XPressionDocument[] documents = null; facade = new XPressionFacade(); try { documents = facade.publishdocument(documentname, customerkey, outputprofile); for (int i=0;i<documents.length;i++) { FileOutputStream fos = new FileOutputStream("C:\\xPressionDocs\\" + documents[i].getdocumentname() + "." + documents[i].getdocumentformat()); fos.write(documents[i].getdocumentdata()); fos.close(); catch { System.out.println("An error occurred publishing the document."); When the document you specify contains a sub-document, the sub-document will use customer data from the default data source instead of the customerdata you provide. The customer data you specify only works for the master document, not the subdocument. publishdocument (overloaded) This method, which returns an XPressionDocument object, enables you to assemble and publish a document from the content repository using an output profile you supply. Calling this overloaded method is perfect when you want to pass XML customer data that you generate on the fly in transactional applications. Syntax XPressionDocument[] = XPressionFacade.publishDocument(documentName, customerdata, xmldatasourcename, outputprofilename); Parameters documentname : String An input parameter containing the document name you re publishing.

92 92 Chapter 4 - The xpression Java API customerdata : String A string containing a customer record in XML format. The XML stream can contain a single record from the primary table and, optionally, additional related records from secondary tables in your data source. In the following example, the customer data is a single record from the primary table. <?xml version="1.0" encoding="utf-8"?> <CustomerData> <WITHDRAWAL> <KEY>1</KEY> <NAME>Sara Jones</NAME> <STREET_ADDRESS>6732 River Run</STREET_ADDRESS> <CITY_STATE_ZIP>University City, CA 22445</CITY_STATE_ZIP> <LETTER_DATE>August 5, 2002</LETTER_DATE> <POLICY_PURCHASED>Flexible Premium Variable Life Insurance Policy</ POLICY_PURCHASED> <SALES_LOAD>2.5%</SALES_LOAD> <STATE_PREMIUM_TAX>2.5%</STATE_PREMIUM_TAX> <POLICY_NUMBER> </POLICY_NUMBER> <LANGUAGE>English</LANGUAGE> <JURISDICTION>CA</JURISDICTION> <EFFDATE> </EFFDATE> </WITHDRAWAL> </CustomerData> Sample xmldatasourcename : String An input parameter containing the name of an XML data source you re using to publish the document. outputprofilename : String An input parameter containing the output profile name. To retrieve output profiles, use the getoutputprofiles method. import com.docscience.xpression.framework.xpressionfacade; import com.docscience.xpression.framework.xpressiondocument; import java.io.fileoutputstream; import java.io.fileinputstream; public class FacadeTest { public void publishdocument(string documentname, String customerdata, String xmldatasourcename, String outputprofile) { XPressionDocument[] documents = null; facade = new XPressionFacade(); try { documents = facade.publishdocument(documentname, customerdata, xmldatasourcename, outputprofile);

93 93 Chapter 4 - The xpression Java API for (int i=0;i<documents.length;i++) { FileOutputStream fos = new FileOutputStream("C:\\xPressionDocs\\" + documents[i].getdocumentname() + "." + documents[i].getdocumentformat()); fos.write(documents[i].getdocumentdata()); fos.close(); catch { System.out.println("An error occurred publishing the document."); removesession() The removesession() method enables you to stop a session in order to release a seat. This method terminates your xpression connection. Typically, you would call this method at the end of your xpression session. Syntax removesession() Parameters This method takes no parameters. The XPressionDocument Class When publishing a document using the XPressionFacade class, an XPressionDocument object is returned to the caller. Each object contains the document name, format, and data in a byte array. To retrieve those values, you must call the three methods documented in this section. This section includes these methods: getdocumentdata getdocumentformat getdocumentname

94 94 Chapter 4 - The xpression Java API getdocumentdata This method returns the published document data in a byte array. It s up to you to convert the array to a logical file if you want to store a copy of the document locally. Syntax documentdata[] = XPressionDocument.getDocumentData(); Sample import com.docscience.xpression.framework.xpressionfacade; import com.docscience.xpression.framework.xpressiondocument; import java.io.fileoutputstream; import java.io.fileinputstream; public class FacadeTest { public void publishdocument(string documentname, String customerkey, String outputprofile) { XPressionDocument[] documents = null; facade = new XPressionFacade(); try { documents = facade.publishdocument(documentname, customerkey, outputprofile); for (int i=0;i<documents.length;i++) { FileOutputStream fos = new FileOutputStream("C:\\xPressionDocs\\" + documents[i].getdocumentname() + "." + documents[i].getdocumentformat()); fos.write(documents[i].getdocumentdata()); fos.close(); catch { System.out.println("An error occurred publishing the document."); getdocumentformat This method returns the published document format, such as PDF or HTML. Syntax documentformat = XPressionDocument.getDocumentFormat();

95 95 Chapter 4 - The xpression Java API Sample import com.docscience.xpression.framework.xpressionfacade; import com.docscience.xpression.framework.xpressiondocument; import java.io.fileoutputstream; import java.io.fileinputstream; public class FacadeTest { public void publishdocument(string documentname, String customerkey, String outputprofile) { XPressionDocument[] documents = null; facade = new XPressionFacade(); try { documents = facade.publishdocument(documentname, customerkey, outputprofile); for (int i=0;i<documents.length;i++) { FileOutputStream fos = new FileOutputStream("C:\\xPressionDocs\\" + documents[i].getdocumentname() + "." + documents[i].getdocumentformat()); fos.write(documents[i].getdocumentdata()); fos.close(); catch { System.out.println("An error occurred publishing the document."); getdocumentname This method returns the published document name. Syntax documentname = XPressionDocument.getDocumentName();

96 96 Chapter 4 - The xpression Java API Sample import com.docscience.xpression.framework.xpressionfacade; import com.docscience.xpression.framework.xpressiondocument; import java.io.fileoutputstream; import java.io.fileinputstream; public class FacadeTest { public void publishdocument(string documentname, String customerkey, String outputprofile) { XPressionDocument[] documents = null; facade = new XPressionFacade(); try { documents = facade.publishdocument(documentname, customerkey, outputprofile); for (int i=0;i<documents.length;i++) { FileOutputStream fos = new FileOutputStream("C:\\xPressionDocs\\" + documents[i].getdocumentname() + "." + documents[i].getdocumentformat()); fos.write(documents[i].getdocumentdata()); fos.close(); catch { System.out.println("An error occurred publishing the document."); xpression Facade Exceptions When calling the methods of the XPressionFacade class, errors may occur for several reasons: user input, server connections timing out, or the xpression session wasn t properly started. In this section, you ll find all the exceptions the XPressionFacade methods can generate. Each high level exception will also include descriptions of its lower level "child" exceptions. This section includes the following xpression Framework exceptions: XPressionFrameworkException NoAuthorizedRightException NoStartSessionException NoSuchTargetException XPressionEJBException

97 97 Chapter 4 - The xpression Java API XPressionProcessException XPressionFrameworkException This is the top level xpression Framework exception. All other Framework exceptions are lower in the call stack. The following table describes the methods this exception calls. Method geterrorcode geterrorcontent replacewithmsg Description Returns the error code for the exception. Returns the error text for the exception. Enables you to replace the error text with a string array. It returns the replaced text. NoAuthorizedRightException This exception occurs when you re attempting to access a category you don t have rights to. It calls the categoryerror method, which returns a string containing the error message.

98 98 Chapter 4 - The xpression Java API NoStartSessionException This exception occurs when an xpression session isn t started and you re trying to call other XPressionFacade methods. It can call the following methods. Method baseerror getsessionerror Description Returns a base message when no other methods can be called. Returns the specific error text when an xpression session can t be started. NoSuchTargetException This exception occurs when xpression Framework cannot find a remote object. It calls the following methods, depending on the error. Method findappprimarydatasourcebybdterror findbdtiderror findcategorybybdterror findeffectivedateerror outputprofileerror Description Occurs when xpression Framework cannot find the primary data source for the business document. Occurs when xpression Framework cannot find the business document (BDT) ID value. Occurs when xpression Framework cannot find the category for the business document. Occurs when xpression Framework cannot find the effective date for the business document. Occurs when xpression Framework cannot retrieve output profiles. XPressionEJBException This exception occurs when xpression Framework cannot access a remote Enterprise Java Beans (EJB) object. It calls the following methods, depending on the error. Method initialcontexterror lookuptargeterror remoteobjecterror Description Occurs when xpression Framework cannot find the initial context for the EJB. Occurs when xpression Framework cannot look up a remote EJB object. Occurs when xpression Framework cannot use the remote EJB object.

99 99 Chapter 4 - The xpression Java API XPressionProcessException This exception occurs when xpression Framework cannot process an xpression document. It calls the following methods, depending on the error. Method getcustomkeywithdataerror geteffectivedatefromcustomerdataerror parameternotallowempty parsecustomdataerror Description Occurs when xpression Framework cannot process the customer key data. Occurs when xpression Framework cannot get the effective date from the supplied customer data. Occurs when xpression Framework passes an empty parameter when a value is required. Occurs when xpression Framework cannot parse customer data.

100 Chapter 5 The xpression EAI Adapter 5 The xpression EAI Adapter supports the JMS (Java Message Service) specification. Vendor products like IBM WebSphere MQ support JMS for guaranteed delivery of messages between systems. The EAI Adapter provides Message-Driven EJBs (MDBs) to process 3 types of messages: Publish Document Preview PDF Post For Batch MDBs are configured to pull messages off an input queue, process messages, and put results on an output queue Multiple MDBs can work in parallel on the same input queue if supported by the Application Server vendor The xpression EAI Adapter can watch for XML files and accumulate them for submission to a larger batch job XML files can be directly placed in a watched file directory At intervals defined by a batch job scheduler, the EAI Adapter performs the following actions: Gathers XML files for processing a particular batch job Optionally transforms them to xpression streamlined XML Merges the XML files into one large XML file Submits the XML file to xbatch for high throughput processing

101 101 Chapter 5 - The xpression EAI Adapter xadapter Architectural Overview The xadapter is organized around three core components: Listener Technology, Request Processor, and xpression Batch Wrapper. Figure 14. These components and their relationships are shown in the diagram and discussed below. Listener Technology Listeners watch for document processing requests and process them according to the technology they employ. Each listener supports a particular integration technology, be it real-time Web services or near-time JMS messages. Multiple listeners of the same technology can be employed simultaneously, or started in parallel as the xadapter is initialized (through J2EE standard Servlet or message-driven EJB initialization).

102 102 Chapter 5 - The xpression EAI Adapter Request Processor Listeners support two different mechanisms for accomplishing an xpression Server request: If the request is flagged for immediate execution, it sends the request to the xpression request processor. This processor connects to the xpression Server through the xpression Framework API and immediately processes the request and returns the results to the listener plug-in. If the request is flagged for batch execution, it creates an XML file in a temporary holding directory. Any number of requests can be queued for batch execution. xpression Batch Wrapper Batch execution is driven by a batch runner program that calls the xadapter s xpression Batch wrapper Java class. The wrapper program accumulates any XML files queued for batch execution, merges them into one XML file, then calls xpression Batch to process the merged XML file. The batch wrapper is written in a recoverable manner, such that if the batch job completes successfully, the intermediate files are deleted so they will not be processed again on subsequent execution. If the batch job doesn t complete successfully, the intermediate files will remain and the batch job can be run again without manual intervention. The Adapter batch wrapper program uses standard batch job error codes, where a zero code indicates success (and deletion of processed XML files), and negative code indicates failure (and files will remain for a subsequent call to re-execute the batch run). Transformation Engine The Transformation Engine is a simple framework for invoking optional transformations of customer data XML. The adapter supports an open source XML transformation engine (Apache Xalan) for the industry standard XSLT technology. The Transformation Engine provides configuration hooks so that third-party XML transformation engines can be used for jobs where the open source solution does not provide adequate performance or throughput. Third-party engines are invoked using a local Java method call.

103 103 Chapter 5 - The xpression EAI Adapter xadapter Deployment Architecture The xadapter is located on the same physical server as the xpression Server, from which it connects to one instance of the xpression Server. If multiple instances of xpression Server are in use, one instance of an adapter must be installed for each instance of xpression Server. The xadapter does not broker requests across multiple instances of xpression Server. Figure 15. The xadapter, deployed on a WebSphere cluster of two Windows servers, would look like this xadapter Components The xadapter supports these seven processing requests: Publish a document to an output profile. For more information, see Publish Document Web Service Method. Preview a document in PDF format. For more information, see Preview PDF Web Service Method. Submit a document to be published in batch. For more information, see Post For Batch Web Service Method. Find the document categories to which the user is eligible to publish. For more information, see Categories For User Web Service Method.

104 104 Chapter 5 - The xpression EAI Adapter Find documents within a document category. For more information, see Documents For Category Web Service Method. Find output profiles configured for use for a particular document. For more information, see Output Profiles For Document Web Service Method. Find variables used in a document. For more information, see Variables for Document Web Service Method. The xadapter supports three methods of system-to-system integration with XML documents as the data transfer medium: Web Services Integration JMS-Based Messaging Mechanism Transformation Engine Web Services Integration The adapter s Web Services integration mechanism is meant for the real time request-reply system integration paradigm. It carries the most processing overhead of the three mechanisms and therefore should be used only when an immediate reply is needed to a request into the adapter. The Web Services mechanism supports all six types of requests using SOAP and WSDL standards. The requests are easily callable by both Java and.net technologies and each is described below. The Web Services mechanism utilizes the Apache Axis open source Web services toolkit for Java, version 1.3. It defines one JWS (Java Web Service) file which has six methods, one for each processing request type. To retrieve the WSDL for the Web service, type: Publish Document Web Service Method To call the Publish Document Web service method, type: This Web service method accepts the following input parameters. Parameter Description Type DocumentName The name of the xpression Document to publish. String UserName The name of the user to log into xpression. This user must have permission to publish the document selected or the request will fail. String

105 105 Chapter 5 - The xpression EAI Adapter Parameter Description Type Password OutputProfile Transformation CustomerData The password that corresponds to the UserName, authenticated by xpression platform security. The xpression output profile to publish the document to. This output profile must be a valid option for the DocumentName to be published to. Specifies whether a named transformation should be applied by the transformation engine. If this parameter is null or an empty string a default transformation for the document or document category will be applied if configured. The XML document for the xpression XML format data source. String String String String The Web service method will return a String as an output parameter should the method complete successfully. The output String will have the following format: Message '<MessageId>' was successfully published to output profile '<OutputProfile>'. MessageId is the primary key of the primary table involved in the xpression XML data source. OutputProfile is the output profile specified in the call to the Web service. The Web service method returns a SOAP fault should the method fail. The error text of the SOAP fault returns a unique error identifier code plus an error message explaining the error code and any pertinent data involved in the error. Preview PDF Web Service Method To call the Preview PDF Web service method, type: This Web service method accepts the following parameters. Parameter Description Type DocumentName The name of the xpression document to publish. String UserName Password OutputProfile The name of the user logging on to xpression. This user must have permission to publish the document selected or the request will fail. The password that corresponds to the UserName, authenticated by xpression platform security. The xpression output profile to publish the document to. This output profile must be a valid option for the DocumentName to be published to. String String String

106 106 Chapter 5 - The xpression EAI Adapter Parameter Description Type Transformation The Web service returns a byte array (which in accordance with SOAP standards is serialized with BASE64 encoding/decoding) should the request be successfully processed. This byte array is the published document in PDF format. The Web service method returns a SOAP fault should the method fail. The error text of the SOAP fault returns a unique error identifier code plus an error message explaining the error code and any pertinent data involved in the error. Post For Batch Web Service Method Specifies whether a named transformation should be applied by the transformation engine. If this parameter is null or an empty string a default transformation for the document or document category will be applied if configured. To call the Post For Batch Web service method, type: This Web service method accepts the following input parameters. String CustomerData The XML document for the xpression XML format data source. String Parameter Description Type BatchDocument-Type The type of batch document to be processed by the adapter, configured in the adapter s configuration properties file. String UserName The name of the user to log into xpression. String Password The password that corresponds to the UserName, authenticated by xpression platform security. String CustomerData The XML document for the xpression XML format data source. String The Web service method returns a String as an output parameter should the method complete successfully. The output String has the following format: Customer data records for xpression batch document type '<BatchDocumentType>' was successfully written to input XML file directory '<inputxmlfiledirectory>' BatchDocumentType corresponds to the input parameter given in the request. The Web service method returns a SOAP fault should the method fail. The error text of the SOAP fault returns a unique error identifier code plus an error message explaining the error code and any pertinent data involved in the error.

107 107 Chapter 5 - The xpression EAI Adapter Categories For User Web Service Method To call the Categories For User Web service method, type: This Web service method accepts the following input parameters. Parameter Description Type UserName The name of the user to log into xpression. String Password The password that corresponds to the UserName, authenticated by xpression platform security. String The Web service method returns a String array as an output parameter should the method complete successfully. There will be one document category in the String array for every document category the user is eligible to publish documents to. It s possible that the request complete successfully with no entries returned (which means there are no categories to which the user is eligible to publish). The Web service method returns a SOAP fault should the method fail. The error text of the SOAP fault includes a unique error identifier code plus an error message explaining the error code and any pertinent data involved in the error. Documents For Category Web Service Method To call the Documents For Category Web service method, type: This Web service method accepts the following parameters. Parameter Description Type DocumentCategory The xpression category that contains the document to publish. String UserName Password The name of the user to log on to xpression. This user must have permission to publish documents in the DocumentCategory selected or the request will fail. The password that corresponds to the UserName, authenticated by xpression platform security. String String The Web service method returns a String array as an output parameter when the method completes successfully. There will be one document name in the String array for every document in xpression contained within the DocumentCategory given as input. It is possible for the request to complete successfully with no entries returned (which means there are no documents registered in the category given).

108 108 Chapter 5 - The xpression EAI Adapter The Web service method returns a SOAP fault if the method fails. The error text of the SOAP fault includes a unique error identifier code plus an error message explaining the error code and any pertinent data involved in the error. Output Profiles For Document Web Service Method To call the Variables for Document web service method, type: xpressionrequest.jws?method=outputprofilesfordocument This Web service method accepts the following parameters. Parameter Description Type DocumentName UserName Password The name of the xpression Document to retrieve assigned output profiles. The name of the user to log on to xpression. This user must have permission to publish documents in the document category that the document belongs to or the request will fail. The password that corresponds to the UserName, authenticated by xpression platform security. String String String The web service method returns a String array as an output parameter when the method completes successfully. There will be one xpression Output Profile in the String array for every output profile assigned to the document in xpression Design. It is possible for the request to complete successfully with no entries returned (which means there are no output profiles assigned to the document). The web service method returns a SOAP fault if the method fails. The error text of the SOAP fault includes a unique error identifier code plus an error message explaining the error code and any pertinent data involved in the error. Variables for Document Web Service Method To call the Variables for Document web service method, type: This Web service method accepts the following parameters. Parameter Description Type DocumentName The name of the xpression Document to retrieve assigned output profiles. String

109 109 Chapter 5 - The xpression EAI Adapter Parameter Description Type UserName Password The name of the user to log on to xpression. This user must have permission to publish documents in the document category that the document belongs to or the request will fail. The password that corresponds to the UserName, authenticated by xpression platform security. String String The web service method will return a String array as an output parameter should the method complete successfully. There will be one xpression document variable in the String array for every document variable defined in xpression Admin for the document specified. The adapter looks for the default data source group assigned to the document's category and returns all variables for that default data source group. It is possible that the request complete successfully with no entries returned (which means there are no variables used in the document). Each variable will be in the format: TABLE.FIELD where TABLE is the xpression Data Source Group table and FIELD is a field defined within that table. The web service method returns a SOAP fault if the method fails. The error text of the SOAP fault includes a unique error identifier code plus an error message explaining the error code and any pertinent data involved in the error. JMS-Based Messaging Mechanism For adapters equipped with JMS messaging support, the adapter s JMS-Based messaging mechanism utilizes the J2EE standardized Message-Driven EJB technology. This technology provides the ability to pull messages off a JMS supported message queuing technology (for example, IBM MQ Series/WebSphere MQ) using application server facilities for pooling EJBs and parallel processing. However, message-driven EJBs only support pulling messages off one queue and don t natively support pushing output messages to an output queue. To minimize these limitations and achieve your requirements, the adapter is designed as follows: One message-driven EJB class can be configured by any number of named message-driven EJBs in the ejb-jar.xml file deployment. So Document Sciences can write only one Java class implementing the message-driven EJB and it can be named any number of times in the EJB descriptor files. In WebSphere, there is an additional XMI descriptor file that relates a named EJB instance to a JMS adapter listener port, which ties a named EJB instance to an input JMS queue. Each message-driven EJB named instance defines a custom property, the JNDI reference to the JMS output queue, in the ejb-jar.xml file. In this manner, each named EJB instance will not only be configured to pull off a different input queue but will also push output messages to a different output queue. Each named EJB instance can be configured by WebSphere-specific properties in XMI descriptor files for container support of pooling and concurrency.

110 110 Chapter 5 - The xpression EAI Adapter All named EJB instances support the following types of XML-based input messages: Publish a document to an output profile (request type = Publish Document) Preview a document in PDF format (request type = Preview PDF) Submit a document to be published in batch (request type = Post For Batch) For the Publish Document and Post For Batch request types, there is an optional parameter in the XML header that may declare the caller does not want an output message to be queued to the output JMS queue (this parameter doesn t make sense for Preview PDF request where the output queue is always sent a binary document message upon successful completion). Publish Document Message The Publish Document input message requires the following XML request parameters. Parameter Description Required? RequestType The type of request this XML message represents. The value for this message must be Publish Document. DocumentName The name of the xpression Document to publish. Y UserName Password OutputProfile ReturnStatus-Message Transformation The name of the user to log into xpression. This user must have permission to publish the document selected or the request will fail. The password that corresponds to the UserName, authenticated by xpression platform security. The xpression Output Profile to publish the document to. This Output Profile must be a valid option for the DocumentName to be published to. A flag which tells the adapter message listener whether to place a message on the output queue telling whether the request was completed or not. This parameter is not required and if not given, the default is "Y" (yes, a status message will be placed on the output queue). Valid values for this parameter are "Y" and "N" (no, a status message will not be placed on the output queue, even if the request cannot be processed). Specifies whether a named transformation should be applied by the transformation engine. If this parameter is not given, a default transformation for the document or document category will be applied if configured. CustomerData The XML document for the xpression XML format data source. Y Y Y Y Y N N

111 111 Chapter 5 - The xpression EAI Adapter An example XML input file for the Publish Document message is shown below. <?xml version="1.0" encoding="utf-8"?> <AdapterRequest> <RequestType>Publish Document</RequestType> <DocumentName>Automatic Payment Letter</DocumentName> <UserName>xpression</UserName> <Password>xpression</Password> <OutputProfile>Combined Print Archive </OutputProfile> <CustomerData> <CustomerData> <Transaction> <AUTOPAY> <AUTOPAY_KEY>1</AUTOPAY_KEY> <FIRST_NAME>Mary</FIRST_NAME> <MIDDLE>K.</MIDDLE> <LAST_NAME>Jackson</LAST_NAME> <STREET_ADDRESS>9573 Main Street</STREET_ADDRESS> <CITY_STATE_ZIP>San Diego CA, 92108</CITY_STATE_ZIP> <LETTER_DATE>1/1/2002</LETTER_DATE> <CLIENT_NUMBER>50</CLIENT_NUMBER> <FIN_INST_NAME>Wells Fargo</FIN_INST_NAME> <FIN_INST_ACCT_NUM>10000</FIN_INST_ACCT_NUM> <REP_NAME>John Doe</REP_NAME> <REP_PHONE> </REP_PHONE> <LANGUAGE>English</LANGUAGE> <JURISDICTION>CA</JURISDICTION> <EFFECTIVE_DATE> </EFFECTIVE_DATE> < _ADDRESS>jdoe@docscience.com</ _ADDRESS> </AUTOPAY> <AUTOPAY_ACCTS> <AUTOPAY_ACCTS_KEY>1</AUTOPAY_ACCTS_KEY> <AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID> <ACCOUNT_ID_NUM>1001</ACCOUNT_ID_NUM> <ACCOUNT_NAME>JMS Flexible Premium Variable Life</ACCOUNT_NAME> <ACCOUNT_NUMBER> </ACCOUNT_NUMBER> <ACCOUNT_AMT>$934.00</ACCOUNT_AMT> <ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY> <ACCOUNT_NEXT_PAY_DATE>4/8/2002</ACCOUNT_NEXT_PAY_DATE> </AUTOPAY_ACCTS> <AUTOPAY_ACCTS> <AUTOPAY_ACCTS_KEY>2</AUTOPAY_ACCTS_KEY> <AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID>

112 112 Chapter 5 - The xpression EAI Adapter <ACCOUNT_ID_NUM>1002</ACCOUNT_ID_NUM> <ACCOUNT_NAME>JMS Portfolio Annuity</ACCOUNT_NAME> <ACCOUNT_NUMBER> </ACCOUNT_NUMBER> <ACCOUNT_AMT>$360.00</ACCOUNT_AMT> <ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY> <ACCOUNT_NEXT_PAY_DATE>10/24/2002</ACCOUNT_NEXT_PAY_DATE> </AUTOPAY_ACCTS> </Transaction> </CustomerData> </CustomerData> </AdapterRequest> If the ReturnStatusMessage flag is set to return a status message, the xadapter will compose an XML document and send it to the output queue. The return status message will have the following output fields. Output Field Name Description Output Conditions RequestType DocumentName The type of request this XML message represents. The value for this message must be Publish Document. The name of the xpression Document to publish. This field is present in all output messages as long as the input message is properly formed. This field is present in all output messages as long as the input message is properly formed UserName The name of the user to log into xpression. This user must have permission to publish the document selected or the request will fail.this field is present in all output messages as long as the input message is properly formed OutputProfile RequestSuccess-ful MessageId The xpression Output Profile to publish the document to. Flag telling if the request was successfully processed. Valid values are "Y" (yes, the request was processed successfully), and "N" (no, the request had an error in the course of processing). The primary key of the first customer data record, if the information can be found in the request to be processed. This Output Profile must be a valid option for the DocumentName to be published to. This field is present in all output messages as long as the input message is properly formed. This field is present in all output messages This field is present in all output messages as long as the customer data record can be properly processed to obtain this information.

113 113 Chapter 5 - The xpression EAI Adapter Output Field Name Description Output Conditions OutputMessage ErrorCode ErrorMessage A message telling what request was processed. Example: Message '<MessageId>' was successfully published to output profile'<outputprofile>. The unique error code from the adapter for any error encountered processing the request. An error message explaining the error code and any pertinent data involved in the error. This field is only present when the request is successfully processed The field is only present when the request cannot be processed The field is only present when the request cannot be processed If the Publish Document request is completed successfully, an example XML output message would look like this: <?xml version="1.0" encoding="utf-8"?> <AdapterResponse> <RequestType>Publish Document</RequestType> <DocumentName>Automatic Payment Letter</DocumentName> <UserName>xpression</UserName> <OutputProfile>Combined Print Archive </OutputProfile> <RequestStatus> <RequestSuccessful>Y</RequestSuccessful> <MessageId>1</MessageId> <OutputMessage>Message 1 was successfully published to output profile Combined Print Archive .</OutputMessage> </RequestStatus> </AdapterResponse> If the Publish Document request is not completed successfully, an example XML output message would look like this: <?xml version="1.0" encoding="utf-8"?> <AdapterResponse> <RequestType>Publish Document</RequestType> <DocumentName>Automatic Payment Letter</DocumentName> <UserName>xpression</UserName> <OutputProfile>Combined Print Archive </OutputProfile> <RequestStatus> <RequestSuccessful>N</RequestSuccessful> <MessageId>1</MessageId> <ErrorCode>10101</ErrorCode> <ErrorMessage>An error occurred while starting a FrameWork service.</errormessage> </RequestStatus> </AdapterResponse>

114 114 Chapter 5 - The xpression EAI Adapter Preview PDF Message The Preview PDF input message requires the following XML request parameters. Parameter Description Required? RequestType The type of request this XML message represents. The value for this message must be Preview PDF. DocumentName The name of the xpression Document to publish. Y UserName Password Transformation CustomerData The name of the user to log into xpression. This user must have permission to publish the document selected or the request will fail. The password that corresponds to the UserName, authenticated by xpression platform security. Specifies whether a named transformation should be applied by the transformation engine. If this parameter is not given, a default transformation for the document or document category will be applied if configured. The XML document for the xpression XML format data source. An example XML input file for the Publish Document message is shown here. Y Y Y N Y <?xml version="1.0" encoding="utf-8"?> <AdapterRequest> <RequestType>Preview PDF</RequestType> <DocumentName>Automatic Payment Letter</DocumentName> <UserName>xpression</UserName> <Password>xpression</Password> <CustomerData> <CustomerData> <Transaction> <AUTOPAY> <AUTOPAY_KEY>1</AUTOPAY_KEY> <FIRST_NAME>Mary</FIRST_NAME> <MIDDLE>K.</MIDDLE> <LAST_NAME>Jackson</LAST_NAME> <STREET_ADDRESS>9573 Main Street</STREET_ADDRESS> <CITY_STATE_ZIP>San Diego CA, 92108</CITY_STATE_ZIP> <LETTER_DATE>1/1/2002</LETTER_DATE> <CLIENT_NUMBER>50</CLIENT_NUMBER> <FIN_INST_NAME>Wells Fargo</FIN_INST_NAME>

115 115 Chapter 5 - The xpression EAI Adapter <FIN_INST_ACCT_NUM>10000</FIN_INST_ACCT_NUM> <REP_NAME>John Doe</REP_NAME> <REP_PHONE> </REP_PHONE> <LANGUAGE>English</LANGUAGE> <JURISDICTION>CA</JURISDICTION> <EFFECTIVE_DATE> </EFFECTIVE_DATE> < _ADDRESS>jdoe@docscience.com</ _ADDRESS> </AUTOPAY> <AUTOPAY_ACCTS> <AUTOPAY_ACCTS_KEY>1</AUTOPAY_ACCTS_KEY> <AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID> <ACCOUNT_ID_NUM>1001</ACCOUNT_ID_NUM> <ACCOUNT_NAME>JMS Flexible Premium Variable Life</ACCOUNT_NAME> <ACCOUNT_NUMBER> </ACCOUNT_NUMBER> <ACCOUNT_AMT>$934.00</ACCOUNT_AMT> <ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY> <ACCOUNT_NEXT_PAY_DATE>4/8/2002</ACCOUNT_NEXT_PAY_DATE> </AUTOPAY_ACCTS> <AUTOPAY_ACCTS> <AUTOPAY_ACCTS_KEY>2</AUTOPAY_ACCTS_KEY> <AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID> <ACCOUNT_ID_NUM>1002</ACCOUNT_ID_NUM> <ACCOUNT_NAME>JMS Portfolio Annuity</ACCOUNT_NAME> <ACCOUNT_NUMBER> </ACCOUNT_NUMBER> <ACCOUNT_AMT>$360.00</ACCOUNT_AMT> <ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY> <ACCOUNT_NEXT_PAY_DATE>10/24/2002</ACCOUNT_NEXT_PAY_DATE> </AUTOPAY_ACCTS> </Transaction> </CustomerData> </CustomerData> </AdapterRequest> If this request is completed successfully, the output message will be a binary message consisting of the PDF format document output from the request. If this request is not completed successfully, the output message will be an XML message with these output fields. Output Field Name Description Output Conditions RequestType The type of request this XML message represents. The value for this message must be Publish Document. This field is present in all output messages as long as the input message is properly formed.

116 116 Chapter 5 - The xpression EAI Adapter Output Field Name Description Output Conditions DocumentName The name of the xpression Document to publish. This field is present in all output messages as long as the input message is properly formed UserName The name of the user to log into xpression. This user must have permission to publish the document selected or the request will fail.this field is present in all output messages as long as the input message is properly formed RequestSuccess-ful MessageId ErrorCode ErrorMessage Flag telling if the request was successfully processed. Valid values are "Y" (yes, the request was processed successfully), and "N" (no, the request had an error in the course of processing). The primary key of the first customer data record, if the information can be found in the request to be processed. The unique error code from the adapter for any error encountered processing the request. An error message explaining the error code and any pertinent data involved. This field is present in all output messages This field is present in all output messages as long as the customer data record can be properly processed to obtain this information. The field is only present when the request cannot be processed The field is only present when the request cannot be processed If the Preview PDF request is not completed successfully, an example XML output message would look like this: <?xml version="1.0" encoding="utf-8"?> <AdapterResponse> <RequestType>Preview PDF</RequestType> <DocumentName>Automatic Payment Letter</DocumentName> <UserName>xpression</UserName> <RequestStatus> <RequestSuccessful>N</RequestSuccessful> <MessageId>1</MessageId> <ErrorCode>10101</ErrorCode> <ErrorMessage>An error occurred while starting a FrameWork service.</errormessage> </RequestStatus> </AdapterResponse>

117 117 Chapter 5 - The xpression EAI Adapter Post For Batch Message The Post For Batch input message requires the following XML request parameters. Parameter Description Required? RequestType BatchDocument-Type The type of request this XML message represents. The value for this message must be Post for Batch. The type of batch document to be processed by the adapter, configured in the adapter's configuration properties file UserName The name of the user to log into xpression. Y Password ReturnStatusMes-sage The password that corresponds to the UserName, authenticated by xpression platform security. A flag which tells the adapter message listener whether to place a message on the output queue telling whether the request was completed or not. This parameter is not required and if not given, the default is "Y" (yes, a status message will be placed on the output queue). Valid values for this parameter are "Y" and "N" (no, a status message will not be placed on the output queue, even if the request cannot be processed). CustomerData The XML document for the xpression XML format data source. Y Y Y Y N An example XML input file for the Post for Batch message is shown here. <?xml version="1.0" encoding="utf-8"?> <AdapterRequest> <RequestType>Post For Batch</RequestType> <BatchDocumentType>Policy</BatchDocumentType> <UserName>xpression</UserName> <Password>xpression</Password> <CustomerData> <CustomerData> <Transaction> <AUTOPAY> <AUTOPAY_KEY>1</AUTOPAY_KEY> <FIRST_NAME>Mary</FIRST_NAME> <MIDDLE>K.</MIDDLE> <LAST_NAME>Jackson</LAST_NAME> <STREET_ADDRESS>9573 Main Street</STREET_ADDRESS> <CITY_STATE_ZIP>San Diego CA, 92108</CITY_STATE_ZIP>

118 118 Chapter 5 - The xpression EAI Adapter <LETTER_DATE>1/1/2002</LETTER_DATE> <CLIENT_NUMBER>50</CLIENT_NUMBER> <FIN_INST_NAME>Wells Fargo</FIN_INST_NAME> <FIN_INST_ACCT_NUM>10000</FIN_INST_ACCT_NUM> <REP_NAME>John Doe</REP_NAME> <REP_PHONE> </REP_PHONE> <LANGUAGE>English</LANGUAGE> <JURISDICTION>CA</JURISDICTION> <EFFECTIVE_DATE> </EFFECTIVE_DATE> < _ADDRESS>jdoe@docscience.com</ _ADDRESS> </AUTOPAY> <AUTOPAY_ACCTS> <AUTOPAY_ACCTS_KEY>1</AUTOPAY_ACCTS_KEY> <AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID> <ACCOUNT_ID_NUM>1001</ACCOUNT_ID_NUM> <ACCOUNT_NAME>JMS Flexible Premium Variable Life</ACCOUNT_NAME> <ACCOUNT_NUMBER> </ACCOUNT_NUMBER> <ACCOUNT_AMT>$934.00</ACCOUNT_AMT> <ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY> <ACCOUNT_NEXT_PAY_DATE>4/8/2002</ACCOUNT_NEXT_PAY_DATE> </AUTOPAY_ACCTS> <AUTOPAY_ACCTS> <AUTOPAY_ACCTS_KEY>2</AUTOPAY_ACCTS_KEY> <AUTOPAY_ACCTS_CUST_ID>1</AUTOPAY_ACCTS_CUST_ID> <ACCOUNT_ID_NUM>1002</ACCOUNT_ID_NUM> <ACCOUNT_NAME>JMS Portfolio Annuity</ACCOUNT_NAME> <ACCOUNT_NUMBER> </ACCOUNT_NUMBER> <ACCOUNT_AMT>$360.00</ACCOUNT_AMT> <ACCOUNT_FREQUENCY>Monthly</ACCOUNT_FREQUENCY> <ACCOUNT_NEXT_PAY_DATE>10/24/2002</ACCOUNT_NEXT_PAY_DATE> </AUTOPAY_ACCTS> </Transaction> </CustomerData> </CustomerData> </AdapterRequest> If the ReturnStatusMessage flag is set to return a status message, the xadapter will compose an XML document and send it to the output queue. The return status message will have the following output fields. Output Field Name Description Output Conditions RequestType BatchDocument-Type The type of request this XML message represents. The value for this message must be Publish Document. The type of batch document to be processed by the adapter, configured in the adapter's configuration properties file. This field is present in all output messages as long as the input message is properly formed This field is present in all output messages as long as the input message is properly formed

119 119 Chapter 5 - The xpression EAI Adapter Output Field Name Description Output Conditions UserName The name of the user to log into xpression. This field is present in all output messages as long as the input message is properly formed RequestSuccessful MessageId OutputMessage ErrorCode ErrorMessage Flag telling if the request was successfully processed. Valid values are "Y" (yes, the request was processed successfully), and "N" (no, the request had an error in the course of processing). The primary key of the first customer data record, if the information can be found in the request to be processed. A message telling which request was processed. Example: Customer data records for xpression batch document type 'Policy' was successfully written to input XML file directory 'c:\\xpressionadapter\\policyxmlinputdir \\'. The unique error code from the adapter for any error encountered processing the request. An error message explaining the error code and any pertinent data involved in the error. This field is present in all output messages This field is present in all output messages as long as the customer data record can be properly processed to obtain this information. This field is only present when the request is successfully processed The field is only present when the request cannot be processed. The field is only present when the request cannot be processed If the Post For Batch request is completed successfully, an example XML output message would look something like this: <?xml version="1.0" encoding="utf-8"?> <AdapterResponse> <RequestType>Post For Batch</RequestType> <BatchDocumentType>Policy</BatchDocumentType> <UserName>xpression</UserName> <RequestStatus> <RequestSuccessful>Y</RequestSuccessful> <MessageId>1</MessageId> <OutputMessage>Customer data records for xpression batch document type Policy was successfully written to input XML file directory c:\\xpressionadapter\\policyxmlinputdir\\.</outputmessage> </RequestStatus> </AdapterResponse>

120 120 Chapter 5 - The xpression EAI Adapter If the Post For Batch request is not completed successfully, an example XML output message would look as follows: <?xml version="1.0" encoding="utf-8"?> <AdapterResponse> <RequestType>Post For Batch</RequestType> <BatchDocumentType>Policy</BatchDocumentType> <UserName>xpression</UserName> <RequestStatus> <RequestSuccessful>N</RequestSuccessful> <MessageId>1</MessageId> <ErrorCode>10321</ErrorCode> <ErrorMessage>Error writing the customer data file to the file system.</errormessage> </RequestStatus> </AdapterResponse> XML Message Error Handling Should an XML Message input into a message-driven EJB not conform to the requirements above, the adapter will detect the following situations and always return an XML message to the output queue with error information. Malformed XML Should the XML Message input into the adapter not be well-formed XML, the adapter will return an error message as follows: <?xml version="1.0" encoding="utf-8"?> <AdapterResponse> <RequestStatus> <RequestSuccessful>N</RequestSuccessful> <ErrorCode>10322</ErrorCode> <ErrorMessage>The XML message input into the adapter could not be parsed as it was not well-formed.</errormessage> </RequestStatus> </AdapterResponse>

121 121 Chapter 5 - The xpression EAI Adapter Request Type Not Supported Should the XML Message input into the adapter provide an invalid RequestType, the adapter will return an error message as follows: <?xml version="1.0" encoding="utf-8"?> <AdapterResponse> <RequestStatus> <RequestSuccessful>N</RequestSuccessful> <ErrorCode>10323</ErrorCode> <ErrorMessage>RequestType Preview PDF is not supported.</errormessage> </RequestStatus> </AdapterResponse> XML Missing a Required Parameter Should the XML Message input into the adapter fail to include a required parameter, the adapter will return an error message as follows: <?xml version="1.0" encoding="utf-8"?> <AdapterResponse> <RequestStatus> <RequestSuccessful>N</RequestSuccessful> <ErrorCode>10324</ErrorCode> <ErrorMessage>Required parameter OutputProfile was not provided.</errormessage> </RequestStatus> </AdapterResponse> Transformation Engine The transformation engine provides a framework for transforming XML Customer Data before it is submitted to xpression. This "streamlines" the XML so it can be processed more efficiently in xpression, and so that the xpression data schema and corresponding document design can be much simpler. Extensible Stylesheet Language Transformation (XSLT) is the industry standard technology for transforming XML. Since XSLT has some limitations, the transformation engine in the adapter is flexible enough to allow 3rd party transformations to be plugged into the adapter and invoked on demand. As long as that transformation can be called by a local Java class extended from a transformation engine base class named com.docscience.xpression.adapter.transform.

122 122 Chapter 5 - The xpression EAI Adapter AbstractTransformationEngine the adapter engine will implement a subclass of this base class, com.docscience.xpression.adapter.transform. JAXPTransformationEngine, to utilize the free Apache Xalan XSLT engine through the JAX Java XML standard. Each transformation defined in the adapter has a transformation name, a transformation engine (the default being the JAXPTransformationEngine), and a set of one or more properties associated with the transformation (for example, in the JAXPTransformationEngine, it is the XSLT file to apply to the input XML). Example property file settings follow for a transformation named PolicyTransformation, using the default XSLT/ JAXP transformation implementation: Transform.PolicyTransformation.transformationClass= com.docscience.xpression.adapter.transform. JAXPTransformationEngine Transform.PolicyTransformation.xsltFile=C:\\xPressionAdapter\\ transformations\\policy.xslt Because the default transformation is the JAXPTransformationEngine, the first property file setting can and should be omitted. The transformation engine can also set up default named transformations for documents and categories, should a request into the adapter publish or preview a document (that is, the "Publish Document" or "Preview PDF" request types only). The adapter will implement a maximum of one transformation per request, and the transformation will be found with the following algorithm: 1. If a transformation name is specified on the adapter request, that transformation is applied and any defaults are ignored. 2. If no transformation name is specified on the request, the transformation engine looks for a default transformation for the document name. 3. If no default transformation is specified for the document name, the transformation engine looks for a default transformation for the document s category. 4. If no default category transformation is configured, no transformation at all will be applied. Example property file settings DocumentTransform.PolicyTransformation.documentName=NB Policy DocumentTransform.PolicyTransformation.transformName= PolicyTransformation CategoryTransform.BillingTransformation.categoryName= Billing Documents CategoryTransform.BillingTransformation.transformName= BillingTransformation

123 123 Chapter 5 - The xpression EAI Adapter The properties above define one default document transformation and one default category transformation. All documents with a name of "NB Policy" will execute the "PolicyTransformation" definition by default. All documents in the "Billing Documents" category will execute the "BillingTransformation" definition by default. The first time the Transformation Engine is loaded into the JVM, all properties in the xpressionadapter.properties file with a prefix of Transform., DocumentTransform., and CategoryTransform., are loaded into 3 different HashMap tables respectively so transformations can be found and executed quickly. The Transform HashMap is keyed by the transformname, the DocumentTransform HashMap is keyed by the document name, and the CategoryTransform HashMap is keyed by the category name. Should a generic XSLT transformation engine not suffice, you can create your own transformation engine by plugging in Java code you create into the adapter. To do so, you must extend the com.docscience.xpression. adapter.transform.abstracttransformationengine class and override the public Result transform(source xmlsource) method. A template for doing so is provided below: package com.mycompany.xpression.adapter.transform; import javax.xml.transform.transformerfactory; import javax.xml.transform.transformer; import javax.xml.transform.source; import javax.xml.transform.result; import javax.xml.transform.stream.streamsource; import javax.xml.transform.stream.streamresult; import javax.xml.transform.transformerconfigurationexception; import javax.xml.transform.transformerexception; import com.docscience.xpression.adapter.transform.abstracttransformationengine; public class MyTransformationEngine extends AbstractTransformationEngine { /** * To process the source tree to the output result. * xmlsource The input for the source tree. Result */ public Result transform(source xmlsource) { // insert code here to perform the transformation Should you complete the code for this class, named com.mycompany.xpression.adapter.transform.mytransformationengine, you would enable the class in a transformation named MyTransform with an xpressionadapter.properties entry such as: Transform.MyTransform.transformationClass=com.mycompany.xpression. adapter.transform.mytransformationengine

124 124 Chapter 5 - The xpression EAI Adapter XML File Export for Batch Execution The adapter supports a convenient way of executing the xpression Batch standardized component of the xpression product suite. xpression Batch is designed to publish large volumes of documents efficiently, and is the most efficient way to utilize the xpression publishing engine. However, xpression Batch supports the execution of only one XML input file per step. xpression Batch does not provide any XML transformation capabilities. The xadapter accumulates smaller individual XML documents queued for batch execution throughout the day. The Adapter then provides a batch runner wrapper Java class, which optionally transforms and then merges the XML files in a format that can be used as input into one xpression Batch run, execute xpression Batch, and perform file cleanup activities. Note: xpression Batch 2.0 and above provides the ability to define multiple job steps in one batch job, and each job step can have a different XML data source override file. xadapter supports only one job step, and that job step must have the same name as the batch job defined in xpression Admin and configured in the xpressionadapter.properties configuration file. XML files containing customer/document data can come from direct XML export to a file system accessible by the adapter. XML files may also come from the Web Services and JMS mechanisms above from the Post For Batch request type. For more information, see Post For Batch Web Service Method on page 106. Each batch job executed is identified by the type of documents published in the batch run. A batch job execution program calls the batch process from the command line according to any interval desired and defined in the batch job execution program. Caution: The Adapter batch runner wrapper must not, for the same batch document type, be called in parallel. Doing so would result in any number of issues as two adapter batch runners compete for the same file resources in the same input and temporary XML file holding areas. The Adapter batch runner wrapper accumulates any files not previously processed in a batch run of that document type and calls xpression Batch, using this command line: java com.docscience.xpression.adapter.batch.adapterbatchrunner Policy In this case, "Policy" is the type of document to execute. The adapter would read all settings in the xpressionadapter.properties property file with a prefix of Policy.

125 125 Chapter 5 - The xpression EAI Adapter Here s a sample property file: Policy.inputXmlFileDirectory=C:\\xPressionAdapter\\PolicyBatchXMLExport\\ Policy.inputXmlFileNamePattern=*.xml Policy.temporaryXmlFileDirectory=c:\\xPressionAdapter\\PolicyTempXML\\ Policy.errorXmlFileDirectory=c:\\xPressionAdapter\\PolicyErrorXML\\ Policy.mergedXmlFileDirectory=C:\\xPressionAdapter\\PolicyMergedXML\\ Policy.xPressionBatchJobName=PolicyBatchJob Policy.transformationName=PolicyTransformation Policy.customerDataMergeDelimiter = /dataroot/transaction Policy.xmlErrorThreshold=100 The Adapter Batch Runner wrapper works as follows: 1. Check to see if the marker file C:\xPressionAdapter\PolicyTempXML\ BatchNotComplete.MARKER exists on the file system. 2. If the marker file already exists, assume a previous batch run did not complete successfully and perform no cleanup activities. 3. If the marker file doesn t exist, perform the following: Delete any files named C:\xPressionAdapter\PolicyTempXML\*.xml as these files may be leftover from a previous batch run and we don't want to double-process them. If the files cannot be cleaned up, abort with a fatal error message in the log and a negative System.exit() code. Write a marker file named C:\xPressionAdapter\PolicyTempXML \BatchNotComplete.MARKER to show that the Policy batch process has not yet completed successfully. If the file cannot be written, abort with a fatal error message in the log and a negative System.exit() code. 4. The program looks for all files named C:\xPressionAdapter\ PolicyBatchXMLExport\*.xml. For each file that matches this pattern we loop through and: Move each file from the export directory to the c:\xpressionadapter\policytempxml directory (this step is taken for safety and recoverability, because moving the file ensures that the file is completely written to the file system and that the file names aren t duplicated) If the file can t be moved, log as a warning message in the log file and move to the next file in the list (assume the file is locked because it isn't completely written to the file system). 5. Next, set the XML error threshold count to zero and look for all files named C:\xPressionAdapter\ PolicyTempXML\*.xml. For each file found, do the following processing: Call the transformation engine with the XML file and a transformation named "PolicyTransformation". Note that XML transformation is completely optional and the transformationname property defined about should be omitted if this is not needed.

126 126 Chapter 5 - The xpression EAI Adapter Aggregate and merge those files into a file named C:\xPressionAdapter\PolicyMergedXML\PolicyBatchJob<timestamp>.xml in a format that can be directly input into xpression BatchRunner. If a transformation is configured, run the appropriate transformation engine and catch any exceptions thrown. (If a transformation is not configured, proceed to the next bullet point in this step.) If an exception is thrown, consider the XML file to be bad. Move the original XML input file from the temp directory to the directory specified by the error XML file directory (c:\xpressionadapter\policyerrorxml in the example on page 125). If the file already exists in the error directory, or the file cannot be moved for any reason, log a fatal error and abort the batch job with a negative exit code. If the file is moved successfully, increment the error threshold counter by one. Check the XML error threshold and, if it has been exceeded, log a fatal error and exit the batch job with a negative exit code. If a bad transformation is encountered, the original input file can be moved successfully from the temp directory to the error directory, and the error threshold is not exceeded, move on to the next input file at the beginning of step 5. If the transformation was successful or if no transformation was encountered, continue with the the next bullet point. For each XML file resulting from the above process (either successfully transformed or not transformed at all), parse the XML file stream to see if it is well-formed. If the XML is well-formed, then make sure the structure matches the customer data merge delimiter specified. If the XML file is not well-formed or if it is well-formed but cannot be merged because the XML node structure does not match the merge delimiter, move the original XML file from the temp directory to the directory specified by the error XML file directory (c:\xpressionadapter\policyerrorxml in the example on page 125). If the file cannot be moved, log a fatal error and abort the batch job with a negative exit code. If the file is moved successfully, increment the error threshold counter by one. Check the XML error threshold and, if it has been exceeded, log a fatal error and exit the batch job with a negative exit code. If an XML error is encountered, the original file is moved successfully, and the threshold is not exceeded, move on to the next input file identified at the beginning of step 5. If the XML file is well-formed and complies with the customer data merge delimiter structure, proceed with the steps below. When merging XML input records (after transformation if a transformation is engaged), the adapter needs to understand what XML node to start the merge process. In the example configuration on page 125, a merge delimiter of /dataroot/transaction would tell the adapter to begin the merge process at the <Transaction> node underneath the <dataroot> root node of the XML document. Each

127 127 Chapter 5 - The xpression EAI Adapter input XML document would need to have a root element named dataroot and inside that element there must be at least one element named Transaction. Everything inside the Transaction element would be extracted from the current XML document and merged with other Transaction elements inside the current document and from other XML documents. The resulting XML document has the same XML structure as the input XML documents, starting with a dataroot root node and including any number of Transaction elements inside the dataroot root node. If the merge process fails, log a fatal error in the log file and return a negative System.exit() code. 6. Start xpression BatchRunner with a job named PolicyBatchJob and C:\xPressionAdapter\PolicyMergedXML\PolicyBatchJob<timestamp>.xml file as input. Note: PolicyBatchJob must be a valid xpression Batch job already defined in xpression Admin, it must have only one job step named PolicyBatchJob, and the merged XML file produced by the adapter must be appropriate as an XML data source override for that single job step. 7. When the xpression BatchRunner job completes successfully (that is, return a zero exit status), the Adapter Batch Runner job will: Remove the marker file. Delete all files named C:\xPressionAdapter\PolicyTempXML\*.xml. Leave the file C:\xPressionAdapter\PolicyMergedXML\ PolicyBatchJob<timestamp>.xml on the file system for auditing and debugging purposes. 8. Should the xpression BatchRunner job exit with a status of zero or one, the Adapter Batch Runner job considers the run successful and exits with a zero status code. Otherwise, the Adapter Batch Runner job considers the run unsuccessful, does not perform any cleanup activities and exits with a status of negative one. The marker file must stay on the file system to show the process did not complete successfully and the batch process can be rerun from the start. Adapter Configuration Information The xpressionadapter needs the following information as part of its configuration to work properly. Parameter xpressionserverurl Definition The URL the xadapter uses to connect xpression Server through the xpression Framework Java interface (JFramework). The xpression Java Framework uses the IIOP/ RMI protocol to connect to xpression, so this URL must point to the IIOP/RMI port exposed by the application server for the Java Virtual Machine that runs xpression Server.

128 128 Chapter 5 - The xpression EAI Adapter Parameter xpressionapplication- Name PreviewPDFOutputProfile xpressionbatchrunner- ScriptDir Definition This is the name of the xadapter application as listed in the AppList.xml xpression configuration file and accordingly assigned document category Access Rights for users and groups in xpression Admin. To view categories, documents in a category, and submit document preview or publish requests, the username given in the request must have access rights in the appropriate category for this application name. This is the xpression Server Output Profile default for CompuSet composition engine documents, should this optional parameter not be given on Preview PDF requests into the adapter. xpression Publish composition documents do not require a PDF output profile to be executed to return PDF documents. The directory where the xpression Batch BatchRunner script is installed into, typically the location of the exploded xpression EAR file after it s deployed to the application server. For each batch document type, a set of properties will be defined as described in Transformation Engine. Here s an example: xpressionserverurl=iiop://localhost:2809 xpressionapplicationname=xpression Adapter PreviewPDFOutputProfile=PDF Return to Application xpressionbatchrunnerscriptdir=c:\\websphere\\appserver\\installedapps\\xpression. ear\\ Creating the Adapter Application After deploying the xadapter, you must configure your environment. You do this by adding your application definition to AppList.xml and configuring it using xadmin. In this chapter, we ll show you how to get everything set up. Caution: We strongly urge you not to make changes to AppList.xml on a production xpression server until you re sure your application works as intended in a test environment. Adding Your Application Definition To add the application definition to AppList.xml: 1. Locate AppList.xml on your xpression server and open it in a text editor. The default location is C:\xPression, but may differ on your server.

129 129 Chapter 5 - The xpression EAI Adapter 2. Type the application element between the <AppList></AppList> tags. For example: <AppList> <Application name= xpression Adapter > </Application> </AppList> Your application name must not contain apostrophes ( ). 3. Type the access rights your application supports, including whether or not they re hierarchical. For example: <AccessRights heirarchical="yes"> <Access name="read" /> <Access name="write" /> <Access name="approve" /> </AccessRights> 4. Type the closing </Application> element at the bottom of your application definition. 5. Save AppList.xml and exit your text editor. When complete, your application definition should appear similar to the following. <AppList> <Application name="xpression Adapter"> <AccessRights heirarchical="yes"> <Access name="read" /> <Access name="write" /> <Access name="approve" /> </AccessRights> </Application> </AppList> Configuring Your Application with xpression Admin Now that you ve added your application definition to AppList.xml, it s time to configure it with xpression Admin. Associating Attribute Sets with Your Application Before you can configure categories, data sources, access rights, and workflow for your application, you must first associate one or more attribute sets with your application. To associate attributes with your application:

130 130 Chapter 5 - The xpression EAI Adapter 1. Open your browser and point to Replace servername and portnum with your server name and port number. 2. Click Category Management, then Attribute Sets. 3. Click an attribute set that you want to associate with your application. You can also create your own attribute sets. For more information, see the xpression System Administrator s Guide. 4. Select your application from the list. 5. Click Next twice, then Save. The attribute set is now associated with your application. Assigning Categories to Your Application To assign categories to your application: 1. In xpression Admin, click Category Management, then Categories. 2. Select a category you want to assign to your application. 3. Select your application from the list. 4. Click Save. The category is now assigned to your application. 5. To assign more categories to your application, repeat this procedure. Assigning Data Sources to Your Application To assign data sources to your application: 1. Select a category you ve already assigned to your application. 2. Click the Data Sources tab. 3. Select a data source group from the list. 4. Click Set Application. 5. Select your application from the drop-down list. 6. Select the data sources you want to assign to your application and click Add. 7. Select a default data source for your application from the drop-down list and click Save. 8. To assign additional data sources to your application, repeat this procedure. Setting Up Access Rights for Your Application To set up access rights for your application: 1. Click the Access Rights tab for a category you ve assigned to your application. 2. Click View/change for your application, then click Add.

131 131 Chapter 5 - The xpression EAI Adapter 3. Select users from the list of available users and click Add. 4. Click Save. The users you selected for the category now have access to your application. 5. When the list of users reappears, select the access levels for each user and click Save. Configure Your Batch Scripts To configure xpression Batch Runner: 1. Create a directory to house your xpression Batch scripts. For example: c:\xpressionadapter\batchscripts. 2. Copy BatchRunner.bat from the xpression.ear installation directory to the new directory. The xpression.ear directory should be in the installedapps directory of your WebSphere application server. 3. Open BatchRunner.bat in a text editor and remove the pause at the end of the script. The last line of the script must contain a call to the java program. Immediately before the call to the java program, add a command to change the directory to your xpression.ear directory. Figure 16. Editing the batchrunner.bat file. rem run batch runner as a java application SET WAS_HOME=c:\Program Files\WebSphere\AppServer SET JAVA_HOME=c:\Program Files\WebSphere\AppServer\java SET UNIARCHHOME=c:\xPression SET INSTALLPATH=. SET JDBCDRIVER=c:\jdbcdriver cd /d "C:\Program Files\WebSphere\AppServer\installedApps\Network\xPression2.ear" "%JAVA_HOME%\bin\java" -classpath pause Remove this. Changes the directory to the xpression.ear folder. 4. Copy AdapterBatchRunner.bat from the xpressionadapter.ear installation directory to c:\xpressionadapter\batchscripts. 5. Open AdapterBatchRunner.bat in a text editor and set the variables at the top of the script as needed. 6. Edit xpressionadapter.properties file in your Adapter Home directory to set the xpressionbatchrunnerscriptdir parameter properly.

132 132 Chapter 5 - The xpression EAI Adapter For example, if you place your Batch Runner scripts in c:\xpressionadapter \batchscripts, it would look like this: xpressionbatchrunnerscriptdir=c:\\xpressionadapter\\batchscripts\\ 7. Configure your Batch Runner program to execute the c:\xpressionadapter\batchscripts\adapterbatchrunner script with a parameter of the batch document type you want executed. Verifying Your Installation Open a Web browser and type xpressionrequest.jws?wsdl to retrieve the WSDL of the Web service. Figure 17. Retrieve the WDSL.

133 133 Chapter 5 - The xpression EAI Adapter JMS For adapters which support JMS capabilities, you will be provided with a small testing application named xpressionadaptertest.war. This application is provided as a convenience for testing and should never be deployed to a production environment. You are welcome to use your own messaging tools and programs to test the adapter. Should you decide to use the test application we provide, deploy the xpressionadaptertest.war file to the same application server as the adapter, with the Context Root xpressionadaptertest. Follow the testing instructions below to the adapter's support for Java Messaging Service requests: 1. Open your Web browser and type 2. Add some XML content and click Submit. Figure 18. Testing the JMS.

134 134 Chapter 5 - The xpression EAI Adapter 3. The following page appears. Figure 19. WebSph ere Embedded Messaging page. Messages are queued in JMS until the adapter has time and resources to process them. Because of this, results may not be available immediately. Refresh the xadapter Test Utility periodically to look for new messages on the output queue, or examine the xpressionadapter.log file to see if your request has been completed. XML Files Three XML files are used: Publish Document Preview with PDF Post for Batch