XML POST Request - Spectrum_OnDemand - web_services - 23.1

Spectrum Web Services Guide

Product type
Software
Portfolio
Integrate
Product family
Spectrum
Product
Spectrum > Web Services
Version
23.1
Language
English
Product name
Spectrum Technology Platform
Title
Spectrum Web Services Guide
First publish date
2007
Last updated
2024-10-17
Published on
2024-10-17T00:33:46.811413

User-defined web services can be exposed as a REST web service and configured to have a POST method that accepts XML input.Spectrum Technology Platform REST web services have a POST method that accepts XML input. Specify Content-Type:application/xml and use the following format for XML POST requests.

Flat Data

Use this format to send flat data to a web service using POST:

<ServiceNameRequest xmlns:svc="http://www.pb.com/spectrum/services/ServiceName">
    <svc:Input>
       <svc:Row>
          <svc:Field1>Example value</svc:Field1>
          <svc:Field2>Another example value</svc:Field2>
       </svc:Row>
    </svc:Input>
</ServiceNameRequest>

Where:

ServiceName
The name of the web service on the Spectrum Technology Platform server.
Field1 and Field2
The names of the input fields defined in the service's Input stage.

For example, this request sends a first name and last name to a service named CasingExample.

<CasingExampleRequest xmlns:svc="http://www.pb.com/spectrum/services/CasingExample">
    <svc:Input>
       <svc:Row>
          <svc:FirstName>Alex</svc:FirstName>
          <svc:LastName>Smith</svc:LastName>
       </svc:Row>
    </svc:Input>
</CasingExampleRequest>

List Data

List data consists of hierarchical groupings of fields grouped under a parent field.
Note: In order to use list data as input, the service must be exposed as a REST web service without any GET resources. If the service has a GET resource you will get an error in Spectrum Enterprise Designer when exposing the service because hierarchical fields are not supported for GET.

Use the following format to send list data to a web service using POST.

<?xml version="1.0" encoding="UTF-8"?>
<ServiceNameRequest xmlns:svc="http://www.pb.com/spectrum/services/ServiceName">
    <svc:Input>
        <svc:Row>
            <svc:ListField1>
                <svc:DataType>
                    <svc:SubField1>Example value</svc:SubField1>
                    <svc:SubField2>Example value</svc:SubField2>
                </svc:DataType>
            </svc:ListField1>
        </svc:Row>
    </svc:Input>
</ServiceNameRequest>

Where:

ListField1
The name of the hierarchical field defined in the service's Input stage.
DataType
The data type of the list field defined in the service's Input stage.
Subfield1 and Subfield2
The names of child fields that comprise the list field.

For example, this request sends a first name, last name, and a list of phone numbers to a service named CasingExample.

<CasingExampleRequest xmlns:svc="http://www.pb.com/spectrum/services/CasingExample">
    <svc:Input>
       <svc:Row>
          <svc:FirstName>George</svc:FirstName>
          <svc:LastName>Washington</svc:LastName>
          <svc:PhoneNumbers>
              <svc:PhoneNumbers>
                 <svc:HomePhone>123-234-9876</svc:HomePhone>
                 <svc:CellPhone>123-678-9012</svc:CellPhone>
                 <svc:OfficePhone>123-987-6543</svc:OfficePhone>
               </svc:PhoneNumbers>
          </svc:PhoneNumbers>
       </svc:Row>
    </svc:Input>
</CasingExampleRequest>

User Fields

You can pass extra fields through the web service even if the web service does not use them. These fields are returned, unmodified, in the user_fields section of the response. The user fields you supply in the request do not need to be defined in the service dataflow's Input stage.

<ServiceNameRequest xmlns:svc="http://www.pb.com/spectrum/services/ServiceName">
    <svc:Input>
       <svc:Row>
          <svc:user_fields>
            <svc:user_field>
                <svc:name>FieldName</svc:name>
                <svc:value>FieldValue</svc:value>
            </svc:user_field>
          </svc:user_fields> 
       </svc:Row>
    </svc:Input>
</ServiceNameRequest>

Where:

FieldName
The name of the pass-through field.
FieldValue
The value contained in the pass-through field.

For example, this request sends the spouse's name as a pass-through field. The user field name is Spouse and the value of the field is Martha.

<CasingExampleRequest xmlns:svc="http://www.pb.com/spectrum/services/CasingExample">
    <svc:Input>
        <svc:Row>
            <svc:FirstName>George</svc:FirstName>
            <svc:LastName>Washington</svc:LastName>
            <svc:PhoneNumbers>
                <svc:PhoneNumbers>
                    <svc:HomePhone>123-123-1234</svc:HomePhone>
                    <svc:CellPhone>123-456-4567</svc:CellPhone>
                    <svc:OfficePhone>123-678-6789</svc:OfficePhone>
                </svc:PhoneNumbers>
            </svc:PhoneNumbers>
            <svc:user_fields>
                <svc:user_field>
                    <svc:name>Spouse</svc:name>
                    <svc:value>Martha</svc:value>
                </svc:user_field>
            </svc:user_fields>
        </svc:Row>
    </svc:Input>
</CasingExampleRequest>

Options

You can specify options in the request, overriding the default options specified in the service dataflow. For user-defined web services, you can only specify options in the request if the dataflow has been configured to accept options. To configure a service to accept options in the request, open the service in Spectrum Enterprise Designer and select Edit > Dataflow Options.

To specify processing options in a request, use this format:

<ServiceNameRequest xmlns:svc="http://www.pb.com/spectrum/services/ServiceName">
    <svc:options>
        <svc:OptionName>OptionValue</svc:OptionName>
    </svc:options>
    <svc:Input>
        <svc:Row> ... </svc:Row>
    </svc:Input>
</ServiceNameRequest>

Where:

OptionName
The name of the option. For a list of valid options for the service see the service's WADL or open the service in Spectrum Enterprise Designer and select Edit > Dataflow Options.
OptionValue
A legal value for the option. For a list of legal values, open the service in Spectrum Enterprise Designer and select Edit > Dataflow Options.

For example, this request sets the option OutputCasing to U:

<AddressValidationRequest xmlns:svc="http://www.pb.com/spectrum/services/AddressValidation">
    <svc:options>
      <svc:OutputCasing>U</svc:OutputCasing>
    </svc:options>
    <svc:Input>
       <svc:Row>
          <svc:FirstName>George</svc:FirstName>
          <svc:LastName>Washington</svc:LastName>
          <svc:AddressLine1>123 Main St.</svc:AddressLine1>
          <svc:City>Springfield</svc:City>
          <svc:StateProvince>MO</svc:City>
       </svc:Row>
    </svc:Input>
</AddressValidationRequest>

Example XML Request using POST

The following example demonstrates how to include options, flat fields, a list field, and user-defined fields in an XML request to a web service using POST.

<CasingExampleRequest xmlns:svc="http://www.pb.com/spectrum/services/CasingExample">
    <svc:options>
        <svc:OutputCasing>U</svc:OutputCasing>
    </svc:options>
    <svc:Input>
        <svc:Row>
            <svc:FirstName>George</svc:FirstName>
            <svc:LastName>Washington</svc:LastName>
            <svc:AddressLine1>1073 Maple</svc:AddressLine1>
            <svc:City>Batavia</svc:City>
            <svc:StateProvince>IL</svc:StateProvince>
            <svc:PhoneNumbers>
                <svc:PhoneNumbers>
                    <svc:HomePhone>123-123-1234</svc:HomePhone>
                    <svc:CellPhone>123-345-3456</svc:CellPhone>
                    <svc:OfficePhone>123-456-4567</svc:OfficePhone>
                </svc:PhoneNumbers>
            </svc:PhoneNumbers>
            <svc:user_fields>
                <svc:user_field>
                    <svc:name>Spouse</svc:name>
                    <svc:value>Martha</svc:value>
                </svc:user_field>
            </svc:user_fields>
        </svc:Row>
    </svc:Input>
</CasingExampleRequest>
In this example,
  • OutputCasing is an option exposed by the web service that controls whether the output is returned in upper case or lower case. In this request, it is set to U for upper case.
  • Input is the label of the Input stage in the dataflow as displayed on the canvas in Spectrum Enterprise Designer.
  • Row is the name of the record-level entity as specified in the Input stage of the dataflow, in the Data type name field on the Input Fields tab.
  • FirstName, LastName, AddressLine1, City, and StateProvince are flat fields.
  • PhoneNumbers is a hierarchical ("list") field containing subfields name HomePhone, CellPhone, and OfficePhone.
  • user_fields contains user-defined fields that are passed through and returned in the output unmodified by the web service.