Using Web Services

Preparing RICOH ProcessDirector to receive web service requests

Before you can submit web services requests, you must create a RICOH ProcessDirector user and password for web services to use. Be sure that the user ID has the appropriate level of authority in RICOH ProcessDirector to do the actions provided in the web service. For the examples in this chapter, Operator authority is sufficient. If you are using Lightweight Directory Access Protocol (LDAP) for authentication, create a user in LDAP for web services to use. The LDAP user must belong to a group that has the appropriate level of authority in RICOH ProcessDirector.

Because all users must change their passwords the first time they log in, log in to the RICOH ProcessDirector user interface using the user ID that you created and change the password. If you have passwords set to expire after a given time period, you must log in and change this password as needed.

Preparing web service requests

When you create requests, keep these points in mind :

• The web services user must log in before doing any actions.

  To submit any web service requests, you must first use the GET /users/login web service to log in to RICOH ProcessDirector as the web service user and receive a credential token. That token must be included in the header of all the web service requests that you submit until you submit the POST /users/logout/{name} web service.

• Property names must be expressed in the database format, not in the user interface format.

  When you include a property name in a request, you must use the database property name. For example, if you want to use GET /objects/{objectType} to retrieve the Class value of a job, you insert Job.Class as the attribute value in the request. Database property names are available in the field help for each property, in the product help system, in results received from some of the web services, and in Database property names.

• Property values must be expressed in the database format, not in the user interface format.

  When you include a value in a query, you must make sure that it is a valid value. Usually, numerical fields require numerical values and text fields require text values. However, some properties have limited lists of values.

  Any property that provides a drop-down list can only accept certain values. In addition, the values that appear in those lists are not always the same values that are stored in the database. For example, in the user interface, the values for the Staple property include:

  • 2 at left
  • 2 at right
  • Top left
  • Top left vertical
  • Bottom left
  However, the database values are:
  • 2_at_left
  • 2_at_right
  • Top_left
  • Top_left_vertical
  • Bottom_left

  In web service requests, you must use the database value. The database values for properties are available in the product help system and in Database property names.

• Positional job properties must include the phase, step, and workflow names in that order following the property name. Enclose each of the three names in brackets.

  This example JSON string specifies a control file on a Linux system as the value of the Identify PDF control file job property (database name Job.IdentifyPDFControlFile):

  "Job.IdentifyPDFControlFile[Prepare][IdentifyPDFDocuments][PullPDFSample]":"/aiw/aiw1/testfiles/PullPDF.ctl"

  The job property is on the IdentifyPDFDocuments step in the Prepare phase of the PullPDFSample workflow.