Preparing to send status to REST web services

You can use notification objects to send status to a REST web service for an application. For example, you can create a notification object to monitor when a job enters the RetainCompletedJobs step in a workflow that processes orders. When that event happens, the notification object can send the application information about the job, such as the order number and customer name.
To prepare to send status to REST web services:
  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 on the event that you want to trigger the notification and the conditions that determine when the notification calls the web service.
    If you want to send a notification for an event that occurs only when a specific workflow processes a job, specify that workflow as a condition.
  5. Define a REST web service notification:
    1. Click the Administration tab.
    2. In the left pane, click Objects ⇒ Notifications.
    3. Click Add ⇒ REST Web Service Notification.
    As an alternative, you can copy the supplied RestfulWebServiceSampleNotify REST web service notification.
  6. On the General tab, type a name for the notification.
  7. On the Request tab:
    1. Set the Request URL property to the URL of the web service that you want to notify.
    2. Set the Request method property to the value 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.
      In this XML example, the payload contains two XML elements: <Token> and <OrderNumber>.

      <Token>${WSNotification.WebService.Credential}</Token> <OrderNumber>${Job.Info.Attr1}</OrderNumber>

      The value for each element is a RICOH ProcessDirector symbol containing a property. If you are using a web service to authenticate with the application, include the WSNotification.WebService.Credential property in a symbol. Replace the other element and property with the elements and properties that you want to send to the application. The notification resolves the symbols when it sends status to the REST web service.

    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, orderNumber, and customerName. The value of each keyword is a RICOH ProcessDirector symbol. Each symbol contains one of these properties: WSNotification.WebService.Credential, Job.Info.Attr1, and Job.CustomerName.

      token:${WSNotification.WebService.Credential}orderNumber:${Job.Info.Attr1}customerName:${Job.CustomerName}

      The input device resolves the symbols when it sends status to the REST web service.

    5. If your environment requires a proxy server to communicate with web services, set the Use proxy property to the correct proxy server.
  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. On the Event tab:
    1. Choose the type of object to be monitored.
    2. Select the property, the action, and the value to monitor.
    3. To define another event, click + to the right of any event.
    4. To delete an event, click - to the right of the event you want to delete.
    For example, to send a notification when the state of a job changes to Retained, select Current job state, Changes to, and Retained.
  10. On the Conditions tab:
    1. Select the property and the value that must be satisfied before any notifications are sent.
    2. To define another condition, click + to the right of any event.
      To specify how the conditions are combined, select Any, All, or Custom.
    3. To delete a condition, click - to the right of the condition you want to delete.
    For example, to send a notification only when a child job is in the ProcessWebOrders workflow, specify two conditions:
    • Workflow = ProcessWebOrders
    • Job number like*.*

    To apply the conditions only when a job meets both of them, select All.

  11. 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 RestfulWebServiceSampleNotify REST web service notification.

Related information:

Web Services Enablement
Usage scenario for processing JSON orders with web services
RestfulWebServiceWF
RestfulWebServiceSample
RestfulWebServiceSampleNotify
Setting up to exchange data with web services
Using a REST web service to authenticate with an application
Installing a security certificate for a website
Setting up the system to use a proxy server
Parent topic: Web service notifications