Add the New answer v2 trigger and deprecate the old one (DS-4558)

source/index.html.md

@@ -99,6 +99,10 @@ We have had ongoing trouble keeping the connector published in the official Powe
 
 Follow the <a href="power_automate/connector_guide_en.html" target="_blank" rel="noopener noreferrer">step-by-step guide</a> to import it and create your first connection. Spanish and Portuguese versions are linked from the top of that guide.
 
+<aside class="notice">
+The New answer v2 (Forms) trigger needs export permission in DataScope for the user whose API Key the connection uses, the same permission the Answers endpoints require. Without it, the trigger is refused with an error that says so. Ask your account administrator to confirm it before you build the flow.
+</aside>
+
 ## Airbyte Cloud connectors
 
 DataScope publishes ready to use low-code connector manifests for Airbyte. Each one is plain YAML: import it in the Connector Builder, fill in your token and a start date, and Airbyte handles the paging, the incremental state and the deduplication.
@@ -2696,6 +2700,13 @@ Remember — use your own Authorization header
 
 # Changelog
 
+**30-Sep-2026**
+
+- The [Microsoft Power Automate](#microsoft-power-automate-beta) connector adds the **New answer v2 (Forms)** trigger. It fires once a form answer is completely submitted, and every form uses the same standard structure: the answers arrive as a list you can loop through with Apply to each, and each question is also available as its own dynamic content, with no Parse JSON step. Several flows can use the same form. Re-import the definition file to pick it up
+- **New answer (Forms)** is deprecated in the connector. Flows already built on it keep running, but it is no longer offered when you build a new flow
+- The [Zapier](#zapier) app adds the **Forms: New Answer v2** trigger in version 2.2.1, with the same structure and the same freedom to use several Zaps on one form
+- Both v2 triggers need export permission for the user whose API Key the connection uses
+
 **10-Sep-2026**
 
 - Documented [Get Answer Statuses](#get-answer-statuses) and [Change Answer Status](#change-answer-status), the two endpoints behind the Change Form Status action of the [Zapier](#zapier) and [Power Automate](#microsoft-power-automate-beta) connectors. Both were already available, they were only missing from this reference

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,134 @@
         ]
       }
     },
+    "/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."
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "The trigger is not enabled for this DataScope account, or the user of the API Key lacks export permission.",
+            "schema": {
+              "type": "object",
+              "description": "Error returned when the subscription is refused.",
+              "properties": {
+                "error": {
+                  "type": "string",
+                  "description": "Reason the subscription was refused, ready to show to the user."
+                }
+              }
+            }
+          }
+        },
+        "operationId": "NewFormAnswerV2",
+        "summary": "New answer v2 (Forms)",
+        "description": "Triggers when a new form answer is complete. Every form uses the same standard structure: answers arrive as a list you can loop through with Apply to each, each with its question ID, value, repeatable group row, list element and location. Several flows can use the same form.",
+        "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 completely 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,33 +114,85 @@ 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 once the answer reaches DataScope complete,
+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, one per question and repetition: put an **Apply to each** over that
+list, and each item carries its question, its value and its row number
+(`subform_index`, counting from 0) as dynamic content.
+
+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 **Checkbox** reads
+  as the names of the items that were checked, and a **Checklist**,
+  **Number Data** or **Text Data** question as `item: 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 list
+  item 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
-  only one active connection at a time. If you need several flows on the
-  same form, chain them from a single trigger.
+  only one active connection at a time. If you need several flows on the same
+  form, chain them from a single trigger. **New answer v2 (Forms)** is the
+  exception: several flows can use it on the same form, and each one receives
+  its own delivery.
 - **Ticket triggers operate at the account level.** They support only one
   active connection per account.
 - **Available fields vary by configuration.** Some data, such as planning
   fields or extended task fields, only appears when those features are
   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
 
 - **The connection fails to create:** check that the API Key is complete,
   with no leading or trailing spaces.
-- **The flow doesn't trigger:** confirm there is no other active connection
-  on the same form, and review the flow's run history in Power Automate.
+- **The flow doesn't trigger:** review the flow's run history in Power
+  Automate. On triggers that allow a single connection per form, also confirm
+  there is no other active connection on that form. With
+  **New answer v2 (Forms)**, the flow runs once the answer is complete, and
+  editing an answer does not run it again.
 - **Expected fields don't appear:** some fields depend on your account's
   configuration. Reach out to support and we'll look into it with you.