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. Also this approach must be chosen in case the custom specific code needs to sign up for events from the API.

  1. By writing a script in 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 “\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 compiler (JDK) 1.6.0 or newer. We recommend using the newest JDK Standard Edition available (as of writing JDK 1.7). The latest JDK can be downloaded free of charge from
. To install follow the standard installation options for Java SE JDK.
A ROB-EX client installation v4.1 or newer. 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 \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.

A text editor for editing Java files. It can be recommended to install a Java development tool, e.g. the Eclipse distribution is well suited and can be downloaded free of charge from
. To install download “Eclipse IDE for Java Developers” and follow the standard installation options. Also see the separate chapter Setting up the Eclipse Java IDE on how to download, install and configure the Eclipse environment.

The following Exercise 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:

Filename
Description

\docs\user\api\index.html
This file can be opened in an HTML browser and provides detailed package, class and method level description of the programming API. It is recommended to initially focus on the package gantt.plugin.

\docs\user\build.xml
Ant script used when compiling and packaging the user plugin. To use this script the Ant program is required (standard part of the Eclipse development environment).

\docs\user\make.bat
A simple command line script basically containing the same functionality as the build.xml file. Use this command line utility if you do not have access to the Eclipse development environment. Using this command line script only requires the Java JDK to be installed.
To compile and immediately build the user.jar file in the correct location simply double click on make.bat

\docs\user\user\UserPlugin.java
Example implementation of a custom user plugin – see details below.

\docs\user\userproperties.properties
\docs\user\userproperties_da_DK.properties
Translation files for the different languages you plan support. Example files are provided for default language (typical English) and Danish.

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.

Feedback

Was this helpful?

Yes No
You indicated this topic was not helpful to you ...
Could you please leave a comment telling us why? Thank you!
Thanks for your feedback.

Post your comment on this topic.

Post Comment