diff --git a/source/index.html.md b/source/index.html.md index ce4679528e7..1c6cbf07d32 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -54,7 +54,7 @@ Method | Direction | Fits when [Webhooks](#webhooks) | DataScope pushes, your endpoint reacts | Something has to happen the moment a form arrives The REST endpoints | You pull, on your own schedule | You are building a custom integration, or you need a specific slice on demand [Airbyte Cloud connectors](#airbyte-cloud-connectors) | You pull, Airbyte runs it | The destination is a data warehouse and you want the paging, the incremental state and the deduplication handled for you -[Zapier](https://zapier.com/apps/datascope-forms/integrations) | DataScope pushes, Zapier reacts | You want the same webhook push as a no-code connector, without building your own receiving endpoint +[Zapier](#zapier) | DataScope pushes, Zapier reacts, and Zaps can write back | You want the webhook push delivered into the apps your team already uses, without building your own receiving endpoint [Microsoft Power Automate](#microsoft-power-automate-beta) | DataScope pushes, Power Automate reacts | Same idea, wired into a Power Automate flow with the event data exposed as dynamic content A **webhook** fits when something has to happen the moment a form arrives: notify a system, start a workflow, post to a channel. DataScope pushes, your endpoint reacts. It covers new submissions, and edits too when you enable **Send modifications** on the webhook. @@ -71,6 +71,22 @@ If the destination is a data warehouse, you do not have to write the receiver, t Using both is normal. A webhook for the immediate reaction, a connector for the warehouse copy. +## Zapier + +DataScope publishes an app for Zapier, so you can trigger Zaps from form answers, generated PDFs, task assignments, tickets and signature events, and act back on DataScope with actions like assigning a task or creating a ticket. + +There is nothing to import. The app is published in Zapier's app directory, and the only thing you need to connect it is your API Key. + +Open the DataScope app in Zapier + +Follow the step-by-step guide to create the connection and your first Zap. Spanish and Portuguese versions are linked from the top of that guide. + +The guide ends with a changelog of the app's versions, where you can check which version is published and what it changed. + + + ## Microsoft Power Automate [Beta] DataScope publishes a custom connector for Microsoft Power Automate, so you can trigger flows from form answers, generated PDFs, task assignments, tickets and signature events, delivered as dynamic content instead of raw webhook JSON. @@ -2549,6 +2565,11 @@ Remember — use your own Authorization header # Changelog +**26-Aug-2026** + +- Added the [Zapier](#zapier) section under Data Export, with a step-by-step guide in English, Spanish and Portuguese covering the connection, every trigger and action, the Locations and Places choice, and the one-Zap-per-form constraint +- The Zapier guide now ends with a changelog of the app's versions, so you can tell which version is published and what it changed + **20-Aug-2026** - Added the [Microsoft Power Automate](#microsoft-power-automate-beta) section under Data Export, with a downloadable connector definition and a step-by-step guide in English, Spanish and Portuguese diff --git a/source/zapier/connector_guide_en.html.md b/source/zapier/connector_guide_en.html.md new file mode 100644 index 00000000000..1f8f0f6fd18 --- /dev/null +++ b/source/zapier/connector_guide_en.html.md @@ -0,0 +1,320 @@ +--- +title: Connect DataScope with Zapier +--- + +# Connect DataScope with Zapier + +> ¿Prefieres leer esto en español o portugués? [Ve a la guía en español](connector_guide_es.html) | [Versão em português](connector_guide_pt.html). + +This guide explains how to connect DataScope with Zapier to automate your +field operation: trigger Zaps when a form is completed, when a document is +generated, when a task is assigned or when a ticket is registered, and act +back on DataScope from the other apps you already use. + + + +## Before you start + +You need: + +- A Zapier account with permission to create Zaps in the workspace you are + working in. +- Your DataScope API Key. You get it from app.mydatascope.com/integrations, + in the Integrations section of your account, under the API Key tab. +- At least one published form in DataScope. Most triggers and actions ask you + to pick a form, and the dropdown reads the forms in your account. + +## Step 1: create the Zap + +1. Go to the DataScope app in Zapier and sign in. +2. Select **Create Zap**, or start from one of the ready-made templates listed + on that page. The Integrations section of DataScope lists the same + templates, grouped by use case. +3. In the trigger step, search for **DataScope Forms** and select it. +4. Choose the event you want to react to, from the list under + [What you can automate](#what-you-can-automate). + +## Step 2: create the connection + +The first time you use DataScope in a Zap, Zapier asks you for a connection +and shows a single field, **Token Key**. Paste your DataScope API Key there. + +Paste it exactly as DataScope shows it, with no leading or trailing spaces. +If the connection is accepted but the trigger then returns no data at all, the +key is the first thing to re-check. + +The connection belongs to your Zapier account and you can reuse it in every +Zap you build. Each person who builds Zaps needs their own connection, with +the API Key of their own account. + +## Step 3: choose the form + +Most triggers show a **Form** dropdown that reads the forms in your account. +Where the field is optional, pick a form anyway. + + + +## Step 4: test and turn the Zap on + +Zapier's **Test trigger** pulls the most recent matching events from your +account, so it needs at least one to show sample data. If your account has +none yet, submit a form answer, generate a document, or assign a task, +depending on the trigger you picked, and test again. + +Once the sample data looks right, add the steps that follow and publish the +Zap. The subscription on DataScope's side is created when you turn the Zap +on, not while you are editing it. + +## What you can automate + +The DataScope app provides the following triggers. The names are the ones you +see in Zapier's trigger list: + +| Trigger | Fires when | Form field | +|---|---|---| +| Forms: New Form Entry | A form answer is submitted | Required | +| Forms: New PDF | A PDF is generated by email backup or auto-notify | Optional, pick one | +| Forms: Status Changed | A form answer changes status | Optional, pick one | +| Tasks: New Assigned Task | A task is assigned | Required | +| Signatures: New Completed Signature | Every signer has signed the document | Optional, pick one | +| Signatures: New Rejected Signature | A signer rejects the signature request | Optional, pick one | +| Signatures: Updated Signature | The signatures on a document change while some are still pending | Optional, pick one | +| Tickets: New Ticket (FKA Issue) | A ticket is created | Not applicable, account level | +| Tickets: Changed Status (FKA Issue) | A ticket changes status | Not applicable, account level | + +Each trigger delivers the event data as individual fields, ready to map into +the following steps of the Zap without having to parse the JSON yourself. For +form answers, every question arrives as its own field, with its name, its type +and its value. + +The app also provides the following actions, so a Zap can act back on +DataScope instead of only reacting to it: + +| Action | What it does | +|---|---| +| Tasks: Assign Task V2 | Assigns a task on a form to a user, optionally scheduling it and linking it to a location or a place | +| Tasks: Assign Task V1 [Legacy] | The earlier version of the same action, kept so existing Zaps keep working | +| Forms: Send Data / New Answer [Beta] | Generates a new form answer and its PDF from an existing form used as a template | +| Change Form Status | Changes the status of a form answer, found by form name and form code | +| Modify Form Answer | Creates or updates a single answer inside an existing form response | +| Tickets: Create Ticket (FKA Issue) | Creates a ticket, optionally taking its defaults from a Ticket Type | + +### Assign Task: V1 or V2 + +Use **V2** for anything new. It does everything V1 does, plus: + +- It accepts plus signs in the user's email address, so + `user+site@example.com` resolves to the right user. +- It can target the new **Places** module, not only the legacy Locations one. +- It can find an existing location or place by its internal ID, which is what + you want when several places share a name. + +**V1** stays available so Zaps built on it keep running. There is no automatic +migration: if you want a V1 Zap on V2, replace the action step and map the +fields again. + + + +### Locations or Places + +**Tasks: Assign Task V2** and **Tickets: Create Ticket** both have a +**Location Type** field with two options, and the two actions do not behave the +same way. On **Assign Task V2**: + + + + +| Location Type | Behavior when nothing matches | +|---|---| +| Locations (old module, legacy) | The location is created in DataScope from the Location Name and the other location fields you sent. With no Location Name there is nothing to create it from, so the task is assigned with no location | +| Places (new module) | Nothing is created. The task is not assigned and the Zap fails with `nestable location not found` | + +**Tickets: Create Ticket** never creates a location, with either option. If the +location you send does not match an existing record, the ticket is created with +no location attached and the Zap reports success. It matches on Location ID and +then Location Name only. + +Locations is the default, so existing Zaps keep working with no changes. If you +choose Places, create the place in DataScope before the Zap runs. + +On **Assign Task V2** the location is matched in this order: Location / Place +ID, then Location Code, then Location Name, then Location Address. The first +one that matches wins. + +The remaining location fields, Location Phone, Location Email, Company Name, +Company Legal ID, Latitude and Longitude, apply only to the legacy Locations +module, where they are saved on the location that is matched or created. They +are ignored with Places, because places are never modified from this action. + +### Send Data / New Answer is in Beta + +**Forms: Send Data / New Answer** creates a form answer from an existing form, +which makes it useful for bringing data captured elsewhere into DataScope. Three +things to plan around: + +- **The PDF is only generated if you fill the Emails field.** That field is what + sends the document, and generating it is part of sending it. Leave it empty and + you get the form answer with no PDF. +- **It does not trigger the rest of the automation chain.** Google Sheets sync, + automatic signature and the form-answer webhooks do not run for an answer + created this way, so a Zap that reacts to `Forms: New Form Entry` will not see + it. `Forms: New PDF` is the exception: when you fill the Emails field, that Zap + does fire. +- **Not every question type is fully supported**, so some fields may not land as + you expect. Test with the form you actually plan to use. + +## Important considerations + +- **One active Zap per form and per trigger, with one exception.** + `Forms: New PDF`, `Forms: Status Changed`, `Tasks: New Assigned Task` and the + three signature triggers support a single active subscription per form. Turning + on a second Zap with the same trigger on the same form is rejected with an + error naming the trigger type and asking you to remove the previous one. + Different triggers on the same form are fine, and so is the same trigger on + different forms. **`Forms: New Form Entry` is not covered by that check**: a + second Zap on the same form is accepted, and both then receive every + submission. Add steps to one Zap instead. +- **If you need several things to happen on one event, add steps to one Zap** + rather than creating a second Zap on the same trigger and form. +- **Ticket triggers work at the account level.** `Tickets: New Ticket` and + `Tickets: Changed Status` cover every ticket in the account and support one + active Zap per account each. They have no Form field. +- **Available fields vary by configuration.** Some data, such as signer + identity fields or extended task fields, appears only when those features + are enabled on your account. +- **A trigger's sample data is not the full field list.** Zapier builds the + field list from recent events, so a question that nobody has answered yet, + or an optional field that was empty, may not appear until it does. Send one + representative answer before mapping the steps that follow. +- **The `Forms: New Form Entry` trigger is visible on DataScope's side.** It + registers itself in the Webhooks list of + app.mydatascope.com/integrations. + The other triggers do not appear in that list. + +## If something doesn't work + +- **The connection is accepted but nothing works:** the connection test does not + reliably reject a wrong key, so a bad API Key surfaces later as a trigger that + returns no data at all. Re-copy the key from the Integrations section, with no + leading or trailing spaces, and replace the connection. +- **Turning the Zap on fails saying the hook already exists:** another Zap in + your account, possibly built by someone else, already uses that trigger on + that form. Turn the older Zap off, then turn this one on. If the error + persists, contact support and we will clear the leftover subscription. +- **Test trigger returns no data:** the trigger reads recent events, so an + account with none yet has nothing to show. Produce one and test again. +- **The Zap never fires:** confirm that a form is selected in the trigger, + that the Zap is on, and check the Zap history in Zapier. An event that + arrived while the Zap was off is not replayed. +- **A Zap you turned off keeps receiving data:** if the trigger is + `Forms: New Form Entry`, open the Webhooks list at + app.mydatascope.com/integrations + and delete the entry there. +- **Expected fields don't appear:** some fields depend on your account's + configuration. Reach out to support and we will look into it with you. + +For any question, contact support and we will help you with the setup. + +## Changelog + +Versions of the DataScope app in Zapier, newest first. A Zap keeps running on +the version it was created with, so an older Zap can behave differently from a +new one built on the same trigger, and there is nothing to install or update on +your side either way. Some versions are released to selected accounts before +they become the default for new Zaps, so the version behind your Zap is not +always the current one. + +Two numbers, 2.0.0 and 2.1.0, were never released. Because of that, the release +notes recorded on 2.0.1 and 2.1.1 describe only the difference from a draft that +no longer exists. The bullets below describe the difference from the previous +released version instead. + + + + + +**2.1.3** (released to selected accounts) + +- Adds the `Location Type` field to `Tasks: Assign Task V2` and to + `Tickets: Create Ticket`, with the `Places (new module)` option next to the + legacy Locations one. +- Adds `Find Location / Place by ID` to `Tasks: Assign Task V2`, so a task can + point at an existing location or place by its internal ID. + +**2.1.2** (default for new Zaps) + +- Adds the action `Tasks: Assign Task V2`, and relabels the previous one + `Tasks: Assign Task V1 [Legacy]`. V2 accepts user email addresses that contain + plus signs. + +**2.1.1** + +- Renames the two ticket triggers. `Findings: New Finding` becomes + `Tickets: New Ticket (FKA Issue)`, and `Findings: Changed Status` becomes + `Tickets: Changed Status (FKA Issue)`. +- Adds the action `Tickets: Create Ticket (FKA Issue)`. +- Fixes a bug with the creation date and the relative expiration date. + +**2.0.2** + +- Location Name is no longer required on the `Assign Task` action. +- Changes some output field types. + +**2.0.1** + +- The first released version of the 2.x line, and the first with the three + signature triggers and the two ticket triggers, then named + `Findings: New Finding` and `Findings: Changed Status`. +- Consolidates what the 1.14 drafts had added separately: the status trigger, + the `Send Data` action, and the mandatory and late-response fields on + `Assign Task`. +- Prefixes every trigger and action name with its area, `Forms:`, `Tasks:` or + `Signatures:`. +- Improves a default value. + +**1.14.3** + +- Adds `Make this task mandatory` and `Allow the task to be answered after the + due date has been reached` to the `Assign Task` action. +- Does not carry the `Status Changed` trigger or the `Send Data` action that + 1.14.2 has, so a Zap on this version has three triggers and three actions. + +**1.14.2** + +- Adds the action `Send Data`. +- Renames the `Change Status` trigger to `Status Changed`, and its Form field + becomes optional. + +**1.14.1** + +- Adds the `Change Status` trigger. + +**1.14.0** + +- The baseline of the 1.14 line: `New Form Entry`, `New Assigned Task` and + `New PDF` as triggers, `Assign Task`, `Change Form Status` and + `Modify Form Answer` as actions. `Assign Task` requires a Location Name here. +- The three signature triggers, the two ticket triggers, `Assign Task V2` and + `Create Ticket` only exist on the 2.x line. To use any of them, rebuild the + Zap so it picks up the current version. diff --git a/source/zapier/connector_guide_es.html.md b/source/zapier/connector_guide_es.html.md new file mode 100644 index 00000000000..2c1b277ff97 --- /dev/null +++ b/source/zapier/connector_guide_es.html.md @@ -0,0 +1,332 @@ +--- +title: Conectar DataScope con Zapier +--- + +# Conectar DataScope con Zapier + +> Reading this in English or Portuguese? [Switch to the English guide](connector_guide_en.html) | [Versão em português](connector_guide_pt.html). + +Esta guía explica cómo conectar DataScope con Zapier para automatizar tu +operación en terreno: disparar Zaps cuando se completa un formulario, cuando +se genera un documento, cuando se asigna una tarea o cuando se registra un +ticket, y actuar sobre DataScope desde las otras aplicaciones que ya usas. + + + +## Antes de empezar + +Necesitas: + +- Una cuenta de Zapier con permisos para crear Zaps en el espacio de trabajo + donde vas a trabajar. +- Tu API Key de DataScope. La obtienes desde app.mydatascope.com/integrations, + en la sección Integraciones de tu cuenta, en la pestaña API Key. +- Al menos un formulario publicado en DataScope. La mayoría de los disparadores + y de las actions te piden elegir un formulario, y la lista se llena con los + formularios de tu cuenta. + +## Paso 1: crear el Zap + +1. Entra a la app de DataScope en Zapier e inicia sesión. +2. Selecciona **Create Zap**, o parte de una de las plantillas listadas en esa + página. La sección Integraciones de DataScope lista las mismas plantillas, + agrupadas por caso de uso. +3. En el paso del disparador, busca **DataScope Forms** y selecciónalo. +4. Elige el evento al que quieres reaccionar, de la lista en + [Qué puedes automatizar](#que-puedes-automatizar). + +## Paso 2: crear la conexión + +La primera vez que uses DataScope en un Zap, Zapier te pedirá una conexión y +te mostrará un solo campo, **Token Key**. Pega ahí tu API Key de DataScope. + +Pégala tal como DataScope te la muestra, sin espacios al inicio ni al final. +Si la conexión se acepta pero después el disparador no devuelve ningún dato, la +API Key es lo primero que conviene revisar. + +La conexión pertenece a tu cuenta de Zapier y puedes reutilizarla en todos los +Zaps que armes. Cada persona que arme Zaps necesita su propia conexión, con la +API Key de su cuenta. + +## Paso 3: elegir el formulario + +La mayoría de los disparadores muestran una lista **Form** con los formularios +de tu cuenta. Aunque el campo sea opcional, elige un formulario igual. + + + +## Paso 4: probar y activar el Zap + +El botón **Test trigger** de Zapier trae los últimos eventos que calzan con el +disparador, así que necesita al menos uno para mostrarte datos de ejemplo. Si +tu cuenta todavía no tiene ninguno, envía una respuesta de formulario, genera +un documento o asigna una tarea, según el disparador que elegiste, y prueba de +nuevo. + +Cuando los datos de ejemplo se vean bien, agrega los pasos siguientes y +publica el Zap. La suscripción del lado de DataScope se crea al activar el +Zap, no mientras lo estás editando. + +## Qué puedes automatizar + +La app de DataScope entrega los siguientes disparadores. Los nombres son los +que ves en la lista de disparadores de Zapier: + +| Disparador | Se activa cuando | Campo Form | +|---|---|---| +| Forms: New Form Entry | Se envía una respuesta de formulario | Obligatorio | +| Forms: New PDF | Se genera un PDF por respaldo por email o por autonotificación | Opcional, elige uno | +| Forms: Status Changed | Una respuesta de formulario cambia de estado | Opcional, elige uno | +| Tasks: New Assigned Task | Se asigna una tarea | Obligatorio | +| Signatures: New Completed Signature | Todos los firmantes firmaron el documento | Opcional, elige uno | +| Signatures: New Rejected Signature | Un firmante rechaza la solicitud de firma | Opcional, elige uno | +| Signatures: Updated Signature | Cambian las firmas de un documento y todavía quedan pendientes | Opcional, elige uno | +| Tickets: New Ticket (FKA Issue) | Se crea un ticket | No aplica, es a nivel de cuenta | +| Tickets: Changed Status (FKA Issue) | Un ticket cambia de estado | No aplica, es a nivel de cuenta | + +Cada disparador entrega los datos del evento como campos individuales, listos +para mapear en los pasos siguientes del Zap sin tener que procesar el JSON +manualmente. En el caso de las respuestas de formulario, cada pregunta llega +como su propio campo, con su nombre, su tipo y su valor. + +La app también entrega las siguientes actions, para que un Zap pueda actuar +sobre DataScope y no solo reaccionar a sus eventos: + +| Action | Qué hace | +|---|---| +| Tasks: Assign Task V2 | Asigna una tarea de un formulario a un usuario, opcionalmente agendándola y vinculándola a una ubicación o a un lugar | +| Tasks: Assign Task V1 [Legacy] | La versión anterior de la misma action, se mantiene para que los Zaps existentes sigan funcionando | +| Forms: Send Data / New Answer [Beta] | Genera una nueva respuesta de formulario y su PDF a partir de un formulario existente usado como plantilla | +| Change Form Status | Cambia el estado de una respuesta de formulario, identificada por nombre y código de formulario | +| Modify Form Answer | Crea o modifica una respuesta puntual dentro de un formulario ya enviado | +| Tickets: Create Ticket (FKA Issue) | Crea un ticket, opcionalmente tomando sus valores por defecto de un Ticket Type | + +### Assign Task: V1 o V2 + +Usa **V2** para todo lo nuevo. Hace todo lo que hace V1, y además: + +- Acepta el signo más en el email del usuario, así que + `usuario+obra@ejemplo.com` resuelve al usuario correcto. +- Puede apuntar al módulo de lugares nuevo, no solo al antiguo. +- Puede encontrar una ubicación o un lugar existente por su ID interno, que es + lo que necesitas cuando varios lugares comparten el nombre. + +**V1** sigue disponible para que los Zaps creados sobre ella sigan corriendo. +No hay migración automática: si quieres pasar un Zap de V1 a V2, reemplaza el +paso de la action y vuelve a mapear los campos. + + + +### Locations o Places + +**Tasks: Assign Task V2** y **Tickets: Create Ticket** tienen un campo +**Location Type** con dos opciones, y las dos acciones no se comportan igual. En +**Assign Task V2**: + + + + +| Location Type | Comportamiento cuando nada coincide | +|---|---| +| Locations (old module, legacy) | El lugar se crea en DataScope a partir del Location Name y de los demás campos de ubicación que enviaste. Sin Location Name no hay con qué crearlo, así que la tarea se asigna sin lugar | +| Places (new module) | No se crea nada. La tarea no se asigna y el Zap falla con `nestable location not found` | + +**Tickets: Create Ticket** nunca crea un lugar, con ninguna de las dos opciones. +Si el lugar que envías no coincide con un registro existente, el ticket se crea +sin lugar asociado y el Zap reporta éxito. Solo busca por Location ID y después +por Location Name. + +Locations es la opción por defecto, así que los Zaps existentes siguen +funcionando sin cambios. Si eliges Places, crea el lugar en DataScope antes de +que corra el Zap. + +En **Assign Task V2** la ubicación se busca en este orden: Location / Place +ID, después Location Code, después Location Name y después Location Address. +Gana la primera que calza. + +El resto de los campos de ubicación, Location Phone, Location Email, Company +Name, Company Legal ID, Latitude y Longitude, aplican solo al módulo de lugares +antiguo, donde se guardan en el lugar que se encontró o se creó. Se +ignoran con Places, porque los lugares nunca se modifican desde esta action. + +### Send Data / New Answer está en Beta + +**Forms: Send Data / New Answer** crea una respuesta de formulario a partir de un +formulario existente, lo que la hace útil para traer a DataScope datos capturados +en otra parte. Tres cosas que conviene tener en cuenta: + +- **El PDF se genera solo si completas el campo Emails.** Ese campo es el que + envía el documento, y generarlo es parte de enviarlo. Si lo dejas vacío, + obtienes la respuesta de formulario sin PDF. +- **No dispara el resto de la cadena de automatización.** La sincronización con + Google Sheets, la firma automática y los webhooks de respuestas de formulario + no corren para una respuesta creada así, por lo que un Zap que reacciona a + `Forms: New Form Entry` no la va a ver. `Forms: New PDF` es la excepción: si + completas el campo Emails, ese Zap sí se dispara. +- **No todos los tipos de pregunta están soportados por completo**, así que + algunos campos pueden no quedar como esperas. Prueba con el formulario que vas + a usar de verdad. + +## Consideraciones importantes + +- **Un Zap activo por formulario y por disparador, con una excepción.** + `Forms: New PDF`, `Forms: Status Changed`, `Tasks: New Assigned Task` y los + tres disparadores de firma admiten una sola suscripción activa por formulario. + Activar un segundo Zap con el mismo disparador sobre el mismo formulario se + rechaza con un error que nombra el tipo de disparador y te pide eliminar el + anterior. Disparadores distintos sobre el mismo formulario no son problema, y + tampoco el mismo disparador sobre formularios distintos. + **`Forms: New Form Entry` no pasa por esa validación**: un segundo Zap sobre el + mismo formulario se acepta, y después los dos reciben todos los envíos. Agrega + pasos a un solo Zap en vez de eso. +- **Si necesitas que pasen varias cosas con un mismo evento, agrega pasos a un + solo Zap** en vez de crear un segundo Zap con el mismo disparador y + formulario. +- **Los disparadores de tickets operan a nivel de cuenta.** `Tickets: New + Ticket` y `Tickets: Changed Status` cubren todos los tickets de la cuenta y + admiten un Zap activo por cuenta cada uno. No tienen campo Form. +- **Los campos disponibles varían según tu configuración.** Algunos datos, como + los de identidad de los firmantes o los campos extendidos de tareas, + aparecen solo si esas funcionalidades están habilitadas en tu cuenta. +- **Los datos de ejemplo de un disparador no son la lista completa de campos.** + Zapier arma la lista a partir de los eventos recientes, así que una pregunta + que nadie respondió todavía, o un campo opcional que llegó vacío, puede no + aparecer hasta que lo haga. Envía una respuesta representativa antes de + mapear los pasos siguientes. +- **El disparador `Forms: New Form Entry` es visible del lado de DataScope.** + Se registra en la lista de Webhooks de + app.mydatascope.com/integrations. + El resto de los disparadores no aparece en esa lista. + +## Si algo no funciona + +- **La conexión se acepta pero nada funciona:** la prueba de conexión no rechaza + de forma confiable una API Key incorrecta, así que una clave mala aparece más + tarde como un disparador que no devuelve ningún dato. Vuelve a copiar la clave + desde la sección Integraciones, sin espacios al inicio ni al final, y reemplaza + la conexión. +- **Al activar el Zap falla diciendo que el hook ya existe:** otro Zap de tu + cuenta, quizás armado por otra persona, ya usa ese disparador sobre ese + formulario. Apaga el Zap más antiguo y luego activa este. Si el error + persiste, escríbenos y limpiamos la suscripción que quedó. +- **Test trigger no devuelve datos:** el disparador lee eventos recientes, así + que una cuenta que todavía no tiene ninguno no tiene nada que mostrar. Genera + uno y prueba de nuevo. +- **El Zap nunca se dispara:** confirma que haya un formulario seleccionado en + el disparador, que el Zap esté activo, y revisa el historial del Zap en + Zapier. Un evento que llegó mientras el Zap estaba apagado no se reenvía. +- **Un Zap que apagaste sigue recibiendo datos:** si el disparador es + `Forms: New Form Entry`, abre la lista de Webhooks en + app.mydatascope.com/integrations + y elimina ahí la entrada. +- **No aparecen los campos esperados:** algunos campos dependen de la + configuración de tu cuenta. Escríbenos y lo revisamos contigo. + +Para cualquier duda, escribe a soporte y te acompañamos en la configuración. + +## Historial de versiones + +Versiones de la app de DataScope en Zapier, de la más nueva a la más antigua. Un +Zap sigue corriendo con la versión con la que fue creado, así que un Zap antiguo +puede comportarse distinto a uno nuevo creado con el mismo disparador, y en +cualquiera de los dos casos no hay nada que instalar ni actualizar de tu lado. +Algunas versiones se liberan a cuentas seleccionadas antes de pasar a ser la +predeterminada para los Zaps nuevos, así que la versión detrás de tu Zap no +siempre es la actual. + +Dos números, 2.0.0 y 2.1.0, nunca se publicaron. Por eso las notas de +publicación registradas en 2.0.1 y 2.1.1 describen solo la diferencia respecto a +un draft que ya no existe. Los bullets de abajo describen, en cambio, la +diferencia respecto a la versión publicada anterior. + + + + + +**2.1.3** (liberada a cuentas seleccionadas) + +- Agrega el campo `Location Type` en `Tasks: Assign Task V2` y en + `Tickets: Create Ticket`, con la opción `Places (new module)` junto a la de + Locations antigua. +- Agrega `Find Location / Place by ID` en `Tasks: Assign Task V2`, para que una + tarea pueda apuntar a un lugar existente por su ID interno. + +**2.1.2** (predeterminada para los Zaps nuevos) + +- Agrega la action `Tasks: Assign Task V2` y renombra la anterior como + `Tasks: Assign Task V1 [Legacy]`. La V2 acepta direcciones de email de usuario + que contienen el signo más. + +**2.1.1** + +- Renombra los dos disparadores de tickets. `Findings: New Finding` pasa a + `Tickets: New Ticket (FKA Issue)`, y `Findings: Changed Status` pasa a + `Tickets: Changed Status (FKA Issue)`. +- Agrega la action `Tickets: Create Ticket (FKA Issue)`. +- Corrige un error con la fecha de creación y con la fecha de expiración + relativa. + +**2.0.2** + +- El Location Name deja de ser obligatorio en la action `Assign Task`. +- Cambia algunos tipos de campos de salida. + +**2.0.1** + +- La primera versión publicada de la línea 2.x, y la primera con los tres + disparadores de firma y los dos de tickets, que en ese momento se llamaban + `Findings: New Finding` y `Findings: Changed Status`. +- Consolida lo que los drafts de 1.14 habían agregado por separado: el + disparador de estado, la action `Send Data`, y los campos de obligatoriedad y + de respuesta tardía en `Assign Task`. +- Antepone su área al nombre de cada disparador y de cada action: `Forms:`, + `Tasks:` o `Signatures:`. +- Mejora un valor por defecto. + +**1.14.3** + +- Agrega `Make this task mandatory` y `Allow the task to be answered after the + due date has been reached` a la action `Assign Task`. +- No trae el disparador `Status Changed` ni la action `Send Data` que sí tiene + 1.14.2, así que un Zap en esta versión tiene tres disparadores y tres actions. + +**1.14.2** + +- Agrega la action `Send Data`. +- Renombra el disparador `Change Status` como `Status Changed`, y su campo Form + pasa a ser opcional. + +**1.14.1** + +- Agrega el disparador `Change Status`. + +**1.14.0** + +- La base de la línea 1.14: `New Form Entry`, `New Assigned Task` y `New PDF` + como disparadores, y `Assign Task`, `Change Form Status` y + `Modify Form Answer` como actions. Acá `Assign Task` exige un Location Name. +- Los tres disparadores de firma, los dos de tickets, `Assign Task V2` y + `Create Ticket` existen solo en la línea 2.x. Para usar cualquiera de ellos, + vuelve a crear el Zap para que tome la versión actual. diff --git a/source/zapier/connector_guide_pt.html.md b/source/zapier/connector_guide_pt.html.md new file mode 100644 index 00000000000..ab14316e1ab --- /dev/null +++ b/source/zapier/connector_guide_pt.html.md @@ -0,0 +1,334 @@ +--- +title: Conectar o DataScope com o Zapier +--- + +# Conectar o DataScope com o Zapier + +> Prefere ler isso em espanhol ou inglês? [Versão em espanhol](connector_guide_es.html) | [English version](connector_guide_en.html). + +Este guia explica como conectar o DataScope com o Zapier para automatizar sua +operação em campo: disparar Zaps quando um formulário é preenchido, quando um +documento é gerado, quando uma tarefa é atribuída ou quando um ticket é +registrado, e agir sobre o DataScope a partir dos outros aplicativos que você +já usa. + + + +## Antes de começar + +Você precisa de: + +- Uma conta do Zapier com permissão para criar Zaps no workspace 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, na aba API Key. +- Pelo menos um formulário publicado no DataScope. A maioria dos disparadores e + das actions pede que você escolha um formulário, e a lista é preenchida com + os formulários da sua conta. + +## Passo 1: criar o Zap + +1. Acesse o app do DataScope no Zapier e faça login. +2. Selecione **Create Zap**, ou comece por um dos modelos listados nessa + página. A seção Integrações do DataScope lista os mesmos modelos, agrupados + por caso de uso. +3. Na etapa do disparador, busque **DataScope Forms** e selecione. +4. Escolha o evento ao qual você quer reagir, na lista em + [O que você pode automatizar](#o-que-voce-pode-automatizar). + +## Passo 2: criar a conexão + +Na primeira vez que você usar o DataScope em um Zap, o Zapier vai pedir uma +conexão e mostrar um único campo, **Token Key**. Cole ali sua API Key do +DataScope. + +Cole exatamente como o DataScope mostra, sem espaços no início ou no final. Se +a conexão for aceita mas o disparador depois não retornar nenhum dado, a API +Key é a primeira coisa a revisar. + +A conexão pertence à sua conta do Zapier e você pode reutilizá-la em todos os +Zaps que montar. Cada pessoa que monta Zaps precisa da sua própria conexão, +com a API Key da sua conta. + +## Passo 3: escolher o formulário + +A maioria dos disparadores mostra uma lista **Form** com os formulários da sua +conta. Mesmo quando o campo é opcional, escolha um formulário. + + + +## Passo 4: testar e ativar o Zap + +O botão **Test trigger** do Zapier busca os últimos eventos que correspondem ao +disparador, então ele precisa de pelo menos um para mostrar dados de exemplo. +Se sua conta ainda não tem nenhum, envie uma resposta de formulário, gere um +documento ou atribua uma tarefa, conforme o disparador escolhido, e teste +novamente. + +Quando os dados de exemplo estiverem certos, adicione as etapas seguintes e +publique o Zap. A assinatura do lado do DataScope é criada quando você ativa o +Zap, não enquanto você o edita. + +## O que você pode automatizar + +O app do DataScope oferece os seguintes disparadores. Os nomes são os que você +vê na lista de disparadores do Zapier: + +| Disparador | É acionado quando | Campo Form | +|---|---|---| +| Forms: New Form Entry | Uma resposta de formulário é enviada | Obrigatório | +| Forms: New PDF | Um PDF é gerado por backup por email ou por autonotificação | Opcional, escolha um | +| Forms: Status Changed | Uma resposta de formulário muda de status | Opcional, escolha um | +| Tasks: New Assigned Task | Uma tarefa é atribuída | Obrigatório | +| Signatures: New Completed Signature | Todos os signatários assinaram o documento | Opcional, escolha um | +| Signatures: New Rejected Signature | Um signatário rejeita a solicitação de assinatura | Opcional, escolha um | +| Signatures: Updated Signature | As assinaturas de um documento mudam e ainda há pendentes | Opcional, escolha um | +| Tickets: New Ticket (FKA Issue) | Um ticket é criado | Não se aplica, é no nível da conta | +| Tickets: Changed Status (FKA Issue) | Um ticket muda de status | Não se aplica, é no nível da conta | + +Cada disparador entrega os dados do evento como campos individuais, prontos +para mapear nas etapas seguintes do Zap sem precisar processar o JSON +manualmente. No caso das respostas de formulário, cada pergunta chega como seu +próprio campo, com o nome, o tipo e o valor. + +O app também oferece as seguintes actions, para que um Zap possa agir sobre o +DataScope e não apenas reagir aos seus eventos: + +| Action | O que faz | +|---|---| +| Tasks: Assign Task V2 | Atribui uma tarefa de um formulário a um usuário, opcionalmente agendando-a e vinculando-a a um local ou a um lugar | +| Tasks: Assign Task V1 [Legacy] | A versão anterior da mesma action, mantida para que os Zaps existentes continuem funcionando | +| Forms: Send Data / New Answer [Beta] | Gera uma nova resposta de formulário e seu PDF a partir de um formulário existente usado como modelo | +| Change Form Status | Muda o status de uma resposta de formulário, identificada por nome e código do formulário | +| Modify Form Answer | Cria ou modifica uma resposta pontual dentro de um formulário já enviado | +| Tickets: Create Ticket (FKA Issue) | Cria um ticket, opcionalmente herdando os valores padrão de um Ticket Type | + +### Assign Task: V1 ou V2 + +Use a **V2** para tudo que for novo. Ela faz tudo o que a V1 faz, e além disso: + +- Aceita o sinal de mais no email do usuário, então + `usuario+obra@exemplo.com` resolve para o usuário correto. +- Pode apontar para o módulo de locais novo, e não apenas para o antigo. +- Pode encontrar um local ou um lugar existente pelo seu ID interno, que é o + que você precisa quando vários lugares têm o mesmo nome. + +A **V1** continua disponível para que os Zaps criados sobre ela sigam +rodando. Não há migração automática: se você quiser passar um Zap da V1 para a +V2, substitua a etapa da action e mapeie os campos novamente. + + + +### Locations ou Places + +**Tasks: Assign Task V2** e **Tickets: Create Ticket** têm um campo +**Location Type** com duas opções, e as duas ações não se comportam da mesma +forma. Na **Assign Task V2**: + + + + +| Location Type | Comportamento quando nada corresponde | +|---|---| +| Locations (old module, legacy) | O local é criado no DataScope a partir do Location Name e dos demais campos de local que você enviou. Sem Location Name não há com o que criá-lo, então a tarefa é atribuída sem local | +| Places (new module) | Nada é criado. A tarefa não é atribuída e o Zap falha com `nestable location not found` | + +**Tickets: Create Ticket** nunca cria um local, com nenhuma das duas opções. Se o +local que você envia não corresponder a um registro existente, o ticket é criado +sem local associado e o Zap informa sucesso. Ele busca somente por Location ID e +depois por Location Name. + +Locations é a opção padrão, então os Zaps existentes continuam funcionando sem +mudanças. Se você escolher Places, crie o lugar no DataScope antes de o Zap +rodar. + +Na **Assign Task V2** o local é buscado nesta ordem: Location / Place ID, +depois Location Code, depois Location Name e depois Location Address. O +primeiro que corresponder é o escolhido. + +Os demais campos de local, Location Phone, Location Email, Company Name, +Company Legal ID, Latitude e Longitude, se aplicam somente ao módulo de locais +antigo, onde são salvos no local encontrado ou criado. Eles são ignorados com +Places, porque os lugares nunca são modificados por esta action. + +### Send Data / New Answer está em Beta + +**Forms: Send Data / New Answer** cria uma resposta de formulário a partir de um +formulário existente, o que a torna útil para trazer ao DataScope dados +capturados em outro lugar. Três pontos para levar em conta: + +- **O PDF é gerado somente se você preencher o campo Emails.** Esse campo é o que + envia o documento, e gerá-lo faz parte de enviá-lo. Se deixar vazio, você fica + com a resposta de formulário sem PDF. +- **Ela não dispara o resto da cadeia de automação.** A sincronização com o + Google Sheets, a assinatura automática e os webhooks de respostas de formulário + não rodam para uma resposta criada assim, então um Zap que reage a + `Forms: New Form Entry` não vai vê-la. `Forms: New PDF` é a exceção: se você + preencher o campo Emails, esse Zap é disparado. +- **Nem todos os tipos de pergunta são totalmente suportados**, então alguns + campos podem não ficar como você espera. Teste com o formulário que você vai + usar de verdade. + +## Considerações importantes + +- **Um Zap ativo por formulário e por disparador, com uma exceção.** + `Forms: New PDF`, `Forms: Status Changed`, `Tasks: New Assigned Task` e os três + disparadores de assinatura admitem uma única assinatura ativa por formulário. + Ativar um segundo Zap com o mesmo disparador sobre o mesmo formulário é + rejeitado com um erro que nomeia o tipo de disparador e pede que você remova o + anterior. Disparadores diferentes sobre o mesmo formulário não são problema, e + o mesmo disparador sobre formulários diferentes também não. + **`Forms: New Form Entry` não passa por essa validação**: um segundo Zap sobre + o mesmo formulário é aceito, e depois os dois recebem todos os envios. + Adicione etapas a um único Zap em vez disso. +- **Se você precisa que várias coisas aconteçam com um mesmo evento, adicione + etapas a um único Zap** em vez de criar um segundo Zap com o mesmo + disparador e formulário. +- **Os disparadores de tickets operam no nível da conta.** `Tickets: New + Ticket` e `Tickets: Changed Status` cobrem todos os tickets da conta e + admitem um Zap ativo por conta cada um. Eles não têm campo Form. +- **Os campos disponíveis variam conforme sua configuração.** Alguns dados, + como os de identidade dos signatários ou os campos estendidos de tarefas, + aparecem somente se essas funcionalidades estiverem habilitadas na sua + conta. +- **Os dados de exemplo de um disparador não são a lista completa de campos.** + O Zapier monta a lista a partir dos eventos recentes, então uma pergunta que + ninguém respondeu ainda, ou um campo opcional que chegou vazio, pode não + aparecer até que apareça. Envie uma resposta representativa antes de mapear + as etapas seguintes. +- **O disparador `Forms: New Form Entry` é visível do lado do DataScope.** Ele + se registra na lista de Webhooks de + app.mydatascope.com/integrations. + Os demais disparadores não aparecem nessa lista. + +## Se algo não funcionar + +- **A conexão é aceita mas nada funciona:** o teste de conexão não rejeita de + forma confiável uma API Key incorreta, então uma chave errada aparece mais + tarde como um disparador que não retorna nenhum dado. Copie a chave novamente + na seção Integrações, sem espaços no início ou no final, e substitua a conexão. +- **Ao ativar o Zap ele falha dizendo que o hook já existe:** outro Zap da sua + conta, talvez montado por outra pessoa, já usa esse disparador sobre esse + formulário. Desative o Zap mais antigo e depois ative este. Se o erro + persistir, escreva para o suporte e nós limpamos a assinatura que ficou. +- **O Test trigger não retorna dados:** o disparador lê eventos recentes, então + uma conta que ainda não tem nenhum não tem nada para mostrar. Gere um e teste + novamente. +- **O Zap nunca é disparado:** confirme que há um formulário selecionado no + disparador, que o Zap está ativo, e revise o histórico do Zap no Zapier. Um + evento que chegou enquanto o Zap estava desativado não é reenviado. +- **Um Zap que você desativou continua recebendo dados:** se o disparador for + `Forms: New Form Entry`, abra a lista de Webhooks em + app.mydatascope.com/integrations + e exclua a entrada ali. +- **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. + +## Histórico de versões + +Versões do app do DataScope no Zapier, da mais nova para a mais antiga. Um Zap +continua rodando com a versão com a qual foi criado, então um Zap antigo pode se +comportar de forma diferente de um novo criado com o mesmo disparador, e em +qualquer um dos dois casos não há nada para instalar ou atualizar do seu lado. +Algumas versões são liberadas para contas selecionadas antes de se tornarem a +padrão para os Zaps novos, então a versão por trás do seu Zap não é sempre a +atual. + +Dois números, 2.0.0 e 2.1.0, nunca foram publicados. Por isso as notas de +publicação registradas na 2.0.1 e na 2.1.1 descrevem apenas a diferença em +relação a um draft que já não existe. Os bullets abaixo descrevem, em vez disso, +a diferença em relação à versão publicada anterior. + + + + + +**2.1.3** (liberada para contas selecionadas) + +- Adiciona o campo `Location Type` na `Tasks: Assign Task V2` e na + `Tickets: Create Ticket`, com a opção `Places (new module)` ao lado da de + Locations antiga. +- Adiciona `Find Location / Place by ID` na `Tasks: Assign Task V2`, para que + uma tarefa possa apontar para um lugar existente pelo seu ID interno. + +**2.1.2** (padrão para os Zaps novos) + +- Adiciona a action `Tasks: Assign Task V2` e renomeia a anterior como + `Tasks: Assign Task V1 [Legacy]`. A V2 aceita endereços de email de usuário + que contêm o sinal de mais. + +**2.1.1** + +- Renomeia os dois disparadores de tickets. `Findings: New Finding` passa a + `Tickets: New Ticket (FKA Issue)`, e `Findings: Changed Status` passa a + `Tickets: Changed Status (FKA Issue)`. +- Adiciona a action `Tickets: Create Ticket (FKA Issue)`. +- Corrige um erro na data de criação e na data de expiração relativa. + +**2.0.2** + +- O Location Name deixa de ser obrigatório na action `Assign Task`. +- Muda alguns tipos de campos de saída. + +**2.0.1** + +- A primeira versão publicada da linha 2.x, e a primeira com os três + disparadores de assinatura e os dois de tickets, que naquele momento se + chamavam `Findings: New Finding` e `Findings: Changed Status`. +- Consolida o que os drafts da 1.14 tinham adicionado separadamente: o + disparador de status, a action `Send Data`, e os campos de obrigatoriedade e + de resposta tardia na `Assign Task`. +- Passa a prefixar o nome de cada disparador e de cada action com a sua área: + `Forms:`, `Tasks:` ou `Signatures:`. +- Melhora um valor padrão. + +**1.14.3** + +- Adiciona `Make this task mandatory` e `Allow the task to be answered after the + due date has been reached` à action `Assign Task`. +- Não traz o disparador `Status Changed` nem a action `Send Data` que a 1.14.2 + tem, então um Zap nesta versão tem três disparadores e três actions. + +**1.14.2** + +- Adiciona a action `Send Data`. +- Renomeia o disparador `Change Status` como `Status Changed`, e o campo Form + dele passa a ser opcional. + +**1.14.1** + +- Adiciona o disparador `Change Status`. + +**1.14.0** + +- A base da linha 1.14: `New Form Entry`, `New Assigned Task` e `New PDF` como + disparadores, e `Assign Task`, `Change Form Status` e `Modify Form Answer` + como actions. Aqui a `Assign Task` exige um Location Name. +- Os três disparadores de assinatura, os dois de tickets, `Assign Task V2` e + `Create Ticket` existem somente na linha 2.x. Para usar qualquer um deles, + crie o Zap novamente para que ele use a versão atual.