Help files

Custom Objects

Custom Objects are a type of Variable in WinAutomation that allows users to generate and translate data in JSON format.

This topic consists of the following sections:

1. What is JSON and why is it important?

2. The JSON format

3. The Custom Object format

If you already know what JSON is please feel free to jump straight to c) The Custom Object format.

1. What is JSON and why is it important?

JSON is a text format that is:

a) easy for humans to read and write,

b) easy for machines to parse and generate and

c) completely language independent but uses conventions that are familiar to programmers.

These properties make JSON an ideal data-interchange language that is very popular among web developers.

JSON stands for Javascript Object Notation and it is based on a subset of the JavaScript Programming Language. You can read more about JSON on the Standard's official page.

2. The JSON format

Here is an example of JSON data:

{     "firstName": "John",     "lastName": "Locke",     "address": {         "streetAddress": "24 2nd Street",         "city": "Somerset",         "kingdom": "England",         "postalCode": 10210     },     "phoneNumbers": [         "212 555-1294",         "646 555-6567"     ] }

As you can see, the JSON format is inspired after two structures:

a) an Object, which can be seen as an unordered set of name/value pairs, like { "firstName": "John", "lastName": "Michael" } inside curly braces and separated by commas.

All names has to be strings (i.e. text values), while values can be almost anything, from Boolean to another Object!

Another thing to note is the colon (:) used to separate the name from its corresponding value.

b) an Array, which is an ordered collection of values, like [1,2,3,4] inside brackets and separated by commas.

Same as before, values can be almost anything, from numbers to strings!

The combination of these two structures is allowing the creation of ordered lists of name/value pairs. You can access individual object values by using either the dot (.) notation in the following manner:

myObj = { "name":"John", "age":378, "car":null };

x = myObj.name;

or by using the bracket ([]) notation:

myObj = { "name":"John", "age":378, "car":null };

x = myObj["name"];

3. The Custom Object format

Understanding the JSON format is important, because Custom Objects were created in order to allow us to build and use data in that format within WinAutomation.

Just like JSON, custom objects in WinAutomation consist of a name and a value; they are essentially a pair of two data:

example-of-custom-object.png

wc.png A Property Name:

A Property name will be by default a Text Value. Given that fact it can consist of almost any combination of characters.

However:

-We can use bracket notation in order to access the value corresponding to the Property Name of the example Custom Object in the following manner.

Setting %BooleanTrue% as true via Tools>Variables Manager and 'writing' the following sequence of actions:

workspace-example-co.png

If we test this on Process Designer, it will produce the following Variable values:

variables-example-co.png

-if we try to access the same value, using dot notation, we will get a Design error on action 4, Set Variable %Newvar2%.

design-error-ex-co.png

This means that in order to be able to access a value using dot notation, we need to be careful to avoid producing syntax errors.

It also should be noted that two different Properties of a Custom Object may have the same Value but not the same Name! (This will produce a Runtime Error informing us that Property Name exists.)

ea.png A Property Value:

Just like in JSON, property values can be of almost any kind, from a Data Table to a List.

This versatility allows you to use Custom Objects either as a medium that allows you to translate data into JSON within PR or as a custom variable type that can increase your own convenience and capabilities in WinAutomation.

For example, let us consider another example:

workspace-example2-co.png

If we test this on Process Designer, it will produce the following Variable values:

variables-example-2co.png

What is noteworthy here is the %NewCustomObject.wife[1]% dot notation syntax we used in order to access the Text Value "Amanda".

This combination of dot and bracket notation is super convenient for accessing list items within the Property Value of a Custom Object and is definitely something you should know in order to make the most of your custom object adventures.

It also should be noted that two different Properties of a Custom Object may have the same Value but not the same Name! (This will produce a Runtime Error informing us that Property Name exists.)

Convert Custom Object to Json

This action enables you to convert a Custom Object [1] to a JSON and store it into a WinAutomation variable [2] for later use:

convert-custom-object-to-json.png

wc.pngCustom Object:

This is a text-field with drop down menu options. It allows you to enter the Name of the Custom Object you want to work with, but also find it and select it effortlessly from the drop down menu that lists all available custom objects in your script.

ea2.pngInto JSON:

JSON is a text format, so it should not be a surprise that this action returns a Text Value. This text field however allows you to enter the name of the variable (new or existing) in which you want to store the JSON Text Value. Also, in case you wish to work with that Text Value, please do note that it is JSON formatted, containing line breaks:

convert-custom-object-to-json-ex-value.png

Please also note that double clicking on the convert-custom-object-to-json-ex2-value.pngValue on the Image above will produce the following pop-up (which is the Variables Visualizer Window), showing us the format of the returned value.

convert-custom-object-to-json-ex3-value.png

Hovering over the convert-custom-object-to-json-ex2-value.pngValue will produce the following pop-up that also allows you to develop a quick feeling of your variable value, without of course the capacity to edit your variable:

convert-custom-object-to-json-ex4-value.png
Convert Json to Custom Object

This action provides the ability to translate JSON [1] into a Custom Object and store it inside a new variable for later use [2]:

convert-json-to-custom-object.png

wc.pngJSON:

This action property allows you to enter either a multiple lines long JSON directly or through a WinAutomation variable.  If you have any questions on what JSON or Custom Objects are, please refer to the appropriate section of the following topic. Please also know, that you can always use the Gear Icon to enter effortlessly an existing variable.

ea2.pngInto Custom Object:

In this text-field you should enter the name of the existing or new variable that you wish to store the Custom Object.

Please note that you can access the values of your custom object almost exactly like if they were JSON. Consider for example the following actions in Process Designer's Workspace:

convert-json-to-custom-sample.png

Testing this from Process Designer will produce the following variable value for %NewVar2%:

convert-json-to-custom-ex-value.png