datagrok-ai/public/datagrok-projects

datagrok-projects

Save / publish — drive the platform's Save dialog

The Save Project dialog is the platform's save/publish entry and the only reliable way to get per-table data sync, creation-script dependency linking, and the correct upload order. Do not hand-write project/table saves with grok.dapi — open the dialog and drive it through its functions.

1. Open the dialog (datagrok_exec) — do NOT await the dialog promise (it resolves only when

the dialog closes):

``js const project = grok.shell.project; DG.Project.showSaveDialog({ tables: [t], views: [view], // add more pairs for multi-table saves project: project.isOnServer ? project : undefined, // re-publish into the SAME project name: project.isOnServer ? undefined : '<name the user gave>', }); return {dialogOpened: true}; ``

1. Find it: list_view_widgets — the dialog is an extra root ref dlg0 ("Save project");

note also the child ref of its entity-list widget (type ProjectEntityMoveWidget).

1. Read its state: get_view_function_result(name: 'getProjectSaveInfo', widget: 'dlg0') —

name (with validity), description, presentation mode, and every entity to be saved, with dataSync / dataSyncPossible per table.

1. Adjust only what the user asked for, via call_view_function:

• on dlg0: setProjectName, setProjectDescription, setPresentationMode, setSaveMode

(when the dialog offers it)

• on the entity-list widget ref: listEntities, setDataSync(table, enabled),

setEntityAction(name, action)

Every function returns {success: false, error: ...} with the reason when something can't be done (e.g. data sync without a creation script) — report that reason; never work around it with raw tag/meta writes.

1. Confirm: call_view_function(name: 'clickButton', parameters: {name: 'OK'}, widget: 'dlg0')

— applies the save and closes the dialog. If the user wanted to review first, stop before this step and say the dialog is ready.

1. Verify server-side (datagrok_verify) — the upload is asynchronous, so if the first

re-read misses, confirm the dialog has closed and retry once:

``js const p = await grok.dapi.projects.filter('friendlyName = "<name>"').first(); return p != null; ``

When data sync was requested, also verify the table: (await grok.dapi.tables.find('<tableInfoId>')).tags['.data-sync'] === 'sync'.

Data sync — the one precondition

A synced table re-runs its creation script when the project opens. The platform records that script only when the query/script runs through its own pipeline — grok.functions.call / grok.data.query run as processed calls and record nothing. So for "query the database and save it with data sync":

1. Make sure the query is saved on the server: create it with

connection.query('<name>', '<sql>'), q = await grok.dapi.queries.save(q), then re-read by id (grok.dapi.queries.find(q.id)) — never by name, duplicates shadow name lookups.

1. Run the server copy so the result opens in the workspace with a creation script:

``js const call = q.prepare({}); await call.call(false, undefined, {processed: false}); ``

1. Open the Save dialog (above) and setDataSync(table, true). If it answers

"no creation script", step 2 didn't happen — fix that instead of forcing tags.

Create / attach / share

• Create an empty project: datagrok_projects(op: "create", args: {name}) once.
• Attach the current table/view to a project: use the Save dialog flow above.
• Share: datagrok_projects(op: "share", args: {projectId, groups, access}) —

access "View"|"Edit", default "View"; ask when no group is named. Confirm it with datagrok_projects(op: "list_shares", args: {projectId}), not with grok.dapi.permissions (its lists come back empty from a script). When the platform's Share dialog is open instead (a dlg<N> ref), drive it the same way: getShareInfo, addShareGrantee(name), setShareAccess(access), setShareMessage(message), then clickButton OK.

Don't

• Hand-write saves with grok.dapi.tables.save / uploadDataFrame / projects.save — the

dialog handles upload order, table meta, and sync dependencies; manual writes corrupt them.

• Set .data-sync / .script tags directly — use setDataSync and let it refuse when the

precondition fails.

• Re-run a save after a timeout — re-read state first (getProjectSaveInfo, or check the dialog

closed); a second dialog or a duplicate project is worse than a late answer.

• Promise data sync before setDataSync (or dataSyncPossible) confirms it.