I know, the title is a bit of a stretch (Jason and the Argonauts is a movie title/Greek myth for those who are really confused) but hopefully the quality of the article will make up for it!

In this article, I want to explore a misunderstanding that many people have around JSON as well as give an explanation on how to utilize powerful capabilities in SFMC SSJS. I have had so many people mention that an article around this topic would be super helpful as there is no clear documentation on JSON in relation to SFMC and this causes confusion for many people. My goal here is to hopefully help clear things up and help you all better arm yourself for your future development and solutioning needs.

To start this off, I am actually going to be taking a few paragraphs from my book, Automating Salesforce Marketing Cloud, to explain what JSON, an array, and an object are. I will then add in some examples and commentary on how to extract values from each of these data objects. So first, lets dig into ‘Who this JSON fella is?’

I am gonna apologize up front on all the mentions of my book, but since I took a chunk of this content from it, I need to promote it or my publisher is going to stab me…and I like being non-stabbed so…..yeah.

Who is JSON?

JSON (pronounced JAY-SON) is a representation of the data structure; it is not an actual array or object itself. And no, JSON is not a hero from Greek myth riding upon the Argo and having many adventures with the likes of Hercules and more. That is Jason.

So, a JSON array is not a special type of array—it is just describing how the array is structured. A great example of this would be the different types of milk—for instance, default JavaScript could be cow milk and then JSON would be almond milk. In most ways, it is used in the same way, but they are built/made completely differently.

The other difference is that JSON is universal outside of JavaScript, so it can be used, transmitted, generated, and read from multiple programming environments. JSON is also stored as a string that is then deserialized (converted to a native object) when parsed. Because of this, JSON can actually be stored as its own file, which is just a text file with the extension of .json. So, for now, let’s take JSON out of the picture and concentrate on finding out exactly what an array is.

Arrays of Our Lives?

An array is basically a list-like object that contains data inside indexed locations, starting at the 0 index and going up from there. Due to this indexing nature, you cannot store string descriptors for each index; it is only the numeric index that can be used. An example of an array would be something such as:

var fruit = ["Apples","Oranges","Bananas"]

This example shows the three types of fruit inside of the open and close square brackets being each indexed value.

Arrays are very much list-based. Think of an array as you would think about a delimited list or an Excel spreadsheet. This is used if you want to have multiple values stored in
a single place. It usually works well when you are looking to do something such as execute the same action on multiple different values or want to have multiple outputs slightly altered.

Going off the example above, we would utilize the numbered index to output the values using bracket notation.

fruit[0] = "Apples"
fruit[1] = "Oranges"
fruit[2] = "Bananas"

As stated above, the index starts at 0, not at 1 – meaning that the first value is [0] not [1]. Keep this in mind as if you do length() and get a length of 2, you will use [0] and [1] and not [2] as its length - 1 to get index.

Pretty simple, right? Well, in theory yes. But this is the most simplistic example, it can get pretty crazy the more complex you make your data storage inside the Array. Please feel free to take a look at my previous article on Javascript Array Methods in SFMC? for some great native and polyfill capabilities of arrays as well as check out my book, Automating Salesforce Marketing Cloud, for some more indepth explanations and examples.

Now that we have a good understanding of when to use an array, let’s move on to the JavaScript object.

Object…ion!?

Objects are basically a combination of the capabilities of arrays and variables. That being said, objects themselves are variables as they must be declared as such, but inside that variable, your object can contain many different values and descriptions assigned to that one variable.

For instance, your variable without an object would equal a single value, like this:

var fruit = 'Apple'

If you were to store the variable as an object, you could instead store multiple values inside of it, like this:

Var fruit = {name: "Apple", type: "Golden Delicious", quantity: 500}

As you see in the preceding code, objects use the curly bracket syntax, as opposed to the square bracket syntax of the array. Inside of these curly brackets, each property is stored as a name:value pair (name and value separated by a colon), and each property is separated by a comma.

Then, in order to access the object property, you would use dot notation to iterate through it. To use the previous example, let’s try to get the type of apple it is. We would first need to list the object name, and then the dot notation, and then the property name, which would be:

fruit.type

which would then output:

Golden Delicious

You can also use square brackets (bracket notation), similar to arrays, to access the object property. Something like this:

fruit["type"]

which would then output:

Golden Delicious

This is useful knowledge in case you have a dynamic key that you want to use. This would not be possible in dot notation, but can be done in bracket notation. For example:

var key = "type"
fruit[key]

which would then output:

Golden Delicious

The other great thing that objects have is something called object methods. Methods are actions that can be performed on objects. They are stored inside properties as function definitions.

I am hoping in the near future to get up some more details around this (maybe a future article) – but for now, you can find these methods easily in Javascript documentation. Just remember to look and ensure it was possible in ECMA 3 or it is not likely possible in SSJS. Also, in case you missed it above, I also have a book with more info in it as well. (Sorry for yet ANOTHER mention of it…)

Objects are a storage place for you to give properties of a single entity. For instance, instead of just saying a car, as you would inside of a normal global variable, an object would say it’s a gray 1998 Ford Fusion with 139,990 miles on the clock and that it had its most recent oil change on September 21, 20XX. The object is basically a contextual blob that subsets off from a single identifier.

This is really useful to create a single point of reference rather than have to set individual variables that then need to be passed and used individually each time.

Argonauts? More like Array-Objects…Am I Right?

No. No, I am not right. That is a terrible attempt and I should be punished for that. No more cookies for a week for me. Damn…

Arrays and objects are each amazing in their own right and offer so much capability and power, but that doesn’t compare to when they work together and you combine them into a single array or object. Nesting arrays in objects or objects in arrays can create unbelievable datasets, creating what is essentially data objects inside of data objects.

Do you have a list of specific subscribers that you want to send to, but need to have all of their details included? Well—you, need an array of objects!

Do you have a specific entity that you need to have multiple values listed inside of a property? You need an object with an array.

A combination of the two makes so much more possible and increases capability, power, and usability tremendously. Lets see a sample of each and how to utilize it to get values out.

Array of objects:

var arr = [
  {
    id: 1234,
    email: "[email protected]",
    name: "John Doe"
  },
  {
    id: 2345,
    email: "[email protected]",
    name: "Jane Doe"
  },
  {
    id: 3456,
    email: "[email protected]",
    name: "Malcolm Doe"
  }
]

As you can see above, an array of objects is literally an array but in each index is an object instead of a string or number or othe singular value. Now the question comes, how do I get this information out?

Its relatively simple, you just combine the dot and bracket notations accordingly and you can get what you need.

For example:

arr[0].id    //outputs 1234
arr[1].name  //outputs Jane Doe
arr[2].email //outputs [email protected]

Using the bracket index notation of array to select the object and then using dot notation with key name for object will get you the specific information you need from your data. Now on to an object with an array!

Object with an array:

var obj = {
  id: 1234,
  name: "John Doe",
  email: "[email protected]",
  relatives: [
    "Jane Doe",
    "Malcolm Doe",
    "Mindy Jo Doe"
  ]
}

This is essentially the opposite of what we say with an array of objects. We now have a key/value pair where the value is actually an array instead of a single value. So how do we extract from here and get what we need?

For example:

obj.relatives[0]   //outputs Jane Doe
obj.id             //outputs 1234
obj.relatives[2]   //outputs Mindy Jo Doe

Again, this is just a combination of bracket and dot notation in the right places to navigate through the object and array to get the specific values.

In Conclusion

This is literally the tip of an amazing iceberg on JSON, Arrays and Objects in SSJS and SFMC. There is a ton that can be done with this knowledge, furthing your capabilities and elegance of solutions and development. My recommendation is to go out and play around with these and then explore places like Salesforce Stack Exchange or similar sites to get some use cases to play with and some indepth development answers. From there, I would use something like (last time I promise) my book, Automating Salesforce Marketing Cloud, to further your knowledge and understanding and begin the next step forward in your journey.

As always let me know if you find something I missed, something inaccurate or even just to say hi!