Parameters ​

Parameters are individual properties of an object that provides access to the value of that property. For instance, the title of a post or the email address of a user. A parameter can also be a general value that doesn't belong to a specific object. For instance, the current time and date or the WordPress site URL.

In WunderAutomation parameters are used to modify the content for different fields when an action is executed which makes it possible to create dynamic content.

The value of a parameter can be accessed inside an action by using double curly braces, i.e. {{ user.id }} or {{ site_url }}

Using parameters in an action ​

Let's say you want to send an email to a WordPress user after the first login. To do this, you need to create a Send Email action and set recipient to {{ user.email }} and perhaps set the email subject to "Hello {{ user.firstname }}.

When the workflow is executed, the parameter names inside the double curly brackets will be replaced with the actual values for the user object that was added to the runtime context earlier in the workflow.

The action editor contains a list of available objects in the top right corner (shown as green 'pills'). By clicking an object the available parameters for that object are displayed. In the image above the user object was clicked so that the parameters of that object are visible (shown as blue 'pills').

Among the objects, there's a pill named general that is always visible. Clicking the general pill will reveal all the properties that don't belong to a specific object, like {{ datetime }} or {{ option }}.

Some object types have so many parameters that they need to be grouped. The image below shows how the action editor looks when selecting an order object. Note that the parameters are grouped in order, cart, billing, shipping and customer. Clicking one of the group names reveals the parameters in that group.

Placeholder syntax ​

The parameter placeholder uses a syntax with two parts separated by a pipe ( | ) character.

1. Parameter name - A name identifying the parameter
2. Modifiers - A list of value pairs consisting of a modifier name and a value. The name and value are separated using a colon ( : ) and multiple modifiers are separated with a comma ( , ).

If the parameter name doesn't contain a dot ( . ), it is a general parameter that does not belong to a specific object in the runtime context.

If the parameter name contains a dot, the first part before the dot identifies the object and the second part after the dot identifies the individual parameter on that object:

The parameter editor ​

Manually typing out the parameter names inside double curly braces is a bit difficult because it's easy to get it wrong. The easiest way to get the parameter correct is to open the parameter editor, by clicking on one of the blue parameter pills which will open the editor as a page overlay:

Inside the parameter editor ​

The parameter editor looks a little bit different depending on the parameter you clicked on to open it, the image above shows how the editor looks when working with a simple string parameter. A few elements are always the same:

• Name - The first element is always the full name of the parameter. In this case user.email.
• Description - A short description of what this parameter represents
• URL Encode - When checked, the parameter value will be passed via the PHP url encode() function. This can be useful when sending data to an API.
• Escape new lines - If the parameter value contains newline character "\n", it's escaped with double backslashes. This can be useful when sending data to an API.
• Preview - The grey area at the bottom that shows the parameter placeholder, including any modifiers.
• Copy to clipboard - Use this button to copy the parameter placeholder to the clipboard.
• Insert - Insert the parameter placeholder in the text field that had focus when you opened the parameter editor.
• Cancel - Close the parameter editor.

Some parameters show a lot more options, here's what the parameter editor looks like when adding a WooCommerce coupon:

Modifiers ​

Most parameters can be manipulated using modifiers. A modifier changes the value in some way before its value is inserted into the action. Most modifiers are editable via the parameter editor, but some of the more advanced ones require manual typing.

Note that the format modifier is overloaded and is used differently when formatting a date parameter vs. a phone parameter or WooCommerce order details, see below.

String parameter modifiers ​

*) This modifier is not accessible or editable via the parameter editor.

Examples

Assuming a WordPress site with the blog name "My cool blog";

Assuming the value "the.quck.brown.fox" is stored in WordPress option "foo";

Note that in the first example, the divider isn't set and will default to a comma. But the string is separated by dots so the resulting array is

Date/time parameter modifiers ​

Examples:

Assuming a workflow that runs 9:30AM on Thursday, October 12th, 2023 and the WordPress timezone is America/Los_Angeles:

Other modifiers ​

Phone modifiers ​

Parameters containing a telephone number will show the phone format dropdown in the parameter editor. This happens for parameters that are known to contain a telephone number, like the order.billing_phone on a WooCommerce order, or when you have selected phone in the type dropdown in the parameter editor.

The E.164 is a standard for formatting telephone numbers, sometimes just called the "international format". Formatting a telephone number according to E.164 increases the likelihood that it is recognized in other databases or APIs outside of WordPress. Many external APIs require telephone numbers to use this standard.

A local telephone number can be formatted in a myriad of different ways, 212-456-7890, +1 212.456.7890 or 212.456.7890 are all common ways of displaying the same US phone number. The E.164 version of that phone number is +12124567890 (always start with the plus sign and the country number, no leading zero for region code, and no spaces, dots or dashes).

WunderAutomation has an advanced telephone number formatter that converts almost any format into an E.164 formatted number. Since some phone numbers are typed in without a valid country code, WunderAutomation needs to have a default country to use as a fallback. The default country used follows this process (note, only in use when the typed-in phone number doesn't already contain a valid country code):

1. If the phone number comes from a WooCommerce order, the billing country on that order is used as the fallback.
2. If it's not a WooCommerce order or if no billing county is found on the order, the base country of the WooCommerce store is used as the fallback.
3. If the site does not have WooCommerce installed, 'US' is used as the fallback.

WooCommerce modifiers ​

Customer details modifiers ​

There are three special parameters that are mostly intended to be used when sending out emails with order information. They return a formatted chunk of text that really only makes sense to display in a message or email.

• order.email_customer_details - Returns customer details for an order (address, phone etc).
• order.email.summary - Returns order details summary including order items, quantities, subtotal and total.
• order.email_meta - Returns meta information about an order like order date etc.

Generate coupon modifiers ​

The Generate coupon parameter will generate a unique WooCommerce coupon every time it is used. The coupon is always based on a manually created coupon that is used as a template. The generated coupon will inherit all properties from the template coupon but with an option to override some settings defined by using modifiers.

Complex data modifiers (JSONPath) ​

Most parameters return plain values like a string or a number (scalar values). But some parameters may return complex data in the form of an array or an object. This is common when reading data from custom fields or from the WordPress options table. By default, WunderAutomation will return the first scalar value it can find from this kind of value.

WunderAutomation can retrieve single scalar values inside a complex object or array using JSON path syntax via the path modifier for parameters that are known to sometimes return complex values.

Authoring correct JSONPath expressions can be tricky to get right so using an online expression tester like https://jsonpath.com/ is highly recommended.

Examples

Assuming that the following data has been picked up from a serialized custom field:

{
    "firstName": "John",
    "lastName": "doe",
    "age": 26,
    "address": {
        "streetAddress": "naist street",
        "city": "Nara",
        "postalCode": "630-0192"
    },
    "phoneNumbers": [
        {
            "type": "iPhone",
            "number": "0123-4567-8888"
        },
        {
            "type": "home",
            "number": "0123-4567-8910"
        }
    ]
}

Note that since the complex value is first translated to a JSON object internally, PHP associative arrays using non-numeric indexes will be treated as JSON objects, not arrays. So even if the value may be stored as a serialized array in the database, associative arrays need to be treated as objects in JSONPath.