SourceAdapterScopeSerializer

This interface allows Valence to take scopes from your custom SourceAdapterForPull Adapter and place them in temporary storage for later retrieval.

By implementing this interface you unlock several powerful diagnostic and recovery features for end users. For example, with serialized batches if a few batches fail outright during a run (say, they have a read timeout calling an external endpoint), then just those batches can be replayed by using the serialized scopes.

You don’t have to implement this interface. If you do not, retries will still work but not at the batch level; only for individual failed records.

Tip

Valence encrypts serialized scopes at-rest. They are not stored in plain text.

Definition

/**
 * Implementing this interface allows Valence to serialize scopes used to fetch records with your Adapter.
 *
 * This allows some powerful behaviors for end users, such as replaying failed batches and resuming aborted runs.
 */
global interface SourceAdapterScopeSerializer extends SourceAdapterForPull {

        /**
         * Turn an instance of one of your scope objects into a representation that can be easily stored in a database.
         *
         * Valence does NOT store this scope in plaintext.
         *
         * @param scope The scope to serialize
         *
         * @return A persistable representation of your scope instance
         */
        String serializeScope(Object scope);

        /**
         * Take a serialized representation of your object and rehydrate it, creating an actual instance of your scope again.
         *
         * @param serializedScope A serialized representation of a scope that needs to be deserialized
         *
         * @return A rehydrated instance of your scope class
         */
        Object deserializeScope(String serializedScope);
}

Example Usage

Your implementation really never has to get fancier than what is below. You will be asked to turn your scope instances into strings, and then you will be asked later in time to turn those same string values back into scope instances.

public String serializeScope(Object scope) {
    return JSON.serialize(scope);
}

public Object deserializeScope(String serializedScope) {
    return JSON.deserialize(serializedScope, MyScopeClass.class);
}

private MyScopeClass {
    Integer pageNumber;
}