Using Libraries

A library allows you to store your RedwoodScript code for use in Redwood Server, in one or multiple Triggers, for example, or in Redwood Expression Language.

You can write your own code directly in your library or add JAR files to your library. RedwoodScript code in a library must always be in Full mode, that is start with package com.redwood.scheduler.custom.... This code can then be accessed from Triggers, Actions, Job Definitions, Period Functions, and Redwood Expression Language.

Note: Customer library names must begin with Custom_.

Note: When you modify a library, all Objects that use the library will have to be recompiled. This can be time-consuming. To reduce the impact, you can set the library of Job Definitions, Actions, and Triggers that do not use the Custom library to use None library.

Custom Library and Customer Libraries

Actions, Triggers, Period Functions, and Job Definitions (RedwoodScript contexts) depend on the Custom library. You may specify your own library in which case the Object will depend on your library and the Custom library.

If you do not want to depend on a library, you can use the None library: this will also prevent superfluous recompiles when the Custom library changes.

It is recommended to spread your code functionally across multiple libraries if you have a lot of RedwoodScript Objects that use libraries. When you modify a library, all RedwoodScript contexts, as well as any other RedwoodScript Objects that use the library, will be recompiled when the library changes. When you specify a library on a RedwoodScript context, the context will depend on the Custom library as well as the library you specified (except for the special None library). You cannot specify more than one library on a context.

Shared code should go into the Custom library, and function-specific code should go into individual libraries to balance recompile times.

Using Loggers in Libraries

A logger is an Object that allows you to write log messages. Loggers have a category and a level. The category is the source of the message, and is arranged hierarchically. All loggers related to Redwood Server are in the category com.redwood, under which there are many more sub-categories.

Loggers also have a level. This controls the amount of information that is logged from a particular source. The levels (in order of most to least important) are:

• FATAL: Messages that will cause an immediate issue for the system or important customer functionality, that require human intervention to resolve.
• ERROR: Errors that only effect part of the system (for example a process failing or a file not being present)
• WARN: Potential errors or bad configuration.
• INFO: Informational messages, generally about progress in a long running task.
• DEBUG: Detailed information about system progress.

You use the default loggers that are available in the context of the library. If you want to create your own, you should create one for each class that requires a separate logger.

package ...;

import com.redwood.scheduler.infrastructure.logging.api.Logger;
import com.redwood.scheduler.api.scripting.variables.LibraryLoggerFactory;

public class MyClass
{
  private static final Logger log = LibraryLoggerFactory.getLogger(MyClass.class);

  ...

  log.info("Reached important point");

  ...
}

The logger Object has two methods for each level, one that takes a message, and another that takes a message and a Throwable Object (an exception).

  Logger log = ...;

  log.debug("Some information useful to developers is " + someVariableName);

  log.info("Finished Pass 2/3");

  try
  {
    ...
  }
  catch (IOException ioe)
  {
    log.error("Error accessing file", ioe);
    throw ioe;
  }

Accessing Libraries in RedwoodScript

To use your methods from within RedwoodScript, you first need to set the library containing your code on the Object, you can then use your code using one of the following:

• specifying <package_name>.<class_name>.<method_name>
• import your class using the following import statement import <package_name>.<class_name>; and use <class_name>.<method_name>

Note: You should not use the jcs prefix in the names of your methods, as this prefix is reserved for the system.

Accessing Libraries in Redwood Expression Language

You can use your methods in Redwood Expression Language throughout the product by specifying REL Entry Points with the following information:

• Name: the name of the method to be used in Redwood Expression Language
• FQ Class Name: the fully qualified class name
• Method Signature: the method syntax

Note: You should not mix code in a same class that is to be used in Redwood Expression Language and RedwoodScript. See Mixing REL and RS Code in a Library for more information.

Note: You should not use the jcs prefix in the names of your methods, as this prefix is reserved for the system.

Persisting Sessions in Libraries

It is not recommended to persist a session in your library code that you intend to use in Redwood Expression Language, as it can have side-effects. The behavior or side-effects might even change from one release to the next without prior notice.

Persisting a session in your library code used for RedwoodScript may have side effects as well, especially when the code is used in triggers, process actions, or Import Rule Set actions. It is strongly recommended not to persist a session in your library code if it is used in triggers, process actions, or Import Rule Set actions.

You may persist a session in your library code when it is used by alert escalations, Alert Sources, or email alert gateways and none of the previously mentioned Objects.

Sessions in Libraries and Restarted Processes

When you called ScriptSessionFactory.getSession() within a library from REL, the call would return null for restarted processes. This has been fixed, however, the session is read-only, for default expressions and in-expressions of parameter mappings.

Context Menu

Libraries support the following context menu options.

Note: For generally applicable Object context menu options, see Object Context Menu.

Deleting Libraries

You can only delete libraries when no other Objects have relationships to them. For example, if there are Job Definitions that use a library, the library cannot be deleted until all Job Definitions that use it have been modified. You can see all Job Definitions that relate to a library under Related Objects in the Detail View.

Security

The privileges available in the Security tab are as follows. For more information, see Security Tab.

Procedure

To create you own package in the Custom library:

1. Navigate to Configure > Automate > Scripting tools > Libraries.
2. Right-click the library and choose Edit.
3. Click the Sources tab.
4. Click Add.
5. Enter your code.
6. Click Save.
7. Click the REL Entry Points tab.
8. Click Add.
9. Enter the following information:
   • Name: The desired name of the method.
   • FQ Class Name: The fully qualified name of the class: <package_name>.<class_name>.
   • Method Signature: The signature of the method. For example, its name in your code and the types of arguments that should be provided.

To add a JAR file to the library:

1. Navigate to Configure > Automate > Scripting tools > Libraries.
2. Right-click the library and choose Edit.
3. Click the JAR Files tab.
4. Click Add.
5. Enter the name of the JAR file in the Name field.
6. Use the Select File field to select the JAR file.
7. ClickSave and wait until the JAR file has been loaded. The System_Import_JarFile Job runs automatically to upload the JAR file.
8. To verify the import, locate the System_Import_JarFile Job in the Monitor screen and inspect its stderr.log and stdout.log files.

See Also

• Library Example