Skip to content

Overview

Concepts and Principles

Development

Overview

IDEs

API Explorer

Releases

Release Notes

TORO Integrate

Coder Studio

Coder Cloud

Bug Reports

Search

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 conf 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.

Note

Your .properties files are not automatically generated when you create a package or when you re-specify the value of package.prefix. If your .properties files are missing, simply create them under the conf folder.

Properties you put in <package.prefix>.package.properties will override those written in package.properties, provided that you are using the same prefix set in package.prefix. However, that's not to say the key-value pairs in 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 smoother!

Info

Deleting or renaming your package.properties or <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 UI

You can add package properties programmatically or via the UI. To add new properties via the user interface, simply follow the steps below:

  1. Go to the Coder Navigator view.
  2. Look for your package and expand its contents, particularly the conf directory, by clicking on the arrow heads.
  3. Double click the .properties file to open it.
  4. Add, edit, and remove key-value pairs as needed.

Opening the package.properties file

Opening the package.properties file

Shortcuts

In Coder Studio, you can do CommandR|kbd!! to search for your .properties file(s) instead. With this, you can optionally open all of your .properties files all at once.

Searching for .properties files via the *Open Resource Dialog*

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 GroovyMethods class.

You can add or modify package properties in Groovy code by using some of the methods provided by the extension module mentioned above:

1
'key'.savePackageProperty('value')

Tip

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:

1
'key'.removePackageProperty()

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:

  1. From your prefixed package properties file (if package.prefix is set and the <package.prefix>.package.properties exists)
  2. From the package.properties file
  3. From your instance properties