Using the Stepped Reader

This guide will describe how to setup a stepped reader. We recommend that you have completed the Reading Data from Shopify - JSON Reader example as there are some concepts introduced and knowledge of the Shopify API is required.

This guide will be querying the Shopify API Orders endpoint.

https://help.shopify.com/api/reference/order

This guide will cover both the setup of the Seed List stepped reader and Parent to Child.

It should be noted this guide is a little contrived since we don't really need to use a stepped reader when querying Shopify. However, this guide attempts to show when a stepped reader is needed, and how it's configured.

The guide will cover three parts:

  • Setting up the Stepped Reader to Seed Values.
    • Shopify will be queried to obtain a list of each orders.
  • Setting up the Reader to use the Seed Values.
    • Shopify will then be queried to obtain the details for each order.
  • Parent to Child type stepping.
    • Shopify will be queried to obtain the payment/cash transactions associated with each order.

Step a – Add the JSON Reader

  1. Open the same integration as from the JSON Reader example and click on the Transform Setup tab; click on Readers; drag a JSON Reader onto the design palette and; double click to open the transform setup screen.
  2. Double click the JSON icon to open the transform setup screen.
  3. Select Http(s) URL from the Data Source drop down.
  4. Select the Shopify Webservice Behaviour.

Step b - Setting up the Seed List

In this step you will setup the seed list to read the ids of the orders. The ids will then be used to query Shopify for each order.

Query

To obtain the list ids we specify a similar query to the one used in JSON Reader example, but we append the fields parameter to return just the id for each order.
/admin/api/2019-04/orders.json?fulfillment_status=unshipped&fields=id

Response Data

Shopify returns the following data. Whilst this example is contrived, this type of result is very much representative of the data returned from a webservice when a stepped reader is needed, where the service returns a skeletal list of entries containing the id or url to the detail.

{
  "orders": [
    {
      "id": 1026786492481
    },
    {
      "id": 1026786033729
    },
    {
      "id": 494884520001
    }
  ]
}

Setup

  1. Enter /admin/api/2019-04/orders.json?fulfillment_status=unshipped&fields=id into the url.

  1. Click on the Field Mapping tab.
  2. The JSON Entry Path represents the path to obtain the order ids.

    Enter '/orders/id' (the path is highlighted in red as shown in the response).

Step c - Seed List to Reader Setup

In this step we will configure the Reader to use the seed list for input into the Reader.

Each id will be used to query Shopify to obtain the specific order.

Query

Shopify provides the means to obtain an order by it's url, in the form:

Response Data

When querying Shopify for a specific data it will return the data of the form below. It is important to note that when setting up the stepped reader, the JSON Paths are relevant to the stepped result/response.

{
  "order": {
    "id": 494884520001,
    "email": "[email protected]",
    "closed_at": null,
    "created_at": "2018-06-01T09:19:42+01:00",
    "updated_at": "2019-04-01T15:26:48+01:00",
    "number": 58,
    "note": "ORD000000000440",
    "token": "7b4ccb4d038d34e6db5fbcbe431edff1",
    "gateway": "Cash on Delivery (COD)",
    "test": false,
    "total_price": "28.00",
    "subtotal_price": "20.00",
    "total_weight": 2000,
    "total_tax": "3.33",
    "taxes_included": true,
    "currency": "GBP",
    "financial_status": "pending",
    "confirmed": true,
    "total_discounts": "0.00",
    "total_line_items_price": "20.00",
    "cart_token": "ccc342a35b707cee524e4e03826f678e",
    "buyer_accepts_marketing": false,

Setup Of Reader

  1. Each transaction type/level needs to be defined, and therein each field defined.
    Enter ‘Orders’ into the New Transaction Id text box and press the Add button [>] to create a transaction type and press the Edit button.

  2. Press the Edit button.
  3. To be able to query each order we need to enter a parametrised url. The stepped reader provides this through the IO Controller Path field. The value from the Seed list can be accessed through the %[SYS.ITEM] expando field. It is important to note that %SYS.ITEM is specific to Seed list stepping.

    Enter /admin/api/2019-04/orders/%[SYS.ITEM].json into the IO Controller Path.

  4. In the Transaction JSON Path enter "/order" (the path is shown in red in the response data). All fields and child JSON paths will be relative to this.

  5. Start simply to ensure the stepping is working, by adding a single field. We will use the id for each of the ‘open’ orders.
    • Field Name
      • Enter 'ID'
    • JSON Path
      • Enter 'id'.
      • The ‘id’ property is directly from the ‘order’ object so there is no need for any forward slashes.

  6. Press the Green tick to Save, and then press the Save button at the bottom of the screen.
  7. Press the Refresh button. Assuming that everything has been successful you should see the ids for each of unshipped orders.

    You could also at this point verify that each called is made, by checking the Trace file. What you should see, is the initial Seed URL is called, and then individual calls to obtain each order.

  8. Now that you have verified your reader is successfully working, you can now add the other fields and the OrderDetails and the from JSON Reader example (steps 8 - 13).

Step D - Parent to Child Stepped Reader

In this section you will configure the reader to obtain the Payment Records for each order (assuming they have any). The setup to achieve this is not too different than the Seed list setup.

To obtain the payments associated with each order, a separate call needs to be made to the Shopify Transactions API.

Query

https://help.shopify.com/en/api/reference/orders/transaction

The URL is parameterised with the order id.

Response Data

The below data is representative of the data returned by Shopify.

{
  "transactions": [
    {
      "id": 630321414209,
      "order_id": 494884520001,
      "kind": "sale",
      "gateway": "Cash on Delivery (COD)",
      "status": "pending",
      "message": "Pending the Cash on Delivery (COD) payment from the buyer",
      "created_at": "2018-06-01T09:19:42+01:00",
      "test": false,
      "authorization": null,
      "location_id": null,
      "user_id": null,
      "parent_id": null,
      "processed_at": "2018-06-01T09:19:42+01:00",
      "device_id": null,
      "receipt": {
      },
      "error_code": null,
      "source_name": "web",
      "amount": "28.00",
      "currency": "GBP",
      "admin_graphql_api_id": "gid:\/\/shopify\/OrderTransaction\/630321414209"
    }
  ]
}

Setup Of Reader

  1. Create a new Transaction Type ‘Payments’ and press the Edit button.

  2. Similarly to the Seed List, we use a parameterised url. Whereas Seed List stepping uses the specific %SYS.ITEM expando value, parent to child stepping is parametrised using any of the fields of the parent transaction type.

    In this example we will parameterise the url with the ID field from the Orders level.

    Enter /admin/api/2019-04/orders/%[ID]/transactions.json into the IO Controller Path.

  3. In the Transaction JSON Path enter "/transactions" (the path is shown in red in the response data). All fields and child JSON paths will again be relative to this.

  4. Now add the fields.
    Field NameJPath

    ID

    id

    Kind

    kind

    Amount

    amount

    Currency

    currency

  1. Press the Save button at the bottom of the screen and press Refresh.

    Assuming there are payments associated with the orders, there will be one of more Payment records as a child transaction to each order.

  2. Again the trace file can be used to verify or check the separate requests being made to Shopify.