Package Development: Returning a List

Carpenters use certain tools for getting their work done - hammers, wrenches, screwdrivers etc...in that same way, Automation Anywhere developers use packages for getting their work done - Recorder package, Simulate Keystroke package, Loops package, etc.

Packages are the "tools" available to bot builders for building out their automation. Having the ability to create custom packages in the Automation Success Platform gives developers the ability to accelerate bot development times not only for themselves but also for the Automation Anywhere bot builders within their organization.

Custom packages can be used for (but are not limited to) interfacing with internal/proprietary applications and services - enabling bots to quickly automate arduous tasks within an organization, or could be used to create connections to 3rd party applications to enable bot builders to quickly make connections/operations with those applications. This capability of creating your own custom packages - paired with an already large number of in-built packages - means that RPA developers have lots of tools at their disposal for creating fast, reliable, and resilient automations. If you aren't familiar with package development, take a look at our tutorial on building your first Automation Success Platform package.

Package Basics

The quickest way to start building a package is to start with the Automation Success Platform Software Development Kit (SDK).

The SDK includes examples of how to use different field types in the Automation Success Platform UI as well as some advanced package capabilities like custom variables types, conditional statements, and triggering capabilities. The example code that we’ll be walking through for the remainder of this article was built from the .23 Automation Success Platform release of the SDK (SDK 2.4.1) – with lots of comments throughout to hopefully guide developers on what each section of code is doing. The screenshots and sample code were all built/taken using IntelliJ – though you should feel free to use the Java IDE of your choosing.

ReturnAList Class

The ReturnAList class is the only class that's been defined for this project and the only action that's been defined for this demo package.

The BotCommand annotation and CommandPkg annotation are mostly generic across any bot action with the exception here of the defined return type. Notice in the code below that the defined return type is LIST (from com.automationanywhere.commandsdk.model.DataType). This establishes that the return type from this action will be a list - and will force an operator to map the action's output to a variable of that specific type. While the label,node_label, description, and other CommandPkg values have been hardcoded in this example, you may alternatively use [[value]] references to reference locales json files (see the default commands included in the SDK download for examples of this kind of reference) Note: If you want to follow along with this code in your IDE, please download this code sample from our GitHub. Instructions for compiling/testing are included below as well.

//BotCommand makes a class eligible for being considered as an action.
@BotCommand

//CommandPks adds required information to be dispalable on GUI.
@CommandPkg(
        //Unique name inside a package and label to display.
        name = "returnalist", label = "Return a List",
        node_label = "Return a List", description = "Returns a list of the provided strings", icon = "pkg.svg",

        //Return type information. return_type ensures only the right kind of variable is provided on the UI.
        return_label = "New list of Strings", return_type = LIST, return_required = true)

Inside the ReturnAList public class, the Execute annotation identifies the entry point into the defined action. Here, a public action with a return type of ListValue<String> is defined (which must correspond with the return type of the action) along with 2 input fields. Nothing is particularly special about the 2 identified input fields, but we needed more than 1 value to use for building out the list, so in this case - two input fields have been defined of type TEXT to enable an operator to enter to Strings that will be added to the list. The process of building out the list is actually quite straightforward once you're a bit familiar with working with the Automation Anywhere datatypes.

1. A ListValue (Automation Anywhere datatype) variable is created.
2. A Java ArrayList variable is created.
3. Values are added to the ArrayList variable.
4. The ListValue is set to the Java ArrayList.
5. The ListValue is returned as a result of the action's execution.

@Execute

    public ListValue<String> action(
            //Idx 1 would be displayed first, with a text box for entering the value.
            @Idx(index = "1", type = TEXT)
            //UI labels.
            @Pkg(label = "Field 1 for List")
            //Ensure that a validation error is thrown when the value is null.
            @NotEmpty
                    String firstString,
            @Idx(index = "2", type = TEXT)
            @Pkg(label = "Field 2 for List")
            @NotEmpty
                    String secondString) {

        //Create new AA ListValue variable type
        ListValue<String> sampleListValue = new ListValue<>();
        //Create new Java ArrayList
        List<Value> values = new ArrayList<Value>();
        try {
            //Add Values to Java Array list as Automation Anywhere types (StringValue here, but could be other supported types)
            values.add(new StringValue(firstString));
            values.add(new StringValue(secondString));
            //Set the AA ListValue variable to the Java Arraylist
            sampleListValue.set(values);
        } catch (Exception e) {
            throw new BotCommandException("Error occurred in creating list: " + e.toString());
        }

        //Return StringValue.
        return sampleListValue;

    }

Building the Project (Optional)

If you want to actually compile the package for testing in your Control Room, click to open the Gradle tab on the far right side of your screen (if it's not showing up, navigate to Window > Restore Default Layout). Once there, click the Execute Gradle Task button (the elephant).

From there, the Run Anything window appears and enables you to build the project by typing clean build shadowJar. Once executed, the project will build in the Run interface at the bottom of the screen and the package jar file will be generated in the /build/libs directory of your project.

Alternatively, you could navigate to the project root directory using Bash Shell/PowerShell and execute the following command:

.gradlew.bat clean build shadowJar

Conclusion

Packages enable endless possibilities for reusable components - to accelerate your own bot builds as well to empower other developers in your organization to build bots using custom packages as well.  Now that you understand how to return a List value to the bot and compile the package - the sky is the limit in the creativity that you can inject into your bot builds. If you want to download and try out the demo custom package from this tutorial, get it from our GitHub. Go build awesome bots (and packages)! Go be Great!