Functions

Every step in a ClearProcess API has pre-processing and post-processing rules that perform data transformations. These transformations prepare parameters for backend systems (in the case of pre-processing) and transform the outputs (in the case of post-processing) from these system calls into something more useful for the API consumer. Within these pre- and post-processing rules, all of the built in Django template tags and filters are available as well as some custom functions we have created for our specific workloads. Functions are broken out into tags and filters:

  • Tags – these modify data permanently in a payload
  • Filters – these modify data at the exact time they are called for faster processing

Tag and filters can also be used together. In the example below, the date filter reformats a date while the dictionary_add_key_value tag stores the new value the in the ClearProcess API payload:

{% dictionary_add_key_value response.payload.ChangeRentalProject2 "START_DATE" start_date|date:"d-b-Y"|upper %}

Tags

There may be errors that occur at different stages during the run of a Clear API. When the API author wishes to notify the user of an error in the system, they can use the add_payload_error to notify the user. These manifest in the ClearWork UI as red error message pop-ups. These errors will also be present in the payload that is returned in the API.

Parameters

  • dictionaryobject – Will always be response.
  • messagestring – The message to display

Example

{% add_payload_error response "User is not authorized to approve this purchase order." %}

Informational, warning, and error messages can be set with add_payload_message. These messages will display in ClearWork UI as pop-ups. The color and behavior of these messages is controlled by several parameters:

Parameters

  • dictionaryobject – Will always be response.
  • messagestring – The message to display
  • stylestring(Defaults to success) Specific styling, options:
    • success – ClearUI Green
    • warning – ClearUI orange
    • info – Bootstrap blue
  • auto_closestring/int(Defaults to 5000ms) Determines how long before the message automatically closes.
  • colorstring – Can override the style color to the named color of your choice (see list below).
  • hiddenboolean – (Defaults to false) Don’t display the message to the user. This is typically used for debugging. The message can still be found in Redux tools.

Examples

Default Success Message

{% add_payload_message response message="Success! A message has been made!" %}

Info Message

{% add_payload_message response message="Here is some info." style="info" %}

Warning Message

{% add_payload_message response message="WARNING: Easily excitable dogs ahead." style="warning" %}

Message Closes After 10 Seconds

{% add_payload_message response message="This will close after 10 seconds" auto_close="10000" %}

Hidden Message

{% add_payload_message response message="You won't see this message" hidden=True %}

Purple Message

{% add_payload_message response message="This message will be purple" color="purple" %}

Color Options

aqua (comes with black text)
black
blue
darkcyan
darkgray
darkgrey
darkslateblue
darkslategray
darkslategrey
firebrick
fuchsia
goldrenrod
gray
green
grey
indigo
lightgray
lightgrey
lime (comes with black text)
maroon
navy
olive
orange
plum
purple
red
rosybrown
royalblue
saddlebrown
salmon
sandybrown
seagreen
sienna
silver
teal
yellow (comes with black text)

Formats a date string in formatted in ISO_8601 according to a format string. Format strings use strptime/strftime formatting

Parameters

  • iso_stringstring – A date string formatted in ISO 8601
  • formatstring – A format string specifying the desired output

Example

{% as_date value "%m/%d/%Y" %}  # "2019-08-27T18:17:52+00:00" => "08/27/2019"

Converts a CSV to a list of dictionaries. The dictionaries keys are read from the header of the CSV.

Example

{% csv_to_list mycsv %}

Input

Year,Make,Model,Mileage
2007,Toyota,Corolloa,128635
2015,Honda,Odyssey,42331
2018,Tesla,S,12011

Output

[{'Make': 'Toyota', 'Mileage': '128635', 'Model': 'Corolloa', 'Year': '2007'},
 {'Make': 'Honda', 'Mileage': '42331', 'Model': 'Odyssey', 'Year': '2015'},
 {'Make': 'Tesla', 'Mileage': '12011', 'Model': 'S', 'Year': '2018'}]

Returns the number of days since a given date to the present. Or, if the argument “ is supplied, calculate the days between two dates.

Parameters

  • datedate – The date to use for calculations (as a date type. see: string_to_date)
  • since_datedate – The date to use for calculations

Example

{% string_to_date '2019-10-03' as created_date %}
{% dayssince created_date %}

Adds an empty dictionary in an existing dictionary at key. Note that this will overwrite any existing value at that key.

Parameters

  • dictionarydictionary – The dictionary to manipulate
  • keystring – The key at which to add an empty dictionary

Example

{% dictionary_add_dictionary mydict "new" %}  # {'a': 1} => {'a': 1, 'new': {}}

Adds a new value to the dictionary at the given key with the given value. Note that this will overwrite any existing value at this key. This tag does not return the set value.

Parameters

  • dictionarydictionary – The dictionary to manipulate
  • keystring – The key to set
  • valueany – The value to set in the dictionary at the given key

Example

{% dictionary_add_key_value user_parameters "newvalue" 42 %}

Adds an empty list in an existing dictionary at key. Note that this will overwrite any existing value at that key.

Parameters

  • dictionarydictionary – The dictionary to manipulate
  • keystring – The key at which to add an empty list

Example

{% dictionary_add_list mydict "new" %}  # {'a': 1} => {'a': 1, 'new': []}

Uppercase all strings in a dictionary.

Parameters

  • dictionarydictionary – The dictionary to uppercase

Example

{% dictionary_capitalize value %}  # {'name': 'Dustin', 'age': 32} => {'name': 'DUSTIN', 'age': 32}

Iterate over the values of a dictionary and perform string replacements on any strings.

Parameters

  • dictionarydictionary – The dictionary to do string replacements in
  • oldvaluestring – The substring to replace
  • newvaluestring – The substring to replace oldvalue with

Example

{% dictionary_value_replace value "Dustin" "Jon" %}  # {'name': 'Dustin', 'age': 32} => {'name': 'Jon', 'age': 32}

Creates a Python-native data structure from the given JSON string. (equivalent to json.loads())

Parameters

  • json_stringstring – The JSON string to load

Example

{% evalJson myjson %}  # "{\"a\": 1}" => {'a': 1} 

Get a value from a dictionary based on a key. This is generally used with the Django as keyword to put this value into another variable for further manipulation.

Parameters

  • dictionarydictionary – The source dictionary
  • keystring – The key to retrieve from the source dictionary

Example

{% get_dictionary_value my_dictionary "b" %}  # {'a': 1, 'b': 2} => 2

Appends a value to a list.

Parameters

  • listlist – The list to append
  • valueany – The value to append to the list

Example

{% list_add_value mylist 42 %}  # [1,2,3] => [1,2,3,42]

Removes the first value in a list that is equal to the given value. This will raise an error if the value does not exist in the list.

Parameters

  • valueany – The value to remove

Example

{% list_remove_value mylist 5 %}  # [4,5,6,5] => [4,6,5]

Frequently, several calls are made into backend systems. It can be convenient to combine the results of those calls into a single dictionary for processing.

first: The first dictionary to merge.

second: The second dictionary to merge. Note that this dictionary takes precedence over the first when keys exist in both.

Parameters

  • firstdictionary – The first dictionary to merge.
  • seconddictionary – The second dictionary to merge. Note that this dictionary takes precedence over the first when keys exist in both.

Example

{% merge_dicts dict1 dict2 %}  # {'a': 1, 'b': 2}, {'b': 3, 'c': 4} => {'a': 1, 'b': 3, 'c': 4}

Removes any empty values from a dictionary. Optionally, sets the values in the returned dictionary to uppercase.

Parameters

  • dictionarydictionary – The dictionary to operate on
  • uppercaseboolean(Defaults to False) Uppercase values in the dictionary.

Example

{% remove_empty_values value %} #  {'a': '', 'b': 1, 'c': []} => {'b': 1}

Perform a string replacement, by replacing oldvalue with newvalue in text.

Parameters

  • textstring – The string to operate on
  • oldvaluestring – The substring to replace
  • newvaluestring – The substring to replace oldvalue with

Example

{% replace mystring "v" "ph" %}  # "Steven" => "Stephen"

Preserve a list as a list, or make a single dictionary into a one-item list. This is used when subsequent code will expect a list. e.g. for loops

Parameters

  • datadictionary or list – The data to return as a list

Example

{% return_as_list mydict as definitely_a_list %}  # {'a': 1} => [{'a': 1}]

Set an HTTP status for a payload. Some backend systems provide inconsistent status codes, e.g. returning both 200 and 404 for Not Found. This tag allows these codes to be normalized.

Parameters

  • payloadpayload – This should be set to the payload variable that is always present in templates
  • statusinteger – The numeric HTTP status code to return

Example

{% set_payload_status payload 400 %}

Occasionally, we have to wait on a backend system to perform some work before moving on with a task. Sleep functions should be used as a last resort, since they consume server resources without accomplishing any work. However, there are instances where there is no reasonable alternative.

Parameters

  • durationinteger – Sleep duration in seconds

Example

{% sleep_use_at_your_own_peril 5 %}

Chunks a string into a list of chunk_size length strings. This is useful for some backend systems that use line-based storage for large strings. The last string may be smaller than chunk_size; no padding is added.

string: The string to chunk

chunk_size: The chunk size for output strings #### Parameters – stringstring – The string to chunk – chunk_sizeinteger – The chunk size for output strings

Example

{% split_string_into_chunks value 10 %}  # 'This is my long string' => ['This is my',' long stri','ng']

Converts a string to a date type based on a format string. Format strings use strptime/strftime formatting

format: strptime/strftime format string #### Parameters – formatstring – strptime/strftime format string

Example

{% string_to_date value "%Y-%b-%d" %}  # Correctly converts "1999-Dec-25" to a date type

Attempts to parse a Python dictionary represented as a string into an actual dictionary type.

Parameters

  • stringstring – The dictionary represented as a string

Example

{% string_to_dictionary str %}  # "{'a': 1}" => {'a': 1}

Add or subtract time from a date. (Subtraction is done using negative values.) The date should be provided as a string with a strptime format string. It will be returned in the same format.

Parameters

  • datestring – The date represented as a string
  • formatstring – The strptime format of the date string
  • weeksinteger(Defaults to 0) The number of weeks to add
  • daysinteger(Defaults to 0) The number of days to add
  • hoursinteger(Defaults to 0) The number of hours to add
  • minutesinteger(Defaults to 0) The number of minutes to add
  • millisecondsinteger(Defaults to 0) The number of milliseconds to add

Example

{% timedelta value days=10 %}

Creates a JSON string from the given data. (equivalent to json.dumps())

Parameters

  • dataany – The data to return as a JSON string

Example

{% toJson mydata %}  # {'a': 1} => "{\"a\": 1}"

Filters

Adds a floating point number to the value. Note that both the argument and value are cast to floating point numbers before performing the addition. This is the primary difference between this filter and the built-in add in Django. add will concatenate two strings representing floating points, rather than add them together. For example, consider the following code:

{{ price|add:salestax }}

If price and salestax are the strings “1.00” and “0.07” respectively, with the built-in add, the result is “1.000.07”. The result of add_float is 1.07

Parameters

  • valuefloat – The value to add

Example

{{ price|add_float:salestax }}

In some scenarios, it can be tricky to add an actual newline to a string. Some systems depend upon having newline characters between rows in a table, for instance. This filter appends a newline character (\n) to the given value.

Parameters

  • prefixboolean – If the prefix argument is supplied, the newline will be added to the beginning of the value instead of the end.

Example

{% for line in items %}
    {{ line|add_newline }}
{% endfor %}

Converts a string to ASCII representation by using unicode.normalize(‘NFKD’) before encoding as ASCII, ignoring characters that don’t exist in ASCII.

Official documentaiton on unicode.normalize

Example

{{ value|ascii }}  # 'abc®' => 'abc'

Functions similarly to Django’s add when used with strings, but first uses smart_text which will correctly convert any source encoding to unicode.

Parameters

  • valueany – The value to concanate to the base string. Values will first be converted to strings.

Example

{{ value|concatenate:ascii_value }}

Decodes base64 data to the original format.

Example

{{ value|decode }}

Divide two values. Both values will be cast to floating point numbers before dividing. Note that there is a potential for divide-by-zero errors when using this filter.

Parameters

  • divisornumber – The number to divide by

Example

{{ value|divide:42 }}

Encodes data as base64. Some backend systems consume data in base64.

Example

{{ value|encode }}

Return the value at a given index in a list (or any subscriptable type, e.g.  strings)

Example

{{ my_list|index:1 }}  # ['abc', 'def', 'ghi'] => 'def'

Return the value for a given key in a dictionary. Raises an error for non-existent keys

Parameters

  • keystring – The key to retrieve

Example

{{ my_dict|keyvalue:"name" }}  # {"name": "Jon", "title": "CEO"} => "Jon"

Multiply two values. Both values will be cast to floating point numbers before multiplying. Note that all math functions accept floats as well as strings that can be parsed into floats.

Parameters

  • factorfloat – The factor to multiply by

Example

{{ value|multiply:42 }}

Splits a string into a list of strings, split by the specified separator.

Parameters

  • separatorstring – String or character to use to split string. e.g. “,”, “/”, etc

Example

{{ value|split:',' }}  # "Bryan,Robinson,Derick" => ["Bryan", "Robinson", "Derick"] 

Adds argument to value, after casting to floating-point. The resulting number is then formatted to the second decimal place. This function also handles negative signs presented as suffixes (i.e. “42-” will become “-42” before the add operation takes place)

Parameters

  • valuenumber – The number to add

Example

{{ value|string_add_float:"42-" }} # 47 => 5

Removes leading and trailing whitespace from a string, and returns a unicode value which has been passed through smart_text

Example

{{ value|strip }}  # '  abc def ' => 'abc def'

Subtract two values. Both values will be cast to floating point numbers before subtracting. Note that all math functions accept floats as well as strings that can be parsed into floats.

Parameters

  • valuenumber – The number to subtract

Example

{{ value|subtract:42 }}

Intended for use with for loops, this filter returns a range that can be used to iterate the given number of times.

Example

{% for i in 5|times %}{{ i }}{% endfor %}  # Output: 01234