Tools

These are the tools the Commcare Nova MCP server exposes. You don't call them directly, your agent does, in response to natural-language instructions. Knowing what's available helps you write better prompts and understand what your agent is doing.

Easy starting point

get_agent_prompt returns the same instructions Commcare Nova's own web builder follows when it builds apps. Tell your agent to call it on its first turn (with mode: "build" for a new app or mode: "edit" for an existing one) and follow the text it returns. You don't have to do this, your agent can drive the tools however it wants, but starting from the instructions Commcare Nova already tunes for these tools is the fastest path to good results.

It's a long result, a whole system prompt. A prompt that fits the model-facing result budget arrives as plain text. A larger prompt instead arrives as a nova-agent-prompt-page JSON object. Have your agent save its prompt_chunk, call the tool again with the same mode and app_id plus next_cursor, and repeat until complete is true. offset_unit is unicode-code-points: chunk_start, chunk_end, and prompt_length count Unicode code points, not UTF-16 code units or UTF-8 bytes, and a chunk never splits a surrogate pair. Each page must have the same prompt_sha256, each chunk_start must equal the preceding chunk_end, and the final chunk_end must equal prompt_length. The agent can then concatenate the chunks in order and follow the assembled prompt. If the app changes while those pages are being fetched, CommCare Nova refuses to mix the snapshots and asks the agent to restart without a cursor.

The complete assembled prompt always ends with the line NOVA-PROMPT-END. Have your agent check for it and stop if it's missing. Pagination keeps all guidance and the complete app summary; it does not shorten either one to fit.

Stable identities and structured content

Read an app before editing it. Commcare Nova returns stable UUIDs for modules, forms, fields, choices, case-list columns, search inputs, automations and their nested criteria, updates, recipients, events, and filters, worker-information properties, roles, personas, organization levels, place-information properties, places, case operations, after-submit links, Project data tables, columns, and rows. Editing tools address those objects by their UUID parameters, such as moduleUuid, formUuid, fieldUuid, columnUuid (the case-list column), searchInputUuid, operationUuid, and linkUuid, rather than by a display name, saved field id, path, list position, or operation id. Project data tables and columns carry their UUID on id. Names, saved ids, lookup tags, and column export names remain readable, editable authoring values; changing one does not retarget a UUID-linked reference.

When one item in a creation call will be referenced by another item in that same call, give it its final UUID in the matching creation slot: moduleUuid, formUuid, fieldUuid, optionUuid, columnUuid, searchInputUuid, or operationUuid. Otherwise, omit that slot and let Commcare Nova mint the UUID. A same-call group or repeat parent must appear earlier in the field list and declare fieldUuid. An operation whose result is consumed by a later operation must likewise appear earlier; predeclaring identity does not change execution order.

Every successful creation result returns the final identities it created in input order, including identities Commcare Nova minted. Field receipts nest their inline choice UUIDs in source order; create_form nests all field and choice receipts under its form, and create_module nests forms, fields, choices, and born case-list columns under its module. Continue from that result: no read-after-write is required just to discover a new UUID.

Machine-authored inline choices have exactly { "optionUuid"?: "...", "value": "...", "label": { "parts": [...] } }. A choice's value is the answer the app stores, not its wording: a lowercase slug with words joined by underscores (prefer_not_to_say), unique within the field and kept stable once data exists. It can't hold spaces, quotes, or apostrophes, because the device refuses a choice value with a space in it and a multi-select answer is a space-separated list of these values. The wording people read goes in label. A value that breaks that shape is refused at the tool's input schema, and the refusal restates the shape; an app that already holds such a value fails validation with a finding that names the replacement slug for that exact choice. Stored uuid, option media, and identity aliases are rejected on every field writer. Lookup-backed choices use the canonical tableId / valueColumnId / labelColumnId fields, plus optional filter; there are no tableUuid or column-UUID aliases. Option media is changed through the dedicated media tools.

MCP expression slots take Commcare Nova's typed AST, not an XPath source string. For example, a field reference is a part such as { "kind": "field-ref", "uuid": "<field UUID>" }; a complete XPath value is { "parts": [/* text and typed reference parts */] }. Reference-capable prose uses the same outer { "parts": [...] } shape with explicit reference atoms. Plain text that happens to contain #form/name stays plain text. Predicate and ValueExpression leaves likewise use UUIDs, for example { "kind": "field", "uuid": "<field UUID>" }, { "kind": "input", "searchInputUuid": "<search input UUID>" }, { "kind": "id-of", "opUuid": "<operation UUID>" }, and { "kind": "session-user-property", "userPropertyUuid": "<property UUID>" }.

There are exactly two name-keyed leaves, both deliberate: a case property, which uses (caseType, property), and a CommCare session field Commcare Nova does not own, which names one field out of a closed framework set.

This is only the machine contract. In Commcare Nova's visual XPath editor, people still type and read friendly expressions such as #form/first_name; Commcare Nova resolves that text to identity when the edit commits and prints the current friendly path when it is opened again. Users are never asked to write a UUID-shaped XPath.

Lookup expressions use the same identity rule. A row-scoped column is { "kind": "table-column", "tableId": "...", "columnId": "..." }; table lookups and lookup-backed choice sources likewise use tableId and column ids, never table tags, export names, or display labels.

Browsing apps

Languages and translations

App languages use the same source/default/target overlay as the visual Builder. The language catalog is not an AI allowlist: an agent may add, copy, read, and manually translate any individual living language whether or not Nova offers automatic translation for that exact direction. A language is an identity object {language, script?, region?}, never a combined code string: language is an ISO 639:2023 Set 3 code for one individual living language (cmn, spa, hin); script is an ISO 15924 code (Hans), required exactly when the language has more than one customary writing system; region is an ISO 3166-1 alpha-2 code (MX), always optional. Macrolanguages (zho), two-letter codes (zh, es), and non-living codes are rejected with the identifiers to use instead; a macrolanguage rejection lists its individual members by name. The worker-facing name and text direction derive from the identity itself rather than being authored.

get_languages reports automatic translation as Available, Not evaluated, or Withheld for each source-to-target pair. Available means both languages are distinct members of Nova's checked-in 57-language launch set; the language axis alone decides it, so two writing systems of one language are never a translatable pair. It is not a claim of provider-published coverage or per-direction bilingual certification. The bounded write tools below remain the complete MCP surface: MCP can inspect availability and author or copy translations, but it has no paid automatic-translation action.

Read get_languages, then call get_translatable_content for the target before writing. A set operation must repeat the unit's current sourceFingerprint as expectedSourceFingerprint; it is machine-authored and starts as Needs review. A review operation repeats the explicit entry's stored fingerprint as expectedSourceFingerprint, the unit's current fingerprint as expectedCurrentSourceFingerprint, and the exact target value returned by the read. These independent fences refuse the whole batch if either side changed concurrently. Prose values keep typed reference parts; do not flatten a protected field reference into its displayed text.

add_language always copies a complete effective projection. If the copy source itself falls back for one unit, the new target receives the value workers would actually see. Missing and out-of-date target entries also fall back to the current canonical source at runtime, so incomplete translation work never creates an invalid app.

Checking project-space compatibility

check_project_space_compatibility is a read-only destination check. It needs both app_id and an explicit domain, and it checks exactly that CommCare HQ project space without compiling, uploading, or changing either side.

Call get_hq_connection first to list the available project spaces. Use the domain the user selects, and never choose among several project spaces on their behalf. The check requires nova.hq.read because it contacts CommCare HQ.

The result returns project_space_compatibility with:

• status: not_needed, ready, or blocked for the checked destination
• target_domain: the exact project space that was checked
• required_capabilities: the app features that need project-space support, including why the app uses each one and whether it is available, missing, or unverified
• blockers: required capabilities that are missing or could not be confirmed
• advisories: guidance that never blocks publishing, including slower large Search results when the faster path is unavailable or unverified
• message, support_email, and docs_url: a plain-language result and the next place to go

A missing or unverified required capability blocks a later direct publish before lookup tables, places, or the app are sent. An advisory never blocks. upload_app_to_hq performs its own authoritative check immediately before any remote write, even when the agent called check_project_space_compatibility earlier. A successful upload and a project_space_incompatible error both return project_space_compatibility so the agent can explain the checked result.

compile_app stays available because a download has no selected destination. When the app has destination requirements, its leading nova_project_space_compatibility result block contains project_space_compatibility with status: "not_checked". The same report is also available in _meta["nova/projectSpaceCompatibility"]. Check the actual destination later with check_project_space_compatibility.

Creating and deleting apps

Projects and sharing

Every app lives in exactly one Nova Project, and the Project is the sharing unit: each of its members sees the Project's apps plus their case data and media. Your account starts with a personal Project, which is private by construction and can't be shared. When other people need to use what your agent builds, the flow is: create a shared Project once, create apps into it, and invite the humans.

The roles: a viewer reads apps and data, an editor also edits them, an admin also manages members, and the owner is the member who created the Project. Owner isn't assignable — the creator stays the one owner.

Prefer creating an app in the right Project from the start. An app that references Project data tables or has captured form submissions can't move between Projects, so move_app is the recovery path for apps born in the wrong place (typically the personal Project), not the everyday flow.

Building a new app from a description

A new app is named Untitled and already contains one survey module, survey form, and text question. Design the requested app first, then refine that starter or replace it only after its valid replacement exists. update_app gives it the requested name. When the design uses custom worker information, add_user_properties declares it next, before generate_schema, modules, forms, conditions, or calculations can refer to it. generate_schema then commits the data model, and each create_module call lands one complete module, every call checked as it lands. Commcare Nova supports one submenu tier: create a top-level parent first, then pass its UUID as the child's parentModuleUuid. After a Connect build's forms exist, configure_connect sets the mode and complete UUID-addressed participant set in one call. Roles and personas can follow the app structure; the referenced worker information cannot.

Configuring CommCare Connect

configure_connect owns enabling Connect, switching between learn and deliver, replacing the participant set, and disabling Connect. For an enabled mode, pass the complete nonempty set of participating forms. Every form is addressed by formUuid; an unlisted form is auxiliary and any old Connect block on it is cleared.

{
  "app_id": "app-id",
  "mode": "learn",
  "participants": [
    {
      "formUuid": "01890f45-0000-7000-8000-000000000002",
      "connect": {
        "learn_module": {
          "name": "Health basics",
          "description": "Introduction and guided practice",
          "time_estimate": 1
        }
      }
    }
  ]
}

time_estimate is the estimated whole hours needed to complete the module. Round up and use at least 1.

The Connect sub-block id is an emitted Connect identifier, not the address of the Commcare Nova form. Usually omit it: Commcare Nova derives it once and stores the final value. An explicit id must already be valid and unique, or the whole call is refused; Commcare Nova never silently rewrites it. The form itself is always selected by UUID.

To disable Connect and clear every form's Connect block in the same change:

{
  "app_id": "app-id",
  "mode": null
}

Do not include participants with mode: null. Duplicate or foreign form UUIDs, empty participation, incomplete blocks, mixed mode families, and duplicate Connect ids are refused before anything saves. Once a mode exists, update_form can refine one participant's block, but it cannot create the mode, cross mode families, or change which forms participate. Creation tools have no Connect slot; a newly created form is auxiliary until a later configure_connect call replaces the complete set.

Working with workers and personas

Worker information defines the values a worker can carry. Roles provide reusable defaults for those values, and personas are named Preview workers that can inherit a role and override individual values. Read first to get stable UUIDs: role and persona values name a worker-information property by userPropertyUuid, so changing its saved name never retargets the value.

Custom worker-information references use that same identity. In Predicate and ValueExpression inputs, use { "kind": "session-user-property", "userPropertyUuid": "..." }. The name-based { "kind": "session-user", "field": "..." } arm is for CommCare-provided or external worker fields that Commcare Nova does not own. Textual XPath in the visual editor shows the current #user/<saved-name> projection. In an MCP XPathExpression, a custom property is instead an explicit { "kind": "user-property-ref", "userPropertyUuid": "..." } part; an external property is a user-ref part. MCP never submits the projected name for Commcare Nova to resolve.

On update tools, leaving a field out keeps it and passing null clears a clearable field. Every batch is checked as one change; if any entry would make the app invalid, none of it saves. Role/persona updates use valuePatch for one UUID-addressed value at a time: a string sets it, null clears it, and omitting valuePatch leaves every value unchanged.

Working with organizations and places

An organization has blueprint-owned levels and place-information properties, plus app-scoped place rows. Read it with get_organization before writing. Its opaque, snapshot-bound cursor pages one bounded stream across levels, properties, and matching places; accumulate each collection until page.complete. If a later page reports that the snapshot changed, restart without a cursor. Use query to narrow a large tree and request includeValues only when custom place values matter.

Every level, property, and place has a stable UUID. Names are editable labels; level codes and place site codes are create-once external identities. Place writes also use an exact organization revision: pass the revision from the complete read into the first write, then chain each successful result's revision into the next write. Re-read after a conflict. update_location supports a one-property valuePatch; a string sets the UUID-addressed value, null clears it, and values replaces the complete value bag.

When a saved reverse-hop owner rule requires a destination below every new source place, create the source with its complete descendants tree in one create_location call. The tree is structurally nested and bounded; nesting is parentage, so it introduces no request-local identity vocabulary. The compact result mirrors that tree with each server-minted final place UUID and site code. Sequential creates are refused because they would leave the source temporarily invalid.

A persona's locationUuids replace its complete place assignment in main-first order. Case flow controls ownership and delivery independently from address-book visibility. Reverse-hop place owners export on every mode: they travel as level codes and the case's own owner. A fixed place owner is Preview only, because it travels as Nova's own place id and would match nobody on a CommCare HQ project.

Archiving is a two-call confirmation flow. First call set_location_archived with archived: true and no confirmation, review its bounded impact and exact confirmation token, then repeat with confirm: true, expectedRevision set to the returned expectedRevisionForConfirmation (the impact revision), and the unchanged confirmedImpact. Never confirm a blocked preflight. The subtree is archived and persona assignments there are removed, but owned cases are never reassigned.

Working with automations

Automations are canonical app objects, not commands that execute in Preview. Read them first and preserve the stable UUID on the automation and every nested criterion, setup-only instruction, case update, recipient, schedule event, and user-data filter that still represents the same item. A complete update removes any nested UUID it omits, but the server projects that desired state into the same granular mutation grammar used by the Builder and Solutions Architect.

commcare nova can describe automatic case-update rules and conditional alerts that CommCare HQ can represent. It never claims to install them: HQ exposes HTML setup pages and an alert-content spreadsheet import, but no REST resource for rules, alerts, or schedules. Reads and successful add/update results return freshly derived manual setup guidance plus the criteria omitted from local matching. Remove returns its deletion receipt only and leaves a rule already configured in HQ unchanged.

The returned guide identifies the exact current HTML route templates: /a/<domain>/data/edit/automatic_updates/ for automatic case updates and /a/<domain>/messaging/conditional/ for conditional alerts. CommCare HQ can be configured to run every active case-update rule for a case type whenever a case is saved. That behavior is project-wide, so it is a deployment caveat, not a field in commcare nova's per-rule schema.

The loaded schema mirrors the two current HTML forms without a shared criteria superset. Automatic updates accept value/date comparisons against case, parent, or host properties, at most one standard closed-parent condition, and the separate server-modified-age field; they do not accept regex conditions. Alerts accept value comparisons plus portable regex against direct case properties, and do not accept date, parent/host, closed-parent, or server-modified conditions. The closed parent is HQ's normal parent link, not a caller-selected index or extension. Names must be nonblank and already trimmed. Equality and fixed-update literals must be exact, nonblank, unquoted stored values, and alert regex patterns must be nonempty. Web users are not a recipient arm. Date conditions compare the current date directly with the property date plus a signed day offset. If the property is a datetime, HQ and Preview use its written calendar date and discard the time and explicit offset before adding days. Both automation families accept at most one UUID-backed location condition with an explicit descendant flag. HQ's runtime and form POST accept it, though the current visible editors hide the picker; returned guidance states the HQ-administrator application requirement. The condition remains locally countable from the organization snapshot and is never reduced to setup prose. Automation inputs always use commcare nova's standard property names. Returned setup guidance projects case_type to HQ type, case_name to name, date_opened to opened_on, and last_modified to modified_on; case_id, owner_id, and external_id remain unchanged. case_id and case_type are read-only. status is refused because the app stores open/closed text while HQ exposes a boolean field. Standard datetime properties allow date or blankness conditions, not equality or regex, and restart/event-time slots accept custom case properties only. After trimming, a case-property event-time value must begin with H:MM or HH:MM, and the whole value must parse as a time. Suffixes such as AM/PM or seconds are accepted; blank, nonmatching, or unparseable values use 12:00 PM. Concrete HQ worker/group recipient IDs must be nonblank and have no surrounding whitespace. Connect content also refuses matched-case, parent-case, all-child-cases, case-property-email, and case-group recipients. Returned guidance states that SMS Survey requires Inbound SMS access. Connect content requires CommCare Connect support in the project space, which Nova checks before publishing, and every resolved recipient must be a CommCare mobile worker with an active PersonalID link. Checkbox-style, case-property, and custom recipient kinds are singletons; list recipients cannot repeat a concrete target. Descendant controls require a location recipient, location-level filters require descendants, and each worker-property filter key appears once. Each filter value is either an exact literal (empty and surrounding whitespace are meaningful) or a structural case-property value with (caseType, property) identity. Never encode a lookup as brace-wrapped literal text: HQ interprets that string dynamically. Every triggering case must contain a referenced property because HQ raises when its direct lookup is missing. HQ applies filters only to user-account recipients, so the schema refuses filters with case, parent/child-case, case-email, case-group, or registered custom recipients; those results bypass filters or have an unknown runtime type. Multiple keys/values or exact empty/whitespace values require HQ's JSON filter mode and the returned guide names its system-administrator prerequisite.

Every message field is an AutomationMessageTemplate, not a magic-token string. Its parts are literal { kind: "text", text } values, explicit { kind: "case-property", scope, caseType, property } references, or closed { kind: "context-property", context, property } case-owner/recipient references. Token-looking text such as {case.case_name} stays literal; the guide doubles its braces before HQ's Python Formatter evaluates the result. Use a structural part only when HQ should substitute a value. Reads return the same canonical parts, while the generated guide alone projects them to HQ {case...} / {recipient...} syntax. Registered custom recipient/content IDs and setup-only condition text must be concrete, trimmed, and nonblank. A setup-only condition has an explicit ucr-filter or registered-custom kind; the returned guide names the former's project-space support and the latter's system-administrator save requirement. The returned guide also names HQ's system-administrator save requirement whenever a custom recipient or custom content handler is present; registration plus project-administrator access is not sufficient.

Custom case properties named owner, host, or last_modified_by cannot be used in a message case-property part in case, parent, or host scope. HQ adds those names to its formatter context before it adds custom case data, so the framework values shadow same-named custom properties. Rename the custom property, or use a context-property part when the intended value is the real case-owner or recipient context.

Conditional-alert schedules are valid only when one HQ setup form can express them. Every event uses one schedule-wide content type, and immediate events after the first wait at least five minutes. Custom Daily events use one timing mode and remain ordered; Weekly and Monthly schedules also share timing and content, with Monthly limited to days 1–28 and -3–-1. Weekly and Monthly days are unique closed choices in HQ's canonical order. A Weekly day is stored as an offset from startDayOfWeek; changing the start must remap and re-sort offsets to preserve the selected absolute weekdays. For a fixed date, setup guidance omits HQ's hidden Custom Daily start-offset control and explains that HQ derives the hidden Weekly start weekday from the date. Random windows cannot overlap. Survey reminder intervals must total less than the expiration window, and case updates in partial submissions require partial submission itself. A timed restart property is valid only with a rule-trigger start. A single zero-delay immediate event maps to Immediately; any delayed or repeated immediate schedule maps to Custom Immediate Schedule. These are input-schema constraints shared by SA and MCP, not post-save warnings.

Email content has one discriminated body: plain-text carries message and targets a project without the domain-level Rich text emails toggle; rich-text carries only html and requires that toggle. HQ sanitizes and rewraps rich HTML and derives its plaintext, so do not send parallel bodies or promise byte-exact rich output. Every email event in a schedule uses the same body kind.

Builder Preview may count current real case rows against each kind's ordinary property criteria, including automatic-update parent/host reads, and the automatic-update closed-parent condition. It never updates a case, sends a message, or advances a schedule. UCR filters, instance-registered custom criteria, and HQ server-modified age have no honest local evaluator; carry the first two as distinct setup-only kinds. The Builder names those omissions beside its partial count; MCP automation results return the same omission list without pretending to return or execute a Preview count. For locally countable property criteria, whitespace-only strings are blank and equality matches only an exact stored string. Stored non-string values never equal the configured string and therefore satisfy inequality. A parent/host equality or inequality requires that related case to exist. Parent reads use the parent identifier regardless of relationship. Host reads are admitted only while the app model leaves one unambiguous canonical extension relation for the automated case type. If an advanced case operation can add a second extension relation, commcare nova refuses every host-scoped criterion, update target, update source, and message case-property part instead of choosing from HQ's unordered extensions; the extra link and parent-scoped references remain valid. Every host-scoped reference also requires exactly one live extension at runtime. Retained extra extension indices make the current-match count unavailable, and HQ does not define which extension it chooses as the host. Alert regex matching applies only to stored strings; commcare nova does not coerce numeric or boolean case values to text. Date conditions use the same relation selection and compare only the property's written calendar date, never its time of day.

Working on modules

Modules may be top-level or may sit one level inside a top-level parent. This menu relationship controls navigation only. It is separate from a case type's parent_type data relationship, so neither implies the other. A child cannot contain another child, and a parent with children stays top-level until those children move or are removed.

Every form has one canonical module. Commcare Nova does not author linked or shadow copies of one form under several menus. When you need several views of the same cases, use case-list filters and design the menu structure deliberately.

Working on the case list

A module's case list is the screen that lists existing cases and the search bar that filters them. Its configuration covers the columns shown in Results and Details, an optional filter predicate, the search inputs the user types into, their ordering, an optional card layout, and whether a form opens with one case or an ordered set.

set_case_list_tile also carries grouping, through tile.grouping. It shows the cases that share a connection together, under one heading:

Two consequences to pass on to whoever asked for grouping. Choosing a group uses its first case. A several-case workflow can choose several groups, but each group's one checkbox still adds only its first case; the other rows are there to read. Every case with no such connection lands together in one group. The list also pages by group, so a page holds whole groups and however many cases they carry.

Working on case search

Case search is the search experience that surrounds the case list: the screen title, helper text, and search button label the user sees, plus a few niche search-side filters most authors never reach for. These tools set those slots; the search inputs themselves live on the case list above. Each setting is independent: pass null on any slot to clear it.

Working on forms

CommCare has four form types: registration creates a new case, followup updates a case, close loads and closes a case, survey is standalone (no case).

Where a form goes after submit

A form's post_submit says where people go once it is submitted. When the destination depends on data, give the form after-submit links: they are checked in order after the form closes and the first true condition is followed. An unconditional link is the otherwise and can only be last; with conditional links and no otherwise link, post_submit is where people go when nothing matches, and Commcare Nova stores it explicitly if it was not set. A link's condition and datums run after the form has closed, so they read the module's case, worker, and session values, never the form's answers; save an answer to a case property first. A link that names datums must name every selection datum the target needs. Each link has an immutable identity: get_form returns it as the link's uuid, and the link tools take that value as linkUuid.

Working with Project data

Project data belongs to the app's Nova Project, so a change may affect several apps. Read before writing. get_lookup_tables returns table and column definitions without the row values, plus counts, byte use, and the current Project, definition, row, and table revisions. Every table id and column id is its immutable UUID. Names, tags, labels, and export names are included so the agent can explain its choice, not so it can address the resource.

get_lookup_table_rows reads up to 100 rows at a time in authored order. Each page is bound to the table revision, query, and requested columns; if the table changes between pages, restart the read instead of combining two generations. Repeat the same query and columnIds with each returned cursor. Rows and cells use stable row and column UUIDs. A missing cell and an explicitly empty text value are different values and stay different across every tool.

Every write other than table creation takes expectedTableRevision. Chain the returned revision into the next write, and re-read after a conflict. Adds and moves use afterColumnId or afterRowId; null means first and an omitted add anchor means append. Numeric positions, table tags, and column export names are never addresses.

create_lookup_table creates a table, its columns, and optional initial rows in one transaction. Request-local column keys let initial row cells name columns whose UUIDs do not exist yet. The result pairs each key with its minted column UUID and returns each row UUID by input position, without inventing a second durable identity. edit_lookup_columns batches add, update, move, remove, and retype operations. edit_lookup_rows batches add, complete-row update, move, and remove operations. replace_lookup_rows replaces the complete row set and mints new row UUIDs for the replacement. A batch either lands completely or saves nothing.

Changing a table or column export name, retyping or removing a column, and removing a table require admin access. Other writes require edit access. A referenced table or column cannot be removed, incompatible values block a retype, and the final column cannot be removed. A stale write returns the current revision, and a destructive refusal states whether an app or accepted design still depends on the resource; there is no force option.

set_field_options_source replaces one single- or multiple-choice field's complete source. A lookup source names the table, saved-value column, and display column by UUID. An inline source carries at least two options, each with its own UUID, value, and label. Switching source kinds is a complete replacement; the previous source is not retained.

An optional row filter may compare columns from that same table with fixed values, worker/session values, and eligible earlier answers from the form. It cannot read case data, Search answers, later form answers, or answers inside a child or sibling repeating section.

Changing cases on submission

Most forms save their answers onto their primary case through their fields. Case operations cover additional ordered effects: create another case, update or close a known case, connect cases, rename or retype one, assign an owner, or repeat an effect for every row in a repeating section.

Each tool names the form by moduleUuid and formUuid, both returned by read tools. An operation has an immutable operationUuid and a separate editable id; tools address and reference the operation by UUID. Form-answer terms use field UUIDs, repeat scopes use repeat-field UUIDs, and an operation target uses { "kind": "op", "opUuid": "..." }. A later operation in one add call may consume an earlier create by UUID when the producer declares operationUuid; the complete list is checked and saved atomically.

Operation ids and link identifiers contain letters, numbers, and underscores and start with a letter or underscore. Write-property names use the same characters and start with a letter. These are readable, editable values rather than object addresses: reads return the complete canonical Predicate and ValueExpression ASTs, including lookup-table terms, and subsequent calls keep targeting the operation by operationUuid.

Operation writes may save custom case properties or the standard external_id scalar. They may not write case_name; create, rename, and retype operations expose their dedicated naming fields instead. Commcare Nova keeps standard scalars out of custom case-property data.

Working on fields (questions)

A field is a single question on a form: text input, dropdown, date, number, repeat group, label, and so on. Most fields also save to a case property; some (on survey forms, or label-only fields) don't.

A section is a field kind of its own: a page of the form. On a phone each section is one screen, Next checks that screen before moving on, and an empty or fully hidden page is skipped. Once a form has a section, every top-level field is one, so a new sectioned form is best authored in one add_fields call (the sections first, with predeclared fieldUuids; each question with parentUuid naming its section), and an existing form is re-paged with set_form_sections rather than a run of move_field calls, which the commit gate would refuse half-way. A worker-added repeat cannot sit on a page; fixed-count and case-query repeats can.

Saving a field answer to a case

Every case-writing field carries one complete caseWrite destination. The field's id remains its friendly form-local name, including in human XPath such as #form/first_name; it does not need to match the saved property:

{
  "app_id": "app-id",
  "moduleUuid": "01890f45-0000-7000-8000-000000000001",
  "formUuid": "01890f45-0000-7000-8000-000000000002",
  "fields": [
    {
      "id": "first_name",
      "kind": "text",
      "caseWrite": {
        "caseType": "patient",
        "property": "given_name"
      }
    }
  ]
}

The same field shape is used inside create_form and create_module. On creation, omit caseWrite or pass null for a field that should not save to a case. In edit_field.updates, pass a complete pair to retarget the writer, pass null to stop writing a case property, or leave caseWrite out to keep it. Changing id never renames saved case data.

An attachment field (image, audio, video, signature, file) saves to a case too, and its caseWrite carries one extra member naming what reaches the case:

{
  "id": "site_photo",
  "kind": "image",
  "caseWrite": {
    "caseType": "patient",
    "property": "photo_url",
    "mode": "url"
  }
}

mode is required on those five kinds and refused on every other kind. "url" saves a link to the captured file, built from the CommCare project space the app is published to; an artifact compiled before the app reaches one omits the property and compile_app says so in its advisories. An attachment may not write case_name or external_id.

A field can also save to the worker's own record instead of a case, by passing caseType: "commcare-user" and a property that is one of the app's declared worker property slugs (get_users lists them):

{
  "id": "visits_so_far",
  "kind": "text",
  "caseWrite": { "caseType": "commcare-user", "property": "visits_done" }
}

This works on any form, including a survey with no case type of its own, and the value reads back as #user/visits_done. Three destinations are refused, each for a reason the refusal names: a slug no worker property declares, a built-in worker field (username, first_name, last_name, language, phone_number, hq_user_id, case_name, and the commcare_* keys), which Commcare Nova keeps in step with the worker's profile, and any field inside a repeat, since one form writes one worker record. Adding a worker property is add_user_properties.

Custom property names remain open. The two standard scalar destinations a field may use are case_name and external_id; other reserved system names are refused. These scalars store text: use a text field for an entered answer or a hidden calculated field for a computed value. Commcare Nova trims only boundary characters U+0000 through U+0020 and limits the result to 255 UTF-16 units. A blank case name is invalid. An active blank external ID clears it, while an omitted or irrelevant writer leaves the existing external ID unchanged.

Renaming case properties

rename_case_properties takes the complete nonempty relation for one app-wide change:

{
  "app_id": "app-id",
  "renames": [
    {
      "caseType": "patient",
      "from": "phone",
      "to": "primary_phone"
    },
    {
      "caseType": "patient",
      "from": "primary_phone",
      "to": "phone"
    }
  ]
}

All entries happen simultaneously, so the example is a swap rather than two overwrites. Chains and cycles are also valid. Each source and destination must be unique within its case type; merges, self-renames, temporary-property sequences, and overwriting an occupied destination are refused with nothing saved. Case properties are the intentional name-keyed exception to Commcare Nova's UUID object addresses, so each entry uses the exact (caseType, from, to) names, never a form id, field path, field UUID, or slug.

On success, the result returns the exact renames relation and a grouped document impact:

{
  "message": "Renamed 2 case properties across 6 document occurrences in 5 carriers as one simultaneous app-wide change.",
  "renames": [
    {
      "caseType": "patient",
      "from": "phone",
      "to": "primary_phone"
    },
    {
      "caseType": "patient",
      "from": "primary_phone",
      "to": "phone"
    }
  ],
  "impact": {
    "totalOccurrences": 6,
    "totalCarriers": 5,
    "groups": [
      { "key": "field-writers", "occurrences": 2, "carriers": 2 },
      { "key": "case-operation-writes", "occurrences": 1, "carriers": 1 },
      { "key": "typed-reads", "occurrences": 1, "carriers": 1 },
      { "key": "catalog-declarations", "occurrences": 2, "carriers": 2 }
    ],
    "byRename": [
      {
        "caseType": "patient",
        "from": "phone",
        "to": "primary_phone",
        "occurrences": 3
      },
      {
        "caseType": "patient",
        "from": "primary_phone",
        "to": "phone",
        "occurrences": 3
      }
    ]
  }
}

Working with media

You can attach images, audio, and video to parts of an app, a field's label or hint, a dropdown choice, a module or form menu tile, or the app logo. First upload the files, then attach them by their asset id. Every attach checks the asset before anything saves: it must be in your library, fully uploaded, and the right type for the slot (an audio file can't become a menu icon), and the app's total attached media must stay within the export limit. A bad id fails the call with a message saying what to fix, and nothing is saved.

Publishing

System reminders

A few read results (get_app, get_field) may include a <system_reminder> block. It carries background context for the calling agent, for example, a case property the app reads that no form in it writes, whose values therefore come from outside the app (another app on the same case type, an integration, or sample cases created for testing). A reminder is informational, never an error: nothing needs fixing, and it isn't meant to be relayed to end users.