ConfigurableSourceAdapter

This interface allows your Adapter to be configurable by Valence users when it is used as a source Adapter. What “configurable” means is entirely up to you. Maybe you need an additional piece of security information, or perhaps you’re going to let users add restrictions on which records your Adapter fetches.

Allowing users to alter the behavior of your adapter across different Links gives them a lot of flexibility.

Depending on which interfaces you have implemented, your Adapter may be a source adapter, a target adapter, or both. There is a different interface if you want to make your adapter configurable as a target adapter.

The explainConfiguration() method gives you an opportunity to share with users a contextually-aware description of what your configuration is doing. Don’t just describe in abstract what can be configured, but rather use the current configuration values the user has chosen to explain to them what effect this will have on your Adapter.

Note

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

Note

For example usage, see how we allow users to change their upsert field with our example in ConfigurableTargetAdapter.

Definition

/**
 * Implement this interface if you would like your SourceAdapter to be configurable by Users to behave differently for each Link that uses it.
 */
global interface ConfigurableSourceAdapter {

        /**
         * 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.
         *
         * @param context Information about this Link
         *
         * @return The name of your Lightning component that will handle configuration, or null if you don't need your own component
         */
        String getSourceConfigurationLightningComponent(LinkContext context);

        /**
         * 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.
         *
         * @param context Information about this Link
         *
         * @return A serialized JSON object describing your configuration data structure, or null if you use your own component
         */
        String getSourceConfigurationStructure(LinkContext context);

        /**
         * Given configuration data, return a user-friendly paragraph that explains how this specific configuration
         * is going to be used by your class and what effect that will have on the Link being run.
         *
         * We show this in the user interface to help Users understand the impact of their configurations.
         *
         * @param context Information about this Link
         * @param configurationData Configuration data in JSON format, or in whatever format your custom configuration component gave us
         *
         * @return A human-readable and friendly explanation that specifically reflects and explains the configuration passed.
         */
        String explainSourceConfiguration(LinkContext context, String configurationData);

        /**
         * Sets configuration data for your Adapter. This is the first method called on your Adapter during Link execution.
         *
         * @param context Information about this Link and the current execution of it.
         * @param configurationData Configuration data in JSON format, or in whatever format your custom configuration component gave us
         */
        void setSourceConfiguration(LinkContext context, String configurationData);
}