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.
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:
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.
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.
This is used to identify your package from its other variants.
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.
The URL of the documentation page of this package.
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.
If this attribute is set to
true, the package will be available for use during runtime. If it is set to
- 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.
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.
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.
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
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
As its name depicts, this directory should contain your package's configuration files.
Similar to the
classesdirectory but for
.jarfiles. Classes of these JAR files will be registered to your package's classloader and thus, they will be available for use in your code.
Contains the schema files for embedded Solr cores.
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.xmlfiles. If this file exists, TORO Integrate will then use this file as the configuration for the package.
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)
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
PackageManagerhas failed to set the status properly.
A package's status cannot be set manually; its value solely depends on what 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.
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.