Creating your own Actions - Deploying actions

After having created your own actions, the last step is to deploy them so everybody can use them into Action(s). Action(s) collection file (.actc) format enables you to bundle all the files requires by your actions to perform correctly into a single archive file.

Typically a collection file contains the class files and auxiliary resources associated with the actions.

The Action(s) collection file format is based on the Java Archive (JAR) file format. If you are familiar with JAR file creation, you will see that creating a collection file follow the same mechanisms. Even better, if you have created a JAR file containing your actions and variables, creating a collection file is as simple as changing its extension from .jar to .actc and adding a few lines in its manifest.

Writing the Collection Manifest

The manifest is a special file that can contain information about the files packaged in a collection file. It is used to identify the actions available within the collection package. There can be only one manifest file in a collection file.

The manifest file is a simple text file. You can create and maintain it with just about any text editor.

The name of this file should be MANIFEST.MF. This file contains the following lines:
Manifest-Version: 1.0
ActionsElements: com.jbbres.examples.actions.GetFileName

Warning: The text file from which you are creating the manifest must end with a new line. The last line will not be parsed properly if it does not end with a new line.

All lines contain key-value pairs. The key is on the left side of the equal sign and the value is on the right. For instance, Manifest-Version is the key that corresponds to the value 1.0.
  • The first mandatory key is Manifest-Version. Its value should always be 1.0 as the manifest is conform with version 1.0 of the manifest specification.
  • The second key is ActionsElements. Its value is the full class name (including package name) of all actions included in the collection file. If you want to declare more that one action, each action class name should be separated by a space.

Creating the Collection File

Collection files are packaged with the ZIP file format. To create a collection file, you can use the Java Archive Tool provided as part of the Java Development Kit (JDK).

If your IDE provides a built-in jar creation tool, you can generate a collection file by creating a JAR file and changing its extension from .jar to .actc. However, you will need to make sure that your IDE includes your manifest file into the JAR file created.

The basic format of the command for creating a collection file is: 
jar cfm actc-file collection-manifest input-file(s)


The options and arguments used in this command are:
  • The c option indicates that you want to create a collection file.
  • The m option indicates that you want to include your own manifest file within the collection file.
  • The f option indicates that you want the output to go to a file (the collection file you're creating) rather than to standard output.
  • collection-manifest is the name (or path and name) of the manifest file you have created for this collection.
  • actc-file is the name that you want the resulting collection file to have (extension should be .actc).
  • The input-file(s) argument is a space-separated list of one or more files that you want to be placed in your collection file. The input-file(s) argument can contain the wildcard * symbol. If any of the "input-files" are directories, the contents of those directories are added to the JAR archive recursively.

The command to create a collection file names GetFileName.actc of our project is:
jar cfm GetFileName.actc MANIFEST.MF bin


Deploying a Collection File

Your collection file created, your final step is now to make sure that people are able to download and install it on their computer. Depending on the audience you are targeting, the deployment strategy you can user are very different.

The easiest deployment strategy you can implement is to let your final user installs the collection file himself.
From a user perspective, installing a collection in Action(s) is a very simple operation. Opening a collection file (.actc) will trigger the collection installation within Action(s), copying the collection file within the user library. The user will immediately be able to see and use the actions from the new collection in his workflows.
As a developer, neither specific coding nor setting is required. You simply need to provide the collection file to the user, for example via a download section on your website. However, this strategy requires the user to have Action(s) installed on its computer, otherwise the collection file will not be recognized by the system and opening the file will result on an error message.

The http://app.jbbres.com/actions/more webpage provides a free listing of 3rd parties Action(s) actions. Visit it to get your collection file listed.

If your strategy is to provide your actions and variables as an additional feature of your application, it is possible to create an automatic installation of your collection files within Action(s) without requiring an user intervention.
Action(s)’ 3rd party collections are stored in the Action(s)’ library folder, a specific directory on the user computer. Any .actc file stored in this directory is automatically loaded into the library next time the user starts Action(s).
The Action(s)’ library folder is located in the application library folder within the user’s directory. Depending on the operating system used by your user, this folder might be located at a different path. The common paths are:
  • Windows XP: C:\documents and settings\%username%\local settings\application data\app.jbbres.com\Actions\plugins\
  • Windows Vista & Windows 7: C:\Users\%username%\AppData\Local\app.jbbres.com\Actions\plugins\
  • Mac OS X: ~/Library/Preferences/app.jbbres.com/Actions/plugins/
By providing a script copying your collection file within the adequate folder you deploy your actions and variables transparently for the final user.

> Next section: Action Design Guidelines