Using the AE Application Interface

The classes and methods of the AE.ApplicationInterface can be used as soon as the library has been integrated in your program.

Data between the program and the AE system is exchanged via Requests. Keep in mind that you should establish a connection to the AE system and log on to a client, as otherwise requests cannot be sent or received.

This page includes the following:

Procedure

The following steps are always required, regardless of how your program is used:

  1. Establish a connection to the AE system. You have two options:

    • You must have either installed the certificates in the Java trust store or defined the path to the folder where the trusted certificates are stored using the TrustedCertFolderPath parameter before establishing the connection (see Securing Connections to the AE (TLS/SSL)):

      setTrustedCertFolderPath(C:\Data\Certs);

      Connection uc4 = Connection.open(PC01, 8443);

    • You can define the path to the folder where the trusted certificates are stored using the TrustedCertFolderPath parameter while establishing the connection:

      Connection uc4 = Connection.open(PC01, 8443, null, null, C:\Data\Certs);

  2. Log on to the AE system with a user.

    uc4.login(98,SMITH,UC4,null,D);

  3. A number of requests such as searching for an object can be sent now. These requests are sent synchronously or asynchronously using the methods sendRequestAndWait and sendRequest.

    uc4.sendRequestAndWait(WinJobs);

    uc4.sendRequest(WinJobs, Handle);

    Now access the request result, for example, search result.

  4. Finally, terminate the connection.

    uc4.close();

Note: Requests are used for retrieving information from or executing an action in the AE system. The supplied package includes several examples which describe how the AE.ApplicationInterface is best used. Additionally, the documents shown below provide information about the most important classes.

Using the AE.ApplicationInterface

The AE.ApplicationInterface mainly facilitates the automation of user interactions.

When reviewing applications, put the main focus on recurring processes, especially in processing loops, as performance gains are most likely here.

In high-volume processing, weigh up the importance of a fast processing time with the importance of non-impaired production system performance. If the performance of the production system is more important, use the AE.ApplicationInterface in such a way that processing is distributed evenly over a longer period of time, for example through waiting queues.

You want to send as few queries as possible to the Automation Engine. Only call the methods Connection.sendRequest() and Connection.sendRequestAndWait() if necessary.

When using the AE.Application Interface, keep the following issues in mind:

  • Log on, execute all actions and log off

  • Open objects in read-only mode if no modification is being made

  • Modify rather than delete and recreate

  • Only use what is required

  • Use mass functions instead of many individual actions if applicable

    If mass functions are not available, please contact our support center. For more information, see Files to Aid Technical Support.

  • Execute complex mass modifications through the AE.ApplicationInterface in a non-production AE environment and transfer your modifications to the production system using the corresponding utility

  • Do not create loops without waiting time, especially for status queries

  • Do not create/modify an object and store it repeatedly

  • Do not make large and numerous searches using the class SearchObject

Error Checking the Response

When you send a request with the sendRequestAndWait() function, you must check the message box of the response for errors before you start working on the response. Continue with the response processing only if the message box is empty.

Example

//Create a Unix Job with the name JOBS.UNIX.API_TEST in the root folder
UC4ObjectName jobName = new UC4ObjectName("JOBS.UNIX.API_TEST");
CreateObject create = new CreateObject(jobName, Template.JOBS_UNIX, tree.root());
uc4.sendRequestAndWait(create);
//Test if the Job was created successfully
if (create.getMessageBox() != null) {
System.err.println(create.getMessageBox().getText());
uc4.close();
return;
}

Negative Effects of Badly Designed Applications

Dialog users rank second because the AE.ApplicationInterface also uses the dialog processes.

The performance of the whole AE system is negatively affected because calling the AE.ApplicationInterface represents a write access to the AE database, resulting in increased I/O database activity.

See also: