SOAP to REST Mapping for the dataSentToOfficeRequest Operation

Overview

This document specifies the data mapping between a RESTful JSON API endpoint and a backend SOAP web service for the dataSentToOfficeRequest operation. This mapping layer allows API consumers to use a standard REST interface, while the platform transforms the request into the SOAP format required by the backend service and transforms the SOAP response back into a RESTful JSON format.

The primary goal is to abstract the complexity of the SOAP protocol, including its specific wrapper objects and null-value representations, providing a stable and modern API for consumers. The transformation is handled by a mapping generator component.

• Input: An HTTP POST request to the / {env}/{serviceKey}/datasenttoofficerequest endpoint with a JSON payload.
• Processing: The mapping generator transforms the incoming JSON into a SOAP XML request, sends it to the backend, receives the SOAP XML response, and transforms it back into a JSON payload.
• Output: A JSON response to the original caller.

How it Works

The mapping process involves a bidirectional data transformation for requests and responses. Correct transformation is critical for successful communication with the backend SOAP service.

Request Transformation (REST to SOAP)

When an API consumer sends a POST request, the mapping generator performs the following transformations to construct the SOAP request body.

1. Receive REST Request: The system accepts a POST request to /{env}/{serviceKey}/datasenttoofficerequest with a JSON body.
2. Insert SOAP Wrappers: The mapping generator converts JSON arrays into the specific wrapped collection types required by the backend's WSDL/XSD. This is a deterministic process. If these wrappers are not generated correctly, the backend may return a business error or fault, even if the underlying data is valid.

The following table details the required request wrapper transformations:

REST JSON Field	Required SOAP Wrapper Type
request.personId[]	request.personId.PersonIdObj[]
personRelationship[]	personRelationship.int[]
personInfo[]	personInfo.PersonInfoObj[]
dataWidgets[]	dataWidgets.DataWidgetObj[]
dataWidgetInfo[]	dataWidgetInfo.DataWidgetInfoObj[]
dataWidgetExtraInfo[]	dataWidgetExtraInfo.DataWidgetExtraInfoObj[]

Response Transformation (SOAP to REST)

After the backend service processes the request, it returns a SOAP response. The mapping generator transforms this response into a standard RESTful JSON format.

1. Unwrap Root Element: The primary data from the SOAP response is extracted and becomes the root of the JSON response. The Body.dataSentToOfficeRequestResponse.dataSentToOfficeRequestReturn.ResponseData path in the SOAP envelope is mapped to the JSON root object, named result.

2. Unwrap Collections: SOAP collection wrappers are removed to produce simple JSON arrays.

   SOAP Collection Wrapper	Resulting REST JSON Array
   userDataList.UserDataObj[]	userDataList[]
   dataList.DataObj[]	dataList[]
   descriptionDataList.DescriptionDataObj[]	descriptionDataList[]
   ctaList.CTAValue[]	ctaList[]
   files.FileObj[]	files[]

3. Handle Nulls: Null or empty values in SOAP are converted to JSON null.

   • An element with xsi:nil="true" is converted to null.
   • An empty XML node (e.g., <x/>) is converted to null if the field is defined as nillable, unless this behavior is overridden by a specific policy.

Character Encoding

The entire process must preserve UTF-8 character encoding. This ensures that all text, including non-ASCII characters such as Hebrew, is transmitted and logged correctly without corruption. Both the incoming JSON and the outgoing SOAP XML must maintain charset=utf-8.

API Endpoint Reference

POST ///datasenttoofficerequest

This endpoint accepts a POST request to submit data for the dataSentToOfficeRequest operation.

Request Body

The request body must be a JSON object with the structure detailed below.

{
  "personId": [
    {
      "companyId": "518880026",
      "idNum": "060743705",
      "personRelationship": [1],
      "personInfo": [
        {
          "personalInformationId": 1,
          "personalInformationIsTrue": true
        }
      ]
    }
  ],
  "dataWidgets": [
    {
      "dataWidgetId": 1,
      "dataWidgetInfo": [
        {
          "dataWidgetCheckBox": true,
          "dataWidgetMultipleSelection": [1],
          "dataWidgetInputNumber": "1",
          "dataWidgetInputString": "1",
          "dataWidgetInputDate": "1"
        }
      ],
      "dataWidgetExtraInfo": [
        {
          "dataWidgetKey": "vehicleLicenseNumber",
          "dataWidgetValue": "1234"
        }
      ]
    }
  ]
}

Request Body Fields

The following table describes the fields in the JSON request body. The source does not specify default values or whether fields are required.

Field	Type	Description
personId	Array of Objects	A list of person identifiers.
personId[].companyId	String	The company identifier.
personId[].idNum	String	The person's identification number.
personId[].personRelationship	Array of Integers	A list of relationship identifiers.
personId[].personInfo	Array of Objects	A list of personal information objects.
personId[].personInfo[].personalInformationId	Integer	The ID for the piece of personal information.
personId[].personInfo[].personalInformationIsTrue	Boolean	A flag indicating if the personal information is true.
dataWidgets	Array of Objects	A list of data widgets.
dataWidgets[].dataWidgetId	Integer	The ID for the data widget.
dataWidgets[].dataWidgetInfo	Array of Objects	A list of informational objects for the widget.
dataWidgets[].dataWidgetInfo[].dataWidgetCheckBox	Boolean	The state of a checkbox.
dataWidgets[].dataWidgetInfo[].dataWidgetMultipleSelection	Array of Integers	A list of selected items from a multi-select control.
dataWidgets[].dataWidgetInfo[].dataWidgetInputNumber	String	A numeric value provided as a string.
dataWidgets[].dataWidgetInfo[].dataWidgetInputString	String	A string input value.
dataWidgets[].dataWidgetInfo[].dataWidgetInputDate	String	A date value provided as a string.
dataWidgets[].dataWidgetExtraInfo	Array of Objects	A list of key-value pairs for extra widget information.
dataWidgets[].dataWidgetExtraInfo[].dataWidgetKey	String	The key for the extra information (e.g., vehicleLicenseNumber).
dataWidgets[].dataWidgetExtraInfo[].dataWidgetValue	String	The value associated with the key.

Response Body

The response is a JSON object. A successful response contains the unwrapped data from the ResponseData element of the backend SOAP response. The source does not provide an example of a successful response body.

Troubleshooting

Error conditions are handled by mapping backend SOAP errors to RESTful error responses.

Condition	Trigger	Meaning
Runtime Error	The backend service returns a SOAP Fault.	The platform maps the SOAP Fault to a deterministic runtime error contract for the API consumer, based on the fault_mapping policy.
REST Error Object	The backend service returns a successful SOAP response containing a business error code in the ResponseData.errorCode.errorCode node.	Based on mapping policy, this business-level error can be "promoted" to a top-level REST error object, signaling a failure to the API consumer instead of a successful response with an error code inside.
Business Error/Fault	The REST-to-SOAP request transformation fails to generate the required SOAP wrappers correctly.	The backend service cannot parse the request and returns a generic business error or fault. This indicates a potential issue in the mapping generator configuration rather than invalid data from the API consumer.

See Also

• For more information on the design of the mapping system, see the full design document: docs/lld/full-auto-mapping-design.md.

---

All SOAP-to-REST docs