You can use the Java mapping API to deserialize JSON to a clipboard page or property object for high-performance and easily maintainable deserialization. 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 JSON to the clipboard or explicitly map parts of the JSON to the clipboard by using an EntityMap. Automapping is easier, but 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.

For details about serialization, see Using the mapping API for high-performance JSON serialization.

To deserialize JSON to the clipboard, perform the following high-level tasks:

1. Instantiate a ClipboardDataStreamMapper object in the correct DataFormat.
2. Instantiate a Reader object with JSON.
3. Get a handle to a clipboard object (Property or Page).
4. Create an EntityMap.
5. Call the method deserialize(aClipboardObject, aReader, aMap) on the ClipboardDataStreamMapper instance.

The deserializer populates the clipboard object based on the JSON structure. All properties must be created before the result of deserialization is saved. If any of the property names on the ClipboardPage do not reference valid properties, the page is not saved.

The following examples show inbound conversion of JSON to clipboard objects and assume that you have performed steps 1 through 3.

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

Automatically mapping to the clipboard

To use automapping, create an EntityMap, but do not map any properties. The following example shows how to use the API with automapping.

java.io.StringReader reader = new java.io.StringReader(myJSONString);  
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.DESERIALIZE);  
  
cdsm.deserialize(myPage, reader, map); 

The following example shows myJSONString with the following contents:

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

After deserialization, myPage has the following XML structure:

<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>

Explicitly mapping to the clipboard

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

java.io.StringReader reader = new java.io.StringReader(myJSONString);  
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 aMap = entityMapBuilder.createEntityMap(com.pega.pegarules.pub.clipboard.mapping.MappingDirection.DESERIALIZE);  
  
  
aMap.addMapping(entityMapBuilder.createClipboardEntity("pyDecimal"), entityMapBuilder.createJSONEntity("DecimalVal"));  
aMap.addMapping(entityMapBuilder.createClipboardEntity("pyTrueFalse"), entityMapBuilder.createJSONEntity("TrueVal"));  
aMap.addMapping(entityMapBuilder.createClipboardEntity("pyCustomerName"), entityMapBuilder.createJSONEntity("CustomerName"));  
aMap.addMapping(entityMapBuilder.createClipboardEntity("pyPageVal"), entityMapBuilder.createJSONEntity("PageVal"));  
  
aMap.addMapping(entityMapBuilder.createClipboardEntity("pyDecimal", "pyPageVal"), entityMapBuilder.createJSONEntity("DecimalVal", "PageVal"));  
aMap.addMapping(entityMapBuilder.createClipboardEntity("pyTrueFalse", "pyPageVal"), entityMapBuilder.createJSONEntity("TrueVal", "PageVal"));  
aMap.addMapping(entityMapBuilder.createClipboardEntity("pyCustomerName", "pyPageVal"), entityMapBuilder.createJSONEntity("CustomerName", "PageVal"));  
  
cdsm.deserialize(myPage, reader, aMap); 

The following example shows myJSONString with the following contents:

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

After deserialization, myPage has the following XML structure:

<pagedata>
    <pyDecimal>123.456</pyDecimal>
    <pyTrueFalse>true</pyTrueFalse>
    <pyCustomerName>BankCustomer</pyCustomerName>
    <pyPageVal>
          <pyDecimalValue>123.456</pyDecimalVal>
          <pyTrueFalse>true</pyTrueFalse>
          <pyCustomerName>BankCustomer</pyCustomerName>
    </pyPageVal>
</pagedata>

Excluding pxObjClass from the map excludes it from the final result.

Multidimensional array input

The clipboard structure cannot handle the JSON multidimensional array structure. Everything in the clipboard requires a name, however, JSON can have unnamed elements inside an array. To handle this situation, the deserializer creates PageList properties named after the original property at every required level.

Consider the following JSON:

{
     "coordinates": [
          [-0.259465, 51.417277],
          [-0.127974, 51.417277]
     ]
}

The resulting ClipboardPage XML has the following structure:

<pagedata> 
    <pzStatus>valid</pzStatus>
    <coordinates REPEATINGTYPE="PageList">
        <rowdata="1">
            <coordinatesREPEATINGTYPE="PageList">
                <rowdataREPEATINGINDEX="1">
                    <pyValue>-0.259465</pyValue>
                    <pxObjClass>SingleValue-Decimal</pxObjClass>
                </rowdata>
                <rowdataREPEATINGINDEX="2">
                    <pyValue>51.417277</pyValue>
                    <pxObjClass>SingleValue-Decimal</pxObjClass>
                </rowdata>
            </coordinates>
         </rowdata>
         <rowdataREPEATINGINDEX="2">
             <coordinatesREPEATINGTYPE="PageList">
                 <rowdataREPEATINGINDEX="1">
                     <pyValue>-0.127974</pyValue>
                     <pxObjClass>SingleValue-Decimal</pxObjClass>
                 </rowdata>
                 <rowdataREPEATINGINDEX="2">
                     <pyValue>51.417277</pyValue>
                     <pxObjClass>SingleValue-Decimal</pxObjClass>
                 </rowdata>
            </coordinates>
        </rowdata>
    </coordinates>
</pagedata>

Consider the following JSON:

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

The resulting ClipboardPage XML has the following structure:

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

The same clipboard structure would also result from the following JSON:

{
    "coordinates": [
          [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"
}

JSON value types and their outputs

JSON value types and how they are output are shown in the following list.

• Object – Converted to a ClipboardPage. All properties under the page are handled individually.
• Array – Converted to a PageList property, with each element handled individually.
• String
  • Set to the ClipboardProperty value as a String
  • Inside of an array, converted to a ClipboardPage of class SingleValue-Text
• Number
  • integer
    • Set to the ClipboardProperty value as an Integer
    • Inside of an array, converted to a ClipboardPage of class SingleValue-Integer
  • long
    • Set to the ClipboardProperty value as a com.pega.ibm.icu.math.BigDecimal.BigDecimal
    • Inside of an array, converted to a ClipboardPage of class SingleValue-Integer
  • big integer
    • Set to the ClipboardProperty value as a com.pega.ibm.icu.math.BigDecimal.BigDecimal
    • Inside of an array, converted to a ClipboardPage of class SingleValue-Integer
  • big decimal
    • Set to the ClipboardProperty value as a com.pega.ibm.icu.math.BigDecimal.BigDecimal
    • Inside of an array, converted to a ClipboardPage of class SingleValue-Decimal
  • double
    • Set to the ClipboardProperty value as a com.pega.ibm.icu.math.BigDecimal.BigDecimal
    • Inside of an array, converted to a ClipboardPage of class SingleValue-Decimal
  • float
    • Set to the ClipboardProperty value as a com.pega.ibm.icu.math.BigDecimal.BigDecimal
    • Inside of an array, converted to a ClipboardPage of class SingleValue-Decimal
• Boolean
  • Set to the ClipboardProperty value as a Boolean
  • Inside of an array, converted to a ClipboardPage of class SingleValue-Text
• Null – Skipped