Adding an External Web Service

External web services are data processing services provided over the Internet by a third party. You can use an external web service as a stage in a flow, allowing you to expand the capabilities of your Spectrum Technology Platform server.

This procedure defines a connection between your Spectrum Technology Platform server and a third-party web service. After completing this procedure, you will have a new stage in Spectrum Enterprise Designer which represents the external web service. You can then use the external web service as you would any other stage in a flow.

  1. Open Spectrum Management Console.
  2. Go to Resources > External Web Services.
  3. Click the Add button .
  4. On the Descriptor step:
    1. Specify the web service's WSDL or WADL by one of these methods:
      To load the web service's descriptor from a URL In the Load descriptor field, choose By URL and in the URL field specify the URL of the WADL or WSDL. Enter your credentials for the web service if required by the web service.
      To load the web service's descriptor from a file In the Load descriptor field, choose Upload then select the file in the Upload file field. Some web service venders prefer to provide the WSDL or WADL as a file rather than making it available via a URL.
      For REST web services that have no WADL In the Load descriptor field, choose None.
    2. Click Next.
  5. On the Settings step:
    1. In the Name field, enter the name you want to give the external web service when it is exposed on Spectrum Technology Platform. This will be the stage name shown in Spectrum Enterprise Designer. The name can be anything you want but must not already be used by another web service on your system.
    2. In the Timeout field, enter the number of seconds that are allowed to elapse before a request submitted to the web service times out.
      Note: The timeout value you specify here applies to any request made to the web service. This includes not only transactions made against the exposed web service, but also requests made while configuring the web service. Such configuration requests are invoked by choosing a new item on the Request page and running preview. Timeouts can occur when performing any of these actions. If timeouts do occur, increasing the Timeout value can help to avoid them, provided the web service is actually up and running.
    3. If the external web service requires a user name and password, under Security settings, in the Type field, choose how to transmit the user name and password from the Spectrum Technology Platform server to the external web service.
      None
      Choose this option if you do not need to provide a user name and password to use the external web service.
      Basic Authentication
      Choose this option to pass user name and password information to the external web service in the HTTP header.
      WS-Security
      For SOAP services only, choose this option to pass user name and password information to the external web service through the header of the SOAP message.
    4. Enter a user name and password if they are required to access the external web service.
    5. Click Next.
  6. On the Request step, configure the parameters to include in requests to the external web service.

    For REST web services:

    URL
    If you did not supply a WADL on the Descriptor step, enter a sample request URL containing the path parameters (if any) and query parameters that you want to include in the request. For example:

    http://example.com/rest/customers/{state}?age=31

    Here, there is one path parameter, {state}, and one query parameter, age.

    If you supplied a WADL on the Descriptor step, the URL field displays the endpoint based on the WADL you provided. You cannot edit the endpoint.

    Resource
    This setting is only visible if you supplied a WADL on the Descriptor step. Select the web service resource that you want to expose on Spectrum Technology Platform.
    Note: If you want to expose more than one resource, you must define a separate external web service for each resource.
    Method
    Select the HTTP method to use to for the request to the external web service.

    If you provided a WADL on the Descriptor step, only those HTTP methods supported by the external web service are listed.

    Path parameters
    The Path parameters section lists the parameters that are part of the URL path, if the external web service uses path parameters. For example, this URL contains the path parameter {state}:

    http://example.com/rest/customers/{state}?age=31

    If you provided a WADL on the Descriptor step, the web service's path parameters are listed. If you did not supply a WADL on the Descriptor step, the list of path parameters is generated from the sample request URL you provided in the URL field. To add or remove a path parameter, add or remove it from the URL. Anything in the URL surrounded by curly braces is interpreted as a path parameter.

    Query parameters
    The Query parameters section lists the parameters that appear after the "?" in the request URL. For example, this URL contains the query parameter age:

    http://example.com/rest/customers/{state}?age=31

    If you provided a WADL on the Descriptor step, the web service's query parameters are listed. If you did not provide a WADL on the Descriptor step, the list of query parameters is generated from the sample request URL you provided in the URL field. To add or remove a query parameter, add or remove it from the URL.

    Table 1. Settings for REST Path Parameters and Query Parameters
    Setting Description
    Expose Check the box in this column to make the parameter available in the Spectrum Technology Platform stage.
    Request This column lists the parameter name that is used in the request to the external web service.
    Input This column lists the input field names as they will appear in a flow. You can leave the names the same as those used by the third-party web service or you can change them by hovering over the name and clicking the edit button .
    Default Value Check the box in this column if you want to specify a default value for the field. Enter the default value in to the field that appears after checking the box.

    If you want to provide a default value that cannot be overridden from a flow, check the box in the Default Value column and clear the corresponding box in the Request column. This hides the field from flows while providing the default value in the request to the external web service. This may be useful if you have an access key that you need to provide in each request. For example:



    For SOAP web services:

    URL
    This field displays the endpoint based on the WSDL you provided on the Descriptor step. You cannot edit this field.
    Operation
    Select the web service operation you want to perform.
    Note: If you want to expose more than one operation, you must define a separate external web service for each operation.
    Request
    In this column, select the fields and options you want to make available through Spectrum Technology Platform.
    Input
    This column lists the input field names as they will appear in a flow. You can leave the names the same as those used by the third-party web service or you can change them by hovering over the name and clicking the edit button .
    Default Value
    Check the box in this column if you want to specify a default value for the field. Enter the default value in to the field that appears after checking the box.

    If you want to provide a default value that cannot be overridden from a flow, check the box in the Default Value column and clear the corresponding box in the Request column. This hides the field from flows while providing the default value in the request to the external web service. This may be useful if you have an access key that you need to provide in each request. For example:



  7. If you selected POST or PUT in the Method field, define the structure of the data you want to send to the web service in the POST or PUT operation. To do this, click the Format button and choose one of the following options:
    Upload schema
    Choose this option if you have an XML schema that defines the structure of the data you to send to the web service in the POST or PUT operation. After selecting this option, browse to the schema file.
    Provide sample
    Choose this option if you have a sample of the data you want to send to the web service in the POST or PUT operation. After selecting this option, you can enter the sample manually or paste the sample into the window.

    After you provide a schema or sample, check the box next to each data element you want to make available in the flow stage.

  8. Click Next.
  9. On the Headers step:
    1. Under HTTP headers, specify the value to pass to the external web service for each header. The values you specify here are used for all requests from Spectrum Technology Platform to the external web service. If no headers are listed, the external web service does not require any HTTP headers.
    2. For SOAP web services, if the external web services supports SOAP headers you can select the headers you want to use under SOAP headers. You can specify a default value for each SOAP header. The default value can be overridden in each request to Spectrum Technology Platform. The Input column shows the name of the header that will be used in requests to Spectrum Technology Platform. If you want to use a different name, hover over the name and click the edit button .

      If a check box is checked and grayed out, it means that the header is required and you cannot disable it.

    3. Click Next.
  10. On the Response step:
    1. If you want the response from the external web service to be returned in a single field, check the box Return payload as field. All response elements will be placed in a single field instead of being returned in separate fields. For REST web services, the field name is RestReponse, and for SOAP web services the field name is SoapResponse.
    2. If you are configuring a REST web service, there is a Format button. Click this button to choose how you want to define the structure of the web service response that will be returned by Spectrum Technology Platform:
      Upload schema
      Choose this option if you have an XML schema that defines the structure of the response you want Spectrum Technology Platform to return. After selecting this option, browse to the schema file.
      Provide sample
      Choose this option if you have a sample response from the external web service and you want to use it to define the response you want from Spectrum Technology Platform. After selecting this option, you can enter the sample manually or paste the sample into the window.
    3. In the Response column, choose the fields you want to make available in Spectrum Technology Platform.

      The icon indicates that a field will be returned as a list field. A list is a Spectrum Technology Platform data type that contains hierarchical data that can be repeated. For example, a field PhoneNumbers may contain multiple Phone fields:

      <PhoneNumbers>
         <Phone>
      	<Type>Cell</Type>
      	<Number>312-123-4567</Number>
         </Phone>
         <Phone>
      	<Type>Home</Type>
      	<Number>773-123-4567</Number>
         </Phone>
      </PhoneNumbers>

      In this case the PhoneNumbers field would be a list field that can contain a list of Phone elements.

    4. The Output column lists the output field names as they will appear in a flow. You can leave the names the same as those used by the third-party web service or you can change them by hovering over the name and clicking the edit button .
    5. Click Next.
  11. On the Preview step, you can test the external web service by entering sample data then clicking Run Preview. This is optional.

    Here are some tips for entering sample data:

    • You do not have to enter data in every field. Leaving a field empty results in an empty string being used for preview.
    • If you want to preview the effect of passing the default value or a null value in a field, click the Disable icon next to the field:

      If you have defined a default value for the field on the Request tab, the default value will be used. If you have not defined a default value, a null value will be used.
    • You can preview multiple records at once. To add a record, click the Add button .
    • You can import test data from a file. To import data, click the Import button . Note the following:
      • The first row in the file must be a header record. The field names in the header must match the field names required by the service.
      • The maximum number of records that can be imported is five.
      • If the file uses a space as the field separator, field values must be surrounded by quotes. Here is an example of a file that uses a space as the field separator:
        AddressLine1 AddressLine2 City StateProvince PostalCode
        "One Global View" "" "Troy" "NY" "12180"
        "3001 Summer St" "" "Stamford" "CT" "06926"
        "224 N Michigan Ave" "Suite 300" "Chicago" "IL" ""
    • To delete all records, click the Delete button at the top of the preview area:

    • To delete an individual record, hover over the input record name (for example, "Input Record 1") and click the Delete button next to the record name:

  12. To make the external web service available to use in flows, switch the Enabled switch to On.
  13. Click Save.

The external web service is now defined and available to use as a stage in a flow in Spectrum Enterprise Designer.