Building reusable packages
- Updated: 2021/07/06
Building reusable packages
Review the guidelines to understand how to build packages for reusability.
- Know your incoming data
- When setting fields that your action package requires from
the user, provide specifics in setting the attribute type to limit the kinds
of data that your package receives.
- Limit the input to reduce the burden of checks that have to be done when the package is received.
- Javadoc includes 34 defined attribute types, so review those when you build your package to select the appropriate field types.
- Set your package so that it takes a stored value. For example, on behalf of the bot, your package is making API calls, verify that the AttributeType of the action input field for the API key or a token is set to credential. This way users are encouraged to use a value stored in the Credential Vault for sensitive input data that the package requires.
- Use labels appropriately
- In the CommandPkg annotation, use different labels,
node_labels, and descriptions appropriately.
- Use these labels as short descriptions of your action and use only a few words to describe an action.
- Replicate the same naming style as it is presented in the default Action packages.
- Each action is a child element of a package, and the action label is displayed along with the package icon in the Actions pane. Use short names to describe each action.
- Document an expected input format for certain fields. Use the
parameter description for the @Pkg annotation.
This allows package developers to review the format,
requirement, or data that must be used for a specific input field.
For example:
@Pkg(label = "Start Date", description="Date Format as MM/DD/YYYY"
- Unit test your components
- During the package development, create unit tests to validate
that each component and the action of the package is working
as expected.
- Validate the behavior of the individual test unit, a single class, or a single action, to ensure that it is functioning as expected.
- Review and document any feature or functionality defects at early stages of the development process.
- Handling errors
- Include the error handling in the bot logic to ensure that
all errors are handled gracefully. If an error is not handled, it could
prevent a bot runner from executing other tasks.
- Create meaningful error messages that can help bot consumers with error resolutions.
- As a package developer, keep in mind these recommendations:
- Use Try/Catch block to accommodate for an error.
- Use a multi-catch block to find specific errors, and use the
BotCommandException to return
customized error messages. For
example:
//create array of 3 items int[] myIntArray = new int[]{1, 0, 7}; try { //print 4th item in array System.out.println(myIntArray[3]); //Perform operation on first and second items in array int result = myIntArray[0] / myIntArray[1]; } catch (ArrayIndexOutOfBoundsException e) { //Throw custom message for IndexOutofBounds throw new BotCommandException("The array does have the number of expected items."); } catch (ArithmeticException e) { //Throw custom message on Atithmetic Exception throw new BotCommandException("Math Operation Error with " + Integer.toString(myIntArray[0]) + " and " + Integer.toString(myIntArray[1])); }
- Follow single-responsibility principle
- A package is a collection of actions. Each action within a
package must have a single responsibility and that
responsibility must be encapsulated by that action.
- Following the single-responsibility principle helps your package consumers to implement it easily, simplifies testing, and avoids unnecessary modifications.
- The actions that you offer allow package consumers to customize the way they use your package within their bots, and can help their bots be as efficient as possible.
- Provide examples
- When submitting packages to the Bot Store
include a demo bot that demonstrates the use of the package.
- Use the Automation 360 actions and allow package consumers to use these actions to expend their bot capabilities.
- Always provide sample bots with descriptions to help your package consumers with the knowledge they require to understand its proper use.