Spaces:
Sleeping
Sleeping
File size: 124,976 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 |
[
{
"user_input":"Howw doo I use the Shopify CLI to createe a neww extensionn for Shopify Floww actions?",
"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 ``` ##"
],
"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.",
"synthesizer_name":"single_hop_specifc_query_synthesizer"
},
{
"user_input":"How do you configure a web server to handle Shopify Flow actions?",
"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). ##"
],
"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.",
"synthesizer_name":"single_hop_specifc_query_synthesizer"
},
{
"user_input":"How can I test an action created in the Partner Dashboard using Shopify Flow?",
"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."
],
"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.",
"synthesizer_name":"single_hop_specifc_query_synthesizer"
},
{
"user_input":"how do you use toml when making new trigger extensions with shopify cli and what are the important parts to configure?",
"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. | ###"
],
"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.",
"synthesizer_name":"single_hop_specifc_query_synthesizer"
},
{
"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?",
"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> ##"
],
"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.",
"synthesizer_name":"multi_hop_abstract_query_synthesizer"
},
{
"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?",
"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."
],
"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.",
"synthesizer_name":"multi_hop_abstract_query_synthesizer"
},
{
"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?",
"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."
],
"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.",
"synthesizer_name":"multi_hop_abstract_query_synthesizer"
},
{
"user_input":"How can a Shopify App Developer ensure security when integrating a custom configuration page in Shopify Flow using Shopify App Bridge?",
"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."
],
"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.",
"synthesizer_name":"multi_hop_abstract_query_synthesizer"
},
{
"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?",
"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."
],
"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.",
"synthesizer_name":"multi_hop_specific_query_synthesizer"
},
{
"user_input":"How can a Shopify app developer create and configure a Flow template extension to optimize store triggers and workflows?",
"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\" } ``` ##"
],
"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.",
"synthesizer_name":"multi_hop_specific_query_synthesizer"
},
{
"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?",
"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. | ###"
],
"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.",
"synthesizer_name":"multi_hop_specific_query_synthesizer"
},
{
"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?",
"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 ``` ##"
],
"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.",
"synthesizer_name":"multi_hop_specific_query_synthesizer"
}
] |