Configuration par étapes

La configuration par étapes permet à un connecteur de renseigner dynamiquement sa configuration en fonction des réponses fournies par l'utilisateur. Par exemple, en renseignant une liste déroulante "Ville" après avoir sélectionné une liste déroulante "État".

Conditions requises

Ce guide suppose que vous connaissez déjà les configurations de connecteurs de la communauté. Pour vous rafraîchir la mémoire, consultez Définir la configuration via getConfig.

Présentation

La configuration par étapes consiste à ce que Data Studio appelle getConfig() plusieurs fois, et que votre connecteur renvoie davantage de questions de configuration à chaque fois. Chaque appel à getConfig() inclura les réponses de l'utilisateur à la dernière réponse getConfig(). Ce processus se poursuit tant que vous renvoyez une réponse avec setIsSteppedConfig(true).

Consignes

Définissez setIsSteppedConfig(true) jusqu'à ce que la configuration soit terminée

Data Studio appellera getConfig() de manière répétée tant que setIsSteppedConfig(true) est défini.Une fois la configuration terminée, la réponse getConfig() finale doit définir setIsSteppedConfig(false).

Définissez isDynamic(true) pour les questions de configuration qui déterminent les questions ultérieures

Si un champ marqué isDynamic est modifié par l'utilisateur, les entrées de configuration suivantes seront effacées dans l'interface utilisateur, et l'utilisateur devra configurer toutes les étapes suivantes. Cela permet de s'assurer que les utilisateurs ne vous envoient pas de configuration non valide.

Les réponses fournies par l'utilisateur seront transmises via request.configParams.

request.configParams sera undefined pour la première requête getConfig() adressée à votre connecteur. Les requêtes suivantes incluront les réponses fournies par l'utilisateur sous la forme d'un objet dont la clé est constituée des ID de configuration ou undefined si l'utilisateur ne fournit aucune réponse.

Exemple :

{
  state: 'CA',
  city: 'mountain_view'
}

Les configurations sont cumulatives

Les nouvelles questions de configuration doivent être ajoutées après celles existantes.

Les configurations ne peuvent pas être modifiées

Si une question de configuration a déjà été posée, elle doit être présente pour tous les appels suivants. Par exemple, si la question de configuration A a été posée lors du premier appel à getConfig(), A doit être incluse dans toutes les réponses futures.

Les configurations sont idempotentes

Les appels à getConfig() avec les mêmes configParams doivent renvoyer la même configuration.

Les paramètres dynamiques ne peuvent pas être ignorés

Data Studio n'autorisera pas l'ignorance des paramètres de configuration dynamiques overridden.

Exemples de configurations

Listes déroulantes dynamiques

Cette première question invite l'utilisateur à sélectionner un état, puis fournit dynamiquement une liste déroulante de villes en fonction de l'état sélectionné.

var cc = DataStudioApp.createCommunityConnector();

function optionsForState(state) {
  switch (state) {
    case "IL": {
      return [["Chicago", "chicago"], ["Springfield", "springfield"]];
    }
    case "CA": {
      return [["Mountain View", "mountain_view"], ["Los Angeles", "los_angeles"]];
    }
    default: {
      cc.newUserError()
          .setText('You must either select "IL" or "CA"')
          .throwException();
    }
  }
}

function getConfig(request) {
  var configParams = request.configParams;
  var isFirstRequest = configParams === undefined;
  var config = cc.getConfig();
  if (isFirstRequest) {
    config.setIsSteppedConfig(true);
  }

  config.newSelectSingle()
      .setId("state")
      .setName("State")
  // Set isDynamic to true so any changes to State will clear the city
  // selections.
      .setIsDynamic(true)
      .addOption(config.newOptionBuilder().setLabel("Illinois").setValue("IL"))
      .addOption(config.newOptionBuilder().setLabel("California").setValue("CA"));

  if (!isFirstRequest) {
    var city = config.newSelectSingle()
        .setId("city")
        .setName("City");
    var cityOptions = optionsForState(configParams.state);
    cityOptions.forEach(function(labelAndValue) {
      var cityLabel = labelAndValue[0];
      var cityValue = labelAndValue[1];
      city.addOption(config.newOptionBuilder().setLabel(cityLabel).setValue(cityValue));
    });
  }
  return config.build();
}

Chemins de branchement

Une question supplémentaire sera posée si le "Pays" sélectionné est "États-Unis".

var cc = DataStudioApp.createCommunityConnector();

function getConfig(request) {
  var configParams = request.configParams;
  var isFirstRequest = configParams === undefined;
  var config = cc.getConfig();
  if (isFirstRequest) {
    config.setIsSteppedConfig(true);
  }

  config
      .newSelectSingle()
      .setId('country')
      .setName('Country')
  // Set isDynamic to true so any changes to Country will clear the state
  // selections.
      .setIsDynamic(true)
      .addOption(config.newOptionBuilder().setLabel('United States').setValue('USA'))
      .addOption(config.newOptionBuilder().setLabel('Canada').setValue('CA'));

  if (!isFirstRequest) {
    // validate a valid value was selected for configParams.country
    if (configParams.country === undefined) {
      cc.newUserError().setText('You must choose a country.').throwException();
    }
    switch (configParams.country) {
      case 'USA': {
        config
            .newSelectSingle()
            .setId('state')
            .setName('State')
            .addOption(config.newOptionBuilder().setLabel('New York').setValue('NY'))
            .addOption(config.newOptionBuilder().setLabel('Calfornia').setValue('CA'));
        break;
      }
      case 'CA': {
        // No additional configuration is needed for Canada.
        break;
      }
      default: {
        cc.newUserError()
            .setText('You must either select "CA" or "USA"')
            .throwException();
      }
    }
  }
  return config.build();
}