Skip to content





API Explorer

An Introduction to Integrate Packages

Definition and Composition

Packages are used to organize related integration components. In fact, it is required for an integration component to belong to a package. In this context, an integration component is any element used to build integrations. They can be, but are not limited to, any of the following:

Because of the structure and design of packages, it is easy to deploy integrations from one instance to another. Importing a package to an instance allows it to obtain all of its integrations and services.


Packages were designed to be customizable in order to suit integration needs. A package has 'meta-fields' that help identify, document, and configure the package's behavior during runtime. The majority of these meta-fields can be configured via the Package configuration editor. They are described below:

  • Name

    This is used to identify a package within an instance. It must be unique (within the instance) and is required. Only alphanumeric characters, dashes, and underscores are allowed. This property cannot be changed once set.

    Rules and conventions for package names

    Aside from character restrictions, there are certain terms which cannot be used to name a package. Learn more about naming packages here.

  • Marketplace ID

    It's possible to upload a package to the TORO Marketplace to make it publicly available. The TORO Marketplace is TORO Integrate's official platform for sharing integrations, API specifications, individual services, and more. This key will be used to uniquely identify the package there.

  • Version

    This is used to identify your package from its other variants.

  • Credentials URL

    Some packages call third-party services that require authentication. This field should be used to indicate where to get the required credentials for those services.

  • Documentation Page

    The URL of the documentation page of a package.

  • Dependencies

    The packages that are required for a package to run. A package cannot start when its dependencies are not present. A package is also not allowed to have cyclic dependencies.

  • Enable Auto Start

    A boolean property indicating if a package should automatically be called to start during instance startup.

  • Enabled

    If this meta-field is set to true, the package will be available for use during runtime. However, if it is set to false:

    • The package will be stopped and will remain in that state until you enable it. A package cannot be run when it is disabled.
    • The package's classloader will not load the Java classes defined in the package.
    • The package's services will not be available for use in other packages.
  • Startup Services

    The services that are called when a package is started. Note that when TORO Integrate is starting up, all enabled packages will be started and thus, these services will be called.

  • Shutdown Services

    The services that are called when a package is stopped. Note that when TORO Integrate is shutting down, all enabled packages will be stopped and thus, these services will be called.

Directory Structure

Packages persist in the file system. Each package, except the core package, is assigned a folder which is named after it. This directory is expected to look like the following:

├── code
├── conf
   └── esb-package.xml
   └── properties
       └── <prefix>
├── jars
├── solr
├── web
  • code

    This directory is meant to contain your services' source files, as well as their corresponding byte code files, if any (i.e. Groovy and Java files have .class file counterparts). Files and directories under this folder must use a valid Java name and identifier. Specifically, they must follow the JLS 6.2 naming guidelines.

    Naming files and directories under code

    Meaningful names are a must when it comes to writing clean code. A meaningful name should describe the purpose of the code unit in just one glance. Learn more about how to name and organize model and service files here.

  • conf

    This directory contains your package's configuration files.

  • jars

    Contains any extra .jar files necessary for the package. Classes of these JAR files will be registered to your package's classloader and thus, they will be available for use in your code.

  • solr

    Contains the schema files for embedded Solr cores.

  • web

    This is where optional Java web application resources reside. It can contain web pages which are used by TORO Integrate's embedded Tomcat server to host web applications. If this directory exists, TORO Integrate will add the package as a webapp to the underlying Tomcat web manager. This directory can be used to store a WEB-INF/web.xml file. If this file exists, TORO Integrate will then use this file as the configuration for the package.

Package XML

Every package is required to have a certain file named esb-package.xml in the conf directory. This is the file that stores package metadata as well as the following pieces of information:

  • The endpoints that belong to the package
  • The custom Solr cores linked to the instance which can then be used to index data
  • The Spring context files that define the Spring beans that need to be instantiated and included in your package's application context
  • The JMS destinations that will be added to the instance's list of broker destinations (if they don't already exist)

Modifying esb-package.xml

It's possible to directly modify the esb-package.xml file in your file system. However, beware that some changes may not take effect immediately and that they may require an instance restart.


A package's status indicates the package's current state. It only changes when a package is started or stopped. Statuses impact how packages will behave in your instance and how it'll interact with other packages. Depending on the current status of a package, some actions may or may not be performed. For instance, configuring a package's metadata or deleting it is not possible unless the package is stopped.

The following list describes all possible package statuses:


    The status of packages that are not running. The integration components of stopped packages will still be available for use in other packages (e.g. you can still use services from stopped packages). However, HTTP endpoints, such as those created by Gloop APIs, Gloop services, Groovy-based controllers, or Integrate endpoints will be unreachable.


    The status of packages that are currently in the process of starting up.


    The status of packages that are currently running.


    The status of packages that have managed to start-up but encountered non-fatal errors such as endpoints that have failed to start and start-up services that encountered exceptions upon invocation.


    The status of packages that have completely failed to start-up because of fatal errors.


    The status of packages whose states are unknown; if a package has this as its status, it most likely means that the PackageManager has failed to set the status properly.

A package's status cannot be set manually; its value solely depends on what the PackageManager assigns.

The core Package

The core package is a system package that must be running at all times. This package cannot be imported or exported and can only be stopped or started by shutting down or starting-up its TORO Integrate instance. The core package does not contribute to any package count limit imposed by a TORO license.

As Shown in the User Interface

You will be able to see all the packages in your instance via the Coder Navigator view. By default, these panels are located on the left side of Coder.

Expanding and collapsing the items in the tree should allow you to view or hide the contents of the parent item.

Coder Navigator view

Coder Navigator view

To perform actions on your package, simply do a right click on the package to pop the mini menu. From this menu, you may then select the action you want to perform. The actions you may be able to do depend on the state of your package.

Right clicking on a package in Coder

Right clicking on a package in Coder