Talend Component Kit Developer Reference Guide :: Talend Component Kit Reference guide

Widget and validation gallery

This gallery shows how widgets and validations are rendered in both Studio and web environments, along with sample implementation code.

You can also find sample working components for each of the configuration cases below:

ActiveIf: Add visibility conditions on some configurations.
Checkbox: Add checkboxes or toggles to your component.
Code: Allow users to enter their own code.
Credential: Mark a configuration as sensitive data to avoid displaying it as plain text.
Datastore: Add a button allowing to check the connection to a datastore.
Datalist: Two ways of implementing a dropdown list with predefined choices.
Integer: Add numeric fields to your component configuration.
Min/Max: Specify a minimum or a maximum value for a numeric configuration.
Multiselect: Add a list and allow users to select multiple elements of that list.
Pattern: Enforce rules based on a specific a pattern to prevent users from entering invalid values.
Required: Make a configuration mandatory.
Suggestions: Suggest possible values in a field based on what the users are entering.
Table: Add a table to your component configuration.
Textarea: Add a text area for configurations expecting long texts or values.
Input: Add a simple text input field to the component configuration
Update: Provide a button allowing to fill a part of the component configuration based on a service.
Validation: Specify constraints to make sure that a URL is well formed.

Widgets

Widgets allow to easily implement different types of input fields to your components.

Input/Text

@Option
String config;

Studio Rendering	Web Rendering

Password

@Option
@Credential
String config;

Studio Rendering	Web Rendering

Textarea

@Option
@Textarea
String config;

Studio Rendering	Web Rendering

Integer

@Option
@Documentation("This is a number")
public Integer number;

Studio Rendering	Web Rendering

Checkbox

@Option
Boolean config;

Studio Rendering	Web Rendering

Datetime

Datetime fields rely on the Java Date Time API, including LocalTime, LocalDate, LocalDateTime and ZonedDateTime classes.

@Option
LocalDateTime startTime;

Studio Rendering	Web Rendering

List

@Option
@Proposable("valuesProvider")
String config;
/** service class */
@DynamicValues("valuesProvider")
public Values actions(){
  return new Values(asList(new Values.Item("1", "Delete"),
                    new Values.Item("2", "Insert"),
                    new Values.Item("3", "Update")));
}

@Option
ActionEnum config;

/** Define enum */
enum ActionEnum {
    Delete,
    Insert,
    Update
}

Studio Rendering	Web Rendering

Suggestions

@Option
@Suggestable(value = "loadModules", parameters = { "myconfig" })
@Documentation("module names are loaded using service")
public String moduleName;


// In Service class
@Suggestions("loadModules")
public SuggestionValues loadModules(@Option final MyConfig myconfig) { }

Studio Rendering	Web Rendering

Table

@Option
List<MyObject> config;

Studio Rendering	Web Rendering

Code

@Code("java")
@Option
String config;

Studio Rendering	Web Rendering

Schema

@Option
@Structure
List<String> config;

Studio Rendering	Web Rendering

Validations

Validations help restricting what can be entered or selected in an input field, to make sure that the value complies with the expected type of information.

Property validation

/** configuration class */
@Option
@Validable("url")
String config;

/** service class */
@AsyncValidation("url")
ValidationResult doValidate(String url) {
//validate the property
}

Studio Rendering	Web Rendering

Property validation with Pattern

/** configuration class */
@Option
@Pattern("/^[a-zA-Z\\-]+$/")
String username;

Studio Rendering	Web Rendering

Data store validation

@Datastore
@Checkable
public class config {
/** config ...*/
}

/** service class */
@HealthCheck
public HealthCheckStatus testConnection(){

//validate the connection
}

Studio Rendering	Web Rendering

You can also use other types of validation that are similar to @Pattern:

@Min, @Max to specify a minimum and maximum value for numerical fields.
@Uniques for collection values.
@Required for a required configuration.

Actions

Close Connection

Mark an action works for closing runtime connection, returning a close helper object which do real close action. The functionality is for the Studio only, studio will use the close object to close connection for existed connection, and no effect for cloud platform.

Type: close_connection
API: @org.talend.sdk.component.api.service.connection.CloseConnection
Returned type: org.talend.sdk.component.api.service.connection.CloseConnectionObject
Sample:

{
 "connection": "..."
}

Create Connection

Mark an action works for creating runtime connection, returning a runtime connection object like jdbc connection if database family. Its parameter MUST be a datastore. Datastore is configuration type annotated with @DataStore. The functionality is for the Studio only, studio will use the runtime connection object when use existed connection, and no effect for cloud platform.

Type: create_connection
API: @org.talend.sdk.component.api.service.connection.CreateConnection

Discoverdataset

This class marks an action that explore a connection to retrieve potential datasets.

Type: discoverdataset
API: @org.talend.sdk.component.api.service.discovery.DiscoverDataset
Returned type: org.talend.sdk.component.api.service.discovery.DiscoverDatasetResult
Sample:

{
 "datasetDescriptionList": "..."
}

Dynamic Dependencies

Mark a method as returning a list of dynamic dependencies with GAV formatting.

Type: dynamic_dependencies
API: @org.talend.sdk.component.api.service.dependency.DynamicDependencies
Returned type: java.util.List
Sample:

{

}

Dynamic Values

Mark a method as being useful to fill potential values of a string option for a property denoted by its value. You can link a field as being completable using @Proposable(value). The resolution of the completion action is then done through the component family and value of the action. The callback doesn’t take any parameter.

Type: dynamic_values
API: @org.talend.sdk.component.api.service.completion.DynamicValues
Returned type: org.talend.sdk.component.api.service.completion.Values
Sample:

{
  "items":[
    {
      "id":"value",
      "label":"label"
    }
  ]
}

Healthcheck

This class marks an action doing a connection test

Type: healthcheck
API: @org.talend.sdk.component.api.service.healthcheck.HealthCheck
Returned type: org.talend.sdk.component.api.service.healthcheck.HealthCheckStatus
Sample:

{
  "comment":"Something went wrong",
  "status":"KO"
}

Schema

Mark an action as returning a discovered schema. Its parameter MUST be a dataset. Dataset is configuration type annotated with @DataSet. If component has multiple datasets, then dataset used as action parameter should have the same identifier as this @DiscoverSchema.

Type: schema
API: @org.talend.sdk.component.api.service.schema.DiscoverSchema
Returned type: org.talend.sdk.component.api.record.Schema
Sample:

{
  "entries":[
    {
      "comment":"The column 1",
      "metadata":false,
      "name":"column1",
      "nullable":false,
      "props":{

      },
      "rawName":"column 1",
      "type":"STRING"
    },
    {
      "comment":"The int column",
      "metadata":false,
      "name":"column2",
      "nullable":false,
      "props":{

      },
      "rawName":"column 2",
      "type":"INT"
    }
  ],
  "metadata":[
  ],
  "props":{
    "talend.fields.order":"column1,column2"
  },
  "type":"RECORD"
}

Schema Extended

Mark a method as returning a Schema resulting from a connector configuration and some other parameters.Parameters can be an incoming schema and/or an outgoing branch.`value' name should match the connector’s name.

Type: schema_extended
API: @org.talend.sdk.component.api.service.schema.DiscoverSchemaExtended
Returned type: org.talend.sdk.component.api.record.Schema
Sample:

{
  "entries":[
    {
      "comment":"The column 1",
      "metadata":false,
      "name":"column1",
      "nullable":false,
      "props":{

      },
      "rawName":"column 1",
      "type":"STRING"
    },
    {
      "comment":"The int column",
      "metadata":false,
      "name":"column2",
      "nullable":false,
      "props":{

      },
      "rawName":"column 2",
      "type":"INT"
    }
  ],
  "metadata":[
  ],
  "props":{
    "talend.fields.order":"column1,column2"
  },
  "type":"RECORD"
}

Suggestions

Mark a method as being useful to fill potential values of a string option. You can link a field as being completable using @Suggestable(value). The resolution of the completion action is then done when the user requests it (generally by clicking on a button or entering the field depending the environment).

Type: suggestions
API: @org.talend.sdk.component.api.service.completion.Suggestions
Returned type: org.talend.sdk.component.api.service.completion.SuggestionValues
Sample:

{
  "cacheable":false,
  "items":[
    {
      "id":"value",
      "label":"label"
    }
  ]
}

Update

This class marks an action returning a new instance replacing part of a form/configuration.

Type: update
API: @org.talend.sdk.component.api.service.update.Update

User

Extension point for custom UI integrations and custom actions.

Type: user
API: @org.talend.sdk.component.api.service.Action

Validation

Mark a method as being used to validate a configuration.

this is a server validation so only use it if you can’t use other client side validation to implement it.

Type: validation
API: @org.talend.sdk.component.api.service.asyncvalidation.AsyncValidation
Returned type: org.talend.sdk.component.api.service.asyncvalidation.ValidationResult
Sample:

{
  "comment":"Something went wrong",
  "status":"KO"
}

Built In Actions

These actions are provided - or not - by the application the UI runs within.

always ensure you don’t require this action in your component.

built_in_suggestable

Mark the decorated field as supporting suggestions, i.e. dynamically get a list of valid values the user can use. It is however different from @Suggestable by looking up the implementation in the current application and not the services. Finally, it is important to note that it can do nothing in some environments too and that there is no guarantee the specified action is supported.

API: @org.talend.sdk.component.api.configuration.action.BuiltInSuggestable

Conditions

ActiveIf

If the evaluation of the element at the location matches value then the element is considered active, otherwise it is deactivated.

API: @org.talend.sdk.component.api.configuration.condition.ActiveIf
Type: if
Sample:

{
  "condition::if::evaluationStrategy":"DEFAULT",
  "condition::if::negate":"false",
  "condition::if::target":"test",
  "condition::if::value":"value1,value2"
}

ActiveIfs

Allows to set multiple visibility conditions on the same property.

API: @org.talend.sdk.component.api.configuration.condition.ActiveIfs
Type: ifs
Sample:

{
  "condition::if::evaluationStrategy::0":"DEFAULT",
  "condition::if::evaluationStrategy::1":"LENGTH",
  "condition::if::negate::0":"false",
  "condition::if::negate::1":"true",
  "condition::if::target::0":"sibling1",
  "condition::if::target::1":"../../other",
  "condition::if::value::0":"value1,value2",
  "condition::if::value::1":"SELECTED",
  "condition::ifs::operator":"AND"
}

Configuration types

Dataset

Mark a model (complex object) as being a dataset.

API: @org.talend.sdk.component.api.configuration.type.DataSet
Sample:

{
  "tcomp::configurationtype::name":"test",
  "tcomp::configurationtype::type":"dataset"
}

Datastore

Mark a model (complex object) as being a datastore (connection to a backend).

API: @org.talend.sdk.component.api.configuration.type.DataStore
Sample:

{
  "tcomp::configurationtype::name":"test",
  "tcomp::configurationtype::type":"datastore"
}

DatasetDiscovery

Mark a model (complex object) as being a dataset discovery configuration.

API: @org.talend.sdk.component.api.configuration.type.DatasetDiscovery
Sample:

{
  "tcomp::configurationtype::name":"test",
  "tcomp::configurationtype::type":"datasetDiscovery"
}

Constraints

MaxLength

Ensure the decorated option size is validated with a higher bound.

API: @org.talend.sdk.component.api.configuration.constraint.Max
Name: maxLength
Parameter Type: double
Supported Types: — java.lang.CharSequence
Sample:

{
  "validation::maxLength":"12.34"
}

MinLength

Ensure the decorated option size is validated with a lower bound.

API: @org.talend.sdk.component.api.configuration.constraint.Min
Name: minLength
Parameter Type: double
Supported Types: — java.lang.CharSequence
Sample:

{
  "validation::minLength":"12.34"
}

Pattern

Validate the decorated string with a javascript pattern (even into the Studio).

API: @org.talend.sdk.component.api.configuration.constraint.Pattern
Name: pattern
Parameter Type: java.lang.string
Supported Types: — java.lang.CharSequence
Sample:

{
  "validation::pattern":"test"
}

Max

Ensure the decorated option size is validated with a higher bound.

API: @org.talend.sdk.component.api.configuration.constraint.Max
Name: max
Parameter Type: double
Supported Types: — java.lang.Number — int — short — byte — long — double — float
Sample:

{
  "validation::max":"12.34"
}

Min

Ensure the decorated option size is validated with a lower bound.

API: @org.talend.sdk.component.api.configuration.constraint.Min
Name: min
Parameter Type: double
Supported Types: — java.lang.Number — int — short — byte — long — double — float
Sample:

{
  "validation::min":"12.34"
}

Required

Mark the field as being mandatory.

API: @org.talend.sdk.component.api.configuration.constraint.Required
Name: required
Parameter Type: -
Supported Types: — java.lang.Object
Sample:

{
  "validation::required":"true"
}

MaxItems

Ensure the decorated option size is validated with a higher bound.

API: @org.talend.sdk.component.api.configuration.constraint.Max
Name: maxItems
Parameter Type: double
Supported Types: — java.util.Collection
Sample:

{
  "validation::maxItems":"12.34"
}

MinItems

Ensure the decorated option size is validated with a lower bound.

API: @org.talend.sdk.component.api.configuration.constraint.Min
Name: minItems
Parameter Type: double
Supported Types: — java.util.Collection
Sample:

{
  "validation::minItems":"12.34"
}

UniqueItems

Ensure the elements of the collection must be distinct (kind of set).

API: @org.talend.sdk.component.api.configuration.constraint.Uniques
Name: uniqueItems
Parameter Type: -
Supported Types: — java.util.Collection
Sample:

{
  "validation::uniqueItems":"true"
}

Junit environments

the configuration is read from system properties, environment variables, ….

Contextual: _class: ContextualEnvironment.
Direct: _class: DirectRunnerEnvironment.
Flink: _class: FlinkRunnerEnvironment.
Spark: _class: SparkRunnerEnvironment.

Scanning

Package Scanning

Since the framework can be used in the case of fatjars or shades, and because it still uses scanning, it is important to ensure we don’t scan the whole classes for performances reason.

Therefore, the following packages are ignored:

it is not recommanded but possible to add in your plugin module a TALEND-INF/scanning.properties file with classloader.includes and classloader.excludes entries to refine the scanning with custom rules. In such a case, exclusions win over inclusions.

Server configuration

the configuration is read from system properties, environment variables, ….

talend.component.server.cache.maxSize

Default value: 1000. Maximum items a cache can store, used for index endpoints.

talend.component.server.component.coordinates

A comma separated list of gav to locate the components

talend.component.server.component.documentation.translations

Default value: ${home}/documentations. A component translation repository. This is where you put your documentation translations. Their name must follow the pattern documentation_${container-id}_language.adoc where ${container-id} is the component jar name (without the extension and version, generally the artifactId).

talend.component.server.component.extend.dependencies

Default value: true. Should the component extensions add required dependencies.

talend.component.server.component.extension.maven.repository

If you deploy some extension, where they can create their dependencies if needed.

talend.component.server.component.extension.startup.timeout

Default value: 180000. Timeout for extension initialization at startup, since it ensures the startup wait extensions are ready and loaded it allows to control the latency it implies.

talend.component.server.component.registry

A property file (or multiple comma separated) where the value is a gav of a component to register(complementary with coordinates). Note that the path can end up with or .properties to take into account all properties in a folder.

talend.component.server.documentation.active

Default value: true. Should the /documentation endpoint be activated. Note that when called on localhost the doc is always available.

talend.component.server.environment.active

Default value: true. Should the /api/v1/environment endpoint be activated. It shows some internal versions and git commit which are not always desirable over the wire.

talend.component.server.gridlayout.translation.support

Default value: false. Should the components using a @GridLayout support tab translation. Studio does not suppot that feature yet so this is not enabled by default.

talend.component.server.icon.paths

Default value: icons/%s.svg,icons/svg/%s.svg,icons/%s_icon32.png,icons/png/%s_icon32.png. These patterns are used to find the icons in the classpath(s).

talend.component.server.icon.theme.default

Default value: light. Icon default theme (light/dark).

talend.component.server.icon.theme.legacy

Default value: true. Do we support legacy (not themed) icons. If true, lookup will be done if not themed icon found.

talend.component.server.icon.theme.support

Default value: true. Do we support icons theme.

talend.component.server.jaxrs.exceptionhandler.defaultMessage

Default value: false. If set it will replace any message for exceptions. Set to false to use the actual exception message.

talend.component.server.lastUpdated.useStartTime

Default value: false. Should the lastUpdated timestamp value of /environment endpoint be updated with server start time.

talend.component.server.locale.mapping

Default value: en*=en fr*=fr zh*=zh_CN ja*=ja de*=de. For caching reasons the goal is to reduce the locales to the minimum required numbers. For instance we avoid fr and fr_FR which would lead to the same entries but x2 in terms of memory. This mapping enables that by whitelisting allowed locales, default being en. If the key ends with it means all string starting with the prefix will match. For instance fr will match fr_FR but also fr_CA.

talend.component.server.maven.repository

The local maven repository used to locate components and their dependencies

talend.component.server.plugins.reloading.active

Default value: false. Should the plugins be un-deployed and re-deployed.

talend.component.server.plugins.reloading.interval

Default value: 600. Interval in seconds between each check if plugins re-loading is enabled.

talend.component.server.plugins.reloading.marker

Specify a file to check its timestamp on the filesystem. This file will take precedence of the default ones provided by the talend.component.server.component.registry property (used for timestamp method).

talend.component.server.plugins.reloading.method

Default value: timestamp. Re-deploy method on a timestamp or connectors version change. By default, the timestamp is checked on the file pointed by talend.component.server.component.registry or talend.component.server.plugins.reloading.marker variable, otherwise we inspect the content of the CONNECTORS_VERSION file. Accepted values: timestamp, anything else defaults to connectors.

talend.component.server.request.log

Default value: false. Should the all requests/responses be logged (debug purposes - only work when running with CXF).

talend.component.server.security.command.handler

Default value: securityNoopHandler. How to validate a command/request. Accepted values: securityNoopHandler.

talend.component.server.security.connection.handler

Default value: securityNoopHandler. How to validate a connection. Accepted values: securityNoopHandler.

talend.component.server.user.extensions.location

A folder available for the server - don’t forget to mount it in docker if you are using the image - which accepts subfolders named as component plugin id (generally the artifactId or jar name without the version, ex: jdbc). Each family folder can contain:

a user-configuration.properties file which will be merged with component configuration system (see services). This properties file enables the function userJar(xxxx) to replace the jar named xxxx by its virtual gav (groupId:artifactId:version),
a list of jars which will be merged with component family classpath

talend.component.server.user.extensions.provisioning.location

Default value: auto. Should the implicit artifacts be provisionned to a m2. If set to auto it tries to detect if there is a m2 to provision - recommended, if set to skip it is ignored, else it uses the value as a m2 path.

User Interface API

@DefaultValue

Provide a default value the UI can use - only for primitive fields.

API: @org.talend.sdk.component.api.configuration.ui.DefaultValue

Snippets

{
  "ui::defaultvalue::value":"test"
}

@Hidden

Mark an @Option as being hidden.

API: @org.talend.sdk.component.api.configuration.ui.Hidden

Snippets

{
  "ui::hidden":"true"
}

@OptionsOrder

Allows to sort a class properties.

API: @org.talend.sdk.component.api.configuration.ui.OptionsOrder

Snippets

{
  "ui::optionsorder::value":"value1,value2"
}

@AutoLayout

Request the rendered to do what it thinks is best.

API: @org.talend.sdk.component.api.configuration.ui.layout.AutoLayout

Snippets

{
  "ui::autolayout":"true"
}

@GridLayout

Advanced layout to place properties by row, this is exclusive with @OptionsOrder.

the logic to handle forms (gridlayout names) is to use the only layout if there is only one defined, else to check if there are Main and Advanced and if at least Main exists, use them, else use all available layouts.

API: @org.talend.sdk.component.api.configuration.ui.layout.GridLayout

Snippets

{
  "ui::gridlayout::value1::value":"first|second,third",
  "ui::gridlayout::value2::value":"first|second,third"
}

@GridLayouts

Allow to configure multiple grid layouts on the same class, qualified with a classifier (name)

API: @org.talend.sdk.component.api.configuration.ui.layout.GridLayouts

Snippets

{
  "ui::gridlayout::Advanced::value":"another",
  "ui::gridlayout::Main::value":"first|second,third"
}

@HorizontalLayout

Put on a configuration class it notifies the UI an horizontal layout is preferred.

API: @org.talend.sdk.component.api.configuration.ui.layout.HorizontalLayout

Snippets

{
  "ui::horizontallayout":"true"
}

@VerticalLayout

Put on a configuration class it notifies the UI a vertical layout is preferred.

API: @org.talend.sdk.component.api.configuration.ui.layout.VerticalLayout

Snippets

{
  "ui::verticallayout":"true"
}

@BasedOnSchema

Mark a table column filled by component’s schema auto. Only for studio.

API: @org.talend.sdk.component.api.configuration.ui.widget.BasedOnSchema

Snippets

{
  "ui::basedonschema":"true"
}

@Code

Mark a field as being represented by some code widget (vs textarea for instance).

API: @org.talend.sdk.component.api.configuration.ui.widget.Code

Snippets

{
  "ui::code::value":"test"
}

@Credential

Mark a field as being a credential. It is typically used to hide the value in the UI.

API: @org.talend.sdk.component.api.configuration.ui.widget.Credential

Snippets

{
  "ui::credential":"true"
}

@DateTime

Mark a field as being a date. It supports and is implicit - which means you don’t need to put that annotation on the option - for java.time.ZonedDateTime, java.time.LocalDate and java.time.LocalDateTime and is unspecified for other types.

API: @org.talend.sdk.component.api.configuration.ui.widget.DateTime

Snippets

{
  "ui::datetime":"time",
  "ui::datetime::useSeconds":"false"
}

{
  "ui::datetime":"date",
  "ui::datetime::dateFormat":"test"
}

{
  "ui::datetime":"datetime",
  "ui::datetime::dateFormat":"test",
  "ui::datetime::useSeconds":"false",
  "ui::datetime::useUTC":"false"
}

{
  "ui::datetime":"zoneddatetime",
  "ui::datetime::dateFormat":"test",
  "ui::datetime::useSeconds":"false",
  "ui::datetime::useUTC":"false"
}

@ModuleList

Mark a string field as being represented by selected module list widget, only for studio

API: @org.talend.sdk.component.api.configuration.ui.widget.ModuleList

Snippets

{
  "ui::modulelist":"true"
}

@Path

Mark a option as being represented by file or directory widget. Only for studio.

API: @org.talend.sdk.component.api.configuration.ui.widget.Path

Snippets

{
  "ui::path::value":"null"
}

@ReadOnly

Mark a option as being read-only widget. User cannot modify widget.

API: @org.talend.sdk.component.api.configuration.ui.widget.ReadOnly

Snippets

{
  "ui::readonly":"true"
}

@Structure

Mark a List<String> or List<Object> field as being represented as the component data selector.

API: @org.talend.sdk.component.api.configuration.ui.widget.Structure

Snippets

{
  "ui::structure::discoverSchema":"test",
  "ui::structure::type":"IN",
  "ui::structure::value":"test"
}

@TextArea

Mark a field as being represented by a textarea(multiline text input).

API: @org.talend.sdk.component.api.configuration.ui.widget.TextArea

Snippets

{
  "ui::textarea":"true"
}