Preparing to retrieve REST web services input

To retrieve input from a REST web service for an application, identify the parameters used to call the REST web service. Test the exchange of data between RICOH ProcessDirector and the application. Then define and configure a REST web service input device.
To prepare to retrieve REST web services input:
  1. Learn the requirements for communication with the REST web service for the application:
    • The values for authenticating with the application
    • The values for requesting data from the REST 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.

    For more information, see the related tasks.

  3. Run a manual test that authenticates with the application and requests a response from the REST 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 REST clients.
  4. Decide how you want the REST 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 or JSON data in the response.
    • The input device can examine the response using an XPath or JSONPath expression.

      If the input device finds XML elements or JSON objects specified by the expression, it creates a job for each matching element or object. Each job contains the matching element or object and all the elements or objects nested within it. If the input device finds two or more elements or objects, 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 REST web service input device:
    1. Click the Administration tab.
    2. In the left pane, click Devices ⇒ Input Devices.
    3. Click Add ⇒ REST web service.
    As an alternative, you can copy the supplied RestfulWebServiceSample REST web service input device.
  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 or JSON 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. Set the Request method and Request content type properties to the values required by the web service.
    3. 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.
        Note:
      • These three job properties are used as example XML values for the Request payload property and as example JSON values for the Request parameters property. The requirements of the web service determine which properties you use to submit these and other values.

      In this XML example, the payload includes these elements: <Token>, <TimeRange>, <Start>, and <End>. The values of three elements are symbols:

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

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

    4. Set the values for the Request header and Request parameters properties, as required.
      Each header field or parameter is a keyword/value pair. Each pair must appear on a separate line and must be separated using a colon (:) or equals sign (=).

      The keyword and value can be multiple words. RICOH ProcessDirector uses the first colon or equals sign on each line to split the words into the keyword/value pair.

      This example contains three parameters: token, start, and end. The value of each keyword is a RICOH ProcessDirector symbol. Each symbol contains one of these properties: WebService.Credential, WebService.LastSuccessRequestTime, and WebService.CurrentRequestTime.

      token:${WebService.Credential}start:${WebService.LastSuccessRequestTime}end:${WebService.CurrentRequestTime}

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

    5. 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 or JSON in the response and create a job each time that an XML element or JSON object is found, select Only when response pattern matches.
    6. If you selected Only when response pattern matches:
      • Set the Response pattern to match property to the XPath expression that identifies the XML element or to the JSONPath expression that identifies the JSON object.
      • 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.
    7. If your environment requires a proxy server to communicate with web services, set the Use proxy property to the correct proxy server.
    8. 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 REST 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

Examine the supplied RestfulWebServiceSample REST web service input device.

In this section:

  1. Using a REST web service to authenticate with an application
    REST web service input device and notification objects can use a REST 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
Parent topic: Configuring the system