Defining Connector Attributes

DevKit is compatible only with Studio 6 and Mule 3. To build Mule 4 connectors, see the Mule SDK documentation.

Like all Mule elements, connectors have attributes that can be assigned in the connector’s global configuration dialog. Using DevKit you can define required and optional attributes.

Prerequisites

This document assumes you are familiar with the Anypoint Connector DevKit and you have already covered the connector’s authentication methods.

@Configurable Annotation

The connector’s attributes are defined using the @Configurable annotation, which provide the code that creates the essential fields, at least from a user perspective. Since DevKit 3.7, all @Configurable parameters must be placed inside the "Config" class instead of the @Connector class, which is normally defined in a separate Java file. These attributes are user assigned in the connector’s global configuration dialog, if not set by default. In addition to the @Configurable annotation for each attribute, you need to define public getters and setters for the attributes.

Note: A connector may make use of any number of simple or complex @Configurable attributes you define when writing code for the connector.

Example connector configuration:

<barn:config name="Barn" key="myKey" doc:name="Barn"/>

A dialog box for global element properties

@Optional Annotation

As mentioned before, @Configurable attributes are mandatory. To make an attribute optional, mark with the @Optional annotation.

public abstract class AbstractAnalyticsConfig {

...
  /**
  * Hostname of the proxy. If this property is not set then no proxy is used, otherwise proxy is going to be used but host can not be empty.
  */
  @Configurable
  @Optional
  @Placement(group = "Proxy Settings")
  @FriendlyName(value = "Host")
  private String proxyHost;

  /**
  * Port of the proxy. If host is set then this property has to be set and can not be a negative number.
  */
  @Configurable
  @Optional
  @Default("3128")
  @Placement(group = "Proxy Settings")
  @FriendlyName(value = "Port")
  private Integer proxyPort;
}

XML configuration for a partially complete configuration with some sample proxy settings defined:

A configuration window with fields for connection details, including username, password, authorization URL, and proxy settings

<sfdc-analytics:config name="Salesforce_Analytics_Cloud__Basic_authentication" username="" password="" securityToken="" metadataFileName="" proxyHost="127.3.4.12" proxyUsername="dearuser" proxyPassword="asdfaesfasf" doc:name="Salesforce Analytics Cloud: Basic authentication" proxyPort="3127"/>

If the user does not change the default port number, no information is displayed in the configuration. If changed, for example, to proxyPort="3127" it shows in the connector’s XML configuration (in the sfdc analytics case above, the default port number is "3128").

@Default Annotation

For optional attributes only, you can set a default value using the @Default annotation. This value is used if no value is assigned to the attribute.

For example:

public abstract class AbstractAnalyticsConfig {
    ...
    @Configurable
    @Default("0")
    @Placement(group = "Connection")
    private int connectionTimeout;
    }

Note: Whenever an attribute is marked as @Default, it’s implicitly @Optional as well.

Customizing Attributes Look and Feel

By default, Anypoint DevKit infers the names and labels for the Studio dialog boxes from methods, parameters, JavaDoc comments, and instance variable names in your Java files. However, you can also use annotations to customize many aspects of the look and feel of your component to improve the user experience.

Note: The package org.mule.api.annotations.display defines the annotations that let you perform these customizations.

You can (and should) use several annotations that control how the attribute appears in the connector’s dialog in Studio and in your connector documentation.

@FriendlyName Annotation

Use this annotation on variables and method parameters to override the default inferred nickname for a @Configurable variable or a @Processor/@Source/@Transformer method parameter. Providing a parameter with this annotation is required.

@Connector(name="barn", schemaVersion="1.0", friendlyName="Barn", minMuleVersion="3.6")
public class BarnConnector
{
  ...

A list of connectors with friendly names

@Password Annotation

Use this annotation to identify a field or method parameter as a password or, more generally, as a variable which contains data that should not be displayed as plain text.

    /**
     * Password used to authenticate against the proxy.
     */
    @Configurable
    @Optional
    @Password
    @Placement(group = "Proxy Settings")
    @FriendlyName(value = "Password")
    private String proxyPassword;

@Summary Annotation

Use this annotation on variables and method parameters to override the default inferred description for a @Configurable variable or a @Processor/@Source/@Transformer method parameter.

@Processor
@Summary("This processor puts an animal in the barn")
public String putInBarn(String animal)
{
   return animal + "has been placed in the barn";
}

@Icons Custom Palette and Flow Editor Icons

Use this annotation on the connector class to override the default location of one or more of the required icons. The path needs to be relative to /src/main/java.

@Icons(connectorLarge="barn-icon-large.png", connectorSmall="barn-icon-small.png")
@Connector(name="barn", schemaVersion="1.0", friendlyName="Barn", minMuleVersion="3.6")
public class BarnConnector
{
   ...

@Placement Field Order, Grouping, and Tabs

Use this annotation on variables and method parameters. It accepts the following parameters:

order — The relative order of the annotated element within its group. If the value provided is duplicated then the order of these elements is arbitrarily defined. Value is relative; an element with order 10 has higher precedence than an element with value 25.
group — A logical way to display one or more variables together. If you do not specify a group, then Mule assumes a default group. To place multiple elements in the same group, assign the same values to them for this attribute.
tab — A logical way to group annotated elements together. This attribute specifies the name of the tab in which to display the annotated element. If no tab is specified, then Mule assumes a default tab. To display multiple parameters in the same the tab, assign the same values to them for this attribute.

@Configurable
@Placement(group = "Basic Settings", order = 1)
@FriendlyName("Consumer Key")
private String consumerKey;

@Configurable
@Placement(tab="Advanced Settings", group = "General Information", order = 2)
@Summary("the application name")
@FriendlyName("Application Name")
private String applicationName;

@Configurable
@Placement(group = "Basic Settings", order = 3)
@FriendlyName("Consumer Secret")
@Summary("consumer secret for authentication")
private String consumerSecret;

A global elements properties window on the General tab

A global elements properties window on the Advanced tab