Conectar o DataScope com o Power Automate

Prefere ler isso em espanhol ou inglês? Versão em espanhol | English version.

Este guia explica como habilitar a integração do DataScope no Power Automate para automatizar sua operação em campo: disparar fluxos quando um formulário é preenchido, quando um documento é gerado, quando uma tarefa é atribuída ou quando um ticket é registrado.

Antes de começar

Você precisa de:

• Uma licença do Power Automate que habilite conectores personalizados. Se não tiver certeza, consulte o administrador do seu tenant da Microsoft.
• Permissão para criar conectores no ambiente do Power Automate em que você vai trabalhar.
• Sua API Key do DataScope. Você a obtém em app.mydatascope.com/integrations, na seção Integrações da sua conta.
• O arquivo apiDefinition.swagger.json fornecido junto com este guia.

Passo 1: criar o conector

1. Acesse make.powerautomate.com e faça login.
2. Selecione o ambiente onde deseja criar o conector, no canto superior direito.
3. No menu lateral, abra Mais e depois Descobrir tudo.
4. Selecione Conectores personalizados.
5. Clique em Novo conector e escolha Importar um arquivo OpenAPI.
6. Digite um nome para o conector, por exemplo DataScope, selecione o arquivo apiDefinition.swagger.json e continue.

Passo 2: revisar a configuração geral

O arquivo já traz configurados o host, o caminho base e a descrição, então não é necessário alterar nada nesta tela.

Se quiser que o conector exiba o logo do DataScope, baixe o ícone do DataScope (PNG) e faça o upload no campo de ícone, depois defina a cor de fundo. Isso é opcional e afeta apenas a aparência.

Passo 3: configurar a autenticação

O arquivo já declara o tipo de autenticação. Verifique se a tela de segurança mostra:

• Tipo de autenticação: Chave de API
• Nome do parâmetro: Authorization
• Localização: Cabeçalho

Continue até o final do assistente e selecione Criar conector.

Passo 4: criar a conexão

Ao usar o conector pela primeira vez em um fluxo, o Power Automate solicitará uma conexão. Cole ali sua API Key do DataScope.

Cada usuário que criar fluxos precisa criar sua própria conexão com a API Key da sua conta.

Atualizar para uma versão mais nova do conector

Quando publicamos uma versão nova do apiDefinition.swagger.json (por exemplo, para adicionar um disparador ou corrigir um campo), você não precisa criar um conector novo — você atualiza o que já existe:

1. Em make.powerautomate.com, vá em Dados > Conectores personalizados.
2. Abra o conector do DataScope, depois abra seu editor do Swagger (ou importe novamente o arquivo pela aba Geral, dependendo da versão do portal em que você está).
3. Substitua a definição pelo arquivo novo e selecione Atualizar conector.

Algumas coisas que vale a pena saber antes de fazer isso:

• Isso atualiza o conector para todos no ambiente, não só para você — não é algo restrito a um único fluxo.
• Os disparadores já configurados continuam funcionando enquanto sua operação subjacente não tiver mudado. Disparadores novos ficam disponíveis para adicionar a fluxos; os que já existem não são adicionados nem removidos automaticamente dos fluxos que já os usam.
• Reveja o ícone, a cor de fundo e a configuração de autenticação depois de atualizar. A documentação da Microsoft não confirma explicitamente se reimportar um arquivo sempre preserva isso, então trate como "verifique, não assuma" em vez de algo garantido.
• Se o disparador de um fluxo parar de se comportar como esperado depois de uma atualização, remova e recrie a conexão desse disparador no fluxo afetado. A própria orientação da Microsoft para atualizar a definição de um conector personalizado recomenda isso como a forma de garantir que um fluxo capte a mudança corretamente.

O que você pode automatizar

O conector oferece os seguintes disparadores. Os nomes são os que você vê na lista de disparadores do Power Automate:

Disparador	É acionado quando
New answer v2 (Forms)	Uma resposta de formulário é enviada por completo, com cada pergunta disponível como seu próprio conteúdo dinâmico
New answer (Forms) (deprecated)	Uma resposta de formulário é enviada. Mantido para que os fluxos já criados sobre ele continuem funcionando
New PDF (Forms)	Um documento PDF é gerado
Status changed (Forms)	Uma resposta de formulário muda de status
New assigned task (Tasks)	Uma tarefa é atribuída
New ticket (Tickets)	Um ticket é registrado
Status changed (Tickets)	Um ticket muda de status
Completed signature (Signatures)	A assinatura de um documento é concluída
Rejected signature (Signatures)	Uma solicitação de assinatura é rejeitada
Updated signature (Signatures)	As assinaturas de um documento são atualizadas

Cada disparador entrega os dados do evento como conteúdo dinâmico, prontos para usar nas próximas etapas do fluxo sem precisar processar o JSON manualmente.

O conector também oferece as seguintes actions, para que um fluxo possa agir sobre o DataScope, e não só reagir aos seus eventos:

Action	O que faz
Assign Task	Atribui uma tarefa de um formulário a um usuário, opcionalmente agendando-a
Change Form Status	Muda o status de uma resposta de formulário
Modify Form Answer	Cria ou modifica uma resposta dentro de um formulário
Send Data	Gera uma nova resposta de formulário e seu PDF a partir de um modelo existente
Create Ticket	Cria um novo ticket

O disparador New answer v2

O New answer v2 (Forms) é o disparador a usar quando você cria um fluxo novo sobre uma resposta de formulário. Ele é acionado quando a resposta chega completa ao DataScope, e seus campos chegam como conteúdo dinâmico que você escolhe direto nas próximas etapas, sem precisar adicionar uma etapa Parse JSON nem colar um schema. As tabelas repetíveis chegam como uma lista de itens da resposta, um por pergunta e por repetição: coloque um Apply to each sobre essa lista e cada item traz como conteúdo dinâmico sua pergunta, seu valor e seu número de linha (subform_index, que conta a partir de 0).

O disparador anterior, New answer (Forms), ficou obsoleto, mas não foi removido. Os fluxos já criados sobre ele continuam rodando exatamente como hoje, e não há prazo para sair dele. O que muda é que ele deixa de ser oferecido quando você cria um fluxo novo, então o que for novo começa na v2.

Para migrar um fluxo existente, crie o novo em paralelo, confirme que ele faz o que você espera e só então exclua o antigo.

Três pontos para levar em conta:

• Uma pergunta com várias respostas chega como uma única linha de texto. O atalho por pergunta sempre traz um valor único, então um Checkbox aparece como os nomes dos elementos marcados, e um Checklist, Dados numéricos ou Dados de texto como pares elemento: valor, separados nos dois casos por ;. Nada disso vem escapado, então trate como texto para mostrar ou guardar, não para separar. Quando precisar desses valores um a um, use a lista de itens da resposta, que traz cada um como campo próprio e com o seu elemento da lista ao lado.
• O pdf_url é oportunista. O campo existe, mas só traz um valor quando o PDF já existe no momento em que a resposta é entregue. O disparador não espera a geração do documento, então um fluxo que usa o pdf_url pode funcionar sempre nos testes e chegar vazio em produção. Se o fluxo precisa do documento, crie-o sobre o disparador New PDF (Forms).
• A lista de campos é um retrato do momento. O conteúdo dinâmico por pergunta que um fluxo enxerga é capturado quando o disparador é configurado. Se depois disso perguntas forem adicionadas ou removidas do formulário, o fluxo não as enxerga até você reabrir o disparador e salvar o fluxo de novo. Os campos de cabeçalho e a lista de itens da resposta não são afetados, apenas os atalhos por pergunta.

Considerações importantes

• Uma conexão ativa por formulário. Os disparadores associados a um formulário admitem apenas uma conexão ativa por vez. Se precisar de vários fluxos sobre o mesmo formulário, encadeie-os a partir de um único disparador. O New answer v2 (Forms) é a exceção: vários fluxos podem usá-lo sobre o mesmo formulário, e cada um recebe sua própria entrega.
• Os disparadores de tickets operam no nível da conta. Admitem apenas uma conexão ativa por conta.
• Os campos disponíveis variam conforme sua configuração. Alguns dados, como os de planejamento ou os campos estendidos de tarefas, aparecem somente se essas funcionalidades estiverem habilitadas na sua conta.
• O conector funciona no ambiente em que foi criado. Se você trabalha com vários ambientes, repita a importação em cada um.
• O disparador New answer (Forms) (deprecated) não se limpa sozinho. Se você desativar ou excluir um flow que o usa (hooks_flow), a assinatura não é removida automaticamente do lado do DataScope. Para interrompê-lo por completo, também é necessário acessar app.mydatascope.com/integrations e excluir a conexão correspondente ali. Nos demais disparadores, incluindo o New answer v2 (Forms), a assinatura é removida do lado do DataScope quando o flow é excluído ou seu disparador é editado, que é o que o Power Automate garante. Se você parar um flow de outra forma e quiser ter certeza de que nada ficou assinado, exclua a conexão nessa mesma página.

Se algo não funcionar

• A conexão falha ao ser criada: verifique se a API Key está completa e sem espaços no início ou no final.
• O fluxo não é disparado: revise o histórico de execuções do fluxo no Power Automate. Nos disparadores que admitem apenas uma conexão por formulário, confirme também que não existe outra conexão ativa sobre esse formulário. Com o New answer v2 (Forms), o fluxo é executado quando a resposta chega completa, e editar uma resposta não o executa de novo.
• Os campos esperados não aparecem: alguns campos dependem da configuração da sua conta. Escreva para o suporte e nós verificamos com você.

Para qualquer dúvida, escreva para o suporte e nós te acompanhamos na configuração.