Spaces:
Sleeping
Sleeping
File size: 209,534 Bytes
0d77f31 |
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 201 |
[
{
"user_input": "Howw doo I use the Shopify CLI to createe a neww extensionn for Shopify Floww actions?",
"retrieved_contexts": [
"## 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",
"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",
"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.",
"## Step 5: Deploy extension\n\nUse Shopify CLI to deploy your extension.\n\n1. Navigate to your app directory. 2. Run the following command to start deploying your extension(s):\n\n```bash\n\n#!/bin/bash\n\nshopify app deploy\n\n```\n\n3. Follow the command prompts\n\nWhen you receive confirmation that the deploy was successful, a new app version in your Partner Dashboard displays, where you can submit a request for review. After the request for review has been submitted and the [approval process](/docs/apps/build/flow/templates/reference#approval-process) is complete, you can release the new version from your Partner Dashboard and your templates will display in Flow's template library.",
"```\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"
],
"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 the Shopify CLI, follow these simplified steps:\n\n1. **Open Your App Directory**: The first thing you need to do is find the folder on your computer where your app is saved. This is known as navigating to your app directory.\n\n2. **Run the Shopify CLI Command**: Once you're in your app's folder, you need to open a command prompt or terminal window. Here, type the command `shopify app generate extension` and press enter. This tells Shopify's tools that you want to start making a new extension.\n\n3. **Choose the Extension Type**: The system will ask you what kind of extension you want to make. Since you're interested in Shopify Flow actions, you should select the `Flow Action` option when prompted. \n\n4. **Name Your Extension**: Give your extension a simple, straightforward name that follows these rules: use a present tense verb plus an object (like `Place auction bid`), don't use punctuation, and separate words with spaces. This name will appear in places like the Shopify Partners Dashboard, which is a tool for managing your apps and extensions.\n\nAfter these steps, the Shopify CLI will create a new folder within your app's `/extensions` directory. This folder, named after your new extension, contains all the files needed to customize and build your Flow action.\n\n- **Edit Your Extension**: You can now go into the newly created extension folder and start making changes to define exactly what your Flow action will do.\n\n- **File Structure of Your Extension**: Inside your extension's folder, you'll find a few different files, including `shopify.extension.toml`, which is a configuration file for your extension. The other files and folders will depend on the specific needs of your Flow action.\n\nWhen you're ready to see your extension in action, don't forget the last step:\n\n- **Deploy Your Extension**: Go back to the command prompt or terminal in your app directory and run the command `shopify app deploy`. This sends your new extension to Shopify, making it available for use. Then, follow any prompts and wait for a success message.\n\nRemember to use the Partner Dashboard to manage testing, review processes, and eventually publish your extension to be used with Shopify Flow.",
"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": [
"## 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.",
"```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:",
"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",
"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:",
"### Callback events\n\nShopify Flow sends trigger lifecycle callbacks when the following events occur:\n\nWhen a merchant activates a workflow that uses your trigger, the callback contains `\"has_enabled_flow\": true`.\n\nWhen a merchant deactivates a workflow that uses your trigger, the callback contains `\"has_enabled_flow\": false`.\n\n### Web server response time and status codes\n\nWhen a merchant tries to enable a workflow that uses your trigger, Shopify Flow sends a trigger lifecycle callback to your web server. If your web server doesn't respond within five seconds, or if it responds with a different status code, then the merchant can't enable that workflow. The merchant receives a notification in the Shopify Flow app that tells them to try enabling the workflow at a later time.\n\n## 1. Configure your web server\n\nTo begin, configure your web server to listen for Shopify Flow callbacks."
],
"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 handle Shopify Flow actions on your web server, follow these straightforward steps:\n\n1. **Configure Your Web Server to Listen for Callbacks**: Set up a specific URL (endpoint) on your web server that will listen for Shopify Flow callbacks. This means when Shopify Flow triggers an action, it'll send information to this URL on your server.\n\n2. **Verify the HMAC Header**: For security, Shopify uses a HMAC (Hash-Based Message Authentication Code) in the HTTP headers when it sends data to your server. This code is in the `x-shopify-hmac-sha256` header. You'll need to check this code against your client secret (a secure key Shopify provides you) to ensure the data is really coming from Shopify. This process helps keep the information secure.\n\n3. **Ensure Quick Response**: Your server must acknowledge the receipt of the Shopify Flow callback quickly, specifically within 5 seconds. If it doesn't, Shopify assumes the callback failed.\n\nOnce configured to receive callbacks:\n\n- **Process and Store Callback Data**: Your web server should be ready to take the data Shopify sends (in the format specified in the \"extensions\" block you've set up, such as action to \"place a bid\") and process or store it as needed. This could involve recording a bid in a database or executing some business logic based on the callback data.\n\n- **Build a Shopify Flow Action**: Essentially, you are creating an action (like \"Place Auction Bid\") which needs to have specific fields defined (such as \"customer_reference\" and \"amount\" for a bid amount) that the merchant fills out in Shopify Flow. Your server should expect data in this structure when Shopify Flow actions are triggered.\n\n- **Responding to Shopify Flow**: When your server receives data from an action trigger, process the data accordingly and respond back with the correct HTTP status codes. This lets Shopify Flow know the action was received and processed correctly (or if there were any errors).\n\nIn summary, you're setting up your web server to:\n\n1. Listen for data from Shopify Flow.\n2. Securely verify that data using HMAC.\n3. Process the data quickly and respond appropriately.\n\nRemember to test this with a test server, app, and Shopify development store with Shopify Flow installed to ensure everything works smoothly before going live.",
"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.",
"### 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",
"## 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).",
"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:",
"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."
],
"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 simple steps:\n\n1. First, make sure you have your development environment set up with your test web server and your test app that can communicate with each other. Ensure Shopify Flow and your test app are installed on your development store.\n\n2. **Create a Flow Workflow**:\n - Go to your development store and navigate to Shopify Flow. Here's a direct link for convenience: [Create a Workflow in Shopify Flow](https://www.shopify.com/admin/apps/flow).\n - Start a new workflow by adding the trigger you've previously created as detailed in the Triggers guide. Then, add the action you want to test to this workflow.\n \n3. **Check for Custom Configurations**:\n - If your action includes a custom configuration page, make sure it displays correctly and is accessible as expected.\n - Also, verify any custom validations you have set up to ensure they are working properly.\n\n4. **Trigger the Workflow**:\n - To test the action, you need to trigger the workflow. This typically involves performing an action on your web server that sends the trigger information to Shopify Flow. This could be simulating an event that your action is designed to respond to.\n\n### Steps summarised for clarity:\n1. Navigate to Shopify Flow in your development store and create a workflow using your custom action.\n2. Ensure any custom configurations and validations work as expected.\n3. Trigger the workflow from your web server to see your action in action.\n\nFollowing these steps will help you test your Shopify Flow action in a development environment before launching it to ensure it works as intended.",
"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, 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.",
"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 4: Test your trigger\n\nAfter the [`app dev`](/docs/api/shopify-cli/app/app-dev) command has started, you can test the draft version of your trigger in Shopify Flow.\n\n1. In your development store, create a [workflow](https://www.shopify.com/admin/apps/flow) that uses the trigger that you created for your app.\n\n2. Using the Admin GraphQL API, send a `flowTriggerReceive` mutation with the following arguments:\n\nThe `handle` of the trigger\n\nThe `payload` of the trigger containing the fields defined in the extension TOML",
"## 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.",
"1. Save the list of stores that are using your triggers in a persistent datastore. Use the <code>timestamp</code> property to make sure that you don't overwrite an existing entry with older information. 2. Edit your application to send your triggers only to stores that are using your triggers.\n\n## 3. Configure the callback\n\nFinally, configure the callback in the CLI:\n\n1. Run `shopify app generate extension`. 2. Select `Flow trigger lifecycle callback`. 3. Change the URL in the generated TOML to the URL configured on the web server. 4. Run `shopify app deploy`.\n\n## Next steps\n\nFamiliarize yourself with [Shopify Flow](/docs/apps/build/flow) and learn about building connectors.\n\nConnect your app to Shopify Flow so that events that occur in your app can [trigger workflows](/docs/apps/build/flow/triggers).\n\nConnect your app to Shopify Flow so that your app receives data and information when a [workflow action](/docs/apps/build/flow/actions) runs."
],
"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": "To use TOML for creating new trigger extensions with Shopify CLI, follow these simple steps and focus on the key configurations:\n\n1. **Start by Installing Shopify CLI**: Make sure you have the latest version of Shopify CLI installed to leverage all features for creating trigger extensions.\n\n2. **Generate Your Trigger Extension**:\n - Navigate to your app directory.\n - Use the `shopify app dev` command to start drafting your extension.\n\n3. **Understanding TOML Configuration**: A `TOML` file is used to define how your extension interacts with Shopify Flow. It includes:\n - **Extension Properties**: Defined in the `[[extensions]]` section. Here you specify the basic info about your extension like `name`, `type`, `handle`, and `description`.\n - **Extension Fields**: In the `[settings]` section, fields are specified. These fields can be of different types like `customer_reference` or `single_line_text_field` for capturing input from the Flow.\n\n4. **Test Your Trigger**:\n - Create a workflow in Shopify Flow using your trigger.\n - Test the trigger by sending a `flowTriggerReceive` mutation via the Admin GraphQL API, including the `handle` and `payload`.\n\n5. **How Triggers Work**: Understand that a trigger initiates a workflow in Shopify Flow based on an event in your app or store.\n\n6. **Configure Callback**: This involves running `shopify app generate extension` and selecting `Flow trigger lifecycle callback`, setting up the correct callback URL in TOML, and deploying it.\n\n**Important Parts to Configure in TOML**:\n- **Name, Type, Handle, and Description**: These are crucial for identifying and describing what your trigger does.\n- **Settings and Fields**: Define the data your trigger will pass on to Shopify Flow, crucial for triggering the right actions.\n- **Callback URL**: Essential for real-time interactions and ensures that your app correctly receives data or commands from Shopify Flow.\n\n**Final Steps**:\n- After configuring and testing your trigger extension, familiarize yourself with Shopify Flow to better integrate your app, allowing it to trigger workflows or receive data from workflow actions.\n\nAlways ensure your TOML file reflects the specifics of your extension correctly to avoid any issues with Flow triggering or execution.",
"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": [
"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.",
"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:",
"<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).",
"[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\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": "Using Shopify App Bridge to render a custom configuration page in Shopify Flow is a useful feature for providing a tailored experience for merchants. Here is a simplified breakdown of what you need to do and understand based on the given context:\n\n1. **Set Up a Partner Account and Create an App -** Firstly, ensure you have a Shopify Partner account and have created an app. These are preliminary steps before you delve into specifics.\n\n2. **Understand Shopify App Bridge -** Shopify App Bridge is a tool that allows your app to interact seamlessly with Shopify's admin interface. To render pages or modify the interface in Shopify Flow, you will need to integrate your app with Shopify App Bridge.\n\n3. **Implement Shopify App Bridge in Your App -** To display your custom configuration page within Shopify Flow, you must integrate Shopify App Bridge on the specific page route you're targeting. You'll find detailed guidance on setting this up in Shopify's documentation. They provide resources for both general Shopify App Bridge setup and an App Bridge React version, should your application use React.\n\n4. **Accessing Action Information -** When your custom configuration page is rendered through Shopify App Bridge, Shopify Flow provides specific action information that you can leverage. This includes:\n - A `step_reference` search parameter, which is a unique identifier for the step within a workflow. This helps in identifying the request made by the merchant.\n - Property data as key-value pairs that include extension fields from your action payload schema. This data is crucial to displaying relevant information to merchants on your custom configuration page.\n\n5. **Adjustments and Customizations -** Beyond just rendering your page, Shopify App Bridge allows you to customize the page frame and add elements such as additional buttons to the title bar. This customization capability ensures a seamless and integrated user experience.\n\n6. **Register for Custom Configuration Page's Intent (For App Bridge Versions 4.X.X and Up) -** If you are using a version of App Bridge that is 4.X.X or later, you need to register to the Custom Configuration Page's intent. This process involves specific steps that are outlined in Shopify's documentation. Unfortunately, the exact steps aren't detailed in the provided context but are crucial for ensuring your app accurately renders and functions within Shopify Flow with the latest versions of App Bridge.\n\n**Summary:** Render a custom configuration page in Shopify Flow by integrating with Shopify App Bridge, adjusting your app to access and utilize action information provided by Shopify Flow, and customize the interface for an optimal merchant experience. Ensure your integration is aligned with the version of Shopify App Bridge you are using, particularly for versions 4.X.X and up, where registering to the Custom Configuration Page's intent is necessary.",
"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, 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.",
"1. Save the list of stores that are using your triggers in a persistent datastore. Use the <code>timestamp</code> property to make sure that you don't overwrite an existing entry with older information. 2. Edit your application to send your triggers only to stores that are using your triggers.\n\n## 3. Configure the callback\n\nFinally, configure the callback in the CLI:\n\n1. Run `shopify app generate extension`. 2. Select `Flow trigger lifecycle callback`. 3. Change the URL in the generated TOML to the URL configured on the web server. 4. Run `shopify app deploy`.\n\n## Next steps\n\nFamiliarize yourself with [Shopify Flow](/docs/apps/build/flow) and learn about building connectors.\n\nConnect your app to Shopify Flow so that events that occur in your app can [trigger workflows](/docs/apps/build/flow/triggers).\n\nConnect your app to Shopify Flow so that your app receives data and information when a [workflow action](/docs/apps/build/flow/actions) runs.",
"## 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.",
"### 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": [
"<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 the Shopify CLI, you basically have to follow a few steps that involve coding and configuration, but let me break it down for you:\n\n1. **Install Shopify CLI**: First, ensure you have the latest version of Shopify CLI installed. This tool helps developers interact with Shopify directly through the command line.\n\n2. **Generate the Extension**: Use the command `shopify app generate extension` in your command line. This creates the basic setup you'll need.\n\n3. **Select Trigger Lifecycle Callback**: When prompted, select the option for `Flow trigger lifecycle callback`. This is what tells Shopify your extension is meant to trigger workflows.\n\n4. **Configure Callback URL**: Inside the generated TOML file (a configuration file), change the callback URL to the web server URL you've set up that will handle the trigger logic. This URL is where Shopify Flow will send data when your trigger is activated.\n\n5. **Deploy Your Extension**: Run `shopify app deploy` to publish your trigger extension. Now it's live and ready to be used by the Flow workflows.\n\n### Supported Field Types for Payload Configuration\n\nFor designing your trigger's payload (the data your trigger will send to start the workflow), you can use various field types in the TOML configuration file. The example you provided shows two types:\n\n- **`customer_reference`**: This type likely allows you to reference a customer in the workflow, enabling actions to be taken specifically regarding customer data.\n \n- **`single_line_text_field`**: This allows for a simple text input that can be used to pass straightforward data like names, titles, identifiers, etc., to the workflow.\n\nEach field type you include will determine what information merchants can use when setting up workflows in Shopify Flow that are triggered by your extension.\n\nUsing the Shopify Partner Dashboard to finalize and test your new trigger will be crucial. From there, you can add to your app, specify titles, descriptions, and configure the properties that will show up for merchants using Shopify Flow.\n\nIn simple terms, by following the steps above, you're creating a small program (an extension) that Shopify Flow can trigger under certain conditions you stipulate. This extension uses the Shopify CLI for setup, and you define the trigger's characteristics and the data it works with in the TOML file. The field types in the TOML file help structure the data your trigger will deal with, making it easier to integrate your extension into practical workflows for Shopify merchants.",
"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.",
"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",
"1. Save the list of stores that are using your triggers in a persistent datastore. Use the <code>timestamp</code> property to make sure that you don't overwrite an existing entry with older information. 2. Edit your application to send your triggers only to stores that are using your triggers.\n\n## 3. Configure the callback\n\nFinally, configure the callback in the CLI:\n\n1. Run `shopify app generate extension`. 2. Select `Flow trigger lifecycle callback`. 3. Change the URL in the generated TOML to the URL configured on the web server. 4. Run `shopify app deploy`.\n\n## Next steps\n\nFamiliarize yourself with [Shopify Flow](/docs/apps/build/flow) and learn about building connectors.\n\nConnect your app to Shopify Flow so that events that occur in your app can [trigger workflows](/docs/apps/build/flow/triggers).\n\nConnect your app to Shopify Flow so that your app receives data and information when a [workflow action](/docs/apps/build/flow/actions) runs.",
"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 4: Test your trigger\n\nAfter the [`app dev`](/docs/api/shopify-cli/app/app-dev) command has started, you can test the draft version of your trigger in Shopify Flow.\n\n1. In your development store, create a [workflow](https://www.shopify.com/admin/apps/flow) that uses the trigger that you created for your app.\n\n2. Using the Admin GraphQL API, send a `flowTriggerReceive` mutation with the following arguments:\n\nThe `handle` of the trigger\n\nThe `payload` of the trigger containing the fields defined in the extension 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": "To use Shopify CLI for configuring a trigger extension for Shopify Flow, follow these straightforward steps and considerations for the TOML configuration file, involving custom and reference fields.\n\n### Step-by-Step Guide:\n\n1. **Install Shopify CLI**: Before you start, make sure you have the latest version of Shopify CLI installed. This tool will help you create and manage your Shopify Flow trigger extensions.\n\n2. **Create a New Trigger Extension**: Run `shopify app generate extension` in your terminal and select \"Flow trigger lifecycle callback\" when prompted. This step initializes a new trigger extension and generates a basic TOML configuration file.\n\n3. **Configure the TOML File**: The TOML (Tom's Obvious, Minimal Language) file is a configuration file that Shopify uses to understand how your trigger extension interacts with Shopify Flow. Here's what you need to edit:\n\n - **Extension Properties**: Within the `[[extensions]]` section, set properties like `name`, `type`, `handle`, and `description` to define your trigger's metadata.\n - **Extension Fields**: In the `[settings]` section, add `[[settings.fields]]` for each data field your trigger will pass to Flow. You can specify different field types:\n - **Reference Field Types** (`customer_reference`, etc.): These fields refer to Shopify objects. For example, a `customer_reference` points to a specific customer in Shopify.\n - **Custom Field Types** (`single_line_text_field`, etc.): These are fields for custom data you want to include. Specify a `key` for each custom field to uniquely identify it.\n\n4. **Set Up the Callback**: Change the callback URL in the TOML to the one configured on your web server. This URL will be used by Shopify to send data to your extension.\n\n5. **Deploy Your Extension**: Run `shopify app deploy` to deploy your trigger extension. Make sure your server is ready to receive callbacks from Shopify.\n\n6. **Test Your Trigger**: After deployment, use `shopify app dev` to start a development version of your extension. Create a workflow in your development store using your new trigger and test it using the Admin GraphQL API's `flowTriggerReceive` mutation with the required `handle` and `payload`.\n\n### Considerations:\n\n- **Reference vs. Custom Fields**: Decide carefully between using reference fields for Shopify objects versus custom fields for any additional data you need to trigger the workflow. Reference fields are straightforward for referencing existing Shopify entities, while custom fields offer flexibility for unique data.\n\n- **Field Data Structure and Validation**: Ensure the data structure for custom fields matches what your application expects, and validate the data before using it in your workflows.\n\n- **Version Updates**: Since Shopify CLI and Flow's capabilities are evolving, keep your Shopify CLI updated and stay informed on the latest features or changes that might affect your trigger extensions.\n\n- **Datastore for Stores List**: If your trigger needs to know which stores are using it, maintain a persistent list of these stores with timestamps to ensure you only send triggers to active subscribers.\n\nBy following these steps and considerations, you can effectively utilize Shopify CLI to create, configure, and deploy trigger extensions for Shopify Flow, enhancing the automation capabilities of your merchant's Shopify store.",
"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": [
"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.",
"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.",
"<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).",
"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.",
"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:"
],
"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": "To ensure security while integrating a custom configuration page in Shopify Flow using Shopify App Bridge, follow these guidelines:\n\n1. **Use HTTPS**: Always use HTTPS (HyperText Transfer Protocol Secure) for your app and custom configuration pages. HTTPS encrypts the data between the Shopify store and your app, protecting against eavesdropping and man-in-the-middle attacks.\n\n2. **Validate Requests**: Make sure to validate all requests coming to your custom configuration page. Shopify uses security mechanisms like HMAC (Hash-Based Message Authentication Code) to ensure that the request is coming from Shopify. Check Shopify's documentation for specific parameters you can validate against.\n\n3. **Sanitize Inputs**: Whenever you're accepting input on your custom configuration page, sanitize this input to prevent SQL injection, cross-site scripting (XSS), and other common web vulnerabilities. Only allow the type of data you expect (e.g., text, number) and use libraries or functions to clean the input.\n\n4. **Use App Bridge Securely**: When using Shopify App Bridge, ensure that you're implementing it according to the version-specific guidelines provided by Shopify. This includes securely authenticating your app with Shopify, using session tokens for API requests, and ensuring that communication between your app and Shopify is secure.\n\n5. **Restrict Access**: Limit the access to your custom configuration page to only the users who should have access. Implement checks to ensure that the user accessing the page has the necessary permissions within Shopify.\n\n6. **Session Handling**: Implement secure session handling. Use secure, HttpOnly cookies for managing sessions and ensure that session tokens are invalidated when users log out or after a certain period of inactivity.\n\n7. **Monitor and Update**: Regularly monitor your app for security vulnerabilities and keep both your app and any libraries or frameworks it uses updated. Shopify and other software providers frequently update their tools to address new security concerns.\n\nBy following these best practices, you can significantly reduce the risk of security vulnerabilities in your app when integrating a custom configuration page into Shopify Flow using Shopify App Bridge.",
"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": [
"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.",
"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.",
"[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",
"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)."
],
"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 Shopfiy App Bridge for managing custom configuration pages and utilizing the mutation API to trigger workflows in Shopify Flow, here's a straightforward plan:\n\n1. **Setup Shopify App Bridge:** First, ensure your app is set up with Shopify App Bridge. If you're starting, use the guides for \"[Getting started with Shopify App Bridge](/docs/api/appbridge/previousversions/appbridgetfromnpm/appsetup)\" or \"[Getting started with App Bridge React](/docs/api/appbridge/library#react)\" depending on your development environment. This will allow your app to communicate efficiently with Shopify's admin.\n\n2. **Render Your Custom Configuration Page:** Utilize Shopify App Bridge to render your custom configuration page within Shopify Flow. This means when your app's custom action is added to a Shopify Flow workflow, your configuration page will appear within the Shopify admin, allowing the merchant to configure the action. Refer to the section on using Shopify App Bridge to render your app page for specific implementation details according to your Shopify App Bridge version.\n\n3. **Access Action Information:** On your custom configuration page, you can access specific action information available from Shopify Flow, such as `step_reference` and property data. `step_reference` is a unique identifier for the workflow step, and property data contains the fields from your action payload schema as key-value pairs. Use this information to display relevant configuration options or default values on your custom configuration page.\n\n4. **Customize Page Frame and Navigation:** You can enhance the merchant's experience by customizing the App Bridge title bar. This may include adding additional buttons for actions (e.g., save, cancel) or a button to return to the previous page, improving navigation and usability within your custom configuration page.\n\n5. **Trigger Workflows via Mutation API:** While the context provided doesn\u2019t elaborate on the mutation API, integrating it typically involves using Shopify App Bridge actions or Shopify\u2019s Admin API to trigger or modify workflows. This might be based on input or configurations made on your custom configuration page. For triggering actions or mutations, you would usually send a request to Shopify\u2019s backend with the necessary payload, which would then enact the changes or trigger the workflow as designed in Shopify Flow.\n\n6. **Testing and Iteration:** Once implemented, test your custom configuration page thoroughly to ensure it integrates seamlessly with Shopify Flow, renders properly within the Shopify admin, and can interact with your app's backend as intended. Pay attention to the merchant's experience, making sure it's intuitive and provides value in automating or enhancing their workflow.\n\nRemember, this plan is based solely on the context provided and aims to offer a simplified approach to integrating Shopify App Bridge for custom configuration pages in Shopify Flow.",
"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": [
"[Shopify Flow](https://apps.shopify.com/flow) is an app that allows merchants to customize their store through automation. As a developer, you can integrate your app with the Flow platform through custom tasks, such as triggers and actions.\n\n! [A workflow for a low stock notification displaying a trigger, condition, and action](/assets/apps/flow/example-workflow-inventory-quantity-changed.png)\n\nThis guide introduces you to the different extensions you can create, building a Flow trigger and action, and considerations when making changes to your extensions.\n\n## Why build for Flow",
"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.",
"## 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",
"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",
"### 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": [
"<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 for Shopify to enhance store triggers and workflows, follow these simplified steps. This guidance aims to reduce technical complexity and focus on key actions you can take to achieve your goal.\n\n### Step 1: Create Your Workflow\nBegin with designing the workflow you intend to automate. Think about the trigger (what initiates the workflow), the conditions (if any) that must be met, and the actions (what the workflow does). Use an existing workflow you have, or design a new one that matches the automation you want to provide to merchants.\n\n### Step 2: Set Up Your Development Environment\nBefore creating a Flow template extension, ensure you have:\n- A development store with both Shopify Flow and your app installed.\n- The Shopify CLI (Command Line Interface) installed, version 3.49 or higher.\n\n### Step 3: Generate a New Flow Template Extension\n1. Open your command line tool and navigate to your app\u2019s directory.\n2. Use Shopify CLI to generate a new extension by running: `shopify app generate extension`.\n3. Choose `Flow Template` when prompted for the type of extension.\n4. Give your extension a clear, descriptive name without punctuation, using spaces to separate words.\n\nAfter these steps, you will find your new extension in the `/extensions` folder of your app\u2019s directory. This is where you can customize it further.\n\n### Building Your Extension\n- **Customize the Trigger**: Every Flow begins with a trigger. In your `/extensions` directory, customize the trigger by defining what event will start your Flow. Use clear and concise titles and descriptions for your trigger, so it\u2019s easy for merchants to understand its purpose.\n- **Define Actions**: After the trigger, specify what actions your Flow will perform. This could be anything from sending an email notification to updating a database or creating a task.\n- **Test Your Workflow**: Ensure that your Flow template works as intended by testing it within your development store.\n\n### Considerations\n- Your Flow app extensions are only available to Shopify Plus stores that have your app installed if it's a custom app.\n- Each Flow template extension can contain only a single template. If you wish to offer multiple templates, you will need to create multiple extensions.\n\nRemember, the goal of your Flow template is to help merchants automate specific tasks with minimal setup. By focusing on creating straightforward, valuable templates, you can enhance the merchant experience on Shopify.",
"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.",
"## 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",
"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."
],
"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": "To create and configure a Flow template extension using the Shopify CLI, and to set up the TOML configuration file for a trigger extension, here\u2019s a straightforward step-by-step guide:\n\n1. **Install Shopify CLI:** First, ensure you have the Shopify CLI installed. This tool helps you manage Shopify app and theme development right from your terminal.\n\n2. **Generate a New Extension:**\n - Open your terminal and navigate to your app directory.\n - Run `shopify app generate extension`.\n - Choose `Flow Template` as the extension type.\n - Provide a name for your extension. Avoid punctuation and use spaces to separate words.\n\n After completing these steps, the CLI will create a basic file structure in the `/extensions` directory of your app.\n\n3. **Understand the TOML File:** The TOML file (`shopify.extension.toml`) is where you define your extension's properties\u2014this includes its name, description, type, and various settings related to visibility and functionality. Here are key sections you\u2019ll deal with:\n - `[[extensions]]`: Here, you define basic information such as the extension's name (`name`), type (`type`), handle (`handle`), and description (`description`).\n - `[extensions.template]`: This section is specific for template extensions. It includes settings like categories (`categories`), module path (`module`), and visibility/enabled status (`discoverable`, `enabled`).\n\n4. **Configure Extension Properties:**\n Your extension's functionality and how it interacts with Shopify Flow are defined within this TOML file. For a trigger extension, you might see something like:\n\n```toml\n[[extensions]]\nname = \"Auction Bid\"\ntype = \"flow_trigger\"\nhandle = \"auction bid\"\ndescription = \"Your description\"\n\n[settings]\n[[settings.fields]]\ntype = \"customer_reference\"\n[[settings.fields]]\ntype = \"single_line_text_field\"\nkey = \"your field key\"\n```\n\n Here, you configure what your trigger will do, what kind of information it handles, and how it appears within Shopify Flow.\n\n5. **Customize and Add Fields:**\n - For trigger extensions, use the `[settings]` and `[[settings.fields]]` to define what data your trigger will accept or provide to Flow workflows.\n - Field types such as `customer_reference` or `single_line_text_field` specify what kind of data can be passed along.\n\n6. **Localization and Additional Configurations:**\n - Add any necessary locale files for different languages, ensuring your extension can be used in various markets.\n - Replace the default `template.flow` with your custom workflow file and ensure the `shopify.extension.toml` file is updated to point to this new file.\n\n7. **Review and Deployment:**\n - After setting up your TOML configuration and ensuring all files are correctly placed and named, review your extension to ensure it meets your requirements.\n - Use Shopify CLI commands to deploy your extension to Shopify.\n\n**Key Considerations:**\n- Keep the TOML file updated as your extension evolves.\n- Ensure the `type` field matches the extension you are developing (`flow_template` for template extensions, `flow_trigger` for trigger extensions).\n- Regularly test your extension to ensure it operates as expected within Shopify Flow.\n- Pay attention to localization if your app targets merchants in different regions.\n\nFollowing these steps and considerations will help in successfully utilizing Shopify CLI to create and configure Flow template extensions effectively.",
"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": [
"### 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",
"[Shopify Flow](https://apps.shopify.com/flow) is an app that allows merchants to customize their store through automation. As a developer, you can integrate your app with the Flow platform through custom tasks, such as triggers and actions.\n\n! [A workflow for a low stock notification displaying a trigger, condition, and action](/assets/apps/flow/example-workflow-inventory-quantity-changed.png)\n\nThis guide introduces you to the different extensions you can create, building a Flow trigger and action, and considerations when making changes to your extensions.\n\n## Why build for 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.",
"**Improved visibility\n\n**: Merchants can discover your templates or tasks in Flow, even if they don't have your app installed. Additionally, when you integrate with Flow, you receive a\n\n**Works with Flow\n\n** badge on your listing in the Shopify App Store. Your app will also be listed in the [Flow app directory](https://apps.shopify.com/collections/connectors\n\nfor\n\nshopify\n\nflow).\n\n## What you can build\n\nAs a Partner you can build one or more tasks related to your app for your merchants to use. These merchants need to have both your app and Shopify Flow installed. Shopify Flow includes the following task types:",
"**Improve integrations between your app, Shopify, and other apps\n\n**: Any task you build can be used with the triggers and actions that Flow already provides, which immediately connects your app to thousands of new features.\n\n**Save development time\n\n**: Rather than building and maintaining direct integrations with many other apps, you can integrate with Flow and provide similar value to your merchants.\n\n**Improved visibility\n\n**: Merchants can discover your templates or tasks in Flow, even if they don't have your app installed. Additionally, when you integrate with Flow, you receive a\n\n**Works with Flow\n\n** badge on your listing in the Shopify App Store. Your app will also be listed in the [Flow app directory](https://apps.shopify.com/collections/connectors\n\nfor\n\nshopify\n\nflow).\n\n## What you can build"
],
"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 use the Partner Dashboard for creating and managing Flow template extensions and actions, follow these steps for seamless integration with Shopify Flow:\n\n### Creating a Flow Trigger:\n1. **Access the Partner Dashboard**: Go to your [Partner Dashboard](https://partners.shopify.com).\n2. **Select Your App**: Choose the app you want to add your Shopify Flow trigger to.\n3. **Navigate to Extensions**: Click on **Extensions**, then select **Create** or **Create extension**.\n4. **Focus on Flow**: Under the **Flow** section, select the **Flow/Triggers** card.\n5. **Define Your Trigger**: Enter a name for your internal use and save it. Then, input a title and a description that will show up to merchants.\n6. **Record the Endpoint**: Copy the GraphQL endpoint shown under **Trigger description** to a safe place. Your app will use this endpoint to send a POST request.\n7. **Configure Properties**: In the **Request body properties** section, add properties by clicking **Add property**. Choose a data type for each and name them. These properties will be visible in Shopify Flow for merchants selecting your trigger.\n\n### Creating a Flow Action:\n1. **Return to Partner Dashboard**: Go back to your dashboard and click on [Apps](https://partners.shopify.com/current/apps).\n2. **Choose Your App**: Select the app you want to integrate a Shopify Flow action into.\n3. **Extension Creation**: Click on **Extensions**, then select **Create** or **Create extension**. Navigate to the **Flow** tab and click on **Flow/Actions**.\n4. **Action Identification**: Name your action internally in the **Extension name** field, like `Place auction bid`.\n5. **Detail Your Action**: Provide a title and description for your action. Use the **Action Preview** to preview how your action will be displayed to merchants in Shopify Flow.\n6. **Setup Execution Endpoint**: Enter the URL for the action execution endpoint you've prepared. Shopify Flow will send a JSON payload to this endpoint to execute your action.\n\n### Why Build for Flow:\n- **Improved Integrations**: Link your app with Shopify and other apps through Flow, expanding feature accessibility.\n- **Save Development Time**: Instead of creating many direct integrations, use Flow to connect with various apps efficiently.\n- **Increase Visibility**: Get discovered by more merchants and earn a **Works with Flow** badge for your app in the Shopify App Store.\n\nCreating Flow template extensions and actions can greatly broaden the functionalities your app offers to Shopify merchants, ensuring your app integrates seamlessly into their workflow and automates business processes efficiently.",
"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."
}
]
|