Variáveis globais no Jitterbit Integration 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 o projeto. Elas são definidas de maneira 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 espaço de nomes, seus nomes devem ser únicos em comparação com todos os outros elementos de dados globais.

As variáveis globais são primeiramente declaradas em uma operação, após o que se tornam disponíveis para serem referenciadas na mesma ou em operações e scripts subsequentes. Operações ou scripts subsequentes são aqueles que estão vinculados dentro de uma cadeia de operações usando ações de operação ou as funções RunOperation ou RunScript. Operações subsequentes podem estar dentro dos mesmos ou de fluxos de trabalho subsequentes.

As variáveis globais também podem ser usadas como fonte ou destino dentro da operação, conforme descrito em Leitura de variável e Gravação 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 nos seguintes exemplos:

• Usando valores criados 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.
• Usando 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.
• Usando 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 "em sucesso" ou "em falha" ações de operação, 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.

Exibição de variáveis globais

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

• No painel do projeto, variáveis globais são exibidas na aba Componentes na categoria Variáveis Globais. A partir 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 dentro da aba Variáveis na sub-aba Variáveis Globais. Este local fornece fácil acesso para inserir referências de variáveis globais em scripts, incluindo 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 fácil acesso para inserir referências de variáveis globais durante o mapeamento de transformação.
• Nas telas de configuração de endpoint, variáveis globais podem ser acessadas e usadas em quaisquer campos que tenham um ícone de variável . Como alternativa à seleção de uma variável global, você pode inserir manualmente a referência da variável usando a sintaxe padrão de colchetes 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 um 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 configuradas em uma conexão de Variável são criadas ou atualizadas automaticamente (veja Conexão de variável).

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.

É 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 semelhante. Observe que, para variáveis globais criadas em JavaScript (ou para variáveis globais do Jitterbit Script que podem ser usadas posteriormente em JavaScript), recomendamos o uso de sublinhados em vez de pontos. O uso de 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.

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

Em JavaScript usado dentro de scripts criados como um componente de projeto, 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 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 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.

Endpoint de variável

Durante a configuração de uma Conexão variável, uma variável global pode ser criada ou atualizada automaticamente.

Ou seja, se durante a configuração você fornecer o nome de uma variável que ainda não existe, uma variável global é criada automaticamente. Se você fornecer o nome de uma variável global que já existe, ela se torna associada ao endpoint de variável.

Para detalhes sobre como criar ou atualizar uma variável global usando este método, consulte Conexão 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 de projeto).

Jitterbit Script

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

• $: Com prefixo de um sinal de dólar $, 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 do painel de componentes de script dentro da sub-aba Variáveis Globais. Veja Adicionar uma variável global a um script abaixo.

JavaScript

Em JavaScript scripts dentro de uma operação, a sintaxe usada para recuperar o valor de 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 $. Prefixado com um sinal de dólar $, 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 objeto 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 a seção sobre 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 seu uso de SetVar (e GetVar) com 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 de variáveis globais modificadas estarão disponíveis fora do script.

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

Adicionar uma variável global a um script

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

Use os triângulos de divulgaçã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 dos seguintes métodos:

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

Usar variáveis globais nas 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 quaisquer campos que tenham um ícone de variável . As variáveis podem ser usadas em campos junto com outras entradas, incluindo outras variáveis ou palavras-chave. Essas ações são abordadas abaixo:

• Selecionar uma variável global
• Alternar formatos entre pílula e texto
• 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 inserir um colchete aberto [ para exibir uma lista de 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

Na lista, passe o mouse sobre o nome da variável para visualizar informações sobre ela:

A Descrição no popup de informações é [Nenhum] para uma variável global. Um Valor é preenchido apenas se a variável global tiver um valor padrão especificado neste campo de configuração.

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 é utilizado.

Selecione uma variável para adicionar ao campo na localização do seu cursor, em qualquer lugar na string. A variável é exibida em um formato de pílula semelhante ao mostrado abaixo:

Para revisar informações sobre a variável, passe o mouse sobre a pílula da variável:

Alternar formatos entre pílula e texto

Para mudar o formato padrão da variável de pílula para o formato de texto, clique no ícone de colapso :

Isso alterna a exibição do formato de pílula para um formato de texto, com o nome da variável entre colchetes [ ]:

No formato de texto, você pode definir um valor padrão.

Para mudar de um formato de texto de volta para o formato de pílula, tire o foco do campo, como clicando em outro campo configurável. A entrada do campo retorna automaticamente ao formato padrão de pílula.

Definir um valor padrão

Durante a execução da operação, um valor padrão definido dentro de um campo de configuração, como mostrado abaixo, é 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 um campo de configuração é utilizado em vez disso.

Para definir um valor padrão dentro de um campo de configuração, primeiro altere para o formato de texto.

Imediatamente após o nome da variável global dentro dos colchetes [ ], especifique o valor padrão dentro de chaves { }:

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

Se você não quiser que a variável global seja interpretada, use uma barra invertida \ para escapar o conjunto de colchetes [ ].

Por exemplo, o seguinte não usa o valor de serverURL, mesmo que esteja definido, mas sempre usa http://server/index.asp:

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

Remover uma variável

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

Ver dependências de variáveis globais

As dependências de uma variável global são os outros componentes que referenciam essa variável ao ler ou escrever 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 Ver Dependências fica disponível na aba Componentes no painel do projeto. Para mais informações sobre a aba Componentes, veja Menu de ações do componente na Aba Componentes do painel do projeto.

A opção Ver Dependências altera a visualização no painel do projeto para exibir outros componentes do projeto que referenciam a variável global.

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

Visão de dependência de variável global

Na visã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 Dependências que referenciam a variável.

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

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

Os seguintes exemplos mostram como diferentes tipos de referências de variável são exibidos na visão de dependências:

• Se um script contém $myVar1='abc', ele está gravando um valor na variável e referenciando myVar1 para acesso de gravação.
• Se um script contém $myVar2=$myVar1, ele está referenciando myVar2 para acesso de gravação e myVar1 para acesso de leitura.
• Se um script contém If(myVar1=='abc', TRUE, FALSE), ele está referenciando myVar1 para acesso de leitura.

Como usar variáveis globais

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

• Converter uma variável global em uma variável de projeto
• Verificar valores nulos ou indefinidos
• Definir e acessar variáveis de array

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ável 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 aviso pede que você confirme que deseja converter a variável global em uma variável de projeto:

Ao clicar em Continuar, todas as referências e dependências da variável global são transferidas para a variável de projeto. Isso inclui referências à antiga variável global dentro de scripts, que agora referenciam a variável de projeto. (Lembre-se de 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, veja 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. Veja Arrays para informações sobre como definir e recuperar valores de variáveis de array.