-
Notifications
You must be signed in to change notification settings - Fork 0
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Glossary, ACs, desynchronize and sync every tables #1
base: issue-416
Are you sure you want to change the base?
Changes from all commits
6195dea
8058761
00b7a83
bcc569b
8528e86
f2f6f99
ee374f8
8ef8986
df80cec
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -21,6 +21,49 @@ Stating @CamilleLegeron | |
> | ||
> Camille | ||
|
||
## Glossary | ||
|
||
<details> | ||
<summary>Acronyms</summary> | ||
<dl> | ||
<dt>MH</dt><dd>Must Have</dd> | ||
<dt>SH</dt><dd>Should Have<dd> | ||
<dt>NTH</dt><dd>Nice To Have</dd> | ||
</dl> | ||
</details> | ||
|
||
<details> | ||
<summary>Vocabulary</summary> | ||
<dl> | ||
<dt>Synchronized table / Target table</dt><dd>The table which fetches its data from an external table, and gets its data and columns synchronized with this external table</dd> | ||
<dt>External table / Source table</dt><dd>Table of another document of the synchronized table (source table should be preferred in the UI)</dd> | ||
<dt>Regular table</dt><dd>A table which is not synchronized</dd> | ||
</dl> | ||
</details> | ||
|
||
## Acceptance Criteria | ||
|
||
- AC1 - MH: A user can create a fresh table synchronized with an external document | ||
- AC2 - MH: The synchronization is made when the user requests it. | ||
- AC2.1 - MH: The columns of the synchronized table are updated/created/deleted so it reflects what exist in the external table | ||
- AC2.2 - MH: Idem for the records | ||
- AC2.3 - MH: If the external table is not accessible anymore or is deleted, a relevant error is displayed to the user, but the synchronized table continue to exist unless the user decide to delete it | ||
- AC2.4 - NTH: If the external table is modified, the user gets notified that changes can be fetched | ||
- AC2.5 - NTH: The user sees what data have been changed through a diff | ||
- AC2.6 - NTH: The user also sees what columns are removed or added | ||
- AC3 - MH: A user can convert an existing table to a synchronized one | ||
- AC3.1 - MH: If another regular table references a column of the table to synchronize, the reference is not broken if the external table has a column of the same id | ||
- AC3.2 - SH: If the external table references a column of another external table, the two tables are synchronized and the reference continues to work in the synchronized document | ||
- AC3.3 - SH: If the external table references a column of another regular table, the reference column is converted to a regular one (type: Ref:... ⇒ Any) in the synchronized table and the display value is stored directly | ||
- AC3.4 - NTH: The user sees what data have been changed through a diff | ||
- AC3.5 - NTH: The user also sees what columns are removed or added | ||
- AC4 - SH: The user should be able to unlink a synchronized table which would become a simple table; | ||
- AC5 - NTH: A "synchronize every tables" button is offered to the user in the "raw data tables" view; | ||
- AC6 - SH: Edits to synchronized tables should be forbidden; | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. To be seen after the POC. If the POC says that references can be synchronized, we can keep this AC. If not, things get more complicated, because the user would want to manually copy/paste the result of a formula from the external table to the synchronized one. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The references cannot yet be retrieved. The main problem here is that when using add-or-update on records, the IDs of the added or updated records are not returned (mapped to each submitted elements) |
||
- AC7 - MH: Attachment columns are not retrieved from source tables; | ||
- AC8 - MH: The hidden columns of the external table are synchronized too; | ||
- AC9 - MH: The source table may not exist anymore, in such a case the synchronization fails with an explicit message for the user; | ||
|
||
## Documents | ||
|
||
- [design.md](./design.md) | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,40 @@ | ||
# Technical proposal | ||
|
||
## API | ||
|
||
3 new APIs are introduced: | ||
- `POST /api/docs/:docId/tables/:tableId/source` to allow attaching a source to a table | ||
- passed data: | ||
- in the query, `:docId` and `:tableId` refer to the target (synchronized) document / table; | ||
- in the body, 2 properties are passed: `docId` and `tableId`, which are the reference to the source table ; | ||
- pre-conditions: | ||
- the table should not have any source yet (a target table may have only 1 source table, although a source table may have multiple target tables) ; | ||
- the passed data reference existing tables in the same site (or even instance?); | ||
- the source table id is not taken in the target document by another table | ||
- What it does: | ||
- it stores the `docId` and the `tableRef` within the document (`_grist_Source_table`); | ||
- it copies the id of the source table to the target one; | ||
- `DELETE /api/docs/:docId/tables/:tableId/source` to allow detaching a source to a table | ||
- passed data: | ||
- in the query, `:docId` and `:tableId` refer to the target (synchronized) document / table; | ||
- pre-conditions: | ||
- the synchronized table should have a source table; | ||
- What it does: | ||
- it removes the `docId` and the `tableRef` from the document; | ||
- `POST /api/docs/:docId/tables/:tableId/sync` to trigger the synchronization | ||
- passed data: none | ||
- pre-conditions: | ||
- the synchronized table should have a source table; | ||
- it ensures that the table id of the source table corresponds to the target table (if it does not, it may break formulas, so the API user should change the id of the target table); | ||
- What it does: | ||
- it replaces the synchronized table columns with the source table ones: | ||
- it fetches the columns from the source table; | ||
- it filters out the attachment columns; | ||
- for the reference columns: | ||
- if the referenced column belongs to another table, it should be a synchronized table (otherwise rejects) and the referenced table gets synchronized beforehand; | ||
- displayCol + visibleCol => it maps the column ids of the source document with the ones of the target document | ||
- it also transforms the "rules" fields (FIXME: HOW? more details needed) | ||
- it replaces the synchronized table data: | ||
- it fetches the data from the source table; | ||
- it filters out the data from the formulas; | ||
- for each reference column (whose values are row ids), it maps the column ids of the source document with the ones of the target document; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
NB: record can be here seen as synonym for row