Java API coverage

[Michael A. Lowry]

Recently we conducted a review of external applications that make connections to the Automation Engine, with the aim of identifying for each one:

• Connection type (Java API, REST API, JDBC, etc.)
• User name
• Purpose

For JDBC connections, we also listed our reason for not using the Java APIs or REST APIs instead.

This exercise was informative. I thought I would share some our findings, because they exposed some gaps in Java API coverage for common tasks.

Use case	Description	Justification for using JDBC & SQL
Get part of folder tree	List folders and objects beneath a specific path in the Automation Engine system.	The FolderTree API fetches the entire AE folder tree. There is no API to get an IFolder object corresponding to a specific path in the hierarchy. Idea deleted by Broadcom: More ways to get IFolder objects.
List tasks by object name	List tasks by object name, regardless of alias.	The TaskFilter.setObjectName() method filters by task alias, not object name. There is no method that filters by object name. Idea deleted by Broadcom: Improvements to TaskFilter API class
Search by object type and name pattern	Search for all objects of a specific type whose names match a given pattern.	The SearchObject API allows for searching for objects of a specific type. The QuickSearch allows searching using wildcards. However, neither API offers both of these capabilities together.
Get titles of workflow tasks	Get the object names and titles of all tasks in a list of workflows.	The SearchObject API does not support searching for a list of objects. The only way to do this via the Java APIs would be: Use SearchObject for each workflow in the list.  Use JobPlan to retrieve details about each workflow. Use taskIterator() to get a list of child tasks. Use JobPlanTask to get the details of each child task. For  20 workflows, that would be at least 80 API calls. With SQL, we can accomplish all this using a single query.
List all user group memberships	Get a list of all user groups and their members	This requires many more steps via the Java APIs: Use SearchObject to list all user groups. Use UserGroup to retrieve details about each user group. Use users() to get a UserAssignment object. Use memberListIterator() to get a list of members. Use UC4UserName to get the name of each member. Retrieving the whole list would take hundreds or even thousands of API calls. We can get all of this information using one SQL query.

Because of the above gaps in the Java APIs, we will continue to rely on a hybrid approach, using the Java APIs where possible, and using JDBC/SQL in those situations where it is impossible or inefficient to achieve the desired result using the Java APIs.

The REST APIs are even less mature, and we cannot yet foresee switching from the Java APIs to REST.

I would be glad to learn better ways to use the APIs, so please let me know if I have overlooked anything.