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:
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.
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.
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 a package.
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.
If this meta-field is set to
true, the package will be available for use during runtime. However, 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 10
package ├── code ├── conf │ └── esb-package.xml │ └── properties │ └── 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
.classfile 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
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.
This directory contains your package's configuration files.
Contains any extra
.jarfiles 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.
Contains the schema files for embedded Solr cores.
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.xmlfile. 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 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)
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 Coder.
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.
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 user interface provided by Coder, the CLI tool and TORO Integrate's ESB REST API is also provided.