## Before you begin In this workshop you'll learn how to leverage the different tasks and capabilities of Shopify Flow in your app projects. Using the Remix app template that's generated using Shopify CLI, we'll build and call a trigger, and demonstrate how to test triggers and create flow templates. This workshop covers the following topics: - [Building, calling and testing triggers](#build-a-trigger) - [Building and validating actions](#build-an-action) - [Sharing templates from existing workflows](#offer-a-template) ## Prerequisites - Create a [Shopify Partner account](https://www.shopify.com/partners) - Create a development store populated with test data - [Installed Node.js 18 or higher](https://nodejs.org/en/download/) or higher - Install [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) - Install the latest version of Chrome or Firefox - Install a text editor such as [Visual Studio Code](https://code.visualstudio.com/) - Install latest version of [Shopify CLI](/docs/api/shopify-cli#installation) - Install an app generated by the Shopify CLI using the Remix template and JavaScript - [Shopify Flow app](https://apps.shopify.com/flow) on your development store - Set up an API tool like CURL or [Postman](https://www.postman.com/) ## Getting set up First scaffold an app by running: ```bash shopify app init ```
Next, in order to send customer data in this workshop, you need the `write_customers` scope. Let’s add that first, because it requires a full deploy and we might not want to deploy everything later. 1. `cd` to the folder of the app you’ve initialized. 2. Open the directory in your favorite text editor. 3. In the `shopify.app.toml` file, update the `scopes` to include `write_customers`:

4. Do an initial deployment of the app. This is necessary to deploy the required app configuration, including [access scopes](https://shopify.dev/docs/api/usage/access-scopes). From the app folder, run: ```bash shopify app deploy ``` 5. Follow the CLI prompts to create a new app and release a version:
6. Next, launch the app in development mode by running: ```bash shopify app dev ``` 7. Follow the CLI prompts to select your Partner organization, and connect to the app you just created (don’t create a new one):
8. Press `p` or click the app preview link. Follow the process for installing the app in your store. 9. You should end with something looking like this:
## Build a trigger ### Build the trigger definition To generate the app extension: 1. First stop the app dev server. 2. Generate the extension by running: ```bash shopify app generate extension ``` 3. Choose `Flow trigger`
4. Add a meaningful name, like `Auction bid placed`. 5. In your code editor, open the file under `extensions / auction-bid-placed / shopify.extension.toml`.

> Note: > The `handle` is like an ID - don't change it after you do `app dev` or `app deploy`. Want to experiment? Check out what [types are available](https://shopify.dev/docs/apps/build/flow/triggers/reference#reference-field-types). 7. Make sure to save the file when you are done. 8. To preview your trigger: ```bash shopify app dev ``` 9. To verify everything looks good, open your Shopify admin and go to the Shopify Flow app. 10. Add your trigger and a “Log output” action. There you will see:
11. Click **Turn on** to activate this workflow, so you can later see it running. ### Triggering the trigger We should have access to the customer scope, so now we just need to write the code to call the trigger. ***Add a button trigger in Remix*** 1. Open the file `app / routes / app._index.jsx`. 2. Delete the `action` function, and replace it with the following. This code will run when a button is pressed and will send a request to the GraphQL Admin API for the trigger.

3. On the `customer_id` line, substitute a customer id from your own shop. 4. To add a new button to the page, we're going to use a Remix hook called `useFetcher`. To the top of the file, add `useFetcher` to the list of imports:

5. In the `Index` function, add:

6. Finally, to show the button and trigger status, in the `return()` of the `Index` function, add a new `BlockStack` inside of the first ``:

Alternative: if you want to remove a bunch the boiler plate code, you can delete the whole `Index` function and replace it with this:

8. The button should now show in your app:
Or if you replaced the code block as in the alternative example:
9. **Click the button** to send a trigger in the app. It should run the workflow that you previously built. To see the run, open your workflow and look at the "runs”.
> Note: > To save time, we are going to leave the existing code in place, but you might want to remove that code later. ## Build an action Next, let’s build an action using a similar process. ### Build the action definition 1. First stop the app dev server. 2. Generate the extension: ```bash shopify app generate extension ``` 3. Choose `Flow action`
4. Name your action, something like “Place bid”. 5. Open the file `extensions / place-bid / shopify.extension.toml`. 6. Like the trigger, configure the file:

> Note: > Wait to set the `runtime_url` field until after you run `app dev`. This is better because running `app dev` will create a new tunnel URL anyway. Handle is like an ID - don't change it after you do `app dev` or `app deploy`. Change it now or never. 7. **Save the file** when you are done. 8. Preview your action by running: ```bash shopify app dev ``` 9. To preview your action, open your Shopify admin and go to the Shopify Flow app. 10. Open your previous workflow and add your action. The workflow should look something like this:
> Note: > When using `shopify app dev`, the tasks configuration is updated in real time for any workflow drafts. If the workflow is active, then you must update the workflow to use the newest version of the task. You can do this by making any change to the workflow and clicking **Apply changes**. ### Listen for the action #### Overview Next, let’s make the action call code in your app. To do this we’ll need to: - Build an endpoint to handle the action - Verify the endpoint is callable via an API tool like Postman - Update URL in action, if necessary, to make it work end-to-end - Trigger a workflow to start and call the action #### Steps 1. In the app / routes directory, create a new file called `actions.place-bid.jsx`. 2. In the file, put the following:

This route has just an action handler, since it's not being used to display a page. It will be callable by submitting a POST request to: `/actions/place-bid` The `BASE_URL` is the URL of your app, which you can find in the `shopify.app.toml` file. For example:

4. Using your preferred HTTP client, try calling this endpoint now at the URL by using POST to: `/actions/place-bid`. You should see your `console.log`, but it will fail the HMAC validation with a `4xx` error. If you want to see it run successfully, you can comment out these lines:

Before moving to the next step, make sure to uncomment the validation link. 5. Now that you have a running action handler, in your action’s `shopify.extension.toml` file, update your action’s `runtime_url` to the tunnel URL and save the file:

6. Now, let’s try the action in Flow. Open the Flow editor. Using the action you added previously, change the Amount field (or make any change to the workflow in order to refresh the configuration to use your URL).
> Note: You can use any trigger that provides a customer, like Customer created. 7. To make your changes live, click **Apply changes**. 8. Run the workflow by clicking the trigger button in your app. You should see your action run successfully in Flow and in your app logs. ### Advanced Action Handing: Preventing duplicates (optional) In some scenarios, like when your server returned a 5xx type error, Shopify Flow may send a request more than once. If you already handled a particular bid, you don’t want to do it again. This section shows you how to prevent duplicates using storage in Remix. 1. In order to store data, we need to add a database table. Open the directory `prisma` and the file `schema.prisma`. 2. Add the following model: This model allows you to store the details that you get from Shopify Flow.

3. To create the table in your SQLite database, run: ```bash npm run prisma migrate dev -- --name add-action-run-table ``` >Note: > You can use npm, pnpm, or yarn. 4. To confirm the table was added, you can view your database by running: ```bash npm run prisma studio ``` Go to the opened browser tab and confirm your table is available. 5. Now you’ll need a way to store data in the table. Let’s add a model. First, create a folder for `app / models`. 6. In the folder, add a file, `flow.server.js` 7. In the flow, we are gong to add 3 functions: - checkActionRun - checks if an action run is already in the database - getActionRuns - gets a list of the actions runs to display in your UI - createActionRun - adds a new action run to the database

8. Now let’s make use of this server by using using it in your action code, in the `actions.place-bid.jsx` file:

9. Test that this code works by executing your workflow again. You should see a new row in your database. 10. To display a list of the runs on your Remix front-end, you can edit the `app._index.jsx` file like:

11. Confirm that the list is displaying in the app. ## Offer a template As a Partner, you can offer templates in [Shopify Flow’s template library](https://shopify.dev/docs/apps/build/flow/templates/reference). Let’s try that out. ### Guidelines for creating a template Templates should: - Be as complete as possible (more complete templates get used more often) - Follow Shopify Flow naming conventions - Include a thorough description - Be tested in your shop ### Create a template extension 1. Build the workflow. For this use case, you can use a workflow that you built for the above exercises. 2. Download the workflow’s `.flow` file by going to the summary page for the template, click **More actions**, and then **Export**.
3. Generate an extension in the Shopify CLI: ```bash shopify app generate extension ``` 4. Choose `Flow template` and give the template an internally meaningful name, such as `Place bid template`. 5. Open the new directory, such as `place-bid-template`, in your code editor. 6. To make sure of your template, drag in your downloaded `.flow` into the same directory. 7. Delete the old `workflow.flow` file in the directory. 8. Next, open the file, `shopify.extension.toml` 9. In the file, edit the `module` to point to your download file name. Alternative: rename the file to `workflow.flow`.

10. You don't need to edit the `handle`, `categories`, and visibility settings (`require_app`, `discoverable`, and `enabled`) for this exercise. Details about these settings can be found in the [Shopify Flow documentation](https://shopify.dev/docs/apps/build/flow/templates/reference). >Note: >You cannot change the handle after you run `app dev` or `app deploy`. You should not edit the name or description fields in this file.

11. To edit the `name` and `description`, open the file `locales/en.default.json`. This allows your template to be translated, depending on the user’s preferred language.

> Tip > Both title and description are searched using an LLM. Because of this, it helps to be descriptive about how something works and the use cases it solves, but you don't need to include “keywords”. 12. You can now preview the extension by running: ```bash shopify app dev ``` 13. Click the link or press, “p”. This should now open the dev console, where you can choose to go to view the template.
> Note: > If preview takes you to the app instead, you can use this URL syntax to find your template previews: `https://yourstoreurl/flow/editor/templates/dev` 14. Click the preview link for “Flow template” and you’ll see the preview (see below). If necessary, you can switch the template being previewed through the toolbar:
15. In the bottom-right corner, you can see a preview of how the template looks when merchants browse or search in the template library. 16. Deploy the app extension by running: ```bash shopify app deploy ``` 16. Don't do this step today, but in order to submit a real template, you must open your Partner Dashboard, choose your app, select **Versions**, and then **Submit for review**. The Shopify Flow team will then review the template. Before submitting, you should read [Shopify Flow’s approval criteria](https://shopify.dev/docs/apps/build/flow/templates/reference#approval-process).
17. Flow will contact your Partner organization via email once the template has been reviewed. If it's approved, you'll see an option to release the template. 🎉