What are maps?
In simple terms, Data Mapper visually represents XSLT 3.0 (Extensible Stylesheet Language Transformation) documents. They allow you to perform clear and intuitive transformations between XML and JSON messages. In the future, the Data Mapper will support additional formats.
However, Data Mapper maps are not just a single artifact. Instead, they consist of two distinct files. First, a Map Definition file (.yml) defines the map’s abstract structure. Second, an XSLT file (.xslt) contains all transformation rules. At runtime, the Logic Apps Standard engine executes this XSLT file to perform the transformation.
📝 One-Minute Brief
Understanding how maps work is essential when building transformations in Logic Apps Standard. This article explains the basic principles of Data Mapper maps, how they rely on XSLT, and the types of transformations you can apply between XML and JSON messages.
What types of transformation can we apply in Logic Apps?
Similar to BizTalk Server, we can define two types of transformations:
- Syntax Transformations: focus on changing how a document is represented. In BizTalk Server, these transformations occur in receive or send pipelines. For example, they convert CSV to XML. Likewise, in Logic Apps, syntax transformations run inside workflows by using an Integration Account or specific actions and expressions.
- In this case, the document keeps the same data semantics but changes its syntax. In other words, we translate the document without modifying its structure. As a result, these transformations are usually bidirectional. Because the semantic content remains intact, we can apply the same logic to restore the original format.
- Semantic Transformations: focus on changing the data itself. In BizTalk Server, these transformations occur inside maps. Similarly, in Logic Apps (Standard), they take place in the Data Mapper.
- Here, the document may keep the same syntax, such as XML or JSON, although this is not mandatory. However, the transformation changes the document’s semantics. Therefore, these transformations are typically one‑way. Since we aggregate or enrich data during the process, we may lose details required to fully reconstruct the original document.
Introduction to the Data Mapper
The Data Mapper enables us to perform transformations on complex messages visually and effortlessly, with links that graphically represent the relationships between the elements of messages.
These relationships between elements are implemented internally as XSL Transformations (XSLT – Extensible Stylesheet Language Transformation), the standard World Wide Web Consortium (W3C) recommendation to message transformations.
Data Mapper is a Visual Code extension that allows you to perform mapping transformations. Currently, it has its own extension, but that will be merged with the main extension in the future.
Essentially, the editor consists of three main modules:
- Source Schema view: this is the data structure of the source message and is on the left side of the main window;
- Destination Schema view: this is the data structure of the target message and is on the right side of the main window; the links that define the mapping lead into the destination schema tree view from the grid view, and ultimately from the source schema tree view.
- Mapping area view: is in the middle of the main window, between the two data structures (source and target); This area plays a critical role in the definition of maps, containing the links and Functions that control how data in a source instance message is transformed into an instance message that conforms to the destination schema. The mapping area can have multiple layers, each of them associated with a specific record on the destination schema, allowing us this way to organize complex maps in a better way.
Apart from these three modules, there are other important windows for the developer:
- Function panel: At the left side of the source schema, providing access to all Functions we can use in the Data Mapper.
- Function properties panel: in this panel, we can see and modify the properties of a selected function inside the Data Mapper.
- Task List and Output windows: much of the time hidden, we can and must use these windows to examine the results of saving and testing we do in our maps. These windows normally appear underneath the Mapping area or the Function properties panel.
- Code view Panel: On this panel, you can view Map definition rules (abstraction of the underlying implementation). It is a read-only panel.
Basic map functionalities (Document mapping)
There are several mapping functionalities that you can perform inside maps, like Data normalization, Transform Injection (XSLT injection), calculating values covering math and scientific functoids, and so on. Still, most of the time, transformations are quite simple, and when we perform a transformation in the message, 5 basic functionalities typically arise:
- Simple mapping of a given value (direct copy)
- Concatenation of values
- Conditional selection
- Custom scripts
- Add new values (data)
Here, we will take a simple transformation problem that will address each one of these functionalities or operations, providing a simple example of how to accomplish this inside the Data Mapper. Of course, there are plenty of other operations or transformation rules that we could do that will not be addressed here.
Hope you find this helpful! So, if you liked the content or found it useful and want to help me write more content, you can buy (or help buy) my son a Star Wars Lego!
