Developing using the API

API Developers Kit

The API Developers Kit will enable custom programs to be written and executed embedded into the ROB-EX client. The program or script written interacts with the ROB-EX client through a Java based API (Application Programming Interface). The API will typically be used in situations where a customer requires functionality not available out of the box in ROB-EX. Typical API use cases are

• a new column in e.g. the order list or an HTML report is required with special data or special formatting
• extra main menus with your own custom developed functionality and UI inside. E.g. a special UI is needed for creating new orders
• customizing the pop-up text shown when the mouse rests on top of a Gantt bar
• custom developed macro items that can be used alongside other build in macro items
• a special import or export interface from/to an external system (e.g. Excel) is needed

The API can be used in two different ways

1. By writing a User Plugin in the Java programming language. The end result with this approach is a jar file called “user.jar” which must be placed in the \plugins\user directory.
   Use this approach for larger and more advanced projects.
2. By writing a script in the Groovy programming language. The end result with this approach is a script file that can be called via the standard ROB-EX Macro Command ExecuteScript or the script file can be placed in <sch_client_dir>\custom\scripts\beforePlugins for automatic loading and execution during startup of the client.
   The scripting language used is Groovy – a powerful and object oriented scripting language, that in addition to full Java Language support, also has some built in power scripting options making it easy and fast to create scripts.
   
   Use this approach for simple and well defined tasks where the functionality can be encapsulated into a single macro command.

In either case the program created will be interacting with the ROB-EX client using the same ROB-EX API classes and methods.

To learn more about scripting read the separate Guide to ROB-EX Scripting. The remainder of this document explains how to get started writing a User Plugin in the Java programming language.

Some experience with programming in Java or a similar language like C# is recommended in order to use the API

Getting started writing a User Plugin

Requirements

In order to create and compile a User Plugin you need the following:

• A Java 1.8.0 compiler. The easiet way to get this is to use the Eclipse IDE development enviroment. Read the separate chapter Setting up the Eclipse Java IDE on how to download, install and configure the Eclipse environment.
• A ROB-EX client installation v7.2. To install follow the standard installation options.

The ROB-EX API Developers Kit.

This is a quick start guide on how to activate the API Developers Kit and check the content it contains:

Make sure you have a valid license for the API Developers Kit. From the ROB-EX client check the menu “Help->Register” for a list of licensed modules

With a valid API Developers Kit license, in the ROB-EX client select the menu item “Help->API Developers Kit”. The very first time this menu item is being activated wait app. 10 seconds for the API Developers Kit to be installed. If the installation fails make sure the user running the ROB-EX Client is having write permissions to the client installation directory (e.g. \planner). On Windows 7 and newer it may be necessary to start ROB-EX with the “Run as administrator” option. If you are able to manually create a new file or directory in <sch_dir>\planner, then you have correct write permissions.

After a successful installation of the API Developers Kit, and on all subsequent calls to menu “Help->API Developers Kit”, the API documentation in Javadoc format is launched in your default web browser.
To verify a successful installation browse the “docs” folder of the ROB-EX Client installation directory. I.e. if ROB-EX Client is installed in c:\programs\ROB-EX\planner, then after extraction you should have the directory c:\programs\ROB-EX\planner\docs\user. Besides the API documentation, the API Developers Kit also contains a simple example implementation of a User Plugin programmed in the Java programming language – for further detail read the following chapters.

It is recommended to install a Java development tool, e.g. the Eclipse distribution is well suited and can be downloaded free of charge. Read the separate chapter Setting up the Eclipse Java IDE on how to download, install and configure the Eclipse environment.

The following explains step-by-step how to get started using the API

Overview

The custom specific code must be written in the Java language and must be located in a separate user plugin. Once the custom code has been written and tested it is shipped to customers in a jar file of the name user.jar. The file user.jar must be placed in the location \plugins\user\user.jar ( is the root directory of the ROB-EX client installation, e.g. “c:\program files\ROB-EX\planner”).

Content of the ROB-EX API Developers Kit

After installation of the ROB-EX API Developers Kit (see requirements section) you should in the beginning focus on the following files:

The UserPlugin.java example

Note that a user plugin must implement the gantt.plugin.Plugin interface. This means providing implementation of the three methods init(), getVersionInfo() and destroy():

public class UserPlugin implements Plugin {
  public boolean init(PluginAPI api) {
    return true;
  }

  public String getVersionInfo() {
    return "1.000";
  }

  public void destroy(PluginAPI api) {
  }
}

When ROB-EX starts up it will automatically search for the class user.UserPlugin provided either in user.jar or during development on the current class path. If this class exists it will be instantiated and the init() method will be called allowing the plugin to perform initialization (e.g. adding extra menu items etc.). Note that the init() method supplies as argument a reference to the gantt.plugin.PluginAPI class. The implementation should store this reference internally within the class, since the PluginAPI class is the central class used when querying the ROB-EX data model and executing ROB-EX business methods.

Start out focusing on the PluginAPI.getWindowAPI() and PluginAPI.getBaseModelAPI() methods, since the interfaces returned by these methods will give access to the most used features.

Running ROB-EX from the command line or from a development environment

During development it may be helpful to bypass the “ROB-EX Gantt.exe” program and launch ROB-EX directly from within your programming IDE. To run ROB-EX directly from a command line selecting the en_IE language you would enter:

java -Xms128M -Xmx1024M -Dsun.java2d.noddraw=true -DApp_language=en -DApp_country=IE -jar lib\gantt.jar 

To launch from a Java IDE you would specify the parameters

-Xms128M -Xmx1024M -Dsun.java2d.noddraw=true -DRobex_language=en -DRobex_country=IE

as start-up parameters, leaving out the rest.