Table of Contents
Elixir Repertoire Server is accessible and manageable through the Hypertext Transport Protocol (HTTP), the kind of network connection used by a browser when accessing an http: or https: web site. We've already seen the browser interface provided by the server in Chapter 6, Web Interface, in this chapter we will look at how the server URLs can be used to interact with the tool through programs.
The HTTP protocol specifies Uniform Resource Locators, like http://www.elixirtech.com/ and operations GET, POST, PUT and DELETE. Browsers typically use GET for reading web pages and POST for submitting data, such as entry forms. Each operation has characteristics defined by the HTTP standard, so that all software that uses HTTP can follow the same rules.
HTTP provides the basic data interchange protocols, but there are a variety of mechanisms used on top of these four primitive operations. Elixir Repertoire Server uses Representational State Transfer (REST).
Explicit logon to the server, just like a user with a browser would do. API users should probably use the BASIC AUTH method of connection instead as this means the credentials are associated with each request and there will be no chance of a session timeout. A timeout would result in a redirect to the logon page, just like in the browser. Use return=SomeURL to redirect to a specific page if successful.
Calling this URL invalidates the current session. Even if you don't explicitly logout, your session will expire within a fixed interval (default 100 mins). You will need to logon or supply BASIC AUTH credentials to continue using services.
This URL supports the Single Sign-On (SSO) mechanism. The controlling server should logon to the Elixir Server using either /logon.html or BASIC AUTH and obtain a session cookie. The controlling server then redirects the user to this service, passing in the session id as a parameter. If the session id is valid, the authentication details will be cloned into a new session cookie returned directly to the user. The user may now continue to use the services without the intervention of the controlling server. If the controlling server logs off (/logout.html) providing the original session id, then any user session that was authenticated based on that session id will also be terminated.
Provides a repository browser if no mode is supplied. The browser shows a single level of the tree with the ability to navigate through the children or return to the parent folder. Selecting a file will "open" the file - that means if it is text, html or pdf it will probably be streamed to your browser. If it is an rml, ds or pml you will probably be prompted to save it. Note that this provides access to the raw files - you can't render or generate from here. Other services provide that ability. If mode is "xml" then the filesystems are returned as XML. If mode is "tree" then the entire repository tree is returned in XML. The modified attributes indicate the last modified times of the files represented as the difference, measured in milliseconds, between the file time and midnight, January 1, 1970 UTC.
Response:
<!-- output when mode=xml -->
<filesystems>
<filesystem displayName="ElixirSamples"/>
<filesystem displayName="Scheduler"/>
</filesystems>
<!-- output when mode=tree -->
<repository>
<folder name="ElixirSamples"
modified="1179946379812" access="rw">
<folder name="Dashboard"
modified="1179946365312" access="rw">
<folder name="Border Catalog"
modified="1180009266296" access="rw">
<file name="All Borders.ds"
modified="1179946257296" access="rw"/>
<file name="All Borders.rml"
modified="1179946300875" access="rw"/>
...This is a continuation of the previous service, as you navigate through the HTML, the service URL changes to mirror the repository file structure. You can use the same mode options, "xml" and "tree", which give you the corresponding output, but rooted on the repository path identified in the URL.
This is a continuation of the previous two services and illustrates the retrieval of a file. In this case, mode is not used as the file will always be returned using its original mime-type. Again, note that this will download the CustomerListing report template, it won't render the report. See the Report and Target services below for rendering options.
Update the filesystem. By entering "update" and "filesystem" for the parameters named "action" and "mode" respectively will update the filesystem specified in the java file.
Set the file contents. If the name doesn't exist, then a new file will be created, or a new folder if the pathname ends with '/'.
Delete the file or folder (along with any child files and folder).
This service provides utility options for repository management. When the path points to a file or folder and the action is "rename" and to is another filename, the file or folder will be renamed (retaining the same parent). When the path points to a filesystem and the action is "refresh", then that filesystem is refreshed. When the path points to /repository and the action is "refresh" then all filesystems are refreshed.
Tests if the server is alive and responding to requests.
Response:
200 (Ok) if the server is alive
Get the mime-types supported for rendering.
Response:
<mime-types> <mime-type name="application/pdf"/> <mime-type name="application/postscript"/> <mime-type name="application/rtf"/> ..
Get the available targets for rendering to, along with the default target properties that you can override.
Response:
<targets>
<target name="mail">
<property name="message">Your report is attached.</property>
<property name="to">elided...alice@example.com</property>
<property name="subject">Report from Elixir Server</property>
<property name="smtp.host">elixir.aspirin</property>
<property name="filename">report</property>
<property name="from">tom@example.com</property>
<property name="cc">elided...susan@example.com</property>
</target>
<target name="db">
<property name="overwrite">yes</property>
<property name="driver">elided...EmbeddedDriver</property>
<property name="table">JobOutput</property>
<property name="url">jdbc:derby:C:/Temp/elxdb/fs</property>
</target>
...Get the filesystems visible to the user.
Response:
<filesystems>
<filesystem display-name="ElixirSamples"
configuration="C:\RepertoireServer\samples"
read-only="false" type="local"/>
<filesystem display-name="Scheduler"
configuration="Scheduler"
read-only="false" type="jdbc"/>
</filesystems>Get the JDBC drivers available on the server. This service will only return available known drivers - i.e. those with known classnames that are provided by the GUI as suggestions and marked with a green icon indicating they are available.
Response:
<drivers>
<driver name="Derby Embedded"
class="org.apache.derby.jdbc.EmbeddedDriver"
url="jdbc:derby:database"/>
<driver name="JDBC/ODBC_Bridge (Sun JVM)"
class="sun.jdbc.odbc.JdbcOdbcDriver"
url="jdbc:odbc:Sample"/>
<driver name="MySQL (com.mysql)"
class="com.mysql.jdbc.Driver"
url="jdbc:mysql://<host>/dbname"/>
<driver name="MySQL (mm.mysql)"
class="org.gjt.mm.mysql.Driver"
url="jdbc:mysql://<host>/dbname"/>
</drivers>Gets the parameters for reports, datasources, dashboards and jobs
Response:
<!-- in this case there aren't any -->
<parameters report="/ElixirSamples/Report/CustomerListing.rml"/>
<!-- in this case there are -->
<parameters report="/ElixirSamples/Report/NewsToday.rml">
<parameter>
<key>Language</key>
<type>choice(Mixed,Korean,Tamil,Arabic)</type>
<value>Mixed</value>
</parameter>
</parameters>Get the clickable repository tree (breadcrumbs flat HTML) that will open chosen files. This is different from the /repository URL in that it will launch the right engine to handle the Elixir file types - for example selecting a report will render it, selecting a datasource will generate the data and selecting a dashboard will open it for viewing. This is the URL that the shows below the menu bar when you log on to the Web Interface.
Render the report into CSV, DocX, Excel, Glint, IML, PDF, PPTX and XML mime-types. The report will be streamed back to the client. Because this is a simple GET method, you can try this directly from your browser or embed a link into any web page. The data will be streamed back to your browser, which will show it directly in the specified mime-type. For "elx.disposition", it is specifically for the PDF mime-type, and there are only two options available. They are "inline" and "attachment". For "inline", the PDF will open in the window. As for "attachment", the user will be prompted to open or save the file. The POST version should be used if sending more than about 4kB of parameters.
Returns the dashboard at the specified card with parameters entered if any. The options available for mode are "init" and "parameters".
Generate the data into the requested mime-type. The available mime-types are: application/vnd.ms-excel (Excel), text/xml (XML) and text/csv (CSV). If you choose XML mode, you may also pass an xslt parameter which names a stylesheet in the repository (full repository url required) which will be used to transform the XML while generating. In all cases, the resulting data will be streamed back to the client. The POST version should be used if sending more than about 4kB of parameters.
By entering "time" for the "mode" parameter, total number of records and elapsed time will be displayed.
Generate the data from the Composite DataSource into the named datastore. Note that this service is a POST, unlike the GET version above, because the server is modified by this operation - the data is written onto the server instead of being streamed back to the client. You will recall from the earlier discussion that POST operations may have side-effects - for example the datastore may append records to a JDBC database. You wouldn't want the same records appended twice! The GET version above is stateless, because the data is returned to the user - the server state doesn't change.
Returns the specified page of the glint, or the first page if no page parameter is supplied. If the mode value is "page-count" then a plain text number is returned indicating the number of pages available.
Renders a report to the named target (TargetName). This service requires an XML structure to be sent as the request, detailing the specific report along with any rendering and target parameters that are required. You should always provide the mime-type target parameter unless the target is a PrintTarget. Other target parameters can be identified from the /query/targets service.
Request:
<request report="/ElixirSamples/Report/CustomerListing.rml">
<report-parameters>
<param name="paramName">value</param>
</report-parameters>
<render-details> <!-- optional -->
</render-details>
<target-parameters>
<param name="mime-type">application/pdf</param>
</target-parameters>
</request>(Admin only)
Lists all users and their groups
Response:
<users>
<user id="1" name="admin" enabled="yes">
<group id="1" name="admin"/>
</user>
<user id="2" name="scheduler" enabled="yes">
<group id="3" name="scheduler"/>
</user>
<user id="3" name="user" enabled="yes">
</user>
</users>(Admin only)
Lists a named user and their groups
Response:
<user id="1" name="admin" enabled="yes"> <group id="1" name="admin"/> </user>
(Admin only)
Adds or edits user bill. When creating, don't specify the name attribute, because it is part of the URL. The enabled state defaults to true if not specified. You can specify a name while editing to rename the user. When editing, leaving out the name, password or enabled attributes indicates that those values are unchanged. Similarly, leaving out the group children indicates that the groups remain unchanged. If you want to remove all groups, you should specify a single child group with no id (this overrides the no groups means no change inference).
Request:
<user name="bill" password="XXX" enabled="yes"> <group id="1"> <group id="2"> </user>
(Admin only)
Lists all groups and their users
Response:
<groups> <group id="2" name="*"/> <group id="1" name="admin"> <user id="1" name="admin"/> </group> <group id="3" name="scheduler"> <user id="2" name="scheduler"/> </group> </groups>
(Admin only)
Lists the group called scheduler and its users
Response:
<group id="3" name="scheduler"> <user id="2" name="scheduler"/> </group>
(Admin only)
Adds or edits the group called testing. When creating, don't specify the name attribute as it is part of the URL. You can specify a name while editing to rename the group. Leaving out the user children indicates that the users remain unchanged. If you want to remove all users from the group, you should specify a single child user with no id (this overrides the no users means no change inference).
Request:
<group name="testing"> <user id="1"> <user id="2"> </group>