Using the Webservice

The AE Internal Webservice is the connecting link between Web client and AE system. The Web client calls Webservice Operations. The Webservice uses an AE user to log on to the AE system and process the selected operations. The result is then sent to the Web client.

Two methods are available for accessing the AE system via the Webservice.

Note: You can use any programming language to create a Web client. The following examples are written in Java.

Method 1: Default User

Indicate the AE user to be used for accessing the AE system in the Configuration WebInterface for the Internal Webservice. The Webservice will always use the default user if the Web client does not supply a session ID (see Method 2).

A port of type "Uc4PortType" is required in order to communicate with the Webservice.

Uc4PortType port = new UC4Service().getUc4Port();

This port can be used to call Webservice operations and, for example, a list of all the client's agents.

List<AgentListItem> list = port.getAgentList();

Method 2: Session with Any User

The default user is limited to one client. A session must be created if you intend to access several clients or log on with different users.

A port of type "Uc4PortType" is again required for the communication with the Webservice.

Uc4PortType port = new UC4Service().getUc4Port();

Log on using the operation logon. The AE user is assigned via the corresponding parameters. The return code is a session ID which can be set in the HTTP Header. By doing so, it will automatically be assigned whenever this operation is called.

try{
String sessionID = port.logon(100, "SMITH", "UC4", "top-secret password", (bytes) 'D');

Map<String, List<String>> requestHeaders = (Map<String, List<String>>) context.get(MessageContext.HTTP_REQUEST_HEADERS);

if(requestHeaders == null) {
requestHeaders = new HashMap<String, List<String>>();
context.put(MessageContext.HTTP_REQUEST_HEADERS, requestHeaders);
}

requestHeaders.put("id", Arrays.asList(sessionID));

} catch(UC4WSException e){
System.out.println("ERROR: " + e.toString());
}

You can use the port to call the Webservice operations and, for example, read database information from the Administration perspective:

DatabaseInformation dbInfos = port.getDatabaseInfo();
String dbName = dbInfos.getDbName();

End sessions using the operation "logoff":

port.logoff(sessionID);

Note: The Webservice automatically closes connections that have not been used for a particular period of time. You can define this timeout length in the configuration web interface.

Filling :READ Masks

The Webservice contains the operation executeObject which can be used to start objects. One of its parameters serves to assign values for script variables via :READ masks as the following example will explain:

The workflow MM.DAY contains the following :READ mask:

:BEGINREAD "Print parameters"
:READ &TITLE#,"00","Please enter a title"
:READ &NUMBER#,"0-5","Please enter a number",,"N"
:ENDREAD

For more information, see :BEGINREAD... :ENDREAD.

A value is assigned to a script variable via the entry field label and not via the variable name. The following excerpt will explain this in more detail. First, create a list in which the values should be stored. Then, define the value for the script variable &TITLE#. Label it Please enter a title. It should obtain the value Final account. Now, define the script variable &NUMBER#. Finally, call the operation executeObjectand assign this list of values.

List<InputParameter> read = new ArrayList<InputParameter>();

InputParameter p1 = new InputParameter();
p1.setName("Please enter a title");
p1.setValue("Final account");
read.add(p1);

InputParameter p2 = new InputParameter();
p2.setName("Please enter a number");
p2.setValue(2);
read.add(p2);

int runID = port.executeObject("MAWI.TAG", "", read, null, false);

Notes:

• Only one value list is required even if an object has several :READ masks.
• Because values are assigned via entry field labels, CA Automic recommends creating unique labels in order to avoid confusion.
• For performance reasons, CA Automic recommends using one larger :READ mask instead of using several individual ones.

Error Handling

Errors occur for the following three reasons:

1. The Webservice cannot establish a connection to the Automation Engine (example: the communication process is not available, invalid login data etc.)
2. Runtime error while processing an operation (example: the object to be started does not exist)
3. The SOAP message the Web client sends to the Webservice is invalid.

The Webservice provides the exception UC4WSException. It contains an information field which includes the message number and text. It also informs about the type, which can either be CONNECT if the error occurred while attempting to establish a connection or REQUEST if operation processing was erroneous.

try{

String priority = port.getHighestNotificationPriority();

} catch(UC4WSException e){
System.out.println("Error number: " + e.getFaultInfo().getId();
System.out.println("Error text: " + e.getFaultInfo().getMessage);
}

The language that is used to transfer message texts to the Web client depends on the time the error occurred:

• It is always English if the error occurred while logging in.
• The text is displayed in the language in which the user logged on if the error occurred after a successful login attempt. Exception: Variable parts of the error message (example, for exceptions) may be displayed in English.
• SOAP faults generally include English texts.

See also:

Webservice Operations