Nordic Edge Automatic Account Manager 3.4 Developer Guide

About this guide

This document gives an overview of the Action API in AAM up until version 3.4.
NOTE: The information in this document covers the way to create and/or customize actions until version 3.4 of AAM.
From version 3.4.23995 a new class is used for this purpose, the old way is still supported though.

Summary

This document is meant for developers who wish to create and/or customize AAM 3.4 actions by using the AAM 3.4 Application Programming Interfaces (APIs).

To read this guide, knowledge about Java™ development and the Automatic Account Manager as a product is assumed.

AAM API Overview

AAM 3.4 provides two Application Programming Interfaces (APIs) for developers who wish to customize the product by creating plug-ins:

Action API — Use the Action API to develop custom actions.
Web Service Listener API — Use the Web Service Listener API to synchronize information over HTTP/HTTPS between two AAM—Provisioning instances.

This section covers the Action API. More information about the Web Service Listener API is available upon request.

AAM Actions

AAM actions are the key to policy implementation. In addition to a large menu of built-in actions, AAM offers an Action API that lets you configure custom actions for your particular situation. There are three types of actions in AAM :

Getters — Getters are actions that add data from one or more data sources to the internal virtual image of an object. Getters create new session objects and session attributes.

Modifiers — Modifiers are actions that update existing session objects and session attributes.

Setters — Setters are actions that save data from existing session objects and session attributes to one or more databases.

Setting up your JAVA Development Environment

Before using one of the AAM APIs, you need to have an instance of the product V3.1 or later installed. You also need a basic understanding of the product. For more information, documentation can be found here:
http://support.nordicedge.com/category/documentation-aam/
You can use any Integrated Development Environment (IDE) to develop custom pluginsfor AAM, including the following:

Eclipse — For more information, visit: http://www.eclipse.org/.
IntelliJ IDEA — For more information, visit: http://www.jetbrains.com/idea/.
NetBeans — For more information, visit: http://www.netbeans.org/.

The Action API, which is written in Java code and distributed in JAR (Java ARchive) files, consist of Java classes. To view the Javadoc and Java classes, visit:
http://download.nordicedge.se/download/aam/javadoc/

Import custom JAVA code

Before you begin, you can import sample Java code in AAM Studio and view two custom actions. One action is an example of a simple configuration, and the other is advanced:

Reverse String (Action Advanced Config)
Reverse String (Action Simple Config)

To download the sample Java code, click:
https://download.phenixid.se/wp/support/prodguide/aam/AAMActionAPISampleCode.zip
The downloaded zip file includes the following JAR file: AAMActionAPISampleCode.jar.
In this procedure, you import the JAR file into AAM, where you
can view the custom actions.

To import custom Java code
1. Open AAM Studio.
2.Go to Tools > Plugin Manager.
3. Click Import from file, browse to locate the JAR file, and click OK.
4. Restart AAM Studio

JAR File dependencies

This section includes information about internal and external JAR file dependencies on a Microsoft Windows operating system:

Internal JAR File Dependencies — When you import JAR files into AAM, include all files with the JAR extension at the following location:
<installation_directory>\AAM3\lib
<installation_directory> Specifies the directory where AAM is installed.
Default: C:\Program Files\NordicEdge\AAM

External JAR File Dependencies — Place all external JAR file dependencies in the ext directory under the root AAM directory.
Default: C:\Program Files\NordicEdge\AAM\ext

Action API Interfaces

In AAM, there are two different API interfaces for developing action plug-ins:

Simple Action API Interface — Using the simple interface, you can develop simple actions. For example, you can develop actions that update session attributes, create a Microsoft Excel file with values read from session objects and attributes, or browse an LDAP directory or file system. The following screen shot shows an action in the simple interface.

Advanced Action API Interface — Using the advanced interface, you can develop advanced actions. For example, you can develop actions that synchronize user information between two or more databases. In the advanced interface, a JPanel is used and graphical components can be added. The following screen shot shows an action group in the advanced interface.

Writing an Action Plug-in: Simple configuration example

To write a simple action plug-in, implement the following interface in a new class or use the sample code classes as templates: se.nordicedge.AAMV3Interface. To assist you, this section includes the following two topics:

AAMV3Interface Methods Used in Sample Code — Summarizes the primary AAMV3Interface methods used by the sample code written for a simple action plugin.

Summary of Sample Code for Simple Configuration — Summarizes the runPlugin method that is called when the action is invoked. This method is where you place your code.

For instructions on how to download the sample code, see earlier section Import Custom Java Code. To view the Javadoc and Java classes, visit: http://download.nordicedge.se/download/aam/javadoc/

AAMV3Interface Methods used in sample code

The following section includes the primary AAMV3Interface methods used in the sample Java code for a simple action plug-in:

getDescription
Type: String
Description: Returns a brief description of the plug-in’s function.

getIconName
Type: String
Description: Returns the name of the image file.
Note: Set the icon size to 16×16 pixels. Supported image formats include BMP,JPG, and PNG.

getName
Type: String
Description: Returns the display name that is used in AAM Studio.

getSimpleConfigParameters
Type: Vector
Description: Returns configuration parameters. Each vector element represents a parameter using a string array.
Example: String[] sArray0 = new String[] {“Session Attribute Containing Givenname [MANDATORY]”, “LDAP-ATTRIBUTE”, “Attribute of the incoming session object which contains the value to be manipulated. Example: givenName”};

getType
Type: String
Description: Returns the plug-in type. The type is used when creating a new instance of the action in AAM.
Note: The type is a unique identifier. Do not modify its value after the plug-in is released for production.

getUsage
Type: Boolean[]
Description: Returns the action’s type, as follows.

getVersion
Type: Float
Description: Returns the version number of the action.

runPlugin
Type: Boolean
Description: This method is called when the action is invoked. Place your code here.

setConfigPanel
Type: Boolean
Description: Returns TRUE when the configuration is advanced and FALSE when the configuration is simple.
Value: FALSE

Summary of sample code for simple configuration

The following steps and comments summarize the sample code for a simple action plug-in. For instructions on how to download the complete sample code, see earlier section Import Custom Java Code. To view more information about the AAMV3Interface methods used in the code, visit: http://download.nordicedge.se/download/aam/javadoc/.

1. Check for search results. If there are search results, then continue. If there are no
search results, then end the action and return a TRUE value.
if (results == null || results.size() == 0){
NELogger.debug(“No session objects available.”);
return Boolean.TRUE; // End the action.
}

2.Get the parameters.
String saContainingGivenname = action.getParameterValue(0, “”);
// No default value is specified and therefor the setting is MANDATORY.
String saNameForStatus = action.getParameterValue(1, “status”);
// “status” is the the default value.

3. Check the parameters.
if (saContainingGivenname.trim().equalsIgnoreCase(“”)){
NELogger.error(“ERROR: The ‘Session Attribute Containing Givenname’ is
unset. Please enter a session attribute which contains the given name.
Example: givenName”);
return Boolean.FALSE;
}

4. Loop through all session objects in the search result.
for (int xx = 0; xx < results.size(); xx++){
// Get the session object.
SessionObject currentSessionObject = (SessionObject) results.get(xx);
// Get the session attribute for given name.
SessionAttribute saGivenname =
currentSessionObject.getSessionAttribute(saContainingGivenname);
String givenName = “”;
boolean success = Boolean.FALSE;
if (saGivenname != null){
// Get the value from the session attribute.
givenName = saGivenname.getValue();
if (givenName == null || givenName.isEmpty()){
NELogger.debug(currentSessionObject.getName() + ” has no value in
attribute: ” + saContainingGivenname);
} else {
// Manipulate the incoming data (given name) as desired.
// In this example the given name is reversed.
StringBuffer sBuf = new StringBuffer(givenName);
givenName = sBuf.reverse().toString();
// Set the session attribute with the manipulated data.
saGivenname.setValue(givenName);
success = Boolean.TRUE;
}
} else {
NELogger.error(currentSessionObject.getName() + ” is missing
attribute: ” + saContainingGivenname);
}
/*
In this example a session status attribute containing a result string is added to the session.
SUCCESS or FAILURE is set depending on the result.
*/
SessionAttribute saStatus = new SessionAttribute();
saStatus.setName(saNameForStatus);
if (success){
saStatus.setValue(“SUCCESS”);
} else {
saStatus.setValue(“FAILURE”);
}
saStatus.setHasBeenEdited(true);
currentSessionObject.addSessionAttribute(saStatus);
}
return Boolean.TRUE; //Success

Writing an Plug-in: Advanced configurarion example

To write an advanced action plug-in, implement the following interface in a new class or use the sample code classes as templates: se.nordicedge.AAMV3Interface. To assist you, this section includes the following two topics:

AAMV3Interface Methods Used in Sample Code — Summarizes the primary AAMV3Interface methods used by the sample code written for an advanced action plug-in.

Summary of Sample Code for Advanced Configuration — Summarizes the runPlugin method that is called when the action is invoked. This method is where you place your code.

For instructions on how to download the sample code, see earlier section Import Custom Java Code. To view the Javadoc and Java classes, visit:
http://download.nordicedge.se/download/aam/javadoc/

AAMV3Interface methods used in sample code

The following section includes the primary AAMV3Interface methods used in the sample Java code for an advanced action plug-in:

getDescription
Type: String
Description: Returns a brief description of the plug-in’s function.

getIconName
Type: String
Description: Returns the name of the image file.
Note: Set the icon size to 16×16 pixels. Supported image formats include BMP,JPG, and PNG.

getName
Type: String
Description: Returns the display name that is used in AAM Studio.

getSimpleConfigParameters
Type: Vector
Description: Returns null.

getUsage
Type: Boolean[]
Description: Returns the action’s type, as follows.

getVersion
Type: Float
Description: Returns the version number of the action.

runPlugin
Type: Boolean
Description: This method is called when the action is invoked. Place your code here.

setAction
Type: void
Description: Sets the action object that stores information for this action. To extract the parameter values, use action.getParameterValue.

setConfigPanel
Type: Boolean
Description: Returns TRUE when the configuration is advanced and FALSE when the configuration is simple.
Value: TRUE

Summary of sample code for advanced configuration

The following steps and comments summarize the sample code for an advanced action plug-in. For instructions on how to download the complete sample code, see erlaier section Import Custom Java Code. To view more information about the AAMV3Interface methods used in the code, visit: http://download.nordicedge.se/download/aam/javadoc/.

1. Check for search results. If there are search results, then continue. If there are no search results, then end the action and return a TRUE value.
if (results == null || results.size() == 0){
NELogger.debug(“No session objects available.”);
return Boolean.TRUE; // End the action.
}

2. Get the parameters.
String sessionAttribName = action.getParameterValue(0, “”);
boolean copyToNewAttribute = action.getParameterValue(1, false);

3. Check the parameters.
if (sessionAttribName.trim().equalsIgnoreCase(“”)){
NELogger.error(“ERROR: The ‘Session Attribute Name’ is unset. Please
enter a session attribute name which contains a string value. Example:
givenName”);
return Boolean.FALSE;
}

4. Loop through all session objects in the search result.
for(int xx=0; xx < results.size(); xx++){
// Get the session object.
SessionObject sessionObj = (SessionObject) results.get(xx);
// Get the session attribute from sessionAttribName.
SessionAttribute sessionAttrib =
sessionObj.getSessionAttribute(sessionAttribName);
if(sessionAttrib != null){
// The session object has the attribute.
String s = sessionAttrib.getValue();
StringBuffer sBuf = new StringBuffer(s);
s = sBuf.reverse().toString();
// If checked, add a new session attribute to the session object.
if(copyToNewAttribute){
SessionAttribute newSessionAttrib = new SessionAttribute();
newSessionAttrib.setName(“New-“+sessionAttribName);
newSessionAttrib.setValue(s);
newSessionAttrib.setHasBeenEdited(true);
sessionObj.addSessionAttribute(newSessionAttrib);
}else{
sessionAttrib.setValue(s);
sessionAttrib.setHasBeenEdited(true);
}
}
}
return Boolean.TRUE; //Success