Working with Integrate Package Properties
Sometimes you may find it useful to store certain values for later use in your services. If this is the case, you may need the help of properties!
In TORO Integrate, we have properties that are global to the instance or local to a certain package. You'll want to use package properties if you want certain values to be persisted and shared across your package and your package only. A typical use case would be storing your API access keys; when you use a third-party API, you would typically just use the same set of credentials to access any of its secured services.
Your package properties are stored in a file called
package.properties under your package's
directory by default. But if you wish, you can have other prefixed
package.properties files under the same folder and
have your instance select which one to use via the
package.prefix instance property.
Might have to manually create the files
.properties files are not automatically generated when you create a package or when you re-specify the value
package.prefix. If your
.properties files are missing, simply create them under the
.properties files used to be just in the root
TORO Integrate's v3.1 release changed the location of these files for better organization.
Properties you put in
<package.prefix>.package.properties will override those written in
provided that you are using the same prefix set in
package.prefix. However, that's not to say the key-value pairs
package.properties are gone or ignored.
<package.prefix>.package.properties simply take higher precedence and its
key-value pairs will be used whenever available. If a key is not present in the prefixed file, TORO Integrate will
fall back to using the same property in
package.properties. This offers more convenience than you think! For packages
that need to use a different set of package properties for development and production environments, the switch will be
Follow the naming convention
Deleting or renaming your
<package.prefix>.package.properties file to something
unconventional will make it unrecognizable to your instance and thus, you lose all your key-value pairs.
Like instance properties, changes to your package properties will be visible as soon as you save the properties file; and likewise, depending on how you use these properties; they may or may not take effect immediately and in the times that they do not, a package restart may be required.
Modifying Package Properties via the Coder Studio UI
You can add package properties programmatically or via the Coder Studio UI. To add new properties via the user interface, simply follow the steps below:
- Go to the Coder Navigator view.
- Look for your package and expand its contents, particularly the
confdirectory, by clicking on the arrow heads.
- Double click the
.propertiesfile to open it.
Add, edit, and remove key-value pairs as needed.
Quick search for files
In Coder Studio, you can do to search for your
.properties file(s) instead. With this, you can
optionally open all of your
.properties files all at once.
Modifying and Using Package Properties Programmatically
The instance-wide classloader ships with a Groovy extension module packed with utility methods. This means that you can use the functions defined in that extension module in all of your Groovy or Gloop code.
When working with package properties, most, if not all, of the methods you'll be needing are present in the
You can add or modify package properties in Groovy code by using some of the methods provided by the extension module mentioned above:
If you want to save an array of values, simply create a string of all the values separated by commas. We have utility methods that'll parse and split those values up for you and return them in an array.
To remove a package property, do:
If you want to fetch the value of a package property, however, you should do any of the following, depending on your needs:
1 2 3 4
'key'.getPackageProperty() 'key'.getPackageProperty('default-value') 'key'.getPackagePropertyArray() 'key'.getPackagePropertyArray(['default-value-one', 'default-value-two'])
The methods for managing package properties are context-aware. If you call any of the methods above in a certain script
and that script is contained in a package called
foo, then only
foo's package properties can be fetched, added,
modified, or removed.
The one liner will take this precedence of retrieving/saving the property from/to your properties file:
- From your prefixed package properties file (if
package.prefixis set and the
- From the
- From your instance properties