From 8332592e81f776ab1d25328d64ab9f339299a152 Mon Sep 17 00:00:00 2001 From: David Jimenez Barrantes Date: Wed, 21 Feb 2024 16:06:40 -0600 Subject: [PATCH] [APIPUB-25] - [APIPUB-24] - Documentation in relation to key changes and deletes. (#36) * Documentation in relation to keychanges and deletes. * Formatting * Fixes --- README.md | 2 ++ docs/API-Publisher-Configuration.md | 7 +++++++ 2 files changed, 9 insertions(+) diff --git a/README.md b/README.md index af24bf1..aa75d2e 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,8 @@ Run the Ed-Fi API Publisher from the folder containing all the binaries by execu For more documentation on API Publisher's parameters, please see the [API Publisher Configuration](docs/API-Publisher-Configuration.md) markdown file for other runtime options. +For more information in relation to key changes and deletes, please see [Considerations in relation to key changes and deletes](docs/API-Publisher-Configuration.md#considerations-in-relation-to-key-changes-and-deletes) + ## Known Limitations for Ed-Fi ODS / API 5.1 through 5.3 Currently, Ed-Fi ODS / API 5.1 through 5.3 has the following known issues related to Change Queries and the Ed-Fi API Publisher. These have been resolved in [Ed-Fi ODS / API 5.3-cqe patch](https://techdocs.ed-fi.org/display/EFTD/Change+Query+Enhancements) and [Ed-Fi ODS / API 6.1](https://techdocs.ed-fi.org/pages/viewpage.action?pageId=138642238). diff --git a/docs/API-Publisher-Configuration.md b/docs/API-Publisher-Configuration.md index 9d87694..f82b5ae 100644 --- a/docs/API-Publisher-Configuration.md +++ b/docs/API-Publisher-Configuration.md @@ -58,6 +58,13 @@ To select or supply source and target connection information, the following conf | Connections:Target:SchoolYear
`--targetSchoolYear` | (_Optional_) The SchoolYear to use with the target connection (corresponding to a year-specific ODS API deployment). | | Connections:Target:TreatForbiddenPostAsWarning
`--treatForbiddenPostAsWarning` | (_Optional_) A boolean value (true/false) indicating whether `403 Forbidden` responses from `POST` requests against the connection (as a target) should be treated as a warning, rather than a failure.

NOTE: This option can be used in scenarios where the target API may not grant the Ed-Fi API Publisher full CRUD permissions to all the dependencies of the specified resources to be written. In such a scenario, the dependent data must already exist in the target ODS or the resulting `409 Conflict` responses will cause publishing failure. | +## Considerations in relation to key changes and deletes + +Ed-Fi API Publisher will only process key changes and deletions if specific Change Window is defined. To do so use the +`--lastChangeVersionProcessed` value and set the `--useChangeVersionPaging` flag to true. +Another option, if you want to keep the `--useChangeVersionPaging` false is defining a name for the source and target, using the +`--sourceName` and `--targetName` values. More information about all these values [below](API-Publisher-Configuration.md#api-connections). + ## Authorization Failure Handling Defines metadata (as an array of JSON objects) about which resources could experience `403 Forbidden` responses caused by data dependencies needed for successful authorization, and which other resources should be processed before retrying the original request. For example, while an API client may be able to create a Student, they won't be able to _update_ the Student until that Student is enrolled in a School through the StudentSchoolAssociation. By defining the authorization-related dependency of the _update_ operation on the StudentSchoolAssociation, the Ed-Fi API Publisher can know to retry the failed POST request after the association has been established.