createAtlObject

Creates an ATL object from the given keys and values.

To create an empty ATL object, leave the optional parameters unspecified.

For more about ATL objects, see ATL Guide > ATL objects.

Parameters

KEYS (string or list)
Optional. One or more key names. Key names must be strings, and each must be unique.
For multiple key names, input a list. Keys are paired with values by position in the list.
VALUES (any or list)
Optional. One or more values. The values can be any type: number, string, list, ATL object, etc.
For multiple values, input a list. Values are paired with keys by position in the list.

Examples

To create an empty ATL object, leave the parameters unspecified.

ATL in Script	Created ATL Object	Printed Result
`[[createAtlObject()]]`	`( )`	( )

Tip

There are several ways to add key–value pairs to an empty ATL object (or populated object). See ATL Objects > Adding key–value pairs for guidance.

The function pairs keys (first parameter) with values (second parameter) by position in the list.

[[

keys = makeList('Branch', 'Manager', 'Sales', 'Profit')

values = makeList('Boston', 'Chris Logan', 1351152.58, 75150.78)

createAtlObject(keys, values)

]]

The created ATL object is:

( Branch = Boston, Manager = Chris Logan, Sales = 1351152.58, Profit = 75150.78 )

The function excludes a key when there is no corresponding value, and the same is true in reverse.

[[

keys = makeList('Branch', 'Manager', 'Sales', 'Profit', 'Units')

values = makeList('Boston', 'Chris Logan', 1351152.58, 75150.78)

createAtlObject(keys, values)

]]

There are five values in keys and only four in values, so the resulting object has just four key–value pairs.

( Branch = Boston, Manager = Chris Logan, Sales = 1351152.58, Profit = 75150.78 )

Tip

You can extract key names from an ATL object by using the keys function.

There are several ways to extract values. You can use the values function or extract values using dot or array notation. See ATL objects > Retrieving values from an ATL object.

Creating a list of ATL objects (table data)

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

	Branch	State	Manager	Profit	ProfitTarget
Row 1	Chicago	Illinois	Andrew Gray	22495.22	24000
Row 2	Dallas	Texas	Emma Moore	32841.38	30000
Row 3	Los Angeles	California	Linda Barclay	19239.66	24000

You can generate a list of ATL objects by combining map, rowNames, and createAtlObject. For example:

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

The result is a list of ATL objects (one for each row):

( (branch = Chicago, profit = 22495.22, target = 24000), (branch = Dallas, profit = 32841.38, target = 30000), (branch = Los Angeles, profit = 19239.66, target = 24000) )

Here's how you might use the result to produce narrative text:

[[

data = map(rowNames(), x -> createAtlObject(('branch','profit','target'), (x, value(cell(x,Profit)), value(cell(x,ProfitTarget)))))

sortedByPerformance = sort(data, (x,y) -> sign(percentageChange(y.profit,y.target) - percentageChange(x.profit,x.target)))

topPerformerName = map(sortedByPerformance[0:1], x -> x.branch)

topPerformerVal = map(sortedByPerformance[0:1], x -> abs(percentageChange(x.profit,x.target)))

direction = topPerformerVal > 0 ? 'exceeding' : 'despite missing'

"The top-performing branch for Profit was [[topPerformerName]], [[direction]] its target by [[topPerformerVal]]%."

]]

The printed result is:

The top-performing branch for Profit was Dallas, exceeding its target by 9.47%.

Creating a list of ATL objects (JSON data)

Assume a "Describe a JSON Object" project with this data:

{
    "Finances": {
        "Q1": [
            {"product": "Retine", "sales": 2493146.89, "target": 2000000},
            {"product": "Ointmo", "sales": 3486198.56, "target": 3500000},
            {"product": "Glower", "sales": 1756934.95, "target": 1750000}
        ]
    }
}

The "Q1" array contains three JSON objects. Each object contains three key–value pairs.

You can create a list of ATL objects by combining map and createAtlObject. For example:

[[map(WholeJSON.Finances.Q1, x -> createAtlObject(('product','performance'), (x.product, diff(x.sales,x.target))))]]

The result is this list of ATL objects:

( (product = Retine, performance = 493146.89), (product = Ointmo, performance = -13801.44), (product = Glower, performance = 6934.95) )