From 6c36b8834bc88470fbc4a6db8f134de3e0b58b1b Mon Sep 17 00:00:00 2001 From: Kathleen Tuite Date: Wed, 25 Sep 2024 15:05:18 -0700 Subject: [PATCH 1/5] Extra entity fields for offline management --- docs/api.yaml | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/docs/api.yaml b/docs/api.yaml index 16864ab99..d1cec99d9 100644 --- a/docs/api.yaml +++ b/docs/api.yaml @@ -45,6 +45,7 @@ info: **Added**: - Extended metadata for Forms includes a new property `publicLinks`, which is the number of Public Links that can submit to the Form. + - Data for Entity versions now includes the properties `branchId`, `trunkVersion`, and `branchBaseVersion` for supporting offline functionality. ## ODK Central v2024.1 @@ -9014,6 +9015,9 @@ paths: userAgent: Enketo/3.0.4 version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null conflictingProperties: null application/json; extended: schema: @@ -9043,6 +9047,9 @@ paths: userAgent: Enketo/3.0.4 version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null conflictingProperties: null creator: createdAt: '2018-04-18T23:19:14.802Z' @@ -9154,6 +9161,9 @@ paths: conflictingProperties: null version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null data: firstName: John age: '88' @@ -9235,6 +9245,9 @@ paths: conflictingProperties: null version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null data: firstName: John age: '88' @@ -9270,6 +9283,9 @@ paths: conflictingProperties: null version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null data: firstName: John age: '88' @@ -9432,6 +9448,9 @@ paths: conflictingProperties: null version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null data: firstName: John age: '88' @@ -9504,6 +9523,9 @@ paths: userAgent: Enketo/3.0.4 version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null conflict: null resolved: false lastGoodVersion: true @@ -9533,6 +9555,9 @@ paths: userAgent: Enketo/3.0.4 version: 1 baseVersion: null + branchId: null + trunkVersion: null + branchBaseVersion: null conflict: null resolved: false lastGoodVersion: true @@ -12261,7 +12286,19 @@ components: example: 2 baseVersion: type: number - description: The version number of the version that was the "base version" of this version. The base version is the version that was shown to the data collector when they made their update. + description: The version number of the version that was the "base version" of this version. + example: 1 + branchId: + type: string + description: The uuid of a branch linking multiple offline entity updates together. + example: b0e927b6-958a-42f6-8344-1deb37ee9672 + trunkVersion: + type: number + description: The version number of the last known base server version of an entity, in the case of an offline branch of updates. + example: 1 + branchBaseVersion: + type: number + description: The base version of the entity according to the submission. In the case of an offline branch of updates, this may not match the version of the base submission on Central. example: 1 EntitySummary: allOf: From b386c9e5936bc57bde2d794e8c10cd389b50b4ab Mon Sep 17 00:00:00 2001 From: Kathleen Tuite Date: Wed, 25 Sep 2024 15:29:04 -0700 Subject: [PATCH 2/5] submission deletes --- docs/api.yaml | 128 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 126 insertions(+), 2 deletions(-) diff --git a/docs/api.yaml b/docs/api.yaml index d1cec99d9..7c7b32ceb 100644 --- a/docs/api.yaml +++ b/docs/api.yaml @@ -44,8 +44,12 @@ info: **Added**: - - Extended metadata for Forms includes a new property `publicLinks`, which is the number of Public Links that can submit to the Form. - - Data for Entity versions now includes the properties `branchId`, `trunkVersion`, and `branchBaseVersion` for supporting offline functionality. + * Submission Delete! + - New DELETE and RESTORE endpoints for submissions! + - Submissions that have been soft-deleted for 30 days will automatically be purged. + * Additional properties on certain responses: + - Extended metadata for Forms includes a new property `publicLinks`, which is the number of Public Links that can submit to the Form. + - Data for Entity versions now includes the properties `branchId`, `trunkVersion`, and `branchBaseVersion` for supporting offline functionality. ## ODK Central v2024.1 @@ -848,6 +852,9 @@ tags: * `submission.update` when a Submission's metadata is updated. * `submission.update.version` when a Submission XML data is updated. * `submission.attachment.update` when a Submission Attachment binary is set or cleared, but _only via the REST API_. Attachments created alongside the submission over the OpenRosa `/submission` API (including submissions from Collect) do not generate audit log entries. + * `submission.delete` when a Submission is soft-deleted. + * `submission.purge` when soft-deleted Submissions are purged. + * `submission.restore` when a Submission is restored. * `dataset.create` when a Dataset is created. * `dataset.update` when a Dataset is updated. * `dataset.update.publish` when a Dataset is published. @@ -6232,6 +6239,123 @@ paths: application/json: schema: $ref: '#/components/schemas/Error403' + delete: + tags: + - Submissions + summary: Deleting a Submission + description: When a Submission is deleted, there is a period of time (30 days) + during which it can be restored. After this time, all of its resources and attachments + are automatically purged. Purging deleted Submissions can also be triggered from the command line. + operationId: Deleting a Submission + parameters: + - name: projectId + in: path + description: The numeric ID of the Project + required: true + schema: + type: number + example: "16" + - name: xmlFormId + in: path + description: The `xmlFormId` of the Form being referenced. + required: true + schema: + type: string + example: simple + - name: instanceId + in: path + description: The `instanceId` of the Submission being referenced. + required: true + schema: + type: string + example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Success' + 403: + description: Forbidden + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + 404: + description: Not Found + content: + application/json: + schema: + required: + - code + type: object + properties: + code: + type: string + message: + type: string + example: + code: "404.1" + message: Could not find the resource you were looking for. + /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}/restore: + post: + tags: + - Submissions + summary: Restoring a deleted Submission + description: Submissions that have been recently soft-deleted and not yet purged can be restored using this endpoint. + operationId: Restoring a deleted Submission + parameters: + - name: projectId + in: path + description: The numeric ID of the Project + required: true + schema: + type: number + example: "16" + - name: xmlFormId + in: path + description: The `xmlFormId` of the Form being referenced. + required: true + schema: + type: string + example: simple + - name: instanceId + in: path + description: The `instanceId` of the Submission being referenced. + required: true + schema: + type: string + example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44 + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Success' + 403: + description: Forbidden + content: + application/json: + schema: + $ref: '#/components/schemas/Error403' + 404: + description: Not Found + content: + application/json: + schema: + required: + - code + type: object + properties: + code: + type: string + message: + type: string + example: + code: "404.1" + message: Could not find the resource you were looking for. /v1/projects/{projectId}/forms/{xmlFormId}/submissions/{instanceId}.xml: get: tags: From 62e8f0595cb66149697343bc3b4a0b323a25d133 Mon Sep 17 00:00:00 2001 From: Kathleen Tuite Date: Wed, 25 Sep 2024 15:47:59 -0700 Subject: [PATCH 3/5] notes about restoring deleted forms by id --- docs/api.yaml | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/api.yaml b/docs/api.yaml index 7c7b32ceb..c9b34964c 100644 --- a/docs/api.yaml +++ b/docs/api.yaml @@ -2979,6 +2979,8 @@ paths: As of version 1.2, Forms that are unpublished (that only carry a draft and have never been published) will appear with full metadata detail. Previously, certain details like `name` were omitted. You can determine that a Form is unpublished by checking the `publishedAt` value: it will be `null` for unpublished forms. This endpoint supports retrieving extended metadata; provide a header `X-Extended-Metadata: true` to additionally retrieve the `submissions` count of the number of Submissions that each Form has, the `reviewStates` object of counts of Submissions with specific review states, the `lastSubmission` most recent submission timestamp, the Actor the Form was `createdBy`, as well as other metadata. + + The query `?deleted=true` can be added to list deleted Forms with their numeric form IDs, which can be used to [restore](/central-api-form-management/#restoring-a-form) a deleted Form. operationId: List all Forms parameters: - name: projectId @@ -2988,6 +2990,12 @@ paths: schema: type: number example: "16" + - name: deleted + in: query + description: If set to `true`, will return only deleted Forms and their IDs + schema: + type: boolean + example: "true" responses: 200: description: OK @@ -3307,13 +3315,18 @@ paths: tags: - Individual Form summary: Deleting a Form - description: When a Form is deleted, it goes into the Trash section, but it + description: -| + When a Form is deleted, it goes into the Trash section, but it can now be restored from the Trash. After 30 days in the Trash, the Form and all of its resources and submissions will be automatically purged. If your goal is to prevent it from showing up on survey clients like ODK Collect, consider setting its `state` to `closing` or `closed` instead (see [Modifying a Form](/central-api-form-management/#modifying-a-form) just above for more details). + + The API usually identifies forms by their `projectId` and `xmlFormId`, but if a Form + is deleted, the same `xmlFormId` can be reused. To [restore](/central-api-form-management/#restoring-a-form) a deleted Form, use its + _numeric ID_, which can be retrieved by [listing Forms with `?deleted=true`](/central-api-form-management/#list-all-forms). operationId: Deleting a Form parameters: - name: xmlFormId @@ -3819,7 +3832,9 @@ paths: description: |- _(introduced: version 1.4)_ - Deleted forms can now be restored (as long as they have been in the Trash less than 30 days and have not been purged). However, a deleted Form with the same `xmlFormId` as an active Form cannot be restored while that other Form is active. This `/restore` URL uses the numeric ID of the Form (now returned by the `/forms` endpoint) rather than the `xmlFormId` to unambigously restore. + Deleted forms can now be restored (as long as they have been in the Trash less than 30 days and have not been purged). However, a deleted Form with the same `xmlFormId` as an active Form cannot be restored while that other Form is active. + + This `/restore` URL uses the numeric ID of the Form (now returned by the `/forms?deleted=true` endpoint) rather than the `xmlFormId` to unambigously restore. Note that the numeric ID of a Form is not returned by default on the [Form list](/central-api-form-management/#list-all-forms) and is only returned when listing deleted Forms. operationId: Restoring a Form parameters: - name: projectId From b6ead12a143884a82afb388c55af7b9bea1c6e87 Mon Sep 17 00:00:00 2001 From: Kathleen Tuite Date: Wed, 25 Sep 2024 15:49:33 -0700 Subject: [PATCH 4/5] link changelog to parts of docs --- docs/api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api.yaml b/docs/api.yaml index c9b34964c..b8ea8c774 100644 --- a/docs/api.yaml +++ b/docs/api.yaml @@ -45,7 +45,7 @@ info: **Added**: * Submission Delete! - - New DELETE and RESTORE endpoints for submissions! + - New [DELETE](/central-api-submission-management/#deleting-a-submission) and [RESTORE](/central-api-submission-management/#restoring-a-deleted-submission) endpoints for submissions! - Submissions that have been soft-deleted for 30 days will automatically be purged. * Additional properties on certain responses: - Extended metadata for Forms includes a new property `publicLinks`, which is the number of Public Links that can submit to the Form. From 7a329fae3d15df4c3e24659c2c89b3885a058952 Mon Sep 17 00:00:00 2001 From: Kathleen Tuite Date: Thu, 26 Sep 2024 09:15:26 -0700 Subject: [PATCH 5/5] Add additional server audit log events to list --- docs/api.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/api.yaml b/docs/api.yaml index b8ea8c774..aa3ef4693 100644 --- a/docs/api.yaml +++ b/docs/api.yaml @@ -855,6 +855,7 @@ tags: * `submission.delete` when a Submission is soft-deleted. * `submission.purge` when soft-deleted Submissions are purged. * `submission.restore` when a Submission is restored. + * `submission.reprocess` when an Entity Submission is held in a processing backlog and then removed. * `dataset.create` when a Dataset is created. * `dataset.update` when a Dataset is updated. * `dataset.update.publish` when a Dataset is published. @@ -865,6 +866,8 @@ tags: * `entity.delete` when an Entity is deleted. * `config.set` when a system configuration is set. * `analytics` when a Usage Report is attempted. + * `blobs.s3.upload` when blobs are moved from the database to external storage. + * `blobs.s3.failed-to-pending` when blobs that failed to upload are reset to the pending state to be retried. * Deprecated: `backup` when a backup operation is attempted for Google Drive backups. - name: Direct Backup x-parent-tag: System Endpoints