Adaptador JSON para o Jitterbit Connector SDK

A interface do Integration Studio para um conector criado com o Jitterbit Connector SDK é definida por um arquivo JSON incluído no arquivo JAR que empacota o conector. Por convenção e por padrão, esse arquivo é nomeado adapter.json.

O nome desse arquivo pode ser diferente, pois o nome utilizado é aquele especificado na entrada Jitterbit-Connector-UI do arquivo MANIFEST-MF:

Jitterbit-Connector-UI: adapter.json

Consulte Registro de conector: Manifesto do conector para detalhes sobre o arquivo MANIFEST.MF.

Arquivo JSON do adaptador

O desenvolvedor de um conector define todos os componentes da interface no arquivo adapter.json. Esses componentes são exibidos quando o usuário configura o conector e suas atividades, e os valores inseridos podem ser recuperados pelo código do conector.

Estrutura do arquivo JSON do adaptador

Aqui está um esquema geral do arquivo JSON que define uma interface de conector, com valores de espaço reservado mostrados como "<name>". Os termos utilizados e seus significados são discutidos após este exemplo:

{
  "name": "<name>",
  "version": "1.0.0",
  "sandbox": true,
  "defaultActivityIcon": "<path-to-SVG-file>",
  "endpoint": {
    "displayName": "<display-name>",
    "icon": "<path-to-SVG-file>",
    "properties": [ "<properties>" ]
  },
  "activities": {
    "activity-1": {
      "displayName": "<display-name-1>",
      "icon": "<path-to-SVG-file>",
      "properties": [ "<properties>" ]
    },
    "activity-2": {
      "displayName": "<display-name-2>",
      "properties": [ "<properties>" ]
    },
    . . .
  }
}

Neste esquema, um conector foi definido com propriedades para o endpoint e suas duas primeiras atividades. Atividades adicionais podem ser adicionadas conforme necessário.

Para a conexão (que é o que aparece quando um usuário final configura o conector pela primeira vez na interface do Integration Studio), um conjunto de propriedades pode ser definido que será usado para gerar um ou mais passos que o usuário final completa para configurar a conexão com o endpoint.

Observe que o name e o version utilizados devem ser o mesmo name e version sob os quais o conector está registrado (veja Registro de conector).

A propriedade sandbox pode ser definida como true ou false. Definida como true, significa que o conector está em desenvolvimento e não será armazenado em cache pelo Harmony. Em vez disso, cada invocação recarregará o conector do agente privado do Jitterbit. Uma vez que você tenha uma versão de produção, pode definir isso como false para que o cache possa ser utilizado para acelerar o uso.

Um conjunto de propriedades é definido para cada atividade, gerando etapas para configurar a atividade após ela ser adicionada a uma operação no Integration Studio.

Ícones de endpoint

Como pode ser visto no esquema acima, você pode definir ícones para a conexão e cada uma das atividades (juntas referidas como um endpoint). Os ícones são definidos usando SVG e são fornecidos como um caminho para um arquivo SVG.

Essas chaves podem ser fornecidas no adapter.json:

No exemplo esquemático acima, um ícone padrão foi definido, com a conexão e a primeira atividade usando outros—talvez diferentes—ícones. A segunda atividade não tem um ícone definido e, em vez disso, usa o ícone padrão.

Esta captura de tela do conector do Dropbox mostra como ícones diferentes podem ser usados:

Um ícone (uma pasta) é usado para a conexão, com um ícone diferente usado para as atividades. É possível ter um ícone diferente para cada atividade, embora seja aconselhável manter um tema comum de cores e formas para um endpoint. Observe que o texto descrevendo a atividade é sobreposto ao ícone. É melhor deixar a metade inferior do ícone de uma cor sólida para que o texto branco tenha um fundo contra o qual aparecer.

Para detalhes sobre como criar os arquivos SVG, incluindo modelos e um guia passo a passo, veja Ícones de endpoint da SDK do Conector.

Ordem de atividades e ícones

A ordem dos ícones na interface do usuário deve seguir a ordem das atividades no JSON. Se o número de atividades exceder três, linhas adicionais de atividades são adicionadas na interface do usuário abaixo da linha original.

Nossa recomendação para a ordem das atividades é seguir esses padrões comuns:

• Ler, Escrever
• Consultar (ou Buscar), Criar, Atualizar, Upsert, Excluir
• Obter, Postar, Colocar, Excluir
• Solicitar, Responder
• Baixar, Enviar

Se houver atividades personalizadas, especiais ou específicas de entidade fora dos exemplos acima (como Obter Lista), coloque-as no início da ordem se forem destinadas a fornecer dados como fonte em uma operação, e no final se forem destinadas a receber dados como alvo em uma operação.

Paginação

Para a conexão e cada atividade, propriedades são definidas em uma estrutura JSON. Essas criam as etapas de configuração (páginas) que um usuário final percorre para configurar a conexão e cada uma das atividades particulares que escolhe usar.

Paginação padrão

Conexões não têm nenhuma paginação por padrão. Para conexões, geralmente há apenas uma etapa, embora o desenvolvedor possa adicionar quantas forem necessárias.

Para atividades, há pelo menos duas etapas: uma página inicial com um campo de nome e uma página final mostrando os esquemas de dados para revisão. Ambas as páginas são criadas automaticamente pela infraestrutura e não estão incluídas ou definidas no arquivo JSON.

Neste exemplo, estão as etapas inicial (página 1) e final (página 2):

Página única

Se a conexão ou atividade puder ser configurada em uma única página e a paginação não for necessária, uma estrutura simples pode ser usada:

. . .
"properties": [
  {
    "name": "<name-1>",
    "displayName": "<display-name-1>",
    "type": "string",
    "validators": [
      {
        "name": "required"
      }
    ]
  },
  {
    "name": "<name-2>",
    "displayName": "<display-name-2>",
    "type": "string",
    "validators": [
      {
        "name": "required"
      }
    ]
  }
]
. . .

Múltiplas páginas

No entanto, se a configuração for mais longa, com vários valores a serem definidos ou revisados, a paginação é recomendada para manter as visualizações menores em profundidade:

. . .
"properties": [
  {
    "name": "page1",
    "displayName": "<display-name-page-1>",
    "type": "pagination",
    "children": [
      {
        "name": "<name-1-1>",
        "displayName": "<display-name-1-1>",
        . . .
      },
      . . .
    ]
  },
  {
    "name": "page2",
    "displayName": "<display-name-page-2>",
    "type": "pagination",
    "children": [
      {
        "name": "<name-2-1>",
        "displayName": "<display-name-2-1>",
        . . .
      },
      . . .
    ]
  }
]
. . .