Add the New answer v2 trigger and deprecate the old one

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)",

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.
+
+<aside class="warning">
+While both flows are active the same form answer is delivered twice, in two different formats, once to each flow. Whatever the flow does happens twice: two work orders, two approvals, two emails. Keep that overlap short, and check the result before you leave both of them running.
+</aside>
+
+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
   <a href="https://app.mydatascope.com/integrations" target="_blank" rel="noopener noreferrer">app.mydatascope.com/integrations</a>
-  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
 

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.
+
+<aside class="warning">
+Mientras los dos flujos estén activos, la misma respuesta de formulario se entrega dos veces, en dos formatos distintos, una vez a cada flujo. Todo lo que haga el flujo ocurre dos veces: dos órdenes de trabajo, dos aprobaciones, dos correos. Mantén corto el periodo en que ambos están activos, y revisa el resultado antes de dejarlos corriendo en paralelo.
+</aside>
+
+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
   <a href="https://app.mydatascope.com/integrations" target="_blank" rel="noopener noreferrer">app.mydatascope.com/integrations</a>
-  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