Actions: Transforming Data with vendor_actions & suredone_actions

What Are Actions?

Actions are conditional transformation rules. Each action says: "When this condition is true, do this transformation." They let you modify data as it flows through an automation -- set values, calculate prices, skip items, reformat text, and more -- without writing any code.

Think of actions as a rulebook the automation engine consults for every single item or order it processes. For each rule, the engine checks the condition. If the condition matches, it applies the transformation. If it does not match, it moves on to the next rule.

Two Types of Actions

There are two action configurations, and the difference is which data the engine checks the condition against:

This distinction is critical. When a vendor sends "Out of Stock" as their stock value and you want to convert it to 0, you use vendor_actions because you are checking the vendor data. When you want to skip updating an item because your SureDone account has a custom field invoverride set to 1, you use suredone_actions because you are checking your data.

For exports, both types check the SureDone item being exported. suredone_actions run first (checking the original item data), then vendor_actions run after (seeing any modifications from suredone_actions).

Action Structure

Actions are defined as an array of objects inside file_configs. Each object has a search key (the condition) and one or more function keys (the transformations):

"vendor_actions": [
  {
    "search": "stock:=0",
    "setValue": {
      "condition": "Out of Stock"
    }
  },
  {
    "search": "price:>1000",
    "setValue": {
      "freeshipping": "1"
    }
  }
]

The search key is optional. If you omit it, the action applies to every item:

"vendor_actions": [
  {
    "setValue": {
      "MARKETPLACE_ID": 148097,
      "CURRENCY": "USD"
    }
  }
]

Search Syntax in Actions

The search value uses SureDone search syntax. Here are the operators you will use most:

Combining conditions:

• AND -- Separate conditions with a space: stock:>0 condition:=New (stock > 0 AND condition = New)
• OR -- Wrap conditions in parentheses: (brand:=Nike brand:=Adidas) (brand = Nike OR brand = Adidas)

{
  "search": "stock:>0 condition:=New",
  "setValue": { "status": "active" }
}

{
  "search": "(status:=disable status:=draft)",
  "ignoreItem": ""
}

Order of Operations

Actions within a single action object execute top to bottom in the order they are defined. This means you can chain calculations -- the output of one function becomes the input for the next:

{
  "sum": {
    "sellprice": ["cost", "shippingcharge"]
  },
  "multiply": {
    "sellprice": ["sellprice", 1.19]
  },
  "round": {
    "sellprice": 2
  }
}

In this example: first sellprice is set to cost + shippingcharge, then it is multiplied by 1.19, then it is rounded to 2 decimal places.

Multiple action objects in the array also execute top to bottom. The engine processes each object for every item before moving on.

All Action Functions

setValue

When you want to set a field to a specific value, use setValue.

{
  "search": "vendorstock:=\"Out of Stock\"",
  "setValue": {
    "stock": 0
  }
}

You can set multiple fields at once:

{
  "setValue": {
    "MARKETPLACE_ID": 148097,
    "CURRENCY": "USD",
    "condition": "New"
  }
}

ignoreField (alias: ignoreValue)

When you want to keep SureDone's existing value for a field instead of overwriting it with the vendor's value, use ignoreField.

{
  "search": "invoverride:=1",
  "ignoreField": "stock"
}

This is commonly used in suredone_actions to protect certain fields from being overwritten. If your SureDone item has invoverride set to 1, the stock value from the vendor file is ignored and your current stock is preserved.

ignoreItem (aliases: ignoreOrder, ignoreObject)

When you want to skip an item entirely so it is not imported, exported, or processed, use ignoreItem.

{
  "search": "(status:=disable status:=draft)",
  "ignoreItem": ""
}

This is powerful when combined with missing_vendor_items. Say you set "missing_vendor_items": "delete" to end-list items that disappear from the vendor file. But some items should never be deleted -- use ignoreItem to protect them:

"suredone_actions": [
  {
    "search": "dontdelete:=1",
    "ignoreItem": ""
  }
],
"missing_vendor_items": "delete"

deleteItem

When you want to mark an item for deletion in the resulting bulk file, use deleteItem.

{
  "search": "discontinued:=1",
  "deleteItem": ""
}

This sets the item's action field to "delete" and flags the item for removal. It is the action-based equivalent of "missing_vendor_items": "delete", but allows you to conditionally delete specific items based on search criteria.

endItem

When you want to mark an item for end-listing in the resulting bulk file, use endItem.

{
  "search": "stock:=0",
  "endItem": ""
}

This sets the item's action field to "end" and flags the item for removal from active listings. Use this when you want to end-list items on channels without fully deleting them from SureDone.

remapField

When you want to pull a field's value from a different source field than what field_map specifies, use remapField.

"field_map": {
  "price": "map_price"
},
"field_run": {
  "mrp": "mrp_price"
},
"suredone_actions": [
  {
    "search": "mapoverride:=1",
    "remapField": {
      "price": "mrp"
    }
  }
]

By default, price comes from map_price via field_map. But when the SureDone item has mapoverride set to 1, the price is instead pulled from the mrp field (originally mapped from mrp_price via field_run).

replace

When you want to find and replace text within a field value, use replace.

{
  "replace": {
    "title": {
      "'": ""
    }
  }
}

This strips all single quote characters from the title. Before: '101B'. After: 101B.

You can perform multiple replacements on the same field:

{
  "replace": {
    "title": {
      "&": "&",
      "&lt;": "<",
      "&gt;": ">"
    }
  }
}

regexExtract

When you want to extract a portion of a field value using a regular expression, use regexExtract.

{
  "regexExtract": {
    "warehouselocation": {
      "regex": "/(.*)Location: (.*)\\[/",
      "capture_group": 2
    }
  }
}

Before: "Warehouse : MUF Location: 1I-6[WPS101] Quantity: 3 ||". After: "1I-6".

If the regex does not match, the original value is preserved.

combine

When you want to merge multiple field values into a single field, use combine.

{
  "combine": {
    "sku": {
      "fields": ["brand", "mpn"],
      "delimiter": "-"
    }
  }
}

If brand is "ACME" and mpn is "12345", the result is "ACME-12345".

When combine targets a single field that contains an array, it implodes the array into a delimited string:

{
  "combine": {
    "vehicleids": {
      "fields": ["acesvehicleid"],
      "delimiter": "*"
    }
  }
}

convertDateTime

When you want to reformat a date value, use convertDateTime.

{
  "convertDateTime": {
    "datefield": "Y-m-d"
  }
}

Accepts Unix timestamps (numeric values) or any standard date string. Common format tokens: Y (4-digit year), m (2-digit month), d (2-digit day), H (24-hour hour), i (minutes), s (seconds).

Math Functions: sum, subtract, multiply, divide

When you want to perform arithmetic on field values, use the math functions.

All four take the same argument structure:

sum -- Adds all values together:

{
  "sum": {
    "sellprice": ["cost", "shippingcharge", 10]
  }
}

Formula: sellprice = cost + shippingcharge + 10

subtract -- Subtracts each subsequent value from the first:

{
  "subtract": {
    "profit": ["price", "cost", "fees"]
  }
}

Formula: profit = price - cost - fees

multiply -- Multiplies all values together:

{
  "multiply": {
    "sellprice": ["cost", 1.19]
  }
}

Formula: sellprice = cost * 1.19

divide -- Divides in order. Division by zero is safely skipped:

{
  "divide": {
    "unitprice": ["totalprice", "quantity"]
  }
}

Formula: unitprice = totalprice / quantity

Values in the array can be field names (the engine reads the current value) or numeric constants (the engine uses the literal number). The first element in the array is the starting value.

Rounding Functions: round, roundUp, roundDown, roundNearest

round -- Round to a specific number of decimal places:

{
  "round": {
    "price": 2
  }
}

49.9567 becomes 49.96.

roundUp -- Round up to the next whole number, with an optional decimal offset:

{
  "roundUp": {
    "price": 0.99
  }
}

42.15 becomes 42.99. 43.01 becomes 43.99. The value rounds up to the next whole number, then the decimal offset is applied.

roundDown -- Round down to the current whole number, with an optional decimal offset:

{
  "roundDown": {
    "price": 0.95
  }
}

42.97 becomes 42.95. 42.94 becomes 41.95. If the decimal portion is less than the offset, it rounds down one more whole number.

roundNearest -- Round to the nearest value matching a base interval and ending:

{
  "roundNearest": {
    "price": {
      "base": 10,
      "ending": 9.95
    }
  }
}

This rounds to the nearest value ending in .95 on a 10-unit interval: 9.95, 19.95, 29.95, 39.95, etc. A value of 34 becomes 29.95. A value of 36 becomes 39.95.

min and max

When you want to enforce a minimum or maximum value across multiple fields, use min or max.

{
  "min": {
    "bestcost": ["vendor1cost", "vendor2cost", "vendor3cost"]
  }
}

bestcost is set to whichever field has the lowest value.

{
  "max": {
    "price": ["calculatedprice", 9.99]
  }
}

price is set to at least 9.99, even if calculatedprice is lower.

autoIncrement

When you want to generate sequential values across items, use autoIncrement.

{
  "autoIncrement": {
    "linenumber": {"start": 1, "step": 1}
  }
}

The first item gets 1, the second gets 2, the third gets 3, and so on. Useful for generating line numbers in export files.

uppercase and lowercase

When you want to change the case of a text field, use uppercase or lowercase.

{
  "uppercase": "sku"
}

{
  "lowercase": "email"
}

Encoding Functions: jsonEncode, base64Encode, base64Decode

When you need to encode or decode a field value, use the encoding functions.

{
  "jsonEncode": {"customdata": ""}
}

Converts the field value to a JSON string. Useful when a field contains an array or object that needs to be serialized.

{
  "base64Encode": {"payload": ""}
}

{
  "base64Decode": {"encodedfield": ""}
}

setAddress

When you want to route individual items or orders to different export destinations, use setAddress.

"suredone_actions": [
  {
    "search": "supplier:=\"Acme Corp\"",
    "setAddress": "orders@acmecorp.com"
  },
  {
    "search": "supplier:=\"BetaGoods\"",
    "setAddress": "orders@betagoods.com"
  }
]

Complete Pricing Example

Here is a real-world pricing calculation automation. A vendor provides cost data, and the automation calculates selling prices with conditional markup and rounding.

Business rules:

• If the item can ship via standard ground, set shipping charge to $15 and apply a 19% markup
• If the item requires freight, set shipping charge to $250 and apply a 16% markup
• Round the final price to 2 decimal places

Formula (standard shipping): sell_price = (cost + 15) * 1.19

Formula (freight shipping): sell_price = (cost + 250) * 1.16

"field_map": {
  "sellprice": "vendor_sellprice"
},
"field_run": {
  "cost": "vendor_cost",
  "shippingcharge": "vendor_shippingcharge",
  "can_ship": "can_ship_ground",
  "tempprice": "vendor_sellprice"
},
"vendor_actions": [
  {
    "ignoreField": "sellprice"
  },
  {
    "ignoreField": "shippingcharge"
  },
  {
    "search": "(can_ship:=true can_ship:=TRUE can_ship:=1)",
    "setValue": {
      "shippingcharge": 15
    },
    "sum": {
      "tempprice": ["cost", "shippingcharge"]
    },
    "multiply": {
      "sellprice": ["tempprice", 1.19]
    }
  },
  {
    "search": "(can_ship:=false can_ship:=FALSE can_ship:=0)",
    "setValue": {
      "shippingcharge": 250
    },
    "sum": {
      "tempprice": ["cost", "shippingcharge"]
    },
    "multiply": {
      "sellprice": ["tempprice", 1.16]
    }
  }
],
"field_format": {
  "sellprice": {
    "decimalPlaces": 2
  },
  "shippingcharge": {
    "decimalPlaces": 2
  }
}

The first two actions (without search) preserve the existing SureDone values for sellprice and shippingcharge by default. Then, if the vendor's can_ship flag indicates standard ground shipping, the third action overrides with the calculated price. If the item requires freight, the fourth action applies instead.

Notice how tempprice is mapped in field_run, not field_map. It exists only as a scratch field for intermediate calculations -- it never appears in the final bulk file.

Tips and Common Patterns

Chain actions for multi-step calculations. Put all steps in one action object to ensure they execute in order against the same item.

Use field_run for scratch fields. Map intermediate calculation fields in field_run so they are available for actions but excluded from the bulk file.

Protect fields with ignoreField. When vendors send values you do not want, use ignoreField without a search to always preserve your SureDone data. Then conditionally overwrite in a subsequent action.

Test with a few items first. Set the automation to "active": false, add a restrictive search filter, and run manually to verify your actions produce the expected results before going live.