Skip to content

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 ship your integrations from one instance to another. Importing a package to an instance allows you to obtain all of its integrations.

Metadata

Packages were designed to be customizable in order to suit your integration needs. A package has a bunch of 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. As of Version 3.0, this property cannot be changed once set.

  • Marketplace ID

    Eventually, you may want to make your package publicly available. The TORO Marketplace is TORO Integrate's official platform for sharing integrations and the like and this key will be used to uniquely identify your 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 this package.

  • Dependencies

    The packages that are required for this 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 attribute is set to true, the package will be available for use during runtime. If it is set to false, however:

    • 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:

1
2
3
4
5
6
7
8
9
package
├── code
├── conf
│   └── esb-package.xml
│   └── package.properties
│   └── <prefix>.package.properties
├── 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).

  • conf

    As its name depicts, this directory should contain your package's configuration files.

  • jars

    Similar to the classes directory but for .jar files. 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 you place your web pages in case you want to make a web UI for any of your integrations. 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 WEB-INF/web.xml files. 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 under the conf directory. This is the file that stores package metadata as well as the following bits of information:

  • The endpoints that belong to the package
  • The custom Solr cores that will be used to index data
  • The Spring context files that will 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.

Status

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:

  • STOPPED

    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.

  • PENDING_START

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

  • STARTED

    The status of packages that are currently running.

  • STARTED_WITH_ERROR

    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.

  • ERROR

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

  • UNRECOGNIZED

    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 the Coder IDEs.

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

*Coder Navigator* in Coder Studio

*Coder Navigator* in Coder Cloud

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 click on a package in Coder Studio

Right click on a package in Coder Cloud

Managing Packages

TORO Integrate is quite flexible in that it provides a variety of ways to interact with your packages (and not only packages, in fact). Aside from the UI, a CLI Tool and a REST API is also provided.