Variáveis globais no Jitterbit Studio

Introdução

Variáveis globais são um dos tipos de elementos de dados globais disponíveis no Harmony. Os outros tipos de elementos de dados globais — variáveis de projeto, variáveis Jitterbit e palavras-chave de nome de arquivo — também estão disponíveis globalmente em todo um projeto. Eles são definidos de forma diferente, conforme descrito em Variáveis de projeto, Variáveis Jitterbit e Palavras-chave de nome de arquivo, respectivamente. No entanto, como todos os elementos de dados globais compartilham o mesmo namespace, seus nomes devem ser exclusivos quando comparados com todos os outros elementos de dados globais.

Diferentemente das variáveis de projeto, variáveis globais não são componentes de projeto e não são implantadas com o projeto. Como variáveis globais só podem ser definidas em scripts durante a execução da operação, não é possível atribuir valores em tempo de design. Para usar o recurso Testar Conexão de um conector com uma variável global referenciada em um campo de configuração de endpoint, você deve especificar um valor padrão nesse campo (consulte Definir um valor padrão).

Variáveis globais são declaradas pela primeira vez em uma operação, após o que ficam disponíveis para serem referenciadas na mesma ou em operações e scripts posteriores. Operações ou scripts posteriores são aqueles que estão vinculados em uma cadeia de operações usando ações de operação ou as funções RunOperation ou RunScript. Operações posteriores podem estar na mesma ou em fluxos de trabalho posteriores.

Variáveis globais também podem ser usadas como origem ou destino dentro da operação, conforme descrito em Leitura de variável e Escrita de variável.

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 nestes exemplos:

• Usar valores criados em uma transformação em uma transformação posterior. Por exemplo, uma ID de sessão (retornada de um serviço web de login) pode ser necessária ao chamar serviços web subsequentes para autenticação.
• Usar um valor criado em uma parte de uma transformação em um estágio posterior dessa 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 vinculadas a uma operação anterior na cadeia de operações usando ações de operação "on success" ou "on failure", bem como aquelas vinculadas através da função RunOperation. Variáveis globais também podem ser usadas na mesma transformação.

Exibição de variáveis globais

Variáveis globais definidas são exibidas em vários locais:

• No painel de projeto, variáveis globais são exibidas na aba Componentes na categoria Variáveis Globais. Daqui você pode ver se a variável global é referenciada em outro lugar no projeto e visualizar dependências.
• No editor de script, variáveis globais são exibidas na paleta de componentes de script na aba Variáveis na sub-aba Variáveis Globais. Este local fornece acesso fácil para inserir referências de variáveis globais em scripts, inclusive em scripts de transformação.
• Em uma transformação, variáveis globais são exibidas na aba Variáveis à esquerda na categoria Variáveis Globais. Este local fornece acesso fácil para inserir referências de variáveis globais durante o mapeamento de transformação.
• Em telas de configuração de endpoint, variáveis globais podem ser acessadas e usadas em qualquer campo que tenha um ícone de variável. Como alternativa à seleção de uma variável global, você pode inserir manualmente a referência de variável usando a sintaxe de colchetes quadrados padrão do Jitterbit Script.

Criar e atualizar variáveis globais

Variáveis globais são criadas ou atualizadas usando Jitterbit Script (em scripts e transformações) ou JavaScript (apenas em scripts criados como componente de projeto). Consulte Tipos de script e criação para obter informações sobre como criar os diferentes tipos de scripts. Variáveis globais também podem ser criadas, selecionadas ou renomeadas durante a configuração da conexão Variable (consulte Conexão Variable).

Nomes de variáveis globais

Nomes de variáveis globais podem ser compostos por caracteres alfanuméricos (letras e 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.

É 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 por account, etc., organizando-a efetivamente quando em uma lista entre outras variáveis globais construídas de forma similar. Observe que para variáveis globais criadas em JavaScript (ou para variáveis globais de 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 causa problemas em tempo de execução. Mais informações são fornecidas na subseção JavaScript abaixo.

Para renomear uma variável global a partir de um script, clique com o botão direito em seu nome na área de script do script e selecione Renomear variável no menu de contexto. Isso atualiza automaticamente todas as referências no script aberto no momento e nos componentes listados na caixa de diálogo de confirmação de renomeação. Uma variável global também pode ser renomeada no campo Nome da variável de uma conexão Variable (consulte Endpoint Variable abaixo).

Jitterbit Script

Em Jitterbit Script usado em scripts e transformações, uma variável global pode ser definida começando com um cifrão $ ou chamando a função Set:

• $: Usando a sintaxe de cifrão $, $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

Em JavaScript usado em scripts criados como componente de projeto, a sintaxe usada para definir uma variável global depende de o nome da variável global conter 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 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 de 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 se destinam a variáveis globais definidas pelo usuário, consulte Variáveis Jitterbit para obter mais informações.

Endpoint de variável

Durante a configuração de uma conexão de Variável, uma variável global pode ser criada ou selecionada no campo Nome da variável.

Ou seja, se você selecionar uma variável global existente, ela fica associada ao endpoint de Variável. Se a variável ainda não existir, você pode usar a ação Nova variável para adicioná-la ao projeto e associá-la ao endpoint.

Você também pode renomear a variável global selecionada diretamente no campo e escolher se o novo nome se aplica a todos os usos no projeto ou apenas a este endpoint.

Para detalhes sobre como criar, selecionar ou renomear uma variável global usando este método, consulte Conexão de Variável.

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

O valor de uma variável global pode ser retornado usando Jitterbit Script (em scripts ou transformações) ou usando JavaScript (apenas em scripts criados como um componente do projeto).

Jitterbit Script

Em scripts e transformações, você pode começar com um cifrão $ ou usar a função Get para recuperar o valor de uma variável global:

• $: Prefixado com um cifrão $, o exemplo de código $serverURL recupera o valor (ou campo em uma transformação) da variável global chamada "serverURL".
• Get: Usando a função Get, o exemplo de código Get("serverURL") retorna o mesmo valor (ou campo em uma transformação).

Em scripts e transformações, as variáveis globais existentes também são exibidas na aba Variáveis da paleta de componentes do script dentro da sub-aba Variáveis Globais. Consulte Adicionar uma variável global a um script abaixo.

JavaScript

Em scripts JavaScript dentro de uma operação, a sintaxe usada para recuperar o valor de uma variável global depende se o nome da variável global contém um ponto.

• Nome sem 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 cifrão $. Prefixado com um cifrão $, a expressão $ServerURL recupera o valor da variável global chamada ServerURL.

• Nome 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 se destinam a variáveis globais definidas pelo usuário, consulte a seção sobre variáveis Jitterbit para mais informações.

  Aviso

  As funções JavaScript Jitterbit.SetVar e Jitterbit.GetVar foram projetadas especificamente para acessar as variáveis predefinidas do Jitterbit. 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 prefixo $ 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, qualquer alteração feita no valor de uma variável global será perdida. Os valores de variáveis globais modificadas ficam disponíveis fora do script apenas se o JavaScript for concluído com sucesso.

Em scripts e transformações, as variáveis globais existentes também são exibidas na aba Variáveis da paleta de componentes do script, dentro da sub-aba Variáveis Globais. Consulte Adicionar uma variável global a um script abaixo.

Adicionar uma variável global a um script

Em scripts Jitterbit Script ou JavaScript usados em scripts criados dentro de uma operação, as variáveis globais existentes são exibidas na aba Variáveis da paleta de componentes do script, dentro da sub-aba Variáveis Globais:

Use os símbolos de intercalação para visualizar ou ocultar detalhes de uso, incluindo quais componentes leem ou escrevem na variável:

Você pode clicar no nome de qualquer componente para abrir sua tela de configuração.

Para adicionar a sintaxe da variável a um script (Jitterbit Script ou JavaScript), use um destes métodos:

• Arraste a variável da paleta para o script para inserir a sintaxe da variável.
• Clique duas vezes na variável na paleta para inserir a sintaxe da variável na localização do cursor dentro do script.
• Comece a digitar o nome da variável e pressione Control+Space para exibir uma lista de sugestões de preenchimento automático. Selecione uma variável para inserir a sintaxe da variável.
• Digite manualmente a sintaxe da variável.

Usar variáveis globais em telas de configuração

Durante a configuração de vários componentes do projeto, incluindo a configuração de endpoint usando conectores, você pode usar variáveis globais em qualquer campo que tenha um ícone de variável. As variáveis podem ser usadas em campos junto com outras entradas, incluindo com outras variáveis ou palavras-chave. Essas ações são abordadas abaixo:

• Selecionar uma variável global
• Definir um valor padrão
• Remover uma variável

Selecionar uma variável global

Para acessar variáveis globais, você pode clicar no ícone de variável ou digitar um colchete de abertura [ para exibir um menu listando variáveis e palavras-chave (se disponíveis para o campo atual).

Na lista, cada tipo de variável ou palavra-chave é indicado pelo ícone ao lado do seu nome:

• para palavra-chave de nome de arquivo
• para variável global
• para variável de projeto
• para variável Jitterbit

O fundo do ícone é sólido se a variável global tiver um valor padrão especificado neste campo de configuração, ou vazio se não tiver. O fundo do ícone não é afetado se a mesma variável global tiver um valor especificado em outro campo de configuração, pois apenas um valor padrão especificado no campo atual é usado.

Selecione uma variável para adicioná-la ao campo na localização do cursor, em qualquer lugar da string. A variável é exibida em um formato de pill semelhante ao mostrado abaixo:

Para revisar informações sobre a variável, passe o mouse sobre o pill da variável para exibir um popup de informações:

• Label: N/A para uma variável global.
• Default value: Preenchido apenas se a variável global possui um valor padrão especificado neste campo de configuração.
• Description: N/A para uma variável global.
• Edit default value: Clique para definir ou editar um valor padrão.

Define a default value

Durante a execução da operação, um valor padrão definido em um campo de configuração é usado apenas se o valor da variável não foi definido durante a execução. Isso é diferente durante testes de script, onde — como qualquer valor de script upstream ainda não terá sido instanciado — qualquer valor padrão definido em um campo de configuração é usado.

Quando valores padrão são especificados, o valor da variável global é usado se estiver definido; caso contrário, o valor padrão é usado.

Defina um valor padrão usando um destes métodos:

• Usando o pill da variável: Para um campo onde a variável global foi inserida usando o ícone de variável ou menu de colchetes, resultando em um pill.
• Usando sintaxe inline: Para qualquer campo, incluindo um campo de texto simples que não suporta um pill de variável, como uma instrução SQL inserida manualmente em uma atividade Database Query.

Using the variable pill

Para definir um valor padrão para uma variável global exibida como um pill, passe o mouse sobre o pill da variável e clique em Edit default value para editar manualmente o campo Default value no popup de informações.

Clique em Save para confirmar suas alterações no campo Default value.

Using inline syntax

Para definir um valor padrão diretamente no texto de um campo de configuração, acrescente o valor padrão ao nome da variável entre chaves, usando a sintaxe [varName{defaultValue}]. Por exemplo, [customer_id{123}] referencia a variável global customer_id com um valor padrão de 123.

Use este método para um campo que não suporta um pill de variável, como uma instrução SQL inserida manualmente em uma atividade Database Query.

Se não quiser que a referência da variável seja interpretada, use uma barra invertida \ para escapar o conjunto de colchetes [ ]. Por exemplo, \[serverURL{http://server/index.asp}] não usa o valor de serverURL mesmo que esteja definido, mas sempre usa o texto literal http://server/index.asp.

Remover uma variável

Para remover a variável, clique no ícone de remoção:

Visualizar dependências de variáveis globais

As dependências de uma variável global são os outros componentes que fazem referência a essa variável lendo ou escrevendo nela. Depois de criar e usar uma variável global em um projeto, você pode visualizar essas dependências.

Após criar uma variável global, a opção View Dependencies fica disponível na aba Components no painel do projeto. Para mais informações sobre a aba Components, consulte Component actions menu em Project pane Components tab.

A opção View Dependencies altera a visualização no painel do projeto para exibir outros componentes do projeto que fazem referência à variável global.

Alternativamente, você pode visualizar as dependências de variáveis globais diretamente na aba Variables da paleta de componentes de script.

Visualização de dependência de variável global

Na visualização de dependências, o nome da variável global selecionada aparece no topo, abaixo das opções de pesquisa e filtro existentes. O nome da variável global é seguido por uma lista de Dependencies que fazem referência à variável.

As dependências são organizadas por categorias como Activity e Script. Dentro de cada categoria, os componentes são classificados como Read ou Write para mostrar como a variável é acessada.

Você pode clicar no nome de qualquer componente para abrir sua tela de configuração.

Os exemplos a seguir mostram como diferentes tipos de referências de variáveis são exibidos na visualização de dependências:

• Se um script contém $myVar1='abc', ele está escrevendo um valor na variável e fazendo referência a myVar1 para acesso de escrita.
• Se um script contém $myVar2=$myVar1, ele está fazendo referência a myVar2 para acesso de escrita e myVar1 para acesso de leitura.
• Se um script contém If(myVar1=='abc', TRUE, FALSE), ele está fazendo referência a myVar1 para acesso de leitura.

Guias práticos de variáveis globais

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

• Convert a global variable to a project variable
• Check for null or undefined values
• Set and access array variables

Converter uma variável global em uma variável de projeto

Você pode converter uma variável global já existente em uma variável de projeto.

Variáveis globais podem ser convertidas em variáveis de projeto durante a configuração de variáveis de projeto. Ao configurar uma variável de projeto, insira o nome de uma variável global existente no campo de nome. Ao tentar salvar, um prompt solicita que você confirme se deseja converter a variável global em uma variável de projeto:

Ao clicar em Continue, todas as referências e dependências da variável global são transferidas para a variável de projeto. Isso inclui referências à variável global anterior em scripts, que agora fazem referência à variável de projeto. (Tenha em mente que um valor para uma variável de projeto definido em um script durante a execução da cadeia de operações substitui o valor padrão especificado na configuração da variável de projeto.)

Para mais detalhes sobre variáveis de projeto, consulte Variáveis de projeto.

Verificar valores nulos ou indefinidos

Uma variável global que não foi definida tem um valor nulo.

Por exemplo, IsNull(Get("GlobalVariableName")) retorna verdadeiro se uma variável global com o nome GlobalVariableName ainda não foi 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 informações sobre como definir e recuperar valores de variáveis de array.