External service: POST XML/JSON para um serviço da web

Na ion, você pode postar dados para um serviço da web em XML, JSON ou qualquer formato que você definir usando o tipo de integração POST XML/JSON. É recomendado usar esse tipo de integração para estender dados a um serviço SOAP ou qualquer plataforma que exija que os dados sejam enviados em um formato específico. Este documento fornece instruções passo a passo para configurar uma integração POST XML/JSON na ion.

Antes de começarmos

Existem alguns itens que você precisa sistematizar antes de configurar a integração. Esses itens podem ser encontrados no formulário da web externo em HTML ou podem ser fornecidos na documentação de suporte do seu fornecedor.

  • Post-To” ou URL endpoint;
  • Solicitação de amostra que exibe o formato dos dados;
  • Requisitos de autenticação, se aplicável;
  • Valores aceitáveis para campos não textuais.

Existem algumas etapas a serem seguidas na plataforma ion antes de configurar a integração, listadas abaixo:

  • Criar campos de coleta de dados;
  • Criar formulário(s) íon;
  • Configurar um Creative de teste

Vamos começar!

1. Crie mapeamento de campo

Ao seguir as etapas abaixo você vai mapear seus campos de coleta de dados ion na estrutura necessária. Para começar, adicione seu novo mapeamento de campo:

  1. Clique na aba Integrations no side nav do seu ion console;
  2. Clique no botão verde “New field mapping”;
  3. Classifique o Field Mapping e, opcionalmente, adicione uma descrição;
  4. No menu Integration type, selecione “Post XML/JSON”;
  5. Cole a estrutura de dados no editor Post XML — a estrutura de dados não precisa ser XML. Tudo bem se houver valores de amostra em sua estrutura de dados. Voltaremos e atualizaremos esses valores com marcadores dinâmicos um pouco mais tarde;
  6. Salve.

2. Adicione Outbound Fields ao Field Mapping

Outbound Fields definem os dados que você estende da ion para seu formulário da web externo.

  1. Clique no botão verde “New Outbound Field” para adicionar um novo campo ao seu Field Mapping;
  2. Ao adicionar um novo campo, você vai selecionar dos menus suspensos Data Collection e Core Field, implementar um Mashup Template ou adicionar um campo via JavaScript —
    1. para adicionar um campo de formulário, use os menus suspensos Data Collection para selecionar a categoria Data Field e o campo Data Collection
    2. OU, para adicionar um ion Core field, selecione-o do menu suspenso Core Field
    3. OU, para exportar vários campos ion para um campo externo, use o Mashup Field ao conectar {{DataName}} {{DataName2}} , etc. no editor
    4. OU, para reformatar um valor antes de exportá-lo, use o campo JavaScript para adicionar lógica em torno do valor coletado na ion. Para acessar Data Collection Fields de dados via Javascript, use respondent.dataname;
  3. Opcionalmente, torne seu campo como obrigatório para executar a integração;
  4. Opcionalmente, adicione um Default Value;
  5. Insira o Substitution Term — este é o valor que adicionaremos à sua estrutura de dados como um marcador dinâmico. Recomendamos usar algo simples que identifica o campo;
  6. Salve;
  7. Repita essas etapas para cada campo que deve ser incluído no Field Mapping.

3. Adicione Substitution terms ao POST XML ou estrutura de dados

Vamos voltar para a estrutura de dados POST XML e substituir seus dados de amostra pelos Substitution Terms definidos no Field Mapping;

  1. Clique no botão “Edit Field Mapping” próximo ao Field Mapping Label para abrir o POST XML;
  2. Substitua todos os valores de dados de amostra por ;
  3. Por exemplo:
    • Alterar <PrimeiroNome> Jane </PrimeiroNome>
    • Para <PrimeiroNome> {{PrimeiroNome}} </PrimeiroNome>;
  4. Salve.

4. Como opção, adicione Inbound Fields

Tire proveito dos Inbound Fields para salvar dados de uma resposta XML na coleta de dados na ion. Abordaremos como analisar e salvar respostas JSON em uma etapa posterior.

  1. Clique no botão verde “New Inbound Field”;
  2. Selecione o Ion Data Collection Field em que deseja salvar o valor;
  3. Insira uma X-Path Query para analisar o valor do XML;
  4. Salve;
  5. Repita para cada campo que você deseja salvar dentro de Ion Data Collection.

5. Crie uma integração

  1. Volte à tela Integrations;
  2. Clique na aba Integrations;
  3. Clique no botão verde “New Integration”;
  4. Insira uma Label;
  5. Opcionalmente, adicione uma descrição;
  6. Selecione o Field Mapping que você acabou de criar;
  7. Cole o Form URL no editor — este é o "post to" ou URL de ponto final de seu formulário da web;
  8. Defina as tentativas máximas — se houver uma interrupção do serviço com a plataforma externa, ion tentará novamente a postagem exatamente na hora escolhida por quantas tentativas você indicar aqui;
  9. Opcionalmente, marque os requisitos especiais — marque “Send form as multipart/form-data” se aplicável. Marque “Disable URL Encoding of all form data” se os dados não devem ser codificados por URL ou se você está aproveitando Javascript Outbound fields para codificar os dados de forma personalizada. Marque “Empty Fields” para excluir campos externos que não possuem valores dos dados POST;
  10. Selecione POST ou PUT como o método;
  11. Opcionalmente, adicione o endereço de e-mail Debug — os endereços de e-mail especificados aqui receberão um e-mail sempre que a integração for executada, exibindo os dados postados e a resposta recebida. Este é um recurso normalmente usado apenas para teste e solução de problemas;
  12. Opcionalmente, tire proveito do Save Response As — insira dados aqui se quiser salvar a resposta inteira do servidor externo. Isso normalmente é usado para salvar uma resposta não XML para que o código do servidor possa ser usado para analisar os pontos de dados que você deseja salvar na Ion Data Collection;
  13. Adicionar Authentication Requirements — se a integração exigir autenticação NTLM ou Básica, faça sua seleção do menu suspenso Remote Authentication e selecione as Account Credentials correspondentes;
  14. Adicionar Custom Headers — se a integração exigir cabeçalhos http personalizados, insira o(s) nome(s) e valor(es) aqui;
  15. Salve.

6. Adicione Integration às ion Pages

A plataforma ion executa a integração com base nas regras que você cria. As regras podem ser adicionadas a qualquer item acionável em seu Creative ion. As regras de integração são normalmente executadas no nível do formulário, no envio do formulário ou em uma etapa de avaliação. Siga as etapas abaixo para adicionar uma integração às suas páginas ion.

  1. Vá até o Creative;
  2. Clique no formulário, botão ou link que você deseja para tornar gatilho para executar sua integração;
  3. No Creative Studio, clique em ‘+ Rules’;
  4. Selecione a condição que precisa ser atendida para executar a integração —“No conditions required” é normalmente usada;
  5. Selecione “Run integration” como a ação;
  6. Salve.

7. Teste a integração

Para testar sua integração, use o Testing Creative que você configurou antes de iniciar as etapas de integração. Observe que as integrações não são executadas no modo Preview, portanto, você deve abrir um URL para teste.

A integração será executada assim que você enviar o formulário ion ou concluir a ação que executa a regra de integração. Se você estiver na lista de distribuição de e-mail de depuração, receberá um e-mail que exibe os dados postados e a resposta do servidor externo. Você também precisa verificar se os dados enviados foram recebidos pela plataforma externa.

Bom trabalho!

Depois de concluir essas etapas, sua integração está pronta para uso. Você pode adicionar a regra para executar a integração em todos os Creatives aplicáveis. Se você tiver algum problema, entre em contato com help@rockcontent.com.