Export and Import of Apps

$$$ Screenshot Application Property with import and export functionality

1. functional features / frontend

1.1 App export

A TableView in the application properties for all performed app exports.

$$$ Screenshot of export card

User creates a new App Export Card:

Text field: Title of the app export (e.g. V2021-08)

Multiline text field: Comment

Calculated multiline text field: Status of App-Export (e.g. preparing, ongoing, finished, erroneous)

Calculated relation field: App export details in application log

Static relation field: Export design cards

o export no design cards

o export all design cards

Static relation field: Export data cards

o do not export any data cards

o export all data cards

o export only certain data-cards ⇒ selection/sorting of the corresponding data-protos in multiple relation field: “school”, “trainer”, “course”, “course type”, “processing status”, “age category”, …

Blank canvas widget: More details on the export process: protogrid.wiki.

User clicks on export button

⇒ Checks if all validations are successful and if no export was already done (status field)

⇒ If no (validation is not successful): Shows a meaningful notification in the upper right corner

⇒ If yes: Starts the export process in a background thread, set the status field with timestamp (server-side), enter the newly created log card in the corresponding relation field (server-side) and return HTTP status 200.

⇒ If HTTP status 200 returned: The card reloads all 5s until the export is finished.

⇒ If otherwise something back: shows meaningful notification in the upper right corner

⇒ Execute and complete the export process

⇒ Status field is completed with success/error message and the current timestamp (server-side)

⇒ Export file will be added to the attachment of the card (server-side)

1.2 App import

A new TableView in the Application-Properties for all performed App-Imports

$$$ Screenshot of export card

User creates a new App-Import-Card:

⇒ User enters an import name and saves the card.

⇒ User uploads the .pgrid file

⇒ If HTTP status 200 back: Reload card

⇒ If anything else back: shows meaningful notification in top right corner

Calculated text field: Title of the .pgrid file

Calculated multiline text field: Comment of the .pgrid file

Calculated text field: Version

Calculated date-time field: date and time of the app export.

Calculated multiline text field: status

Calculated relation field: app import details in application log.

FYI: the target app needs the languages in the same order as the source app.


1. fr

2. en

3. es

⇒ if that's not the case the import will fail with a message sugesting to change the languages in the target app.

Static relation field: import of design cards

o do not import any design cards

o import all design cards ⇐ only selectable if there are any design cards in the .pgrid file at all

Static relation field: Import data cards

o import no data cards

o import all data cards ⇐ only selectable if there are any data cards in the .pgrid file at all

o import only certain data cards ⇒ HTML checkboxes for all protos exported ⇐ only selectable if any data cards exist in the .pgrid file at all

Blank canvas widget: More details about the import process: wiki (opens new browser window).

User clicks on button “Update app now according to selection”.

⇒ Check if languages match, version matches and no import has already been done (status field)

⇒ If no: Show meaningful notification in the upper right corner

⇒ If yes: Start the import process in a background thread, set the status field with timestamp (server-side), enter the newly created log card in the corresponding relation field (server-side) and return 200.

⇒ From this point on: CSL hides save buttons

⇒ If 200 back: reload card and repeat this every 5s

⇒ If otherwise something back: Show meaningful notification in the upper right corner

⇒ Performs and completes the import process

⇒ Status field is completed with success/error message and current timestamp (server-side)

2. Non-functional features / backend

2.1 Log

The log card is stored in the application log of the respective app.

A log card is created for each export/import.

In this log one line is created per exported/imported Design-Card This means that a log line is only created for data cards in the event of an error, otherwise the total number of imported/exported data cards is shown in the corresponding “proto log line”.

2.2 Security + Rights

Only the full-access admin of the app and the environment administrator have rights for export/import.

Any download/upload endpoints are also restricted to the full-access admin of the app or the environment administrator.

Before starting an import, an additional backup (besides the nightly backup) of the existing app should be triggered.

Note: A restore of a backup will still be resolved via a ticket to the support team and will be subject to a fee.

2.3 Format

.pgrid file in the format of a zip (filename App-URL with attached timestamp) Contains a .card file in JSON format for each exported card (filename Card-ID)

Note: Contains also the application properties as .card file

Encoding: UTF-8

Additionally a descriptor file (meta_data.json):

- What were the selected export options?

- Title + comment, which the user specified during the export.

- When was the export done by whom in which environment with which Protogrid version?

- Date and time of the app export

3. Remarks / special cases

3.1 Design Cards

Definition: The following types of cards are considered “design cards” here: Menu Definitions, Overview Cards, Stats Cards, Utility Cards, Proto Definitions, Field Definitions, Code Definitions (currently: Triggers, SSL, CSL, Agents, Import Connectors, Connector Field Mappings), ML Cards referenced by the above, Referenced Roles referenced by the above. Design cards must be imported in the exact reverse order as listed in the definition above. This way, an inconsistent state of the app during the import process can be avoided as much as possible. For this purpose, the cards are already divided into subfolders in the zip file during export according to the above types.

Note: Certain data cards can also have a similar function in an application as “design cards” (e.g. in a help proto with the pure purpose of offering selection values as with categories/status values). By definition, we explicitly do not count these as design cards, since the boundary is fluid and must be determined by the app developer. This is also the reason why an export/import of selected data cards must already be available in the basic functionality of the templating.

The user who performs the export/import, or the app developer, must also independently ensure that the selected data cards do not contain any relations to data cards that do not exist or will not exist in the target app.

It is also his responsibility to enter the data protos to be exported in the correct order, so that related cards can be imported (and denormalized) before relating cards.

Design cards are always overwritten in the target app.

3.2 Application properties

Are normally exported with the design cards.

Cannot be imported directly because most settings (URL, name, description, access roles) must be permanently different between source and target app.

However, the Menus field will be imported and overwritten in the target app.

3.3 Duplicating an existing app

Process to duplicate an app using the new functionalities:

User creates a new, empty app and sets the desired name and URL (already possible now).

User exports the old app (new feature 1.1) to a .pgrid file

User imports the .pgrid file into the new app (new feature 1.2)

Alternatively, as before, a duplication at file system level can be commissioned via a chargeable ticket to the support team.

3.4 Recycle Bin

Cards that are logically deleted in the source app are also exported/imported (the delete flag in the target app is set accordingly). 3.5 Using the app during an ongoing import/export.

Is technically possible in principle and is not prohibited.

However, to prevent any problems/inconsistencies/confusion, an individual organizational solution should be found for the time being (e.g. announcement of maintenance windows at off-peak times). The import code makes sure that it imports the cards with the lowest hierarchy first, so that the app is at no time in a state where references run into the void. Note: You can probably never guarantee this 100%.

3.6 Attachments

Since currently only the attachments of the Code-Overview-Card have design significance, no attachments will be exported/imported for the time being. This means that the app developer has to take care of the update on his own.

Since a .pgrid file can become quite large (GB range), this cannot be stored in the DB, but must always be in the file system of the server.

3.8 Background Python threads

The import and export is run in an extra thread so to not block other functionality.