Introduction

This is a JSON file describing the plugin. Here's a snippet.

{  
  "name" : "Email Plugin",  
  "label" : "Email",  

  "serverSideIntents" : [  
    {...}  
  ],  
  "clientSideIntents" : [  
    {...}  
  ],  
  "variables" : [  
    {...}  
  ]  
}

• name

  Uniquely identifies a plugin.

• label

  Display friendly label for a plugin, may be used in the future to group multiple intents together as a menu.

• serverSideIntents

  A list of server side action descriptors.

• clientSideIntents

  A list of client side action descriptors

• variables

  A list of variables declared by the plugin. These variables are available for all intents declared by this plugin

Variables are values that could be configured at deployment time, and used within the intents. For example, in the Send Email action, the mail server and authentication properties can be configured using variables. Variable definition looks like this:

{  
    ...  

    "variables": [  
        {  
            "name": "mail.smtp.host",  
            "value": "smtp.gmail.com",  
            "type": "STRING"  
        },  
        {  
            "name": "mail.smtp.port",  
            "value": 587,  
            "type": "INT"  
        },  
        {  
            "name": "mail.smtp.starttls.enable",  
            "value": true,  
            "type": "BOOLEAN"  
        },  
        {  
            "name": "cc",  
            "label": "Cc",  
            "description": "Comma separated list of recipients to send a copy to",  
            "required": true,  
            "userEditable": true  
        }  
        ...  
    ]  
    ...  
}

• name

  An internal name for the variable. Intents use the name to retrieve a variable value.

• value

  The default value of the variable. The value can be parameterized - for example, ${resourcePath}, ${userName}. See below for further details.

• type

  The data-type of the variable. The allowed types are : LONG, DOUBLE, STRING, PASSWORD, BOOLEAN. Date values can be modelled as UNIX timestamp in milliseconds (LONG).

• userEditable

  Marking variables as user-editable offers them to be changed/populated at runtime when invoking actions from UI.

• label

  This is a user-friendly label on the variable for user-editable variables.

• description

  This is help text that will be shown to end-users for user editable variables.

• required

  Adds a validation for non-empty values at runtime for user editable variables.

Variables can be used to retrieve special runtime variables by using the ${xxx} pattern in the values. For example, consider the following:

{  
    "name": "myResourceId",  
    "value": "${resourceKey}",  
    "type": "STRING"  
}

At runtime, the value of the resource id in context will be substituted and will be available as the value of the variable myResourceId in the action implementation class.

These dollar $variables can be used both in server-side as well as client-side actions. For example, a client-side action may expose specify a open URL template of the form

"url_template: http://54.67.46.235/create/dataset?uri=${resourcePath}"

which for instance, might resolve to:

http://54.67.46.235/create/dataset?uri=/user/jdoe/data/file.csv

The following dollar variables are available:

• User properties

  • ${userName}: Username of the currently logged in user
  • (could be expanded to user.email etc., in the future)

• Resource properties

  • ${resourceKey}: Resource ID of the selected resource
  • ${resourcePath}: /user/jdoe/file.csv
  • ${resourceName}: file.csv

• Data source properties

  (For the resource in context, the source to which the resource belongs)

  • ${sourceKey}: Source id
  • ${sourceName}: "MyHDFS"
  • ${sourcePath}: Source path for the data source, for example, /data
  • ${sourceType}: source_type_hdfs | source_type_hive | source_type_jdbc
  • ${sourceUrl}: hdfs://namenode:8020/

Server-side actions are implemented in Java. The ldc-plugin-api should be added as a dependency, which contains public classes and API that can be used to implement custom plugin actions.

The main interface to implement is the IntentHandler:

public interface IntentHandler { 
    IntentResponse handleIntent(Intent intent);  
}

The Intent parameter contains the context data:

public interface Intent {
    Map<String, Variable> getData();
    Logger getLogger();  
}

• The getData() method returns a map of variables. Wherever parameterized, the variables values are substituted.
• The getLogger() method returns a slf4j-like logger interface which can and should be used to log plugin events.

public interface Logger {
    void debug(String message, Throwable throwable);
    void info(String message, Throwable throwable);
    void warn(String message, Throwable throwable);
    void error(String message, Throwable throwable);  

    void debug(String message, Object... args);
    void info(String message, Object... args);
    void warn(String message, Object... args);
    void error(String message, Object... args);
}

The handleIntent method returns an IntentResponse:

public interface IntentResponse {
    String getMessage();
    Status getStatus();

    enum Status {SUCCESS, FAILURE}  
}

The IntentResponse is used to display a custom message generated by the plugin to the end user.

For long running tasks, implementations may use the PluginUtilities.invokeAsync() method and supply a runnable.

PluginUtilities.invokeAsync (new Runnable(){
    @Override public void run(){
        try {
            performLongRunningTaskHere();
        } catch (IOException e) {
            intent.getLogger().error("", e);
        }
    }

Passwords occurring in the plugin descriptor json can be encrypted using the standard Lumada Data Catalog encryption utility and used in variables of type PASSWORD:

"variables": [  
     {  
      "name": "password",  
      "value": "enc(rO0ABXcIAAABXIB2RwdzcgAZamF2YXguY3J5cHRvLlNlYWxlZE9iamVjdD42PabDt1RwAgAEWwANZW5jb2RlZFBhcmFtc3QAAltCWwAQZW5jcnlwdGVkQ29udGVudHEAfgABTAAJcGFyYW1zQWxndAASTGphdmEvbGFuZy9TdHJpbmc7TAAHc2VhbEFsZ3EAfgACeHBwdXIAAltCrPMX+AYIVOACAAB4cAAAACCHi3NzySa5e08Ip92BJbuAIuhJ7yH8Gy5Y5wFfwzfXPHB0ABRBRVMvRUNCL1BLQ1M1UGFAZGluZw==)",  
      "type": "PASSWORD"  
    }  
  ]