Ir para o conteúdo

Melhores Práticas de Harmony

Introdução

Este documento serve como um guia geral para usar a plataforma de integração como serviço (iPaaS) Harmony da Jitterbit. Ele fornece orientação de melhores práticas para cenários de integração comuns e recomendações usando as ferramentas disponíveis. Este documento não é abrangente e não cobre todos os cenários.

Este documento é para usuários do Cloud Studio, a versão baseada na web do aplicativo de design de projeto da Jitterbit. Para melhores práticas usando Design Studio, aplicativo de design de projeto baseado em desktop da Jitterbit, consulte Melhores práticas com o Design Studio.

Melhores práticas para App Builder, o aplicativo Jitterbit para criação de aplicativos web e móveis são abordados separadamente.

Você já deve estar familiarizado com o Harmony e o Cloud Studio a partir dos seguintes recursos:

Nesse ponto, você deve conhecer os conceitos e termos básicos usados no Harmony e entender o que queremos dizer com projetos, operações, endpoints, scripts, migração e implantação.

Veja os Recursos adicionais no final desta página para obter links para vídeos e outros documentos que expandem essas práticas recomendadas com o Harmony.

Suporte, Gerentes de Sucesso do Cliente e Documentação

O acesso ao suporte Jitterbit está incluído como parte de uma licença de cliente Harmony. Quando surgirem dúvidas ou problemas técnicos, você pode obter assistência especializada do suporte Jitterbit. O suporte Jitterbit descreve instruções especiais para situações de queda de produção a fim de escalar problemas sensíveis ao tempo.

Você também pode entrar em contato com seu Gerente de Sucesso do Cliente (CSM) com perguntas relacionadas a licenciamento ou outros tópicos.

Este site de documentação (Jitterbit Documentation) e nosso site de documentação para desenvolvedor (Jitterbit Developer Portal) contém mais de 3.600 URLs exclusivos de material técnico.

Para ajudar você a localizar material relevante, a caixa de pesquisa é pré-filtrada para limitar os resultados da pesquisa à seção da documentação que está sendo acessada no momento. Você pode pesquisar toda a documentação limpando o filtro de pesquisa. Para pesquisar frases específicas, coloque-as entre aspas duplas.

Receitas e Modelos

O Marketplace fornece mais de 400 receitas e modelos prontos do Cloud Studio para usar como base para designs de integração:

  • Uma receita de integração move dados em uma direção entre objetos em dois aplicativos ou sistemas.

  • Um modelo de processo acelera a execução de um processo de negócios específico usando vários objetos em vários aplicativos ou sistemas. Os modelos de processo são projetados para reduzir o tempo de implantação em 50 a 80 por cento.

Atualizações de Produtos Jitterbit

As atualizações do Harmony são lançadas com frequência (consulte Cronograma de lançamentos). Mesmo uma versão menor contém novos recursos e melhorias, além de correções de bugs.

Aplicativos em nuvem acessados através do portal Harmony são atualizados automaticamente e sempre executam a versão mais recente lançada.

Gateway da API da nuvem e grupo de agentes de nuvem atualizações são aplicadas automaticamente. Para os grupos de agentes de nuvem, há dois conjuntos: Produção e Sandbox. O último conjunto é usado para testar a compatibilidade com pré-lançamentos do software do agente e não é um ambiente de desenvolvimento.

Os aplicativos instalados localmente são atualizados baixando e executando um instalador:

É aconselhável manter-se atualizado com os lançamentos, especialmente aqueles que incluem atualizações de recursos.

Simplicidade de Design do Projeto e Preferência de Recursos

Durante o processo de criação de um projeto de integração, você pode encontrar vários métodos de implementação que podem resultar na mesma funcionalidade.

Embora muitas vezes haja vantagens ou desvantagens de um método em relação a outro, dependendo do caso de uso da integração (conforme documentado), recomendamos sempre manter o princípio orientador abrangente da simplicidade em mente. Projetos que são projetados da forma mais simples possível geralmente têm maior longevidade e são muito mais fáceis para um estranho se atualizar se uma mudança precisar ser feita. Por outro lado, projetos excessivamente complexos podem ser mais difíceis de manter e repassar a outros durante uma transição de responsabilidades.

Para projetar projetos mais simples, recomendamos a seguinte ordem de preferência de recursos:

  1. Utilize recursos sem código sempre que possível, como projetar visualmente operações na quadro de design, agrupando componentes juntos para ajudar a organizá-los, adicionando tags e comentários ao implantar e publicar operações como APIs.
  2. Aproveite os recursos de baixo código, como usar variáveis dentro das telas de configuração de componentes baseadas em assistente ou manipular dados de nível de campo em um mapeamento de transformação usando uma função de script.
  3. Conforme necessário, implemente lógica mais complexa usando scripts escritos em Jitterbit Script linguagem.
  4. Somente quando um equivalente do Jitterbit Script não estiver disponível, implemente scripts em JavaScript.

Design de Projeto e Reutilização

Um cenário típico para reutilização de um projeto envolve o desenvolvimento de um projeto inicial com o uso extensivo de variáveis globais e, especialmente, variáveis de projeto. Itens configuráveis — como credenciais de endpoint, mapeamentos de campos opcionais, consultas parametrizadas, endereços de email e nomes de arquivo — podem ser expostos como variáveis de projeto. O projeto inicial também pode conter funções comuns, como tratamento de erros ou o uso de caches em todo o ambiente. O projeto inicial é exportado e, em seguida, importado para novos projetos para formar uma base consistente para o desenvolvimento.

Reutilização de Endpoint

Endpoints, criados pela configuração de uma conexão e atividades associadas usando conectores, são frequentemente usados em operações. No entanto, um endpoint exclusivo não precisa necessariamente ser criado para cada operação. Como as configurações de atividade aceitam variáveis para caminhos e nomes de arquivo, endpoints genéricos podem ser criados uma vez e então configurados dinamicamente usando variáveis globais e de projeto.

Por exemplo, suponha um HTTP a conexão e uma atividade associada são criadas, e a configuração da atividade especifica um caminho definido por uma variável global, como $gv_http_path. Um script de controlador pode ser usado para preencher o $gv_http_path conforme necessário.

Outro exemplo é uma atividade Database Query com uma condição. Sua WHERE condição pode ser atribuída a uma variável global, como $gv_database_condition.

A maioria dos endpoints tem a capacidade de ser configurada usando variáveis.

Reutilização de Script

Scripts autônomos que executam uma função específica, como retornar uma pesquisa de banco de dados ou calcular um resultado de uma série de argumentos, podem ser candidatos à reutilização, principalmente se usados em múltiplas operações.

Por exemplo, se um script usa o DBLookup função em relação a uma tabela de banco de dados, e esta função é usada em todo o projeto, então um script autônomo (separado de uma operação) pode ser construído. Usando o ArgumentList função ou variáveis globais simples, o script pode aceitar argumentos e retornar um resultado. Como cada cadeia de operação é um escopo diferente, o mesmo script pode ser chamado com segurança de várias operações simultâneas.

Organização do Projeto

Workflows são usados como um meio de organização de projeto. Um workflow normalmente contém operações relacionadas que processam dados do início ao fim: Criar pedidos, Sincronizar mestre de clientes, Processar confirmações, etc. Processos que são comuns em diferentes workflows, como consultar um endpoint ou lidar com uma condição de erro de operação, podem ser mantidos em seu próprio workflow e referenciados por outras operações de workflow.

Você também pode criar grupos personalizados onde os componentes do projeto podem ser coletados para facilitar a referência.

Os números atribuídos às operações que aparecem no designer de projeto são atribuídos automaticamente e são baseados na posição de exibição da operação no designer de projeto. Esses números não são mostrados nos logs de operação. Se for necessário um esquema de numeração de operação, ele pode ser implementado incorporando a numeração ao nome da operação.

Gerenciar Operações Assíncronas

Ao usar o RunOperation função em seu modo assíncrono, as operações são executadas sem retornar o controle para a função de chamada. O uso de operações assíncronas pode levar a condições de corrida.

Por exemplo, se a Operação A atualiza uma tabela de banco de dados e é encadeada à Operação B, que lê a mesma tabela (ambas são síncronas), nenhuma condição de corrida é encontrada. Mas se a Operação A for chamada de forma assíncrona seguida imediatamente pela Operação B, então B pode ser executada antes que A termine.

Além disso, o número de chamadas assíncronas simultâneas deve ser gerenciado, pois o número de operações simultâneas em execução em um agente é limitado (consulte o [OperationEngine] seção do arquivo de configuração do agente privado).

Credenciais de Endpoint

Recomendamos usar um ID de sistema com permissões de administração para credenciais de endpoint, em vez de um ID de nível de usuário. IDs de usuário normalmente expiram ou precisam ser desabilitadas quando um usuário sai de uma empresa.

Ao usar variáveis de projeto (cujos valores podem ser ocultados) para gerenciamento de credenciais, um administrador de organização Harmony não precisa inserir credenciais de produção. Ao configurar as permissões de usuário apropriadas, um usuário pode aplicar as credenciais de produção por meio do Management Console Projects página.

Se estiver usando agentes privados, como alternativa ao uso do Management Console, as variáveis globais podem ser gerenciadas usando o [PredefinedGlobalVariables] seção do arquivo de configuração do agente privado.

Dados de Integração Persistentes

Existem vários métodos para armazenar dados na nuvem Harmony, incluindo o uso de variáveis de projeto, funções de cache na nuvem ou armazenamento temporário.

Variáveis do Projeto

Variáveis de projeto são variáveis estáticas pré-inicializadas que podem ser consideradas constantes de projeto. Elas podem ser editadas no Cloud Studio (consulte Variáveis de projeto) ou o Management Console (consulte Projetos).

Um exemplo de uso de variáveis de projeto é para credenciais de endpoint. Ao usar variáveis de projeto, diferentes ambientes de endpoint (que geralmente têm credenciais diferentes) podem ser aplicados a diferentes ambientes Harmony e editado por meio do Management Console. Isso permite um processo de negócios em que um usuário com direitos do Management Console pode alterar credenciais sem precisar de acesso ao Cloud Studio e ao designer do projeto.

Um segundo exemplo é usar variáveis de projeto para manter sinalizadores usados pela lógica de integração que podem personalizar o comportamento da integração. Se um único projeto for desenvolvido, mas usado para diferentes endpoints, uma variável de projeto booleana (como Send_PO_Number) pode ser verificada pela lógica da transformação para o campo PO Number. Se o valor da variável do projeto for falso, então o UnMap a função poderia ser usada para "desligar" esse campo e não incluí-lo em uma transformação relevante.

Funções de Cache em Nuvem

As funções de cache em nuvem ReadCache e WriteCache são usados para atribuir espaços de dados que estão disponíveis em projetos e ambientes. Um valor armazenado em cache é visível para todas as operações em execução no mesmo escopo até que ele expire, independentemente de como essa operação foi iniciada ou em qual agente ela é executada. Ao armazenar dados em cache no Harmony, em vez de depender de armazenamentos de dados locais ou específicos do agente, como Armazenamento Temporário, os dados podem ser compartilhados entre operações separadas e entre projetos.

Estes são usos adicionais do cache em nuvem:

  • Os dados podem ser compartilhados entre operações assíncronas dentro de um projeto.
  • Erros que são gerados em diferentes operações podem ser armazenados em um cache comum. Ao acumular resultados de operação dessa maneira, alertas mais abrangentes podem ser criados.
  • Os tokens de login podem ser compartilhados entre operações.

Gerenciar Armazenamento Temporário

Armazenamento Temporário endpoints são frequentemente usados em operações em agentes privados e de nuvem. Eles são distintos do Armazenamento Local endpoints, que só podem ser usados em agentes privados.

Ao usar um endpoint de armazenamento temporário, os arquivos temporários são gravados e lidos no diretório temporário do sistema operacional padrão no agente que está executando o trabalho:

  • No caso de um único agente privado, o diretório de armazenamento temporário é o diretório temporário padrão do servidor do agente privado.
  • Se você estiver usando mais de um agente privado, agrupado em um grupo de agentes privados, o diretório de armazenamento temporário será o diretório temporário padrão do servidor de agente privado específico que está fazendo o trabalho.
  • Como os agentes de nuvem são agrupados em um grupo de agentes de nuvem, o diretório de armazenamento temporário é o diretório temporário padrão do servidor de agente de nuvem específico que está fazendo o trabalho.

Em um grupo de agentes em cluster (agentes privados ou de nuvem), desde que as operações que usam o armazenamento temporário sejam vinculadas (encadeadas), todas as leituras e gravações de armazenamento temporário acontecerão no mesmo servidor de agente. No entanto, se Chain A gravar em seu armazenamento temporário myfile e a Cadeia B lê de seu armazenamento temporário myfile, e as duas cadeias não estão encadeadas uma à outra, a ação de leitura de armazenamento temporário na Cadeia B pode não ser lida pelo mesmo agente que a Cadeia A.

Ao usar armazenamento temporário, tenha estas diretrizes em mente:

  • Ao usar agentes privados, para tornar seu projeto à prova de atualização, use armazenamento temporário de forma que mover de um único agente privado para um grupo de agentes com vários agentes não exija refatoração.

  • Ao usar um grupo de agentes em cluster (agentes privados ou em nuvem), para garantir que o servidor do agente onde o armazenamento temporário é gravado seja o mesmo servidor onde o armazenamento temporário será lido, certifique-se de que todas as referências às atividades de Leitura e Gravação do armazenamento temporário estejam na mesma cadeia de operação.

  • O armazenamento temporário em agentes privados é excluído após 24 horas por padrão pelo serviço de limpeza de arquivos Jitterbit. A frequência do serviço de limpeza pode ser configurada por meio do arquivo de configuração do agente privado sob o [FileCleanup] seção. No entanto, em agentes de nuvem, arquivos temporários podem ser excluídos imediatamente.

  • Os agentes de nuvem têm um limite de tamanho de arquivo de armazenamento temporário de 50 GB por arquivo. Arquivos temporários maiores que 50 GB são possíveis somente ao usar agentes privados.

  • Ao gravar no armazenamento temporário, o padrão é sobrescrever arquivos. Isso pode ser alterado com a caixa de seleção Anexar ao arquivo em uma Atividade de gravação de armazenamento temporário. Normalmente, isso requer que, após a leitura da fonte, o arquivo seja excluído ou arquivado. Uma maneira simples de fazer isso é usar as opções de pós-processamento Excluir arquivo ou Renomear arquivo em uma atividade de Leitura de armazenamento temporário.

  • Palavras-chave do nome do arquivo estão disponíveis e podem ser usados ao criar um nome de arquivo.

  • Um arquivo em armazenamento temporário pode ser lido construindo um script com o ReadFile função. Por exemplo: ReadFile("<TAG>activity:tempstorage/Temporary Storage/tempstorage_read/Read</TAG>"). Tenha em mente que isso funciona de forma confiável somente se houver um único agente privado.

Em alguns casos, pode ser vantajoso usar uma Variável endpoint em vez de um endpoint de Armazenamento Temporário. Veja Variável versus Armazenamento Temporário em Variável global versus armazenamento temporário para uma comparação desses dois tipos diferentes e para recomendações sobre quando cada um é apropriado.

Roteiro

Scripts escritos em Jitterbit Script linguagem ou JavaScript pode ser usado em quase qualquer lugar em operações e em mapeamentos de transformação.

Quando Usar Script

As operações podem ser organizadas em cadeias de operação de duas maneiras: (1) vinculando operações usando as condições On Success e On Fail usando ações de operação, ou (2) usando um controlador script.

Em vez de usar ações de operação, um script de controlador usa o RunOperation função para vincular operações usando um script.

Para capturar uma operação com falha, o If a função pode ser usada em conjunto com RunOperation. Por exemplo: If(!RunOperation(<operation tag>),<condition>), onde a condição pode usar GetLastError para capturar o erro e pode optar por interromper todo o processo usando RaiseError, e/ou executar outro processo para acumular texto de erro.

Um script de controlador pode ser benéfico em situações como estas:

  • executar uma operação que depende de fatores externos, como variáveis de projeto ou dados.
  • Para chamar suboperações de dentro de um loop, onde os dados são passados para a operação a partir de uma lista.
  • Para rastrear atividades da cadeia de operação. Por exemplo: (WriteToOperationLog("count of records to process: " + cnt), WriteToOperationLog("Starting update operation at: " + Now()), WriteToOperationLog("Database query: " + sql), etc.)

Outras áreas onde o script é frequentemente usado estão dentro dos campos mapeados em transformações e em outros scripts autônomos. Se o mesmo script estiver sendo usado em mais de uma transformação, considere configurar esse script como um script autônomo e chamá-lo de dentro de cada transformação usando RunScript.

Convenção de Nomenclatura para Variáveis

A Harmony tem quatro tipos de variáveis:

Como o escopo de uma variável local é limitado a um único script, uma convenção de nomenclatura para elas pode ser muito simples, como todas as letras minúsculas ou uma palavra inicial, como return ou myVariable. Pontos não são permitidos em variáveis locais.

Variáveis globais, como seu escopo é maior (uma variável global está disponível para ser referenciada nas mesmas operações ou scripts abaixo dentro de uma cadeia de operação ), devem usar uma convenção de nomenclatura consistente para evitar confusão. Por exemplo, usando vários componentes para um nome de variável, separados por pontos, você pode seguir um padrão como este:

type.category.subcategory
Componente Descrição
type Uma abreviação curta que identifica o tipo de variável, como pv(variável de projeto), gv(variável global), io (nome da origem/destino do endpoint ), dict(dicionário), etc.
category Uma categoria lógica para a variável, como sfdc, shipearly, confirm, order, etc.
subcategory Uma subcategoria lógica para a variável, como purchase_orders, categories, ids, etc.

Combinando esses componentes, estes são os possíveis nomes de variáveis:

  • $pv_shopify_base_url
  • $dict_staples_po_line_items
  • $io_request
  • $gv_sfdc_workorder_id

Como as variáveis são classificadas alfabeticamente em vários lugares na IU, organizá-las hierarquicamente ajudará no gerenciamento e uso de variáveis.

Seja qual for a convenção que você escolher usar, recomendamos codificá-la e documentá-la para que todos os membros da equipe possam usá-la consistentemente em todos os projetos.

Nota

Se você planeja usar Jitterbit Script variáveis globais em um JavaScript script, é importante usar sublinhados em vez de pontos:

  • $example_arr_names
  • $example_sfdc_success_message

Ambientes

O Harmony permite metodologias de ciclo de vida de desenvolvimento de software por meio do uso de ambientes. Você pode configurar ambientes de produção e não produção.

Por exemplo, suponha que um ambiente Development e um Production sejam configurados no Management Console e ambos estejam associados ao mesmo grupo de agentes. Suponha que um projeto seja desenvolvido primeiro no ambiente_Development_.

O Cloud Studio tem um recurso de migração que copiará esse projeto para o ambiente_Production_, após o qual as credenciais do endpoint serão alteradas para as credenciais do endpoint Production usando variáveis do projeto. Outros endpoints de origem e destino também são alterados. Após a migração inicial, quaisquer migrações posteriores do mesmo projeto de Development para Production excluem valores de variáveis de projeto migratórios, a menos que sejam novas variáveis de projeto.

Testando

O Harmony permite o desenvolvimento rápido de integração e teste de unidade ao tornar visíveis os dados de integração reais durante o tempo de design. A vantagem óbvia é permitir um processo de desenvolvimento iterativo ao mostrar os dados antes e depois das transformações de campo, em vez de construir a operação inteira, executá-la e inspecionar a saída. Os dados são tornados visíveis usando o recurso de visualização em uma transformação.

Depois que os dados de origem da amostra forem importados ou gerados, a transformação mostrará a saída de quaisquer mapeamentos e scripts incorporados.

Solução de Problemas

Um conceito-chave para uma arquitetura de integração saudável é reconhecer que haverá questões levantadas pelo negócio sobre a precisão do trabalho de integração, particularmente quando discrepâncias aparecem nos dados do endpoint. A integração pode ou não estar com defeito. É responsabilidade do projeto de integração fornecer um alto grau de transparência para ajudar a resolver questões sobre a precisão dos dados.

Por exemplo, se os dados em um endpoint de destino parecem estar incorretos, então, normalmente, o suporte de integração é chamado para fornecer detalhes sobre quaisquer ações de integração, como horários, fontes, lógica de transformação, mensagens de sucesso ou falha, etc. O processo de solução de problemas será beneficiado ao disponibilizar essas informações como uma parte padrão da arquitetura de integração. No Harmony, isso é suportado por meio de logging e alerta características.

Registro

Registros de operação capturam dados-chave por padrão, como tempos de execução de operação e mensagens de sucesso, falha ou cancelamento. Se houver falhas e o endpoint retornar informações de falha, o log capturará essas informações.

Com relação a falhas, o Harmony usa a resposta para fazer a determinação de status. Por exemplo, se um código de status HTTP 400 ou mais for recebido em uma resposta, o Harmony considera isso uma falha. Se a solicitação tiver um status de 200, mas a resposta contiver erros de dados, o Harmony tratará isso como um sucesso.

Ao desenvolver um projeto de integração, utilize o WriteToOperationLog função nos mapeamentos e scripts para capturar dados-chave e etapas no processo. Isso normalmente é tão simples quanto: WriteToOperationLog("The id is: "+sourcefieldid).

Se desejar capturar toda a saída de uma transformação, isso pode ser feito construindo uma operação que lê a fonte, executa a transformação e grava a saída em uma Variável ou Armazenamento Temporário endpoint em vez do endpoint de destino. Um script pós-operação pode ler a saída e registrá-la. Então, a operação "real" pode ser realizada.

Os logs podem ser visualizados no Cloud Studio tela de log de operação ou o Management Console Operações de Tempo de Execução página. O Management Console Operações de Tempo de Execução pode ser acessada pela equipe de suporte sem a necessidade de navegar até o projeto.

Os dados nos logs são pesquisáveis. Para filtrar apenas os logs necessários, você pode usar a sintaxe de pesquisa de message=%\<seu texto>% nos logs de operação do Cloud Studio e do Management Console.

Frequentemente, as APIs têm uma mensagem informativa de resposta de sucesso ou não sucesso. Se o registro de depurar estiver habilitado para a API, o corpo da solicitação será capturado nos registros da API (que são distintos dos registros de operação).

Os logs de operação, incluindo mensagens de log detalhadas de agentes de nuvem e agentes privados, são retidos por 30 dias pelo Harmony.

Alerta

Frequentemente, os resultados da integração não só precisam ser registrados, mas também precisam ser escalonados. Notificações Email pode ser facilmente anexado a operações e caminhos de sucesso/falha ou chamado de scripts. Você pode alternativamente usar o Email conector para configurar uma atividade de envio email como alvo de uma operação.

Para obter informações adicionais, consulte Configurar alertas, registro e tratamento de erros.

Recursos Adicionais

Estas seções e páginas na documentação fornecem práticas recomendadas adicionais.

Palestras Sobre Tecnologia

Palestras técnicas do Jitterbit são apresentações em vídeo que abrangem áreas de interesse para usuários de todos os níveis:

Tech Talk Duração Data de lançamento
Proxy de API 39:53 09.01.2019
APIs 49:22 07.08.2018
Cloud Studio 43:53 14/05/2019
Melhores práticas de orquestração de projetos complexos 50:46 16/10/2018
Construtor de conectores 50:19 16/07/2019
Ambientes 1:04:22 04/04/2018
Armazenamento e gerenciamento de credenciais externas 46:58 2020.10.09
Melhores práticas de tratamento de erros 27:22 13/03/2018
Melhores práticas do Jitterbit 1:04:38 2020.03.16
Melhores práticas de registro 1:03:02 12.02.2019
Gerenciador do Portal de API Aberta 57:21 05/11/2019
Melhores práticas de fontes de passagem e variáveis globais 42:44 2018.12.05
Melhores práticas para agentes privados 42:43 05/07/2018
Modelos de processo 43:27 2020.07.08
Melhores práticas de organização de projetos 1:08:39 08/06/2018

Documentação

A documentação do Jitterbit tem as melhores práticas incluídas em nossas páginas sobre o uso de produtos Jitterbit:

Segurança

Metodologia de Projeto de Integração

  • Metodologia de Projeto de Integração
    Itens essenciais que um gerente de projeto para um projeto do Cloud Studio deve saber, incluindo como organizar sua equipe, reunir e validar requisitos de forma clara e concisa e aproveitar os pontos fortes do Harmony para entregar um projeto de integração bem-sucedido.

Criar Projetos

Registro

Agentes Privados