How to Publish with EWPS - Quick Guide
By AndyL-Oracle on Jul 08, 2014
Getting Started with Documaker and Web Services
Today I'll be addressing a common question - how do I get started publishing with web services and Documaker? The aim of this guide is to give you a quick rundown on how you can be up and running with publishing via web services and Documaker within a few hours, or even minutes! Before we get started, I think it's pertinent to discuss web services. Web Services are, put simply, a method for communication between two software components over a network. Prior to web services, there were various protocols, languages, and proprietary methods for performing this sort of communication. Web Services provide a (hopefully) simpler method of facilitating this communication by being language-independent and by providing information on how a system can request and receive data (e.g. what parameters are needed in the request and what the structure of the data response will look like). I use the analogy that it's like an IKEA pictograph manual for assembling a bed: it's generic enough that almost anyone can interpret the instructions and (hopefully) obtain the same results given the same set of inputs. There are two major programming models used when providing and consuming web services:
- REST-based (Representational State Transfer) - this model represents each web document and process as a web resource, which has a unique URI. HTTP headers are used to specify actions that manipulate the web resources. Because HTTP headers are used, this means that message exchange can be performed in a multitude of formats (JSON, HTML, XML, etc.) and SOAP, WSDL, and other WS-* standards are not used. RESTful services use the HTTP protocol, which means the only methods available are GET, PUT, POST, and DELETE; and this also means that requests can be bookmarked and responses cached. Security in RESTful services is implemented in the HTTP infrastructure.
- SOAP-based (Simple Object Access Protocol) - this model exposes web service interfaces using an XML document called WSDL, which have URLs. Message exchange is in SOAP format, which is a document specification represented in XML. SOAP is suitable for large applications using complicated operations and applications requiring sophisticated security, reliability, and other features supported by the WS-* standards. SOAP is also useful where protocols other than HTTP must be used. SOAP is used by financial and insurance companies, government agencies, and more.
Documaker offers two sets of web services: EWPS and DWS. For all Documaker Standard Editions and pre-12.0 versions, the only flavor available is EWPS. For Documaker Enterprise Edition and 12.0 forward, you have a choice of EWPS or DWS. Determining which to set of web services to use is documented in the ODEE Administration Guide:
- EWPS - These web service methods offer a number of ways to gather information about the MRL, locate documents or field information, and retrieve a form during transaction processing. EWPS also lets you update a document in WIP, publish a document from an extract file or publish a document stored in WIP. EWPS supports SOAP and JSON protocols.
- DWS - These web services, introduced in Documaker version 12.0, let you submit a job that tells the system to publish a document from an input or extract file. DWS also provides a generic web service method, doCallIDS, that lets you work with Docupresentment using specific request types. Because of Documaker Web Services' concrete schema, you should use the doCallIDS method with the Business Process Execution Language (BPEL) to facilitate workflow within the iDocumaker application. This method can also be used by BPEL outside of iDocumaker or by other web service clients to make specific requests to IDS or Documaker and should be used if your request needs to be asynchronous. DWS supports SOAP protocols.
With that out of the way, let's begin. There are four components to using Documaker with Web Services:
- Documaker (and a resource library)
- Web Service application server
- Web Service test tool
You'll need to have a functioning Documaker environment - that means Documaker and a Master Resource Library (MRL). The version of Documaker doesn't matter too much, so let's assume it's a Standard Edition, or any version pre-12.0. You're also going to need Docupresentment - if you don't already have this in your enterprise, you can download a trial license version from eDelivery. Login to your Oracle account, accept the license and restrictions, then search for the Product Pack "Oracle Insurance Applications". Select the appropriate OS platform (for the purposes of this demonstration, I'm going to assume you're running on Microsoft Windows). You should see search results similar to this:
Click on the link for Oracle Documaker Standard Edition media pack, then you'll see the contents of the media pack:
Click the Download button, and about 207MB later, you'll have a zip file ready for installation. Extract the contents of the zip file, and you'll see a number of files. Open up the read me file and have a look - in here you'll find important information like links to documentation, release notes, bugs fixed in this version, and other useful things. Most useful is a description of what these files are:
- Docupresentment Server: Collection of applications including IDS and EWPS used to web-enable Documaker solutions.
- Docupresentment Client: Core client files and example code for connecting to an IDS Server solution.
- Documaker Shared Objects: A package of Documaker service routines that can be invoked while running under IDS.
What does all that mean? It's pretty simple, really: Docupresentment Server and Documaker Shared Objects are the core server-side components that you'll need to install to have Docupresentment running. Docupresentment Client is a package that needs to be installed on any servers that will be submitting requests to Docupresentment - that is to say, Docupresentment's clients - examples of this would be application or web servers that submit requests to Docupresentment. At this point, it's a good idea to define what Docupresentment is - Docupresentment itself is a request processor that is scalable and highly configurable. Once installed, you'll get a configuration that allows Docupresentment to processes requests that are specific to Documaker. You can even make your own requests - but that's a post for another day. For now, you need only know that Docupresentment can receive a request, process it, and send a response.
Go ahead and perform the installation routines for all three packages - starting with the ODDS (Oracle Documaker Docupresentment Server), then ODSO (Oracle Documaker Shared Objects) and then ODDC (Oracle Documaker Docupresentment Client). You can accept the defaults for all installation questions - the one key point is to make sure the EWPS component of ODDS is checked for install (it is by default). At this point you should have two directories for Docupresentment: Server (c:\docserv) hereafter called [ODDS] and Client (c:\docclnt). We won't be doing anything further with the Client directory, but let's talk about it for a moment. These instructions are going to assume that you will run the web services host (an application server like Tomcat) and Docupresentment on the same machine, however in a real environment that might not always be the case - you might have application servers running in a cluster, and back end services like Documaker and Docupresentment run on totally different machines. That's acceptable (and a good practice) so in those cases, you would find the Docupresentment client installed to the application servers only.
Next, we'll do a little Docupresentment configuration. First we have to work around some Windows items - starting with Windows Vista/Windows Server 2008, the default dynamic port range for TCP/IP ports changed. It so happens that the new default lower end of this range changed to the same port used by the installation routines for Docupresentment, so we need to do a little change to accommodate this. In the file, locate this line:
And change it to:
This line may appear more than once so change all occurrences! Note that the 127.0.0.1 might be a different IP address or a host name - no matter, just change the 49152 to 49200. You might be wondering why I chose port 49200. Well it happens that this port was free on my test system. You can determine what ports are in use on your test system too! Open a command prompt and type "netstat -a" and press Enter. Have a look at the ports in use and make sure the number you pick isn't shown anywhere in netstat's output!
Save your changes to the configuration file and close it. Next we'll move to [ODDS]\docserver.xml - you're going to perform a very similar change from:
You're done - save the file and close it. While we're here, let's open [ODDS]\dap.ini for editing. You're going to add a value to tell Docupresentment about your configuration, so add these 3 lines at the top of the file:
[ Config:DMS1 ]
The value of [ Config:DMS1 ] should match a Config name in your FSIUSER/FSISYS INI files. Refer back to your existing Documaker MRL and have a look in the INI files to determine the proper values - I always make the libraryId and name match a <CONFIG:_> value. The values for the INIFile= options should be the path and filenames of your Documaker FSIUSER and FSISYS INI files. Next, add this to the list of configurations in the DAP.INI file by locating the INI group [Configurations] and adding Config=DMS1 to the list. Save and close the file. If you haven't started Docupresentment, go ahead and do so now. If you already started it, you can stop and start it again. To start Docupresentment, run [ODDS]\docserver.bat. To stop, locate the console window for Docupresentment and press CTRL-C. You'll be prompted to "terminate the file? (y/n)" to which you can reply with a Y.
The last bit of configuration we need to do for Documaker/Docupresentment is to the master resource library (MRL). You'll need to go into both the FSIUSER and FSISYS INI files and change all paths to absolute paths. This is because Docupresentment needs absolute paths for locating resources, since it can be running in any location and relative paths may not be relative to Docupresentment. Next you'll need to add a bit of configuration that's needed for Docupresentment to run your MRL. In either the FSIUSER or FSISYS (recommended) add the following items:
< RPDRunRP >
Executable = c:\fap\dll\gendaw32.exe
Directory = c:\fap\mstrres\dms1
UserINI = fsiuser.ini
< RPRun >
BaseDirectory = c:\fap\mstrres\dms1\
BaseLocation = http://localhost/doc-data
Debug = Yes
SingleStepGendata = Yes
Startup = c:\fap\dll
UserIni = c:\fap\mstrres\dms1\fsiuser.ini
< IDSServer >
doPublishAttachment = Yes
Naturally you'll want to change any of the paths to match your particular environment. There is one item we need to discuss - SingleStepGendata. It's quite possible that your MRL is set up to run in multi-step. That's fine - just make sure you set this option to no if that's the case. Otherwise, if you're running single step, set this option to Yes. If you're not sure, locate the JDT file referenced by the <Data>AfgJobFile= INI option and look at the job level rules forInitPrint form set rules for NoGenTrnTransactionProc. If you find both, then you're running single step. If you don't find both, then it's possible you're running two step, in which case you might need to reconfigure your JDT for single step. Have a look at the Documaker Standard Edition Administration Guide in the section entitled "Using Single Step Processing".
Now you'll need a software implementation of the Java Servlet and Java Server Pages specification in which you can host the EWPS web services. I am going to assume that you'll use Apache Tomcat, but you can use any supported Servlet/JSP implementation. You can try unsupported options like Glassfish or JBoss, but they will be unsupported and therefore not recommended. I chose Tomcat because it's familiar, solid, and light-weight. You can visit the Apache site here, and select the appropriate installer for your platform - it's a simple process to install it; all you have to do is unzip the file into a directory of your choosing. At this point you should have a directory for Tomcat (c:\apache-tomcat-6.0.41), hereafter called [TOMCAT]. Let's deploy EWPS components into Tomcat.
Deployment is simple - the web services are contained in a WAR (web archive) file in [ODDS]\webservices\ewps-axis2.war. To deploy, simply copy this file into [TOMCAT]\webapps. Start up Tomcat by executing [TOMCAT]\bin\startup.bat, and the WAR file will be exploded into [TOMCAT]\webapps\ewps-axis2. Hereafter we'll call this directory [EWPS]. Note: if you get a warning about a missing JAVA_HOME or JRE_HOME when you try to start Tomcat, you need to create an environment variable. You can do this by opening your startup.bat file in a text editor and adding the following at the top of the file:
Replace the value to the right of the = with the path to your JRE. If you don't have a JRE and instead have a JDK, use JAVA_HOME= instead. If you don't have a JDK or a JRE, go to www.java.com and download/install one. Save the file and start Tomcat again and you should be up and running. Once the deployment is completed, you can peruse the directory structure created - there are two files in particular that you will be interested in: [EWPS]\WEB-INF\xml\ewps.config.xml and [EWPS]\WEB-INF\classes\log4j.xml. We won't be doing anything with the latter file, but in the future if you want to change the logging mechanisms used by EWPS or enable debugging output, this is one place you'll come back to. For now, open up the ewps.config.xml file and have a look. There's not a lot to this file at first glance, but there are some important things to note. You might already see the libraryConfigurations node, and notice there's a commented-out configuration. You'll be uncommenting this libraryConfiguration and changing the name - make it match the <Config: _> name you used in the Docupresentment configuration. After you're done it should look similar to this:
<libraryConfiguration libraryId="DMS1" name"DMS1"/>
After making this change, stop Tomcat by pressing CTRL-C in the Tomcat window, and then restart it by issuing the [TOMCAT]\bin\startup.bat command. You can validate the deployment of EWPS and Tomcat by opening a browser and navigating to http://localhost:8080/ewps-axis2 (replace localhost with your server name or IP address if it's different). You should see a screen like this:
Click on the Services link to see the available services, and you should immediately notice DocumentService which contains most of the methods or operations we are interested in:
You can explore this further at your leisure, but for now note the Service EPR or endpoint: http://localhost:8080/ewps-axis2/services/DocumentService. We'll need this later.
Once you've completed this, you're done - all that's left is to submit a web service request! You will need an additional piece of software to accomplish this task. If you're going to work on developing applications that will interface with Documaker via web services, I recommend using an IDE that supports web services and the language(s) of the applications you'll be developing. Some examples of this would be Jdeveloper, Eclipse, NetBeans, or Visual Studio. I've used all three and they are all very competent IDEs, although my personal preference is Jdeveloper for Java-based projects and Visual Studio for .NET applications. If you're not going to do application development, then you're probably ok using a web service tool like SoapUI - my personal favorite. The instructions from here will illustrate testing the web service with SoapUI but the instructions are generally similar across toolsets.
1. Download and install your IDE or toolset.
2. Open the toolset and start a new SOAP-based Project.
4. Click OK and the project is created. Expand the project and primary endpoint ("EWPSDocumentServicesSoap") and locate/expand the doPublish method. You can see that SoapUI automatically created a request based on the WSDL definition of the method. Have a look at the XML document that represents the SOAP request and notice that it follows a defined schema (envelope, header, body).
5. Replace the contents of the request with the following. Note the bold item, libraryId, which you will need to change to match your libraryId from above. Additionally you'll need to base-64 encode the extract file to send along with the request. You can easily do with with online web tools, however SoapUI will allow you to right-click at the point you wish to insert the file, and select "Insert File as Base-64 Encoded". You can then locate the file, and SoapUI will encode and insert it for you. Be sure to remove any extraneous text or spaces between the <ImportFile></ImportFile> tags!
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<doPublishRequest xsi:type="doPublishReq_Import" xmlns="http://webservices.docucorp.com/ewps/schema/2005-12-01">
<DistributionOptions xsi:type="DistributionOptions_PREDEFINED" source="PREDEFINED">
<Recipient xsi:type="RecipientDistributionItem" name="ALLRECIPIENTS"/>
<ImportFile xsi:type="ImportFile_ATTACH" location="ATTACH">INSERT BASE64 ENCODED EXTRACT DATA HERE</ImportFile>
6. Submit the request by clicking the right-facing triangle, and await your glorious results, hopefully similar to below:
On the left side you see the request and on the right side you'll see the response. Notice the <Result>Success</Result>? This means it all worked, and if you look a bit further into the <Documents> node, you can see a base-64 encoded PDF document was attached. Now all you need to do is copy the contents of the <Document> node and base-64 decode it to a file. Being a Mac user I use the OpenSSL toolkit to decode base-64 from the command line. There are also online tools and other options available to you - a quick internet search will show you many options. Just ensure that you don't decode sensitive documents or data on the open interwebs! Once decoded, you can download the file as binary (this decoder will do it automatically if you use the "decode" button). Rename the file with the appropriate extension (e.g. ".pdf") and then open with your favorite PDF reader. You've done it!
At this point you are ready to explore the other methods and operations available to you with EWPS. While the WSDL is quite useful in giving you a starting point for creating requests for each of the methods, you really must refer back to the EWPS documentation, which is quite detailed in explaining the requisite parameters for each operation. Given that the EWPS method design is abstract in nature, it can be a bit confusing at first, but stick with the documentation and the models created by SoapUI and you should come out on top. If you run into any problems, remember that most issues you'll encounter are Documaker/Docupresentment configuration-related, or MRL-related. EWPS and the web services host are usually very thin layers that do not add much to the complexity of the solution. One final pointer - make sure you work out any MRL issues before testing web services. Use the testing tool within Documaker Studio to make sure you are producing the proper output given your inputs, then move on to test the same with web services. When all else fails, you can also look for assistance at the Oracle Forum. I wish you luck in your web servicing endeavors!