How to interact with endpoints (PDI jobs or transformations)

pentaho-logoThis post is part of the Pentaho Sparkl application builder tutorial. As my habitude the tutorial is described as a “step by step” list of tasks and commands, in my opinion more useful and clear to understand how to do and make it work.

The tutorial is developed using a Linux Ubuntu 12.04 LTS operating system, but even on a different platform the description should be valid and help to understand how to reach the goal.

Prerequisites

This tutorial assumes that Pentaho Business Analytics Platform 5 is correctly installed into your system together with Sparkl. A basic Pentaho application should be created with it with a dashboard and a Kettle endpoint.

Introduction

A Pentaho application created with Sparkl is a set of dashboards developed with CDE of the Ctools, and Pentaho Data Integration – or Kettle – endpoints developed as PDI jobs or transformations with some specific characteristics. Of course those two subsets of the application will be able to interact to develop exactly what you expect. In this tutorial we are going to see how to invoke the execution of a Kettle endpoint using a button in a dashboard.

Call a Kettle endpoint using a button in a dashboard

First of all, access to Pentaho User Console as administrator (otherwise you won’t be able to access to Sparkl desktop) and access to Sparkl desktop.

Sparkl - Menu with application2

ATTENTION: Do not access from here to the MyFisrtApplication because this link is to the content of the application and not the administration panel.

Once the Sparkl desktop will be visible, identify your application (in our case ‘MyFirstApplication’) and access to edit it by clicking on the ‘edit’ icon. Now that you are in the administration panel of the application, click on the ‘Elements’ tab to manage the dashboards and Kettle endpoints. Take a look at ‘myfirstdashboard’ and access to edit it using the icon on the right of the line.

By clicking the edit icon, another window is going to be opened with an administration panel. Starting from now, editing a dashboard is exactly the same as develop your own CDE dashboard. We assume that in the dashboard a button has been developed. If not, please follow this tutorial.

Now that we are in the dashboard management panel, let’s go ahead adding some source code. First of all we need to include a javascript package, useful to manage the run of the endpoints. To reach that goal follow what is described below:

  • Click on ‘Layout panel’ using the icon in the upper right corner (probably you are already there).
  • Add a new resource by pressing the ‘add resource’ icon.
  • Once the button is pressed, a message box is going to ask you the resource type (set it to ‘Javascript’ and ‘Code snippet’).
  • Select on the appearing new row and click on the three dots of the ‘Resource code’ of the right panel.
  • Evaluate the Resource code property with the code below.
var myApplication = {};

(function(myself) {
  myself.runEndpoint = function (pluginId, endpoint, opts) {

    if (!pluginId && !endpoint) {
      Dashboards.log('PluginId or endpointName not defined.');
      return false
    }

    var _opts = {
      success: function () {
        Dashboards.log(pluginId + ': ' + endpoint + ' ran successfully.')
      },
      error: function (){
        Dashboards.log(pluginId + ': error running ' + endpoint + '.')
      },
      params: {},
      systemParams: {},
      type: 'POST',
      dataType: 'json'
    }
    var opts = $.extend( {}, _opts, opts);
    var url = Dashboards.getWebAppPath() + '/plugin/' + pluginId + '/api/' + endpoint;
    function successHandler (json) {
      if (json && json.result == false) {
        opts.error.apply(this, arguments);
      } else {
        opts.success.apply( this, arguments );
      }
    }
    function errorHandler () {
      opts.error.apply(this, arguments);
    }

    if (endpoint != 'renderer/refresh' ) {
      var ajaxOpts = {
        url: url,
        async: true,
        type: opts.type,
        dataType: opts.dataType,
        success: successHandler,
        error: errorHandler,
        data: {}
      }
    } else {
      var ajaxOpts = {
        url: url,
        async: true,
        type: 'GET',
        dataType: opts.dataType,
        success: successHandler,
        error: errorHandler,
        data: {}
      }
    }
    _.each( opts.params , function ( value , key) {
      ajaxOpts.data['param' + key] = value;
    });

    _.each(opts.systemParams , function (value , key) {
      ajaxOpts.data[key] = value;
    });
    $.ajax(ajaxOpts)
  }
})(myApplication);

ATTENTION: This source code is part of the file you can study and copy in ‘<biserver>/pentaho-solution/system/sparkl/static/custom/js/sparkl.js’. Please, refer to it for further details… and many thank to WebDetails guys for sharing it as open code. 😉

The source code you see here is the key point of the task. The declared function ‘runEndpoint’ manages an ajax call to the endpoint with two callback functions, very useful to manage the error event and success event. But let’s go ahead…

Now that we have all it’s necessary to invoke a Kettle endpoint suing a javascript function, let’s make the button of the dashboard interactive with the end point. To reach that goal, follow what is described below:

  • Click on ‘Components panel’ using the icon in the upper right corner.
  • In the middle panel, expand the group and select the button component.
  • In the right panel, click on the three dots of the Expression property.
  • In the text form put the code below:
function() {
  myApplication.runEndpoint(
    'myApplication', // Plugin identifier.
    'myFirstEndpoint', // Put your endpoint name here!
    {
      success: function() { alert("Succeed!"); },
      error: function() { alert("Fail!"); }
    }
  );
}
  • Click ok and save the dashboard.

As you can see, the ‘runEndpoint’ call is quite easy to understand for the one of you that know javascript, but I would like to submit to your attention the success and fail callback functions. Because those are very important in the dashboard to manage a correct execution of the Kettle endpoint or some kind of error in its execution. In this case, an alert message box with a “succeed!” message inside is shown in case of success and an alert message box with a “fail!” message inside is shown in case of failure.

Did you remember to replace the ‘myFirstEndpoint’ string with the name of your Kettle endpoint? It will be the very first thing I’ll ask you when you will write me to ask for some kind of support. 😉

Now it’s time to see a first result. Again in the application dashboard you see the ‘myfirstdashboard’ with an ‘View dashboard’ icon on the right. By clicking it, you will obtain the preview of your dashboard where you can see the button. By clicking it, a message box will be shown containing the result of your call. In the example below you can see a case of success.

sparkl - Endpoint call

Call a Kettle endpoint with parameters

Now that we know how to call a Kettle endpoint using a button, it’s time to dive deep in a more complicated use case. In particular, how to pass parameters to a Kettle endpoint; because in the real world a Kettle job/transformation needs parameters.

To reach that goal, everything will seems to be easier using the ‘runEndpoint’ function. In particular you have simply to invoke it in the way describe below.

function() {
  myApplication.runEndpoint(
    'myApplication', // Plugin identifier.
    'myFirstEndpoint', // Put your endpoint name here!
    {
      params: {
        param1: 'val1', // Put here your params.
        param2: 'val2',
        ...
      },
      success: function() { alert("Succeed!"); }, 
      error: function() { alert("Fail!"); }
    }
  ); 
}

Conclusion

In this tutorial we have seen how to call a Kettle endpoint from a button of your dashboards on a Sparkl application and some technical details about it. To get more tutorials on that topic, you can see the menu list in this page.

5 thoughts on “How to interact with endpoints (PDI jobs or transformations)

  1. Great blog series – thanks!

    However this one seems out of date now. The URL for an endpoint no longer has /api/ in it, and you just go to /content/APP/ENDPOINTNAME like so:

    Dashboards.getWebAppPath() + ‘/content/’ + pluginId + ‘/’ + endpoint;

    Also for some reason this code always reports failure, despite it working. So there’s something else funny there – I’ve not had chance to look at it yet!

  2. Francesco Corti

    Hi Dan,
    Hi Pedro,
    It’s a pleasure to have your (appreciated) comment into my blog! 🙂
    I hope to have enough time to try it again and develop an updated version of the post. Let’s stay tuned…

Leave a Reply

Your email address will not be published. Required fields are marked *

Time limit is exhausted. Please reload CAPTCHA.