Overview

When working with Business Automation Workflow (BAW) applications, developers often need to bridge the gap between TWObjects (Teamworks Objects) and JSON formats. Sounds straightforward, right? Well, not quite. A significant hurdle in this process is handling the Map data type within TWObjects, especially when the parent object is a Map or contains nested Map objects.

To tackle this challenge and simplify the conversion process, BAWJSONUtils was developed—a server side JavaScript utility library designed to make TWObject and JSON conversion effortless, with special attention to the Map data type.

BAWJSONUtils is a JavaScript utility that provides two primary functions:

1. TWToJSON(twObject): Converts a TWObject into a JSON string, handling complex data types like Maps, Dates, Lists, and nested objects.
2. JSONToTW(jsonString, mappingVariableName): Converts a JSON string into a TWObject, accurately reconstructing Map objects and other complex types.

The utility overcomes the limitations of JSON.stringify() when dealing with Map data types in TWObjects. It ensures data integrity is maintained during the conversion process.

Motivation

Working with BAW applications means dealing with TWObjects, which often include the Map data type. This data type is crucial as it represents complex data structures. However, standard JSON serialization methods like JSON.stringify() hit a wall when faced with TWObject Maps.

Here's the problem:

• Serialization Issues: JSON.stringify() can't properly serialize TWObject Maps. The result? Incomplete or incorrect JSON output.
• Deserialization Challenges: Even if the Map object is manually converted into a normal JSON object, parsing it back into a TWObject Map doesn't work as expected. Type information and structure are lost.
• Nested Map Complexity: When TWObjects contain nested Map objects, the issues multiply, making serialization and deserialization even more complex.

So, what's the solution? BAWJSONUtils handles the Map data type differently by preserving it as an XML element during serialization and deserialization. This approach ensures that Map objects are accurately represented and reconstructed, keeping data intact.

Key Features

• Special Handling of Map Data Type: Preserves Map objects as XML elements during conversion, ensuring accurate serialization and deserialization.
• Comprehensive Data Type Support: Handles various data types, including primitives (String, Number, Boolean), complex types (Date, List), and nested structures.
• Robust Type Detection: Utilizes reliable methods for type checking, ensuring accurate conversions.
• Global Accessibility: Attaches BAWJSONUtils to the global object, making it easily accessible throughout the application once the toolkit is associated with the application.

Implementation Details

The utility is encapsulated within an Immediately Invoked Function Expression (IIFE) to prevent global namespace pollution. It checks if BAWJSONUtils exists on the global object and creates it if not, ensuring that it doesn't overwrite any existing utilities.

Handling the Map Data Type

The core idea behind BAWJSONUtils is to provide proper handling of the Map data type in TWObjects, which standard JSON serialization methods cannot handle.

• Serialization of Maps: When converting a TWObject to JSON, if a Map object is encountered, the utility serializes it into an XML string using tw.system.serializer.toXml(). This preserves the structure and data of the Map object in a format that can be accurately reconstructed later.
• Deserialization of Maps: When converting JSON back to a TWObject, the utility detects XML strings representing Map objects and deserializes them back into tw.object.Map instances using tw.system.serializer.fromXml(). This ensures that the Map objects are fully restored with their original structure and data.

Usage Examples

Once the toolkit is associated with the application - 

Converting a TWObject to JSON string -

var jsonString = BAWJSONUtils.TWToJSON(tw.local.myVar);

Converting a JSON string to TWObject-

BAWJSONUtils.TWToJSON(jsonString, "tw.local.myVar");

Toolkit Download

BAWJSONUtils Toolkit Download

Conclusion

The idea behind BAWJSONUtils is simple yet powerful: handle the Map data type effectively within TWObjects during conversion processes. Standard JSON methods can't do this, but this utility can. By handling Map objects differently and preserving them as XML elements, BAWJSONUtils overcomes these limitations.