Import, export, and predefined queries

In user language: This article is for workspace admins. It explains what happens to predefined queries when you copy a skill or app to another workspace, how import can fill them in one step, and what to watch when the target database schema differs. Everyday members only need to use the skill or app; they do not need to know file names inside the zip. Implementation notes are at the end.

Date: 2026-07-19 Status: Implemented Related help: Workspace apps · Data connections and predefined queries · How to write a good workspace skill Mechanism notes: Workspace apps

---

Takeaway (read this first)

In one sentence: UI and logic travel in the skill/app pack; how to fetch data lives in predefined queries on a data connection; on migrate, take the query definitions as dependencies and optionally merge them on import.

---

1. Why a move used to “import but not work”

Skills and apps do not store a business-database connection. They call workspace data connections by query id, for example:

• The skill body says “call predefined query staff_by_dept”
• An employee-portrait pipeline hard-codes employee_by_name
• A report-app script has platform.query_run("dept_rank_emp", …)

The export pack used to mainly take:

• Skill: write-up, scripts, reference materials
• App: UI description and logic (not registered business data)

Predefined queries hang on Data integration → Data connections, not inside the pack. If the target workspace has no query of the same name (or no matching data connection), import itself often succeeds, but the first fetch reports “query definition not found”, or the conversation guesses another id on the spot and uses table preview as if it were a real result.

---

2. What we do now: a dependency list travels with the pack

2.1 Collect automatically on export

When you export a skill pack or app pack, the system:

1. Scans materials in the pack for query ids (pipeline, scripts, body text, and so on)
2. Resolves matching definitions in this workspace’s data connections (name, description, SQL, parameters)
3. Writes a dependency file into the pack (no host, account, or password)

If the source workspace itself does not have complete definitions for those queries, the pack cannot carry the SQL — configure the usual queries on the source side before you export.

2.2 Gap check on import + optional write

Import preview compares against the target workspace and shows roughly:

After you confirm import, if anything is missing (or conflicting), the workspace admin is asked:

• Whether to write onto a data connection in this workspace
• On same-name conflict: keep what is already there, or overwrite with the pack definition

You can also choose “import only, do not write” — the skill/app still lands; you fill queries later by hand under Data integration.

Non-admins can import a pack but cannot write queries onto a data connection; the UI asks them to involve an admin.

---

3. Steps (admin)

3.1 Export from the source workspace

The export still does not include business-table data already registered in the source workspace, and does not include database connection secrets.

3.2 Prepare a data connection in the target workspace

Before writing predefined queries, the target workspace needs:

1. Data integration enabled, with a working MySQL (or similar) data connection
2. Business tables in the database (or at least room to edit SQL later to match)
3. The person importing is a workspace admin (if they want to write queries in one step)

3.3 Import and write missing queries

1. Import the skill or app pack; handle “identifier already exists” (overwrite / copy) as prompted
2. If predefined-query dependencies are flagged: pick the data connection to write to, confirm “write and continue import”
3. Open Data integration → that data connection and check the query list
4. Run a real scenario once (type / to pick the skill in conversation, or tap the app button)

3.4 Same-name conflict

---

4. When the target database differs from the source

The dependency list answers “is there a same-name query”. It does not guarantee the SQL will run on the target database. Common gaps:

• Different table or column names (e.g. empId vs emp_id)
• Allowed table scope is narrower; write-time validation fails
• Parameter names do not match what scripts/skills call

Suggested path:

1. Finish import and write missing queries
2. Run smart check and fix on the important connections (see Checking predefined queries)
3. Execute each query id once with fixed sample parameters
4. For employee-portrait fixed pipelines, also see Employee portrait and data connections

---

5. How this relates to “generate a skill / write queries from chat”

The three complement each other: day-to-day setup uses forms/conversation; whole-pack moves use import/export dependency merge.

---

6. What members see

• Import succeeded, queries written: use the skill or app as before
• Pack imported, queries not written: tapping report/portrait fetch may fail; conversation may say the query was not found — ask an admin to fill them in
• No data connection: queries cannot be written; configure a connection first and import again (or paste query definitions by hand)

---

7. Checklist (before you migrate)

• [ ] Source workspace: queries the skill/app depends on are configured on a data connection and can run
• [ ] You have a zip (app or skill)
• [ ] Target workspace: data connection works, table structure is roughly usable
• [ ] An admin imports and chooses to write missing items
• [ ] Conflicts were keep-or-overwrite according to the intended definitions
• [ ] Spot-check conversation fetch or an app button
• [ ] If schemas differ, smart check or hand-edit SQL is done

---

Implementation map (for developers / troubleshooting)

Preview response query_deps includes ready/missing/conflict counts and a suggested connection; if merge fails the app/skill may still be imported, and the response can include query_deps_merge_error for UI.

---

Related

• Data connections and predefined queries
• Workspace apps · Import and export
• Employee portrait and data connections
• Skills that create report apps
• Checking predefined queries