User-defined web services can be exposed as a REST web service and
configured to have a POST method that accepts XML input.
Spectrum OnDemand 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 OnDemand 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
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
.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 .
- OptionValue
- A legal value for the option. For a list of legal values, open the service in Spectrum Enterprise Designer and select .
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>
- 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.