Sending and Receiving HTTP Body Data

The following sections describe how to construct working data to map XML and JSON body data to and from the RESTCaller service and the REST service that it is calling.

Sending XML Data

To send XML data:

Create a Working Data variable with some convenient name, such as "BodyXMLVariableOut".
Set the type to Private Complex.
Add a child DataElement to represent the document root element of the HTTP body XML. It should be named and typed the same as the root XML element of the data that appears in the body of the REST HTTP call. Take care to set the correct XML namespace as expected by the REST services, because the child DataElement will take the namespace defined of the Orchestration inherited from the parent working data variable (in this example, BodyXMLVariableOut) by default. In most cases, the document root element should be a Private Complex type. Naming the child DataElement, "RESTServiceDocument", creates the working data structure:
```
BodyXMLVariableOut 
               RESTServiceDocument
```
which results in the document root element sent in the HTTP body as:
```
<RESTServiceDocument>…</RESTServiceDocument>
```
Add any further Child DataElements under the document root element. These should be added with the appropriate names, types, and namespaces to create the same structure as the expected XML. For example, naming the Child DataElement, "Name":
```
BodyXMLVariableOut 
               RESTServiceDocument
                              Name
```
Results in the root XML element sent in the HTTP body as:
```
<RESTServiceDocument>
       <Name>…</Name>…
</RESTServiceDocument>
```
Initialize the created Working Data variable structure DataElements with appropriate default values or via Calculate steps in the normal way.
Note: If a DataElement is optional and no value is mapped to it, it will not be sent in the resulting XML structure.
Create a RESTCaller service step, and set the operation to PUT or POST, and set the Option values as appropriate. Map the created Working Data variable to the "bodyXML" parameter. For example, the variable "BodyXMLVariableOut" should be mapped to the "bodyXML" parameter. At runtime, the content "RESTServiceDocument" is copied to set the content of the "bodyXML" parameter and sent as the HTTP body content of the resulting HTTP REST service call:
```
<RESTServiceDocument>
       <Name>my name</Name>
       <OtherElement>some value</OtherElement >
</RESTServiceDocument>
```

Receiving XML Data

To receive XML data:

Create a Working Data variable with a convenient name such as "BodyXMLVariableIn".
Set the type to Private Complex.
Add a Child DataElement to represent the root element of the HTTP body XML. It should be named and typed the same as the root XML element of the data that will appear in the body of the REST HTTP call response. Take care to set the correct XML namespace as returned by the REST services because the Child DataElement will take the namespace defined of the Orchestration inherited from the parent working data variable (in this example, BodyXMLVariableIn) by default. In most cases, the root element should be a Private Complex type. For example, naming the Child DataElement "RESTServiceDocument" creates the following working data structure:
```
BodyXMLVariableIn 
               RESTServiceDocument
```
which creates a container for the expected document root XML element as:
```
<RESTServiceDocument>…
</RESTServiceDocument>
```
Add any further Child DataElements under the HTTP body root element. These should be added with appropriate names, types, and namespaces to create the same structure as the expected XML. For example, naming the Child DataElement "Name" results in the expected root XML element to be received in the HTTP body as:
```
<RESTServiceDocument>
       <Name>…</Name>…
</RESTServiceDocument>
```
Important: In addition to the name, it is essential to set the namespace property correctly for any element in this structure. If the declared namespace does not match the namespace of the element in the received XML, the orchestration interprets them as different elements and does not copy the value data.

Tip: Due to the way Orchestrations work, it is only necessary to declare the specific elements from the received XML that you actually need to process in the Orchestration. The Working Data variable must be created with sufficient structure to place the element at the correct path in the XML data, but elements that are not part of a path and not accessed do not need to be declared.
Create a RESTCaller service step, and set the operation to GET, PUT or POST as appropriate. Set the Option values as appropriate. Map any inputs as required and described above.
Create a Calculate step that follows the RESTCaller service step, and map the RESTCaller service step response results.result.XML to the variable that you created to receive the returned data. For example, "BodyXMLVariableIn".
Create further Calculate steps to extract specific values from the variable that you created to receive the returned data. For example, use the "BodyXMLVariableIn" variable to retrieve the value of the returned RESTServiceDocument and its children. The value of the Name child element is retrieved using the calculate Expression BodyXMLVariableIn.RESTServiceDocument.Name.

Note: If the REST service provides an XSD schema for the XML document it expects, it may be possible to import that schema and use the named types defined within it to set the type of the root XML elements for either sent or received XML. For details on this advanced usage, search the knowledge base at http://www.serena.com/support for solution S140078.

Sending JSON Data

To send JSON data:

Create a Working Data variable with a convenient name such as "BodyJSONVariableOut".
Set the type to Private Complex.
Add a Child DataElement to hold the XML that will be converted to JSON data. It must be named "JsonDoc". Set the type to Private Complex. Set the namespace to empty by deleting any value in the Namespace property.
Add any further Child DataElements under the JsonDoc root element. These should be added with the appropriate names and types to create the same structure as the expected JSON. Set the namespace to empty by deleting any value in the Namespace property. The specific rules for correctly structuring and naming the elements is explained in Constructing Working Data XML to Map to JSON.
Initialize the created Working Data variable structure DataElements with appropriate default values and/or via Calculate steps in the normal way.
Note: If a DataElement is optional and no value is mapped to it, it will not be sent in the resulting XML structure or the JSON structure that it converts to.
Create a RESTCaller service step, and set the operation to PUT or POST as appropriate. Set the sendAsJSON Option parameter to true. Set other Option values as appropriate. Map the created Working Data variable to the "bodyXML" parameter. For example, the variable "BodyJSONVariableOut" should be mapped to the "bodyXML" parameter. At runtime, the content "JsonDoc" will be copied to set the content of the "bodyXML" parameter and then converted to JSON as the HTTP body content of the resulting HTTP REST service call.

Receiving JSON Data

To receive JSON data:

Create a Working Data variable with a convenient name such as "BodyJSONVariableIn".
Set the type to Private Complex.
Add a Child DataElement to hold the XML that will be converted to JSON data. It must be named "JsonDoc". Set the type to Private Complex. Set the namespace to empty by deleting any value in the Namespace property.
Add any further Child DataElements under the JsonDoc root element. These should be added with the appropriate names and types to create the same structure as the expected JSON. Set the namespace to empty by deleting any value in the Namespace property. The specific rules for correctly structuring and naming the elements is explained below in Constructing Working Data XML to Map to JSON.
Important: In addition to the name, it is essential to set the namespace property to empty by deleting any value in the Namespace property for any element in this structure because the XML that is converted from JSON uses no namespace. If the declared namespaces for all the elements are not empty, they will not match the empty namespace of the elements in the received JSON XML. The orchestration interprets them as different elements and does not copy the value data.

Tip: Due to the way Orchestrations work, it is only necessary to declare the specific elements from the received JSON XML that you actually need to process in the Orchestration. The Working Data variable must be created with sufficient structure to place the element at the correct path in the XML data, but elements that are not part of a path and not accessed do not need to be declared.
Create a RESTCaller service step, and set the operation to GET, PUT or POST as appropriate. Set the Option values as appropriate. Map any inputs as required and described above.
Create a Calculate step that follows the RESTCaller service step, and then map the RESTCaller service step response results.result.XML to the variable that you created to receive the returned data. For example, "BodyJSONVariableIn".
Create further Calculate steps to extract specific values from the variable that you created to receive the returned data. For example, use "BodyJSONVariableIn" to retrieve the value of the returned Name child element.