add task config option and update docs (#397)

docs/auto-tag-orders-that-contain-an-out-of-stock-item/README.md

@@ -2,7 +2,7 @@
 
 Tags: Auto-Tag, Orders, Out of Stock
 
-This task watches for newly-created orders, and checks each line item for that variant's total inventory quantity. If any are found with an inventory level of 0 or less, the task will add the tag of your choice to the order – and, optionally, will add a tag to the customer and to each product related to an out-of-stock line item.
+This task watches for new orders, and checks each line item for that variant's total inventory quantity. If any are found with an inventory level of 0 or less, the task will add the tag of your choice to the order, and optionally will add a tag to the customer and to each product related to an out-of-stock line item.
 
 * View in the task library: [tasks.mechanic.dev/auto-tag-orders-that-contain-an-out-of-stock-item](https://tasks.mechanic.dev/auto-tag-orders-that-contain-an-out-of-stock-item)
 * Task JSON, for direct import: [task.json](../../tasks/auto-tag-orders-that-contain-an-out-of-stock-item.json)
@@ -13,6 +13,7 @@ This task watches for newly-created orders, and checks each line item for that v
 ```json
 {
   "apply_this_order_tag__required": "",
+  "ignore_variants_marked_for_oversell__boolean": true,
   "apply_this_customer_tag": null,
   "apply_this_product_tag_for_each_out_of_stock_line_item": null
 }
@@ -30,7 +31,9 @@ shopify/orders/create
 
 ## Documentation
 
-This task watches for newly-created orders, and checks each line item for that variant's total inventory quantity. If any are found with an inventory level of 0 or less, the task will add the tag of your choice to the order – and, optionally, will add a tag to the customer and to each product related to an out-of-stock line item.
+This task watches for new orders, and checks each line item for that variant's total inventory quantity. If any are found with an inventory level of 0 or less, the task will add the tag of your choice to the order, and optionally will add a tag to the customer and to each product related to an out-of-stock line item.
+
+By default, this task will disregard the inventory levels of any variants which have the "Continue selling when out of stock" option enabled. Uncheck the "Ignore variants marked for oversell" task option to disable this exclusion.
 
 ## Installing this task
 

docs/auto-tag-orders-that-contain-an-out-of-stock-item/script.liquid

@@ -1,183 +1,209 @@
-{% comment %}
-  Preferred option order:
+{% assign apply_this_order_tag = options.apply_this_order_tag__required %}
+{% assign ignore_variants_marked_for_oversell = options.ignore_variants_marked_for_oversell__boolean %}
+{% assign apply_this_customer_tag = options.apply_this_customer_tag %}
+{% assign apply_this_product_tag = options.apply_this_product_tag_for_each_out_of_stock_line_item %}
 
-  {{ options.apply_this_order_tag__required }}
-  {{ options.apply_this_customer_tag }}
-  {{ options.apply_this_product_tag_for_each_out_of_stock_line_item }}
+{% comment %}
+  -- get product and variant data for all line items on this order
 {% endcomment %}
 
-{% assign cursor = nil %}
-{% assign out_of_stock_line_items = array %}
-
-{% for n in (0..100) %}
-  {% capture query %}
-    query {
-      order(id: {{ order.admin_graphql_api_id | json }}) {
-        id
-        tags
-        {% if options.apply_this_customer_tag != blank %}
-          customer {
+{% assign out_of_stock_products = array %}
+
+{% capture query %}
+  query {
+    order(id: {{ order.admin_graphql_api_id | json }}) {
+      id
+      tags
+      {% if apply_this_customer_tag != blank %}
+        customer {
+          id
+          tags
+        }
+      {% endif %}
+      lineItems(first: 250) {
+        nodes {
+          name
+          product {
             id
+            title
             tags
+            tracksInventory
           }
-        {% endif %}
-        lineItems(
-          first: 250
-          after: {{ cursor | json }}
-        ) {
-          pageInfo {
-            hasNextPage
-          }
-          edges {
-            cursor
-            node {
-              name
-              product {
-                id
-                tags
-                tracksInventory
-              }
-              variant {
-                inventoryQuantity
-                inventoryPolicy
-              }
-            }
+          variant {
+            inventoryQuantity
+            inventoryPolicy
           }
         }
       }
     }
-  {% endcapture %}
-
-  {% assign result = query | shopify %}
-
-  {% if event.preview %}
-    {% capture result_json %}
-      {
-        "data": {
-          "order": {
-            "id": "gid://shopify/Order/1234567890",
-            "tags": [],
-            "customer": {
-              "id": "gid://shopify/Customer/1234567890",
-              "tags": []
-            },
-            "lineItems": {
-              "pageInfo": {
-                "hasNextPage": false
-              },
-              "edges": [
-                {
-                  "cursor": "eyJsYXN0X2lkIjo0NTEwOTE5MzI3ODA1LCJsYXN0X3ZhbHVlIjo0NTEwOTE5MzI3ODA1fQ==",
-                  "node": {
-                    "name": "An out of stock product",
-                    "product": {
-                      "id": "gid://shopify/Product/1234567890",
-                      "tags": [],
-                      "tracksInventory" : true
-                    },
-                    "variant": {
-                      "inventoryQuantity": -1,
-                      "inventoryPolicy": "DENY"
-                    }
-                  }
+  }
+{% endcapture %}
+
+{% assign result = query | shopify %}
+
+{% if event.preview %}
+  {% capture result_json %}
+    {
+      "data": {
+        "order": {
+          "id": "gid://shopify/Order/1234567890",
+          "customer": {
+            "id": "gid://shopify/Customer/1234567890"
+          },
+          "lineItems": {
+            "nodes": [
+              {
+                "name": "An out of stock product",
+                "product": {
+                  "id": "gid://shopify/Product/1234567890",
+                  "title": "An out of stock product",
+                  "tracksInventory" : true
+                },
+                "variant": {
+                  "inventoryQuantity": -1,
+                  "inventoryPolicy": "DENY"
                 }
-              ]
-            }
+              }
+            ]
           }
         }
       }
-    {% endcapture %}
+    }
+  {% endcapture %}
 
-    {% assign result = result_json | parse_json %}
+  {% assign result = result_json | parse_json %}
+{% endif %}
+
+{% assign order = result.data.order %}
+
+{% for line_item in order.lineItems.nodes %}
+  {% assign product = line_item.product %}
+  {% assign variant = line_item.variant %}
+
+  {% comment %}
+    -- skip custom line items (i.e. not attached to a product in the shop), and products that do not track inventory
+  {% endcomment %}
+
+  {% if product == blank %}
+    {% continue %}
   {% endif %}
 
-  {% for line_item_edge in result.data.order.lineItems.edges %}
-    {% assign variant = line_item_edge.node.variant %}
-    {% if variant and variant.inventoryQuantity < 0 and variant.inventoryPolicy == "DENY" and line_item_edge.node.product.tracksInventory %}
-      {% log %}{{ line_item_edge.node.name | append: " was purchased while at stock level " | append: variant.inventoryQuantity | json }}{% endlog %}
-      {% assign out_of_stock_line_items[out_of_stock_line_items.size] = line_item_edge.node %}
+  {% unless product.tracksInventory %}
+    {% continue %}
+  {% endunless %}
+
+  {% if variant.inventoryQuantity < 0 %}
+    {% comment %}
+      -- ignore variants with negative inventory if they are set to oversell and that option is enabled in the task
+    {% endcomment %}
+
+    {% if ignore_variants_marked_for_oversell and variant.inventoryPolicy == "CONTINUE" %}
+      {%- capture log_output -%}
+        {{ line_item.name }} was purchased while at stock level {{ variant.inventoryQuantity }}; however, the variant's inventory policy allows overselling and the "Ignore variants marked for oversell" task option is enabled; skipping.
+      {%- endcapture -%}
+
+      {% log log_output %}
+
+      {% continue %}
     {% endif %}
-  {% endfor %}
 
-  {% if result.data.order.lineItems.pageInfo.hasNextPage %}
-    {% assign cursor = result.data.order.lineItems.edges.last.cursor %}
-  {% else %}
-    {% break %}
+    {% assign out_of_stock_products = out_of_stock_products | push: product | uniq %}
   {% endif %}
 {% endfor %}
 
-{% assign mutations = array %}
+{% if out_of_stock_products == blank %}
+  {% log "No out of stock products for this order." %}
+  {% break %}
+{% endif %}
 
-{% assign order = result.data.order %}
+{% comment %}
+  -- apply the order tag
+{% endcomment %}
 
-{% if out_of_stock_line_items != empty %}
-  {% if order.tags contains options.apply_this_order_tag__required %}
-    {% log %}{{ "This order is already tagged " | append: options.apply_this_order_tag__required | json }}{% endlog %}
-  {% else %}
-    {% capture mutation %}
-      order: tagsAdd(
-        id: {{ order.id | json }}
-        tags: {{ options.apply_this_order_tag__required | json }}
-      ) {
-        userErrors {
-          field
-          message
+{% action "shopify" %}
+  mutation {
+    tagsAdd(
+      id: {{ order.id | json }}
+      tags: {{ apply_this_order_tag | json }}
+    ) {
+      node {
+        ... on Order {
+          id
+          name
         }
       }
-    {% endcapture %}
+      userErrors {
+        field
+        message
+      }
+    }
+  }
+{% endaction %}
 
-    {% assign mutations[mutations.size] = mutation %}
-  {% endif %}
+{% comment %}
+  -- apply the customer tag if it is configured, there is a customer for the order, and they do not yet have the tag
+{% endcomment %}
 
-  {% if options.apply_this_customer_tag != blank %}
-    {% if order.customer.tags contains options.apply_this_customer_tag %}
-      {% log %}{{ "This customer is already tagged " | append: options.apply_this_customer_tag | json }}{% endlog %}
-    {% else %}
-      {% capture mutation %}
-        customer: tagsAdd(
+{% unless apply_this_customer_tag == blank or order.customer == blank %}
+  {% if order.customer.tags contains apply_this_customer_tag %}
+    {% log "This customer already has the configured tag." %}
+
+  {% else %}
+    {% action "shopify" %}
+      mutation {
+        tagsAdd(
           id: {{ order.customer.id | json }}
-          tags: {{ options.apply_this_customer_tag | json }}
+          tags: {{ apply_this_customer_tag | json }}
         ) {
+          node {
+            ... on Customer {
+              id
+              displayName
+            }
+          }
           userErrors {
             field
             message
           }
         }
-      {% endcapture %}
-
-      {% assign mutations[mutations.size] = mutation %}
-    {% endif %}
+      }
+    {% endaction %}
   {% endif %}
+{% endunless %}
+
+{% comment %}
+  -- apply product tag if it is configured, for any products that do not yet have the tag
+{% endcomment %}
 
-  {% if options.apply_this_product_tag_for_each_out_of_stock_line_item != blank %}
-    {% for line_item in out_of_stock_line_items %}
-      {% if line_item.product.tags contains options.apply_this_product_tag_for_each_out_of_stock_line_item %}
-        {% log %}{{ "The product for line item " | append: line_item.name | append: " is already tagged with " | append: options.apply_this_product_tag_for_each_out_of_stock_line_item | json }}{% endlog %}
-      {% else %}
-        {% capture mutation %}
-          lineItem{{ forloop.index }}: tagsAdd(
-            id: {{ line_item.product.id | json }}
-            tags: {{ options.apply_this_product_tag_for_each_out_of_stock_line_item | json }}
+{% if apply_this_product_tag != blank %}
+  {% for product in out_of_stock_products %}
+    {% if product.tags contains apply_this_product_tag %}
+      {%- capture log_output -%}
+        The product "{{ product.title }}" already has the configured tag.
+      {%- endcapture -%}
+
+      {% log log_output %}
+
+    {% else %}
+      {% action "shopify" %}
+        mutation {
+          tagsAdd(
+            id: {{ product.id | json }}
+            tags: {{ apply_this_product_tag | json }}
           ) {
+            node {
+              ... on Product {
+                id
+                title
+              }
+            }
             userErrors {
               field
               message
             }
           }
-        {% endcapture %}
-
-        {% assign mutations[mutations.size] = mutation %}
-      {% endif %}
-    {% endfor %}
-  {% endif %}
-{% else %}
-  {% log "No out of stock line items for this order." %}
-{% endif %}
-
-{% if mutations != empty %}
-  {% action "shopify" %}
-    mutation {
-      {{ mutations | join: newline }}
-    }
-  {% endaction %}
+        }
+      {% endaction %}
+    {% endif %}
+  {% endfor %}
 {% endif %}