Main - #19
Closed
felipegarcia98 wants to merge 32 commits into
Closed
Main#19felipegarcia98 wants to merge 32 commits into
felipegarcia98 wants to merge 32 commits into
Conversation
add endpoint bulk update list documentation
* docs(DS-2757): add GET /api/external/task_assigns/:id endpoint documentation Documents the show endpoint for task assignments, including path parameters, all 30 response fields with types and descriptions, and shell/ruby examples. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * add index documentation * docs(DS-2757): update status values and add note about default date behavior - Replace `sent`/`in_progress` with `assigned`/`accepted` in status fields - Clarify that without date filters the API returns all historical tasks - Note that the platform UI applies a default ±7-day window Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs(DS-2757): rename form_answer_code to response_code and add priority field - Rename `form_answer_code` to `response_code` to match Google Sheet naming - Add `priority` field to response examples and field tables - Updated in both Show and Index endpoint sections Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * rename: datetime_start/datetime_end to response_start/response_end Aligns field names with the API naming convention (noun_qualifier) and matches the backend rename in datascope-rails. Addresses review comment by @Tailmon on lines 1284, 1334, 1456 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(DS-2757): add GET /api/external/task_assigns/:id endpoint documentation Documents the show endpoint for task assignments, including path parameters, all 30 response fields with types and descriptions, and shell/ruby examples. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * add index documentation * docs(DS-2757): update status values and add note about default date behavior - Replace `sent`/`in_progress` with `assigned`/`accepted` in status fields - Clarify that without date filters the API returns all historical tasks - Note that the platform UI applies a default ±7-day window Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs(DS-2757): rename form_answer_code to response_code and add priority field - Rename `form_answer_code` to `response_code` to match Google Sheet naming - Add `priority` field to response examples and field tables - Updated in both Show and Index endpoint sections Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * rename: datetime_start/datetime_end to response_start/response_end Aligns field names with the API naming convention (noun_qualifier) and matches the backend rename in datascope-rails. Addresses review comment by @Tailmon on lines 1284, 1334, 1456 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(DS-2757): rename start_date/end_date params to start/end Align task assigns API docs with updated parameter names for consistency with internal v1 API conventions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(DS-2756): Add GET /api/external/findings endpoint documentation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(DS-2756): Add pagination explanation to findings index endpoint * docs(DS-2756): Add task_form_id filter to findings index endpoint Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(DS-2756): update findings index endpoint documentation - Replace location_name with location + nestable_location fields - Replace form_answer_id with form_answer_code - Fix date format description (account-preference formatted string, not ISO 8601) - Add max values for limit (200) and offset (10000) parameters Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: align index endpoint documentation with implementation - Update JSON example: location_id/name/code, structured assignees/invitees, creator_id/email, assignees_concatenated, invitees_concatenated, form_answer_id - Fix type field description: resolved name, not raw ID - Fix offset max: 10000 → 2000 (matches MAX_OFFSET constant) - Fix return codes: 403 → 401 Unauthorized - Add asset_name, asset_identifier to response fields table Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * finding GET documentation * fix(DS-2756): update findings endpoints to renamed routes - GET findings/list (was /findings) - GET findings/get/:id (was /findings/:id) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
…d manifest Answers V5 shipped to production but had no presence in the public API reference, so customers had no way to discover it or its custom fields without being pointed at an internal Notion page. Adds a `Get All Answers V5 (Beta)` section under `# Answers`, between `Get All Answers with metadata` and `Change Answer`, covering: - What the endpoint solves: in v1 to v4 every question becomes its own top-level key, so each form yields a different column set and a relational destination cannot model it. `answers_data_in_array` nests the questions in an `answers` array and the schema stops changing per form. - Full query parameter table, including the parameters added with this release: `sort_order` (asc/desc for `order_date`) and `since` (keyset pagination cursor). - A dedicated pagination section explaining the `since` cursor flow and why it beats `page`/`offset` on large or recurring exports. - All 32 `custom_fields`, grouped by what they affect (answer structure, form-level data, assigned task, assigned task location) rather than listed flat. - An `Airbyte Cloud connector` section documenting the three streams (`form_answers`, `answers`, `answer_metadata_comments`), their primary keys, and the five installation steps. - Notices for the two footguns worth calling out: `date_modified` and `order_date` must travel together when paging modified answers, and descending sort breaks the cursor under incremental sync. - A note that the token's user needs export permission, so customers configure that before wiring a recurring integration. Also publishes the connector manifest at `source/airbyte/datascope_source_manifest.yaml` so it is downloadable from a public URL. Customers previously had no way to obtain it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…URL at main Two fixes to the Airbyte manifest link: 1. The URL said `master`. This PR lands the file on `main` (the branch that deploys the site), so the `master` URL would have 404'd the moment the docs went live. Now `main`. 2. Removed the second "Browse it on GitHub" link. Customers download the manifest and import it into Airbyte; they do not need a blob view of it. One link instead of two URLs to keep in sync. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…fest The manifest reads as a black box: customers either use it verbatim or edit it blind. Both are avoidable. Adds a `Customizing the manifest` subsection that says plainly it is editable YAML, then splits the surface into what is cosmetic and what is load-bearing. Safe to change, with the reasoning: stream names (they are just table names in the destination), `page_size` (200 is the endpoint ceiling so it only goes down), optional custom_fields (plus the reminder to add them to the stream schema), and the two config fields. Change with care, each paired with the actual failure mode rather than a generic warning: sort direction (the cursor jumps to the newest record and never comes back), `primary_key` (collapses distinct rows, or duplicates on every edit), `cursor_field` (stalls sync state), extractor `field_path` (returns zero records with no error, indistinguishable from an empty account), the structural custom_fields (they feed the keys and cursors), and adding `limit` to request_parameters (collides with the paginator). Two notices: rename streams before the first sync, because Airbyte treats a renamed stream as a new one and leaves the old table behind; and when a modified manifest misbehaves, re-import the published copy and reapply changes incrementally. Replaces the earlier single notice about descending sort, which is now one row of the "change with care" table instead of the only warning. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The Notion page is where the endpoint's change history is tracked release by release, and it covers the same material in Spanish. Readers landing on this section had no way to find it. Placed inside the Beta notice rather than as a separate line, since the two facts belong together: the endpoint is still growing, and that page is where the growth is recorded. The link text flags that the page is in Spanish, so an English reader knows what they are clicking into. The Notion page already links back here, so the pair is bidirectional. Verified the page resolves anonymously (confirmed in a private window) before linking it from a public reference. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
docs(DS-3533): document the Answers V5 (Beta) endpoint + Airbyte Cloud manifest
… about the detected schema
Three fixes from a real Connector Builder run.
## base_url removed as a config field
It was a configurable field defaulting to production. Customers have no
reason to point the connector anywhere else, and leaving the field blank
when configuring the source made the stream test fail with an invalid
URL error that does not name the missing field. Now the production URL
is fixed in `url_base` and the spec is down to three fields: api_token,
start_date, form_id.
## Missing schema fields declared
The endpoint returns five fields on `form_answers` that the schema never
declared: `created`, `created_date`, `updated`, `updated_date` and
`latlong`. The `answers` stream was likewise missing `metadata_comments`,
the nested array that feeds the third stream. All six showed up as
"detected but not declared" in the Builder's schema diff, which is what
tempts a user into accepting the detected schema wholesale. Declaring
them shrinks that diff to pure normalization noise.
## Warning about the detected schema
This one is a real trap, not a cosmetic mismatch. Airbyte drops any field
that is `null` across every sampled record, because it cannot infer a
type from nulls alone. Several fields here are legitimately null on a
quiet account: `assign_*` with no task assigns, `form_state` with no
states, and `subform_index` when no answer sits inside a repeatable
group.
`subform_index` is the dangerous one, because it is part of the
`answer_metadata_comments` primary key. Accepting the detected schema
leaves the key pointing at a field that no longer exists and the stream
test fails with:
Path [] does not have field `subform_index` in the schema and hence
can't be marked as required.
Dropping it from the key is not the fix. It is what distinguishes
comments from different rows of the same repeatable group that selected
the same alternative; without it one comment overwrites the other in the
warehouse. So the declared schema has to stay authoritative, and both
the manifest header and the public reference now say so, along with the
list of Builder differences that genuinely are safe to ignore.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…g it The previous wording said "do not accept it", which reads as though there is a decline button to press. There is not. The notice offers only "Overwrite declared schema" and "Merge properties"; taking neither action is how you decline, and the warning then persists as an indicator on the Schema tab without blocking the test or the sync. Names both buttons explicitly so a reader can match them against what is on screen, and splits the guidance in two: what to do (nothing) as a warning, and why overwriting breaks the connector as a separate notice. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…mary keys
Root cause of the "Path [] does not have field `subform_index`" failure,
confirmed against the Connector Builder's Response tab: the endpoint does
emit the field correctly ("subform_index": null is right there in the raw
JSON). Airbyte is what removes it. It strips null-valued keys from the
record, then infers the schema and validates required fields against the
already-trimmed record. Since Airbyte marks every primary-key field as
required, a null primary-key component makes the stream fail.
My earlier diagnosis in this branch was wrong. I blamed the detected
schema and told users to leave the notice alone, which addressed a
symptom: the same null-stripping breaks the stream whether or not anyone
touches that button. The header comment is corrected accordingly.
The field cannot simply leave the primary key. It is the only thing
separating two answers that belong to different rows of the same
repeatable group, so dropping it would let one comment silently overwrite
another in the warehouse. Failing loudly beats that.
Fix: an `AddFields` transformation on both `answers` and
`answer_metadata_comments` that maps a null `subform_index` to -1, chosen
over a backend change because it needs no API contract change and no
redeploy. -1 reads as "not inside a repeatable group" and cannot collide
with a real row 0: a given question is either always inside a group or
never, so for one `real_question_id` the two values never coexist.
Applied to both streams deliberately, so the documented join on
(form_answer_id, real_question_id, subform_index, answer_row_key) keeps
comparing -1 against -1 rather than -1 against null.
Documented in the public reference too, since it changes what customers
see in their warehouse.
Not verified by me: I cannot run the Connector Builder. If AddFields
behaves differently than expected the stream test will say so, and the
fallback is dropping the field from the `answer_metadata_comments` key
and documenting the collision case.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Feat/ds 3533/answers v5 endpoint
…d pull Someone who wants their answers in a warehouse can land on Webhooks, find something that superficially fits, and build a receiver before discovering it cannot backfill. The two features answer different questions and nothing in the docs said so. Anchored to the tip already at the end of that section, "it will only start sending information for the new forms done after the integration", because that is the exact point where a reader hits the limitation and needs to know the alternative exists. Frames it as push versus pull rather than old versus new, since both are current and using both together is normal: a webhook for the immediate reaction, the connector for the warehouse copy. The three differences are concrete rather than abstract: - History: webhooks start at configuration time; the API takes a start_date and backfills. - Edits: a webhook fires on new submissions; date_modified=true also returns answers edited after their first sync. - Schema: the webhook payload keys each answer by [question_name][question_id], the same dynamic-key shape that makes a relational destination unmodelable and that answers_data_in_array exists to fix. Worth naming explicitly because the reader can see it in the payload sample right above. Links to both the endpoint and the Airbyte connector section. Verified both anchors resolve against the headings actually present in the file. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The comparison table listed "Edits" as something webhooks cannot do. That
is wrong. `Webhook` has a `send_modify` column, surfaced in the UI as
"Send modifications", and `Webhooks::ManagerService` selects on it:
webhooks = webhooks.where(send_modify: true) if
%w[form_edited_answer form_gsheet_answers].include?(mode)
So a `form_edited_answer` dispatch does reach webhooks that have the
option enabled. I asserted the opposite without checking, and a customer
reading it could have concluded they needed the API for something the
feature they already had would do.
Turned the error into useful content: the section now mentions the option
by its UI label, since a reader who wants edit notifications may not know
the checkbox exists.
That leaves two honest differentiators instead of three. The remaining
edit-related advantage is not "webhooks miss edits", it is replay: a push
cannot resend what the endpoint missed while it was down, and cannot
cover anything from before the webhook existed. Folded into the history
row, which is where it belongs, rather than kept as a separate claim.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… doc sample I described the webhook payload as keying each answer by `[question_name][question_id]` and cited the JSON sample above it as evidence. I had taken that from the sample rather than from the code, and the sample does not match either code path. `FormAnswer#webhook_json` builds the key two different ways: - Older forms: `question_name`, plus `[form_answer_index]` when that index is above zero, plus `(table_row)` for repeated rows. - Newer forms, via `answer_key_generator(..., zapier: true)`: `question_name_question_id`, or `question_name_real_question_name_question_id` for the metadata question types, plus `_table_row`. Neither uses the bracketed pair I wrote. The separator is an underscore, and which format you get depends on the form. The underlying point survives and is in fact stronger than I stated. The keys derive from the question's *name*, which is mutable, so a rename reshapes the payload; two different formats coexist depending on the form; and repeatable rows multiply keys. The row now says that, without leaking the internal form-id threshold that selects between the formats. Also dropped the "visible in the sample above" pointer, since that sample is what misled me. Separate, pre-existing: that JSON sample in the Webhooks section is inaccurate about the key format regardless of this PR. Left alone here because correcting a payload spec deserves its own verification pass rather than being folded into a cross-reference commit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ebhook internals Two rounds of corrections in this section both had the same root cause: I was making claims about how the webhook payload is built, and getting the details wrong. The fix is not a third attempt at describing it, it is to stop describing it. The table now says what the API adds and how, which is a claim about the feature this PR documents rather than about one it does not. Three rows, flexibility and schema stability being the two the reader actually needs to make a choice: - Access to everything, not only what comes next. Kept because it rests on the section's own existing tip plus a property inherent to push rather than on any implementation detail. - A schema you can model. Now describes what `answers_data_in_array` returns instead of characterizing what the webhook returns. - Control over the payload. New. `custom_fields` and `version` are the flexibility argument and were missing from the comparison entirely. The mention of "Send modifications" stays, since it is verified against `Webhooks::ManagerService` and is useful to a reader who wants edit notifications and does not know the option exists. Net effect: nothing in this section now asserts anything about webhook payload structure. The inaccurate JSON sample above it is still inaccurate, but that is pre-existing and belongs to its own pass. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Feat/ds 3533/answers v5 endpoint
…split `main` and `master` diverged and each held real content the other lacked. `main` is the canonical side: the site is built from it (both branches' deploy.yml trigger on `main`), it is substantially larger (2099 lines against 1053), and it carries the CI fix and the Answers V5 work. This brings over what only `master` had, and documents why the split happened so it does not silently repeat. ## Three Ticket endpoints `master` documented three endpoints `main` never had, and `main` documents two `master` lacks. They do not overlap: five distinct endpoints, all five verified present in `config/routes.rb` before porting. GET /api/external/last_findings (was master-only) GET /api/external/findings/types (was master-only) POST /api/external/findings/create (was master-only) GET /api/external/findings/list (already here) GET /api/external/findings/get/:id (already here) Appended in reading order: list, fetch one, recent shortcut, reference data, create. ## Developer portal links Three links still pointed at `www.mydatascope.com/webhooks` and `mydatascope.com/webhooks/new`. `master` moved these to `app.mydatascope.com/integrations` last November and `main` never got the change, so the live site has been sending readers to the old URL ever since. ## Changelog block Ported from `master`, which introduced it in the Introduction. Entries for this reconciliation, the V5 work and the April additions. ## README The README was still the untouched upstream Slate one, with nothing about this repository. Added a header block covering what the repo is, where it publishes, and the branch trap: `master` is GitHub's default so PRs target it automatically, while `main` is what actually deploys. That mismatch is the mechanism behind the divergence, and since it cannot be fixed from the repository itself, the README is where a contributor can be warned before opening a PR against the wrong base. ## Deliberately not ported from master - Its workflows. They pin `actions/cache@v2`, which GitHub now auto-fails; `main` already moved to v3. - Its duplicated `## Create a Location` heading. `main` correctly renamed the second occurrence to `## Update a Location`, which is what that endpoint does. - Its Return Codes, `creation_date` and `assignees` content. `main` has strictly more in all three. ## Pre-existing issues left alone The `Remember — user your own header Authorization` aside carries a typo ("user" for "use") in most of its 14 occurrences. Ported verbatim rather than fixing one instance and making the file inconsistent. Worth its own sweep. The JSON sample in the Webhooks section misdescribes the payload key format, checked against `FormAnswer#webhook_json`. Correcting a payload spec deserves its own verification pass. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Every endpoint section closes with a `<aside class="success">` reminding the reader to send their own Authorization header. The line had drifted into three variants: 13x Remember — user your own header Authorization 2x Remember — use your own header Authorization 2x Remember — use your own Authorization header Two separate problems. The 13 carry a typo, "user" where it means "use". The remaining four are correct but disagree on word order, and "your own header Authorization" is calqued from Spanish rather than idiomatic English. All 17 now read `Remember — use your own Authorization header`. Verified before and after: every occurrence sits inside a `aside class="success"` block, so no prose was touched; the diff contains 30 changed lines and none of them is anything other than these asides; and the count of canonical lines afterwards (17) matches the total of all variants beforehand, so nothing was missed or double-replaced. The em dash is left as is. It is the file's existing convention in these asides and throughout the prose, and swapping it would enlarge the diff without helping a reader. Folded into this branch rather than opened as its own PR, which is what the description of this one originally suggested: both would edit the same lines of the same file, and two open PRs over them would only conflict with each other. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
docs: port the master-only content into main and document the branch split
The changelog block rendered as one run-on paragraph on the live site: "Last Update Date: 29-Jul-2026 Last Updates: - Documented the three Ticket endpoints..." all on a single line. Cause: no blank line between `Last Updates:` and the list beneath it, so Redcarpet never started a list and folded every line into the same paragraph. This is inherited, not new. `master` had the same shape, so porting it faithfully in the previous commit reproduced the bug. Two changes: **Its own section.** It was buried inside Introduction, which is about what the API is, not what moved last week. `# Changelog` now sits at the end of the file, right before the Errors include, so the tail of the doc is reference material: endpoints, then changelog, then errors. A new reader still gets Introduction and Authentication first; a returning one clicks straight to it from the sidebar. Introduction keeps a one-line pointer. **Dates as bold text, not headings.** Slate builds the sidebar from h1 and h2, so a heading per date would add a nav entry every release and turn the sidebar into a date list. Bold keeps the nav at one entry regardless of how long the changelog grows. Also grouped the entries by date instead of repeating the date on every bullet, which is what made the original hard to scan, and dropped the redundant "Last Update Date" line since the topmost group already carries it. One judgment call worth naming: `master`'s block credited the portal-link update to Nov-2025, because that is when it was merged there. It never reached `main`, so the published site kept the old links until this branch. The entry sits under 29-Jul-2026, which is when it becomes true for anyone actually reading the site. Verified: every list has a blank line before it, and the three internal anchors still resolve. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The single 29-Jul-2026 group bundled work that landed on three different days, and dated all of it to the earliest. Checked against the merge timestamps rather than memory: #14 2026-07-29 Answers V5, manifest #15 2026-07-29 V5 fixes #16 2026-07-30 V5 fixes #17 2026-08-04 Ticket endpoints, portal links So Answers V5 finished landing on the 30th, not the 29th, and the Ticket endpoints and portal links are from today. Now two groups instead of one, each carrying only what shipped under it. Also added the changelog-section move itself to the 04-Aug group, since it is a visible change to the page and the changelog should record it. The dates matter here beyond tidiness: this file is the only place a customer can see when the endpoint they are reading about became available, and it is served publicly. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
docs: give the changelog its own section and fix its broken rendering
Author
|
Cambia los procesos de workflow. Aborto misión |
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
5 participants
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.
No description provided.