Skip to main content

Example: hand a publish to a person

Synced from bicycle-studio-api

Source: studio_guide("example-publish-handoff") (GET /api/studio/v1/guide/example-publish-handoff) rendered at origin/platform (1afd83f), synced 2026-09-28. Do not edit this page here; change the source and run yarn sync:studio.

Use this when your token has built and validated an app version and the next step may reach other people. You build; a person with publish rights decides what goes live.

Person-only stops: a person with publish rights on functions confirms demo_kpis at the link function_publish returns; a person with publish rights on apps confirms any app version that adds or re-pins an import, at the link dataapp_publish returns. Both sign in to Studio; a token cannot confirm.

Files​

None. This uses the app and function from "Example: a KPI function and a hand-built app that shows it".

Calls, in order​

  1. dataapp_describe(app_id): app state draft, a versions table with each version's state, and whether the version imports anything. dataapp_complete_upload answered validated for the version you hand off.
  2. function_publish("demo_kpis", 1): "A person must confirm this in Studio before v1 of demo_kpis goes live: open https://preview.bicycle.ai/`/apps/functions/demo_kpis?publish=v1 ... Who: a person with publish rights on functions (the owner or an admin), signed in to Studio; a token cannot confirm." Send the person the link, say what it does (lets apps and workflows run orders_by_day` through this function), and stop.
  3. You do not wait for the person. Add "functions": {"kpis": {"ref": "fn:<tenant>/demo_kpis@1"}} to the manifest, build, and upload a version with dataapp_new_version and dataapp_complete_upload: validated. An unpublished version may import a tested draft. dataapp_describe(app_id) lists kpis as draft (tested).
  4. dataapp_publish(app_id, version) before the function is published: function_unpublished (409), "a published app needs published function versions", naming fn:<tenant>/demo_kpis@1. Nothing moves. After they confirm the function (function_get("demo_kpis") shows it published), call dataapp_publish on the same version once more. You do not upload again. Studio answers a link for a person, because the version adds an import. Give it to them and stop.
  5. The person opens the link and confirms. dataapp_describe(app_id) then shows state published and that version as current.

Know this before step 4: a version with no imports is not gated. A token with apps:publish publishes it at once (state: published). If you want a person to decide, do not call dataapp_publish on it; send them the appUrl and let them publish from Studio. If you publish by mistake, dataapp_unpublish(app_id) puts the app back to draft.

Switch it off​

dataapp_unpublish(app_id)          # only if it was published
function_disable("demo_kpis", reason="example cleanup")

Verified on preview 2026-09-28: dataapp_describe, function_publish (link for a person), dataapp_publish (a no-import version: published at once, not refused), dataapp_unpublish, dataapp_new_version, dataapp_complete_upload (draft import: validated), dataapp_publish (draft import: refused, function_unpublished 409) ran. Not run: the publish after the function is published, and step 5 (they need the person's function publish), so the app-import link wording is not verified. No invocation ids were issued.

guide_version bb2461328de4