ATL objects

ATL objects are similar to JSON objects, but unlike the values in JSON objects, the values in ATL objects can be of any data type. This makes JSON objects a subtype of ATL objects.

An ATL object — when defined in a script or variable definition — looks like this:

A JSON object — which you can't define directly in a script or variable definition — looks like this:

The key differences are summarized in this table:

You can define ATL objects ad hoc within ATL by placing round brackets around a list of key–value pairs.

Alternatively, you can use the createAtlObject function.

[[

keys = makeList('product','sales')

values = makeList('Retine', 12547.39)

createAtlObject(keys, values)

]]

You can retrieve the value of a key–value pair using dot notation.

[[

myObject = (products = ('Retine','Glower','Ointmo'), sales = 385429.47) 

myObject.products

]]

You can also retrieve values using bracket notation.

[[

myObject = (products = ('Retine','Glower','Ointmo'), sales = 385429.47)

myObject['products'][0]

]]

To get a list of all values from an ATL object, use the values function.

[[

myObject = (product = 'Retine', sales = 12547.39) 

values(myObject)

]]

You can add key–value pairs to an ATL object by using the addToAtlObject function.

[[

myObject = (product = 'Retine', sales = 12547.39)

newKeys = makeList('target', 'profit')

newValues = makeList(10000, 3792.15)

addToAtlObject(myObject, newKeys, newValues)

]]

The first line defines an ATL object and assigns it the name myObject. This object contains two key–value pairs. The final line uses the addToAtlObject function to add new keys and values. The resulting object is:

You can also add key–value pairs by using dot or bracket notation.

[[

myObject = (product = 'Retine', sales = 12547.39)

myObject.target = 10000

myObject.profit = 3792.15

myObject

]]

[[

myObject = (product = 'Retine', sales = 12547.39)

myObject['target'] = 10000

myObject['profit'] = 3792.15

myObject

]]

You can remove key–value pairs from an ATL object by using the removeFromAtlObject function.

[[

myObject = (product = 'Retine', sales = 12547.39, target = 10000, diff = 2547.39)

removeFromAtlObject(myObject, ('target', 'diff'))

]]

The first line defines an ATL object and assigns it the name myObject. The object contains four key–value pairs. The second line uses the removeFromAtlObject function to remove the last two key–value pairs.

The resulting ATL object is:

Key names may contain spaces — e.g. 'sales target'— but restrictions apply.

For example, you can't use key names with spaces when defining ATL objects ad hoc within ATL.

To include a key name with spaces, use the createAtlObject function.

[[

keys = makeList('product', 'sales target')

values = makeList('Retine', 10000)

createAtlObject(keys, values)

]]

Or add the key to the object after its creation using bracket notation.

[[

myObject = (product = 'Retine')

myObject['sales target'] = 10000 

myObject

]]

If a key name contains spaces, you can't access the value for that key using dot notation.

[[

myObject = (product = 'Retine')

myObject['sales target'] = 10000 

myObject.sales target

]]

Use bracket notation instead.

[[

myObject = (product = 'Retine')

myObject['sales target'] = 10000 

myObject['sales target']

]]

To retrieve a list of all key names from an ATL object, use the keys function.

[[

myObject = (product = 'Retine', sales = 12547.39)

keys(myObject)

]]

To test if an object contains a specific key name, use the hasKey function.

[[

myObject = (product = 'Retine', sales = 12547.39)

hasKey(myObject, 'target')

]]

Another use for ATL objects is reorganizing your data. For example, assume a JSON project with this data:

{"yr2021": {
	"Revenue": [
	    {
                "name": "Premium income",
                "value": 22166
            },
	    {
                "name": "Net investment income",
                "value": 6334
            },
	    {
                 "name": "Fees and other income",
                 "value": 1283
            }
	],
	"Expenses": [
	    {
                "name": "Policyholders' benefits",
                "value": 19046
            },
	    {
                "name": "General insurance expenses",
                "value": 2251
            },
            {
                "name": "Commissions",
                "value": 869
            },
	    {
                "name": "State taxes, licenses and fees",
                "value": 237
            },
	    {
                "name": "Dividends to policyholders",
                "value": 1566
            }
	]
    }
}

Let's say that, instead of the nested structure shown above, you want a flatter list of all transactions for the year with only their type and value. You could get this with the following ATL:

[[

rev2021 = map(WholeJSON.yr2021.Revenue, x -> createAtlObject(('type', 'value'), makeList('revenue', x.value)))

exp2021 = map(WholeJSON.yr2021.Expenses, x -> createAtlObject(('type', 'value'), makeList('expense', x.value)))

concat(rev2021,exp2021)

]]

The first line produces this list of ATL objects from the Revenue array:

The second line produces this list of ATL objects from the Expenses array:

The third line concatenates the lists.

The printed output is:

Assume a "Describe the Table" project with this data:

This example builds a list of ATL objects from three table columns:

[[map(rowNames(), x -> createAtlObject(('branch', 'manager', 'profit'), (x, value(cell(x,Manager)), value(cell(x,Profit)))))]]

The resulting is the following list of ATL objects (one for each row):

The printed output is:

In a "Describe Row in Context" project, the ATL would be:

[[map(rowNames(), x -> createAtlObject(('branch', 'manager', 'profit'), (x, value(cell(x,ManagerColumn)), value(cell(x,ProfitColumn)))))]]

You can't do this in a "Describe Each Row" project because that project type does not allow access to column data across multiple rows. In that project type, you can access the data in the focus row only.