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.