> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/projects/use-cases/omnistudio-experiences/omniscript-card-picker.md).

# Build a Salesforce OmniScript Card Picker with Avonni Visual Picker

Build an OmniScript plan picker that restores valid choices, blocks ineligible plans and shows server-verified prices.

Select an eligible insurance plan in OmniScript, preserve a valid choice when navigating back, and show a premium verified by an Integration Procedure.

![Northfield Mutual OmniScript displaying two qualified plan cards, with Condo selected and the Next button ready](https://3857391697-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdHOej9Pd5IxJNGEJMZKW%2Fuploads%2FO9qI8SOLNRyGSNtUIWjV%2Fomniscript-project-cover.jpg?alt=media)

{% embed url="<https://youtu.be/McExPJ6lMq0>" %}

### Build the project

Choose how you want to build:

✨ **Build with AI** — Give your AI assistant a ready-to-use prompt.

🛠️ **Build it** — Follow the steps yourself.

{% tabs %}
{% tab title="Build with AI" icon="wand-magic-sparkles" %}
{% stepper %}
{% step %}

#### Prepare the assistant and sandbox

Follow [Build with AI](https://docs.avonnicomponents.com/build-with-ai). Connect the Avonni MCP and install the `avonni-lwc-components` skill. Use a disposable Salesforce org with OmniStudio standard runtime, Avonni LWC Components, Salesforce CLI, and the OmniStudioAdmin and OmniStudioUser permission sets. Clone the [companion repository](https://github.com/cedv17/salesforce-omniscript-avonni-card-picker) and give the assistant its fixtures, server tests and native OmniScript metadata schemas. Keep the AI component and OmniScript subtype separate from the manual example.
{% endstep %}

{% step %}

#### Copy the build prompt

{% code title="OmniScript card picker prompt" collapsedlinecount="10" %}

```
Build an OmniScript plan picker for the fictional insurer Northfield Mutual using Avonni Visual Picker in a standalone custom LWC. Use the avonni-lwc-components skill and live Avonni MCP documentation. Inspect my sandbox, confirm the package and OmniStudio standard runtime, and show your plan and org alias before writing or deploying anything.

Use the supplied catalog Integration Procedure and fixtures. One active rate rule makes one card, keyed productId|ruleKey. Show its plan, annual USD price and conditions. Qualified lists eligible plans; All also shows ineligible plans as disabled cards with reasons. Preserve a valid selection on Previous, but clear and publish it when property answers make it ineligible. Support keyboard use and a narrow container.

Use the tested standalone OmniScript contract: accept catalog and initialChoice, emit omniaggregate for ChoosePlan.PlanPicker.choice with filter, selection and valid, and set bStandalone:true in the Custom LWC property. Native Messaging Requirements block Next when no valid choice exists. Pass only the choice key and property answers to the validation Integration Procedure. Review must show the server-returned price, never the browser's price. Use a separate component name and OmniScript subtype; do not invent an OmniscriptBaseMixin dependency.

Deploy only to the agreed demo org. Test 1996 owner-occupied (two Qualified and four All), empty Next blocked, Condo reviewed at $1,240, Previous restoring selection, 1975 clearing and blocking the old choice, and House reviewed at $1,680 after restoring 1996. Run the supplied server tests, then report the actual Salesforce runtime results and any failures.
```

{% endcode %}

The filmed AI build and its exact prompt are also in [BUILD-PROMPT.md](https://github.com/cedv17/salesforce-omniscript-avonni-card-picker/blob/main/BUILD-PROMPT.md). Use the prompt above with the same supplied fixtures and review the generated code before deployment.
{% endstep %}

{% step %}

#### Verify the generated path

Deploy the generated component and its separate OmniScript to the demo org. Open the AI selection app, perform the [Try it](#try-it) checks, and verify the returned premium in Salesforce. A successful deploy or local unit test alone does not prove the OmniScript return trip.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Build it" icon="screwdriver-wrench" %}
{% stepper %}
{% step %}

#### Deploy the companion example

Use a disposable Salesforce org with OmniStudio standard runtime and Designer, Avonni LWC Components, Salesforce CLI, and the OmniStudioAdmin and OmniStudioUser permission sets. Clone the [companion repository](https://github.com/cedv17/salesforce-omniscript-avonni-card-picker), authenticate the org, and replace `<demo-org>` with its alias:

{% code collapsedlinecount="10" %}

```sh
cd component
sf project deploy start --source-dir force-app --target-org <demo-org>
cd ../org
sf project deploy start --source-dir force-app --target-org <demo-org>
sf org assign permset --name Northfield_Tutorial --target-org <demo-org>
sf org assign permset --name OmniStudioAdmin --target-org <demo-org>
sf org assign permset --name OmniStudioUser --target-org <demo-org>
```

{% endcode %}

Open **Northfield Mutual → Northfield Plan Selection**. The OmniScript is `Northfield / CardPickerFinal / English`.
{% endstep %}

{% step %}

#### Trace the data contract

The PropertyDetails step collects `ownerOccupied` and `yearBuilt`. `Northfield_PlanCatalogLive` returns the catalog. The standalone Custom LWC receives `catalog` and `initial-choice`, renders [Visual Picker](https://docs.avonnicomponents.com/lwc-components/core-components/visual-picker), and publishes `ChoosePlan.PlanPicker.choice` with `filter`, `selection` and `valid` through `omniaggregate`. The native Custom LWC property is `bStandalone: true`.

A native Messaging Requirement guards Next using `choice.valid`. Before ReviewPlan, `Northfield_ValidateSelection` receives only the selected key and property answers. ReviewPlan reads the server response, including its price, and has its own requirement for an invalid response. The [companion README](https://github.com/cedv17/salesforce-omniscript-avonni-card-picker#readme) explains each mapping.
{% endstep %}

{% step %}

#### Run the checks

From the companion repository root:

{% code collapsedlinecount="10" %}

```sh
node --test tests/planOptions.test.mjs
python3 tests/validate_ip.py --target-org <demo-org>
```

{% endcode %}

Then run [Try it](#try-it) in Salesforce. The server test includes a client-supplied price of $1: an eligible Condo must still return $1,240 from the server.
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

### Try it

1. Enter **owner-occupied** and **1996**. Qualified shows two cards; All shows four, including two disabled cards with reasons.
2. Leave the plan empty and click **Next**. The OmniScript stays on Choose a plan and explains the missing choice.
3. Select **Condo** and click **Next**. Review shows the server-verified annual premium of **$1,240**. Click **Previous**; Condo remains selected.
4. Go back to property details and change the year to **1975**. The old selection clears, Qualified has no offers, All explains the unmet rules, and Next stays blocked.
5. Restore **1996**, choose **House**, and continue. Review shows the server-verified annual premium of **$1,680**.
6. Select with the keyboard and narrow the container. Disabled cards are skipped and the cards fit without horizontal overflow.

**Verified runtime.** These checks passed in a Salesforce demo org using OmniStudio standard runtime and a sandbox admin account. Northfield Mutual and its rates are fictional demo fixtures.

### Why Avonni here?

Visual Picker supplies the selectable cards, selection state, responsive layout and disabled treatment. The custom LWC handles eligibility and OmniScript state; native OmniScript requirements control navigation; the Integration Procedure is the authority for price. With the Avonni MCP and LWC skill, the AI path can use the documented component API instead of generating a second card widget from scratch.

### References

* [Visual Picker component](https://docs.avonnicomponents.com/lwc-components/core-components/visual-picker)
* [Complete source and deployment guide](https://github.com/cedv17/salesforce-omniscript-avonni-card-picker)
* [Avonni LWC Components](https://www.avonni.app/product/lwc-components)
* [Avonni Agent Skills setup](https://www.avonni.app/product/agent-skills-setup)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.avonnicomponents.com/projects/use-cases/omnistudio-experiences/omniscript-card-picker.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
