api-tool.jar

You can use the api-tool.jar tool to run scripts and raise events from systems for which there are no command-line system tools.

Note: Any RedwoodScript script files you want to run must be available to api-tool.jar.

Note: Depending on the platform, you may not be able to create the necessary connection file. If so, use the jsecret command on a supported platform to create the connection file, then copy it to the system where you want to use api-tool.jar.

Installing api-tool.jar

To install api-tool.jar, do this.

Navigate to Configuration > Software.
Expand API downloads.
Right-click api-tool.jar and choose Download from its context menu.
If you want the JavaDocs for api-tool.jar, right-click api-tool-javadoc.jar and choose Download from the context menu.

Setting the Return Code

Use the jcsShell.setReturnCode(int) method to set the return code of a script. If you want to terminate processing, throw an exception. The last effective call to jcsShell.setReturnCode() will set the return code.

Prerequisites

Java 1.8 or higher JVM
- Unlimited strength Java Cryptography Extension (JCE) if your server uses TLS and/or SSL.
- You can set TLS options using JVM specific system properties.

Syntax

Copy

java -jar api-tool.jar <command> [command-specific-arguments]

<command>:
event <connectionFile> <eventName> [raiseComment] -  Raise event <eventName> with optional comment [raiseComment]
script <connectionFile> <scriptFile> -  Run script in <scriptFile>
import <connectionFile> <file> [-targetpartition <Partition>] [<ImportRuleSet>]
version - Print the version
  -noverify           Skip server certificate verification
  -cipherlist <list>  Override the default cipherlist

Example: Simple Program

Copy

Usage javac -cp api-tool.jar <class.java>

Example: Print Process Definitions

Here is a sample Java program, in a file named PrintJobDefinitions.java.

Copy

import com.redwood.scheduler.api.tool.*;

public class PrintJobDefinitions
{
  public static void main(String [] args)
  throws Exception
  {
    ToolConnection tConnection = ToolConnectionFactory.createConnection(args[0], 60000);
    ToolResultSet rs = tConnection.executeQuery("select JobDefinition.Name, JobDefinition.UniqueId from JobDefinition", null, null);
    while (rs.next())
    {
      System.out.println(rs.getString(1) + " = " + rs.getString(2));
    }
  }
}

To compile and run this program, follow this procedure.

Copy

$ javac -cp api-tool.jar PrintJobDefinitions.java
$ java -cp api-tool.jar:. PrintJobDefinitions net/connect.rw

Example: Upload CAR and JAR Files

To upload a CAR or JAR file, use a script like this.

Copy

import com.redwood.scheduler.api.tool.ToolConnection;
import com.redwood.scheduler.api.tool.ToolConnectionFactory;
import java.io.File;
import java.util.Collection;
import java.util.Map;

public class Uploader
{
  public static void main(String [] args)
  throws Exception
  {
    if (args.length > 1)
    {
      ToolConnection tConnection = ToolConnectionFactory.createConnection(args[0], 60000);

      if (args[1].toLowerCase().endsWith("car"))
      {
        System.out.println("Uploading CAR file");
        String importSet = "";
        if(args.length == 3)
        {
          importSet = args[2];
        }
        Map mp = tConnection.uploadCAR(new File(args[1]), importSet);

        if (mp.size() > 0)
        {
          Collection cl = mp.values();
          System.out.println("JobId: "+cl.iterator().next());
        }
      }
      else if (args[1].toLowerCase().endsWith("jar")&& args.length == 3)
      {
        System.out.println("Uploading JAR file");
        Map mp = tConnection.uploadJAR(new File(args[1]), args[2]);

        if (mp.size() > 0)
        {
          Collection cl = mp.values();
          System.out.println("JobId: "+cl.iterator().next());
        }
      }
      else
      {
        System.out.println("Invalid Arguments.");
        System.out.println("Usage: Main <connection_file> <car_file> [<importRuleSet>]");
        System.out.println("       Main <connection_file> <jar_file> <library>");
      }

    }
    else
    {
      System.out.println("Invalid Arguments.");
      System.out.println("Usage: Main <connection_file> <car_file> [<importRuleSet>]");
      System.out.println("       Main <connection_file> <jar_file> <library>");
    }
  }
}

To compile and run this program, follow this procedure.

Copy

$ javac -cp api-tool.jar Uploader.java
$ java -cp api-tool.jar:. Uploader
Invalid Arguments.
Usage: Uploader <connection_file> <car_file> [<importRuleSet>]
       Uploader <connection_file> <jar_file> <library>
$ java -cp api-tool.jar:. Uploader net/connect.rw /tmp/JobDefinition_RS_MSLN_DB_Backup.car
$ java -cp api-tool.jar:. Uploader net/connect.rw /tmp/myJar.jar Custom_Example

Examples that Use Connection Files

For the following examples, assume that the connection file created with jsecret -c is stored in net/connect.rw, and a script named script.rw contains the following.

Copy

{
// code to submit a process running System_Sleep
// get the process definition (technical name 'job definition')
JobDefinition aDefinition  = jcsSession.getJobDefinitionByName("System_Sleep");

// create the process from the process definition
Job process = aDefinition.prepare();

// submit the process definition and write unsaved data to the database
jcsSession.persist();
}

Running a RedwoodScript

To run a script named script.rw, do this.

Copy

java -jar /opt/tools/api-tool.jar script net/connect.rw script.rw

Raise an Event

To raise an event named ETL_Complete, do this.

Copy

java -jar /opt/tools/api-tool.jar event net/connect.rw "ETL_Complete"  "ETL completed, please proceed with the next step"

Import a CAR File

To import a CAR file, do this.

Copy

java -jar apit-tool.jar import net/connect.rw JobDefinition_Test.car