Elixir Programmming Interfaces

Release 4.0.0

Elixir Technology Pte Ltd

Elixir Programmming Interfaces: Release 4.0.0Elixir Technology Pte Ltd

Published 2015Copyright © 2015 Elixir Technology Pte Ltd

All rights reserved.

Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries. Microsoft and Windows are trademarksof Microsoft Corporation.

Table of Contents1. Programming Interfaces ............................................................................................... 1

Introduction .......................................................................................................... 12. ERS Client API .......................................................................................................... 2

ERS Client Example ............................................................................................... 23. Single Sign On Sample ................................................................................................ 5

Using Ambience APIs for Single Sign On ................................................................... 54. Using WebIDE ........................................................................................................... 8

Understanding WebIDE ........................................................................................... 8Changing the Landing Page .............................................................................. 8Using CoffeeScript Files ................................................................................ 10Cleaning Up the Deployment Folder ................................................................ 11Creating a Custom Action in WebIDE .............................................................. 11Locking WebIDE .......................................................................................... 12

5. Using Elixir Tempo ................................................................................................... 14Introduction ........................................................................................................ 14Features .............................................................................................................. 15Integration .......................................................................................................... 15

6. Using Views ............................................................................................................. 18Creating Views ..................................................................................................... 18

iii

List of Figures3.1. Single Sign On Workflow .......................................................................................... 54.1. WebIDE Link .......................................................................................................... 84.2. WebIDE ................................................................................................................. 84.3. Landing Page Code Sample ........................................................................................ 94.4. WebIDE Unsaved Changes ......................................................................................... 94.5. WebIDE Preview Option ............................................................................................ 94.6. WebIDE Preview Result ............................................................................................ 94.7. WebIDE Change Landing Page ................................................................................. 104.8. build.xml Source .................................................................................................... 104.9. CoffeeScript Source ................................................................................................ 114.10. Top Level build.xml Source .................................................................................... 114.11. Top Level Action .................................................................................................. 124.12. Custom Action Button ........................................................................................... 124.13. Locking WebIDE .................................................................................................. 135.1. Round Robin Database ............................................................................................ 145.2. Consolidate Data .................................................................................................... 155.3. Tempo Integration ................................................................................................... 155.4. Tempo Authentication ............................................................................................. 165.5. Tempo Graph ......................................................................................................... 165.6. Tempo RRD Inspector ............................................................................................. 176.1. View Tool Button .................................................................................................... 186.2. View Type Button ................................................................................................... 186.3. Select Template ...................................................................................................... 196.4. View Code Editor ................................................................................................... 196.5. Edit Tab Code ........................................................................................................ 20

iv

Chapter 1Programming Interfaces

IntroductionYou can use the Ambience APIs to extract, transform and load data between Ambience and your otherapplications.

The ERS client API was originally developed for Elixir Repertoire and has been supported since version5.0. To ease the transition to Elixir Ambience, the same core functions have been made available sothat old client codes can more easily work with the latest releases and do not need to be re-developed.

Users who are creating new clients should use HTTP/REST APIs directly.

All of these API libraries require at least Java 7 to run. Ensure that the version of Java on your systemis at least 7.0 for these libraries to run.

1

Chapter 2ERS Client API

The ERS Client API allows you to write your own JVM-based programs which can call into Ambienceto render reports and generate datastores.

This API can be used to migrate data between older applications such as Elixir Report 4.0 and Ambience.

ERS Client ExampleThis example will render the standard Master-Detail RML sample into PDF as tmp/output.pdf. It will also output the number of pages rendered (showing the JobInfo API) and dumps the completeJobInfo so you can see all the information.

To run this example:

1. Make sure that Ambience is listening on its default port - 8080. If you have changed the Ambiencelistening port, then change it in the code also.

2. Create a new Java project.

3. Copy the following jars from the Ambience lib folder to the lib folder of your project (replace{version} with the appropriate version for your release). Note the third-party jar versions mayalso vary over time, so use the corresponding version found in lib.

• commons-io-2.4.jar

• commons-logging-1.1.1.jar

• elx-arch-{version}.jar

• elx-ers2-client-{version}.jar

• elx-jdom-{version}.jar

• elx-json-{version}.jar

• httpclient-4.2.1.jar

• httpcore-4.2.2.jar

• httpmime-4.2.1.jar

• logback-classic-1.0.13.jar

• logback-core-1.0.13.jar

• paranamer-2.1.jar

• scala-library-2.11.8.jar

• slf4j-api-1.7.5.jar

• typesafe-config-1.2.1.jar

2

The ERS Client is in elx-ers2-client-{version}.jar, the rest are supporting jars.

4. Create a file called JavaRender.java and enter the following code:

package demo;

import java.io.ByteArrayInputStream;import java.io.ByteArrayOutputStream;import java.io.File;import java.nio.file.Files;import java.nio.file.StandardCopyOption;

import com.elixirtech.ers2.client.ERSClient;import com.elixirtech.report2.runtime.IJobInfo;

public class JavaRender {

public final static void main(String[] args) throws Exception {ERSClient c = new ERSClient("localhost", 8080, "eno", "admin", "sa");

try {c.connect();

ByteArrayOutputStream baos = new ByteArrayOutputStream();

IJobInfo jobInfo = c.renderReport("/ElixirSamples/Report/RML/ Master-Detail Report.rml", "application/pdf", baos, new java.util.Properties());

byte[] bytes = baos.toByteArray();

File output = new File("tmp/output.pdf");

output.getParentFile().mkdirs();

Files.copy(new ByteArrayInputStream(bytes),output.toPath(), StandardCopyOption.REPLACE_EXISTING);System.out.println("Report with " + jobInfo.getLong(IJobInfo.PAGE_COUNT) + " pages rendered to tmp/output.pdf");

System.out.println(jobInfo.toString());}

finally {c.close(); } }}

3

ERS Client API

5. Save and run the file. The output should be the following:

Report with 7 pages rendered to tmp/output.pdf [byte-size=98085, elapsed-time=418, log-file=/User/admin/logs/tmp-0000000009.json, mime-type=application/pdf, page-count=7, record-count=117, result=/Temp/admin/tmp-0000000007.pdf, status-code=1]

The output PDF is in tmp/output.pdf .

You can also use the ERS Client to generate data into a DataStore.

The API is almost exactly the same as the old Repertoire client jar. The only changes are as follows:

1. The constructor supports one more parameter - the domain name. For backwards compatibility,you can leave the domain name out (use the original API args) and "eno" will be used as thedomain name by default.

2. The filesystem API is not supported:

public synchronized IFileSystem getFileSystem(String fs)

This requires duplicating the whole legacy IFileSystem, IFileObject tree which is quitedifferent in DaCapo.

The DaCapo REST API is more suitable for accessing this information, as it provides much morepowerful functionality.

3. Secure mode API:

public void setSecure(File keystore, String keystorePassword, File truststore, String truststorePassword)

This is now handled internally if the server uses https. There is no support for client certificatesin this release. Only server certificates are supported.

As long as your code does not call these functions, it should run exactly the same as before.

4

ERS Client API

Chapter 3Single Sign On Sample

Using Ambience APIs for Single Sign OnThe following example demonstrates the use of Ambience APIs to perform Single Sign On (SSO) toAmbience from a third party application.

The diagram in Figure 3.1, “Single Sign On Workflow” depicts the workflow:

Figure 3.1. Single Sign On Workflow

• A. Browser connects to user server.

• B.User server POSTS to /elx/sso/[domain]/[user] with the authenticators - usernameand password.

• C. Ambience checks that authenticator has SSOAuthentication permissions and that [user]is not admin. If these conditions are true, Ambience then returns an [sso-token].

• D. User server sends a REDIRECT message back to the browser, sending it to /elx/sso/[sso-token]. This can also include a ?ret=XXX target URL.

• E. Browser GETs /elx/sso/[sso-token]?ret=XXX.

• F. Ambience checks valid [sso-token] and adds a session cookie to the reply. It then sends areply (with the cookie) as part of a REDIRECT to XXX (the return value), or to the default landingpage if the return value is not defined.

• G. Browser visits the regular Ambience page (XXX) and is already authenticated by the cookie.

The following Java code sample demonstrates this functionality.

To run the sample, you need to compile it as a Java servlet and put it in a Java web server.

5

You can also re-implement the same logic in any other modern language, such as C#, Ruby or Python.

As a security consideration, do not use admin as the SSO Authenticator. It is only done forsimplicity in this demo.

package com.elixirtech.sample.sso;

import java.io.DataInputStream;import java.util.ArrayList;import java.util.List;

import javax.servlet.ServletException;import javax.servlet.http.HttpServlet;import javax.servlet.http.HttpServletRequest;import javax.servlet.http.HttpServletResponse;

import org.apache.http.HttpResponse;import org.apache.http.NameValuePair;import org.apache.http.StatusLine;import org.apache.http.client.entity.UrlEncodedFormEntity;import org.apache.http.client.methods.HttpPost;import org.apache.http.impl.client.DefaultHttpClient;import org.apache.http.message.BasicNameValuePair;

@SuppressWarnings("serial")public class SSODemo extends HttpServlet {

final static String url = "http://localhost:8080/elx/sso";

@Override public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, java.io.IOException {

String domain = "eno";

// Ambience user with SSOAuthentication permission String ssoAuthName = "admin"; String ssoAuthPassword = "sa";

// user we want to sign-on String username = "test";

DefaultHttpClient client = new DefaultHttpClient();

HttpPost sso = new HttpPost(url + "/" + domain + "/" + username);

List<NameValuePair> nameValuePairs = new ArrayList<NameValuePair>(2);

nameValuePairs.add(new BasicNameValuePair("username", ssoAuthName));

6

Single Sign On Sample

nameValuePairs.add(new BasicNameValuePair("password", ssoAuthPassword));

sso.setEntity(new UrlEncodedFormEntity(nameValuePairs));

sso.setHeader("ContentType", "application/x-www-form-urlencoded");

HttpResponse reply = client.execute(sso);

StatusLine status = reply.getStatusLine(); int code = status.getStatusCode();

if (code < 400) { int length = (int)reply.getEntity().getContentLength();

byte[] bytes = new byte[length];

DataInputStream is = new DataInputStream(reply.getEntity().getContent());

is.readFully(bytes); is.close();

String token = new String(bytes,"UTF-8");

System.out.println("token = " + token);

response.sendRedirect(url + "/" + token + ret(request));

return; }

else { response.sendError(code,status.getReasonPhrase()); } }

private String ret(HttpServletRequest request) { String ret = request.getParameter("ret");

if (ret==null || ret.trim().length()==0) return "";

else {

// prevent header splitting

System.out.println("set ret to " + ret);

return "?ret=" + ret.trim().replace("\r", ""). replace("\n", ""); } }}

7

Single Sign On Sample

Chapter 4Using WebIDE

Understanding WebIDEWebIDE allows you to create custom front ends for Elixir Ambience web interface from within theAmbience environment.

This option is available only if you are an administrator or a member of the WebIDE group.

Click the WebIDE link from the Ambience web interface, as shown in Figure 4.1, “WebIDE Link”.

Figure 4.1. WebIDE Link

The WebIDE looks as shown in Figure 4.2, “WebIDE”:

Figure 4.2. WebIDE

Changing the Landing PageTo change the Ambience landing page:

1. Right-click the web directory and select Add File.

2. Name it sample.html for example. Click OK.

3. Type in your code. An example is shown in Figure 4.3, “Landing Page Code Sample”. The editorhighlights code, and also syntax errors if any.

8

Figure 4.3. Landing Page Code Sample

4. Click Save to save the changes. Notice that the Save button turns pink when there are unsavedchanges, as shown in Figure 4.4, “WebIDE Unsaved Changes”

Figure 4.4. WebIDE Unsaved Changes

5. To preview your sample, right click the file and select Preview as shown in Figure 4.5, “WebIDEPreview Option”

Figure 4.5. WebIDE Preview Option

6. The preview is displayed as shown in Figure 4.6, “WebIDE Preview Result”

Figure 4.6. WebIDE Preview Result

7. Change the landing page link to the one we created with WebIDE. Click Admin > Web andchange the landing page as shown in Figure 4.7, “WebIDE Change Landing Page”

9

Using WebIDE

Figure 4.7. WebIDE Change Landing Page

8. Logout and then login back to Ambience. Your landing page will be the one that you created withWebIDE.

Using CoffeeScript FilesYou can use other files such as JavaScript and CoffeeScript files as your source. CoffeeScript files areautomatically converted to Javascript output using Ant.

The following sample demonstrates using a CofeeScript file:

1. Create a new folder for your script - say sample.

2. Right click the sample folder and select Upload File.

3. Click Choose File and select the build.xml file inside the /misc/webide/ folder. ClickOK.

4. The build file is displayed as shown in Figure 4.8, “build.xml Source”

Figure 4.8. build.xml Source

5. Add a new file called my.coffee

6. Enter the coffee script code as shown in Figure 4.9, “CoffeeScript Source”.

10

Using WebIDE

Figure 4.9. CoffeeScript Source

7. Notice that when you save the CoffeeScript code, Ant automatically compiles it into JavaScript.You can see the compilation messages in the log window at the bottom.

Cleaning Up the Deployment FolderWhen you rename a file or a folder (asset) from WebIDE, the original output is not automaticallyoverwritten, but still exists in the deployment folder.

Click Clean to clean the deployment folder and re-build all the assets.

Creating a Custom Action in WebIDETo create a custom action in WebIDE:

1. Create a build.xml file in the top level WebIDE folder, as shown in Figure 4.10, “Top Levelbuild.xml Source”.

Figure 4.10. Top Level build.xml Source

11

Using WebIDE

2. Modify build.xml to include a custom target. Note that the target name should begin withaction-. This is shown in Figure 4.11, “Top Level Action”.

Figure 4.11. Top Level Action

3. Save the code and refresh WebIDE. You will now see the custom action as a button, as shown inFigure 4.12, “Custom Action Button”. In our example, it is "Do This Now!".

Figure 4.12. Custom Action Button

Locking WebIDEOnce you are done building your custom front end, you can lock WebIDE to prevent any furtherchanges.

Click Admin > Web. Select the Lock WebIDE option as shown in Figure 4.13, “Locking WebIDE”.

12

Using WebIDE

Figure 4.13. Locking WebIDE

The webIDE is locked by default, if you are using Ambience 3.x data. If you are starting from Ambience4.0 afresh, you can choose to lock and unlock it, as required.

13

Using WebIDE

Chapter 5Using Elixir Tempo

IntroductionElixir Tempo is a database for storing fast changing time-series data. Examples of such data wherevalues change over time include:

• Sensor readings (Gauge)

• Continuous Throughput (Counter)

• Rate of Change (Derive)

• Per-read throughput (Absolute)

Data is stored in a Round Robin Database (RRD).

Figure 5.1, “Round Robin Database” shows an example of the RRD.

Figure 5.1. Round Robin Database

A field in an RRD is defined by the size of a step (here 1 minute) and the number of steps in a row(here 10).

This RRD only holds 10 minutes of data; the 11th minute will wrap-around and overwrite the firstslot.

You can consolidate data as shown in example: Figure 5.2, “Consolidate Data”:

14

Figure 5.2. Consolidate Data

FeaturesElixir Tempo is built on RRD4J and includes a stand alone web server that:

• Creates RRD files

• Accepts values (single or batch)

• Retrieves consolidated values

• Generates image graphs

IntegrationFigure 5.3, “Tempo Integration” shows an example of integrating Elixir Tempo.

Figure 5.3. Tempo Integration

Authentication can be done using one of the three methods as shown in Figure 5.4, “Tempo Authen-tication” :

15

Using Elixir Tempo

Figure 5.4. Tempo Authentication

RRD definitions are stored in .tempo files. Restart the server after you change any .tempo file.

Graph styling information is stored in .graph files, and is automatically reloaded if changed. Youdo not need to restart the server.

Figure 5.5, “Tempo Graph” shows an example of graph styles in Elixir Tempo.

Figure 5.5. Tempo Graph

The RRD inspector allows you to inspect every detail of each RRD as shown in Figure 5.6, “TempoRRD Inspector”.

16

Using Elixir Tempo

Figure 5.6. Tempo RRD Inspector

APIs for adding fields to RRDs, and for importing and exporting data from RRDs are available.

17

Using Elixir Tempo

Chapter 6Using Views

Creating ViewsThe View Tool editor allows you to create custom views for Ad Hoc Dashboard.

To create a view:

1. Click View Tool from your dashboard to open the View Tool editor. This is shown in Figure 6.1,“View Tool Button”.

Figure 6.1. View Tool Button

2. Click New View Type from the View Editor. This is shown in Figure 6.2, “View Type Button”.

Figure 6.2. View Type Button

3. Enter a name for the view and optionally select a template, if any, that closely matches the viewthat you want to create. This is shown in Figure 6.3, “Select Template”.

18

Figure 6.3. Select Template

4. The code editor opens as shown in Figure 6.2, “View Type Button”. You use HTML and JSONcode to create the views. Enter your code as appropriate.

Figure 6.4. View Code Editor

5. When you create a view from a template, the view will inherit all the tabs of the template. To editthe inherited tabs, edit the code in the View JSON tab, as shown in

19

Using Views

Figure 6.5. Edit Tab Code

6. Preview your view by clicking the Edit Preview tab.

7. Click Save to save your view code.

8. You need to publish your view to use it in Ad Hoc Dashboard. Click Publish to publish yourview.

20

Using Views