Skip to main content
This content has been archived and is no longer being updated. Links may not function; however, this content may be relevant to outdated versions of the product.
LinkedIn
Copied!

Using the mapping API for high-performance JSON serialization

You can use the Java mapping API to serialize a clipboard page or property object to a JSON string for high-performing and easily maintainable serialization. Using the mapping API instead of classes and properties for connecting an application to your system of record reduces latency and increases performance. You can either automatically map the entire clipboard structure to JSON or explicitly map the clipboard structure by using an EntityMap. Automapping is easier, however, automapping gives you less control over the results. You specify the type of mapping by using an EntityMap, which is a reusable template for mapping between the Pega® Platform ClipboardPage and JSON. If you do not specify a mapping type, automapping is used. When properties are mapped, they are serialized to the output JSON.

For information about deserialization, see Using the mapping API for high-performance JSON deserialization.

To serialize a clipboard object to JSON, perform the following high-level tasks:

  1. Instantiate a ClipboardDataStreamMapper object in the correct DataFormat.
  2. Instantiate a StringWriter object.
  3. Create an EntityMap.
  4. Call the method serialize(aPage, aWriter, aMap) on the ClipboardDataStreamMapper instance.

If you do the preceding steps 1 through 3, the following examples show sample code for configuring outbound conversion of clipboard objects to JSON, sample XML structure of a clipboard page, and the resulting JSON after serialization.

For additional details about the Java mapping API, refer to the Engine API help by clicking Resources > Engine API in Designer Studio.

Automatically mapping to JSON

To use automapping, create an EntityMap, but do not map any properties. The serializer populates the StringWriter with the resulting JSON, which can then be output by calling toString() on the StringWriter instance. The following example shows how to use the API with automapping.


java.io.StringWriter writer = new java.io.StringWriter();  
com.pega.pegarules.pub.clipboard.mapping.ClipboardDataStreamMapper cdsm = tools.getClipboardDataStreamMapper(com.pega.pegarules.pub.clipboard.mapping.DataFormat.JSON);  
com.pega.pegarules.pub.clipboard.mapping.EntityMap map = cdsm.getEntityMapBuilder().createEntityMap(com.pega.pegarules.pub.clipboard.mapping.MappingDirection.SERIALIZE);  
  
cdsm.serialize(myPage, writer, map); 

The following example shows the XML structure of myPage, which is a ClipboardPage:


<pagedata>
    <DecimalVal>123.456</DecimalVal>
    <TrueVal>true</TrueVal>
    <pxObjClass>@baseclass</pxObjClass>
    <CustomerName>BankCustomer</CustomerName>
    <PageVal>
        <DecimalVal>123.456</DecimalVal>
        <TrueVal>true</TrueVal>
        <pxObjClass>@baseclass</pxObjClass>
        <CustomerName>BankCustomer</CustomerName>
    </PageVal>
</pagedata>

After serialization, the resulting JSON is as follows:


{
    "DecimalVal": 123.456,
    "TrueVal": true,
    "pxObjClass": "@baseclass",
    "PageVal": {
          "DecimalVal": 123.456,
          "TrueVal": true,
          "pxObjClass": "@baseclass",
          "CustomerName": "BankCustomer"
    },
    "CustomerName": "BankCustomer"
}

Explicitly mapping to JSON

The following example shows how to use the mapping API with explicit mapping.



java.io.StringWriter writer = new java.io.StringWriter();
com.pega.pegarules.pub.clipboard.mapping.ClipboardDataStreamMapper cdsm = tools.getClipboardDataStreamMapper(com.pega.pegarules.pub.clipboard.mapping.DataFormat.JSON);
com.pega.pegarules.pub.clipboard.mapping.EntityMapBuilder entityMapBuilder = cdsm.getEntityMapBuilder();
com.pega.pegarules.pub.clipboard.mapping.EntityMap map = entityMapBuilder.createEntityMap(com.pega.pegarules.pub.clipboard.mapping.MappingDirection.SERIALIZE);
  
map.addMapping(entityMapBuilder.createClipboardEntity("DecimalVal"), entityMapBuilder.createJSONEntity("decimal"));  
map.addMapping(entityMapBuilder.createClipboardEntity("TrueVal"), entityMapBuilder.createJSONEntity("true"));  
map.addMapping(entityMapBuilder.createClipboardEntity("pxObjClass"), entityMapBuilder.createJSONEntity("class"));
  
map.addMapping(entityMapBuilder.createClipboardEntity("PageVal"), entityMapBuilder.createJSONEntity("page"));
map.addMapping(entityMapBuilder.createClipboardEntity("DecimalVal", "PageVal"), entityMapBuilder.createJSONEntity("decimal", "page"));
map.addMapping(entityMapBuilder.createClipboardEntity("TrueVal", "PageVal"), entityMapBuilder.createJSONEntity("true", "page"));
map.addMapping(entityMapBuilder.createClipboardEntity("pxObjClass", "PageVal"), entityMapBuilder.createJSONEntity("class", "page"));
map.addMapping(entityMapBuilder.createClipboardEntity("CustomerName", "PageVal"), entityMapBuilder.createJSONEntity("customer", "page"));
  
cdsm.serialize(myPage, writer, map); 

The following example shows the XML structure of myPage, which is a ClipboardPage:


<pagedata>
    <DecimalVal>123.456</DecimalVal>
    <TrueVal>true</TrueVal>
    <pxObjClass>@baseclass</pxObjClass>
    <CustomerName>BankCustomer</CustomerName>
    <PageVal>
        <DecimalVal>123.456</DecimalVal>
        <TrueVal>true</TrueVal>
        <pxObjClass>@baseclass</pxObjClass>
        <CustomerName>BankCustomer</CustomerName>
    </PageVal>
</pagedata>

After serialization, the resulting JSON is as follows:


{
    "decimal": 123.456,
    "true": true,
    "class": "@baseclass",
    "page": {
          "decimal": 123.456,
          "true": true,
          "class": "@baseclass",
          "customer": "BankCustomer"
  }
}

The CustomerName property is not included at the top level because the EntityMap intentionally does not have an entry for the top-level CustomerName, while it does have a mapping for CustomerName under PageVal.

Multidimensional array output

By default, a ClipboardProperty of mode PageList is serialized to an array of objects in JSON. You can include multidimensional arrays in the output by passing true to map.createMultidemensional.Arrays().

The clipboard structure must have a specific format. It must have a PageList property whose page elements have only system-generated properties and a PageList of the same name as the parent PageList.

The following example Java code shows how to implement multidimensional array output:


java.io.StringWriter writer = new java.io.StringWriter();  
com.pega.pegarules.pub.clipboard.mapping.ClipboardDataStreamMapper cdsm = tools.getClipboardDataStreamMapper(com.pega.pegarules.pub.clipboard.mapping.DataFormat.JSON);  
com.pega.pegarules.pub.clipboard.mapping.EntityMapBuilder entityMapBuilder = cdsm.getEntityMapBuilder();  
com.pega.pegarules.pub.clipboard.mapping.EntityMap map = entityMapBuilder.createEntityMap(com.pega.pegarules.pub.clipboard.mapping.MappingDirection.SERIALIZE);  
  
map.createMultidimensionalArrays(true);  
  
cdsm.serialize(myPage, writer, map); 

The following example shows the XML structure of myPage, which is a ClipboardPage:


<pagedata>
    <pxObjClass>@baseclass</pxObjClass>
    <pzStatus>valid</pzStatus>
    <test860216> REPEATINGTYPE="PageList">
       <rowdata REPEATINGINDEX=1">>
            <pxObjClass>ata-</pxObjClass>
                <test860216 REPEATINGTYPE="PageList">
                <rowdata REPEATINGINDEX="1">
                    <pyValue>0</pyValue>
                    <pxObjClass>SingleValue-Integer</pxObjClass>
                </rowdata>
                <rowdata REPEATINGINDEX="2">
                    <pyValue>1</pyValue>
                    <pxObjClass>SingleValue-Integer></pxObjClass>
                </rowdata>
                <rowdata REPEATINGINDEX="3">
                    <pyValue>2</pyValue>
                    <pxObjClass>SingleValue-Integer</pxObjClass>
                </rowdata>
                <rowdata REPEATINGINDEX="4">
                    <pyValue></pyValue>
                    <pxObjClass>SingleValue-Integer</pxObjClass>
                </rowdata><rowdata REPEATINGINDEX="5">
                    <pyValue>4</pyValue>
                    <pxObjClass>SingleValue-Integer</pxObjClass>
                </rowdata>
        </rowdata>
        .  
        . (Repetition omitted to save space)  
        .  
        <rowdata REPEATINGINDEX="5">
            <pxObjClass>Data-</pxObjClass>
            <test860216 REPEATINGTYPE="PageList">
                <rowdata REPEATINGINDEX="1">
                    <pyValue>4</pyValue>
                    <pxObjClass>SingleValue-Integer</pxObjClass>
                </rowdata>
                <rowdata REPEATINGINDEX="2">
                    <pyValue>5</pyValue>
                    <pxObjClass>ingleValue-Integer</pxObjClass>
                </rowdata>
                <rowdata REPEATINGINDEX="3">
                    <pyValue>6</pyValue>
                    <pxObjClass>SingleValue-Integer</pxObjClass>
                </rowdata>
                <rowdata REPEATINGINDEX="4">
                    <pyValue>7</pyValue>
                    <pxObjClass>SingleValue-Integer</pxObjClass>
                </rowdata>
                <rowdata REPEATINGINDEX="5">
                    <pyValue>8</pyValue>
                    <pxObjClass>SingleValue-Integer</pxObjClass>
                </rowdata>
            </test860216>
        </rowdata>
    </test860216>
</pagedata>

After serialization, the resulting JSON is as follows:


{
    "test860216": [
          [0, 1, 2, 3, 4],
          [1, 2, 3, 4, 5],
          [2, 3, 4, 5, 6],
          [3, 4, 5, 6, 7],
          [4, 5, 6, 7, 8]
    ],
    "pxObjClass": "@baseclass"
}

Compare the above results with the following results that occur when the serializer is not set to create multidimensional arrays:


{
    "test860216": [{
          "test860216": [0, 1, 2, 3, 4],
          "pxObjClass": "Data-"
    }, {
          "test860216": [1, 2, 3, 4, 5],
          "pxObjClass": "Data-"
    }, {
          "test860216": [2, 3, 4, 5, 6],
          "pxObjClass": "Data-"
    }, {
          "test860216": [3, 4, 5, 6, 7],
          "pxObjClass": "Data-"
    }, {
          "test860216": [4, 5, 6, 7, 8],
          "pxObjClass": "Data-"
    }],
    "pxObjClass": "@baseclass"
}

ClipboardPage structure and output

A ClipboardPage property is serialized to a JSON object with its properties rendered as JSON fields in all scenarios except the following two use cases. They are exceptions that will not occur for most scenarios.

Single-value page

When the page is of class SingleValue- (SingelValue-Text, SingleValue-Integer, and so on) it is always converted to the value of the ClipboardPage's pyValue property. The following example shows the XML structure of myPage, which is a ClipboardPage:


	<pagedata>
	    <pxObjClass>@baseclass</pxObjClass>
	    <page1>
	          <pxObjClass>SingleValue-Integer</pxObjClass>
	          <pyValue>1</pyValue>
	    </page1>
	    <page2>
	          <pxObjClass>SingleValue-Text</pxObjClass>
	          <pyValue>some value</pyValue>
	    </page2>
	</pagedata>

After serialization, the resulting JSON is as follows:



{
    "pxObjClass": "@baseclass",
    "page1": 1,
    "page2": "some value"
}

PageList element

When the ClipboardPage is an element in a PageList, and the only non-system property on the page is a PageList property of the same name as the outer PageList, and multidimensional arrays have been enabled, the ClipboardPage is collapsed into another dimension of the output array. The system properties are pxObjClass and pxSubscript.

For an example, see Multidimensional array output.

ClipboardProperty modes and output

The way a ClipboardProperty is serialized depends on the ClipboardProperty mode. The following outputs are possible for any ClipboardProperty.

The following ClipboardProperty modes are not supported:

  • Page group
  • String group
  • Java property list
  • Java object list
  • Java object group
  • Java property
  • Java object
  • Unknown list
  • Unknown group

Did you find this content helpful?

100% found this useful

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.

Ready to crush complexity?

Experience the benefits of Pega Community when you log in.

We'd prefer it if you saw us at our best.

Pega Community has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice
Contact us