ConfigurablePerLinkFilter

This interface allows a Filter to have multiple configurations applied to it on a given Link that are independent of any particular Mapping. If you need configurations that are different for a given Mapping, look at ConfigurablePerMappingFilter.

Users can set up multiple configurations for your Filter on a single Link, so you’ll notice that setFilterConfigurations() accepts a collection of serialized configurations and you should be prepared to apply each one to records.

Each actual String configuration value is whatever you need it to be. Most commonly it is a serialized JSON object of key-value pairs, but you are not locked into using that pattern.

Note

For a deeper look at configurable extensions in Valence, read our guide on Configurability.

Definition

/**
 * Implementing this interface means your Filter is capable of being configured.
 */
global interface ConfigurablePerLinkFilter extends TransformationFilter {

        /**
         * You can use your own Lightning component to let Users build and edit your configuration. If you want to do this, return the fully qualified
         * name of your component, which looks like this:
         *
         * valence:MyAwesomeAdapterConfigurator
         *
         * Make sure your component is set to global so that Valence can instantiate it.
         *
         * @return The name of your Lightning component that will handle configuration, or null if you don't need your own component
         */
        String getFilterConfigurationLightningComponent();

        /**
         * If you don't need or don't want to use your own Lightning Component, you can simply describe your configuration shape and we will present
         * the user with some basic input fields to populate values in your configuration.
         *
         * @return A serialized JSON object describing your configuration data structure, or null if you use your own component
         */
        String getFilterConfigurationStructure();

        /**
         * Given configuration data, return a user-friendly paragraph that explains how this specific configuration
         * is going to be used by your Filter and what effect that will have on the Record.
         *
         * We show this in the user interface to help Users understand the impact of their configurations.
         *
         * @param configurationData The raw configuration for your Filter
         *
         * @return A human-readable and friendly explanation that specifically reflects and explains the configuration passed.
         */
        String explainFilterConfiguration(String configurationData);

        /**
         * Sets configuration data for your Filter. This is the first method called on your Filter during Link execution. User might configure your Filter multiple
         * times (for example, setting two different constants for a Filter that sets constants), so you are passed a list of configurations.
         *
         * @param context Information about this Link and the current execution of it.
         * @param configurationData List of configuration data in JSON format, or in whatever format your custom configuration component gave us
         */
        void setFilterConfigurations(LinkContext context, List<String> configurationData);
}

Example - Access Configurations

private List<FilterConfiguration> configs = new List<FilterConfiguration>();

public void setFilterConfigurations(valence.LinkContext context, List<String> configurationData) {
        configs.clear();
        for(String configData : configurationData) {
                configs.add(interpretConfigData(configData));
        }
}

public void process(valence.LinkContext context, List<valence.RecordInFlight> records) {

        // do work on the records using our configurations
        for(valence.RecordInFlight record : records) {
                for(FilterConfiguration config : configs) {
                        record.setOriginalPropertyValue(config.fieldName, config.value);
                }
        }
}

private static FilterConfiguration interpretConfigData(String data) {
        return String.isBlank(data) ? new FilterConfiguration() : (FilterConfiguration)JSON.deserialize(data, FilterConfiguration.class);
}

private class FilterConfiguration {
        String fieldName;
        String value;
}