Ir para o conteúdo

Variáveis globais no Jitterbit Design Studio

Introdução

Variáveis globais são um dos três tipos de elementos de dados globais disponíveis no Harmony. (Os outros dois tipos de elementos de dados globais—variáveis de projeto e variáveis Jitterbit—também estão disponíveis globalmente em um projeto. Eles são configurados de maneira diferente, conforme descrito em Variáveis de projeto e Variáveis Jitterbit.)

As variáveis globais são primeiramente declaradas em uma operação, após o que se tornam disponíveis para serem referenciadas nas mesmas operações ou scripts subsequentes. Operações ou scripts subsequentes são aqueles que estão vinculados dentro de uma cadeia de operações ou nas funções RunOperation ou RunScript.

As variáveis globais também podem ser usadas como fonte ou destino dentro da operação, conforme descrito em Fonte de variável global e Destino de variável global.

Você pode querer usar variáveis globais se seu caso de uso envolver compartilhar informações com partes subsequentes de uma cadeia de operações, como nos seguintes exemplos:

  • Usar um valor criado em uma transformação em uma transformação posterior. Por exemplo, um ID de sessão (retornado de um serviço web de login) pode ser necessário ao chamar serviços web subsequentes para autenticação.
  • Usar um valor criado em uma parte de uma transformação em uma fase posterior da mesma transformação. Por exemplo, um número de registro pode ser inicializado e incrementado para cada registro inserido em um destino para identificar seu número de item.
  • Usar um valor retornado em uma transformação na configuração de componentes em operações subsequentes. Por exemplo, a configuração de URL retornada por uma transformação pode ser usada para definir a URL do serviço web de uma chamada de serviço web subsequente.

Variáveis globais passam por operações encadeadas. Isso inclui operações que estão vinculadas a uma operação anterior dentro da cadeia de operações usando eventos On Success ou On Failure, assim como aquelas que estão vinculadas através da função RunOperation(). Variáveis globais também podem ser usadas dentro da mesma transformação.

Variáveis globais definidas estão disponíveis na aba Data Elements do construtor de scripts acessível a partir das telas de scripts e transformações.

Criar e atualizar variáveis globais

No Design Studio, variáveis globais são criadas ou atualizadas usando Jitterbit Script ou JavaScript.

Nomes de variáveis globais

Nomes de variáveis globais podem ser compostos por caracteres alfanuméricos (as letras a-z e A-Z, e os dígitos 0-9), pontos (.) e sublinhados (_). (Outros caracteres, como hífens, não são recomendados e podem causar problemas.) Nomes de variáveis globais não diferenciam maiúsculas de minúsculas; uma variável chamada GlobalVar é tratada da mesma forma que globalvar.

Pode ser uma boa prática usar pontos ou sublinhados ao definir variáveis globais para que sejam fáceis de encontrar. Por exemplo, uma variável global criada em um Jitterbit Script chamada org.account.filename começa com org, seguida de account, etc., organizando efetivamente por domínio quando em uma lista entre outras variáveis globais construídas de forma semelhante. Observe que para variáveis globais criadas em JavaScript (ou para variáveis globais do Jitterbit Script que possam ser usadas posteriormente em JavaScript) recomendamos usar sublinhados em vez de pontos. Usar pontos em variáveis globais definidas pelo usuário em JavaScript causa problemas em tempo de execução. Mais informações são fornecidas na subseção JavaScript abaixo.

Jitterbit Script

No Jitterbit Script usado dentro de scripts e transformações, uma variável global pode ser definida começando com um sinal de dólar $ ou chamando a função Set():

  • $: Usando a sintaxe do sinal de dólar $, $ServerURL=URL cria ou atualiza uma variável global chamada ServerURL com o valor de URL (o nome de outra variável ou o nome de um campo em uma transformação).
  • Set: Usando a função Set(), Set("ServerURL", URL) cria ou atualiza uma variável global chamada ServerURL com o valor de URL (o nome de outra variável ou o nome de um campo em uma transformação).

JavaScript

No JavaScript utilizado dentro de scripts criados dentro de uma operação, a sintaxe usada para definir uma variável global depende se o nome da variável global contém um ponto:

  • Nome não inclui um ponto (recomendado): Uma variável global que não contém um ponto em seu nome pode ser criada ou atualizada usando var $<name> ou atualizada simplesmente usando $<name> sem var:

    • var $: A expressão var $ServerURL="https://www.example.com/" cria ou atualiza uma variável global ServerURL com um valor de string de https://www.example.com/. Uma nova variável global deve preceder o $ com var.
    • $: A expressão $ServerURL="https://www.example.com/" atualiza a mesma variável global ServerURL com a mesma URL em string. Isso funciona apenas para variáveis globais que já existem.

  • Nome inclui um ponto (recomendado apenas para variáveis Jitterbit e valores de objeto JavaScript): Uma variável que contém pontos em seu nome pode ser atualizada ou recuperada em JavaScript apenas com as funções Jitterbit.SetVar e Jitterbit.GetVar. Como essas funções não são destinadas a variáveis globais definidas pelo usuário, consulte variáveis Jitterbit para mais informações.

    Aviso

    As funções JavaScript Jitterbit.SetVar e Jitterbit.GetVar são projetadas especificamente para acessar as variáveis Jitterbit predefinidas. Elas não devem ser usadas para acessar variáveis globais definidas pelo usuário.

Recuperar valores de variáveis globais em scripts ou transformações

No Design Studio, o valor de uma variável global pode ser retornado usando Jitterbit Script ou JavaScript.

Jitterbit Script

Em scripts e transformações, é possível começar com um sinal de dólar $ seguido pelo nome da variável global ou usar a função Get() para recuperar o valor de uma variável global:

  • $: Com um sinal de dólar $, o exemplo de código $ServerURL retorna o valor da variável global ServerURL.
  • Get: Usando a função Get(), o exemplo de código Get("ServerURL") retorna o valor da variável global ServerURL.

JavaScript

Em scripts JavaScript dentro de uma operação, a sintaxe usada para recuperar uma variável global depende de o nome da variável global conter um ponto:

  • Nome não inclui um ponto (recomendado): O valor de uma variável global que não contém um ponto em seu nome pode ser recuperado começando com um sinal de dólar $:

    • $: Com um sinal de dólar $, a expressão $ServerURL recupera o valor da variável global chamada ServerURL.

  • Nomes com pontos (recomendado apenas para variáveis Jitterbit e valores de objetos JavaScript): Uma variável que contém um ponto em seu nome pode ser atualizada ou recuperada em JavaScript apenas com as funções Jitterbit.SetVar e Jitterbit.GetVar. Como essas funções não são destinadas a variáveis globais definidas pelo usuário, consulte variáveis Jitterbit para mais informações.

    Aviso

    As funções JavaScript Jitterbit.SetVar e Jitterbit.GetVar são projetadas especificamente para acessar as variáveis Jitterbit predefinidas. Elas não devem ser usadas para acessar variáveis globais definidas pelo usuário.

    Em JavaScript, não misture o uso de SetVar (e GetVar) com a prefixação $ ao definir (e recuperar) uma variável. Use apenas uma sintaxe. Misturar as duas sintaxes diferentes para a mesma variável pode causar problemas em tempo de execução.

    Se um JavaScript falhar, quaisquer alterações feitas no valor de uma variável global são perdidas. Somente se o JavaScript for concluído com sucesso, os valores das variáveis globais modificadas estarão disponíveis fora do script.

Use variáveis globais em telas de definição

Em uma tela de definição (como durante a configuração de fontes ou destinos), você pode referenciar variáveis globais usando a sintaxe [GlobalVariableName{DefaultValue}].

Por exemplo, para fornecer um valor para uma URL de servidor em uma chamada de serviço web, você pode usar a sintaxe de variável global [ServerURL] em vez de um valor codificado. O valor atribuído à variável global ServerURL seria então utilizado em tempo de execução.

Para especificar um valor padrão, use chaves { } imediatamente após o nome da variável global dentro dos colchetes [ ]. Por exemplo, o seguinte será avaliado para o valor da variável global ServerURL se a variável estiver definida; se não estiver definida, http://server/index.asp é utilizado:

[ServerURL{http://server/index.asp}]

Em tempo de operação, um valor padrão definido em uma tela de definição é utilizado apenas se o valor da variável não tiver sido definido durante a execução. Isso é diferente durante o teste de script, onde—como quaisquer valores de script anteriores ainda não terão sido instanciados—qualquer valor padrão definido dentro de uma tela de definição é utilizado em vez disso.

Dica

Ao usar uma variável global em uma cláusula WHERE, como dentro de uma consulta de banco de dados ou Salesforce, recomendamos especificar um valor padrão para que o teste de script seja possível. Caso contrário, como uma variável global obtém seu valor em tempo de execução, durante o teste a sintaxe pode ser inválida se nenhum valor padrão tiver sido especificado.

Se você não quiser que a variável global seja interpretada, use uma barra invertida "\" para escapar o conjunto de colchetes "[" e "]". Isso pode ser útil temporariamente durante os testes. Por exemplo, a seguinte expressão não usará o valor de ServerURL (mesmo que esteja definido), mas sempre usará http://server/index.asp:

\[ServerURL{http://server/index.asp}]

Cuidado

Dentro de caminhos de arquivo que contêm barras invertidas, uma única barra invertida será interpretada como o início de uma sequência de escape se for seguida por um conjunto de colchetes "[" e "]".

Barras invertidas adicionais podem ser usadas para alcançar o resultado desejado. Por exemplo, \\server\share\\[Directory{testing}] será interpretado como \\server\share\testing se a variável Directory não estiver definida; caso contrário, \\server\share\"valor de Directory" será usado.

Para evitar esse problema, recomenda-se converter caminhos de arquivo para o formato de URL (por exemplo, C:/directory/path).

Como usar variáveis globais

Consulte estas seções para dicas sobre como usar variáveis globais em seus projetos:

Verificar valores nulos ou indefinidos

Um elemento de dados global que não foi definido é considerado ter um valor nulo.

Por exemplo, IsNull(Get("GlobalVariableName")) retorna verdadeiro se uma variável global com o nome GlobalVariableName ainda não tiver sido definida. Isso pode ser usado para verificar se uma variável global foi definida ou não.

Definir e acessar variáveis de array

Você pode criar arrays de variáveis globais, também conhecidas como variáveis de array. Consulte Arrays para obter informações sobre como definir e recuperar valores de variáveis de array.