Yonyx Functions

Introduction

Yonyx Functions can be added to any Guidance Step. Functions are evaluated before the Guidance Step is displayed to the user. Using Functions an Author can manipulate placeholder values or call 3rd party APIs to set/update placeholders. Functions are available in the following categories:

This is how you can add functions to a guidance step in a Yonyx guide.

List Functions

Format Functions

API Functions

API Function Examples

.

Functions accept Input parameters, perform some operation on them, and produce Output parameters.

Parameter values accept placeholder name or actual value.

The green sections are Input parameters and red sections are Output parameters.

Functions can only be inserted in Guidance Steps and a Guidance Step can contain multiple functions such that the first function’s output parameters become input parameters for the second function.

In this example chain of functions, if the 3rd function (lower) fails due to an error, the remaining functions after that are not evaluated.

Math Functions

Abs

Returns the unsigned absolute value of the given number.

Takes a signed number and precision as input and outputs an unsigned absolute number.

Example 1:

INPUT PARAMETER(S):
Set “number” to “-5.56789”

Leave “precision” as is with Auto. Precision is how you control the number of decimal places the output should return.

OUTPUT PARAMETER(S):
The output parameter “absolute” carries the value “5.56789” which will be assigned to a placeholder that you choose.

Example 2:

INPUT PARAMETER(S):
Set “number” to “-5.56789”

Set “precision” to “2”

OUTPUT PARAMETER(S):
The output parameter “absolute” carries the value “5.57” which will be assigned to a placeholder that you choose.

Ceil

Returns the smallest integer greater than or equal to the given number.

Example:

INPUT PARAMETER(S):
Set “number” to “4.1”

OUTPUT PARAMETER(S):
The output parameter “ceil” carries the value “5” which will be assigned to a placeholder that you choose.

Divide

Divides a numerator by a denominator.

Takes two numbers (numerator and denominator) and precision as input and outputs the quotient.

Example 1:

INPUT PARAMETER(S):
Set “numerator” to “10”

Set “denominator” to “5.1”

Leave “precision” as is with “AUTO”.

OUTPUT PARAMETER(S):
The output parameter “quotient” carries the value “1.9607843137254903” which will be assigned to a placeholder that you choose.

Example 2:

INPUT PARAMETER(S):
Set “numerator” to “10”

Set “denominator” to “5.1”

Set “precision” to “2”.

OUTPUT PARAMETER(S):
The output parameter “quotient” carries the value “1.96” which will be assigned to a placeholder that you choose.

Floor

Returns the largest integer less than or equal to the given number.

Example:

INPUT PARAMETER(S):
Set “number” to “4.1”

OUTPUT PARAMETER(S):
The output parameter “floor” carries the value “4” which will be assigned to a placeholder that you choose.

Max

Returns the maximum value from the given list of numbers.

Takes a list of numbers (both in the form of placeholders as well as number values) as input and returns the largest number as output.

Example:

INPUT PARAMETER(S):
Set “numbers” to a list of numbers [ 4.4, 4.3, 2, -20 ]

OUTPUT PARAMETER(S):
The output parameter “max” carries the value “4.4” which will be assigned to a placeholder that you choose.

Min

Returns the minimum value from the given list of numbers.

Takes a list of numbers (both in the form of placeholders as well as number values) as input and returns the smallest number as output.

Example:

INPUT PARAMETER(S):
Set “numbers” to a list of numbers [ 4.4, 4.3, 2, -20 ]

OUTPUT PARAMETER(S):
The output parameter “min” carries the value “-20” which will be assigned to a placeholder that you choose.

Modulo

Returns the remainder after the numerator is divided by the denominator.

Takes two numbers (numerator and denominator) and precision as input and outputs the remainder.

Example:

INPUT PARAMETER(S):
Set “numerator” to “10”

Set “denominator” to “3.5”

Leave “precision” as is with Auto.

OUTPUT PARAMETER(S):
The output parameter “remainder” carries the value “3” which will be assigned to a placeholder that you choose.

Multiply

Returns the product by multiplying all the given numbers.

Takes a list of numbers (both in the form of placeholders as well as number values) and precision as input and outputs the product.

Example:

INPUT PARAMETER(S):
Set “numbers” to a list of numbers [ 6, 4.3, 2.0002, -2 ]

Set “precision” to “2”.

OUTPUT PARAMETER(S):
The output parameter “product” carries the value “-103.21” which will be assigned to a placeholder that you choose.

Sum

Returns a sum total of all the given numbers.

Takes a list of numbers (both in the form of placeholders as well as number values) and precision as input and outputs the sum.

Example 1:

INPUT PARAMETER(S):
Set “numbers” to a list of numbers [ 12, 6.001, 24, -2.567 ]

Set “precision” to “2”.

OUTPUT PARAMETER(S):
The output parameter “sum” carries the value “39.43” which will be assigned to a placeholder that you choose.

Example 2:

INPUT PARAMETER(S):
Set “numbers” to a list of numbers and placeholders [ ph-branch-total, 250 ]

Leave “precision” as is with “AUTO”.

OUTPUT PARAMETER(S):
Assuming ph-branch-total was previously set to 500, the output parameter “sum” carries the value “750” which will be assigned to a placeholder that you choose.

String Functions

Concatenate

Returns the concatenation of all the given strings.

Example:

INPUT PARAMETER(S):
Set “string” to [ “Yonyx”, “Decision”, “Trees” ]

Set “delimiter” to “_”

OUTPUT PARAMETER(S):
The output parameter “concatenated” carries the value “Yonyx_Interactive_Guides” which will be assigned to a placeholder that you choose.

Find in string

Returns the index (position) within this string of the first occurrence of the specified substring.
Index (position) is a zero-based number (initial element starts with zero instead of one).
If the substring does not exist within the string, then -1 is returned.

Example:

INPUT PARAMETER(S):
Set “string” to “Yonyx Decision Trees”

Set “search” to “Trees”

OUTPUT PARAMETER(S):
The output parameter “index” carries the value “15” which will be assigned to a placeholder that you choose.

Length of string

Returns the length of the given string.

Example:

INPUT PARAMETER(S):
Set “string” to “Yonyx Decision Trees”

OUTPUT PARAMETER(S):
The output parameter “length” carries the value “20” which will be assigned to a placeholder that you choose.

Lower

Converts all characters of the given string to lowercase.

Example:

INPUT PARAMETER(S):
Set “string” to “Yonyx Decision Trees”

OUTPUT PARAMETER(S):
The output parameter “lower” carries the value “yonyx decision trees” which will be assigned to a placeholder that you choose.

Replace

Replaces each occurrence of the search-string in the given string with the replacement-string.

Example:

INPUT PARAMETER(S):
Set “string” to “Yonyx Decision Trees”

Set “search” to “Decision Trees”

Set “replace” to “Interactive Guides”

OUTPUT PARAMETER(S):
The output parameter “replaced” carries the value “Yonyx Interactive Guides” which will be assigned to a placeholder that you choose.

Substring

Returns a fragment of the given string starting from the start position (inclusive) to the specified length.

Example:

INPUT PARAMETER(S):
Set “string” to “Yonyx Decision Trees”

Set “start” to “0”

Set “length” to “5”

OUTPUT PARAMETER(S):
The output parameter “substring” carries the value “Yonyx” which will be assigned to a placeholder that you choose.

Trim

Removes space characters before and after the given string.

Example:

INPUT PARAMETER(S):
Set “string” to ” Yonyx Decision Trees “

OUTPUT PARAMETER(S):
The output parameter “trimmed” carries the value “Yonyx Decision Trees” which will be assigned to a placeholder that you choose.

Upper

Converts all characters of the given string to uppercase.

Example:

INPUT PARAMETER(S):
Set “string” to “Yonyx Decision Trees”

OUTPUT PARAMETER(S):
The output parameter “upper” carries the value “YONYX DECISION TREES” which will be assigned to a placeholder that you choose.

Date Functions

Yonyx supports combined Date and Time representations expressed according to ISO 8601 format in UTC with or without the ‘T’ separating date and time. Eg: 2023-07-18 07:05:15 or 2023-07-18T07:05:15. Learn more about ISO 8601.

Add Date

Returns the date by adding the specified quantity of unit (year/month/day) to it.
Supported units are:
year: Returns a numeric year.
month: Returns a numeric month (1, 2, 3, … , 12).
day: Returns a numeric day of the month (1, 2, 3, to end of month).

Example:

INPUT PARAMETER(S):
Set “date” to “2023-01-25”

Set “quantity” to “2”

Set “unit” to “year”

OUTPUT PARAMETER(S):
The output parameter “added” carries the value “2025-01-25” which will be assigned to a placeholder that you choose.

Age

Returns a numeric value that represents the number of full years, full months, and full days between the current timestamp and the given date.

Example:

INPUT PARAMETER(S):
Set “date” to “1970-01-25”

OUTPUT PARAMETER(S):
The output parameter “years” carries the value “53” which will be assigned to a placeholder that you choose.

The output parameter “months” carries the value “3” which will be assigned to a placeholder that you choose.

The output parameter “days” carries the value “13” which will be assigned to a placeholder that you choose.

Convert Date Time

Converts the given date or time from one format to another.

Example 1:

INPUT PARAMETER(S):
Set “date-time” to “7:5:5 PM”

Set “from-format” to “hh:mm:ss a”

Set “to-format” to “HH:mm:ss”

OUTPUT PARAMETER(S):
The output parameter “converted” carries the value “19:05:05” which will be assigned to a placeholder that you choose.

Example 2:

INPUT PARAMETER(S):
Set “date-time” to “Jun 30, 2009 7:03:47 PM”

Set “from-format” to “MMM dd, yyyy hh:mm:ss a”

Set “to-format” to “yyyy-MM-dd HH:mm:ss”

OUTPUT PARAMETER(S):
The output parameter “converted” carries the value “2009-06-30 19:03:47” which will be assigned to a placeholder that you choose.

Example 3:

INPUT PARAMETER(S):
Set “date-time” to “6/30/09 7:03 pm”

Set “from-format” to “M/d/yy hh:mm a”

Set “to-format” to “yyyy-MM-dd HH:mm:ss”

OUTPUT PARAMETER(S):
The output parameter “converted” carries the value “2009-06-30 19:03:00” which will be assigned to a placeholder that you choose.

Example 4:

INPUT PARAMETER(S):
Set “date-time” to “June 30, 2009 7:03:47 AM PDT”

Set “from-format” to “MMMMM d, yyyy hh:mm:ss a zz”

Set “to-format” to “yyyy-MM-dd HH:mm:ss”

OUTPUT PARAMETER(S):
The output parameter “converted” carries the value “2009-06-30 14:03:47” which will be assigned to a placeholder that you choose. Note: The output is PDT to UTC converted.

Example 5:

INPUT PARAMETER(S):
Set “date-time” to “June 30, 2009 7:03:47 AM PDT”

Set “from-format” to “MMMMM d, yyyy hh:mm:ss a”

Set “to-format” to “yyyy-MM-dd HH:mm:ss”

OUTPUT PARAMETER(S):
The output parameter “converted” carries the value “2009-06-30 07:03:47” which will be assigned to a placeholder that you choose.

Example 6:

INPUT PARAMETER(S):
Set “date-time” to “Tuesday, June 30, 2009 7:03:47 PM PDT”

Set “from-format” to “E, MMMMM d, yyyy hh:mm:ss a”

Set “to-format” to “yyyy-MM-dd HH:mm:ss”

OUTPUT PARAMETER(S):
The output parameter “converted” carries the value “2009-06-30 19:03:47” which will be assigned to a placeholder that you choose.

Example 7:

INPUT PARAMETER(S):
Set “date-time” to “2015-05-21T05:05:35+00:00”

Set “from-format” to “yyyy-MM-dd’T’HH:mm:ss”

Set “to-format” to “HH:mm”

OUTPUT PARAMETER(S):
The output parameter “converted” carries the value “05:05” which will be assigned to a placeholder that you choose.

Example 8:

INPUT PARAMETER(S):
Set “date-time” to “2009-06-30 07:03:47-07:00”

Set “from-format” to “yyyy-MM-dd HH:mm:ssXXX”

Set “to-format” to “yyyy-MM-dd HH:mm:ss”

Date Part

Extracts the specified part of a given date.

Supported date parts are:
year: Returns a numeric year.
month: Returns a numeric month (1, 2, 3, … , 12).
week-of-month: Returns a numeric week of the month (1, 2, 3, 4, or 5).
week-of-year: Returns a numeric week of the year (1, 2, 3, … , 52).
day: Returns a numeric day of the month (1, 2, 3, to end of month).
day-of-week: Returns a numeric day of the week (1 = Monday, 2 = Tuesday,…, 7 = Sunday).
day-of-year: Returns a numeric day of the year (1, 2, 3, to end of year).
quarter: Returns a numeric quarter (1, 2, 3, or 4).

Example:

INPUT PARAMETER(S):
Set “date” to “2023-01-25”

Set “part” to “year”

OUTPUT PARAMETER(S):
The output parameter “extracted” carries the value “2022” which will be assigned to a placeholder that you choose.

Duration

Returns the difference between 2 dates in years, months, and days.

Example:

INPUT PARAMETER(S):
Set “date1” to “2023-01-25”

Set “date2” to “2023-02-25”

OUTPUT PARAMETER(S):
The output parameter “years” carries the value “0” which will be assigned to a placeholder that you choose.

The output parameter “months” carries the value “1” which will be assigned to a placeholder that you choose.

The output parameter “days” carries the value “31” which will be assigned to a placeholder that you choose.

Subtract Date

Returns the date by subtracting the specified quantity of unit (year/month/day) from it.
Supported units are:
year: Returns a numeric year.
month: Returns a numeric month (1, 2, 3, … , 12).
day: Returns a numeric day of the month (1, 2, 3, to end of month).

Example:

INPUT PARAMETER(S):
Set “date” to “2023-01-25”

Set “quantity” to “2”

Set “unit” to “year”

OUTPUT PARAMETER(S):
The output parameter “subtracted” carries the value “2022-01-25” which will be assigned to a placeholder that you choose.

Time Part

Extracts the specified part of a given time.

Supported time parts are:
hour: Returns a numeric hour (00, 01, 02,….)
min: Returns a numeric minute (00, 01, 02,….)

Example:

INPUT PARAMETER(S):
Set “date” to “05:35”

Set “part” to “minute”

OUTPUT PARAMETER(S):
The output parameter “extracted” carries the value “35” which will be assigned to a placeholder that you choose.

Time of Day – Greeting

Generates time-of-day part of a greeting. Eg. Good ‘morning’, Good ‘afternoon’, or Good ‘evening’.
‘morning’ if hour of the day is between 12 am and 12 pm.
‘afternoon’ if hour of the day is between 12 pm and 6 pm.
‘evening’ if hour of the day is between 6pm and 12 am.

Example:

INPUT PARAMETER(S):
set “timezone” to “PST”. If left empty, defaults to the account’s timezone.

Not all time zones have a 3-character string representation. The 3-character representations are not unique identifiers and can lead to ambiguity. There are many time zones that do not have a unique 3-character abbreviation, and some abbreviations may be shared by multiple time zones.

For accurate and unambiguous handling of time zones, please use the full timezone ID from the IANA (Internet Assigned Numbers Authority)

The full timezone ID is a string like “America/New_York” or “Europe/London”.

For list of IANA Timezones refer – https://timeapi.io/documentation/iana-timezones
IANA Timezone Database – https://www.iana.org/time-zones

OUTPUT PARAMETER(S):
The output parameter “time-of-day” carries the value “morning” which will be assigned to a placeholder that you choose.

List Functions

Add to list

Adds an item to the list at the specified index (position).

Example:

INPUT PARAMETER(S):
Set “list-string” to “red,blue,green”

Set “delimiter” to “,” because list-string is delimited by commas. If left empty, defaults to delimiter that is compatible with checkbox list control.

Set “item” to “green”

Set “index-type” to “LAST”

Leave “index” empty because “index-type” is not set to “CUSTOM”

OUTPUT PARAMETER(S):
The output parameter “updated-list-string” carries the value “red,blue,green,orange” which will be assigned to a placeholder that you choose.

Common in lists

Produces a list consisting of common items from multiple lists. Think of this as an intersection of multiple lists..

Example:

INPUT PARAMETER(S):
SET “list-strings” to [ ‘red,green,blue,yellow’, ‘black,yellow,white,blue’, ‘blue,orange,white,yellow’ ]

Set “delimiter” to “,” because list-string is delimited by commas. If left empty, defaults to delimiter that is compatible with checkbox list control.

OUTPUT PARAMETER(S):
The output parameter “list-string” carries the value “blue,yellow” which will be assigned to a placeholder that you choose.

Find in list

Returns the index (position) within this list of the first occurrence of the search-item.
Index (position) is a zero-based number (initial element starts with zero instead of one).
-1 is returned, if the search-item does not exist within the list.

Example:

INPUT PARAMETER(S):
Set “list-string” to “red,blue,green,orange”

Set “delimiter” to “,” because list-string is delimited by commas. If left empty, defaults to delimiter that is compatible with checkbox list control.

Set “search-item” to “green”

OUTPUT PARAMETER(S):
The output parameter “index” carries the value “2” which will be assigned to a placeholder that you choose.

Length of list

Returns the total number of items in the given list.

Example:

INPUT PARAMETER(S):
Set “list-string” to “red,blue,green,orange”

Set “delimiter” to “,” because list-string is delimited by commas. If left empty, defaults to delimiter that is compatible with checkbox list control.

OUTPUT PARAMETER(S):
The output parameter “length” carries the value “4” which will be assigned to a placeholder that you choose.

Remove from list

Removes an item of the list from the specified index (position).

Example 1: Remove by item

INPUT PARAMETER(S):
Set “list-string” to “red,blue,green,orange”

Set “delimiter” to “,” because list-string is delimited by commas. If left empty, defaults to delimiter that is compatible with checkbox list control.

Set “item” to “green”

Leave “index-type” as is because it only matters when removing an item by index.

Leave “index” empty because “index-type” is not set to “CUSTOM”

OUTPUT PARAMETER(S):
The output parameter “updated-list-string” carries the value “red,blue,orange” which will be assigned to a placeholder that you choose.

Example 2: Remove by index

INPUT PARAMETER(S):
Set “list-string” to “red,blue,green,orange”

Set “delimiter” to “,” because list-string is delimited by commas. If left empty, defaults to delimiter that is compatible with checkbox list control.

Leave “item” empty because item does not matter when removing by index.

Set “index-type” to “CUSTOM”

Set “index” to “1”

OUTPUT PARAMETER(S):
The output parameter “updated-list-string” carries the value “red,green,orange” which will be assigned to a placeholder that you choose.

The output parameter “removed-item” carries the value “blue” which will be assigned to a placeholder that you choose.

String to array

Splits the string by the specified delimiter, wraps each individual split element with prefix and suffix, and finally joins them back into a single string to produce an array representation of the string.

Use this function to pass the value of a checkbox list control as an array to an API.

Example 1: Value of a Checkbox list control

INPUT PARAMETER(S):
Set “string” to a placeholder that is a source for a checkbox list. The value of a checkbox list looks like this: “Administrator<!–ynx-delim–>Editor<!–ynx-delim–>Agent”

Set “delimiter” to “” If left empty, defaults to delimiter that is compatible with checkbox list control.

Set “prefix” to { “name” : “

If left empty, defaults to “”

Set “suffix” to ” }

If left empty, defaults to “”

OUTPUT PARAMETER(S):
The output parameter “converted” carries the value { “name” : “Administrator” }, { “name” : “Editor” }, { “name” : “Agent” }

which will be assigned to a placeholder that you choose.

Example 2: Comma separated string

INPUT PARAMETER(S):
Set “string” to “red,blue,green,orange”

Set “delimiter” to “,” because the input string is delimited by commas. If left empty, defaults to delimiter that is compatible with checkbox list control.

Leave “prefix” empty. If left empty, defaults to ‘”‘.

Leave “suffix” empty. If left empty, defaults to ‘”‘.

OUTPUT PARAMETER(S):
The output parameter “converted” carries the value “red”, “blue”, “green”, “orange”

which will be assigned to a placeholder that you choose.

String to list

Splits the string by the specified delimiter and joins them back to produce a string that is compatible with Checkbox List control for Yonyx data capture commands.

Example :

INPUT PARAMETER(S):
Set “string” to “red,blue,green”

Set “delimiter” to “,” because the input string is delimited by commas.

OUTPUT PARAMETER(S):
The output parameter “converted” carries the value “red<!–ynx-delim–>blue<!–ynx-delim–>green” which will be assigned to a placeholder that you choose.

If a checkbox list control contains 4 values “red,blue,green,orange” and this placeholder is set as its data source, then the 3 items (red,blue,green) will be checked and the last item will remain unchecked.

Unique in lists

Produces a list consisting of unique items from multiple lists. Think of this as a union of multiple lists.

Example:

INPUT PARAMETER(S):
SET “list-strings” to [ ‘red,green,blue,yellow’, ‘black,yellow,white,blue’, ‘blue,orange,white,yellow’ ]

Set “delimiter” to “,” because list-string is delimited by commas. If left empty, defaults to delimiter that is compatible with checkbox list control.

OUTPUT PARAMETER(S):
The output parameter “list-string” carries the value “red,green,blue,yellow,black,white,orange” which will be assigned to a placeholder that you choose.

Format Functions

Format date or time

Formats the given date or time or datetime according to the specified locale (language & country).

Predefined Date Format Eamples:

Style	US Locale lang=en, country=US	French Locale lang=fr, country=FR
SHORT	6/30/09	30/06/09
MEDIUM	Jun 30, 2009	30 juin 2009
LONG	June 30, 2009	30 juin 2009
FULL	Tuesday, June 30, 2009	mardi 30 juin 2009

Predefined Time Format Eamples:

Style	US Locale lang=en, country=US	Germal Locale lang=de, country=DE
SHORT	7:03 AM	07:03
MEDIUM	7:03:47 AM	07:03:07
LONG	7:03:47 AM	07:03:45
FULL	7:03:47 AM	7.03 Uhr

Example 1 Date: Use predefined format types.

INPUT PARAMETER(S):
Set “date-time” to “2023-03-25”

Set “language-code” to “en” This is a 2-letter ISO language code in lower case. If left empty, defaults to ‘en’. Review complete list here. You can use Yonyx system placeholder ‘sys-ynx-lang-code’ if you intend to pass the Guide’s language code.

Set “country-code” to “US” This is a 2-letter ISO country code in upper case. If left empty, defaults to ‘US’. Review complete list here.

Set “format-type” to “FULL” (SHORT/MEDIUM/LONG/FULL/CUSTOM).

Leave “custom-format” empty since we did not set ‘format-type’ to ‘CUSTOM’

OUTPUT PARAMETER(S):
The output parameter “formatted” carries the value “Saturday, March 25, 2023” which will be assigned to a placeholder that you choose.

Example 2 TIme: Use predefined format types.

INPUT PARAMETER(S):
Set “date-time” to “01:15:05”

Set “country-code” to “US” This is a 2-letter ISO country code in upper case. If left empty, defaults to ‘US’. Review complete list here.

Set “format-type” to “SHORT” (SHORT/MEDIUM/LONG/FULL/CUSTOM).

Leave “custom-format” empty since we did not set ‘format-type’ to ‘CUSTOM’

OUTPUT PARAMETER(S):
The output parameter “formatted” carries the value “1:15 AM” which will be assigned to a placeholder that you choose.

Example 3: Use custom format type.

INPUT PARAMETER(S):
Set “date-time” to “2023-03-25”

Set “country-code” to “US” This is a 2-letter ISO country code in upper case. If left empty, defaults to ‘US’. Review complete list here.

Set “format-type” to “CUSTOM” (SHORT/MEDIUM/LONG/FULL/CUSTOM).

Set “custom-format” to ‘week ‘w’ of ‘yyyy since we set ‘format-type’ to ‘CUSTOM’

OUTPUT PARAMETER(S):
The output parameter “formatted” carries the value “week 12 of 2023” which will be assigned to a placeholder that you choose.

Format number

Formats the given number according to the specified locale (language & country).

Example 1: Number.

INPUT PARAMETER(S):
Set “number” to “122341234.55”

Set “country-code” to “US” This is a 2-letter ISO country code in upper case. If left empty, defaults to ‘US’. Review complete list here.

Set “currency” to “NO” (YES/NO).

Leave “custom-format” empty.

OUTPUT PARAMETER(S):
The output parameter “formatted” carries the value “123,412,345.55” which will be assigned to a placeholder that you choose.

Example 2: Currency.

INPUT PARAMETER(S):
Set “number” to “122341234.55”

Set “country-code” to “US” This is a 2-letter ISO country code in upper case. If left empty, defaults to ‘US’. Review complete list here.

Set “currency” to “YES” (YES/NO).

Leave “custom-format” empty.

OUTPUT PARAMETER(S):
The output parameter “formatted” carries the value “$123,412,345.55” which will be assigned to a placeholder that you choose.

Example 3: Custom format.

INPUT PARAMETER(S):
Set “number” to “122341234.55”

Set “country-code” to “US” This is a 2-letter ISO country code in upper case. If left empty, defaults to ‘US’. Review complete list here.

Set “currency” to “YES” (YES/NO).

Set “custom-format” to “US Dollar ###,###.###”.

OUTPUT PARAMETER(S):
The output parameter “formatted” carries the value “US Dollar 123,412,345.55” which will be assigned to a placeholder that you choose.

Custom Format Patterns:

Input	Pattern	Output	Explanation
123456.789	###,###.###	123,456.789	The pound sign (#) denottes a digit, the comma is the placeholder for group separator, and the period is a placeholder for decimal separator.
123456.789	###.##	123456.78	The digits to the right of decimal point has been rounded up because the pattern has only two pound signs.
123.78	000000.000	000123.780	Leading and trailing zeros are added.
12345.67	$###,###.###	$12,345.67	Can include currency symbols in the pattern.

Custom Date Time Format Symbols

Construct representations of dates and times using the symbols from this table:

Symbol	Meaning	Presentation	Example
G	Era designator	Text	AD
y	Year	Number	2023
M	Month in year	Number & Text	M –>3 MM –> 03 MMM –> Mar MMMMM –> March
d	Day in month	Number	25
h	Hour in am/pm (1-12)	Number	11
H	Hour in day (0-23)	Number	23
m	Minute in hour (0-59)	Number	59
s	Second in minute	Number	55
S	Millisecond	Number	950
E	Day in week	Text	E –> Sat EEEE –> Saturday
D	Day in year	Number	84
F	Day of week in month	Number	4 (4th Saturday of March)
w	Week in year	Number	12
W	Week in month	Number	4
a	am/pm marker	Text	AM
k	Hour in day (1-24)	Number	23
K	Hour in am/pm (0-11)	Number	11
z	Time zone	Text	Pacific Standard Time
X	Time zone offset	Text	X –> -07 XXX –> -07:00
‘	Escape for text	Delimiter

API Functions

HTTP request, Encode and Decode. Some tools you can use to test 3rd party APIs before using them in Yonyx Functions are Postman, JSONPath Online Evaluator and XPather.

Encode

Returns an encoded version of the given string.

Example 1:

INPUT PARAMETER(S):
Set “string” to “Lorem?ipsum”

Set “encoder” to “Base64”

OUTPUT PARAMETER(S):
The output parameter “encoded” carries the value “TG9yZW0/aXBzdW0=” which will be assigned to a placeholder that you choose.

Example 2:

INPUT PARAMETER(S):
Set “string” to “Lorem?ipsum”

Set “encoder” to “Base64 URL Safe”

OUTPUT PARAMETER(S):
The output parameter “encoded” carries the value “TG9yZW0_aXBzdW0=” which will be assigned to a placeholder that you choose.

Example 3:

INPUT PARAMETER(S):
Set “string” to “name=Yonyx Decision Trees”

Set “encoder” to “URL”

OUTPUT PARAMETER(S):
The output parameter “encoded” carries the value “name%3DYonyx+Decision+Trees” which will be assigned to a placeholder that you choose.

Decode

Returns an decoded version of the given string.

Example 1:

INPUT PARAMETER(S):
Set “string” to “TG9yZW0/aXBzdW0=”

Set “decoder” to “Base64”

OUTPUT PARAMETER(S):
The output parameter “decoded” carries the value “Lorem?ipsum” which will be assigned to a placeholder that you choose.

Example 2:

INPUT PARAMETER(S):
Set “string” to “TG9yZW0_aXBzdW0=”

Set “decoder” to “Base64 URL Safe”

OUTPUT PARAMETER(S):
The output parameter “decoded” carries the value “Lorem?ipsum” which will be assigned to a placeholder that you choose.

Example 3:

INPUT PARAMETER(S):
Set “string” to “name%3DYonyx+Decision+Trees”

Set “decoder” to “URL”

OUTPUT PARAMETER(S):
The output parameter “decoded” carries the value “name=Yonyx Decision Trees” which will be assigned to a placeholder that you choose.

HTTP Request

Make HTTP requests to connect to API endpoints. HTTP requests can retrieve, add, delete, and update data. At the moment, any API both public and authenticated (basic authentication, Access token authentication, and OAuth 2.0 bearer token authentication) are supported. If the API responds with a payload (xml or JSON), this function is capable of extracting values (single string or list of strings) from it. Lists of strings are extracted in a format that is compatible with Checkbox list control for Yonyx data capture commands.

Using different public APIs, we will walk through multiple use cases with examples and understand the following aspects of HTTP Request function:

Pass parameters either as path parameters or URL parameters.
Set Headers for Authentication or Authorization.
Set Request Body
Specify path expressions (XPath/JSONPath) in output parameter ‘body-extracts-string’ and ‘body-extracts-list’ to extract specific properties from the API Response body. You can use tools like JSONPath Online Evaluator and XPather to test and construct correct path expressions.
Specify header names in output parameter ‘header-extracts’ to extract specific header values from the API Response header
Examine the default output parameters ‘succeess’ and ‘message’ to determine if the API succeeded or failed and auto traverse accordingly.

API Function Examples

Ex.1 – ReqRes GET

API: ReqRes is a test REST endpoint located at https://reqres.in/
Task: Retrieves list of users and extracts the user object at index 0 (first user object).

INPUT PARAMETER(S):
url <– “https://reqres.in/api/users”
Set “url” to “https://reqres.in/api/users”

method <– “GET”
Set “method” to “GET”

query-params <– [
“page” <– “2”
]

Add a query parameter “page” with value set to “2”.

Skip Content-Type input parameter.

Skip headers input parameter.

Skip body input parameter.

response-format <– “JSON”
Set “response-format” to “JSON” because we expect the API to respond with JSON.

OUTPUT PARAMETER(S):
true –> placeholder you choose
The output parameter “success” carries the value “true” if API succeeds or “false” if it fails – which will be assigned to a placeholders.

message –> placeholder you choose
The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

body-extracts <– [
   $.data[0].email –> placeholder you choose
   $.data[0].first_name –> placeholder you choose
   $.data[0].last_name –> placeholder you choose
   $.data[0].avatar –> placeholder you choose
]
body-extracts output parameter is where you specify JSONPaths to extract values and store into placeholder you choose.
Extract the email of the user “michael.lawson@reqres.in” located at path “$.data[0].email” and store it in a placeholder.
Extract the first name of the user “Michael” located at path “$.data[0].first_name” and store it in a placeholder.
Extract the last name of the user “Lawson” located at path “$.data[0].last_name” and store it in a placeholder.
Extract the avatar of the user “https://reqres.in/img/faces/7-image.jpg” located at path “$.data[0].avatar” and store it in a placeholder.

Skip header-extracts output parameter.

The actual JSON response of this call is:

{
  "page": 2,
  "per_page": 6,
  "total": 12,
  "total_pages": 2,
  "data": [
    {
      "id": 7,
      "email": "michael.lawson@reqres.in",
      "first_name": "Michael",
      "last_name": "Lawson",
      "avatar": "https://reqres.in/img/faces/7-image.jpg"
    },
    {
      "id": 8,
      "email": "lindsay.ferguson@reqres.in",
      "first_name": "Lindsay",
      "last_name": "Ferguson",
      "avatar": "https://reqres.in/img/faces/8-image.jpg"
    },
    {
      ...
    },
    {
      ...
    },
    ...
  ],
  "support": {
    "url": "https://reqres.in/#support-heading",
    "text": "To keep ReqRes free, contributions towards server costs are appreciated!"
  }
}

Ex.2 – ReqRes POST

API: ReqRes is a test REST endpoint located at https://reqres.in/
Task: Creates a new user and extracts the user’s name and job from API’s response.

INPUT PARAMETER(S):
url <– “https://reqres.in/api/users”
Set “url” to “https://reqres.in/api/users”

method <– “POST”
Set “method” to “POST”

Skip query-params input parameter.

Content-Type <– “application/json”
Set “Content-Type” to “application/json”

Skip headers input parameter.

body <–

{
    "name": "morpheus",
    "job": "leader"
}

Set “body” to JSON payload.

response-format <– “JSON”
Set “response-format” to “JSON” because we expect the API to respond with JSON.

message –> placeholder you choose
The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

body-extracts <– [
   $.id –> placeholder you choose
   $.name –> placeholder you choose
   $.job –> placeholder you choose
   $.createdAt –> placeholder you choose
]
body-extracts output parameter is where you specify JSONPaths to extract values and store into placeholder you choose.
Extract the id of the user “699” located at path “$.data[0].email” and store it in a placeholder.
Extract the name of the user “morpheus” located at path $.name; and store it in a placeholder.
Extract the job of the user “leader” located at path $.job and store it in a placeholder.
Extract the createdAt of the user located at path $.createdAt and store it in a placeholder.

Skip header-extracts output parameter.

The actual JSON response of this call is:

{
  "name": "morpheus",
  "job": "leader",
  "id": "699",
  "createdAt": "2023-05-30T16:09:30.637Z"
}

Ex.3 – ReqRes DELETE

API: ReqRes is a test REST endpoint located at https://reqres.in/
Task: Delete an existing user whose id is 2.

INPUT PARAMETER(S):
url <– “https://reqres.in/api/users/2”
Set “url” to “https://reqres.in/api/users/2”

method <– “DELETE”
Set “method” to “DELETE”

Skip query-params input parameter.

Skip Content-Type input parameter.

Skip headers input parameter.

Skip body input parameter.

Leave response-format as is.

message –> placeholder you choose
The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

Skip body-extracts output parameter.

Skip header-extracts output parameter.

Ex.4 – Postman Echo POST Raw Text

API: Postman Echo is a service you can use to test REST API calls. It provides endpoints for GET, POST, PUT, and various auth mechanisms located at https://postman-echo.com
Task: Make a POST request with TEXT payload and extracts specific values from response body and header.

INPUT PARAMETER(S):
url <– “https://postman-echo.com/post”
Set “url” to “https://postman-echo.com/post”

method <– “POST”
Set “method” to “POST”

Skip query-params input parameter.

Content-Type <– “text/plain”
Set “Content-Type” to “text/plain”

Skip headers input parameter.

body <–This is expected to be sent back as part of response body.

Set “body” to TEXT payload.

response-format <– “JSON”
Set “response-format” to “JSON” because we expect the API to respond with JSON.

message –> placeholder you choose
The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

body-extracts <– [
$.data –> placeholder you choose
]
body-extracts output parameter is where you specify JSONPaths to extract values and store into placeholder you choose.
Extract the data from the reponse body “This is expected to be sent back as part of response body.” located at path “$.data” and store it in a placeholder.

Skip header-extracts output parameter.

The actual JSON response of this call is:

{
    "args": {},
    "data": "This is expected to be sent back as part of response body.",
    "files": {},
    "form": {},
    "headers": {
        "x-forwarded-proto": "https",
        "x-forwarded-port": "443",
        "host": "postman-echo.com",
        "x-amzn-trace-id": "Root=1-64762d94-73cce04561cfc2b018c765e1",
        "content-length": "58",
        "content-type": "text/plain",
        "user-agent": "PostmanRuntime/7.32.2",
        "accept": "*/*",
        "postman-token": "8036c92d-38bd-4c1f-b30a-ec44b3fa8304",
        "accept-encoding": "gzip, deflate, br"
    },
    "json": null,
    "url": "https://postman-echo.com/post"
}

Ex.5 – Postman Echo GET Basic Auth

API: Postman Echo is a service you can use to test REST API calls. It provides endpoints for GET, POST, PUT, and various auth mechanisms located at https://postman-echo.com
Task: Make a basic authenticated GET request with base64 encoded payload (postman:password) and extracts specific values from response body and header.

INPUT PARAMETER(S):
url <– “https://postman-echo.com/basic-auth”
Set “url” to “https://postman-echo.com/basic-auth”

method <– “GET”
Set “method” to “GET”

Skip query-params input parameter.

Skip Content-Type input parameter.

headers <– [
“Authorization” <– “Basic cG9zdG1hbjpwYXNzd29yZA==”
]
Add a header “Authorization” with value set to “Basic cG9zdG1hbjpwYXNzd29yZA==”. The random characters here are the output of Encode function which took “postman:password” as input.

Skip body input parameter.

response-format <– “JSON”
Set “response-format” to “JSON” because we expect the API to respond with JSON.

message –> placeholder you choose
The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

body-extracts <– [
$.authenticaated –> placeholder you choose
]
body-extracts output parameter is where you specify JSONPaths to extract values and store into placeholder you choose.
Extract “authenticated” from the reponse body “true” located at path “$.authenticated” and store it in a placeholder.

Skip header-extracts output parameter.

The actual JSON response of this call is: { “authenticated”: true }

Ex.6 – HttpBin.org POST Multipart/form-data

API: HttpBin.org is a simple HTTP Request & Response service you can use to test REST API calls. It provides endpoints for GET, POST, PUT, etc located at https://httpbin.org
Task: Make a POST multipart/form-data request with payload (name, email, address) and extracts specific values from response body and header.

INPUT PARAMETER(S):
url <– “https://httpbin.org/post”
Set “url” to “https://httpbin.org/post”

method <– “POST”
Set “method” to “POST”

query-params <– [
   “name” <– “Adrian Purdy”
   “email” <– “adrian.p@email.com”
   “address” <– “2001 Woodruff Rd, Greenville, South Carolina 29607, USA”
]
Add a query parameters “name” with value set to “Adrian Purdy”, “email” with value set to “adrian.p@email.com”, and “address” with value set to “2001 Woodruff Rd, Greenville, South Carolina 29607, USA”

Content-Type <– “multipart/form-data”
Set “Content-Type” to “multipart/form-data”

Skip headers input parameter.

Skip body input parameter.

response-format <– “JSON”
Set “response-format” to “JSON” because we expect the API to respond with JSON.

message –> placeholder you choose
The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

body-extracts <– [
   $.form.name –> placeholder you choose
   $.form.email –> placeholder you choose
   $.form.address –> placeholder you choose
]
body-extracts output parameter is where you specify JSONPaths to extract values and store into placeholder you choose.
Extract “name” from the response body “Adrian Purdy” located at path “$.form.name” and store it in a placeholder.
Extract “email” from the response body “adrian.p@email.com” located at path “$.form.email” and store it in a placeholder.
Extract “address” from the response body “2001 Woodruff Rd, Greenville, South Carolina 29607, USA” located at path “$.form.address” and store it in a placeholder.

header-extracts <– [
   Content-Type –> placeholder you choose
   Content-Length –> placeholder you choose
   Server –> placeholder you choose
]
header-extracts output parameter is where you specify Header names to extract values from the response header and store into placeholder you choose.
Extract “Content-Type” from the response header “application/json” and store it in a placeholder.
Extract “Content-Length” from the response header “711” and store it in a placeholder.
Extract “Server” from the response header “gunicorn/19.9.0” and store it in a placeholder.

The actual JSON response of this call is:

{
  "args": {}, 
  "data": "", 
  "files": {}, 
  "form": {
    "address": "2001 Woodruff Rd, Greenville, South Carolina 29607, USA",
    "email": "adrian.p@email.com", 
    "name": "Adrian Purdy"
  }, 
  "headers": {
    "Content-Length": "396", 
    "Content-Type": "multipart/form-data; boundary=----YonyxFormBoundarySvP3PVXNCT63ZUS", 
    "Host": "httpbin.org", 
    "User-Agent": "Java-http-client/17.0.2", 
    "X-Amzn-Trace-Id": "Root=1-647702e9-486c9fc132cead02085a2be6"
  }, 
  "json": null, 
  "origin": "94.202.70.100", 
  "url": "https://httpbin.org/post"
}

The actual response Header of this call is:

HTTP/1.1 200 OK
Date: Wed, 31 May 2023 08:21:16 GMT
Content-Type: application/json
Content-Length: 711
Connection: keep-alive
Server: gunicorn/19.9.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true

Ex.7 – Google Address Validation – POST

API: Google Address Validation is an API that takes an address and returns standardized address. It is located at https://developers.google.com/maps/documentation/address-validation/overview.
This API requires Api key authentication, so you will have to get your own API key if you are following this example.
Task: Makes a POST request with payload (address) and extracts specific values from response body and header.

INPUT PARAMETER(S):
url <– “https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_OWN_API_KEY”
Set “url” to “https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_OWN_API_KEY”

method <– “POST”
Set “method” to “POST”

Skip query-params input parameter.

Content-Type <– “application/json”
Set “Content-Type” to “appliction/json”

Skip headers input parameter.

body <–

{
	"address": {
		"regionCode": "US",
		"locality": "Mountain View",
		"addressLines": ["1600 Amphitheatre Pkwy"]
	}
}

Set body to the JSON address payload

response-format <– “JSON”
Set “response-format” to “JSON” because we expect the API to respond with JSON.

message –> placeholder you choose
The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

body-extracts <– [
   $..addressComponents[?(@.componentType == “street_number”)].componentName.text –> placeholder you choose
   $..addressComponents[?(@.componentType == “route”)].componentName.text –> placeholder you choose
   $..addressComponents[?(@.componentType == “locality”)].componentName.text –> placeholder you choose
   $..addressComponents[?(@.componentType == “country”)].componentName.text –> placeholder you choose
   $..addressComponents[?(@.componentType == “administrative_area_level_1”)].componentName.text –> placeholder you choose
   $..addressComponents[?(@.componentType == “postal_code”)].componentName.text –> placeholder you choose
   $..addressComponents[?(@.componentType == “postal_code_suffix”)].componentName.text –> placeholder you choose
]
body-extracts output parameter is where you specify JSONPaths to extract values and store into placeholder you choose.
Extract “street_number” from the response body “1600” located at specified path and store it in a placeholder.
Extract “route” from the response body “Amphitheatre Parkway” located at specified path and store it in a placeholder.
Extract “locality” from the response body “Mountain View” located at specified path and store it in a placeholder.
Extract “country” from the response body “USA” located at specified path and store it in a placeholder.
Extract “administrative_area_level_1” from the response body “Mountain View” located at specified path and store it in a placeholder.
Extract “postal_code” from the response body “Mountain View” located at specified path and store it in a placeholder.
Extract “postal_code_suffix” from the response body “Mountain View” located at specified path and store it in a placeholder.

header-extracts <– [
Alt-Svc –> placeholder you choose
Server –> placeholder you choose
]
header-extracts output parameter is where you specify Header names to extract values from the response header and store into placeholder you choose.
Extract “Alt-Svc” from the response header ‘h3=”:443″; ma=2592000,h3-29=”:443″; ma=2592000’ and store it in a placeholder.
Extract “Server” from the response header “scaffolding on HTTPServer2” and store it in a placeholder.

The actual JSON response of this call is:

{
  "result": {
    "verdict": {
      "inputGranularity": "PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "addressComplete": true,
      "hasInferredComponents": true
    },
    "address": {
      "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "componentName": {
            "text": "1600"
          },
          "componentType": "street_number",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Amphitheatre Parkway",
            "languageCode": "en"
          },
          "componentType": "route",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Mountain View",
            "languageCode": "en"
          },
          "componentType": "locality",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "USA",
            "languageCode": "en"
          },
          "componentType": "country",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "94043"
          },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "CA",
            "languageCode": "en"
          },
          "componentType": "administrative_area_level_1",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "1351"
          },
          "componentType": "postal_code_suffix",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        }
      ]
    },
    "geocode": {
      "location": {
        "latitude": 37.4223878,
        "longitude": -122.0841877
      },
      "plusCode": {
        "globalCode": "849VCWC8+X8"
      },
      "bounds": {
        "low": {
          "latitude": 37.4220699,
          "longitude": -122.084958
        },
        "high": {
          "latitude": 37.4226618,
          "longitude": -122.0829302
        }
      },
      "featureSizeMeters": 116.538734,
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g",
      "placeTypes": [
        "premise"
      ]
    },
    "metadata": {
      "business": true,
      "poBox": false
    },
    "uspsData": {
      "standardizedAddress": {
        "firstAddressLine": "1600 AMPHITHEATRE PKWY",
        "cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
        "city": "MOUNTAIN VIEW",
        "state": "CA",
        "zipCode": "94043",
        "zipCodeExtension": "1351"
      },
      "deliveryPointCode": "00",
      "deliveryPointCheckDigit": "0",
      "dpvConfirmation": "Y",
      "dpvFootnote": "AABB",
      "dpvCmra": "N",
      "dpvVacant": "N",
      "dpvNoStat": "Y",
      "carrierRoute": "C909",
      "carrierRouteIndicator": "D",
      "postOfficeCity": "MOUNTAIN VIEW",
      "postOfficeState": "CA",
      "fipsCountyCode": "085",
      "county": "SANTA CLARA",
      "elotNumber": "0103",
      "elotFlag": "A",
      "addressRecordType": "S"
    }
  },
  "responseId": "5e0afdd2-cbc9-442e-8ba6-31c598293518"
}

The actual response Header of this call is:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer
Content-Encoding: gzip
Date: Wed, 31 May 2023 08:55:06 GMT
Server: scaffolding on HTTPServer2
Cache-Control: private
X-XSS-Protection: 0
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
Alt-Svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
Transfer-Encoding: chunked

Ex.8 – ATTOM GET JSON

API: ATTOM is a real estate data API located at https://api.gateway.attomdata.com/property/.
This API requires API key authentication, so you will have to get your own API key if you are following this example.
Task: Makes an API key authenticated GET request and extracts specific values from response body.

INPUT PARAMETER(S):
url <– “https://api.gateway.attomdata.com/propertyapi/v1.0.0/property/id”
Set “url” to “https://api.gateway.attomdata.com/propertyapi/v1.0.0/property/id”

method <– “GET”
Set “method” to “GET”

query-params <– [
“geoid” <– “PL0820000”
“minBeds” <– “1”
“maxBeds” <– “2”
]
Add query parameters “geoid” with value set to “PL0820000”, “minBeds” with value set to “1”, and “maxBeds” with value set to “2”

Content-Type <– “application/json”
Set “Content-Type” to “appliction/json”

headers <– [
“apikey” <– “YOUR_OWN_API_KEY”
]
Add a header “apikey” with value set to your own API key from ATTOM.

Skip body input parameter.

response-format <– “JSON”
Set “response-format” to “JSON” because we expect the API to respond with JSON.

message –> placeholder you choose
The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

body-extracts <– [
$.property[0].identifier.fips –> placeholder you choose
$.property[0].identifier.apn –> placeholder you choose
$.property[0].identifier.attomId –> placeholder you choose
]
body-extracts output parameter is where you specify JSONPaths to extract values and store into placeholder you choose.
Extract “fips” from the response body “08031” located at specified path and store it in a placeholder.
Extract “apn” from the response body “05053-14-021-000” located at specified path and store it in a placeholder.
Extract “attomId” from the response body “143367” located at specified path and store it in a placeholder.

Skip header-extracts output parameter.

The actual JSON response of this call is:

{
  "status": {
    "version": "1.0.0",
    "code": 0,
    "msg": "SuccessWithResult",
    "total": 10000,
    "page": 1,
    "pagesize": 10,
    "transactionID": "e5476a46b543ab5c2fdf48de27e13a1a"
  },
  "property": [
    {
      "identifier": {
        "Id": 143367,
        "fips": "08031",
        "apn": "05053-14-021-000",
        "attomId": 143367
      },
      "vintage": {
        "lastModified": "2023-05-12",
        "pubDate": "2023-05-12"
      }
    },
    {
      "identifier": {
        "Id": 145233,
        "fips": "08031",
        "apn": "05036-12-019-000",
        "attomId": 145233
      },
      "vintage": {
        "lastModified": "2023-05-12",
        "pubDate": "2023-05-12"
      }
    },
    {
      "identifier": {
        "Id": 145234,
        "fips": "08031",
        "apn": "05066-00-144-144",
        "attomId": 145234
      },
      "vintage": {
        "lastModified": "2023-05-12",
        "pubDate": "2023-05-12"
      }
    },
    {
      "identifier": {
        "Id": 145235,
        "fips": "08031",
        "apn": "05065-14-015-000",
        "attomId": 145235
      },
      "vintage": {
        "lastModified": "2023-05-12",
        "pubDate": "2023-05-12"
      }
    },
    {
      "identifier": {
        "Id": 146764,
        "fips": "08031",
        "apn": "05066-16-005-000",
        "attomId": 146764
      },
      "vintage": {
        "lastModified": "2023-05-12",
        "pubDate": "2023-05-12"
      }
    },
    {
      "identifier": {
        "Id": 147148,
        "fips": "08031",
        "apn": "05304-03-007-000",
        "attomId": 147148
      },
      "vintage": {
        "lastModified": "2023-05-12",
        "pubDate": "2023-05-12"
      }
    },
    {
      "identifier": {
        "Id": 147149,
        "fips": "08031",
        "apn": "05102-26-026-000",
        "attomId": 147149
      },
      "vintage": {
        "lastModified": "2023-05-12",
        "pubDate": "2023-05-12"
      }
    },
    {
      "identifier": {
        "Id": 147151,
        "fips": "08031",
        "apn": "00221-01-037-000",
        "attomId": 147151
      },
      "vintage": {
        "lastModified": "2023-05-12",
        "pubDate": "2023-05-12"
      }
    },
    {
      "identifier": {
        "Id": 147152,
        "fips": "08031",
        "apn": "02291-21-035-000",
        "attomId": 147152
      },
      "vintage": {
        "lastModified": "2023-05-12",
        "pubDate": "2023-05-12"
      }
    },
    {
      "identifier": {
        "Id": 147157,
        "fips": "08031",
        "apn": "00186-03-016-000",
        "attomId": 147157
      },
      "vintage": {
        "lastModified": "2023-05-12",
        "pubDate": "2023-05-12"
      }
    }
  ]
}

Ex.9 – ATTOM GET XML

INPUT PARAMETER(S):
url <– “https://api.gateway.attomdata.com/property/v2/propertysearch/address/11235/S/STEWART/AVE/-/Chicago/US/IL/60628”
Set “url” to “https://api.gateway.attomdata.com/property/v2/propertysearch/address/11235/S/STEWART/AVE/-/Chicago/US/IL/60628”

Note: URL can be dynamically constructed. https://api.gateway.attomdata.com/property/v2/propertysearch/address/{{ev:number}}/{{ev:direction}}/{{ev:street}}/{{ev:suffix}}/{{ev:unit}}/{{ev:city}}/{{ev:country}}/{{ev:state}}/{{ev:zip}}

method <– “GET”
Set “method” to “GET”

Skip query-params input parameter.

Skip Content-Type input parameter.

headers <– [
“Accept” <– “text/xml”
“apikey” <– “YOUR_OWN_API_KEY”
]
Add headers “Accept” with value set to “text/xml” and “apikey” with value set to your own API key from ATTOM.

Skip body input parameter.

response-format <– “XML”
Set “response-format” to “XML” because we expect the API to respond with XML.

message –> placeholder you choose
The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

body-extracts <–

[
/RESPONSE_GROUP/RESPONSE/RESPONSE_DATA/PROPERTY_INFORMATION_RESPONSE_ext/SUBJECT_PROPERTY_ext/PROPERTY/MAILING_ADDRESS_ext[@_City]/@_City –> placeholder you choose
/RESPONSE_GROUP/RESPONSE/RESPONSE_DATA/PROPERTY_INFORMATION_RESPONSE_ext/SUBJECT_PROPERTY_ext/PROPERTY/MAILING_ADDRESS_ext[@_State]/@_State –> placeholder you choose
]

body-extracts output parameter is where you specify XPath to extract values and store into placeholder you choose.
Extract “_City” from the response body “DARIEN” located at specified path and store it in a placeholder.
Extract “_State” from the response body “IL” located at specified path and store it in a placeholder.

Skip header-extracts output parameter.

The actual XML response of this call is:

<RESPONSE_GROUP>
  <RESPONDING_PARTY _Name="ATTOM Data Solutions" _StreetAddress="505 Technology Drive, Suite 100" _City="Irvine" _State="CA" _PostalCode="92618" />
  <RESPONSE ResponseDateTime="2023-05-31T02:31:19">
    <KEY _Name="TransactionId" _Value="e7720fec-a7e4-41e0-98b0-227ef7d96bb4" />
    <RESPONSE_DATA>
      <PROPERTY_INFORMATION_RESPONSE_ext>
        <SUBJECT_PROPERTY_ext>
          <PROPERTY PropertyParcelID_ext="20823815" APNFormatted_ext="25-21-212-003" OwnerNames_ext="LAWRENCE LEBLANC" _State="IL" _PostalCode="60628" _City="CHICAGO">
            <PRODUCT_INFO_ext ReportID_ext="105" ReportDescription_ext="PropertySearch" Product_ext="PropertySearch" RecordNumber_ext="0" MappingVersion_ext="1" />
            <PARSED_STREET_ADDRESS _DirectionPrefix="S" _HouseNumberFraction_ext="" _HouseNumber="11235" _DirectionSuffix="" _StreetName="STEWART" _StreetSuffix="AVE" _ApartmentOrUnitPrefix_ext="" _ApartmentOrUnit="" PlusFourPostalCode="4751" />
            <MAILING_ADDRESS_ext _City="DARIEN" _State="IL" _PostalCode="60561">
              <PARSED_STREET_ADDRESS _DirectionPrefix="" _HouseNumber="7721" _HouseNumberFraction_ext="" _DirectionSuffix="" _StreetName="SAWYER" _StreetSuffix="RD" _ApartmentOrUnit="" _ApartmentOrUnitPrefix_ext="" PlusFourPostalCode="4818" />
            </MAILING_ADDRESS_ext>
          </PROPERTY>
        </SUBJECT_PROPERTY_ext>
      </PROPERTY_INFORMATION_RESPONSE_ext>
    </RESPONSE_DATA>
  </RESPONSE>
  <PRODUCT>
    <STATUS _Code="0" _Condition="Success" _Name="Success" _Description="Successful execution" />
  </PRODUCT>
  <ECHOED_FIELDS_ext JobID="" LoanNumber="" PreparedBy="" ResellerID="" PreparedFor="" />
</RESPONSE_GROUP>

Ex.10 – FedEx Address Validation with OAuth 2.0 Bearer token authentication

API: FedEx offers Address validation API among others APIs like Rates and Transit Times, Shipping, Tracking, etc. The Address validation API is located at https://developer.fedex.com/api/en-us/catalog/address-validation/v1/address/v1/addresses/resolve.

This API requires OAuth 2.0 Bearer token authentication, so you will have to register with FedEx developer account to get your own API credentials if you are following this example.
Task: Makes an OAuth 2.0 Bearer token authenticated POST request and extracts specific values from response body.

This is a 2-step process:

1. Get OAuth token.

2. Validate address.

1. Get OAuth Token:

INPUT PARAMETER(S):
Set “url” to “https://apis-sandbox.fedex.com/oauth/token”

Set “method” to “POST”

Add the following query parameters:

“grant_type” with value set to “client_credentials”

“client_id” with value set to the client id you received when you created your developer account.

“client_secret” with value set to the client secret you received when you created your developer account.

Set “Content-Type” to “APPLICATION/X-WWW-FORM-URLENCODED”

Leave header parameter empty.

Leave body parameter empty.

Set “response-format” to “JSON” because we expect the API to respond with JSON.

OUTPUT PARAMETER(S):
The output parameter “success” carries the value “true” if API succeeds or “false” if it fails – which will be assigned to a placeholders.

The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

body-extracts-string output parameter is where you specify JSONPaths to extract values and store into placeholder you choose.
Extract “access-token” from the response body “the-access-token-from-response” located at JSONPath “$.access_token” and store it in a placeholder.

Skip body-extracts-list output parameter.

Skip header-extracts output parameter.

The actual JSON response of this call is:

{
	"access_token":"eyJhbGciOiJSUzI1....UeVIKZzc",
	"token_type":"bearer",
	"expires_in":3599,
	"scope":"CXS"
}

2. Validate Address:

INPUT PARAMETER(S):
Set “url” to “https://apis-sandbox.fedex.com/address/v1/addresses/resolve”

Set “method” to “POST”

Leave query parameters empty.

Set “Content-Type” to “APPLICATION/JSON”

Add the following headers:

Set “Authorization” to “Bearer {{ev:access-token}}”

Note: {{ev:access-token}} will get replaced with the actual access token (eyJhbGciOiJSUzI1….UeVIKZzc) we extracted in the previous call.

Set body to the following:

{
  "addressesToValidate": [
    {
      "address": {
        "streetLines": [
          "{{ev:street}}"
        ],
        "city": "{{ev:city}}",
        "stateOrProvinceCode": "{{ev:state}}",
        "countryCode": "{{ev:country}}",
        "addressVerificationId": "string"
      }
    }
  ]
}

Note:
{{ev:street}}, {{ev:city}}, {{ev:state}} and {{ev:country}} are placeholders that were set to some values during the journey.
In this example the placeholders were set to the following values:
"street" was set to "7372 PARKRIDGE"
"city" was set to "IRVING"
"state" was set to "TX"
"country" was set to "US"

Set “response-format” to “JSON” because we expect the API to respond with JSON.

OUTPUT PARAMETER(S):
The output parameter “success” carries the value “true” if API succeeds or “false” if it fails – which will be assigned to a placeholders.

The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

body-extracts-string output parameter is where you specify JSONPaths to extract values and store into placeholder you choose.

Extract “street” from the response body “7372 PARKRIDGE BLVD” located at JSONPath “$.output.resolvedAddresses[0].streetLinesToken[0]” and store it in a placeholder.

Extract “city” from the response body “IRVING” located at JSONPath “$.output.resolvedAddresses[0].city” and store it in a placeholder.

Extract “state” from the response body “TX” located at JSONPath “$.output.resolvedAddresses[0].stateOrProvinceCode” and store it in a placeholder.

Extract “zip” from the response body “75063” located at JSONPath “$.output.resolvedAddresses[0].parsedPostalCode.base” and store it in a placeholder.

Extract “country” from the response body “US” located at JSONPath “$.output.resolvedAddresses[0].countryCode” and store it in a placeholder.

Skip body-extracts-list output parameter.

Skip header-extracts output parameter.

The actual JSON response of this call is:

{
  "transactionId": "2fffd391-87bd-475d-9510-9f63d70448ef",
  "output": {
    "resolvedAddresses": [
      {
        "streetLinesToken": [
          "7372 PARKRIDGE BLVD"
        ],
        "city": "IRVING",
        "stateOrProvinceCode": "TX",
        "postalCode": "75063-8659",
        "parsedPostalCode": {
          "base": "75063",
          "addOn": "8659",
          "deliveryPoint": "99"
        },
        "countryCode": "US",
        "classification": "UNKNOWN",
        "ruralRouteHighwayContract": false,
        "generalDelivery": false,
        "customerMessages": [
          {
            "code": "SUITE.NUMBER.REQUIRED",
            "message": "Invalid or missing Apartment/Suite"
          }
        ],
        "normalizedStatusNameDPV": false,
        "standardizedStatusNameMatchSource": "Postal",
        "resolutionMethodName": "USPS_VALIDATE",
        "attributes": {
          "POBox": "false",
          "POBoxOnlyZIP": "false",
          "SplitZIP": "false",
          "SuiteRequiredButMissing": "true",
          "InvalidSuiteNumber": "false",
          "ResolutionInput": "RAW_ADDRESS",
          "DPV": "false",
          "ResolutionMethod": "USPS_VALIDATE",
          "DataVintage": "December 2022",
          "MatchSource": "Postal",
          "CountrySupported": "true",
          "ValidlyFormed": "true",
          "Matched": "true",
          "Resolved": "true",
          "Inserted": "false",
          "MultiUnitBase": "true",
          "ZIP11Match": "true",
          "ZIP4Match": "true",
          "UniqueZIP": "false",
          "StreetAddress": "false",
          "RRConversion": "false",
          "ValidMultiUnit": "false",
          "AddressType": "STANDARDIZED",
          "AddressPrecision": "MULTI_TENANT_BASE",
          "MultipleMatches": "false"
        }
      }
    ]
  }
}

Ex.11 – JIRA Create Issue

API: Atlassian JIRA offers REST APIs to create and update Issues. This API is located at https://<your-subdomain>.atlassian.net/rest/api/2/issue/.

This API requires Access token authentication, so you will have to register with Atlassian developer account to get your own API credentials if you are following this example.
Task: Create a new Issue with minimal fields.

INPUT PARAMETER(S):
Set “url” to “https://<your-subdomain>.atlassian.net/rest/api/2/issue/”

Set “method” to “POST”

Skip query parameters.

Set “Content-Type” to “APPLICATION/JSON”

Add the following header(s):
Set “Authorization” to “Basic <your-access-token>”

Set body parameter to this payload:

{
    "fields": {
       "project":
       {
          "key": "PRJ1"
       },
       "summary": "{{ev:title}}",
       "description": "{{ev:description}}",
       "issuetype": {
          "name": "{{ev:type}}"
       }
   }
}

Note:
{{ev:title}}, {{ev:description}}, and {{ev:type}} are placeholders that were previously assigned to some values.
In this example the placeholders were set to the following values:
"title" was set to "Test Issue"
"description" was set to "This is a test JIRA issues, please ignore."
"type" was set to "Bug"

"PRJ1" is simply the project key.

Set “response-format” to “JSON” because we expect the API to respond with JSON.

OUTPUT PARAMETER(S):
The output parameter “success” carries the value “true” if API succeeds or “false” if it fails – which will be assigned to a placeholders.

The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

body-extracts-string output parameter is where you specify JSONPaths to extract values and store into placeholder you choose.
Extract “key” from the response body “PRJ1-10” located at JSONPath “$.key” and store it in a placeholder.

Skip body-extracts-list output parameter.

Skip header-extracts output parameter.

The actual JSON response of this call is:

{
  "id": "10009",
  "key": "PRJ1-10",
  "self": "https://<your-sobdomain>.atlassian.net/rest/api/2/issue/10009"
}

Ex.12 – Zendesk – Read Ticket

API: Zendesk offers REST APIs to create and update Tickets. This API is located at https://<your-subdomain>.zendesk.com/api/v2/tickets/. Documentation can be found here https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/

This API supports both Basic and API token authentication methods.

For Basic Authentication, it expects a header in this format:
Authorization: Basic <BASE64 ENCODE(email:password)>
Eg: If username and password string is jdoe@example.com:pa$$w0rd, then the header would look like this:
Authorization: Basic amRvZUBleGFtcGxlLmNvbTpwYSQkdzByZA==

For API token Authentication, it expects a header in this format:
Authorization: Basic <BASE64 ENCODE(email/token:api-token)>
Eg: If username and token string is jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv, then the header would look like this:
Authorization: Basic amRvZUBleGFtcGxlLmNvbS90b2tlbjo2d2lJQldiR2tCTW8xbVJETXVWd2t3MUVQc05rZVVqOTVQSXoyYWt2

Task: Read an existing ticket from Zendesk.

In order to achieve this task, we will chain two functions.
1. Encode – to encode the string for authentication
2. HTTP Request – to make the actual http GET call

1. Encode Function
INPUT PARAMETER(S):
Set “string” to {{ev:sys-ynx-user-email}}/token:<zendesk-api-token-here>

Set “encoder” to “BASE64”

OUTPUT PARAMETER(S):
The output parameter “encoded” carries the base64 encoded version of the input string which will be assigned to a placeholder that you choose. Let’s say you had already created a placeholder called “token” and are using that placeholder here to store the value of the output parameter “encode”. This is important because we will be passing this placeholder as input to the next function HTTP Request.

2. HTTP Request Function
INPUT PARAMETER(S):
Set “url” to”https://<your-subdomain>.zendesk.com/api/v2/tickets/{{ev:ticket-id}}”.

Notice that {{ev:ticket-id}} is another placeholder that you are using here which could have been set in the previous steps on the user’s journey.

Set “method” to “GET”

Skip query parameters.

Set “Content-Type” to “APPLICATION/JSON”

Add the following header(s):
Set “Authorization” to “Basic {{ev:token}}”

Notice that you are using the output of previous function here as an input.

Leave body empty.

Set “response-format” to “JSON” because we expect the API to respond with JSON.

OUTPUT PARAMETER(S):
The output parameter “success” carries the value “true” if API succeeds or “false” if it fails – which will be assigned to a placeholders.

The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

body-extracts-string output parameter is where you specify JSONPaths to extract values and store into placeholder you choose.
Extract “first-name” from the response body located at JSONPath “$.ticket.custom_fields[?(@.id == “15175380405524”)].value” and store it in a placeholder.

Extract “last-name” from the response body located at JSONPath “$.ticket.custom_fields[?(@.id == “15175380405524”)].value” and store it in a placeholder.

Extract “phone” from the response body located at JSONPath “$.ticket.custom_fields[?(@.id == “23985743”)].value” and store it in a placeholder.

Extract “description” from the response body located at JSONPath “$.ticket.description” and store it in a placeholder.

Extract “subject” from the response body located at JSONPath “$.ticket.subject” and store it in a placeholder.

Skip body-extracts-list output parameter.

Skip header-extracts output parameter.

The actual JSON response of this call is:

{
    "ticket": {
        "url": "https://<your-subdomain>.zendesk.com/api/v2/tickets/1479.json",
        "id": 1479,
        "external_id": null,
        "via": {
            "channel": "web",
            "source": {
                "from": {},
                "to": {},
                "rel": null
            }
        },
        "created_at": "2023-06-16T21:49:15Z",
        "updated_at": "2023-06-16T21:52:55Z",
        "type": null,
        "subject": "Can't login ",
        "raw_subject": "Can't login ",
        "description": "Not sure why?",
        "priority": null,
        "status": "new",
        "recipient": null,
        "requester_id": 481420907,
        "submitter_id": 362619316,
        "assignee_id": null,
        "organization_id": 35463043,
        "group_id": null,
        "collaborator_ids": [],
        "follower_ids": [],
        "email_cc_ids": [],
        "forum_topic_id": null,
        "problem_id": null,
        "has_incidents": false,
        "is_public": true,
        "due_at": null,
        "tags": [
            "family_plan"
        ],
        "custom_fields": [
          ...
            {
                "id": 14656737968404,
                "value": "d9dc63a0-0c8f-11ee-997a-4201c0a8012b"
            },
            {
                "id": 15175380405524,
                "value": "Hanes"
            },
            {
                "id": 15175365857556,
                "value": "Christine"
            },
            {
                "id": 13429169078420,
                "value": "family_plan"
            },
            ...
        ],
        "satisfaction_rating": null,
        "sharing_agreement_ids": [],
        "custom_status_id": 13642571,
        "fields": [
          ...
            {
                "id": 14656737968404,
                "value": "d9dc63a0-0c8f-11ee-997a-4201c0a8012b"
            },
            {
                "id": 15175380405524,
                "value": "Hanes"
            },
            {
                "id": 15175365857556,
                "value": "Christine"
            },
            {
                "id": 13429169078420,
                "value": "family_plan"
            },
            ...
        ],
        "followup_ids": [],
        "ticket_form_id": 13404111369236,
        "brand_id": 2666126,
        "allow_channelback": false,
        "allow_attachments": true,
        "from_messaging_channel": false
    }
}

Ex.13 – Zendesk – Update Ticket

This API supports both Basic and API token authentication methods.

Task: Update an existing ticket in Zendesk.

HTTP Request Function
INPUT PARAMETER(S):
Set “url” to”https://<your-subdomain>.zendesk.com/api/v2/tickets/{{ev:ticket-id}}”.

Notice that {{ev:ticket-id}} is another placeholder that you are using here which could have been set in the previous steps on the user’s journey.

Set “method” to “PUT”

Skip query parameters.

Set “Content-Type” to “APPLICATION/JSON”

Add the following header(s):
Set “Authorization” to”Basic {{ev:token}}” Note: The placeholder called token was computed in an earlier step of the guide and is reused here.

Set “body” to

{
  "ticket": {
    "subject": "{{ev:title}}",
    "comment": {
      "body": "{{ev:notes}}",
      "public": false
    },
    "custom_fields": [
      {
        "id": 15175365857556,
        "value": "{{ev:first-name}}"
      },
      {
        "id": 15175380405524,
        "value": "{{ev:last-name}}"
      },
      {
        "id": 23985743,
        "value": "{{ev:phone}}"
      }
    ]
  }
}
Note: The placeholders first-name, last-name, and phone were presented in a form to the user in an earlier step to allow for changes.

Set “response-format” to “JSON” because we expect the API to respond with JSON.

OUTPUT PARAMETER(S):
The output parameter “success” carries the value “true” if API succeeds or “false” if it fails – which will be assigned to a placeholders.

The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

Skip body-extracts-string output parameter.

Skip body-extracts-list output parameter.

Skip header-extracts output parameter.

Using the placeholder that stores the value of the output parameter “success”, you can branch off either towards success path or towards failure path.

Ex.14 – Freshdesk – Read Ticket

API: Freshdesk offers REST APIs to create and update Tickets, Contacts, and other objects.
This API is located at https://<your-subdomain>.freshdesk.com/api/v2/tickets/.
Documentation can be found here https://developers.freshdesk.com/api/#tickets

This API supports API token authentication method. It expects a header in this format:
Authorization: Basic <BASE64 ENCODE(api-token:X)>
Eg: If token string is abcdefghij1234567890:X, then the header would look like this:
Authorization: Basic YWJjZGVmZ2hpajEyMzQ1Njc4OTA6WA==

Task: Read an existing ticket from Freshdesk.

In order to achieve this task, we will chain two functions.
1. Encode – to encode the string for authentication
2. HTTP Request – to make the actual http GET call

1. Encode Function
INPUT PARAMETER(S):
Set “string” to <your-api-key-here:X>

Set “encoder” to “BASE64”

OUTPUT PARAMETER(S):
The output parameter “encoded” carries the base64 encoded version of the input string which will be assigned to a placeholder that you choose. Let’s say you had already created a placeholder called “token” and are using that placeholder here to store the value of the output parameter “encoded”. This is important because we will be passing this placeholder as input to the next function HTTP Request.

2. HTTP Request Function
INPUT PARAMETER(S):
Set “url” to”https://<your-subdomain>.freshdesk.com/api/v2/tickets/{{ev:ticket-id}}”.

Notice that {{ev:ticket-id}} is another placeholder that you are using here which could have been set in the previous steps on the user’s journey.

Set “method” to “GET”

Skip query parameters.

Set “Content-Type” to “APPLICATION/JSON”

Add the following header(s):
Set “Authorization” to “Basic {{ev:token}}”

Notice that you are using the output of previous function here as an input.

Leave body empty.

Set “response-format” to “JSON” because we expect the API to respond with JSON.

OUTPUT PARAMETER(S):
The output parameter “success” carries the value “true” if API succeeds or “false” if it fails – which will be assigned to a placeholders.

The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

body-extracts-string output parameter is where you specify JSONPaths to extract values and store into placeholder you choose.
Extract “description_text” from the response body located at JSONPath “$.description_text” and store it in a placeholder.

Extract “subject” from the response body located at JSONPath “$.subject” and store it in a placeholder.

Skip body-extracts-list output parameter.

Skip header-extracts output parameter.

The actual JSON response of this call is:

{
    "cc_emails": null,
    "fwd_emails": null,
    "reply_cc_emails": null,
    "ticket_cc_emails": null,
    "fr_escalated": true,
    "spam": false,
    "email_config_id": null,
    "group_id": 1060000055670,
    "priority": 1,
    "requester_id": 1060001463062,
    "responder_id": null,
    "source": 1,
    "company_id": null,
    "status": 2,
    "subject": "Received a broken TV",
    "association_type": null,
    "support_email": null,
    "to_emails": null,
    "product_id": 1060000011924,
    "id": 3,
    "type": "Question",
    "due_by": "2023-06-22T07:00:00Z",
    "fr_due_by": "2023-06-19T16:00:00Z",
    "is_escalated": true,
    "description": "Hi,<br><br>The television I ordered from your site was delivered with a cracked screen. <br><br>I need some help with a refund or a replacement.     <br><br>Here is the order number FD07062010     <br><br><br>Thanks, <br>Sarah",
    "description_text": "Hi,  The television I ordered from your site was delivered with a cracked screen.   I need some help with a refund or a replacement.       Here is the order number FD07062010        Thanks,  Sarah",
    "custom_fields": {
        "cf_reference_number": null
    },
    "created_at": "2023-06-18T05:38:40Z",
    "updated_at": "2023-06-22T13:51:52Z",
    "tags": [],
    "attachments": [],
    "source_additional_info": null,
    "nr_due_by": null,
    "nr_escalated": false
}

Ex.15 – Freshdesk – Update Ticket

API: Freshdesk offers REST APIs to create and update Tickets, Contacts, and other objects. This API is located at https://<your-subdomain>.freshdesk.com/api/v2/tickets/. Documentation can be found here https://developers.freshdesk.com/api/#tickets

This API supports API token authentication method. It expects a header in this format:
Authorization: Basic
Eg: If token string is abcdefghij1234567890:X, then the header would look like this:
Authorization: Basic YWJjZGVmZ2hpajEyMzQ1Njc4OTA6WA==

Task: Update an existing ticket in Freshdesk.

In order to achieve this task, we will chain two functions.
1. Replace – to convert description from text to html (convert text line break to html line break)
2. HTTP Request – to make the actual http PUT call

1. Replace Function
INPUT PARAMETER(S):
Set “string” to: {{ev:description}}

Set “search” to “\n”

Set “search” to “<br/>”

OUTPUT PARAMETER(S):
The output parameter “replaced” carries the html version of the input string which will be assigned to a placeholder that you choose. Let’s say you had already created a placeholder called “description-html” and are using that placeholder here to store the value of the output parameter “replaced”. This is important because we will be passing this placeholder as input to the next function HTTP Request.

2. HTTP Request Function
INPUT PARAMETER(S):
Set “url” to”https://<your-subdomain>.freshdesk.com/api/v2/tickets/{{ev:ticket-id}}”.

Notice that {{ev:ticket-id}} is another placeholder that you are using here which could have been set in the previous steps on the user’s journey.

Set “method” to “PUT”

Skip query parameters.

Set “Content-Type” to “APPLICATION/JSON”

Add the following header(s):
Set “Authorization” to “Basic {{ev:token}}”

Note: The placeholder called token was computed in an earlier step of the guide and is reused here.

Set “body” to

{
  "description" : "{{ev:description-html}}",
  "subject" : "{{ev:subject}}"
}
Note: The placeholders description and subject were presented in a form to the user in an earlier step to allow for changes.

Set “response-format” to “JSON” because we expect the API to respond with JSON.

OUTPUT PARAMETER(S):
The output parameter “success” carries the value “true” if API succeeds or “false” if it fails – which will be assigned to a placeholders.

The output parameter “message” carries the error message if API fails – which will be assigned to a placeholder that you choose.

Skip body-extracts-string output parameter.

Skip body-extracts-list output parameter.

Skip header-extracts output parameter.

Using the placeholder that stores the value of the output parameter “success”, you can branch off either towards success path or towards failure path.

Get Started Now!

Request a Demo

Yonyx Functions

Introduction

Math Functions

String Functions

Date Functions

List Functions

Format Functions

API Functions

API Function Examples

.

Math Functions

Abs

Ceil

Divide

Floor

Max

Min

Modulo

Multiply

Sum

String Functions

Concatenate

Find in string

Length of string

Lower

Replace

Substring

Trim

Upper

Date Functions

Add Date

Age

Convert Date Time

Date Part

Duration

Subtract Date

Time Part

Time of Day – Greeting

List Functions

Add to list

Common in lists

Find in list

Length of list

Remove from list

String to array

String to list

Unique in lists

Format Functions

Format date or time

Format number

Custom Date Time Format Symbols

API Functions

Encode

Decode

HTTP Request

API Function Examples

Ex.1 – ReqRes GET

Ex.2 – ReqRes POST

Ex.3 – ReqRes DELETE

Ex.4 – Postman Echo POST Raw Text

Ex.5 – Postman Echo GET Basic Auth

Ex.6 – HttpBin.org POST Multipart/form-data

Ex.7 – Google Address Validation – POST

Ex.8 – ATTOM GET JSON

Ex.9 – ATTOM GET XML

Ex.10 – FedEx Address Validation with OAuth 2.0 Bearer token authentication

Ex.11 – JIRA Create Issue

Ex.12 – Zendesk – Read Ticket

Ex.13 – Zendesk – Update Ticket

Ex.14 – Freshdesk – Read Ticket

Ex.15 – Freshdesk – Update Ticket

Sign up for a free trial today!