ConfigurablePerMappingFilter

This interface allows a Filter to have a configuration applied to it that is different for each Mapping on the Link. This allows an admin to make the Filter behavior differently for each Mapping, or skip certain Mappings. If you need configurations that aren’t tied to a particular Mapping, look at ConfigurablePerLinkFilter.

This interface follows our normal pattern for a configurable extension in Valence, with a slight variation: instead of a setConfiguration method, you can find the configuration for each mapping on the Mapping itself that you get inside a LinkContext. The LinkContext is tailored to each Filter that is called, so the mappings will have configurations for just your Filter, or nothing. See an example of how to access these configurations below.

The 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 per-Mapping. The configurations
 * for the mappings will be fed to your Filter when it receives RecordInFlight records to process.
 */
global interface ConfigurablePerMappingFilter 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 getMappingConfigurationLightningComponent();

    /**
     * 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 getMappingConfigurationStructure();

    /**
     * Given mapping 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 configuration The raw configuration for a specific mapping
     *
     * @return A human-readable and friendly explanation that specifically reflects and explains the configuration passed.
     */
    String explainMappingConfiguration(String configuration);
}

Example - Access Configurations

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

    // extract mappings from the context object
    List<valence.Mapping> mappings = context.mappings.values();

    // look for configurations
    for(valence.Mapping mapping : mappings) {
        if(String.isNotBlank(mapping.configuration)) {
            // this mapping has a configuration for your filter
        }
    }
}