diff --git a/source/power_automate/apiDefinition.swagger.json b/source/power_automate/apiDefinition.swagger.json index 4f87a06e07d..3a1d5b2e76c 100644 --- a/source/power_automate/apiDefinition.swagger.json +++ b/source/power_automate/apiDefinition.swagger.json @@ -46,6 +46,43 @@ "x-ms-visibility": "internal" } }, + "/new_answer_v2_schema/{formId}": { + "get": { + "responses": { + "200": { + "description": "Get new answer v2 schema", + "schema": { + "type": "object", + "description": "Description of the answer payload of a selected form.", + "properties": { + "schema": { + "type": "object", + "description": "Field schema of the selected form, used to describe the trigger payload." + } + } + } + } + }, + "summary": "Get new answer v2 schema", + "description": "Retrieves the payload schema of a selected form for the New answer v2 trigger.", + "operationId": "Get-new-answer-v2-schema", + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "formId", + "type": "string", + "in": "path", + "description": "Form whose answer schema is returned.", + "x-ms-url-encoding": "single", + "required": true, + "x-ms-summary": "Select Form" + } + ], + "x-ms-visibility": "internal" + } + }, "/hooks_flow/{formId}": { "x-ms-notification-content": { "schema": { @@ -90,10 +127,16 @@ } } }, - "summary": "New answer (Forms)", - "description": "Triggers when a new answer is submitted. Only one active connection per form is supported.", + "summary": "New answer (Forms) (deprecated)", + "description": "Triggers when a new answer is submitted. Only one active connection per form is supported. (deprecated)", "operationId": "Form-answer", "x-ms-trigger": "single", + "deprecated": true, + "x-ms-api-annotation": { + "status": "Production", + "family": "FormAnswer", + "revision": 1 + }, "parameters": [ { "name": "body", @@ -2144,6 +2187,121 @@ ] } }, + "/hooks/power_automate/new_answer_v2": { + "x-ms-notification-content": { + "schema": { + "type": "object", + "x-ms-dynamic-schema": { + "operationId": "Get-new-answer-v2-schema", + "parameters": { + "formId": { + "parameter": "form_id" + } + }, + "value-path": "schema" + } + } + }, + "post": { + "responses": { + "201": { + "description": "Subscription registered successfully.", + "schema": { + "type": "object", + "description": "Result of the subscription registration.", + "properties": { + "result": { + "type": "string", + "description": "Registration outcome reported by the platform." + } + } + } + }, + "400": { + "description": "The subscription could not be registered.", + "schema": { + "type": "object", + "description": "Error returned when the subscription cannot be registered.", + "properties": { + "error": { + "type": "string", + "description": "Description of the reason the registration failed." + } + } + } + } + }, + "operationId": "NewFormAnswerV2", + "summary": "New answer v2 (Forms)", + "description": "Triggers when a new answer is submitted. Only one active connection per form is supported.", + "x-ms-trigger": "single", + "x-ms-api-annotation": { + "status": "Preview", + "family": "FormAnswer", + "revision": 2 + }, + "parameters": [ + { + "name": "event", + "in": "query", + "required": true, + "type": "string", + "default": "new_answer_v2", + "x-ms-visibility": "internal", + "description": "Event name that identifies the subscription type." + }, + { + "name": "form_id", + "in": "query", + "type": "string", + "description": "Form to monitor for this trigger.", + "x-ms-dynamic-values": { + "operationId": "Form-list", + "value-path": "key", + "value-title": "label" + }, + "required": true, + "x-ms-summary": "Select Form", + "x-ms-visibility": "important" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "type": "object", + "properties": { + "subscription_url": { + "type": "string", + "description": "Callback URL generated by the platform to receive notifications.", + "x-ms-visibility": "internal", + "x-ms-notification-url": true + }, + "version": { + "type": "string", + "description": "Payload version used by the notification contract.", + "x-ms-visibility": "internal", + "default": "2.0.0" + }, + "platform": { + "type": "string", + "description": "Platform that registers the subscription.", + "x-ms-visibility": "internal", + "default": "power_automate" + } + }, + "x-ms-visibility": "internal", + "required": [ + "version", + "subscription_url", + "platform" + ] + }, + "x-ms-visibility": "internal" + } + ] + } + }, "/assign_task": { "post": { "summary": "Assign Task (Tasks)", diff --git a/source/power_automate/connector_guide_en.html.md b/source/power_automate/connector_guide_en.html.md index 29781b21cf6..89978c10fbe 100644 --- a/source/power_automate/connector_guide_en.html.md +++ b/source/power_automate/connector_guide_en.html.md @@ -85,19 +85,21 @@ A few things worth knowing before you do this: ## What you can automate -The connector provides the following triggers: +The connector provides the following triggers. The names are the ones you see +in Power Automate's trigger list: | Trigger | Fires when | |---|---| -| New answer | A form answer is submitted | -| New PDF | A PDF document is generated | -| Status changed | A form answer changes status | -| New assigned task | A task is assigned | -| New ticket | A ticket is registered | -| Ticket status changed | A ticket changes status | -| Completed signature | A document signature is completed | -| Rejected signature | A signature request is rejected | -| Updated signature | The signatures on a document are updated | +| New answer v2 (Forms) | A form answer is submitted, with every question available as its own dynamic content | +| New answer (Forms) (deprecated) | A form answer is submitted. Kept so flows already built on it keep running | +| New PDF (Forms) | A PDF document is generated | +| Status changed (Forms) | A form answer changes status | +| New assigned task (Tasks) | A task is assigned | +| New ticket (Tickets) | A ticket is registered | +| Status changed (Tickets) | A ticket changes status | +| Completed signature (Signatures) | A document signature is completed | +| Rejected signature (Signatures) | A signature request is rejected | +| Updated signature (Signatures) | The signatures on a document are updated | Each trigger delivers the event data as dynamic content, ready to use in the following steps of the flow without having to parse the JSON manually. @@ -112,6 +114,48 @@ The connector also provides the following actions, so a flow can act back on Dat | Send Data | Generates a new form answer and its PDF from an existing template | | Create Ticket | Creates a new ticket | +## The New answer v2 trigger + +**New answer v2 (Forms)** is the trigger to use when you build a new flow on a +submitted form answer. It fires when the answer is submitted, and its fields +arrive as dynamic content you can pick directly in the following steps, with no +**Parse JSON** step to add and no schema to paste. Repeatable tables come +through as a list of answer items: put an **Apply to each** over that list, and +the table's columns are available as dynamic content inside the loop. + +The earlier **New answer (Forms)** trigger is deprecated, not removed. Flows +already built on it keep running exactly as they do today, and there is no +deadline to move off it. What changes is that it is no longer offered when you +build a new flow, so new work starts on v2. + +To move an existing flow, build the new one alongside it, confirm it does what +you expect, and only then delete the old one. + + + +Three things to plan around: + +- **A question with several answers arrives as one line of text.** The + per-question shortcut always carries a single value, so a checklist reads as + the names of what was checked, and a question over a list as `option: value` + pairs, separated in both cases by `;`. Nothing in it is escaped, so treat it + as text to show or store, not to split apart. When you need those values one + by one, use the list of answer items, which carries each one as its own field + with its option beside it. +- **`pdf_url` is opportunistic.** The field is there, but it carries a value + only when the PDF already exists at the moment the answer is delivered. The + trigger does not wait for the document to be generated, so a flow that binds + `pdf_url` can work every time in testing and then arrive with it empty in + production. If the flow needs the document, build it on the + **New PDF (Forms)** trigger instead. +- **The field list is a snapshot.** The per-question dynamic content a flow + sees is captured when the trigger is configured. If questions are added to or + removed from the form afterwards, the flow does not see them until you reopen + the trigger and save the flow again. The header fields and the list of answer + items are not affected, only the per-question shortcuts. + ## Important considerations - **One active connection per form.** Triggers associated with a form support @@ -124,14 +168,16 @@ The connector also provides the following actions, so a flow can act back on Dat enabled on your account. - **The connector works in the environment where you created it.** If you work with several environments, repeat the import in each one. -- **The "New answer" trigger doesn't clean up on its own.** If you turn off or - delete a flow that uses the "New answer" trigger (`hooks_flow`), the - subscription is not automatically removed on DataScope's side. To fully - stop it, you also need to go to +- **The New answer (Forms) (deprecated) trigger doesn't clean up on its own.** + If you turn off or delete a flow that uses it (`hooks_flow`), the + subscription is not automatically removed on DataScope's side. To fully stop + it, you also need to go to app.mydatascope.com/integrations - and delete the connection there. Every other trigger (forms, PDFs, tasks, - tickets, signatures) does clean up automatically when the flow is turned - off in Power Automate. + and delete the connection there. The other triggers, + **New answer v2 (Forms)** included, are unsubscribed on DataScope's side when + the flow is deleted or its trigger is edited, which is what Power Automate + guarantees. If you stop a flow in any other way and want to be sure nothing + is left subscribed, delete its connection on that same page. ## If something doesn't work diff --git a/source/power_automate/connector_guide_es.html.md b/source/power_automate/connector_guide_es.html.md index dd01491b95a..16c091152fa 100644 --- a/source/power_automate/connector_guide_es.html.md +++ b/source/power_automate/connector_guide_es.html.md @@ -84,19 +84,21 @@ Algunas cosas que vale la pena saber antes de hacer esto: ## Qué puedes automatizar -El conector entrega los siguientes disparadores: +El conector entrega los siguientes disparadores. Los nombres son los que ves en +la lista de disparadores de Power Automate: | Disparador | Se activa cuando | |---|---| -| Nueva respuesta | Se envía una respuesta de formulario | -| Nuevo PDF | Se genera un documento PDF | -| Cambio de estado | Una respuesta de formulario cambia de estado | -| Nueva tarea asignada | Se asigna una tarea | -| Nuevo ticket | Se registra un ticket | -| Cambio de estado de ticket | Un ticket cambia de estado | -| Firma completada | Se completa la firma de un documento | -| Firma rechazada | Se rechaza una solicitud de firma | -| Firma actualizada | Se actualizan las firmas de un documento | +| New answer v2 (Forms) | Se envía una respuesta de formulario, con cada pregunta disponible como su propio contenido dinámico | +| New answer (Forms) (deprecated) | Se envía una respuesta de formulario. Se mantiene para que los flujos ya armados sobre él sigan funcionando | +| New PDF (Forms) | Se genera un documento PDF | +| Status changed (Forms) | Una respuesta de formulario cambia de estado | +| New assigned task (Tasks) | Se asigna una tarea | +| New ticket (Tickets) | Se registra un ticket | +| Status changed (Tickets) | Un ticket cambia de estado | +| Completed signature (Signatures) | Se completa la firma de un documento | +| Rejected signature (Signatures) | Se rechaza una solicitud de firma | +| Updated signature (Signatures) | Se actualizan las firmas de un documento | Cada disparador entrega los datos del evento como contenido dinámico, listos para usar en los pasos siguientes del flujo sin necesidad de procesar el JSON @@ -112,6 +114,50 @@ El conector también entrega las siguientes actions, para que un flujo pueda act | Send Data | Genera una nueva respuesta de formulario y su PDF a partir de una plantilla existente | | Create Ticket | Crea un nuevo ticket | +## El disparador New answer v2 + +**New answer v2 (Forms)** es el disparador que conviene usar al armar un flujo +nuevo sobre una respuesta de formulario. Se activa cuando la respuesta se +envía, y sus campos llegan como contenido dinámico que puedes elegir +directamente en los pasos siguientes, sin agregar un paso **Parse JSON** ni +pegar un esquema. Las tablas repetibles llegan como una lista de ítems de la +respuesta: pon un **Apply to each** sobre esa lista y las columnas de la tabla +quedan disponibles como contenido dinámico dentro del ciclo. + +El disparador anterior, **New answer (Forms)**, queda obsoleto, pero no se +elimina. Los flujos que ya están armados sobre él siguen funcionando igual que +hoy, y no hay plazo para dejarlo. Lo que cambia es que ya no se ofrece al armar +un flujo nuevo, así que lo nuevo parte en v2. + +Para pasar un flujo existente, arma el nuevo en paralelo, confirma que hace lo +que esperas y solo entonces elimina el antiguo. + + + +Tres cosas para tener en cuenta: + +- **Una pregunta con varias respuestas llega como una sola línea de texto.** El + acceso directo por pregunta siempre trae un valor único, así que un checklist + se lee como los nombres de lo que quedó marcado, y una pregunta sobre una + lista como pares `opción: valor`, separados en ambos casos por `;`. Nada de + eso viene escapado, así que conviene tratarlo como texto para mostrar o + guardar, no para separar. Cuando necesites esos valores uno por uno, usa la + lista de ítems de la respuesta, que trae cada uno como campo propio y con su + opción al lado. +- **`pdf_url` es oportunista.** El campo está, pero trae un valor solo cuando + el PDF ya existe en el momento en que se entrega la respuesta. El disparador + no espera a que el documento se genere, así que un flujo que usa `pdf_url` + puede funcionar siempre en las pruebas y llegar vacío en producción. Si el + flujo necesita el documento, ármalo sobre el disparador **New PDF (Forms)**. +- **La lista de campos es una instantánea.** El contenido dinámico por pregunta + que ve un flujo se captura cuando se configura el disparador. Si después se + agregan o se eliminan preguntas del formulario, el flujo no las ve hasta que + vuelvas a abrir el disparador y guardes el flujo de nuevo. Los campos de + cabecera y la lista de ítems de la respuesta no se ven afectados, solo los + accesos directos por pregunta. + ## Consideraciones importantes - **Una conexión activa por formulario.** Los disparadores asociados a un @@ -124,14 +170,17 @@ El conector también entrega las siguientes actions, para que un flujo pueda act funcionalidades están habilitadas en tu cuenta. - **El conector funciona en el entorno donde lo creaste.** Si trabajas con varios entornos, repite la importación en cada uno. -- **El disparador "Nueva respuesta" no se limpia solo al apagarlo.** Si detienes - o eliminas un flow que usa el disparador "Nueva respuesta" (`hooks_flow`), la - suscripción no se elimina automáticamente del lado de DataScope. Para - detenerlo por completo, también debes ir a +- **El disparador New answer (Forms) (deprecated) no se limpia solo.** Si + detienes o eliminas un flow que lo usa (`hooks_flow`), la suscripción no se + elimina automáticamente del lado de DataScope. Para detenerlo por completo, + también debes ir a app.mydatascope.com/integrations - y eliminar ahí la conexión correspondiente. El resto de los disparadores - (formularios, PDFs, tareas, tickets, firmas) sí se limpian automáticamente - al apagar el flow en Power Automate. + y eliminar ahí la conexión correspondiente. En el resto de los disparadores, + incluido **New answer v2 (Forms)**, la suscripción se elimina del lado de + DataScope cuando se borra el flow o se edita su disparador, que es lo que + garantiza Power Automate. Si detienes un flow de otra manera y quieres + asegurarte de que no quede nada suscrito, elimina su conexión en esa misma + página. ## Si algo no funciona diff --git a/source/power_automate/connector_guide_pt.html.md b/source/power_automate/connector_guide_pt.html.md index c1b37c89c2f..1fa87c0c833 100644 --- a/source/power_automate/connector_guide_pt.html.md +++ b/source/power_automate/connector_guide_pt.html.md @@ -85,19 +85,21 @@ Algumas coisas que vale a pena saber antes de fazer isso: ## O que você pode automatizar -O conector oferece os seguintes disparadores: +O conector oferece os seguintes disparadores. Os nomes são os que você vê na +lista de disparadores do Power Automate: | Disparador | É acionado quando | |---|---| -| Nova resposta | Uma resposta de formulário é enviada | -| Novo PDF | Um documento PDF é gerado | -| Mudança de status | Uma resposta de formulário muda de status | -| Nova tarefa atribuída | Uma tarefa é atribuída | -| Novo ticket | Um ticket é registrado | -| Mudança de status de ticket | Um ticket muda de status | -| Assinatura concluída | A assinatura de um documento é concluída | -| Assinatura rejeitada | Uma solicitação de assinatura é rejeitada | -| Assinatura atualizada | As assinaturas de um documento são atualizadas | +| New answer v2 (Forms) | Uma resposta de formulário é enviada, 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 @@ -113,6 +115,49 @@ O conector também oferece as seguintes actions, para que um fluxo possa agir so | 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 é +enviada, 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: +coloque um **Apply to each** sobre essa lista e as colunas da tabela ficam +disponíveis como conteúdo dinâmico dentro do loop. + +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 checklist aparece + como os nomes do que foi marcado, e uma pergunta sobre uma lista como pares + `opção: 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 a sua opção 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 @@ -126,14 +171,16 @@ O conector também oferece as seguintes actions, para que um fluxo possa agir so 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 "Nova resposta" não se limpa sozinho.** Se você desativar ou - excluir um flow que usa o disparador "Nova resposta" (`hooks_flow`), a - assinatura não é removida automaticamente do lado do DataScope. Para - interrompê-lo por completo, também é necessário acessar +- **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. Os demais disparadores - (formulários, PDFs, tarefas, tickets, assinaturas) se limpam - automaticamente ao desativar o flow no Power Automate. + 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