About IAS annotations

The IAS Extension API provides Java annotations that define extensions to the Integrator Acquisition System and also define configuration properties for an extension. Annotations can describe whether configuration properties are required or optional, whether they have a default value, and their display properties in ias-cmd.

Annotations define extensions

An extension requires an annotation of either @IasDataSource or @IasManipulator to indicate whether the extension is a data source or a manipulator.

After an IAS application developer installs a plugin, the Integrator Acquisition System scans for extensions by checking for classes that have an annotation of either @IasDataSource or @IasManipulator and by checking the uniqueness of extension IDs.

Here is an example annotation that defines a data source extension:

@IasDataSource(displayName="CSV File", description="Reads comma separated files")
public class CsvDataSource extends DataSource<CsvDataSourceConfig>

Here is an example annotation that defines a manipulator extension:

@IasManipulator(
		supportsIncrementals=true, 
		deleteRecordsBypassManipulator = true,
		displayName="Substring Manipulator", 
		description="Generates a new property that is a substring of another property value")
public class SubstringManipulator extends Manipulator<SubstringManipulatorConfig>

Annotations define configuration properties for an extension

You annotate a Java field in a PipelineComponentConfiguration class to expose the field as a configuration property for an extension. The fields that you annotate are available to the IAS Server Command-line Utility and the IAS Server API. If you do not annotate a field, IAS Server ignores it.

Each Java field has a IAS annotation that corresponds to the data type of the Java field. Field annotations include the following:

@StringProperty
@BooleanProperty
@DoubleProperty
@IntegerProperty

Annotations contain attributes that specify additional information about a configuration property. This information may control the order in which fields render, default values for the fields, and so on.

Here is an example annotation of two string fields:

@StringProperty(isRequired=true, name="inputFile", displayName="Input File", 
 description="Path to the input csv file e.g. c:\\incoming\\data.csv")
	private String mInputFile;
	
@StringProperty(isRequired=true, name="keyColumn", displayName="Key Column", 
	description="Name of the column with the record key")
	private String mKeyColumn;

Here is an example annotation for a field which is a list of strings (a multi-valued property):

@StringProperty(isRequired=true, name="sourcePropertyList", displayName="Source Property List")
	private List<String> mSourcePropertyList;

Here is an example annotation for an integer field with four attributes:

@IntegerProperty(isRequired=false, name="startIndex", displayName="Substring Start Index", 
			description="Substring start index (zero based)", defaultValue=0)
	private int mStartIndex;

Annotations specify groups and the order of fields in a group

You can annotate an extension to organize a set of fields into a group and specify the order of fields in a group.

The @ConfigurationGroup annotation specifies that the fields contained within it are a group from the perspective of the IAS Server Command-line Utility.

The groupName attribute of @ConfigurationGroup specifies the label for the group, and the propertyOrder attribute specifies the order in which the properties display as output from tasks in IAS Server Command-line Utility. If you omit the propertyOrder attribute, the properties are sorted alphabetically and display alphabetically when returned from ias-cmd.

Here is an example group named User Credentials that defines three configuration properties:

@ConfigurationGroup(groupName="User Credentials", propertyOrder={"userName","userPassword"})

Annotations specify the order of multiple groups of fields

You can annotate an extension to specify the order of multiple groups of fields. As mentioned above, you specify each group with a @ConfigurationGroup annotation. You specify the order of multiple groups with a @ConfigurationGroupOrder annotation.

This may be useful if you want to enforce the order of groups and order of the fields within each group. For example, suppose a data source extension accesses a database. The first group is called User Credentials and it displays a userName property and a userPassword property.

Next you want a second group of fields called Database Settings, and it displays serverName, databasePath, and portNumber.

Last you want a third group called Advanced Settings, and it displays settingA, settingB, and settingC.

This scenario requires the following annotations:

@ConfigurationGroupOrder({
     @ConfigurationGroup(groupName="User Credentials", propertyOrder={
       "userName","userPassword"}) 
     @ConfigurationGroup(groupName="Database settings", propertyOrder={
       "serverName","databasePath","portNumber"}) 
     @ConfigurationGroup(groupName="Advanced Settings", propertyOrder={
       "settingA","settingB","settingC"})})