ERES provides SOAP service for communication with other applications. You can run and export a report or a chart by sending an XML SOAP request message to the ERES SOAP service. In this chapter, you will find instructions for writing your own application that will be able to communicate with ERES using SOAP.
The SOAP service that runs a report/chart is called LookupService. The functionality of LookupService is similar to the LookupServlet, which is used in the Report/Image URLs. The main difference is that the request and response are both in XML format and are being transported in an envelope over HTTP/SMTP.
LookupService takes a SOAP envelope, processes the request, generates report/chart and exports it to the requested format. It returns the result in a SOAP envelope back to the client. It uses MIME attachments for sending data files and receiving the generated reports/charts.
The Lookup Service is running at this URL by default:
http://machine:port/ERES_CONTEXT/services/LookupService
(Please, replace machine, port, and ERES_CONTEXT by actual values used in your system. If you used the default setup with Tomcat, the port number is 8080 and ERES_CONTEXT is ERES.)
The name of the SOAP method to use is lookup.
Before you can use the LookupService, the member host and member port number need to be set up. They can be added in the → → . The member host is usually the machine ERES is running on and the member port number is usually the port ERES is running on.
LookupService can be started automatically when ERES Server is started. To do this, you need to add the -deploySOAPService parameter to the ServerCommands= line of the QB.properties (in the ERES/WEB-INF/classes directory). LookupService will be deployed the next time you start the ERES Server.
The request message is a standard XML SOAP message. It looks like this:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<!—-Here belongs the Header elements (see below)--> </s:Header>
<s:Body>
<lookup xmlns:er="LookupService">
<!-—Here belongs the Body elements (see below)--> </lookup> </s:Body>
</s:Envelope>
After you create the SOAP message, you have to send it to the LookupService and wait for the response.
Possible header elements are listed in this table.
| Element name | Required | Content description |
|---|---|---|
| UserName | Yes | Username used to log in to ERES Server |
| Password | Yes | Password used to log in to ERES Server |
| URLType | Yes | FORREPORT - generate report or FORCHART - generate chart |
| ReturnOption | Yes | Return Option: CONTENT - Return the exported file in a byte array. Dynamic export is used. Only the root report is returned, drill-down is generated using DrilldownReportServlet. For DHTML export, chart is generated using RPTImageGeneratorServlet. LINK - Store the exported file in ERES repository and return a link in the envelope. The user can use the link to retrieve the exported file later. EMAIL - Notify the user with an email after the report is exported. This asynchronous approach is especially useful when generating large reports that takes a long time. Can return the result as link, attachment, or HTML. |
| TemplateType | Only if the template is passed in attachment | Type of the template stored in attachment: PAK, RPT or XML for reports; CHT, TPL or XML for charts |
| XMLDataType | Only if the XML data are passed in attachment | Type of the XML data stored in attachment: QUADBASE - XML data in Quadbase format, DTD - XML data with DTD schema, XSD - XML data with XML Schema |
Possible body elements are listed in this table.
| Element name | Required | Content description |
|---|---|---|
| Refresh | No | Refresh report/chart data before export: true or false |
| TemplatePath | Only if the template is not passed in attachment | Path to the report/chart template file (on server side). The path can be either absolute or relative to the ERES installation directory or it can be an URL. |
| QueryParamName | No | Name of a query parameter. See Section 7.8.1.1.5 - Passing Query Parameters for details about passing parameters. |
| QueryParamSize | No | Number of values for multi-value parameters. On for single-value parameters. See Section 7.8.1.1.5 - Passing Query Parameters for details about passing parameters. |
| QueryParamValue | No | Single parameter value. For multi-value parameters, use this element several times. See Section 7.8.1.1.5 - Passing Query Parameters for details about passing parameters. |
| EmailFromAddress | Only if the EMAIL Return Option is used. | From address used in the email. |
| EmailToAddress | Only if the EMAIL Return Option is used. | To address used in the email. This element can be used several times to specify more recipients. |
| EmailSubject | Only if the EMAIL Return Option is used. | Subject of the email. |
| EmailBodyText | Only if the EMAIL Return Option is used and Email type is 0 or 1. | Body of the email. |
| EmailType | Only if the EMAIL Return Option is used. |
Type of the email: 0 - report/chart is sent as email attachment 1 - link to report/chart is append to the end of the email body 2 - the report is sent as the HTML email body. Only available for reports and (D)HTML export formats |
| MultiPageExport | No | Is multiPage export used? true or false. Default is false. This option is useful only for reports. |
| NewDHTML | No | Is new DHTML rendering used? true or false. Default is true. This option is useful for DHTML export format only. The new DHTML is displayed correctly in FireFox and IE 6.0 and above. If you want to use IE 5.5 or lower, set it to false. |
| OptimizeMemory | No | Is optimized memory used? true or false. Default is false. This option is useful only for reports. |
| ExportFormat | Yes | Export format: For reports: DHTML, PDF, RTF, TXT, CSV, XLS, XLSX, or RPT For charts: GIF, JPEG, JPG, PNG, PDF, SVG, BMP, or CHT |
| IsGIFBGTransparent | No | Is GIF background transparent? true or false. Default is false. This option is useful for GIF display type only. |
All the necessary files are sent with SOAP message as MIME attachments. The attachments are sent as byte arrays. The following attachments can be sent:
File with report/chart template. Only single file is allowed. If you want to send report with subreport, chart, image or drilldown, use PAK template. If this attachment is added, the TemplateType must be specified. This attachment must be the first attachment of the SOAP message.
File used as XML datasource. This can be used only for the reports with XML datasource. If this attachment is added, the XMLDataType must be specified. This attachment must be the second attachment after the template file. This attachment must be the first if the template file attachment is not used. If the XMLDataType is DTD or XSD, there must be another attachment added just after this one. This attachment must contain the DTD or XML Schema of the XML.
File with DTD or XML Schema of the XML data file. This attachment must be added, if the XMLDataType is DTD or XSD. This attachment is always the last attachment of the SOAP message and can be used only together with the XML data file attachment.
Here you can see an example of the request message. This message will generate a report from the template located at c:/ERES/ReportFiles/report.rpt. It then exports it to DHTML to the default ERES repository and returns a link, which allows accessing the exported report.
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<UserName>admin</UserName>
<Password>admin</Password>
<URLType>FORREPORT</URLType>
<ReturnOption>LINK</ReturnOption> </s:Header>
<s:Body>
<lookup xmlns:er="LookupService">
<TemplatePath>c:/ERES/ReportFiles/report.rpt</TemplatePath>
<ExportFormat>DHTML</ExportFormat> </lookup> </s:Body>
</s:Envelope>
If your report/chart is parameterized you may want to enter parameter values. This can be done in a similar way as in the Report/Image URL. The QueryParamName, QueryParamSize and QueryParamValue elements are used to specify parameters. All three elements must be used for each parameter in this exact order: QueryParamName followed by QueryParamSize followed by one or more QueryParamValue. This can be followed by other parameter specification. If some parameter value is specified, the default parameter value is used.
The example below shows how to set parameters for a report with a single value parameter (Category) and a multi-value parameter (Products).
<QueryParamName>Category</QueryParamName>
<QueryParamSize>1</QueryParamSize>
<QueryParamValue>Arm Chairs</QueryParamValue>
<QueryParamName>Products</QueryParamName>
<QueryParamSize>3</QueryParamSize>
<QueryParamValue>Cula Chair</QueryParamValue>
<QueryParamValue>Marduk Chair</QueryParamValue>
<QueryParamValue>Nisaba Chair</QueryParamValue>
The message, you will get back from the LookupService is again a standard XML SOAP message. The response message has no header and looks like this:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<LookupResponse xmlns="">
<!-—Here is a message from the LookupService (see below)--> </LookupResponse> </soapenv:Body>
</soapenv:Envelope>
You can get one of the following responses from the LookupService:
these messages begin with Info:. They contain various information for the user. For example, you will get this message if you use the EMAIL Return option. In this case, the message says that the report is processed and will be emailed to the specified user.
these messages begin with Error:. You will get this kind of message if there were some errors. You should always check the response message if it starts with Error. If error occurs, the attachments may be empty.
this message is always CONTENT. It says that an exported report/chart can be found in attachment (see the next chapter).
if the message is not anything from above, it is link to the generated report (when the LINK ReturnOption is used).
if the response message does not contain the LookupResponse element at all, it is because of a SOAP fault. In this case, you will find the Fault element instead of the LookupResponse in the message. This element contains description of the SOAP fault.
The response message can contain only one attachment- the exported report or chart. This is in case you have used the CONTENT ReturnOption and you have gotten the CONTENT response message. Then you can find the attachment, which is containing the file as byte array.
Only single file is supported as attachment. Therefore, it is not possible to export to multi-page (D)HTML using the CONTENT ReturnOption.
You can find an example SOAP client application in help/example/soap/SimpleSOAPMessenger.java. The example is using Apache AXIS as its SOAP engine.
SimpleSOAPMessenger is a convenient class for user to easily send SOAP request and to receive response from ERES LookupService. The most important method in this class is SendAndRecieve(). It first creates a SOAP Request Message (as described in Section 7.8.1.1 - Request Message). It then sends the message to the LookupService on the server (at the specified URL). Finally, it will receive a response message, process it and return a byte array to the user. The byte array can be a string containing error or link or actual content of the exported report/chart depending on the ReturnOption.
User can set the request message parameters using the following methods:
public void setURL(String s)- set the LookupService URL public void setUsername(String s) public void setPassword(String s) public void setURLType(String s) public void setTemplatePath(String s) public void setTemplateType(String s) public void setTemplateByteArray(byte[] b) public void setReturnOption(String s) public void setXmlDataType(String s) public void setXmlData(byte[] data) public void setDTDData(byte[] data) public void setRefresh(boolean b) public void setMultiPageExport(boolean b) public void setNewDHTML(boolean b) public void setOptimizeMemory(boolean b) public void setExportFormat(String s) public void addQueryParamNameAndValue(String name, Object[]value) public void setDisplayType(String s) public void setGIFBGTransparent(boolean b) public void setChartPath(String s) public void setEmailFromAddress(String s) public void setEmailToAddresses(String[] s) public void setEmailSubject(String s) public void setEmailBodyText(String s) public void setEmailType(int type)
Here is an example of using the SimpleSOAPMessenger class.
public class TestLookupService{ public static void main(java.lang.String[] args) { SimpleSOAPMessenger ssm = new SimpleSOAPMessenger(); ssm.setURL("http://localhost:8080/ERES/services/LookupService"); ssm.setUsername("admin"); ssm.setPassword("admin"); ssm.setURLType("FORREPORT"); ssm.setTemplatePath("help/quickstart/templates/QuickStart51.rpt"); ssm.setExportFormat("DHTML"); ssm.setReturnOption("LINK"); try { byte[] byteArray = ssm.SendAndRecieve(); String link = new String(byteArray); System.out.println("Generated report is at : "+link); }catch (Exception ex) { ex.printStackTrace(); } } }