Preparing to retrieve SOAP web services input

To retrieve input from a SOAP web service for an application, identify the parameters used to call the SOAP web service. Test the exchange of data between RICOH ProcessDirector and the application. Then define and configure a SOAP web service input device.
To prepare to retrieve SOAP web services input:
  1. Learn the requirements for communication with the SOAP web service for the application:
    • The values for authenticating with the application
    • The values for requesting data from the SOAP web service
    • The format of the data provided in the response

    Refer to the documentation for the application or consult with the company that hosts the application.

  2. To prepare RICOH ProcessDirector to communicate with the application, do these tasks:
    • If the application requires a security certificate, install the certificate on the RICOH ProcessDirector primary computer.
    • If your environment requires a proxy server to communicate with web services, set up the system to use it.
    • Import WSDL files for all the web services that you plan to call.

      RICOH ProcessDirector creates SOAP request objects from SOAP operations in the WSDL file. You specify a prefix that RICOH ProcessDirector adds to the names of the SOAP operations when it creates the objects. A SOAP request object lets RICOH ProcessDirector determine the SOAP version and other information required to make a correct call to the web service.

    For more information, see the related tasks.

  3. Run a manual test that authenticates with the application and requests a response from the SOAP web service. Verify that the web service returns the response that you want.
    Many browsers have plug-ins, such as Boomerang for Google Chrome, that test web service calls to SOAP clients.
  4. Decide how you want the SOAP web service input device to create jobs from the data in the response returned by the web service.
    • Every time the input device receives a response, it can create a job containing all XML data in the response.
    • The input device can examine the response using an XPath expression.

      If the input device finds XML elements specified by the expression, it creates a job for each matching element. Each job contains the matching element and all the elements nested within it. If the input device finds two or more elements, it can create independent jobs or child jobs.

      If the input device does not find matching elements, it does not create a job.

  5. Define a SOAP web service input device:
    1. Click the Administration tab.
    2. In the left pane, click Devices ⇒ Input Devices.
    3. Click Add ⇒ SOAP web service.
  6. On the General tab:
    • Type a name for the input device.
    • Set the Polling interval property to the time that you want the input device to wait between web service calls.
    • After you define a workflow to process the XML jobs, set the Child workflow property to the name of that workflow.
    • Enter values for other properties that you want to set.
  7. On the Request tab:
    1. Set the Request URL property to the URL of the web service that returns data that RICOH ProcessDirector uses to create one or more jobs.
    2. For the value of the Request payload property, specify the body of the web services request that the input device submits to the application.
      To specify a credential or token and a time range that matches the value of the Polling interval property, use symbols for these properties:
      Database name of property User interface name of property Remarks
      WebService.Credential None RICOH ProcessDirector stores the web service credential or token in this property.
      WebService.CurrentRequestTime None RICOH ProcessDirector sets the value of this property at the start of the polling interval.
      WebService.LastSuccessRequestTime Status tab: Time of last successful request When the input device successfully communicates with the application, RICOH ProcessDirector sets the value of this property to match the value of the WebService.CurrentRequestTime property. A successful communication results in a response code 200, even if no data is received that RICOH ProcessDirector can use to create jobs.

      In this example, the payload includes these elements: <Token>, <TimeRange>, <Start>, and <End>. The value of each element is a symbol:

      <Token>${WebService.Credential}</Token><TimeRange> <Start>${WebService.LastSuccessRequestTime}</Start> <End>${WebService.CurrentRequestTime}</End></TimeRange>

      The input device resolves the symbols when it polls for XML input.

    3. Set the SOAP request property to the SOAP request that RICOH ProcessDirector created when you imported the WSDL file.
      For example, you want to use the GetOrdersByDate SOAP request. You prepended PrintShop to the names of the SOAP requests when you imported them. Select PrintShop-GetOrdersByDate.
    4. Select a value for the Create job from response property to specify how the input device creates jobs from the input:
      • To create a job every time the input device receives a response, select Always.
      • To examine the XML in the response and create a job each time that an XML element is found, select Only when response pattern matches.
    5. If you selected Only when response pattern matches:
      • Set the Response pattern to match property to the XPath expression that identifies the XML element that you want to use for each job.

        For example, you want one job for each order, and the data in the response contains an order element. Enter the XPath expression that represents the order element in the XML.

      • Set the Create child jobs property to Yes if you want to create child jobs when the input device finds two or more matches. The input device also creates a parent job without any data. If the input device finds one match, it creates an independent job.
      • Set the Create child jobs property to No if you want to create independent jobs regardless of how many matches the input device finds.
    6. If your environment requires a proxy server to communicate with web services, set the Use proxy property to the correct proxy server.
    7. Set the Time zone offset property to the offset in hours between Coordinated Universal Time (UTC) and the time zone used by the web service.
      For example, if the web service uses Pacific Standard Time, set the property to -8.
        Note:
      • Make sure that you change this property when a location that hosts the web service changes between standard and daylight savings time. Otherwise, during the lost or gained hour, you can lose the data that RICOH ProcessDirector uses to create jobs.
      • If the web service uses UTC, enter 0 or leave the field blank.
  8. On the Authentication tab, specify the values required to authenticate with the application.
    For more information, see the related task about authenticating with a SOAP web service.

    If the application does not require authentication, leave all the Authentication properties blank.

  9. Optional: On the Advanced tab, specify any optional properties for your environment.
  10. When you finish, click OK.

When you finish setting up your input devices, notifications, and workflows, test the exchange of data between RICOH ProcessDirector and the application.

Example

The supplied RestfulWebServiceSample REST web service input device is similar to a SOAP web service input device. The MarcomCentral Connect feature includes a supplied SOAP web service input device.

In this section:

  1. Using a SOAP web service to authenticate with an application
    SOAP web service input device and notification objects can use a SOAP web service to authenticate with an application. RICOH ProcessDirector supports both API key and session authentication. Input device objects authenticate when they poll for input. Notification objects authenticate when they send status to the application.

Related information:

Web Services Enablement
Usage scenario for processing JSON orders with web services
RestfulWebServiceWF
RestfulWebServiceSample
RestfulWebServiceSampleNotify
Defining input devices
Setting up to exchange data with web services
Installing a security certificate for a web site
Setting up the system to use a proxy server
Importing WSDL files
Parent topic: Configuring the system