Add Zapier section with step-by-step guides - #32
Merged
Merged
Conversation
Data Export listed Zapier only as an outbound link to the Zapier app directory, so everything about how it actually works lived outside the docs. This adds it as a real section, mirroring the Power Automate one, and moves the detail into a step-by-step guide in three languages. Every trigger, action and field description was checked against the published Zap definitions and the Rails endpoints they call, so the tables name the labels users see in Zapier rather than internal keys. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The connection test hits /api/external/ping, which answers 200 with a "Bad Token" body instead of 401, so a wrong key is not guaranteed to fail at that step. Point at the symptom that is actually observable. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The guides had no place to record what a new version of the app brings, so every release would have landed as an undated edit somewhere in the body. This adds a Changelog section to all three languages with an entry template in the source, seeded with the current published version and the one earlier boundary that can still affect a live connection. Versions before 2.1.3 are left unlisted on purpose: there is no reliable record of what each changed, and the gap is more useful visible than filled in. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… history Two things, both in the three language guides. **Claims the backend contradicts.** A review against the Rails code found statements the product does not do: - Locations and Places behaved as one table for two actions. Create Ticket never creates a location and never fails when nothing matches; it attaches none and reports success. Assign Task V2 keeps its own row, now noting that legacy creation needs a Location Name. - One active Zap per form did not hold for Forms: New Form Entry, which is excluded from the uniqueness check, so two Zaps both fire. - Send Data generates the PDF only when Emails is filled, and that same path does fire Forms: New PDF. - Spanish and Portuguese named location modules the product UI does not use. Both modules are Lugares in Spanish and Locais in Portuguese; only the parenthetical separates them. Also adds the silent-assignee caveat on Assign Task, drops the no-code label from the comparison table, and stops asserting that a blank Form creates a subscription, which a pending backend fix will change. **Changelog.** The first pass had only a placeholder entry, and it named 2.1.3 as the published version and carried the Zapier platform version. Both were wrong to publish: 2.1.3 is a draft, 2.1.2 is what new Zaps get, and the platform version is Zapier's own build number, not ours. It now itemizes 2.1.2 down to 2.0.1 from the real changelog notes, keeps the 2.0.0 delivery boundary, and summarizes the 1.14.x line by what it does and does not provide. The entry template now says never to publish the per-version user and task counts. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Drafts are released to customer accounts and are in use, so treating them as unpublished was wrong on both counts: 2.1.3 was described as running no Zaps, and the 1.14.x line was collapsed into a single summary. Every version now has its own entry, and the intro says a version can be released to selected accounts before becoming the default, so a reader on a draft finds their version listed. The 1.14.x entries come from diffing the app definitions: - 1.14.1 adds the Change Status trigger - 1.14.2 adds the Send Data action, renames that trigger to Status Changed and makes its Form field optional - 1.14.3 adds the mandatory and late-response fields to Assign Task but carries neither Status Changed nor Send Data, so it has fewer triggers than 1.14.2 Where a version has no release note recorded, the entry says so and describes what its definition provides instead of inventing a change. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
With the 2.x definitions in hand, the entries no longer rest on release notes alone, and two of those notes turned out to undersell their version badly. 2.0.0 and 2.1.0 were never released, so the notes on 2.0.1 and 2.1.1 describe a delta from a draft that no longer exists. - 2.0.0 is no longer an entry. It is a threshold the backend compares against, not a release, so it moved into a note that also says why the split lands cleanly between the 1.14 and 2.x lines. - 2.0.1 is the first released 2.x version: the three signature triggers, the two ticket triggers (then Findings), and the area prefixes on every name. - 2.1.1 renames Findings to Tickets and adds Create Ticket, neither of which its release note mentions. - 2.1.2 keeps the Assign Task V2 note, now confirmed against the diff. - 2.1.3 adds Location Type and Find Location / Place by ID. Previously the entry could only say it "carries" them, because 2.1.2 was unknown. That last one also gates a claim in the body: Location Type only exists from 2.1.3, which is released to selected accounts, so the Locations or Places section now says a reader on an earlier version will not see the field at all. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resumen
En Data Export, Zapier era solo un link externo al directorio de apps. Todo lo que explica cómo funciona la integración vivía fuera de la documentación. Esta PR lo convierte en sección propia, espejando la de Power Automate, y baja el detalle a una guía paso a paso en inglés, español y portugués, con changelog de versiones de la app.
La diferencia estructural con Power Automate es que acá no hay nada que importar: la app está publicada en el directorio de Zapier y lo único que hace falta es la API Key. La sección lo dice explícitamente para que nadie busque un archivo de definición que no existe.
Cambios
source/index.html.md: sección## Zapiernueva, antes de Power Automate para respetar el orden de la tabla "Choosing a method". La fila de Zapier de esa tabla ahora apunta al ancla interna#zapieren vez de salir del sitio, menciona que los Zaps también escriben hacia DataScope, y deja de usar la etiqueta "no-code" que la guía de marca prohíbe. Entrada nueva en el Changelog del sitio.source/zapier/connector_guide_{en,es,pt}.html.md: guía nueva en tres idiomas, con la misma estructura y el mismo selector de idioma que las de Power Automate, más una sección de historial de versiones al final.Cómo se verificó el contenido
Cada afirmación de comportamiento se contrastó contra el backend en
datascope-railsantes de escribirla, no contra las descripciones de la app:hidden: false. Los pollers internos (tasks_forms,users,form_state,findings_types,test) y los legacy ocultos quedaron fuera porque el usuario no los ve en el editor de Zaps. Se usan los labels literales de Zapier, no las keys internas.(account, hook_type, form, platform)enWebhooks::MakerService#find_or_create_webhook. Triggers distintos sobre el mismo formulario conviven, algo que la descripción de la app no aclara.Forms: New Form Entry:CustomWebhook::FORM_HOOK_TYPESomitenew_answer, así que ese trigger cae al branch legacy que nunca rechaza un duplicado, yManagerService#retrieve_form_hooksdespacha a todas las filasWebhookdel formulario. Dos Zaps sobre el mismo formulario reciben ambos.Tickets: Create Ticketno crea ubicaciones:Finding#set_location!anula la ubicación cuando nada coincide, paraLocationyNestableLocation, y solo busca por ID y por Name. El errornestable location not foundes exclusivo deAssign Task V2.Send Datagenera el PDF solo si se completa Emails:create_pdfllama aAlert.send_pdfúnicamenteif answers_saved > 0 && params[:emails].present?, y ese mismo camino disparaForms: New PDF.config/locales/es.ymlypt.ymllos llamanLugares (antiguo/nuevo módulo)yLocais (antigo/novo módulo). Los dos módulos comparten el sustantivo; solo el paréntesis los separa.Assign Task:MobileUser.where(account_id:).last if mu.blank?. Un email que no coincide asigna la tarea a un usuario arbitrario de la cuenta, con respuesta 200. Documentado comoaside class="warning"en las tres guías.No se publicó nada del JSON del source ni de los endpoints internos: la guía habla de labels, campos y comportamiento observable.
Changelog de versiones
Pasó por tres iteraciones a medida que apareció información. Estado final: 9 versiones publicadas itemizadas (2.1.3 a 2.0.1 y 1.14.3 a 1.14.0), idénticas en los tres idiomas, con la plantilla de entrada como comentario en el source.
Las entradas se construyeron diffeando las definiciones de la app, no solo leyendo las notas de publicación de Zapier, y eso importó: dos notas describen mucho menos de lo que su versión trae. 2.0.0 y 2.1.0 nunca se publicaron, así que las notas de 2.0.1 y 2.1.1 describen el delta contra un draft que ya no existe. Casos concretos:
Findings:aTickets: ... (FKA Issue)y agrega la actionTickets: Create Ticket.Otras dos correcciones de fondo:
general_webhooks_job.rb). Pasó a unaside, que ahora además puede decir algo más claro: como nunca existió una 2.0.0, el corte cae limpio entre la línea 1.14 y la 2.x.En la línea 1.14 el diff destapó algo contraintuitivo que quedó documentado: 1.14.3 no es un superset de 1.14.2. Perdió el disparador
Status Changedy la actionSend Data, y agregó los campos de obligatoriedad y respuesta tardía aAssign Task. Un cliente en 1.14.3 tiene menos disparadores que uno en 1.14.2.Esto también corrigió una afirmación del cuerpo de la guía: el campo
Location Type, con la opción Places, existe solo desde 2.1.3, que está liberada a cuentas seleccionadas. La sección de Locations o Places ahora avisa que quien esté en una versión anterior no va a ver el campo.No se publica la actividad por versión (usuarios y tareas son datos de clientes), y la plantilla lo prohíbe explícitamente.
Dos afirmaciones que se cayeron en la verificación
GET /api/external/ping, que tiene un typo en la rama de token inválido:status => :unauthorizedarma la clave200 => :unauthorizeden vez de la opciónstatus:, así que la respuesta sale 200 con cuerpo "Bad Token". La guía ahora dice lo observable: pegar la clave sin espacios y, si la conexión se acepta pero el trigger no devuelve datos, revisar la API Key primero.datascope-railsque hace que el subscribe falle con 400. El texto quedó neutro respecto a la versión: dejar Form en blanco no entrega nada, y hay que elegir un formulario siempre.Los dos bugs de backend van aparte, fuera del scope de esta PR de documentación.
Test plan
parameterizede Slatemiddleman builden CI: verde en 2.3, 2.4, 2.5 y 2.6. Localmente no corre porque el repo pide Ruby 2.3.3 y no está instalado en la máquinaactionsvsacciones, yassinaturaen portugués usado a la vez para suscripción y para firmaNota
La guía en portugués usa "ticket", alineada con los labels de la app (
Tickets: ... (FKA Issue)) y con las guías EN/ES. La guía PT de Power Automate todavía dice "não conformidade" porque el rename de #28 no la alcanzó, y la EN todavía dice "issue"; no lo toqué acá para no mezclar scope, pero conviene alinearlas en una PR aparte.