Spaces:
Sleeping
Sleeping
File size: 214,063 Bytes
c1367c2 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 |
[
{
"user_input":"Howw doo I use the Shopify CLI to createe a neww extensionn for Shopify Floww actions?",
"retrieved_contexts":[
"A test app that works with the test web server\n\nA development store that has [Shopify Flow](https:\/\/apps.shopify.com\/flow) and the test app installed\n\n## Step 1: Create a Flow Action\n\nTo give your Flow action a meaningful name, use the following guidelines:\n\nUse a present\n\ntense verb + object acted on format. For example, `Place auction bid`.\n\nUse sentence case.\n\nDon't use punctuation.\n\nSeparate words using spaces.\n\n### Using Shopify CLI\n\nUse the Shopify CLI to generate a new extension:\n\n1. Navigate to your app directory. 2. Run the following command:\n\n```bash\n\n#!\/bin\/bash\n\nshopify app generate extension\n\n```\n\n3. Select the `Flow Action` as the type of extension. 4. Provide a meaningful name for your extension.\n\nAfter you've followed the prompts, Shopify CLI generates the extension\u2019s file representation in your app's `\/extensions` directory and gives you a success message. You can then go into your app's `\/extensions` directory and start editing your new extension.",
"Don't use punctuation.\n\nSeparate words using spaces.\n\n### Using Shopify CLI\n\nThe following steps show how to create a trigger that sends bid information to Shopify Flow when a bid is placed on an auction.\n\nUse the Shopify CLI to generate a new extension:\n\n1. Navigate to your app directory. 2. Run the following command:\n\n```bash\n\n#!\/bin\/bash\n\nshopify app generate extension\n\n```\n\n3. Select the `Flow Trigger` as the type of extension. 4. Provide a meaningful name for your extension.\n\nAfter you've followed the prompts, Shopify CLI generates the extension\u2019s file representation in your app's `\/extensions` directory and gives you a success message. You can then go into your app's `\/extensions` directory and start editing your new extension.\n\nThe file structure of your extension should look like the following:\n\n```\n\n\/auction\n\nbid\n\nplaced\n\nshopify.extension.toml\n\n```",
"1. Navigate to your app directory. 2. Run the following command:\n\n```bash\n\n#!\/bin\/bash\n\nshopify app generate extension\n\n```\n\n3. Select the `Flow Action` as the type of extension. 4. Provide a meaningful name for your extension.\n\nAfter you've followed the prompts, Shopify CLI generates the extension\u2019s file representation in your app's `\/extensions` directory and gives you a success message. You can then go into your app's `\/extensions` directory and start editing your new extension.\n\nThe file structure of your extension should look like the following:\n\n```\n\n\/place\n\nauction\n\nbid\n\nshopify.extension.toml\n\n```\n\nTo learn more about the extensions file structure, refer to [App structure](\/docs\/apps\/build\/cli-for-apps\/app-structure) and the documentation for your extension type.\n\n### Using the Partner Dashboard",
"```\n\n3. Select the `Flow Trigger` as the type of extension. 4. Provide a meaningful name for your extension.\n\nAfter you've followed the prompts, Shopify CLI generates the extension\u2019s file representation in your app's `\/extensions` directory and gives you a success message. You can then go into your app's `\/extensions` directory and start editing your new extension.\n\nThe file structure of your extension should look like the following:\n\n```\n\n\/auction\n\nbid\n\nplaced\n\nshopify.extension.toml\n\n```\n\nTo learn more about the extensions file structure, refer to [App structure](\/docs\/apps\/build\/cli-for-apps\/app-structure) and the documentation for your extension type.\n\n### Using the Partner Dashboard",
"When you create a new trigger extension using Shopify CLI, a basic version of the TOML configuration file structure is generated. In this guide, you'll learn about configuring the different sections and properties of the configuration file, including extension properties, extension fields, reference field types, custom field types, and more.\n\nThis guide will also inform you how to make HTTP requests to Flow to start the workflows in which your extension is the trigger.\n\n## TOML\n\n> Note: > Creating Flow extensions using Shopify CLI is an exciting new feature that is currently in development. As with any developing feature, it's important to note that the Flow's CLI capabilities will continue to evolve and improve over time. Developers can expect additional functionality, enhancements, and improvements to be added as development progresses. > >To create Flow extensions using [Shopify CLI](https:\/\/www.npmjs.com\/package\/@shopify\/cli), ensure you have the latest version installed."
],
"reference_contexts":[
"To create an action that merchants can use in their workflows, you need to add the action to your app. The action needs to contain the following information: The fields that the merchant needs to complete when they add the action to their workflows The URL that Shopify Flow uses to send (POST) the contents (JSON payload) of the action to your app You also need to configure your app to process the data from the POST request when it arrives and to send status codes back to Shopify Flow. To enhance the merchant experience and more closely integrate external systems, you can also [build a custom configuration page](\/docs\/apps\/build\/flow\/actions\/build-config-ui). To improve the reliability of your action, you can add [custom validation](\/docs\/apps\/build\/flow\/actions\/endpoints#custom-validation) for action properties. ## Requirements You have the following: A test web server that has access to the Internet, so that it can receive POST requests from Shopify Flow A test app that works with the test web server A development store that has [Shopify Flow](https:\/\/apps.shopify.com\/flow) and the test app installed ## Step 1: Create a Flow Action To give your Flow action a meaningful name, use the following guidelines: Use a present tense verb + object acted on format. For example, `Place auction bid`. Use sentence case. Don't use punctuation. Separate words using spaces. ### Using Shopify CLI Use the Shopify CLI to generate a new extension: 1. Navigate to your app directory. 2. Run the following command: ```bash #!\/bin\/bash shopify app generate extension ``` 3. Select the `Flow Action` as the type of extension. 4. Provide a meaningful name for your extension. After you've followed the prompts, Shopify CLI generates the extension\u2019s file representation in your app's `\/extensions` directory and gives you a success message. You can then go into your app's `\/extensions` directory and start editing your new extension. The file structure of your extension should look like the following: ``` \/place auction bid shopify.extension.toml ``` To learn more about the extensions file structure, refer to [App structure](\/docs\/apps\/build\/cli-for-apps\/app-structure) and the documentation for your extension type. ### Using the Partner Dashboard 1. In your Partner Dashboard, click [Apps](https:\/\/partners.shopify.com\/current\/apps). 2. Select the app that you want to add your Shopify Flow action to. 3. Click **Extensions**, then click **Create** or **Create extension**. 4. Under the **Flow** tab, click **Flow\/Actions**. 5. In the **Extension name** field, name your action, such as `Place auction bid`. This name is used only for internal purposes. 6. Enter a title and description for the action. In the **Action Preview** area, you can see how the title and action display to merchants when they're choosing actions in Shopify Flow. 7. Enter the URL for the action execution endpoint that you created. Shopify Flow sends the action's JSON payload to this endpoint when it's about to execute your action. ## Step 2: Customize a Flow action configuration file In this section you'll use the default action template and update it to be a functional extension example. Once you have generated a Flow extension using Shopify CLI, follow the instructions below: 1. Change the description to `Place a bid on an auction`. 2. Update the `extensions.runtime_url` to an endpoint where you can receive the runtime request. 3. On the second `settings.fields` field, update the following values: - `type` to `number_decimal` - `key` to `amount` - `name` to `Bid Amount` - Add a `description` property and set it to `The amount of the bid` ```bash [[extensions]] name = \"Place Auction Bid\" type = \"flow_action\" handle = \"place-bid\" description = \"Place a bid on an auction\" runtime_url = \"https:\/\/your-server-domain\/path\/to\/action\/handler\" [settings] [[settings.fields]] type = \"customer_reference\" required = true [[settings.fields]] type = \"number_decimal\" key = \"amount\" name = \"Bid Amount\" description = \"The amount of the bid\" required = true ``` ##"
],
"response":"To create a new extension for Shopify Flow actions using Shopify CLI, here\u2019s a simplified step-by-step guide you can follow:\n\n1. **Prepare Your Development Environment**:\n - Make sure you have a development store that has Shopify Flow and your test app installed. This will be necessary for testing your new extension.\n - Ensure Shopify CLI is installed in your machine. If it's not, you'll need to install it. Since Shopify CLI updates regularly, make sure you have the latest version to use all the newest features.\n\n2. **Navigate to Your App Directory**: \n - Open your terminal or command prompt.\n - Use the command line to navigate to your app\u2019s directory\/folder.\n\n3. **Generate a New Extension**:\n - In your terminal, while you are in your app directory, run the command:\n\n ```bash\n shopify app generate extension\n ```\n - This command starts the process to create a new extension in your app.\n\n4. **Choose the Type of Extension**:\n - You will be prompted to select the type of extension you want to create. Select `Flow Action` if you intend to create an action for Shopify Flow, or `Flow Trigger` if you're aiming to trigger a workflow.\n\n5. **Name Your Extension**:\n - Provide a meaningful name following the guidelines (use present tense verb + object acted on, sentence case, no punctuation, and separate words using spaces). For example, `Place auction bid` for a Flow action.\n\n6. **Edit Your New Extension**:\n - After you've followed the prompts, the Shopify CLI will generate your extension and place it in the `\/extensions` directory of your app. You\u2019ll get a success message once it's done.\n - Find your new extension in the `\/extensions` directory and start editing according to your needs. Each extension will have its `shopify.extension.toml` configuration file among others, which you can configure as needed.\n\n7. **Learn About Extensions File Structure**:\n - To understand how to organize and configure your extension effectively, refer to additional documentation on app structure and your specific extension type mentioned in the Shopify CLI or Shopify Developers documentation.\n\nRemember, the goal of these steps is to set up your extension's basic structure, which you can then further develop and tailor to meet your specific requirements for Shopify Flow actions or triggers. This guide uses straightforward, non-technical language to make the process accessible, even if you're new to Shopify CLI or extension development.",
"reference":"To use the Shopify CLI to generate a new extension for Shopify Flow actions, follow these steps: 1. Navigate to your app directory. 2. Run the command `shopify app generate extension`. 3. Select `Flow Action` as the type of extension. 4. Provide a meaningful name for your extension. After completing these steps, Shopify CLI generates the extension\u2019s file representation in your app's `\/extensions` directory and provides a success message. You can then start editing your new extension in the `\/extensions` directory."
},
{
"user_input":"How do you configure a web server to handle Shopify Flow actions?",
"retrieved_contexts":[
"```bash [[extensions]] name = \"Place Auction Bid\" type = \"flow_action\" handle = \"place-bid\" description = \"Place a bid on an auction\" runtime_url = \"https:\/\/your-server-domain\/path\/to\/action\/handler\"\n\n[settings]\n\n[[settings.fields]]\n\ntype = \"customer_reference\"\n\nrequired = true\n\n[[settings.fields]] type = \"number_decimal\" key = \"amount\" name = \"Bid Amount\" description = \"The amount of the bid\" required = true ```\n\n## Step 3: Configure your web server\n\nTo build a Shopify Flow action, you need to add a service to your web server to listen for the JSON payload that Shopify Flow sends when the action runs.\n\nOptionally, you can also add the following:\n\nAn endpoint to validate actions\n\nA [custom configuration page](\/docs\/apps\/build\/flow\/actions\/build\n\nconfig\n\nui), and an endpoint that lets merchants preview your custom configuration page\n\nAdd the following API endpoints to your server:",
"## 1. Configure your web server\n\nTo begin, configure your web server to listen for Shopify Flow callbacks.\n\n1. Configure a URL in your web server to listen for the trigger lifecycle callbacks from Shopify Flow. 2. Configure your web server to verify the HMAC header in the trigger lifecycle callback with your client secret.\n\nThe HMAC header is located in the following HTTP header: `x-shopify-hmac-sha256`. If you are using a Ruby-based web framework, then the header is `http-x-shopify-hmac-sha256`.\n\n3. Configure your web server to respond within 5 seconds when it receives a trigger lifecycle callback.\n\n## 2. Process and store callback data\n\nAfter you've added support to listen for Shopify Flow callbacks, you can configure your web server to process and store the callback data.",
"To create an action that merchants can use in their workflows, you need to add the action to your app. The action needs to contain the following information:\n\nThe fields that the merchant needs to complete when they add the action to their workflows\n\nThe URL that Shopify Flow uses to send (POST) the contents (JSON payload) of the action to your app\n\nYou also need to configure your app to process the data from the POST request when it arrives and to send status codes back to Shopify Flow.\n\nTo enhance the merchant experience and more closely integrate external systems, you can also [build a custom configuration page](\/docs\/apps\/build\/flow\/actions\/build-config-ui). To improve the reliability of your action, you can add [custom validation](\/docs\/apps\/build\/flow\/actions\/endpoints#custom-validation) for action properties.\n\n## Requirements\n\nYou have the following:\n\nA test web server that has access to the Internet, so that it can receive POST requests from Shopify Flow",
"## Requirements\n\nMake sure that you have the following:\n\nA test web server that you can use to send information to Shopify Flow. You can use an existing web server. This web server needs to be able to send POST requests to Shopify's [GraphQL Admin API](\/docs\/api\/admin\n\ngraphql).\n\nA test app that works with the test web server and can send HTTP requests.\n\nA development store that has [Shopify Flow](https:\/\/apps.shopify.com\/flow) and the test app installed.\n\nYour application has access to the `read_customers` scope. The trigger you will build using this tutorial will be using a customer reference which requires that scope.\n\n## Step 1: Create a Flow trigger extension\n\nTo give your Flow action a meaningful name, use the following guidelines:\n\nUse an object acted on + past tense verb format. For example, `Auction bid placed`.\n\nUse sentence case.\n\nDon't use punctuation.\n\nSeparate words using spaces.\n\n### Using Shopify CLI",
"To enhance the merchant experience and more closely integrate external systems, you can also [build a custom configuration page](\/docs\/apps\/build\/flow\/actions\/build-config-ui). To improve the reliability of your action, you can add [custom validation](\/docs\/apps\/build\/flow\/actions\/endpoints#custom-validation) for action properties.\n\n## Requirements\n\nYou have the following:\n\nA test web server that has access to the Internet, so that it can receive POST requests from Shopify Flow\n\nA test app that works with the test web server\n\nA development store that has [Shopify Flow](https:\/\/apps.shopify.com\/flow) and the test app installed\n\n## Step 1: Create a Flow Action\n\nTo give your Flow action a meaningful name, use the following guidelines:\n\nUse a present\n\ntense verb + object acted on format. For example, `Place auction bid`.\n\nUse sentence case.\n\nDon't use punctuation.\n\nSeparate words using spaces.\n\n### Using Shopify CLI\n\nUse the Shopify CLI to generate a new extension:"
],
"reference_contexts":[
"Step 3: Configure your web server To build a Shopify Flow action, you need to add a service to your web server to listen for the JSON payload that Shopify Flow sends when the action runs. Optionally, you can also add the following: An endpoint to validate actions A [custom configuration page](\/docs\/apps\/build\/flow\/actions\/build config ui), and an endpoint that lets merchants preview your custom configuration page Add the following API endpoints to your server: | Endpoint | Purpose | | --- | --- | | [Flow action execution](\/docs\/apps\/flow\/actions\/endpoints#flow-action-execution) | The endpoint where the automation tool sends your action's payload. The payload contains data that you can use to execute the action in your app.| | [Custom configuration page preview](\/docs\/apps\/flow\/actions\/endpoints#custom-configuration-page-preview) | An endpoint that provides data about your [custom configuration page](\/docs\/apps\/build\/flow\/actions\/build-config-ui) to display in the automation tool. This endpoint is required if you want to use a custom configuration page.| | [Custom validation](\/docs\/apps\/flow\/actions\/endpoints#custom-validation) | An endpoint that validates the contents of merchant-configurable properties in an action payload when an action is saved. This endpoint is required if you want to use a custom configuration page.| To learn more about the endpoint requirements for your server, refer to [Action endpoints](\/docs\/apps\/build\/flow\/actions\/endpoints). To learn how to create a custom configuration page, refer to [Build a custom configuration page](\/docs\/apps\/build\/flow\/actions\/build-config-ui). ##"
],
"response":"To get your web server ready to work with Shopify Flow actions, here's a simple guide you can follow:\n\n1. **Set Up Your Web Server**: Your web server should be configured to accept incoming POST requests from Shopify Flow. This means setting up a specific URL (endpoint) on your server where Shopify Flow can send data. This is where you listen for Shopify Flow's JSON payloads that describe the actions to be performed.\n\n2. **Verify Requests**: For security, Shopify sends a special code with each request called an HMAC (Hash-Based Message Authentication Code) in the HTTP header `x-shopify-hmac-sha256`. Your server needs to check this code to make sure the request is really coming from Shopify. This involves a bit of coding to compare Shopify's HMAC with a hash you generate from the incoming request using your app's client secret.\n\n3. **Respond Quickly**: Your server must process the Shopify Flow request and respond within 5 seconds. If it takes longer, Shopify might think the request failed.\n\n4. **Handle the JSON Payload**: Your endpoint will receive data in JSON format. This data includes the action fields defined in your app, like `customer_reference` and `amount` for a bid. You'll need to extract these values from the JSON and use them in your server's logic to perform the action\u2014like placing a bid in an auction.\n\n5. **Reply to Shopify Flow**: After processing the request, you should send a response back to Shopify Flow. This usually includes HTTP status codes to indicate whether the action was successfully processed (e.g., `200 OK` for success).\n\n6. **Custom Configuration and Validation (Optional)**: If you want to offer merchants a way to configure your action specifically for their needs or validate action properties, you can create a custom configuration page and validation endpoints. This is more advanced and involves creating additional web pages and more complex server logic.\n\nTo summarize, you're setting up a specific spot on your server to listen for instructions from Shopify Flow, making sure those instructions are legitimate, acting on them quickly, and then letting Shopify Flow know the result. If you're not familiar with terms like \"JSON payload\" or \"HMAC verification,\" it may be helpful to work with a developer or use more detailed guides and examples provided by Shopify or web development resources.",
"reference":"To configure a web server to handle Shopify Flow actions, you need to add a service to your web server to listen for the JSON payload that Shopify Flow sends when the action runs. Additionally, you can add an endpoint to validate actions, a custom configuration page, and an endpoint that lets merchants preview your custom configuration page. The necessary API endpoints include: Flow action execution, Custom configuration page preview, and Custom validation."
},
{
"user_input":"How can I test an action created in the Partner Dashboard using Shopify Flow?",
"retrieved_contexts":[
"1. Navigate to your app directory. 2. Run the following command to start using draft versions of your extension(s):\n\n```bash\n\n#!\/bin\/bash\n\nshopify app dev\n\n```\n\n3. Follow the prompts.\n\n## Step 5: Test the action\n\nAfter you've created an action in the Partner Dashboard and added support for it in your web server, you can test the action in Shopify Flow on your development store.\n\n1. In your development store, create a [workflow](https:\/\/www.shopify.com\/admin\/apps\/flow) that uses the action. For example, add the trigger that you created in the [Triggers guide](\/docs\/apps\/build\/flow\/triggers\/create) and this action to a workflow.\n\n2. If you created a custom configuration page, then ensure that the preview displays and that the custom configuration page is accessible.\n\n3. If you added any custom validation, then ensure that it works as expected.\n\n4. Trigger the workflow. For example, in your web server, run the event that sends the trigger information to Shopify Flow.",
"shopify.extension.toml\n\n```\n\nTo learn more about the extensions file structure, refer to [App structure](\/docs\/apps\/build\/cli-for-apps\/app-structure) and the documentation for your extension type.\n\n### Using the Partner Dashboard\n\n1. In your Partner Dashboard, click [Apps](https:\/\/partners.shopify.com\/current\/apps). 2. Select the app that you want to add your Shopify Flow action to. 3. Click **Extensions**, then click **Create** or **Create extension**. 4. Under the **Flow** tab, click **Flow\/Actions**. 5. In the **Extension name** field, name your action, such as `Place auction bid`. This name is used only for internal purposes. 6. Enter a title and description for the action. In the **Action Preview** area, you can see how the title and action display to merchants when they're choosing actions in Shopify Flow. 7. Enter the URL for the action execution endpoint that you created. Shopify Flow sends the action's JSON payload to this endpoint when it's about to execute your action.",
"## How actions work\n\nAn action is a workflow component in Shopify Flow. It represents a task that's executed in a store or in an app when certain conditions are met. You can connect your app to Shopify Flow so that your app receives data when a workflow action runs.\n\nThis guide shows you how to add an action to your app so that merchants can use it in their workflows.\n\n! [A diagram that show how third party actions interface with Flow ](\/assets\/apps\/flow\/action_diagram.png)\n\n## Next steps\n\nFollow our step by step guide on [how to create and test a Flow action](\/docs\/apps\/build\/flow\/actions\/create).\n\nCheck out our action endpoint guide for more information on how to setup an [execution endpoint](\/docs\/apps\/build\/flow\/actions\/endpoints#flow\n\naction\n\nexecution), a [custom configuration page preview endpoint](\/docs\/apps\/build\/flow\/actions\/endpoints#custom\n\nconfiguration\n\npage\n\npreview) and [custom validation](\/docs\/apps\/build\/flow\/actions\/endpoints#custom\n\nvalidation).",
"Follow our step by step guide on [how to create and test a Flow action](\/docs\/apps\/build\/flow\/actions\/create).\n\nCheck out our action endpoint guide for more information on how to setup an [execution endpoint](\/docs\/apps\/build\/flow\/actions\/endpoints#flow\n\naction\n\nexecution), a [custom configuration page preview endpoint](\/docs\/apps\/build\/flow\/actions\/endpoints#custom\n\nconfiguration\n\npage\n\npreview) and [custom validation](\/docs\/apps\/build\/flow\/actions\/endpoints#custom\n\nvalidation).\n\nLearn more about how to [return complex data](\/docs\/apps\/build\/flow\/configure\n\ncomplex\n\ndata\n\ntypes) in a Flow action.\n\nInterested in building a custom configuration page? Follow this [guide](\/docs\/apps\/build\/flow\/actions\/build\n\nconfig\n\nui) to learn more.",
"### Using the Partner Dashboard\n\n1. Open your [Partner Dashboard](https:\/\/partners.shopify.com). 2. Click the app that you want to add your Shopify Flow trigger to. 3. Click **Extensions**, then click **Create** or **Create extension**. 4. Under **Flow**, click the **Flow\/Triggers** card. 5. Enter an internal extension name for your trigger and click **Save**. 6. Enter a title and description for the trigger that will be shown to merchants. 7. Copy the GraphQL endpoint that displays under the **Trigger description** field to a text file. Your app uses this endpoint to send your POST request to Shopify Flow. The endpoint follows the format `https:\/\/{shop}.myshopify.com\/admin\/api\/latest\/graphql.json`. 8. In the **Request body properties** section, click **Add property**, choose a data type, and create the properties that display in Shopify Flow when a merchant chooses your trigger.\n\n## Step 2: Customize a Flow trigger configuration file"
],
"reference_contexts":[
"Step 4: Enable the draft version of your action Running [`app dev`](\/docs\/api\/shopify-cli\/app\/app-dev) allows changes made to local files to update the draft version of your Flow task extensions. The draft version is only available in your development store. > Note: > When [`app dev`](\/docs\/api\/shopify-cli\/app\/app-dev) is running and \"Development store preview\" is enabled, the draft version of a task will appear in your development store _in place_ of the deployed version. Other shops will continue to see the deployed version of your task (if one exists). Draft versions can be identified by the \"draft\" badge. To see the deployed version of the task in your development store, turn off \"Development store preview\" in the \"Extensions\" section of your app in [Shopify Partners](https:\/\/partners.shopify.com\/). 1. Navigate to your app directory. 2. Run the following command to start using draft versions of your extension(s): ```bash #!\/bin\/bash shopify app dev ``` 3. Follow the prompts. ## Step 5: Test the action After you've created an action in the Partner Dashboard and added support for it in your web server, you can test the action in Shopify Flow on your development store. 1. In your development store, create a [workflow](https:\/\/www.shopify.com\/admin\/apps\/flow) that uses the action. For example, add the trigger that you created in the [Triggers guide](\/docs\/apps\/build\/flow\/triggers\/create) and this action to a workflow. 2. If you created a custom configuration page, then ensure that the preview displays and that the custom configuration page is accessible. 3. If you added any custom validation, then ensure that it works as expected. 4. Trigger the workflow. For example, in your web server, run the event that sends the trigger information to Shopify Flow. When the workflow completes, your web server has sent data to Shopify Flow because of the trigger. Shopify Flow has sent this data to a web server that logged the information to its console because of the action. ## Step 6: Deploy your extension > Note: > Deploying extensions using the `app deploy` command also publishes the extensions. We recommend testing changes by using [`app dev`](\/docs\/api\/shopify-cli\/app\/app-dev) or deploying to a test app before deploying them to a production app. Use Shopify CLI to deploy your extensions: 1. Navigate to your app directory. 2. Run the following command to start deploying your extension(s): ```bash #!\/bin\/bash shopify app deploy ``` 3. Follow the prompts. When you receive confirmation that the deploy was successful, your extensions have been released. ## Verifying requests For security reasons, make sure that you verify the following elements in each request: The POST request's HMAC header (either `x shopify hmac sha256` or `http x shopify hmac sha256`). The HMAC header should be verified before you process the payload. For more information, refer to [Verifying requests](\/docs\/apps\/build\/flow\/actions\/endpoints#verifying requests). The payload `handle`. This ID should match the `handle` of the action that you created, and can be retrieved from the payload preview. ## Next steps Connect your app to Shopify Flow so that events that occur in your app can [trigger workflows](\/docs\/apps\/build\/flow\/triggers). Learn how to receive [lifecycle events from Shopify Flow](\/docs\/apps\/build\/flow\/track lifecycle events) about the stores that are using your triggers in enabled workflows. Learn more about how to [return complex data](\/docs\/apps\/build\/flow\/configure complex data types) in a Flow action."
],
"response":"To test an action you've created in the Partner Dashboard using Shopify Flow, follow these steps:\n\n1. **Start Your Environment**: Open your app directory and run `shopify app dev` in your command line. This prepares your development environment for testing.\n\n2. **Create a Workflow in Shopify Flow**: Go to your development store's Shopify admin, then navigate to the Flow app. Here, create a new workflow that includes the action you developed. Start by picking a trigger (an event that starts the workflow) that matches the one you designed in the Triggers guide.\n\n3. **Check Custom Configuration (If Applicable)**: If your action has a custom configuration page, ensure that this page is showing up correctly and is accessible within the workflow.\n\n4. **Verify Custom Validation**: If you added any custom validation (rules to make sure the input or actions are correct) to your action, test these to confirm they behave as expected.\n\n5. **Trigger the Workflow**: Finally, to see your action in action, you'll need to trigger the workflow. This usually means performing the action in your web server that mimics the event which starts the workflow. For example, if your trigger is \"Order Created,\" you would simulate an order being created which should then trigger your custom Shopify Flow action.\n\nRemember, all these steps are part of a development process, meant to be done in a testing or development environment, not in your live store. This way, you can ensure everything works perfectly before launching your action to actual users.",
"reference":"After you've created an action in the Partner Dashboard and added support for it in your web server, you can test the action in Shopify Flow on your development store. First, create a workflow in your development store that uses the action. Ensure that any custom configuration page displays correctly and that custom validation works as expected. Then, trigger the workflow by running the event in your web server that sends the trigger information to Shopify Flow. When the workflow completes, your web server will have sent data to Shopify Flow because of the trigger, and Shopify Flow will have sent this data to a web server that logged the information to its console because of the action."
},
{
"user_input":"how do you use toml when making new trigger extensions with shopify cli and what are the important parts to configure?",
"retrieved_contexts":[
"When you create a new trigger extension using Shopify CLI, you'll get a basic version of the TOML configuration file structure which should look like the following example:\n\n```bash\n\n[[extensions]]\n\nname = \"Auction Bid\"\n\ntype = \"flow_trigger\"\n\nhandle = \"auction\n\nbid\"\n\ndescription = \"Your description\"\n\n[settings]\n\n[[settings.fields]]\n\ntype = \"customer_reference\"\n\n[[settings.fields]] type = \"single_line_text_field\" key = \"your field key\" ```\n\n### Trigger extension properties\n\nExtension properties are listed in the `[[extensions]]` section and enable you to define the interface between Flow and your event.",
"When you create a new trigger extension using Shopify CLI, a basic version of the TOML configuration file structure is generated. In this guide, you'll learn about configuring the different sections and properties of the configuration file, including extension properties, extension fields, reference field types, custom field types, and more.\n\nThis guide will also inform you how to make HTTP requests to Flow to start the workflows in which your extension is the trigger.\n\n## TOML\n\n> Note: > Creating Flow extensions using Shopify CLI is an exciting new feature that is currently in development. As with any developing feature, it's important to note that the Flow's CLI capabilities will continue to evolve and improve over time. Developers can expect additional functionality, enhancements, and improvements to be added as development progresses. > >To create Flow extensions using [Shopify CLI](https:\/\/www.npmjs.com\/package\/@shopify\/cli), ensure you have the latest version installed.",
"### Folder structure\n\n```\n\n\/my\n\nextension\n\nname\n\nshopify.extensions.toml\n\nschema.graphql\n\n```\n\n### `shopify.extension.toml` file\n\n```bash [[extensions]] name = \"Place auction bid\" type = \"flow_action\" handle = \"auction-bid\" description = \"My description\" runtime_url = \"https:\/\/{url}.com\/api\/execute\" schema = \".\/schema.graphql\" return_type_ref = \"Auction\" ```\n\n## Referencing the return type schema in an action extension's TOML\n\nAfter a schema file has been defined, it can be referenced in the action extension's TOML by setting `extensions.schema` to the relative path of the schema file, and `extension.return_type_ref` to a type defined in the referenced schema file. The schema defined above can be referenced by setting the following fields:\n\n| Property Name | Property value | | ------------------- | --------------- | | `extensions.schema` | .\/schema.graphql | | `extensions.return_type_ref` | Auction |\n\n## Referencing the return type schema in a trigger extension's TOML",
"```\n\n3. Select the `Flow Trigger` as the type of extension. 4. Provide a meaningful name for your extension.\n\nAfter you've followed the prompts, Shopify CLI generates the extension\u2019s file representation in your app's `\/extensions` directory and gives you a success message. You can then go into your app's `\/extensions` directory and start editing your new extension.\n\nThe file structure of your extension should look like the following:\n\n```\n\n\/auction\n\nbid\n\nplaced\n\nshopify.extension.toml\n\n```\n\nTo learn more about the extensions file structure, refer to [App structure](\/docs\/apps\/build\/cli-for-apps\/app-structure) and the documentation for your extension type.\n\n### Using the Partner Dashboard",
"This guide provides explanations of key topics for building and deploying a Flow template extension. This includes the TOML configuration file, localization, and the template approval process.\n\n## TOML\n\nWhen you first create a new Flow template extensions through Shopify CLI, you get a basic version of the `shopify.extension.toml` file structure that looks like the following example:\n\n```toml\n\n[[extensions]]\n\nname = \"t:name\"\n\ntype = \"flow_template\"\n\nhandle = \"example\n\nname\"\n\ndescription = \"t:description\"\n\n[extensions.template]\n\ncategories = [\"orders\", \"risk\"]\n\nmodule = \".\/template.flow\"\n\nrequire_app = false\n\ndiscoverable = true\n\nenabled = true\n\n```\n\n### Flow template extension fields"
],
"reference_contexts":[
"When you create a new trigger extension using Shopify CLI, a basic version of the TOML configuration file structure is generated. In this guide, you'll learn about configuring the different sections and properties of the configuration file, including extension properties, extension fields, reference field types, custom field types, and more. This guide will also inform you how to make HTTP requests to Flow to start the workflows in which your extension is the trigger. ## TOML > Note: > Creating Flow extensions using Shopify CLI is an exciting new feature that is currently in development. As with any developing feature, it's important to note that the Flow's CLI capabilities will continue to evolve and improve over time. Developers can expect additional functionality, enhancements, and improvements to be added as development progresses. > >To create Flow extensions using [Shopify CLI](https:\/\/www.npmjs.com\/package\/@shopify\/cli), ensure you have the latest version installed. When you create a new trigger extension using Shopify CLI, you'll get a basic version of the TOML configuration file structure which should look like the following example: ```bash [[extensions]] name = \"Auction Bid\" type = \"flow_trigger\" handle = \"auction bid\" description = \"Your description\" [settings] [[settings.fields]] type = \"customer_reference\" [[settings.fields]] type = \"single_line_text_field\" key = \"your field key\" ``` ### Trigger extension properties Extension properties are listed in the `[[extensions]]` section and enable you to define the interface between Flow and your event. | Property name | Description | Rules | | --------------------------- | ------------------------------------------------------------- | -------------------------------------- | | `name` <br><span class=\"heading-flag\">Required<\/span> | Name of your extension. Will be the merchant-facing name of your task in the editor. This should be something that is human readable. | | | `type` <br><span class=\"heading-flag\">Required<\/span> | The type of your extension. This should always be set to \u201cflow_trigger\u201d for Flow triggers. | - Value must be `flow_trigger`. | `handle` <br><span class=\"heading-flag\">Required<\/span> | A unique identifier for your extension. This property cannot be changed once you\u2019ve run the `dev` or `deploy` command. | - Cannot exceed 30 characters.<br \/> - Must be unique across your app's extensions. <br \/> - Must only contain alphanumeric characters and hyphens. | | `description` <br><span class=\"heading-flag\">Optional<\/span> | A description of your extension. This description will be shown in the Flow editor navigation panel. | | ### Trigger extension fields Trigger extension fields are listed in the `[settings]` section, with each field using a `[[settings.field]]` header. These fields define the payload your event will send to Flow. You can add more than one field to your Flow trigger. The order of the fields in the TOML file is preserved when they're being rendered in the editor configuration panel. When sending a trigger payload, all fields defined in a trigger are required. | Property name | Description | Rules | | ------------------------------ | --------------------------------------------------------------------------------------------------- | --------------------------------| | `type` <br><span class=\"heading-flag\">Required<\/span> | The field type. | - [Accepted custom field types](#custom-field-types).<br> - [Accepted reference field types](#reference-field-types). | | `key` <br><span class=\"heading-flag\">Optional<\/span> | A unique key that identifies your field. This should be human readable since it will appear in the Flow editor in the environment picker menu. | - Required for custom field types. <br \/> Should only contain alphabetic values or spaces. <br \/> - This property is not valid for reference field types. | | `description` <br><span class=\"heading-flag\">Required<\/span> | A description of the field. This will appear in the Flow editor configuration panel. | ###"
],
"response":"Using TOML with Shopify CLI for creating new trigger extensions involves configuring a `shopify.extension.toml` file that specifies how your extension will work. TOML stands for Tom's Obvious, Minimal Language, which is a configuration file format that's easy to read due to its clear semantics. Here's a straightforward breakdown of the important parts you need to configure:\n\n### Important Parts of the TOML Configuration:\n\n1. **`[[extensions]]` block:** This is where you define the basic information about your extension. It includes properties such as `name`, `type`, `handle`, and `description`. \n\n - `name`: The name of your extension.\n - `type`: The type of extension, like `flow_trigger` for trigger extensions or `flow_action` for action extensions.\n - `handle`: A unique identifier for your extension.\n - `description`: A brief description of what your extension does.\n\n2. **`[settings]` and `[[settings.fields]]` blocks:** These are for setting up the fields that users can interact with when they use your extension. You can define various types of fields, such as customer references or text fields, and set properties like `type` and `key` for those fields.\n\n - `type`: The type of field, which determines what kind of data it can hold. Examples include `customer_reference` for customer data or `single_line_text_field` for text.\n - `key`: A unique identifier for the field which can be used in the extension's code to access the data entered by a user.\n\n3. **`runtime_url`** (for action extensions): Specifies the URL where your extension's logic is hosted. This is where Shopify sends a request when the extension is triggered.\n\n4. **`schema` and `return_type_ref`** (for action extensions): If your extension acts upon data, these fields tell Shopify how to understand the data your extension handles. \n - `schema`: A relative path to a `.graphql` file that defines the data structures your extension uses or modifies.\n - `return_type_ref`: Specifies a type from your `.graphql` schema that the extension returns after execution.\n\n### Creating and Modifying the TOML File:\n\nWhen you initiate a new trigger extension using Shopify CLI, it automatically generates a basic `shopify.extension.toml` file in your project's `\/extensions` directory. To modify this file:\n\n1. Navigate to your project's `\/extensions` directory.\n2. Open the `shopify.extension.toml` file in your text editor.\n3. Edit the properties within the `[[extensions]]` block and add any necessary `settings` fields according to the needs of your extension.\n4. If you're working with an action extension, make sure to correctly set the `runtime_url`, `schema`, and `return_type_ref` properties.\n\nRemember, the key to effectively using TOML in Shopify CLI is to thoroughly configure these properties to accurately represent your extension's functionality, enabling smooth interaction between Shopify's Flow and your extension. These settings define how your extension appears to users within Shopify's Flow and dictate the data it can receive or send.",
"reference":"When you create a new trigger extension using Shopify CLI, a basic version of the TOML configuration file structure is generated. Important parts to configure include extension properties such as `name`, `type`, `handle`, and `description` in the `[[extensions]]` section, and trigger extension fields in the `[settings]` section, where each field uses a `[[settings.field]]` header. These fields define the payload your event will send to Flow, and all fields defined in a trigger are required when sending a trigger payload."
},
{
"user_input":"How do you use Shopify App Bridge to render a custom configuration page in Shopify Flow, and what are the requirements for setting up the necessary endpoints?",
"retrieved_contexts":[
"App Bridge components\n\nApp Bridge actions specific to the custom configuration page\n\n## Implementing a custom configuration page\n\nTo build a custom configuration page, you'll [use Shopify App Bridge to render a page from your app page in Shopify Flow](#use-shopify-app-bridge-to-render-your-app-page).\n\nFrom the context of the custom configuration page, you can then [access step and property information](#access-action-information) that you can use to display the appropriate information.\n\nYou can also [add additional buttons](#add-buttons-to-the-app-bridge-title-bar) to the App Bridge title bar, or [trigger a redirect to the previous page](#return-to-the-previous-page).\n\n## Use Shopify App Bridge to render your app page\n\n> Note: > The specifics of the Custom Configuration Page integration varies between Shopify App Bridge versions. Make sure you implement the integration specific to your Shopify App Bridge version.",
"In this tutorial, you'll learn how to render a custom configuration page in Shopify Flow, customize the page frame, and access data relevant to your action in the custom configuration page context.\n\n## Requirements\n\nYou've created a [Partner account](https:\/\/www.shopify.com\/partners).\n\nYou've [created an app](\/docs\/apps\/build\/scaffold\n\napp).\n\n## Resources\n\nTo implement this feature, you'll use the following:\n\n[Shopify App Bridge](\/docs\/api\/app\n\nbridge)\n\nApp Bridge components\n\nApp Bridge actions specific to the custom configuration page\n\n## Implementing a custom configuration page\n\nTo build a custom configuration page, you'll [use Shopify App Bridge to render a page from your app page in Shopify Flow](#use-shopify-app-bridge-to-render-your-app-page).\n\nFrom the context of the custom configuration page, you can then [access step and property information](#access-action-information) that you can use to display the appropriate information.",
"You can also [add additional buttons](#add-buttons-to-the-app-bridge-title-bar) to the App Bridge title bar, or [trigger a redirect to the previous page](#return-to-the-previous-page).\n\n## Use Shopify App Bridge to render your app page\n\n> Note: > The specifics of the Custom Configuration Page integration varies between Shopify App Bridge versions. Make sure you implement the integration specific to your Shopify App Bridge version.\n\nTo render your custom configuration page, you need to integrate Shopify App Bridge on the route that you want to render. To learn about setting up Shopify App Bridge, refer to one of the following pages:\n\n[Getting started with Shopify App Bridge](\/docs\/api\/app\n\nbridge\/previous\n\nversions\/app\n\nbridge\n\nfrom\n\nnpm\/app\n\nsetup)\n\n[Getting started with App Bridge React](\/docs\/api\/app\n\nbridge\n\nlibrary#react)\n\n### Access action information\n\nIn the context of the custom configuration page, Shopify Flow makes the following action information available:",
"<figure class=\"figure\"><img src=\"https:\/\/cdn.shopify.com\/shopifycloud\/shopify_dev\/assets\/apps\/flow\/ccp-preview-d0bce046a2f45d366041698ab3e42abbf3ebd3a191696e16acaecb7718da5afb.png\" class=\"lazyload\" alt=\"A custom configuration page preview with an \"Edit Email\" button.\" width=\"899\" height=\"737\"><\/figure>\n\nYour custom configuration page is then displayed in a frame in the Shopify admin.\n\n<figure class=\"figure\"><img src=\"https:\/\/cdn.shopify.com\/shopifycloud\/shopify_dev\/assets\/apps\/flow\/ccp-app-bridge-a41ecd52945725531037786df500785ea47a89f16b7df392e19be619bd133f64.png\" class=\"lazyload\" alt=\"The custom configuration page is rendered with an App Bridge title bar.\" width=\"1253\" height=\"756\"><\/figure>\n\nIn this tutorial, you'll learn how to render a custom configuration page in Shopify Flow, customize the page frame, and access data relevant to your action in the custom configuration page context.\n\n## Requirements\n\nYou've created a [Partner account](https:\/\/www.shopify.com\/partners).",
"| Endpoint | Purpose | | --- | --- | | [Flow action execution](\/docs\/apps\/flow\/actions\/endpoints#flow-action-execution) | The endpoint where the automation tool sends your action's payload. The payload contains data that you can use to execute the action in your app.| | [Custom configuration page preview](\/docs\/apps\/flow\/actions\/endpoints#custom-configuration-page-preview) | An endpoint that provides data about your [custom configuration page](\/docs\/apps\/build\/flow\/actions\/build-config-ui) to display in the automation tool. This endpoint is required if you want to use a custom configuration page.| | [Custom validation](\/docs\/apps\/flow\/actions\/endpoints#custom-validation) | An endpoint that validates the contents of merchant-configurable properties in an action payload when an action is saved. This endpoint is required if you want to use a custom configuration page.|\n\n## General endpoint requirements\n\nThe requirements for Shopify Flow action endpoints are as follows:"
],
"reference_contexts":[
"<1-hop>\n\nTo give merchants a more seamless action configuration experience, and to allow them to manage resources that are external to Shopify Flow, you can embed a page from your app in the Shopify Flow editor. In your Shopify Flow action configuration, merchants see a preview with an image and text that's fetched from your [custom configuration page preview URL](\/docs\/apps\/build\/flow\/actions\/endpoints#custom-configuration-page-preview). Merchants can click the button to access the custom configuration page. <figure class=\"figure\"><img src=\"https:\/\/cdn.shopify.com\/shopifycloud\/shopify_dev\/assets\/apps\/flow\/ccp-preview-d0bce046a2f45d366041698ab3e42abbf3ebd3a191696e16acaecb7718da5afb.png\" class=\"lazyload\" alt=\"A custom configuration page preview with an \"Edit Email\" button.\" width=\"899\" height=\"737\"><\/figure> Your custom configuration page is then displayed in a frame in the Shopify admin. <figure class=\"figure\"><img src=\"https:\/\/cdn.shopify.com\/shopifycloud\/shopify_dev\/assets\/apps\/flow\/ccp-app-bridge-a41ecd52945725531037786df500785ea47a89f16b7df392e19be619bd133f64.png\" class=\"lazyload\" alt=\"The custom configuration page is rendered with an App Bridge title bar.\" width=\"1253\" height=\"756\"><\/figure> In this tutorial, you'll learn how to render a custom configuration page in Shopify Flow, customize the page frame, and access data relevant to your action in the custom configuration page context. ## Requirements You've created a [Partner account](https:\/\/www.shopify.com\/partners). You've [created an app](\/docs\/apps\/build\/scaffold app). ## Resources To implement this feature, you'll use the following: [Shopify App Bridge](\/docs\/api\/app bridge) App Bridge components App Bridge actions specific to the custom configuration page ## Implementing a custom configuration page To build a custom configuration page, you'll [use Shopify App Bridge to render a page from your app page in Shopify Flow](#use-shopify-app-bridge-to-render-your-app-page). From the context of the custom configuration page, you can then [access step and property information](#access-action-information) that you can use to display the appropriate information. You can also [add additional buttons](#add-buttons-to-the-app-bridge-title-bar) to the App Bridge title bar, or [trigger a redirect to the previous page](#return-to-the-previous-page). ##",
"<2-hop>\n\nUse Shopify App Bridge to render your app page > Note: > The specifics of the Custom Configuration Page integration varies between Shopify App Bridge versions. Make sure you implement the integration specific to your Shopify App Bridge version. To render your custom configuration page, you need to integrate Shopify App Bridge on the route that you want to render. To learn about setting up Shopify App Bridge, refer to one of the following pages: [Getting started with Shopify App Bridge](\/docs\/api\/app bridge\/previous versions\/app bridge from npm\/app setup) [Getting started with App Bridge React](\/docs\/api\/app bridge library#react) ### Access action information In the context of the custom configuration page, Shopify Flow makes the following action information available: **A `step_reference` search parameter **: `step_reference` is a unique ID for the step within a workflow, and can be used to identify the resource that the merchant is requesting. **Property data **: Properties contains the extension fields data that make up your [action payload schema](\/docs\/apps\/build\/flow\/actions\/endpoints#request). The properties are passed as an object containing the properties as key value pairs: ```json { <property name>: <property value> } ``` ### Shopify App Bridge integration for versions 4.X.X and up #### Register to the Custom Configuration Page's intent To access property data with Shopify App Bridge version 4.X.X and up, you will need to use the `shopify.intents` API. The following example code allows you to register to the Custom Configuration Page's intent: ```jsx import { useAppBridge } from '@shopify\/app-bridge-react' const Application = () => { const shopify = useAppBridge() const [intent, setIntent] = useState({}) useEffect(() => { const cleanup = shopify.intents.register((intent) => { setIntent(intent) }) return () => cleanup() }, []); return <>...<\/> } ``` The `intent` object will contain the following data: | Field | Data Type | Description | | ------- | --------- | ----------------------------------------------------------------------------------------------------- | | action | `string` | The action that has been registered for. In the case of the Custom Configuration Page, it will always be set to `configure`. | | type | `string` | A GID with the following structure: `gid:\/\/flow\/stepReference\/<step-reference>`. | | data | `object` | An object that contains the `properties` data. | | finish | `method` | A function that allows you to navigate to the previous page. | The register method also returns a cleanup function, which you can use to unregister from the intent when your component is unmounting. #### Return to the previous page By default, the title bar of the custom configuration page includes an **Exit** button that the user can use to return to the previous page. You can choose to trigger a redirect to the previous page using the `intent.finish()` method: ```jsx <Button primary onClick={() => { intent.finish() }} > Go back to Flow <\/Button> ``` #### Add buttons to the App Bridge title bar You can add more actions to the navigation bar by using the **[ui-title-bar](\/docs\/api\/app-bridge-library\/web-components\/ui-title-bar)** element. Only primary and secondary actions are supported. ```jsx function Page() { return <ui-title-bar> <button variant=\"primary\" onClick={() => console.log('Primary action')}> Primary action <\/button> <button onClick={() => console.log('Secondary action')}> Secondary action <\/button> <\/ui-title-bar> } ``` ### Shopify App Bridge integration for versions 3.X.X and down #### Request property data To access property data, you need to subscribe to `APP::APP_FRAME::PROPERTIES_EVENT`, and then request the properties by triggering the `APP::APP_FRAME::REQUEST_PROPERTIES` event. The following example code subscribes to the properties event and requests the action properties in React: ```jsx import { useAppBridge } from '@shopify\/app-bridge-react' const Application = () => { const app = useAppBridge() const [propertiesData, setPropertiesData] = useState({}) useEffect(() => { const unsubscribeToPropertiesEvent = app.subscribe( 'APP::APP_FRAME::PROPERTIES_EVENT', payload => { setPropertiesData(payload['properties']) }, ) return unsubscribeToPropertiesEvent }, [app]) useEffect(() => { app.dispatch({ type: 'APP::APP_FRAME::REQUEST_PROPERTIES', group: 'AppFrame', }) }, []) return (...) } ``` #### Return to the previous page By default, the title bar of the custom configuration page includes an **Exit** button that the user can use to return to the previous page. This might be the Shopify Flow editor. However, you can choose to trigger a redirect to the previous page using `APP::APP_FRAME::NAVIGATE_BACK`: ```jsx app.dispatch({ type: 'APP::APP_FRAME::NAVIGATE_BACK', group: 'AppFrame', }) ``` #### Add buttons to the App Bridge title bar You can add more actions to the App Bridge title bar in one of two ways: Using `@shopify\/app bridge`: Use the [`Button.create`](\/docs\/api\/app bridge\/previous versions\/actions\/button#create a button) initializer to create the buttons, then pass them to the [`Titlebar.create`](\/docs\/api\/app bridge\/previous versions\/actions\/titlebar#plain javascript) initializer to set the buttons. You need to keep a reference to the Titlebar instance if you wish to do additional updates after the initialization. Using `@shopify\/app bridge react`: Pass the primary and secondary actions to the [`TitleBar`](\/docs\/api\/app bridge\/previous versions\/actions\/titlebar#react) React component. Only primary and secondary actions on the TitleBar are supported. Other App Bridge actions are ignored. ```js import { TitleBar, Button } from '@shopify\/app-bridge\/actions' \/\/ create the buttons const primaryBtn = Button.create(app, { label: 'Button 1', }) const secondaryBtn = Button.create(app, { label: 'Button 2', }) \/\/ add click handlers primaryBtn.subscribe(Button.Action.CLICK, () => { console.log('button 1 clicked') }) secondaryBtn.subscribe(Button.Action.CLICK, () => { console.log('button 2 clicked') }) const titleBar = TitleBar.create(app, { title: '', buttons: { primary: primaryBtn, secondary: [secondaryBtn], }, }) \/\/ update buttons after initialization const newPrimary = Button.create(app, { label: 'New button', }) newPrimary.subscribe(Button.Action.CLICK, () => { console.log('new primary button clicked') }) titleBar.set({ buttons: { primary: newPrimary, secondary: [secondaryBtn], }, }) ``` ```jsx import { TitleBar } from '@shopify\/app-bridge-react' function Page() { const buttons = { primaryAction: { content: 'Button 1', onAction: () => { console.log('button 1 clicked') }, }, secondaryActions: [ { content: 'Button 2', onAction: () => { console.log('button 2 clicked') }, }, ], } return <TitleBar title=\"\" {...buttons} \/> } ``` ##",
"<3-hop>\n\nNext steps Add [custom configuration page preview URL](\/docs\/apps\/build\/flow\/actions\/endpoints#custom configuration page preview) and [custom validation](\/docs\/apps\/build\/flow\/actions\/endpoints#custom validation) endpoints to your app. Add your custom configuration page preview URL, custom configuration page URL, and custom validation URL to [your Shopify Flow action configuration](\/docs\/apps\/build\/flow\/actions). > Note: > To add a custom configuration page to your action, you also need to add a custom validation endpoint.",
"<4-hop>\n\nSupported field types When you create a trigger, you add the fields that your trigger sends to Shopify Flow in the `[settings]` section of the TOML file. These fields define what your event plans to send to Shopify Flow. Merchants can then use that data in their conditions and actions. You can add two types of fields: custom fields or predefined reference fields. ! [A diagram that shows how trigger properties are rendered in the Flow editor](\/assets\/apps\/flow\/trigger_properties_in_flow_editor.png) ### Reference field types A reference field lets you send the identifier of a Shopify resource to Shopify Flow. This allows merchants to build workflows that use any data related to that resource. For example, your trigger sends a customer ID to Shopify Flow. The merchant can create a condition that checks `customer \/ amountSpent` and `customer \/ tags`. In their action, the merchant can include the template variables for customers, such as `{{customer.email}}`. To specify that a trigger will include a reference field, you only need to specify the `type` and an optional `description` property. For example: ```bash ... [settings] [[settings.fields]] type = \"customer_reference\" ``` You can use the following reference fields: | Reference type (TOML) | Payload key | Description | | --- | --- | --- | | `customer_reference` | `customer_id` | The [`id`](\/docs\/api\/admin-rest\/current\/resources\/customer#resource-object) or [`legacyResourceId`](\/docs\/api\/admin-graphql\/current\/objects\/customer#field-customer-legacyresourceid) of the customer.<br><br>Triggers that include this property in the request body are also available to [Shopify marketing automations](\/docs\/apps\/build\/marketing-analytics\/automations). | | `order_reference` | `order_id` | The [`id`](\/docs\/api\/admin-rest\/current\/resources\/order#resource-object) or [`legacyResourceId`](\/docs\/api\/admin-graphql\/current\/objects\/order#field-order-legacyresourceid) of the order. | | `product_reference` | `product_id` | The [`id`](\/docs\/api\/admin-rest\/current\/resources\/product#resource-object) or [`legacyResourceId`](\/docs\/api\/admin-graphql\/current\/objects\/product#field-product-legacyresourceid) of the product. | When making a request to Flow, include the payload key. See the [mutation API reference section](#mutation-api-reference) for a complete example. ### Custom field A custom field lets you define the data that you send as part of your trigger request. The following is an example: ```bash ... [settings] [[settings.fields]] type = \"number_decimal\" key = \"Amount\" ``` #### Custom field types The following are the available custom field types: | Field type | Description | Example | | ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------- | | `boolean` | A Boolean value. | `true`, `false` | | `email` | An email formatted string. | `\"email@example.com\"` | | `single_line_text_field` | A string. | `\"Hello world. \"` | `number_decimal` | A number with a decimal point. | `1.0` | | `url` | A URL formatted string. | `\"https:\/\/example\/com\"` | | `schema.<type>` | `<type>` can be any type defined in the provided schema. [Learn more about defining complex types](\/docs\/apps\/build\/flow\/configure-complex-data-types). | `{ \"foo\": \"bar\", \"baz\": 123 }` | #### Naming custom fields Field names need to be self-describing and readable. Use sentence case and separate words with spaces (not underscores or hyphens). These names can contain only alphabetical characters (a-z, A-Z) and spaces. When you refer to these fields in the payload that you send to Shopify Flow, enter the names verbatim . For example, `{ \"City location\": \"Ottawa\" } }`. Don't use shortened versions. #### Custom fields in the Shopify Flow editor Fields can be used in the Shopify Flow editor either in conditions or in actions as [template variables](https:\/\/help.shopify.com\/manual\/shopify-plus\/flow2\/reference\/variables). When used as template variables, Shopify Flow converts your `key` property to camelCase such as `{{ customerEmail }}`. ##",
"<5-hop>\n\nMutation API reference Once your extension is defined, published, and activated in a workflow according to [this guide](\/docs\/apps\/build\/flow\/triggers\/create), you can call Flow's mutation with an event, which will start the workflow(s). ```graphql mutation { flowTriggerReceive( handle: \"auction bid placed\", payload: { \"Amount\": \"30\", \"customer_id\": 12345 }) { userErrors {field, message} } } ``` | Property name | Property usage | | ------------------- | ------------------------------------------------------------------------------------------------------ | | `handle` | The extension\u2019s handle. | | `payload` | The fields that you selected for your payload schema in the action configuration. These should be serialized in a key-value pair format where the keys are equal to your field's \u201ckey\u201d properties. | > Note: > If you are using a Shopify admin API version of `2023-07` or earlier the mutation won't support the `handle` and `payload` properties. For information on that mutation shape you can rely on the [flowTriggerReceive documentation](\/docs\/api\/admin-graphql\/2023-07\/mutations\/flowTriggerReceive). ## Considerations When you create a trigger, the payload that you send to Shopify Flow needs to be [less than 1 MB and contain specific content](\/docs\/apps\/build\/flow\/triggers\/create#step 4 test your trigger) in the body. Triggers have the same [API rate limits](\/docs\/api\/usage\/rate limits) as the Shopify API.",
"<6-hop>\n\nCustom validation](\/docs\/apps\/flow\/actions\/endpoints#custom-validation) | An endpoint that validates the contents of merchant-configurable properties in an action payload when an action is saved. This endpoint is required if you want to use a custom configuration page.| ## General endpoint requirements The requirements for Shopify Flow action endpoints are as follows: | Rule \/ concern | Type \/ requirement | | --- | --- | | API format | REST | | Content type | JSON | | Security mechanism | [HMAC \/ Signed requests](#verifying-requests) | | Protocol | HTTPS (app domain requires valid SSL certificate) | ## Flow action execution When a workflow that contains your action is executed, Flow sends an HTTP request to your Flow action execution endpoint (runtime URL). The request contains a payload that matches the payload schema that you configured for your action. ### Request <script data-option=\"filename\" data-value=\"POST <Flow action HTTPS request URL>\">``` ```json { \"shop_id\": \"gid:\/\/shopify\/Shop\/1\", \"shopify_domain\": \"{shop}.myshopify.com\", \"action_run_id\": \"xxxx xxxx xxxx xxxx\", \"action_definition_id\": \"Place auction bid\", \"handle\": \"place auction bid\", \"properties\": { \"customer_id\": \"123456\", \"amount\": \"10.00\", \"step_reference\": \"320d4f8a aaab 40ff 9ed2 2bc079633705\" } } ``` The payload contains the following parameters: | Property Name | Property Usage | | ------------------- | ------------------------------------------------------------------------------------------------------ | | `shop_id` | The ID of the store. | | `shopify_domain` | The myshopify.com domain of the store. | | `action_run_id` | An ID that represents an instance of an action being run. [Learn more](#prevent-apps-from-processing-duplicate-requests). | | `handle` | The extension\u2019s handle. We recommend using this property to identify your actions. | | `step_reference` | A unique ID for the step within a workflow. This property only appears if you\u2019ve set a [Custom Configuration Page](\/docs\/apps\/build\/flow\/actions\/build-config-ui). | | `action_definition_id` | A unique ID for the action. The ID is based on the action name in the Partner Dashboard. | | | `properties` | The fields that you selected as part of the action configuration. | To learn how to configure the payload schema, refer to [Shopify Flow actions](\/docs\/apps\/build\/flow\/actions). ### Expected response After the automation tool sends a POST request to your web server, it waits for a maximum of 10 seconds for an [HTTP status code](https:\/\/en.wikipedia.org\/wiki\/List_of_HTTP_status_codes). If after 10 seconds the automation tool hasn't received a response from your web server, then the automation tool closes the connection to your web server and resends the request later. When the automation tool receives a response, it processes the codes as displayed in the following table: <table> <tr> <th>Status codes<\/th> <th>Description<\/th> <\/tr> <tr> <td>200 Success<\/td> <td>The automation tool assumes that the POST request has been processed by your web server.<\/td> <\/tr> <tr> <td>202 Success<\/td> <td>The automation tool assumes that the POST request has been accepted but not processed by your web server. The automation tool will resend the POST request at increasing intervals for up to 36 hours. <\/td> <\/tr> <tr> <td>4XX Client errors<\/td> <td> <p>If your web server sends a 429 status code without a <code>Retry-After<\/code> header, then the automation tool resends the POST request at increasing intervals for up to 36 hours. <p>If your web server sends a 429 status code with a <code>Retry-After<\/code> header that specifies a wait time, then the automation tool resends the POST request after the wait time (formatted in seconds) has passed. <p>If your web server sends any other 4XX code, then the automation tool assumes that there was a failure and it doesn't resend the POST request. Merchants see a notification in the automation tool that includes the raw contents of your web server's response. <p><strong>Example<\/strong>: <code>400 Bad Request { \"error1\": \"server unresponsive\" }<\/code> <p>You can provide a merchant-friendly description of the error by adding a key named <code>message<\/code>. For example: <p><strong>Example<\/strong>: <code>{ \"message\": \"Finish the onboarding on our website.\" }<\/code> <\/td> <\/tr> <tr> <td>5XX Server errors<\/td> <td>The automation tool resends the POST request at increasing intervals for up to 36 hours.<\/td> <\/tr> <tr> <td>Other status code<\/td> <td>If your web server returns a code that isn't described in this table, then the automation tool assumes that there was a failure and it doesn't resend the POST request.<\/td> <\/tr> <\/table> ### Prevent apps from processing duplicate requests Each request from an automation workflow contains an `action_run_id` that's unique to the associated action run. This ID is included in the body of the request. You can use `action_run_id` as an [idempotency key](\/docs\/api\/usage\/idempotent-requests) to check if the request is unique. In some cases, your app could receive an identical request more than once. For example, the automation tool might resend a request because it didn't receive your response in time. Your app can store the idempotency key in a cache with a set expiry time to avoid reprocessing duplicate requests. ### Identify actions The `handle` property is how you identify the action for processing when your web server receives a request from Flow during workflow execution. ```json { \"shop_id\": 0, \"shopify_domain\": \"{shop}.myshopify.com\", \"action_run_id\": \"xxxx xxxx xxxx xxxx\", \"handle\": \"auction bid\", \"action_definition_id\": \"Auction Bid\", \"properties\": {} } ``` ## Custom configuration page preview An endpoint that provides data about your [custom configuration page](\/docs\/apps\/build\/flow\/actions\/build-config-ui) to display in the automation tool. This endpoint is required if you want to use a custom configuration page. Using the endpoint, you can dynamically set the following information: The field\u2019s label A text preview A last updated at timestamp An image preview The text used by the button that redirects to the custom configuration page ### Request <script data-option=\"filename\" data-value=\"POST <Custom configuration page preview URL>\">``` ```json { \"shop_id\": \"gid:\/\/shopify\/Shop\/1\", \"shopify_domain\": \"{shop}.myshopify.com\", \"step_reference\": \"122438de2e57d8bad7e50958d2bd4999ca2c4c35ee3b5120e85e42a17fc1ce93\", \"handle\": \"my-extension-handle\", \"locale\":\"en\", \"properties\": { \"customer_id\": \"gid:\/\/shopify\/Customer\/1234567\", \"sms_message\": \"Thanks for making the purchase! \", \"marketing_activity_id\": \"gid:\/\/shopify\/MarketingActivity\/1234567\" } } ``` The payload contains the following parameters: | Parameter | Description | | ---------------------- | --- | | `shop_id` | The ID of the store. | | `shopify_domain` | The myshopify.com domain of the store. | | `handle` | The extension\u2019s handle. We recommend using this property to identify your actions. | | `step_reference` | A unique ID for the step within a workflow. | | `locale` | The locale of the store making the request,",
"<7-hop>\n\nBefore your app can receive communication from Flow actions, you need to create one or more standardized API endpoints on your web server. Review the information for each endpoint to understand its requirements, the format of the payload, and the expected response. You'll also learn how to avoid processing duplicate requests, identify an action by its ID, and verify requests for security purposes. | Endpoint | Purpose | | --- | --- | | [Flow action execution](\/docs\/apps\/flow\/actions\/endpoints#flow-action-execution) | The endpoint where the automation tool sends your action's payload. The payload contains data that you can use to execute the action in your app.| | [Custom configuration page preview](\/docs\/apps\/flow\/actions\/endpoints#custom-configuration-page-preview) | An endpoint that provides data about your [custom configuration page](\/docs\/apps\/build\/flow\/actions\/build-config-ui) to display in the automation tool. This endpoint is required if you want to use a custom configuration page.| | [Custom validation](\/docs\/apps\/flow\/actions\/endpoints#custom-validation) | An endpoint that validates the contents of merchant-configurable properties in an action payload when an action is saved. This endpoint is required if you want to use a custom configuration page.| ## Flow action execution](\/docs\/apps\/flow\/actions\/endpoints#flow-action-execution) | The endpoint where the automation tool sends your action's payload. The payload contains data that you can use to execute the action in your app.| | [ Custom configuration page preview](\/docs\/apps\/flow\/actions\/endpoints#custom-configuration-page-preview) | An endpoint that provides data about your [custom configuration page](\/docs\/apps\/build\/flow\/actions\/build-config-ui) to display in the automation tool. This endpoint is required if you want to use a custom configuration page.| | [",
"<8-hop>\n\nin ISO format. | | `properties` | The fields that you selected as part of the action configuration. | ### Expected response ```json { \"label_text\": \"Abandonment Email Template\", \"text_preview\": \"We want you back. Enjoy a 15% discount on your next purchase. \", \"button_text\": \"Edit Email\", \"image_preview\": { \"url\": \"http:\/\/someUrl.io\/assets\/preview_image.png\", \"alt\": \"Abandonment Email Template Preview Image\" }, \"last_updated_at\": \"2023-02-10T16:50:24.709Z\" } ``` Other than `text_preview`, all fields are nullable. <table> <caption><\/caption> <thead> <tr> <th scope=\u201ccol\u201d>Parameter<\/th> <th scope=\u201ccol\u201d>Description<\/th> <\/tr> <\/thead> <tbody> <tr> <td scope=\u201crow\u201d>1<\/td> <td><code>label_text<\/code><\/td> <td>A title for the custom configuration page.<br><br>If no value is specified, then the label text defaults to <b>Configuration Page Preview<\/b>.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d>2<\/td> <td><code>text_preview<\/code><\/td> <td>A preview that indicates the resource that's tied to the step. For example, in the case of an email content editor, this might be a preview of the email text.<br><br>This field is required.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d>3<\/td> <td><code>button_text<\/code><\/td> <td>The text for the button that the merchant clicks to access the custom configuration page.<br><br>If no value is specified, then the label text defaults to <b>Edit<b>.<br><br>If the value for `button_text` is longer than 23 characters, then the label is truncated to twenty characters with an ellipsis.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d><\/td> <td><code>image_preview<\/code><\/td> <td>The details of the image.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d>4<\/td> <td><code>image_preview.url<\/code><\/td> <td>The URL for a preview image of the custom configuration page. The image should be between 500px and 600px wide, and 100KB or less. There is no maximum height.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d><\/td> <td><code>image_preview.thumbnail_url<\/code><\/td> <td>The URL for a thumbnail version of the preview image.<br><br>This image is not currently used in the user interface.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d><\/td> <td><code>image_preview.alt<\/code><\/td> <td>The alt text for the preview image. This text appears if your image fails to render, and is accessible to screen readers.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d>5<\/td> <td><code>last_updated_at<\/code><\/td> <td>The date and time that the resource was last updated, in <a href=\"https:\/\/en.wikipedia.org\/wiki\/ISO_8601\">IS0-8601<\/a> format.<\/td> <\/tr> <\/tbody> <\/table> <figure class=\"figure\"><img src=\"https:\/\/cdn.shopify.com\/shopifycloud\/shopify_dev\/assets\/apps\/flow\/ccp-preview-annotated-379253a9b1eebe09194a0a0a0e5be1e2fd918fc977bdd1f78db60fa6f1e119c3.png\" class=\"lazyload\" alt=\"A labeled custom configuration page.\" width=\"901\" height=\"675\"><\/figure> ## Custom validation An endpoint that validates the contents of merchant-configurable properties in an action payload when an action is saved. This endpoint is required if you want to use a custom configuration page. ### Request The request contains a payload that matches the payload schema you configured for your action. <script data option=\"filename\" data value=\"POST <Validation endpoint>\">``` ```json { \"shop_id\": \"gid:\/\/shopify\/Shop\/1\", \"shopify_domain\": \"{shop}.myshopify.com\", \"handle\": \"my extension handle\", \"locale\": \"en\", \"steps\": [ { \"step_reference\": \"122438de2e57d8bad7e50958d2bd4999ca2c4c35ee3b5120e85e42a17fc1ce93\", \"properties\" : { \"outside_na\": true, \"guest_no\": 22, \"first_name\": \"John\", \"customer_id\": \"customer.id\" } }, { \"step_reference\": \"ca2c4c35ee3b5120e85e42a17fc1ce93122438de2e57d8bad7e50958d2bd4999\", \"properties\" : { \"outside_na\": false, \"guest_no\": 14, \"first_name\": \"Kim\", \"customer_id\": \"customer.id\" } }, ] } ``` The payload contains the following parameters: <table> <caption><\/caption> <thead> <tr> <th scope=\u201ccol\u201d>Parameter<\/th> <th scope=\u201ccol\u201d>Description<\/th> <\/tr> <\/thead> <tbody> <tr> <td scope=\u201crow\u201d><code>shop_id<\/code><\/td> <td>The ID of the store.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d><code>shopify_domain<\/code><\/td> <td>The myshopify.com domain of the store.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d><code>handle<\/code><\/td> <td>The extension\u2019s handle. We recommend using this property to identify your actions.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d><code>locale<\/code><\/td> <td>The locale of the store, in ISO format.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d><code>steps<\/code><\/td> <td>An array of all of the steps to validate. Each child step object represents a separate action on the merchant\u2019s workflow.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d><code>steps.step_reference<\/code><\/td> <td>The unique identifier for the step. This ID should be used when returning errors for a step.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d><code>steps.properties<\/code><\/td> <td> <p>An object containing the properties specified on the action. <p><b>Merchant-configurable properties<\/b>: These properties are passed as strings, with the following exceptions: <ul> <li>Checkbox properties: Boolean<\/li> <li>Number properties: integer<\/li> <\/ul> <p><b>Shopify properties<\/b>: The path to the value for the related commerce object in the workflow environment. For example, <code>customer.id<\/code>. If the value isn't available in the workflow environment, then an empty string is returned. The property will be populated with an actual value at runtime. <p><b>Example 1: Customer ID is available in the workflow environment<\/b> <ul> <li>Validation payload value: \"customer.id\"<\/li> <li>Runtime value: \"123456\"<\/li> <\/ul> <p><b>Example 2: Customer ID isn't available in the workflow environment<\/b> <ul> <li>Validation payload value: \"\"<\/li> <li>Runtime value: null<\/li> <\/ul> <p>If a property is marked as optional, then the workflow tool won't validate the presence of the commerce object, and will only rely on external validation. The path to the value for the commerce objects is still returned as a path, but Shopify can't guarantee their presence at runtime. If you need a commerce object to be present at runtime, then you should mark it as required. This allows the workflow tool to assess the presence of the commerce object and return any errors to the editor. <p><b>Example 3: Customer ID might be available in the workflow environment (for example, when using a custom trigger and an order step)<\/b> <ul> <li>Validation payload value: \"customer.lastOrder.id\"<\/li> <li>Runtime value: \"123456\" OR null<\/li> <\/ul> <\/td> <\/tr> <\/tbody> <\/table> ### Expected response Your app should return an array of the steps that you validated, which are identified by their `step_reference`. If there are any validation errors, then specify them in a `step_errors` array. The error messages that return display to the merchant in the action configuration pane in Shopify Flow. ! [An image of error messages in the action configuration pane. ](\/assets\/apps\/flow\/validation-error.png) ```yml [ { step_reference: '122438de2e57d8bad7e50958d2bd4999ca2c4c35ee3b5120e85e42a17fc1ce93', step_errors: [ { message: 'A step level error occurred' } ], properties_errors: [ { id: 'guest_no', message: 'Number of guests is limited to 8 when outside of North America' } ] }, { step_reference: 'ca2c4c35ee3b5120e85e42a17fc1ce93122438de2e57d8bad7e50958d2bd4999', step_errors: [], properties_errors: [] } ] ``` <table> <caption><\/caption> <thead> <tr> <th scope=\u201ccol\u201d>Parameter<\/th> <th scope=\u201ccol\u201d>Description<\/th> <\/tr> <\/thead> <tbody> <tr> <td scope=\u201crow\u201d><code>step_reference<\/code><\/td> <td>The unique identifier for the step. This ID should be used when returning errors for a step.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d><code>step_errors<\/code><\/td> <td>An array of errors that apply to the entire step.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d><code>step_errors.message<\/code><\/td> <td>An error message to display at the top of the action configuration pane.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d><code>properties_errors<\/code><\/td> <td>An array of errors that apply to particular properties.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d><code>properties_errors.id<\/code><\/td> <td>The key of the property that contains the error.<\/td> <\/tr> <tr> <td scope=\u201crow\u201d><code>properties_errors.message<\/code><\/td> <td>An error message to display for the property.<\/td> <\/tr> <\/tbody> <\/table> ##"
],
"response":"To use Shopify App Bridge for a custom configuration page in Shopify Flow, here's a straightforward guide:\n\n### Setting Up Your Custom Configuration Page\n\n1. **Create a Shopify Partner Account**: Before anything, ensure you've signed up for a Shopify Partner account.\n2. **Build Your App**: You\u2019ll need to have an app that you've developed. If you haven't yet, you should follow Shopify's guide on creating an app.\n\n### Implementing Shopify App Bridge\n\n3. **Integrate Shopify App Bridge**: Your next step involves incorporating Shopify App Bridge into your app. This lets your app communicate efficiently with Shopify, ensuring your custom configuration page works seamlessly within the Shopify admin interface. Depending on your preference or existing tech stack, you can use Shopify App Bridge directly or with React.\n\n### Rendering the Custom Configuration Page\n\n4. **Configure the App Page**: On the route (URL path) where you intend to show the custom configuration page, you'll set up Shopify App Bridge. This setup ensures that when this page is accessed, it will correctly render within the Shopify admin environment, complete with a Shopify-like frame and functionality.\n\n5. **Access Action and Property Information**: Within your custom configuration page, Shopify Flow allows you to access necessary information regarding the steps and properties for your action. This is crucial for displaying relevant data or options to merchants.\n\n6. **Enhance with Additional Buttons or Redirects**: You have the option to add more buttons to the App Bridge title bar for extra functionalities. Besides, if needed, you can implement a feature to redirect users back to the previous page, enhancing navigation and user experience within your custom configuration page.\n\n### Setting Up Necessary Endpoints\n\nTo support your custom configuration page, you must set up specific endpoints:\n\n- **Flow Action Execution Endpoint**: Handles execution of your action's logic using the provided payload data.\n- **Custom Configuration Page Preview Endpoint**: Offers data to render a preview of your custom configuration page within Shopify Flow.\n- **Custom Validation Endpoint**: Validates the merchant-configurable properties in your action's payload before saving.\n\nEach endpoint plays a critical role in how your custom configuration page operates, from rendering previews to ensuring data integrity through validation.\n\n### Summary\n\nBy following these steps, integrating Shopify App Bridge into your app, and setting up the necessary endpoints, you can create a custom configuration page that smoothly operates within Shopify Flow. This enhances the merchant experience by providing a seamless integration for your app's unique functionalities within Shopify's ecosystem.",
"reference":"To render a custom configuration page in Shopify Flow, you need to integrate Shopify App Bridge on the route you want to render. This involves using Shopify App Bridge to render a page from your app within the Shopify Flow editor, allowing merchants to manage resources external to Shopify Flow. The custom configuration page is displayed in a frame in the Shopify admin, and you can access step and property information relevant to your action. For setting up the necessary endpoints, you need to create standardized API endpoints on your web server to receive communication from Flow actions. These include the Flow action execution endpoint, which receives the action's payload, and the custom configuration page preview endpoint, which provides data about your custom configuration page to display in the automation tool. The endpoints must adhere to specific requirements, such as using REST API format, JSON content type, and HTTPS protocol with a valid SSL certificate."
},
{
"user_input":"How can Shopify CLI be used to create a trigger extension for Shopify Flow, and what are the supported field types for configuring the payload?",
"retrieved_contexts":[
"When you create a new trigger extension using Shopify CLI, a basic version of the TOML configuration file structure is generated. In this guide, you'll learn about configuring the different sections and properties of the configuration file, including extension properties, extension fields, reference field types, custom field types, and more.\n\nThis guide will also inform you how to make HTTP requests to Flow to start the workflows in which your extension is the trigger.\n\n## TOML\n\n> Note: > Creating Flow extensions using Shopify CLI is an exciting new feature that is currently in development. As with any developing feature, it's important to note that the Flow's CLI capabilities will continue to evolve and improve over time. Developers can expect additional functionality, enhancements, and improvements to be added as development progresses. > >To create Flow extensions using [Shopify CLI](https:\/\/www.npmjs.com\/package\/@shopify\/cli), ensure you have the latest version installed.",
"### Trigger extension fields\n\nTrigger extension fields are listed in the `[settings]` section, with each field using a `[[settings.field]]` header. These fields define the payload your event will send to Flow. You can add more than one field to your Flow trigger. The order of the fields in the TOML file is preserved when they're being rendered in the editor configuration panel. When sending a trigger payload, all fields defined in a trigger are required.",
"When you create a new trigger extension using Shopify CLI, you'll get a basic version of the TOML configuration file structure which should look like the following example:\n\n```bash\n\n[[extensions]]\n\nname = \"Auction Bid\"\n\ntype = \"flow_trigger\"\n\nhandle = \"auction\n\nbid\"\n\ndescription = \"Your description\"\n\n[settings]\n\n[[settings.fields]]\n\ntype = \"customer_reference\"\n\n[[settings.fields]] type = \"single_line_text_field\" key = \"your field key\" ```\n\n### Trigger extension properties\n\nExtension properties are listed in the `[[extensions]]` section and enable you to define the interface between Flow and your event.",
"> Note: > If you are using a Shopify admin API version of `2023-07` or earlier the mutation won't support the `handle` and `payload` properties. For information on that mutation shape you can rely on the [flowTriggerReceive documentation](\/docs\/api\/admin-graphql\/2023-07\/mutations\/flowTriggerReceive).\n\n## Considerations\n\nWhen you create a trigger, the payload that you send to Shopify Flow needs to be [less than 1 MB and contain specific content](\/docs\/apps\/build\/flow\/triggers\/create#step\n\n4\n\ntest\n\nyour\n\ntrigger) in the body.\n\nTriggers have the same [API rate limits](\/docs\/api\/usage\/rate\n\nlimits) as the Shopify API.",
"## How triggers work\n\nA trigger is a task in Shopify Flow that starts the execution of a workflow. The trigger represents an event that happens in a store or in an app. You can [build a trigger](\/docs\/apps\/build\/flow\/triggers\/create) for Shopify Flow so that events in your app trigger workflows to run.\n\n! [A diagram that show how third party triggers interface with Flow ](\/assets\/apps\/flow\/trigger_diagram.png)\n\n## Next steps\n\nTo build a trigger, you need to [create a trigger extension](\/docs\/apps\/build\/flow\/triggers\/create) in your app. In that extension, you specify details about the trigger using a [TOML file](\/docs\/apps\/build\/flow\/triggers\/reference).\n\nOnce you have published your extension, you can then test or use it by [calling the Shopify API](\/docs\/apps\/build\/flow\/triggers\/reference#mutation\n\napi\n\nreference) with the trigger payload."
],
"reference_contexts":[
"<1-hop>\n\nWhen you create a new trigger extension using Shopify CLI, a basic version of the TOML configuration file structure is generated. In this guide, you'll learn about configuring the different sections and properties of the configuration file, including extension properties, extension fields, reference field types, custom field types, and more. This guide will also inform you how to make HTTP requests to Flow to start the workflows in which your extension is the trigger. ## TOML > Note: > Creating Flow extensions using Shopify CLI is an exciting new feature that is currently in development. As with any developing feature, it's important to note that the Flow's CLI capabilities will continue to evolve and improve over time. Developers can expect additional functionality, enhancements, and improvements to be added as development progresses. > >To create Flow extensions using [Shopify CLI](https:\/\/www.npmjs.com\/package\/@shopify\/cli), ensure you have the latest version installed. When you create a new trigger extension using Shopify CLI, you'll get a basic version of the TOML configuration file structure which should look like the following example: ```bash [[extensions]] name = \"Auction Bid\" type = \"flow_trigger\" handle = \"auction bid\" description = \"Your description\" [settings] [[settings.fields]] type = \"customer_reference\" [[settings.fields]] type = \"single_line_text_field\" key = \"your field key\" ``` ### Trigger extension properties Extension properties are listed in the `[[extensions]]` section and enable you to define the interface between Flow and your event. | Property name | Description | Rules | | --------------------------- | ------------------------------------------------------------- | -------------------------------------- | | `name` <br><span class=\"heading-flag\">Required<\/span> | Name of your extension. Will be the merchant-facing name of your task in the editor. This should be something that is human readable. | | | `type` <br><span class=\"heading-flag\">Required<\/span> | The type of your extension. This should always be set to \u201cflow_trigger\u201d for Flow triggers. | - Value must be `flow_trigger`. | `handle` <br><span class=\"heading-flag\">Required<\/span> | A unique identifier for your extension. This property cannot be changed once you\u2019ve run the `dev` or `deploy` command. | - Cannot exceed 30 characters.<br \/> - Must be unique across your app's extensions. <br \/> - Must only contain alphanumeric characters and hyphens. | | `description` <br><span class=\"heading-flag\">Optional<\/span> | A description of your extension. This description will be shown in the Flow editor navigation panel. | | ### Trigger extension fields Trigger extension fields are listed in the `[settings]` section, with each field using a `[[settings.field]]` header. These fields define the payload your event will send to Flow. You can add more than one field to your Flow trigger. The order of the fields in the TOML file is preserved when they're being rendered in the editor configuration panel. When sending a trigger payload, all fields defined in a trigger are required. | Property name | Description | Rules | | ------------------------------ | --------------------------------------------------------------------------------------------------- | --------------------------------| | `type` <br><span class=\"heading-flag\">Required<\/span> | The field type. | - [Accepted custom field types](#custom-field-types).<br> - [Accepted reference field types](#reference-field-types). | | `key` <br><span class=\"heading-flag\">Optional<\/span> | A unique key that identifies your field. This should be human readable since it will appear in the Flow editor in the environment picker menu. | - Required for custom field types. <br \/> Should only contain alphabetic values or spaces. <br \/> - This property is not valid for reference field types. | | `description` <br><span class=\"heading-flag\">Required<\/span> | A description of the field. This will appear in the Flow editor configuration panel. | ###",
"<2-hop>\n\nSupported field types When you create a trigger, you add the fields that your trigger sends to Shopify Flow in the `[settings]` section of the TOML file. These fields define what your event plans to send to Shopify Flow. Merchants can then use that data in their conditions and actions. You can add two types of fields: custom fields or predefined reference fields. ! [A diagram that shows how trigger properties are rendered in the Flow editor](\/assets\/apps\/flow\/trigger_properties_in_flow_editor.png) ### Reference field types A reference field lets you send the identifier of a Shopify resource to Shopify Flow. This allows merchants to build workflows that use any data related to that resource. For example, your trigger sends a customer ID to Shopify Flow. The merchant can create a condition that checks `customer \/ amountSpent` and `customer \/ tags`. In their action, the merchant can include the template variables for customers, such as `{{customer.email}}`. To specify that a trigger will include a reference field, you only need to specify the `type` and an optional `description` property. For example: ```bash ... [settings] [[settings.fields]] type = \"customer_reference\" ``` You can use the following reference fields: | Reference type (TOML) | Payload key | Description | | --- | --- | --- | | `customer_reference` | `customer_id` | The [`id`](\/docs\/api\/admin-rest\/current\/resources\/customer#resource-object) or [`legacyResourceId`](\/docs\/api\/admin-graphql\/current\/objects\/customer#field-customer-legacyresourceid) of the customer.<br><br>Triggers that include this property in the request body are also available to [Shopify marketing automations](\/docs\/apps\/build\/marketing-analytics\/automations). | | `order_reference` | `order_id` | The [`id`](\/docs\/api\/admin-rest\/current\/resources\/order#resource-object) or [`legacyResourceId`](\/docs\/api\/admin-graphql\/current\/objects\/order#field-order-legacyresourceid) of the order. | | `product_reference` | `product_id` | The [`id`](\/docs\/api\/admin-rest\/current\/resources\/product#resource-object) or [`legacyResourceId`](\/docs\/api\/admin-graphql\/current\/objects\/product#field-product-legacyresourceid) of the product. | When making a request to Flow, include the payload key. See the [mutation API reference section](#mutation-api-reference) for a complete example. ### Custom field A custom field lets you define the data that you send as part of your trigger request. The following is an example: ```bash ... [settings] [[settings.fields]] type = \"number_decimal\" key = \"Amount\" ``` #### Custom field types The following are the available custom field types: | Field type | Description | Example | | ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------- | | `boolean` | A Boolean value. | `true`, `false` | | `email` | An email formatted string. | `\"email@example.com\"` | | `single_line_text_field` | A string. | `\"Hello world. \"` | `number_decimal` | A number with a decimal point. | `1.0` | | `url` | A URL formatted string. | `\"https:\/\/example\/com\"` | | `schema.<type>` | `<type>` can be any type defined in the provided schema. [Learn more about defining complex types](\/docs\/apps\/build\/flow\/configure-complex-data-types). | `{ \"foo\": \"bar\", \"baz\": 123 }` | #### Naming custom fields Field names need to be self-describing and readable. Use sentence case and separate words with spaces (not underscores or hyphens). These names can contain only alphabetical characters (a-z, A-Z) and spaces. When you refer to these fields in the payload that you send to Shopify Flow, enter the names verbatim . For example, `{ \"City location\": \"Ottawa\" } }`. Don't use shortened versions. #### Custom fields in the Shopify Flow editor Fields can be used in the Shopify Flow editor either in conditions or in actions as [template variables](https:\/\/help.shopify.com\/manual\/shopify-plus\/flow2\/reference\/variables). When used as template variables, Shopify Flow converts your `key` property to camelCase such as `{{ customerEmail }}`. ##",
"<3-hop>\n\nMutation API reference Once your extension is defined, published, and activated in a workflow according to [this guide](\/docs\/apps\/build\/flow\/triggers\/create), you can call Flow's mutation with an event, which will start the workflow(s). ```graphql mutation { flowTriggerReceive( handle: \"auction bid placed\", payload: { \"Amount\": \"30\", \"customer_id\": 12345 }) { userErrors {field, message} } } ``` | Property name | Property usage | | ------------------- | ------------------------------------------------------------------------------------------------------ | | `handle` | The extension\u2019s handle. | | `payload` | The fields that you selected for your payload schema in the action configuration. These should be serialized in a key-value pair format where the keys are equal to your field's \u201ckey\u201d properties. | > Note: > If you are using a Shopify admin API version of `2023-07` or earlier the mutation won't support the `handle` and `payload` properties. For information on that mutation shape you can rely on the [flowTriggerReceive documentation](\/docs\/api\/admin-graphql\/2023-07\/mutations\/flowTriggerReceive). ## Considerations When you create a trigger, the payload that you send to Shopify Flow needs to be [less than 1 MB and contain specific content](\/docs\/apps\/build\/flow\/triggers\/create#step 4 test your trigger) in the body. Triggers have the same [API rate limits](\/docs\/api\/usage\/rate limits) as the Shopify API."
],
"response":"To create a trigger extension for Shopify Flow using Shopify CLI, you'd follow these steps:\n\n1. **Ensure Shopify CLI is Installed**: Make sure you have the latest version of Shopify CLI. This tool helps developers interact with Shopify and develop apps and themes more efficiently.\n\n2. **Generate Your Extension**: Use Shopify CLI to generate a new trigger extension. When you do this, you will get a basic TOML (Tom's Obvious, Minimal Language) configuration file structure. TOML is a straightforward file format used for configuration files. This file is where you will define how your trigger works and what kind of data it sends.\n\n3. **Configure Your Extension**:\n \n a. **Extension Properties**: Inside your TOML file, in the `[[extensions]]` section, you define the basic information about your extension like its name, type (should be \"flow_trigger\" for flow triggers), handle, and a description of what it does.\n \n b. **Trigger Extension Fields**: In the `[settings]` section of your TOML file, you can define the payload your trigger will send when it fires. These settings are added with `[[settings.fields]]` headers. This is the data that Shopify Flow will use to start the workflows. The payload needs to be less than 1 MB.\n\n4. **Supported Field Types for Payload**: Within the settings for your trigger extension, you specify the fields of the payload using various types, such as:\n \n - `customer_reference`: This type could be used to reference a customer in Shopify.\n - `single_line_text_field`: A simple text field.\n\n Each field you define should have a type and a key, which are used to construct the data sent to Flow.\n\n5. **Testing and Usage**: After you've defined your trigger extension, you will need to publish your extension and test it by making HTTP requests to Shopify API with your trigger payload. This test ensures that when your trigger fires, the correct data is sent and the workflows in Shopify Flow start as intended.\n\nRemember, triggers are responsible for starting workflows in Shopify Flow based on certain events, and with a trigger extension, you can customize exactly how and when those workflows should start, based on the events occurring in your app or store.\n\nThe process of setting this up involves some technical steps like installing software (Shopify CLI), coding (editing the TOML file), and using APIs (to test triggers), but each step essentially breaks down into preparing your trigger extension, defining what data it sends, and ensuring it communicates correctly with Shopify Flow.",
"reference":"Shopify CLI can be used to create a trigger extension for Shopify Flow by generating a basic version of the TOML configuration file structure. This includes defining extension properties such as name, type, handle, and description in the `[[extensions]]` section. The supported field types for configuring the payload in the `[settings]` section of the TOML file include custom fields and predefined reference fields. Custom fields can be of types like boolean, email, single_line_text_field, number_decimal, and url, while reference fields can include customer_reference, order_reference, and product_reference. These fields define the data that the trigger sends to Shopify Flow, which merchants can use in their conditions and actions."
},
{
"user_input":"How can a Shopify App Developer utilize Shopify CLI to configure a trigger extension for Shopify Flow, and what are the considerations for using custom and reference fields in the TOML configuration file?",
"retrieved_contexts":[
"When you create a new trigger extension using Shopify CLI, a basic version of the TOML configuration file structure is generated. In this guide, you'll learn about configuring the different sections and properties of the configuration file, including extension properties, extension fields, reference field types, custom field types, and more.\n\nThis guide will also inform you how to make HTTP requests to Flow to start the workflows in which your extension is the trigger.\n\n## TOML\n\n> Note: > Creating Flow extensions using Shopify CLI is an exciting new feature that is currently in development. As with any developing feature, it's important to note that the Flow's CLI capabilities will continue to evolve and improve over time. Developers can expect additional functionality, enhancements, and improvements to be added as development progresses. > >To create Flow extensions using [Shopify CLI](https:\/\/www.npmjs.com\/package\/@shopify\/cli), ensure you have the latest version installed.",
"When you create a new trigger extension using Shopify CLI, you'll get a basic version of the TOML configuration file structure which should look like the following example:\n\n```bash\n\n[[extensions]]\n\nname = \"Auction Bid\"\n\ntype = \"flow_trigger\"\n\nhandle = \"auction\n\nbid\"\n\ndescription = \"Your description\"\n\n[settings]\n\n[[settings.fields]]\n\ntype = \"customer_reference\"\n\n[[settings.fields]] type = \"single_line_text_field\" key = \"your field key\" ```\n\n### Trigger extension properties\n\nExtension properties are listed in the `[[extensions]]` section and enable you to define the interface between Flow and your event.",
"### Supported field types\n\nWhen you create a trigger, you add the fields that your trigger sends to Shopify Flow in the `[settings]` section of the TOML file. These fields define what your event plans to send to Shopify Flow. Merchants can then use that data in their conditions and actions.\n\nYou can add two types of fields: custom fields or predefined reference fields.\n\n! [A diagram that shows how trigger properties are rendered in the Flow editor](\/assets\/apps\/flow\/trigger_properties_in_flow_editor.png)\n\n### Reference field types\n\nA reference field lets you send the identifier of a Shopify resource to Shopify Flow. This allows merchants to build workflows that use any data related to that resource.\n\nFor example, your trigger sends a customer ID to Shopify Flow. The merchant can create a condition that checks `customer \/ amountSpent` and `customer \/ tags`. In their action, the merchant can include the template variables for customers, such as `{{customer.email}}`.",
"| Property Name | Property value | | ------------------- | --------------- | | `extensions.schema` | .\/schema.graphql | | `extensions.return_type_ref` | Auction |\n\n## Referencing the return type schema in a trigger extension's TOML\n\nAfter a schema file has been defined, it can be referenced in the trigger extension's TOML by setting `extensions.schema` to the relative path of the schema file, and setting the type of a field to `schema.<type>`. The schema defined above can be referenced by setting the following fields:\n\n| Property Name | Property value | | ------------------- | --------------- | | `extensions.schema` | .\/schema.graphql | | `extensions.settings.fields[0].type` | schema.Auction |\n\n## Returning data from an action at runtime",
"### Folder structure\n\n```\n\n\/my\n\nextension\n\nname\n\nshopify.extensions.toml\n\nschema.graphql\n\n```\n\n### `shopify.extension.toml` file\n\n```bash [[extensions]] name = \"Place auction bid\" type = \"flow_action\" handle = \"auction-bid\" description = \"My description\" runtime_url = \"https:\/\/{url}.com\/api\/execute\" schema = \".\/schema.graphql\" return_type_ref = \"Auction\" ```\n\n## Referencing the return type schema in an action extension's TOML\n\nAfter a schema file has been defined, it can be referenced in the action extension's TOML by setting `extensions.schema` to the relative path of the schema file, and `extension.return_type_ref` to a type defined in the referenced schema file. The schema defined above can be referenced by setting the following fields:\n\n| Property Name | Property value | | ------------------- | --------------- | | `extensions.schema` | .\/schema.graphql | | `extensions.return_type_ref` | Auction |\n\n## Referencing the return type schema in a trigger extension's TOML"
],
"reference_contexts":[
"<1-hop>\n\nWhen you create a new trigger extension using Shopify CLI, a basic version of the TOML configuration file structure is generated. In this guide, you'll learn about configuring the different sections and properties of the configuration file, including extension properties, extension fields, reference field types, custom field types, and more. This guide will also inform you how to make HTTP requests to Flow to start the workflows in which your extension is the trigger. ## TOML > Note: > Creating Flow extensions using Shopify CLI is an exciting new feature that is currently in development. As with any developing feature, it's important to note that the Flow's CLI capabilities will continue to evolve and improve over time. Developers can expect additional functionality, enhancements, and improvements to be added as development progresses. > >To create Flow extensions using [Shopify CLI](https:\/\/www.npmjs.com\/package\/@shopify\/cli), ensure you have the latest version installed. When you create a new trigger extension using Shopify CLI, you'll get a basic version of the TOML configuration file structure which should look like the following example: ```bash [[extensions]] name = \"Auction Bid\" type = \"flow_trigger\" handle = \"auction bid\" description = \"Your description\" [settings] [[settings.fields]] type = \"customer_reference\" [[settings.fields]] type = \"single_line_text_field\" key = \"your field key\" ``` ### Trigger extension properties Extension properties are listed in the `[[extensions]]` section and enable you to define the interface between Flow and your event. | Property name | Description | Rules | | --------------------------- | ------------------------------------------------------------- | -------------------------------------- | | `name` <br><span class=\"heading-flag\">Required<\/span> | Name of your extension. Will be the merchant-facing name of your task in the editor. This should be something that is human readable. | | | `type` <br><span class=\"heading-flag\">Required<\/span> | The type of your extension. This should always be set to \u201cflow_trigger\u201d for Flow triggers. | - Value must be `flow_trigger`. | `handle` <br><span class=\"heading-flag\">Required<\/span> | A unique identifier for your extension. This property cannot be changed once you\u2019ve run the `dev` or `deploy` command. | - Cannot exceed 30 characters.<br \/> - Must be unique across your app's extensions. <br \/> - Must only contain alphanumeric characters and hyphens. | | `description` <br><span class=\"heading-flag\">Optional<\/span> | A description of your extension. This description will be shown in the Flow editor navigation panel. | | ### Trigger extension fields Trigger extension fields are listed in the `[settings]` section, with each field using a `[[settings.field]]` header. These fields define the payload your event will send to Flow. You can add more than one field to your Flow trigger. The order of the fields in the TOML file is preserved when they're being rendered in the editor configuration panel. When sending a trigger payload, all fields defined in a trigger are required. | Property name | Description | Rules | | ------------------------------ | --------------------------------------------------------------------------------------------------- | --------------------------------| | `type` <br><span class=\"heading-flag\">Required<\/span> | The field type. | - [Accepted custom field types](#custom-field-types).<br> - [Accepted reference field types](#reference-field-types). | | `key` <br><span class=\"heading-flag\">Optional<\/span> | A unique key that identifies your field. This should be human readable since it will appear in the Flow editor in the environment picker menu. | - Required for custom field types. <br \/> Should only contain alphabetic values or spaces. <br \/> - This property is not valid for reference field types. | | `description` <br><span class=\"heading-flag\">Required<\/span> | A description of the field. This will appear in the Flow editor configuration panel. | ###",
"<2-hop>\n\nSupported field types When you create a trigger, you add the fields that your trigger sends to Shopify Flow in the `[settings]` section of the TOML file. These fields define what your event plans to send to Shopify Flow. Merchants can then use that data in their conditions and actions. You can add two types of fields: custom fields or predefined reference fields. ! [A diagram that shows how trigger properties are rendered in the Flow editor](\/assets\/apps\/flow\/trigger_properties_in_flow_editor.png) ### Reference field types A reference field lets you send the identifier of a Shopify resource to Shopify Flow. This allows merchants to build workflows that use any data related to that resource. For example, your trigger sends a customer ID to Shopify Flow. The merchant can create a condition that checks `customer \/ amountSpent` and `customer \/ tags`. In their action, the merchant can include the template variables for customers, such as `{{customer.email}}`. To specify that a trigger will include a reference field, you only need to specify the `type` and an optional `description` property. For example: ```bash ... [settings] [[settings.fields]] type = \"customer_reference\" ``` You can use the following reference fields: | Reference type (TOML) | Payload key | Description | | --- | --- | --- | | `customer_reference` | `customer_id` | The [`id`](\/docs\/api\/admin-rest\/current\/resources\/customer#resource-object) or [`legacyResourceId`](\/docs\/api\/admin-graphql\/current\/objects\/customer#field-customer-legacyresourceid) of the customer.<br><br>Triggers that include this property in the request body are also available to [Shopify marketing automations](\/docs\/apps\/build\/marketing-analytics\/automations). | | `order_reference` | `order_id` | The [`id`](\/docs\/api\/admin-rest\/current\/resources\/order#resource-object) or [`legacyResourceId`](\/docs\/api\/admin-graphql\/current\/objects\/order#field-order-legacyresourceid) of the order. | | `product_reference` | `product_id` | The [`id`](\/docs\/api\/admin-rest\/current\/resources\/product#resource-object) or [`legacyResourceId`](\/docs\/api\/admin-graphql\/current\/objects\/product#field-product-legacyresourceid) of the product. | When making a request to Flow, include the payload key. See the [mutation API reference section](#mutation-api-reference) for a complete example. ### Custom field A custom field lets you define the data that you send as part of your trigger request. The following is an example: ```bash ... [settings] [[settings.fields]] type = \"number_decimal\" key = \"Amount\" ``` #### Custom field types The following are the available custom field types: | Field type | Description | Example | | ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------- | | `boolean` | A Boolean value. | `true`, `false` | | `email` | An email formatted string. | `\"email@example.com\"` | | `single_line_text_field` | A string. | `\"Hello world. \"` | `number_decimal` | A number with a decimal point. | `1.0` | | `url` | A URL formatted string. | `\"https:\/\/example\/com\"` | | `schema.<type>` | `<type>` can be any type defined in the provided schema. [Learn more about defining complex types](\/docs\/apps\/build\/flow\/configure-complex-data-types). | `{ \"foo\": \"bar\", \"baz\": 123 }` | #### Naming custom fields Field names need to be self-describing and readable. Use sentence case and separate words with spaces (not underscores or hyphens). These names can contain only alphabetical characters (a-z, A-Z) and spaces. When you refer to these fields in the payload that you send to Shopify Flow, enter the names verbatim . For example, `{ \"City location\": \"Ottawa\" } }`. Don't use shortened versions. #### Custom fields in the Shopify Flow editor Fields can be used in the Shopify Flow editor either in conditions or in actions as [template variables](https:\/\/help.shopify.com\/manual\/shopify-plus\/flow2\/reference\/variables). When used as template variables, Shopify Flow converts your `key` property to camelCase such as `{{ customerEmail }}`. ##",
"<3-hop>\n\nMutation API reference Once your extension is defined, published, and activated in a workflow according to [this guide](\/docs\/apps\/build\/flow\/triggers\/create), you can call Flow's mutation with an event, which will start the workflow(s). ```graphql mutation { flowTriggerReceive( handle: \"auction bid placed\", payload: { \"Amount\": \"30\", \"customer_id\": 12345 }) { userErrors {field, message} } } ``` | Property name | Property usage | | ------------------- | ------------------------------------------------------------------------------------------------------ | | `handle` | The extension\u2019s handle. | | `payload` | The fields that you selected for your payload schema in the action configuration. These should be serialized in a key-value pair format where the keys are equal to your field's \u201ckey\u201d properties. | > Note: > If you are using a Shopify admin API version of `2023-07` or earlier the mutation won't support the `handle` and `payload` properties. For information on that mutation shape you can rely on the [flowTriggerReceive documentation](\/docs\/api\/admin-graphql\/2023-07\/mutations\/flowTriggerReceive). ## Considerations When you create a trigger, the payload that you send to Shopify Flow needs to be [less than 1 MB and contain specific content](\/docs\/apps\/build\/flow\/triggers\/create#step 4 test your trigger) in the body. Triggers have the same [API rate limits](\/docs\/api\/usage\/rate limits) as the Shopify API."
],
"response":"Utilizing Shopify CLI to configure a trigger extension for Shopify Flow involves understanding and editing the TOML configuration file that is generated when you create a new trigger extension. This configuration file is crucial as it defines how your trigger interacts with Shopify Flow, including what data it sends and how it's structured.\n\n### Steps to Configure a Trigger Extension\n\n**1. Familiarize with the TOML File Structure:** When you initiate a new trigger extension using the Shopify CLI, it generates a base TOML file. Learn the sections and properties within this file, such as the extension properties (`[[extensions]]`), and the settings for your trigger (`[settings]`).\n\n**2. Define Extension Properties:** These are specified in the `[[extensions]]` section and are essential for setting up the interface between your trigger event and Shopify Flow. Key details like the name, type, handle, and description of the trigger are defined here.\n\n**3. Add Trigger Fields:** In the `[settings]` section, you'll add fields that represent the data your trigger will push to Shopify Flow. These fields could either be custom fields designed by you or predefined reference fields provided by Shopify.\n\n### Custom vs. Reference Fields\n\n**Custom Fields:** These are fields you define to suit the specific needs of your trigger. For example, you could have a field for a special identifier, a status, or any other unique information your trigger deals with.\n\n**Reference Fields:** These utilize Shopify's predefined fields that represent Shopify resources, like a customer ID. Using these allows merchants to build workflows based on existing Shopify data structures, like customer information or product details.\n\n### Considerations for Configuration\n\n1. **Understand Field Types:** Knowing when to use custom fields versus reference fields is crucial. Use custom fields for unique data specific to your extension, and reference fields when you can leverage Shopify\u2019s existing data structure.\n\n2. **Schema Definitions:** If you're working with complex data types or need to refer to specific Shopify objects, you might need to define a schema (using GraphQL) that outlines these types. This schema is then referenced in the TOML file, allowing you to use these complex types as fields in your extension.\n\n3. **Maintaining the TOML File:** Keep the TOML configuration accurate and up to date as you develop your extension. Any changes in what your extension does or the data it handles should be reflected in this file.\n\n4. **Version Compatibility:** The Shopify CLI and its features for Flow are evolving. Make sure you're using the latest version of the CLI to take advantage of new features and ensure compatibility.\n\nBy carefully configuring the TOML file and understanding the difference and use cases for custom and reference fields, you can effectively create trigger extensions for Shopify Flow that enhance the functionality of your or your clients' Shopify stores.",
"reference":"A Shopify App Developer can utilize Shopify CLI to configure a trigger extension for Shopify Flow by creating a new trigger extension, which generates a basic version of the TOML configuration file structure. This file includes sections for extension properties and fields, such as `name`, `type`, `handle`, and `description`. The `type` should always be set to 'flow_trigger' for Flow triggers. In the `[settings]` section, developers can define the fields that the trigger will send to Shopify Flow. These fields can be either custom fields or predefined reference fields. Custom fields allow developers to define specific data types, such as `boolean`, `email`, or `number_decimal`, while reference fields let developers send identifiers of Shopify resources, like `customer_reference` or `order_reference`, to Shopify Flow. When making a request to Flow, the payload must include the keys defined in the TOML file. It's important to ensure that the payload is less than 1 MB and adheres to Shopify's API rate limits. Additionally, developers should be aware that the CLI capabilities are evolving, and they should keep their CLI version updated to access new features and improvements."
},
{
"user_input":"How can a Shopify App Developer ensure security when integrating a custom configuration page in Shopify Flow using Shopify App Bridge?",
"retrieved_contexts":[
"App Bridge components\n\nApp Bridge actions specific to the custom configuration page\n\n## Implementing a custom configuration page\n\nTo build a custom configuration page, you'll [use Shopify App Bridge to render a page from your app page in Shopify Flow](#use-shopify-app-bridge-to-render-your-app-page).\n\nFrom the context of the custom configuration page, you can then [access step and property information](#access-action-information) that you can use to display the appropriate information.\n\nYou can also [add additional buttons](#add-buttons-to-the-app-bridge-title-bar) to the App Bridge title bar, or [trigger a redirect to the previous page](#return-to-the-previous-page).\n\n## Use Shopify App Bridge to render your app page\n\n> Note: > The specifics of the Custom Configuration Page integration varies between Shopify App Bridge versions. Make sure you implement the integration specific to your Shopify App Bridge version.",
"You can also [add additional buttons](#add-buttons-to-the-app-bridge-title-bar) to the App Bridge title bar, or [trigger a redirect to the previous page](#return-to-the-previous-page).\n\n## Use Shopify App Bridge to render your app page\n\n> Note: > The specifics of the Custom Configuration Page integration varies between Shopify App Bridge versions. Make sure you implement the integration specific to your Shopify App Bridge version.\n\nTo render your custom configuration page, you need to integrate Shopify App Bridge on the route that you want to render. To learn about setting up Shopify App Bridge, refer to one of the following pages:\n\n[Getting started with Shopify App Bridge](\/docs\/api\/app\n\nbridge\/previous\n\nversions\/app\n\nbridge\n\nfrom\n\nnpm\/app\n\nsetup)\n\n[Getting started with App Bridge React](\/docs\/api\/app\n\nbridge\n\nlibrary#react)\n\n### Access action information\n\nIn the context of the custom configuration page, Shopify Flow makes the following action information available:",
"In this tutorial, you'll learn how to render a custom configuration page in Shopify Flow, customize the page frame, and access data relevant to your action in the custom configuration page context.\n\n## Requirements\n\nYou've created a [Partner account](https:\/\/www.shopify.com\/partners).\n\nYou've [created an app](\/docs\/apps\/build\/scaffold\n\napp).\n\n## Resources\n\nTo implement this feature, you'll use the following:\n\n[Shopify App Bridge](\/docs\/api\/app\n\nbridge)\n\nApp Bridge components\n\nApp Bridge actions specific to the custom configuration page\n\n## Implementing a custom configuration page\n\nTo build a custom configuration page, you'll [use Shopify App Bridge to render a page from your app page in Shopify Flow](#use-shopify-app-bridge-to-render-your-app-page).\n\nFrom the context of the custom configuration page, you can then [access step and property information](#access-action-information) that you can use to display the appropriate information.",
"To give merchants a more seamless action configuration experience, and to allow them to manage resources that are external to Shopify Flow, you can embed a page from your app in the Shopify Flow editor.\n\nIn your Shopify Flow action configuration, merchants see a preview with an image and text that's fetched from your [custom configuration page preview URL](\/docs\/apps\/build\/flow\/actions\/endpoints#custom-configuration-page-preview). Merchants can click the button to access the custom configuration page.\n\n<figure class=\"figure\"><img src=\"https:\/\/cdn.shopify.com\/shopifycloud\/shopify_dev\/assets\/apps\/flow\/ccp-preview-d0bce046a2f45d366041698ab3e42abbf3ebd3a191696e16acaecb7718da5afb.png\" class=\"lazyload\" alt=\"A custom configuration page preview with an \"Edit Email\" button.\" width=\"899\" height=\"737\"><\/figure>\n\nYour custom configuration page is then displayed in a frame in the Shopify admin.",
"2. If you created a custom configuration page, then ensure that the preview displays and that the custom configuration page is accessible.\n\n3. If you added any custom validation, then ensure that it works as expected.\n\n4. Trigger the workflow. For example, in your web server, run the event that sends the trigger information to Shopify Flow.\n\nWhen the workflow completes, your web server has sent data to Shopify Flow because of the trigger. Shopify Flow has sent this data to a web server that logged the information to its console because of the action.\n\n## Step 6: Deploy your extension\n\n> Note: > Deploying extensions using the `app deploy` command also publishes the extensions. We recommend testing changes by using [`app dev`](\/docs\/api\/shopify-cli\/app\/app-dev) or deploying to a test app before deploying them to a production app.\n\nUse Shopify CLI to deploy your extensions:\n\n1. Navigate to your app directory. 2. Run the following command to start deploying your extension(s):\n\n```bash"
],
"reference_contexts":[
"<1-hop>\n\nTo give merchants a more seamless action configuration experience, and to allow them to manage resources that are external to Shopify Flow, you can embed a page from your app in the Shopify Flow editor. In your Shopify Flow action configuration, merchants see a preview with an image and text that's fetched from your [custom configuration page preview URL](\/docs\/apps\/build\/flow\/actions\/endpoints#custom-configuration-page-preview). Merchants can click the button to access the custom configuration page. <figure class=\"figure\"><img src=\"https:\/\/cdn.shopify.com\/shopifycloud\/shopify_dev\/assets\/apps\/flow\/ccp-preview-d0bce046a2f45d366041698ab3e42abbf3ebd3a191696e16acaecb7718da5afb.png\" class=\"lazyload\" alt=\"A custom configuration page preview with an \"Edit Email\" button.\" width=\"899\" height=\"737\"><\/figure> Your custom configuration page is then displayed in a frame in the Shopify admin. <figure class=\"figure\"><img src=\"https:\/\/cdn.shopify.com\/shopifycloud\/shopify_dev\/assets\/apps\/flow\/ccp-app-bridge-a41ecd52945725531037786df500785ea47a89f16b7df392e19be619bd133f64.png\" class=\"lazyload\" alt=\"The custom configuration page is rendered with an App Bridge title bar.\" width=\"1253\" height=\"756\"><\/figure> In this tutorial, you'll learn how to render a custom configuration page in Shopify Flow, customize the page frame, and access data relevant to your action in the custom configuration page context. ## Requirements You've created a [Partner account](https:\/\/www.shopify.com\/partners). You've [created an app](\/docs\/apps\/build\/scaffold app). ## Resources To implement this feature, you'll use the following: [Shopify App Bridge](\/docs\/api\/app bridge) App Bridge components App Bridge actions specific to the custom configuration page ## Implementing a custom configuration page To build a custom configuration page, you'll [use Shopify App Bridge to render a page from your app page in Shopify Flow](#use-shopify-app-bridge-to-render-your-app-page). From the context of the custom configuration page, you can then [access step and property information](#access-action-information) that you can use to display the appropriate information. You can also [add additional buttons](#add-buttons-to-the-app-bridge-title-bar) to the App Bridge title bar, or [trigger a redirect to the previous page](#return-to-the-previous-page). ##",
"<2-hop>\n\nUse Shopify App Bridge to render your app page > Note: > The specifics of the Custom Configuration Page integration varies between Shopify App Bridge versions. Make sure you implement the integration specific to your Shopify App Bridge version. To render your custom configuration page, you need to integrate Shopify App Bridge on the route that you want to render. To learn about setting up Shopify App Bridge, refer to one of the following pages: [Getting started with Shopify App Bridge](\/docs\/api\/app bridge\/previous versions\/app bridge from npm\/app setup) [Getting started with App Bridge React](\/docs\/api\/app bridge library#react) ### Access action information In the context of the custom configuration page, Shopify Flow makes the following action information available: **A `step_reference` search parameter **: `step_reference` is a unique ID for the step within a workflow, and can be used to identify the resource that the merchant is requesting. **Property data **: Properties contains the extension fields data that make up your [action payload schema](\/docs\/apps\/build\/flow\/actions\/endpoints#request). The properties are passed as an object containing the properties as key value pairs: ```json { <property name>: <property value> } ``` ### Shopify App Bridge integration for versions 4.X.X and up #### Register to the Custom Configuration Page's intent To access property data with Shopify App Bridge version 4.X.X and up, you will need to use the `shopify.intents` API. The following example code allows you to register to the Custom Configuration Page's intent: ```jsx import { useAppBridge } from '@shopify\/app-bridge-react' const Application = () => { const shopify = useAppBridge() const [intent, setIntent] = useState({}) useEffect(() => { const cleanup = shopify.intents.register((intent) => { setIntent(intent) }) return () => cleanup() }, []); return <>...<\/> } ``` The `intent` object will contain the following data: | Field | Data Type | Description | | ------- | --------- | ----------------------------------------------------------------------------------------------------- | | action | `string` | The action that has been registered for. In the case of the Custom Configuration Page, it will always be set to `configure`. | | type | `string` | A GID with the following structure: `gid:\/\/flow\/stepReference\/<step-reference>`. | | data | `object` | An object that contains the `properties` data. | | finish | `method` | A function that allows you to navigate to the previous page. | The register method also returns a cleanup function, which you can use to unregister from the intent when your component is unmounting. #### Return to the previous page By default, the title bar of the custom configuration page includes an **Exit** button that the user can use to return to the previous page. You can choose to trigger a redirect to the previous page using the `intent.finish()` method: ```jsx <Button primary onClick={() => { intent.finish() }} > Go back to Flow <\/Button> ``` #### Add buttons to the App Bridge title bar You can add more actions to the navigation bar by using the **[ui-title-bar](\/docs\/api\/app-bridge-library\/web-components\/ui-title-bar)** element. Only primary and secondary actions are supported. ```jsx function Page() { return <ui-title-bar> <button variant=\"primary\" onClick={() => console.log('Primary action')}> Primary action <\/button> <button onClick={() => console.log('Secondary action')}> Secondary action <\/button> <\/ui-title-bar> } ``` ### Shopify App Bridge integration for versions 3.X.X and down #### Request property data To access property data, you need to subscribe to `APP::APP_FRAME::PROPERTIES_EVENT`, and then request the properties by triggering the `APP::APP_FRAME::REQUEST_PROPERTIES` event. The following example code subscribes to the properties event and requests the action properties in React: ```jsx import { useAppBridge } from '@shopify\/app-bridge-react' const Application = () => { const app = useAppBridge() const [propertiesData, setPropertiesData] = useState({}) useEffect(() => { const unsubscribeToPropertiesEvent = app.subscribe( 'APP::APP_FRAME::PROPERTIES_EVENT', payload => { setPropertiesData(payload['properties']) }, ) return unsubscribeToPropertiesEvent }, [app]) useEffect(() => { app.dispatch({ type: 'APP::APP_FRAME::REQUEST_PROPERTIES', group: 'AppFrame', }) }, []) return (...) } ``` #### Return to the previous page By default, the title bar of the custom configuration page includes an **Exit** button that the user can use to return to the previous page. This might be the Shopify Flow editor. However, you can choose to trigger a redirect to the previous page using `APP::APP_FRAME::NAVIGATE_BACK`: ```jsx app.dispatch({ type: 'APP::APP_FRAME::NAVIGATE_BACK', group: 'AppFrame', }) ``` #### Add buttons to the App Bridge title bar You can add more actions to the App Bridge title bar in one of two ways: Using `@shopify\/app bridge`: Use the [`Button.create`](\/docs\/api\/app bridge\/previous versions\/actions\/button#create a button) initializer to create the buttons, then pass them to the [`Titlebar.create`](\/docs\/api\/app bridge\/previous versions\/actions\/titlebar#plain javascript) initializer to set the buttons. You need to keep a reference to the Titlebar instance if you wish to do additional updates after the initialization. Using `@shopify\/app bridge react`: Pass the primary and secondary actions to the [`TitleBar`](\/docs\/api\/app bridge\/previous versions\/actions\/titlebar#react) React component. Only primary and secondary actions on the TitleBar are supported. Other App Bridge actions are ignored. ```js import { TitleBar, Button } from '@shopify\/app-bridge\/actions' \/\/ create the buttons const primaryBtn = Button.create(app, { label: 'Button 1', }) const secondaryBtn = Button.create(app, { label: 'Button 2', }) \/\/ add click handlers primaryBtn.subscribe(Button.Action.CLICK, () => { console.log('button 1 clicked') }) secondaryBtn.subscribe(Button.Action.CLICK, () => { console.log('button 2 clicked') }) const titleBar = TitleBar.create(app, { title: '', buttons: { primary: primaryBtn, secondary: [secondaryBtn], }, }) \/\/ update buttons after initialization const newPrimary = Button.create(app, { label: 'New button', }) newPrimary.subscribe(Button.Action.CLICK, () => { console.log('new primary button clicked') }) titleBar.set({ buttons: { primary: newPrimary, secondary: [secondaryBtn], }, }) ``` ```jsx import { TitleBar } from '@shopify\/app-bridge-react' function Page() { const buttons = { primaryAction: { content: 'Button 1', onAction: () => { console.log('button 1 clicked') }, }, secondaryActions: [ { content: 'Button 2', onAction: () => { console.log('button 2 clicked') }, }, ], } return <TitleBar title=\"\" {...buttons} \/> } ``` ##",
"<3-hop>\n\nNext steps Add [custom configuration page preview URL](\/docs\/apps\/build\/flow\/actions\/endpoints#custom configuration page preview) and [custom validation](\/docs\/apps\/build\/flow\/actions\/endpoints#custom validation) endpoints to your app. Add your custom configuration page preview URL, custom configuration page URL, and custom validation URL to [your Shopify Flow action configuration](\/docs\/apps\/build\/flow\/actions). > Note: > To add a custom configuration page to your action, you also need to add a custom validation endpoint.",
"<4-hop>\n\nVerifying requests For security reasons, your web service should enforce a hash-based message authentication (HMAC) header verification that uses the client secret that you created when you configured your app. The name of the HMAC header is `x-shopify-hmac-sha256`. If you are using a Ruby-based web framework, then the name of the header is `http-x-shopify-hmac-sha256`. When the action runs in a workflow, the automation tool posts the contents (JSON payload and the HMAC header) of the action to the URL that you entered when you created the action in the Partner Dashboard. When your web server receives the POST request, it needs to verify the HMAC header against the JSON payload and your app's API secret. The HMAC verification works the same as [webhooks](\/docs\/apps\/build\/webhooks\/subscribe\/https). Your web server also needs to [verify that the `handle` that's sent in the payload matches the `handle` of the action that you created](#identify-actions). After you've verified the HMAC header, you can process the contents of the payload. For example, you could log the contents of the payload to your web server's console."
],
"response":"Given the details you shared, here's a simplified breakdown of how to ensure security when integrating a custom configuration page into Shopify Flow using Shopify App Bridge:\n\n1. **Shopify App Bridge Setup:** First, ensure you've properly implemented Shopify App Bridge in your application. Shopify App Bridge provides a secure, standardized way to embed your app directly within the Shopify Admin, which includes custom configuration pages. Use the official Shopify documentation to set it up according to your app bridge version.\n\n2. **Data Access and Display:** When you're displaying data on your custom configuration page, make sure you're only showing information relevant to the merchant's current action or configuration. This helps prevent accidental exposure of sensitive data.\n\n3. **Validation and Security Features:** Implement custom validation on your configuration page to ensure that the data being entered or manipulated is safe and meets your application's requirements. This could include checking for valid input formats or preventing unauthorized actions.\n\n4. **Secure Preview and Access:** The preview of your custom configuration page that appears in Shopify Flow should accurately represent what the merchant will interact with and should be securely accessible. Ensure the URLs and data involved in previewing and loading this page are transmitted securely.\n\n5. **Testing Your Implementation:** Before deploying your custom configuration page, rigorously test it in a non-production environment. This includes testing the security of your data access, the effectiveness of your validations, and the overall security of the page integration.\n\n6. **Deployment:** Use Shopify CLI for deployment, and follow best practices by deploying changes to a test app before pushing them to your production app. This helps ensure that any potential security issues are caught and fixed in a controlled environment.\n\nIn short, focus on secure implementation of Shopify App Bridge, careful management of data access and display, robust validation mechanisms, secure page access, thorough testing, and cautious deployment. Following these steps can help you maintain a high level of security in your app's integration with Shopify Flow.",
"reference":"A Shopify App Developer can ensure security when integrating a custom configuration page in Shopify Flow using Shopify App Bridge by implementing HMAC header verification. This involves enforcing a hash-based message authentication (HMAC) header verification using the client secret created during app configuration. The HMAC header, named `x-shopify-hmac-sha256`, must be verified against the JSON payload and the app's API secret when the web server receives a POST request. This verification process is similar to that used for webhooks, ensuring that the request is authentic and secure."
},
{
"user_input":"How can a Shopify App Developer integrate Shopify App Bridge to manage custom configuration pages and utilize the mutation API to trigger workflows in Shopify Flow?",
"retrieved_contexts":[
"App Bridge components\n\nApp Bridge actions specific to the custom configuration page\n\n## Implementing a custom configuration page\n\nTo build a custom configuration page, you'll [use Shopify App Bridge to render a page from your app page in Shopify Flow](#use-shopify-app-bridge-to-render-your-app-page).\n\nFrom the context of the custom configuration page, you can then [access step and property information](#access-action-information) that you can use to display the appropriate information.\n\nYou can also [add additional buttons](#add-buttons-to-the-app-bridge-title-bar) to the App Bridge title bar, or [trigger a redirect to the previous page](#return-to-the-previous-page).\n\n## Use Shopify App Bridge to render your app page\n\n> Note: > The specifics of the Custom Configuration Page integration varies between Shopify App Bridge versions. Make sure you implement the integration specific to your Shopify App Bridge version.",
"You can also [add additional buttons](#add-buttons-to-the-app-bridge-title-bar) to the App Bridge title bar, or [trigger a redirect to the previous page](#return-to-the-previous-page).\n\n## Use Shopify App Bridge to render your app page\n\n> Note: > The specifics of the Custom Configuration Page integration varies between Shopify App Bridge versions. Make sure you implement the integration specific to your Shopify App Bridge version.\n\nTo render your custom configuration page, you need to integrate Shopify App Bridge on the route that you want to render. To learn about setting up Shopify App Bridge, refer to one of the following pages:\n\n[Getting started with Shopify App Bridge](\/docs\/api\/app\n\nbridge\/previous\n\nversions\/app\n\nbridge\n\nfrom\n\nnpm\/app\n\nsetup)\n\n[Getting started with App Bridge React](\/docs\/api\/app\n\nbridge\n\nlibrary#react)\n\n### Access action information\n\nIn the context of the custom configuration page, Shopify Flow makes the following action information available:",
"In this tutorial, you'll learn how to render a custom configuration page in Shopify Flow, customize the page frame, and access data relevant to your action in the custom configuration page context.\n\n## Requirements\n\nYou've created a [Partner account](https:\/\/www.shopify.com\/partners).\n\nYou've [created an app](\/docs\/apps\/build\/scaffold\n\napp).\n\n## Resources\n\nTo implement this feature, you'll use the following:\n\n[Shopify App Bridge](\/docs\/api\/app\n\nbridge)\n\nApp Bridge components\n\nApp Bridge actions specific to the custom configuration page\n\n## Implementing a custom configuration page\n\nTo build a custom configuration page, you'll [use Shopify App Bridge to render a page from your app page in Shopify Flow](#use-shopify-app-bridge-to-render-your-app-page).\n\nFrom the context of the custom configuration page, you can then [access step and property information](#access-action-information) that you can use to display the appropriate information.",
"## Mutation API reference\n\nOnce your extension is defined, published, and activated in a workflow according to [this guide](\/docs\/apps\/build\/flow\/triggers\/create), you can call Flow's mutation with an event, which will start the workflow(s).\n\n```graphql\n\nmutation\n\n{\n\nflowTriggerReceive(\n\nhandle: \"auction\n\nbid\n\nplaced\",\n\npayload: {\n\n\"Amount\": \"30\",\n\n\"customer_id\": 12345\n\n})\n\n{\n\nuserErrors {field, message}\n\n}\n\n}\n\n```\n\n| Property name | Property usage | | ------------------- | ------------------------------------------------------------------------------------------------------ | | `handle` | The extension\u2019s handle. | | `payload` | The fields that you selected for your payload schema in the action configuration. These should be serialized in a key-value pair format where the keys are equal to your field's \u201ckey\u201d properties. |",
"[Getting started with Shopify App Bridge](\/docs\/api\/app\n\nbridge\/previous\n\nversions\/app\n\nbridge\n\nfrom\n\nnpm\/app\n\nsetup)\n\n[Getting started with App Bridge React](\/docs\/api\/app\n\nbridge\n\nlibrary#react)\n\n### Access action information\n\nIn the context of the custom configuration page, Shopify Flow makes the following action information available:\n\n**A `step_reference` search parameter\n\n**: `step_reference` is a unique ID for the step within a workflow, and can be used to identify the resource that the merchant is requesting.\n\n**Property data\n\n**: Properties contains the extension fields data that make up your [action payload schema](\/docs\/apps\/build\/flow\/actions\/endpoints#request). The properties are passed as an object containing the properties as key\n\nvalue pairs:\n\n```json\n\n{\n\n<property\n\nname>: <property\n\nvalue>\n\n}\n\n```\n\n### Shopify App Bridge integration for versions 4.X.X and up\n\n#### Register to the Custom Configuration Page's intent"
],
"reference_contexts":[
"<1-hop>\n\nUse Shopify App Bridge to render your app page > Note: > The specifics of the Custom Configuration Page integration varies between Shopify App Bridge versions. Make sure you implement the integration specific to your Shopify App Bridge version. To render your custom configuration page, you need to integrate Shopify App Bridge on the route that you want to render. To learn about setting up Shopify App Bridge, refer to one of the following pages: [Getting started with Shopify App Bridge](\/docs\/api\/app bridge\/previous versions\/app bridge from npm\/app setup) [Getting started with App Bridge React](\/docs\/api\/app bridge library#react) ### Access action information In the context of the custom configuration page, Shopify Flow makes the following action information available: **A `step_reference` search parameter **: `step_reference` is a unique ID for the step within a workflow, and can be used to identify the resource that the merchant is requesting. **Property data **: Properties contains the extension fields data that make up your [action payload schema](\/docs\/apps\/build\/flow\/actions\/endpoints#request). The properties are passed as an object containing the properties as key value pairs: ```json { <property name>: <property value> } ``` ### Shopify App Bridge integration for versions 4.X.X and up #### Register to the Custom Configuration Page's intent To access property data with Shopify App Bridge version 4.X.X and up, you will need to use the `shopify.intents` API. The following example code allows you to register to the Custom Configuration Page's intent: ```jsx import { useAppBridge } from '@shopify\/app-bridge-react' const Application = () => { const shopify = useAppBridge() const [intent, setIntent] = useState({}) useEffect(() => { const cleanup = shopify.intents.register((intent) => { setIntent(intent) }) return () => cleanup() }, []); return <>...<\/> } ``` The `intent` object will contain the following data: | Field | Data Type | Description | | ------- | --------- | ----------------------------------------------------------------------------------------------------- | | action | `string` | The action that has been registered for. In the case of the Custom Configuration Page, it will always be set to `configure`. | | type | `string` | A GID with the following structure: `gid:\/\/flow\/stepReference\/<step-reference>`. | | data | `object` | An object that contains the `properties` data. | | finish | `method` | A function that allows you to navigate to the previous page. | The register method also returns a cleanup function, which you can use to unregister from the intent when your component is unmounting. #### Return to the previous page By default, the title bar of the custom configuration page includes an **Exit** button that the user can use to return to the previous page. You can choose to trigger a redirect to the previous page using the `intent.finish()` method: ```jsx <Button primary onClick={() => { intent.finish() }} > Go back to Flow <\/Button> ``` #### Add buttons to the App Bridge title bar You can add more actions to the navigation bar by using the **[ui-title-bar](\/docs\/api\/app-bridge-library\/web-components\/ui-title-bar)** element. Only primary and secondary actions are supported. ```jsx function Page() { return <ui-title-bar> <button variant=\"primary\" onClick={() => console.log('Primary action')}> Primary action <\/button> <button onClick={() => console.log('Secondary action')}> Secondary action <\/button> <\/ui-title-bar> } ``` ### Shopify App Bridge integration for versions 3.X.X and down #### Request property data To access property data, you need to subscribe to `APP::APP_FRAME::PROPERTIES_EVENT`, and then request the properties by triggering the `APP::APP_FRAME::REQUEST_PROPERTIES` event. The following example code subscribes to the properties event and requests the action properties in React: ```jsx import { useAppBridge } from '@shopify\/app-bridge-react' const Application = () => { const app = useAppBridge() const [propertiesData, setPropertiesData] = useState({}) useEffect(() => { const unsubscribeToPropertiesEvent = app.subscribe( 'APP::APP_FRAME::PROPERTIES_EVENT', payload => { setPropertiesData(payload['properties']) }, ) return unsubscribeToPropertiesEvent }, [app]) useEffect(() => { app.dispatch({ type: 'APP::APP_FRAME::REQUEST_PROPERTIES', group: 'AppFrame', }) }, []) return (...) } ``` #### Return to the previous page By default, the title bar of the custom configuration page includes an **Exit** button that the user can use to return to the previous page. This might be the Shopify Flow editor. However, you can choose to trigger a redirect to the previous page using `APP::APP_FRAME::NAVIGATE_BACK`: ```jsx app.dispatch({ type: 'APP::APP_FRAME::NAVIGATE_BACK', group: 'AppFrame', }) ``` #### Add buttons to the App Bridge title bar You can add more actions to the App Bridge title bar in one of two ways: Using `@shopify\/app bridge`: Use the [`Button.create`](\/docs\/api\/app bridge\/previous versions\/actions\/button#create a button) initializer to create the buttons, then pass them to the [`Titlebar.create`](\/docs\/api\/app bridge\/previous versions\/actions\/titlebar#plain javascript) initializer to set the buttons. You need to keep a reference to the Titlebar instance if you wish to do additional updates after the initialization. Using `@shopify\/app bridge react`: Pass the primary and secondary actions to the [`TitleBar`](\/docs\/api\/app bridge\/previous versions\/actions\/titlebar#react) React component. Only primary and secondary actions on the TitleBar are supported. Other App Bridge actions are ignored. ```js import { TitleBar, Button } from '@shopify\/app-bridge\/actions' \/\/ create the buttons const primaryBtn = Button.create(app, { label: 'Button 1', }) const secondaryBtn = Button.create(app, { label: 'Button 2', }) \/\/ add click handlers primaryBtn.subscribe(Button.Action.CLICK, () => { console.log('button 1 clicked') }) secondaryBtn.subscribe(Button.Action.CLICK, () => { console.log('button 2 clicked') }) const titleBar = TitleBar.create(app, { title: '', buttons: { primary: primaryBtn, secondary: [secondaryBtn], }, }) \/\/ update buttons after initialization const newPrimary = Button.create(app, { label: 'New button', }) newPrimary.subscribe(Button.Action.CLICK, () => { console.log('new primary button clicked') }) titleBar.set({ buttons: { primary: newPrimary, secondary: [secondaryBtn], }, }) ``` ```jsx import { TitleBar } from '@shopify\/app-bridge-react' function Page() { const buttons = { primaryAction: { content: 'Button 1', onAction: () => { console.log('button 1 clicked') }, }, secondaryActions: [ { content: 'Button 2', onAction: () => { console.log('button 2 clicked') }, }, ], } return <TitleBar title=\"\" {...buttons} \/> } ``` ##",
"<2-hop>\n\nMutation API reference Once your extension is defined, published, and activated in a workflow according to [this guide](\/docs\/apps\/build\/flow\/triggers\/create), you can call Flow's mutation with an event, which will start the workflow(s). ```graphql mutation { flowTriggerReceive( handle: \"auction bid placed\", payload: { \"Amount\": \"30\", \"customer_id\": 12345 }) { userErrors {field, message} } } ``` | Property name | Property usage | | ------------------- | ------------------------------------------------------------------------------------------------------ | | `handle` | The extension\u2019s handle. | | `payload` | The fields that you selected for your payload schema in the action configuration. These should be serialized in a key-value pair format where the keys are equal to your field's \u201ckey\u201d properties. | > Note: > If you are using a Shopify admin API version of `2023-07` or earlier the mutation won't support the `handle` and `payload` properties. For information on that mutation shape you can rely on the [flowTriggerReceive documentation](\/docs\/api\/admin-graphql\/2023-07\/mutations\/flowTriggerReceive). ## Considerations When you create a trigger, the payload that you send to Shopify Flow needs to be [less than 1 MB and contain specific content](\/docs\/apps\/build\/flow\/triggers\/create#step 4 test your trigger) in the body. Triggers have the same [API rate limits](\/docs\/api\/usage\/rate limits) as the Shopify API."
],
"response":"To integrate Shopify App Bridge for handling custom configuration pages and utilize the mutation API for triggering workflows in Shopify Flow, follow these steps. This process allows app developers to enhance their app's functionality within Shopify, making the user experience smoother by automating certain tasks.\n\n### Step 1: Set Up Shopify App Bridge\nFirst, you need to integrate Shopify App Bridge in your app. Depending on which version you're using (check the version as it's crucial for proper integration), you can follow the guides provided in Shopify\u2019s documentation for setting up Shopify App Bridge or App Bridge React. This setup is essential for creating an interactive custom configuration page within your app.\n\n### Step 2: Implement a Custom Configuration Page\nAfter setting up Shopify App Bridge, you'll develop a custom configuration page. Use Shopify App Bridge to render this page within Shopify, specifically for configuring your app's settings or parameters. The custom configuration page can access and display relevant action and step information, which helps tailor the page based on specific workflow steps or properties.\n\n- **Add Additional Buttons:** You can enhance the App Bridge title bar with extra buttons for improved navigation or functionality.\n- **Trigger Redirects:** Implement functionality to return to the previous page, enhancing the user experience by simplifying navigation.\n\n### Step 3: Access Action and Property Information\nWithin the custom configuration page, utilize the available action information (like `step_reference`) and property data to display the appropriate content or options to the user. This step is crucial for a personalized and relevant configuration experience based on the specific action or workflow step.\n\n### Step 4: Utilize the Mutation API for Workflows\nYou can trigger Shopify Flow workflows via a mutation API call. Define an event with a handle and payload that match your workflow's requirements. The `handle` refers to your extension's identifier in the workflow, while the `payload` includes the data schema fields you've configured for your action. Follow the GraphQL mutation format provided in the documentation to properly format your API call.\n\n```graphql\nmutation {\n flowTriggerReceive(handle: \"your_event_handle\", payload: { \"YourField\": \"Value\", \"AnotherField\": 123 }) {\n userErrors {\n field\n message\n }\n }\n}\n```\n\nThis mutation API enables your app to programmatically trigger workflows in Shopify Flow, automating processes or actions based on the app's activities or user interactions.\n\n### In Summary:\n1. **Set up Shopify App Bridge:** Make sure it's correctly integrated with your app.\n2. **Build and Render a Custom Configuration Page:** Use it to adjust settings or parameters relevant to your app's workflow within Shopify.\n3. **Access and Use Action Information:** Tailor your configuration page based on the context (action steps and properties) provided by Shopify Flow.\n4. **Use the Mutation API:** Finally, automate workflows in Shopify Flow with the mutation API by providing the necessary handles and payloads.\n\nBy following these steps, you'll be able to integrate Shopify App Bridge effectively, create useful custom configuration pages, and automate workflows in Shopify Flow, enhancing the overall functionality and efficiency of your Shopify app.",
"reference":"A Shopify App Developer can integrate Shopify App Bridge to manage custom configuration pages by implementing the integration specific to their Shopify App Bridge version. For versions 4.X.X and up, developers can use the `shopify.intents` API to register to the Custom Configuration Page's intent, allowing access to property data and enabling navigation actions such as returning to the previous page using the `intent.finish()` method. For versions 3.X.X and down, developers need to subscribe to `APP::APP_FRAME::PROPERTIES_EVENT` and request properties by triggering the `APP::APP_FRAME::REQUEST_PROPERTIES` event. Additionally, developers can utilize the mutation API to trigger workflows in Shopify Flow by calling the `flowTriggerReceive` mutation with an event, which starts the workflow(s). The mutation requires a `handle` and `payload` in a key-value pair format, and developers must ensure that the payload is less than 1 MB and adheres to Shopify's API rate limits."
},
{
"user_input":"How can a Shopify app developer create and configure a Flow template extension to optimize store triggers and workflows?",
"retrieved_contexts":[
"A template in Shopify Flow is an example workflow that can be copied into a merchant's shop. Templates help merchants automate a specific use case with minimal or no additional configuration. Flow's template library offers hundreds of templates with features to filter, browse, and search. You can create a template for Shopify Flow that showcases your custom triggers and actions and help merchants do more.\n\nTo create a workflow template that merchants can add to their workflow list, you need to add a Flow template extension to your app.\n\n## Requirements\n\nA [development store](\/docs\/api\/development\n\nstores) that has [Shopify Flow](https:\/\/apps.shopify.com\/flow) and your app installed.\n\nYour existing custom triggers and actions are connected to your instance of Shopify Flow.\n\n[Shopify CLI](\/docs\/apps\/build\/cli\n\nfor\n\napps) installed with a version of `3.49` or higher.\n\n## Step 1: Create a workflow\n\nA workflow is the foundation of a Flow template.",
"> Note: > Each Flow template extension can contain only a single template. To deploy multiple templates, you will need to create an extension for each template.\n\nThe file structure of your extension should look like the following:\n\n```ssh\n\n\/your\n\nextension\n\nname\n\n\/locales\n\nen.default.json\n\nfr.json\n\nshopify.extension.toml\n\ntemplate.flow\n\n```\n\nTo learn more about the extensions file structure, refer to our [app structure](\/docs\/apps\/build\/cli-for-apps\/app-structure) documentation and the [documentation](\/docs\/apps\/build\/flow\/templates\/reference) for the Flow template extension type.\n\n## Step 3: Configure extension Configure your template extension to include information describing it's function for merchants, and settings that control visibility.",
"## Requirements\n\nA [development store](\/docs\/api\/development\n\nstores) that has [Shopify Flow](https:\/\/apps.shopify.com\/flow) and your app installed.\n\nYour existing custom triggers and actions are connected to your instance of Shopify Flow.\n\n[Shopify CLI](\/docs\/apps\/build\/cli\n\nfor\n\napps) installed with a version of `3.49` or higher.\n\n## Step 1: Create a workflow\n\nA workflow is the foundation of a Flow template.\n\n1. In your development store navigate to **Apps** > **Flow**. 2. Click **Create workflow**. 3. In the workflow editor, build a workflow that solves a merchant use case and showcases your custom trigger and or actions. 4. Optional: Tailor your template to a wider audience by [localizing your custom step descriptions](\/docs\/apps\/build\/flow\/templates\/reference#step-descriptions). 5. After you're satisfied with your workflow, [export the workflow](https:\/\/help.shopify.com\/en\/manual\/shopify-flow\/manage#export-a-workflow) and save the `.flow` file locally.",
"> Note: > - Remove any shop specific test data or replace with placeholder values if the merchant needs to provide a value. For example using the placeholder `YOUR_TAG_NAME` in a location where the merchant needs to provide a shop specific tag.<br \/> > - Don't edit `.flow` files directly. Only make changes within the Flow app and export the updated workflow.<br \/> > - Test your workflow thoroughly, ensuring the trigger, condition(s), and action(s) used provide the intended result.\n\n## Step 2: Create a Flow template extension\n\nUse the Shopify CLI to generate a new extension:\n\n1. Navigate to your app directory. 2. Run the following command:\n\n```bash\n\n#!\/bin\/bash\n\nshopify app generate extension\n\n```\n\n3. Select the `Flow Template` as the type of extension. 4. Provide a meaningful name for your extension.\n\nThe name that you provide displays in the Partners Dashboard. Follow these guidelines when choosing a name:\n\nDon't use punctuation.\n\nSeparate words using spaces.",
"Flow features [differ by plan](https:\/\/help.shopify.com\/en\/manual\/shopify-flow). For apps, the primary difference is that if you have a [custom app](https:\/\/help.shopify.com\/en\/manual\/apps\/app-types\/custom-apps), your Flow app extensions are available only to a [Shopify Plus](https:\/\/www.shopify.com\/plus) store that has your app installed.\n\n## Templates\n\nA template in Shopify Flow is an example workflow that can be copied into a merchant's shop. Templates help merchants automate a specific use case with minimal or no additional configuration. Flow's template library offers hundreds of templates with features to filter, browse, and search. You can [create a template](\/docs\/apps\/build\/flow\/templates\/create-a-template) for Shopify Flow that showcases your custom triggers and actions and help merchants do more.\n\n## Getting started"
],
"reference_contexts":[
"<1-hop>\n\nA template in Shopify Flow is an example workflow that can be copied into a merchant's shop. Templates help merchants automate a specific use case with minimal or no additional configuration. Flow's template library offers hundreds of templates with features to filter, browse, and search. You can create a template for Shopify Flow that showcases your custom triggers and actions and help merchants do more. To create a workflow template that merchants can add to their workflow list, you need to add a Flow template extension to your app. ## Requirements A [development store](\/docs\/api\/development stores) that has [Shopify Flow](https:\/\/apps.shopify.com\/flow) and your app installed. Your existing custom triggers and actions are connected to your instance of Shopify Flow. [Shopify CLI](\/docs\/apps\/build\/cli for apps) installed with a version of `3.49` or higher. ## Step 1: Create a workflow A workflow is the foundation of a Flow template. 1. In your development store navigate to **Apps** > **Flow**. 2. Click **Create workflow**. 3. In the workflow editor, build a workflow that solves a merchant use case and showcases your custom trigger and or actions. 4. Optional: Tailor your template to a wider audience by [localizing your custom step descriptions](\/docs\/apps\/build\/flow\/templates\/reference#step-descriptions). 5. After you're satisfied with your workflow, [export the workflow](https:\/\/help.shopify.com\/en\/manual\/shopify-flow\/manage#export-a-workflow) and save the `.flow` file locally. > Note: > - Remove any shop specific test data or replace with placeholder values if the merchant needs to provide a value. For example using the placeholder `YOUR_TAG_NAME` in a location where the merchant needs to provide a shop specific tag.<br \/> > - Don't edit `.flow` files directly. Only make changes within the Flow app and export the updated workflow.<br \/> > - Test your workflow thoroughly, ensuring the trigger, condition(s), and action(s) used provide the intended result. ## Step 2: Create a Flow template extension Use the Shopify CLI to generate a new extension: 1. Navigate to your app directory. 2. Run the following command: ```bash #!\/bin\/bash shopify app generate extension ``` 3. Select the `Flow Template` as the type of extension. 4. Provide a meaningful name for your extension. The name that you provide displays in the Partners Dashboard. Follow these guidelines when choosing a name: Don't use punctuation. Separate words using spaces. After you've followed the prompts, Shopify CLI generates the extension\u2019s file representation in your app's `\/extensions` directory and returns a success message. You can then go into your app's `\/extensions` directory and start editing your new extension. > Note: > Each Flow template extension can contain only a single template. To deploy multiple templates, you will need to create an extension for each template. The file structure of your extension should look like the following: ```ssh \/your extension name \/locales en.default.json fr.json shopify.extension.toml template.flow ``` To learn more about the extensions file structure, refer to our [app structure](\/docs\/apps\/build\/cli-for-apps\/app-structure) documentation and the [documentation](\/docs\/apps\/build\/flow\/templates\/reference) for the Flow template extension type. ## Step 3: Configure extension Configure your template extension to include information describing it's function for merchants, and settings that control visibility. 1. Update the [shopify.extension.toml configuration file](\/docs\/apps\/build\/flow\/templates\/reference#toml). 2. Update and add any additional locales. [Localization reference](\/docs\/apps\/build\/flow\/templates\/reference#localization). 3. Replace `template.flow` with the workflow [that you exported](\/docs\/apps\/build\/flow\/templates\/create-a-template#step-1-create-a-workflow). 4. Be sure to update the filename to match your chosen file path in the `shopify.extension.toml` file. `template.flow` is the default. ##",
"<2-hop>\n\nThis guide provides explanations of key topics for building and deploying a Flow template extension. This includes the TOML configuration file, localization, and the template approval process. ## TOML When you first create a new Flow template extensions through Shopify CLI, you get a basic version of the `shopify.extension.toml` file structure that looks like the following example: ```toml [[extensions]] name = \"t:name\" type = \"flow_template\" handle = \"example name\" description = \"t:description\" [extensions.template] categories = [\"orders\", \"risk\"] module = \".\/template.flow\" require_app = false discoverable = true enabled = true ``` ### Flow template extension fields | Property | Description | Rules | | ------------- | ---------------------------------------------------------------------------------- | ----------------- | | `name` <br><span class=\"heading-flag\">Required<\/span> | The title of the template. This property is translatable and will use the value for the key `name` in the translation files. | | | `type` <br><span class=\"heading-flag\">Required<\/span> | The type of your extension. This should always be set to `flow_template` for Flow templates.| - Value must be `flow_template`. | | `handle` <br><span class=\"heading-flag\">Required<\/span> | A globally-unique identifier for your extension. This property can't be changed after you\u2019ve run the [`app dev`](\/docs\/api\/shopify-cli\/app\/app-dev) or [`deploy`](\/docs\/api\/shopify-cli\/app\/app-deploy) command. | - Can't exceed 30 characters.<br \/> - Must only contain alphanumeric characters and hyphens. | | `description` <br><span class=\"heading-flag\">Optional<\/span> | The description of your template's workflow. This property is translatable and will use the value for the key `description` in the translation files. | | | `categories` <br><span class=\"heading-flag\">Required<\/span> | The categories that best describe the function of your template. | - Must be an array containing only strings of valid categories. <br \/> - Must choose at least one category. Max 2 recommended. <br \/> - Valid categories are: `buyer_experience`, `customers`, `inventory_and_merch`, `loyalty`, `orders`, `promotions`, `risk`, `fulfillment`, `b2b`, `payment_reminders`, `custom_data`, and `error_monitoring`. | | `module` <br><span class=\"heading-flag\">Required<\/span> | The file path of the template workflow in the extension's folder. | | `require_app` <br><span class=\"heading-flag\">Optional<\/span> | Whether your template is visible only to merchants who have your app installed. | - Defaults to `false`. | | `discoverable` <br><span class=\"heading-flag\">Optional<\/span> | Whether your template should be displayed in the template browser. When `false`, the template is accessible only through a deep link. | - Defaults to `true`. | | `enabled` <br><span class=\"heading-flag\">Optional<\/span> | Whether you template should be published and made available after being approved. | - Defaults to `true`. ## Localization Localizing your template by providing translated text allows a wider audience to understand your template better and can increase adoption. You can provide translations for the following fields: **`name` **: Title of the template. **`description` **: Description of the template and it's purpose. **`preInstallNote` **: (Optional): Instructions for merchants to complete before activating the workflow. This field should only be included if setup is required before the template can be turned on. [Custom step descriptions](#step descriptions) added within the workflow. ### Adding additional locales Add new `.json` files prefixed with the locale, for example `es.json`. Add `default` to one of the locales to make it the fallback if a merchant's locale isn't in the locales you have provided. Example: `en.default.json`. ### Step descriptions You can provide translated custom step descriptions by adding a translation key wrapped by curly braces in the step description field. For example, `{expressShippingCondition}`. Ensure there's no other characters before or after `{yourKey}`. After adding this to your workflow, you can update the translation files to include the step description. The following is an example: ! [How to format localized step descriptions in the Flow editor](\/assets\/apps\/flow\/localized_step_descriptions_in_flow_editor.png) ```json { \"name\": \"My Awesome Template! \", \"description\": \"A template that helps increase merchant productivity\", \"preInstallNote\": \"You must disable automatic payment capture in the Shopify Admin before using this template\", \"expressShippingCondition\": \"This step will check if the order uses express shipping\" } ``` ##"
],
"response":"To create and configure a Flow template extension that optimizes store triggers and workflows for merchants, follow these straightforward steps:\n\n### Step 1: Ensure Prerequisites\n1. **Development Store with Shopify Flow**: Have a development store with Shopify Flow and your app installed. This is where you'll test and build your workflow.\n2. **Custom Triggers and Actions**: Make sure your app's custom triggers and actions are already integrated into Shopify Flow.\n3. **Shopify CLI Installed**: Ensure you have Shopify Command Line Interface (CLI) installed on your computer, version 3.49 or higher.\n\n### Step 2: Create a Workflow\n1. **Open Shopify Flow**: Go to **Apps** > **Flow** in your development store.\n2. **Create Workflow**: Click on **Create workflow**.\n3. **Build the Workflow**: Design a workflow that addresses a specific merchant need, integrating your custom triggers and actions.\n4. **Localize if Necessary**: Optionally, make your workflow accessible to more users by adding translations for custom step descriptions.\n5. **Export the Workflow**: After perfecting your workflow, export it to a `.flow` file and save it on your computer. Make sure to use generic placeholders for any merchant-specific data.\n\n### Step 3: Create a Flow Template Extension\n1. **Open Your App Directory**: Using a terminal or command prompt, navigate to the folder where your app's code is stored.\n2. **Generate New Extension**: Run the command `shopify app generate extension` to start creating a new extension.\n3. **Choose Extension Type**: When prompted, select `Flow Template` as the extension type.\n4. **Name Your Extension**: Give your extension a clear, concise name without punctuation, using spaces to separate words.\n\n### Step 4: Configure Extension\n- **Describe Its Function and Visibility**: Edit your extension to include a description of what it does for merchants and set its visibility options. This usually involves editing the `shopify.extension.toml` file and possibly localizing descriptions in the `\/locales` folder.\n- **File Structure**: Your extension should have a specific file structure with the exported `.flow` file, `shopify.extension.toml`, and any localization files housed properly.\n- **Test Thoroughly**: Before finalizing, ensure your workflow operates as intended and provides the correct outcomes based on the triggers and actions.\n\n### Note:\n- Each Flow template extension can only contain one template. If you want to offer multiple templates, you'll need a separate extension for each.\n- Remember, editing `.flow` files directly is discouraged. Always make modifications within the Flow app and then re-export.\n\nBy following these steps, you can create a Flow template extension that helps Shopify merchants by automating store triggers and workflows, streamlining operations, and enhancing efficiency.",
"reference":"To create and configure a Flow template extension, a Shopify app developer should first create a workflow in their development store by navigating to Apps > Flow and building a workflow that showcases custom triggers and actions. After exporting the workflow as a .flow file, the developer should use the Shopify CLI to generate a new extension by running the command 'shopify app generate extension' and selecting 'Flow Template' as the type. The developer must then configure the extension by updating the shopify.extension.toml file, adding any additional locales for localization, and replacing 'template.flow' with the exported workflow. The extension should be configured to include information describing its function for merchants and settings that control visibility, ensuring it is discoverable and enabled for use."
},
{
"user_input":"How can a Shopify App Developer utilize the Shopify CLI to create and configure a Flow template extension, and what are the key considerations for setting up the TOML configuration file for a trigger extension?",
"retrieved_contexts":[
"When you create a new trigger extension using Shopify CLI, a basic version of the TOML configuration file structure is generated. In this guide, you'll learn about configuring the different sections and properties of the configuration file, including extension properties, extension fields, reference field types, custom field types, and more.\n\nThis guide will also inform you how to make HTTP requests to Flow to start the workflows in which your extension is the trigger.\n\n## TOML\n\n> Note: > Creating Flow extensions using Shopify CLI is an exciting new feature that is currently in development. As with any developing feature, it's important to note that the Flow's CLI capabilities will continue to evolve and improve over time. Developers can expect additional functionality, enhancements, and improvements to be added as development progresses. > >To create Flow extensions using [Shopify CLI](https:\/\/www.npmjs.com\/package\/@shopify\/cli), ensure you have the latest version installed.",
"This guide provides explanations of key topics for building and deploying a Flow template extension. This includes the TOML configuration file, localization, and the template approval process.\n\n## TOML\n\nWhen you first create a new Flow template extensions through Shopify CLI, you get a basic version of the `shopify.extension.toml` file structure that looks like the following example:\n\n```toml\n\n[[extensions]]\n\nname = \"t:name\"\n\ntype = \"flow_template\"\n\nhandle = \"example\n\nname\"\n\ndescription = \"t:description\"\n\n[extensions.template]\n\ncategories = [\"orders\", \"risk\"]\n\nmodule = \".\/template.flow\"\n\nrequire_app = false\n\ndiscoverable = true\n\nenabled = true\n\n```\n\n### Flow template extension fields",
"When you create a new trigger extension using Shopify CLI, you'll get a basic version of the TOML configuration file structure which should look like the following example:\n\n```bash\n\n[[extensions]]\n\nname = \"Auction Bid\"\n\ntype = \"flow_trigger\"\n\nhandle = \"auction\n\nbid\"\n\ndescription = \"Your description\"\n\n[settings]\n\n[[settings.fields]]\n\ntype = \"customer_reference\"\n\n[[settings.fields]] type = \"single_line_text_field\" key = \"your field key\" ```\n\n### Trigger extension properties\n\nExtension properties are listed in the `[[extensions]]` section and enable you to define the interface between Flow and your event.",
"en.default.json\n\nfr.json\n\nshopify.extension.toml\n\ntemplate.flow\n\n```\n\nTo learn more about the extensions file structure, refer to our [app structure](\/docs\/apps\/build\/cli-for-apps\/app-structure) documentation and the [documentation](\/docs\/apps\/build\/flow\/templates\/reference) for the Flow template extension type.\n\n## Step 3: Configure extension Configure your template extension to include information describing it's function for merchants, and settings that control visibility.\n\n1. Update the [shopify.extension.toml configuration file](\/docs\/apps\/build\/flow\/templates\/reference#toml). 2. Update and add any additional locales. [Localization reference](\/docs\/apps\/build\/flow\/templates\/reference#localization). 3. Replace `template.flow` with the workflow [that you exported](\/docs\/apps\/build\/flow\/templates\/create-a-template#step-1-create-a-workflow). 4. Be sure to update the filename to match your chosen file path in the `shopify.extension.toml` file. `template.flow` is the default.",
"## Step 2: Create a Flow template extension\n\nUse the Shopify CLI to generate a new extension:\n\n1. Navigate to your app directory. 2. Run the following command:\n\n```bash\n\n#!\/bin\/bash\n\nshopify app generate extension\n\n```\n\n3. Select the `Flow Template` as the type of extension. 4. Provide a meaningful name for your extension.\n\nThe name that you provide displays in the Partners Dashboard. Follow these guidelines when choosing a name:\n\nDon't use punctuation.\n\nSeparate words using spaces.\n\nAfter you've followed the prompts, Shopify CLI generates the extension\u2019s file representation in your app's `\/extensions` directory and returns a success message. You can then go into your app's `\/extensions` directory and start editing your new extension.\n\n> Note: > Each Flow template extension can contain only a single template. To deploy multiple templates, you will need to create an extension for each template.\n\nThe file structure of your extension should look like the following:\n\n```ssh\n\n\/your"
],
"reference_contexts":[
"<1-hop>\n\nA template in Shopify Flow is an example workflow that can be copied into a merchant's shop. Templates help merchants automate a specific use case with minimal or no additional configuration. Flow's template library offers hundreds of templates with features to filter, browse, and search. You can create a template for Shopify Flow that showcases your custom triggers and actions and help merchants do more. To create a workflow template that merchants can add to their workflow list, you need to add a Flow template extension to your app. ## Requirements A [development store](\/docs\/api\/development stores) that has [Shopify Flow](https:\/\/apps.shopify.com\/flow) and your app installed. Your existing custom triggers and actions are connected to your instance of Shopify Flow. [Shopify CLI](\/docs\/apps\/build\/cli for apps) installed with a version of `3.49` or higher. ## Step 1: Create a workflow A workflow is the foundation of a Flow template. 1. In your development store navigate to **Apps** > **Flow**. 2. Click **Create workflow**. 3. In the workflow editor, build a workflow that solves a merchant use case and showcases your custom trigger and or actions. 4. Optional: Tailor your template to a wider audience by [localizing your custom step descriptions](\/docs\/apps\/build\/flow\/templates\/reference#step-descriptions). 5. After you're satisfied with your workflow, [export the workflow](https:\/\/help.shopify.com\/en\/manual\/shopify-flow\/manage#export-a-workflow) and save the `.flow` file locally. > Note: > - Remove any shop specific test data or replace with placeholder values if the merchant needs to provide a value. For example using the placeholder `YOUR_TAG_NAME` in a location where the merchant needs to provide a shop specific tag.<br \/> > - Don't edit `.flow` files directly. Only make changes within the Flow app and export the updated workflow.<br \/> > - Test your workflow thoroughly, ensuring the trigger, condition(s), and action(s) used provide the intended result. ## Step 2: Create a Flow template extension Use the Shopify CLI to generate a new extension: 1. Navigate to your app directory. 2. Run the following command: ```bash #!\/bin\/bash shopify app generate extension ``` 3. Select the `Flow Template` as the type of extension. 4. Provide a meaningful name for your extension. The name that you provide displays in the Partners Dashboard. Follow these guidelines when choosing a name: Don't use punctuation. Separate words using spaces. After you've followed the prompts, Shopify CLI generates the extension\u2019s file representation in your app's `\/extensions` directory and returns a success message. You can then go into your app's `\/extensions` directory and start editing your new extension. > Note: > Each Flow template extension can contain only a single template. To deploy multiple templates, you will need to create an extension for each template. The file structure of your extension should look like the following: ```ssh \/your extension name \/locales en.default.json fr.json shopify.extension.toml template.flow ``` To learn more about the extensions file structure, refer to our [app structure](\/docs\/apps\/build\/cli-for-apps\/app-structure) documentation and the [documentation](\/docs\/apps\/build\/flow\/templates\/reference) for the Flow template extension type. ## Step 3: Configure extension Configure your template extension to include information describing it's function for merchants, and settings that control visibility. 1. Update the [shopify.extension.toml configuration file](\/docs\/apps\/build\/flow\/templates\/reference#toml). 2. Update and add any additional locales. [Localization reference](\/docs\/apps\/build\/flow\/templates\/reference#localization). 3. Replace `template.flow` with the workflow [that you exported](\/docs\/apps\/build\/flow\/templates\/create-a-template#step-1-create-a-workflow). 4. Be sure to update the filename to match your chosen file path in the `shopify.extension.toml` file. `template.flow` is the default. ##",
"<2-hop>\n\nWhen you create a new trigger extension using Shopify CLI, a basic version of the TOML configuration file structure is generated. In this guide, you'll learn about configuring the different sections and properties of the configuration file, including extension properties, extension fields, reference field types, custom field types, and more. This guide will also inform you how to make HTTP requests to Flow to start the workflows in which your extension is the trigger. ## TOML > Note: > Creating Flow extensions using Shopify CLI is an exciting new feature that is currently in development. As with any developing feature, it's important to note that the Flow's CLI capabilities will continue to evolve and improve over time. Developers can expect additional functionality, enhancements, and improvements to be added as development progresses. > >To create Flow extensions using [Shopify CLI](https:\/\/www.npmjs.com\/package\/@shopify\/cli), ensure you have the latest version installed. When you create a new trigger extension using Shopify CLI, you'll get a basic version of the TOML configuration file structure which should look like the following example: ```bash [[extensions]] name = \"Auction Bid\" type = \"flow_trigger\" handle = \"auction bid\" description = \"Your description\" [settings] [[settings.fields]] type = \"customer_reference\" [[settings.fields]] type = \"single_line_text_field\" key = \"your field key\" ``` ### Trigger extension properties Extension properties are listed in the `[[extensions]]` section and enable you to define the interface between Flow and your event. | Property name | Description | Rules | | --------------------------- | ------------------------------------------------------------- | -------------------------------------- | | `name` <br><span class=\"heading-flag\">Required<\/span> | Name of your extension. Will be the merchant-facing name of your task in the editor. This should be something that is human readable. | | | `type` <br><span class=\"heading-flag\">Required<\/span> | The type of your extension. This should always be set to \u201cflow_trigger\u201d for Flow triggers. | - Value must be `flow_trigger`. | `handle` <br><span class=\"heading-flag\">Required<\/span> | A unique identifier for your extension. This property cannot be changed once you\u2019ve run the `dev` or `deploy` command. | - Cannot exceed 30 characters.<br \/> - Must be unique across your app's extensions. <br \/> - Must only contain alphanumeric characters and hyphens. | | `description` <br><span class=\"heading-flag\">Optional<\/span> | A description of your extension. This description will be shown in the Flow editor navigation panel. | | ### Trigger extension fields Trigger extension fields are listed in the `[settings]` section, with each field using a `[[settings.field]]` header. These fields define the payload your event will send to Flow. You can add more than one field to your Flow trigger. The order of the fields in the TOML file is preserved when they're being rendered in the editor configuration panel. When sending a trigger payload, all fields defined in a trigger are required. | Property name | Description | Rules | | ------------------------------ | --------------------------------------------------------------------------------------------------- | --------------------------------| | `type` <br><span class=\"heading-flag\">Required<\/span> | The field type. | - [Accepted custom field types](#custom-field-types).<br> - [Accepted reference field types](#reference-field-types). | | `key` <br><span class=\"heading-flag\">Optional<\/span> | A unique key that identifies your field. This should be human readable since it will appear in the Flow editor in the environment picker menu. | - Required for custom field types. <br \/> Should only contain alphabetic values or spaces. <br \/> - This property is not valid for reference field types. | | `description` <br><span class=\"heading-flag\">Required<\/span> | A description of the field. This will appear in the Flow editor configuration panel. | ###"
],
"response":"Apologies, but it seems there was an interruption in the provided context. However, I'll summarize how to use Shopify CLI for creating and configuring a Flow template extension, and the key considerations for setting up the TOML configuration file for a trigger extension, based on the provided information.\n\n### Utilizing Shopify CLI for Flow Template Extension\n\n1. **Installation**: Ensure you have the latest version of Shopify CLI installed since creating Flow extensions is a new feature.\n\n2. **Generating a New Extension**:\n - Navigate to your app's directory.\n - Run `shopify app generate extension` in your terminal.\n - Choose `Flow Template` as the extension type and provide a name following the guidelines (avoid punctuation, separate words with spaces).\n - Shopify CLI will then create the extension in your app's `\/extensions` directory.\n\n3. **Editing the TOML Configuration File**:\n - Initially, Shopify CLI generates a basic TOML configuration file (`shopify.extension.toml`). You'll need to adjust this file to define the interface between Flow and your event.\n - Include descriptive information about the extension, control its visibility (e.g., `discoverable`, `enabled`), and assign it to categories (like `\"orders\"`, `\"risk\"`).\n\n### Key Considerations for TOML Configuration File:\n\n- **Extension Properties**: These include `name`, `type`, `handle`, and `description`. They are critical for defining how the extension interacts with Flow and how it's represented within the Shopify system.\n\n- **Extension Fields**:\n - For a trigger extension, you can define custom fields within the `[settings.fields]` section. Examples of field types are `customer_reference` and `single_line_text_field`. These fields determine the data your extension can accept or process.\n - You must accurately set these fields according to what your extension is designed to trigger on or collect.\n\n- **Template and Localization**:\n - Replace the `template.flow` file with your exported workflow and ensure this is correctly referenced in the TOML file.\n - Consider localizing your extension by adding additional locales beyond `en.default.json`, like `fr.json`, for a more accessible merchant experience.\n\n- **Visibility and Function Description**:\n - Be clear and concise in your descriptions to effectively communicate the extension's purpose to merchants.\n - Properly configure settings like `discoverable` and `enabled` to control how and when your extension appears to users.\n\n### Final Suggestions:\n\n- **Follow Documentation**: Always refer back to Shopify's official documentation for [Flow template extensions](https:\/\/shopify.dev\/docs\/apps\/build\/flow\/templates\/reference#toml) and the [Shopify CLI](https:\/\/www.npmjs.com\/package\/@shopify\/cli) for the most current information and detailed guidelines.\n- **Test Extensively**: Before finalizing your extension, thoroughly test it to ensure it triggers workflows as expected and interacts seamlessly with other components within Shopify Flow.\n\nBy carefully setting up your TOML configuration and adhering to Shopify's guidelines for extension development, you can effectively create and deploy Flow template extensions that enhance the automation capabilities for Shopify merchants.",
"reference":"A Shopify App Developer can utilize the Shopify CLI to create a Flow template extension by first navigating to their app directory and running the command `shopify app generate extension`, selecting 'Flow Template' as the type of extension. This process generates the extension\u2019s file representation in the app's `\/extensions` directory. The developer must then configure the extension by updating the `shopify.extension.toml` configuration file, adding any additional locales, and replacing `template.flow` with the exported workflow. Key considerations for setting up the TOML configuration file for a trigger extension include defining the extension properties such as `name`, `type`, `handle`, and `description` in the `[[extensions]]` section. The `type` must be set to 'flow_trigger', and the `handle` must be unique across the app's extensions. Additionally, trigger extension fields are defined in the `[settings]` section, where each field uses a `[[settings.field]]` header, specifying the field type and a unique key for custom field types. These configurations ensure the proper interface between Flow and the event, allowing the extension to function as intended."
},
{
"user_input":"How can a Shopify App Developer utilize the Partner Dashboard to create and manage Flow template extensions and Flow actions, ensuring seamless integration with Shopify Flow?",
"retrieved_contexts":[
"shopify.extension.toml\n\n```\n\nTo learn more about the extensions file structure, refer to [App structure](\/docs\/apps\/build\/cli-for-apps\/app-structure) and the documentation for your extension type.\n\n### Using the Partner Dashboard\n\n1. In your Partner Dashboard, click [Apps](https:\/\/partners.shopify.com\/current\/apps). 2. Select the app that you want to add your Shopify Flow action to. 3. Click **Extensions**, then click **Create** or **Create extension**. 4. Under the **Flow** tab, click **Flow\/Actions**. 5. In the **Extension name** field, name your action, such as `Place auction bid`. This name is used only for internal purposes. 6. Enter a title and description for the action. In the **Action Preview** area, you can see how the title and action display to merchants when they're choosing actions in Shopify Flow. 7. Enter the URL for the action execution endpoint that you created. Shopify Flow sends the action's JSON payload to this endpoint when it's about to execute your action.",
"### Requirements\n\nCreate a [Partner account](https:\/\/www.shopify.com\/partners).\n\n[Scaffold an app that uses Shopify CLI v3.70.0 or higher](\/docs\/apps\/build\/scaffold\n\napp), or [migrate your existing app](\/docs\/apps\/build\/cli\n\nfor\n\napps\/migrate\n\nto\n\nlatest\n\ncli) so it's compatible with Shopify CLI v3.70.0 or higher.\n\n[Migrate a Partner Dashboard\n\nmanaged app](\/docs\/apps\/build\/cli\n\nfor\n\napps\/migrate\n\nfrom\n\ndashboard).\n\n## Step 1: Import your Flow task extension locally\n\n> Note: > The command in this procedure only generates the local file representation of your Partner Dashboard extensions. Running the `deploy` command migrates your extensions to CLI managed-extensions. You can only import extensions that have versions. The published version is imported, if one exists. Otherwise, the latest version is imported.\n\n1. Navigate to your app directory. 1. To start importing your Flow extension, run the following command:\n\n```bash\n\n#!\/bin\/bash\n\nshopify app import\n\nextensions\n\n```",
"### Using the Partner Dashboard\n\n1. Open your [Partner Dashboard](https:\/\/partners.shopify.com). 2. Click the app that you want to add your Shopify Flow trigger to. 3. Click **Extensions**, then click **Create** or **Create extension**. 4. Under **Flow**, click the **Flow\/Triggers** card. 5. Enter an internal extension name for your trigger and click **Save**. 6. Enter a title and description for the trigger that will be shown to merchants. 7. Copy the GraphQL endpoint that displays under the **Trigger description** field to a text file. Your app uses this endpoint to send your POST request to Shopify Flow. The endpoint follows the format `https:\/\/{shop}.myshopify.com\/admin\/api\/latest\/graphql.json`. 8. In the **Request body properties** section, click **Add property**, choose a data type, and create the properties that display in Shopify Flow when a merchant chooses your trigger.\n\n## Step 2: Customize a Flow trigger configuration file",
"A template in Shopify Flow is an example workflow that can be copied into a merchant's shop. Templates help merchants automate a specific use case with minimal or no additional configuration. Flow's template library offers hundreds of templates with features to filter, browse, and search. You can create a template for Shopify Flow that showcases your custom triggers and actions and help merchants do more.\n\nTo create a workflow template that merchants can add to their workflow list, you need to add a Flow template extension to your app.\n\n## Requirements\n\nA [development store](\/docs\/api\/development\n\nstores) that has [Shopify Flow](https:\/\/apps.shopify.com\/flow) and your app installed.\n\nYour existing custom triggers and actions are connected to your instance of Shopify Flow.\n\n[Shopify CLI](\/docs\/apps\/build\/cli\n\nfor\n\napps) installed with a version of `3.49` or higher.\n\n## Step 1: Create a workflow\n\nA workflow is the foundation of a Flow template.",
"This guide provides explanations of key topics for building and deploying a Flow template extension. This includes the TOML configuration file, localization, and the template approval process.\n\n## TOML\n\nWhen you first create a new Flow template extensions through Shopify CLI, you get a basic version of the `shopify.extension.toml` file structure that looks like the following example:\n\n```toml\n\n[[extensions]]\n\nname = \"t:name\"\n\ntype = \"flow_template\"\n\nhandle = \"example\n\nname\"\n\ndescription = \"t:description\"\n\n[extensions.template]\n\ncategories = [\"orders\", \"risk\"]\n\nmodule = \".\/template.flow\"\n\nrequire_app = false\n\ndiscoverable = true\n\nenabled = true\n\n```\n\n### Flow template extension fields"
],
"reference_contexts":[
"<1-hop>\n\nA template in Shopify Flow is an example workflow that can be copied into a merchant's shop. Templates help merchants automate a specific use case with minimal or no additional configuration. Flow's template library offers hundreds of templates with features to filter, browse, and search. You can create a template for Shopify Flow that showcases your custom triggers and actions and help merchants do more. To create a workflow template that merchants can add to their workflow list, you need to add a Flow template extension to your app. ## Requirements A [development store](\/docs\/api\/development stores) that has [Shopify Flow](https:\/\/apps.shopify.com\/flow) and your app installed. Your existing custom triggers and actions are connected to your instance of Shopify Flow. [Shopify CLI](\/docs\/apps\/build\/cli for apps) installed with a version of `3.49` or higher. ## Step 1: Create a workflow A workflow is the foundation of a Flow template. 1. In your development store navigate to **Apps** > **Flow**. 2. Click **Create workflow**. 3. In the workflow editor, build a workflow that solves a merchant use case and showcases your custom trigger and or actions. 4. Optional: Tailor your template to a wider audience by [localizing your custom step descriptions](\/docs\/apps\/build\/flow\/templates\/reference#step-descriptions). 5. After you're satisfied with your workflow, [export the workflow](https:\/\/help.shopify.com\/en\/manual\/shopify-flow\/manage#export-a-workflow) and save the `.flow` file locally. > Note: > - Remove any shop specific test data or replace with placeholder values if the merchant needs to provide a value. For example using the placeholder `YOUR_TAG_NAME` in a location where the merchant needs to provide a shop specific tag.<br \/> > - Don't edit `.flow` files directly. Only make changes within the Flow app and export the updated workflow.<br \/> > - Test your workflow thoroughly, ensuring the trigger, condition(s), and action(s) used provide the intended result. ## Step 2: Create a Flow template extension Use the Shopify CLI to generate a new extension: 1. Navigate to your app directory. 2. Run the following command: ```bash #!\/bin\/bash shopify app generate extension ``` 3. Select the `Flow Template` as the type of extension. 4. Provide a meaningful name for your extension. The name that you provide displays in the Partners Dashboard. Follow these guidelines when choosing a name: Don't use punctuation. Separate words using spaces. After you've followed the prompts, Shopify CLI generates the extension\u2019s file representation in your app's `\/extensions` directory and returns a success message. You can then go into your app's `\/extensions` directory and start editing your new extension. > Note: > Each Flow template extension can contain only a single template. To deploy multiple templates, you will need to create an extension for each template. The file structure of your extension should look like the following: ```ssh \/your extension name \/locales en.default.json fr.json shopify.extension.toml template.flow ``` To learn more about the extensions file structure, refer to our [app structure](\/docs\/apps\/build\/cli-for-apps\/app-structure) documentation and the [documentation](\/docs\/apps\/build\/flow\/templates\/reference) for the Flow template extension type. ## Step 3: Configure extension Configure your template extension to include information describing it's function for merchants, and settings that control visibility. 1. Update the [shopify.extension.toml configuration file](\/docs\/apps\/build\/flow\/templates\/reference#toml). 2. Update and add any additional locales. [Localization reference](\/docs\/apps\/build\/flow\/templates\/reference#localization). 3. Replace `template.flow` with the workflow [that you exported](\/docs\/apps\/build\/flow\/templates\/create-a-template#step-1-create-a-workflow). 4. Be sure to update the filename to match your chosen file path in the `shopify.extension.toml` file. `template.flow` is the default. ##",
"<2-hop>\n\nTo create an action that merchants can use in their workflows, you need to add the action to your app. The action needs to contain the following information: The fields that the merchant needs to complete when they add the action to their workflows The URL that Shopify Flow uses to send (POST) the contents (JSON payload) of the action to your app You also need to configure your app to process the data from the POST request when it arrives and to send status codes back to Shopify Flow. To enhance the merchant experience and more closely integrate external systems, you can also [build a custom configuration page](\/docs\/apps\/build\/flow\/actions\/build-config-ui). To improve the reliability of your action, you can add [custom validation](\/docs\/apps\/build\/flow\/actions\/endpoints#custom-validation) for action properties. ## Requirements You have the following: A test web server that has access to the Internet, so that it can receive POST requests from Shopify Flow A test app that works with the test web server A development store that has [Shopify Flow](https:\/\/apps.shopify.com\/flow) and the test app installed ## Step 1: Create a Flow Action To give your Flow action a meaningful name, use the following guidelines: Use a present tense verb + object acted on format. For example, `Place auction bid`. Use sentence case. Don't use punctuation. Separate words using spaces. ### Using Shopify CLI Use the Shopify CLI to generate a new extension: 1. Navigate to your app directory. 2. Run the following command: ```bash #!\/bin\/bash shopify app generate extension ``` 3. Select the `Flow Action` as the type of extension. 4. Provide a meaningful name for your extension. After you've followed the prompts, Shopify CLI generates the extension\u2019s file representation in your app's `\/extensions` directory and gives you a success message. You can then go into your app's `\/extensions` directory and start editing your new extension. The file structure of your extension should look like the following: ``` \/place auction bid shopify.extension.toml ``` To learn more about the extensions file structure, refer to [App structure](\/docs\/apps\/build\/cli-for-apps\/app-structure) and the documentation for your extension type. ### Using the Partner Dashboard 1. In your Partner Dashboard, click [Apps](https:\/\/partners.shopify.com\/current\/apps). 2. Select the app that you want to add your Shopify Flow action to. 3. Click **Extensions**, then click **Create** or **Create extension**. 4. Under the **Flow** tab, click **Flow\/Actions**. 5. In the **Extension name** field, name your action, such as `Place auction bid`. This name is used only for internal purposes. 6. Enter a title and description for the action. In the **Action Preview** area, you can see how the title and action display to merchants when they're choosing actions in Shopify Flow. 7. Enter the URL for the action execution endpoint that you created. Shopify Flow sends the action's JSON payload to this endpoint when it's about to execute your action. ## Step 2: Customize a Flow action configuration file In this section you'll use the default action template and update it to be a functional extension example. Once you have generated a Flow extension using Shopify CLI, follow the instructions below: 1. Change the description to `Place a bid on an auction`. 2. Update the `extensions.runtime_url` to an endpoint where you can receive the runtime request. 3. On the second `settings.fields` field, update the following values: - `type` to `number_decimal` - `key` to `amount` - `name` to `Bid Amount` - Add a `description` property and set it to `The amount of the bid` ```bash [[extensions]] name = \"Place Auction Bid\" type = \"flow_action\" handle = \"place-bid\" description = \"Place a bid on an auction\" runtime_url = \"https:\/\/your-server-domain\/path\/to\/action\/handler\" [settings] [[settings.fields]] type = \"customer_reference\" required = true [[settings.fields]] type = \"number_decimal\" key = \"amount\" name = \"Bid Amount\" description = \"The amount of the bid\" required = true ``` ##"
],
"response":"To utilize the Partner Dashboard for creating and managing Flow template extensions and Flow actions for seamless integration with Shopify Flow, follow these straightforward steps:\n\n### Step 1: Set Up Your Development Environment\n- Before getting started, ensure you have a Shopify Partner account and your app environment is ready and meets the requirements (Shopify CLI v3.70.0 or higher).\n- If you have an existing app, migrate it to be compatible with the necessary Shopify CLI version.\n\n### Step 2: Create and Manage Extensions\n1. **Import Flow Extension Locally**: Use the Shopify CLI to import your Flow task extension into your local development environment. This helps prepare your extension for deployment.\n \n2. **Using the Partner Dashboard to Create Extensions**:\n - Access your [Partner Dashboard](https:\/\/partners.shopify.com), and navigate to the specific app you want to enhance with Shopify Flow capabilities.\n - Under **Extensions**, opt to create a new extension.\n - If creating a **Flow Action**: Choose **Flow\/Actions**, fill in the internal name, title, description, and provide the URL for the action execution endpoint. This will be where Shopify Flow sends the action's JSON payload.\n - If creating a **Flow Trigger**: Select the **Flow\/Triggers** card, provide names and descriptions pertinent to your trigger, and note the provided GraphQL endpoint for your POST request.\n\n### Step 3: Customize Flow Extensions\n- **For Triggers**: Customize your trigger's configuration file to define the data properties that will appear in Shopify Flow when selected by merchants. \n- **For Actions**: Ensure your action's endpoint is secure and capable of handling the JSON payload from Shopify Flow efficiently.\n\n### Step 4: Create a Workflow Template\n- To showcase your custom triggers and actions through a Flow template, first create a workflow that outlines a specific automation process.\n- Use the `shopify.extension.toml` file to configure your Flow template extension, detailing the name, type, description, and relevant categories. Make sure to enable and set your template as discoverable if you wish for it to be available for merchant use.\n\n### Step 5: Deploy and Test\n- After configuring your extension, use Shopify CLI to deploy it. Testing is vital; ensure your custom triggers and actions perform as intended within Shopify Flow. Utilize a development store with both Shopify Flow and your app installed for testing.\n\n### Key Points to Remember:\n- **Scaffolding and Compatibility**: Your app and development setup should comply with the latest Shopify CLI requirements.\n- **Partner Dashboard Navigation**: Use the Partner Dashboard for a smooth creation and management process of your Flow extensions.\n- **Extension Configuration**: The `shopify.extension.toml` file plays a crucial role in defining the properties and capabilities of your Flow template extension.\n- **Testing**: Before launch, thoroughly test your Flow triggers and actions to ensure they work seamlessly for merchants.\n\nBy following these streamlined steps, Shopify App Developers can effectively create and manage Flow template extensions and Flow actions, enhancing their apps\u2019 integration with Shopify Flow and automating business processes for merchants.",
"reference":"A Shopify App Developer can utilize the Partner Dashboard to create and manage Flow template extensions and Flow actions by following a structured process. To create a Flow template extension, the developer must first create a workflow in their development store by navigating to Apps > Flow and using the workflow editor to build a workflow that showcases custom triggers and actions. After exporting the workflow, the developer uses the Shopify CLI to generate a new extension, selecting 'Flow Template' as the type. The extension's name, which appears in the Partners Dashboard, should be meaningful and follow specific naming guidelines. The developer then configures the extension by updating the shopify.extension.toml configuration file and replacing the template.flow with the exported workflow. For creating Flow actions, the developer can use the Partner Dashboard to add the action to their app by selecting the app, clicking Extensions, and then creating a new Flow action under the Flow tab. The action requires a meaningful name, a title, and a description, and the developer must provide the URL for the action execution endpoint. This process ensures that the app is configured to process data from POST requests and send status codes back to Shopify Flow, facilitating seamless integration with Shopify Flow."
}
] |