HP Embedded Capture CLI Reference Guide

HP Embedded Capture (HP EC)

API Reference Guide

Version 1.3.0

Microsoft, Windows, and Windows NT are U.S. registered trademarks of Microsoft Corporation.

June 2014

Confidential computer software. Valid license from HP required for possession, use, or copying. Consistent with FAR 12.211 and

12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor’s standard commercial license.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

Table of contents

1 API Introduction ............................................................................................................................................ 1

1.1 Basic and Advanced modes ............................................................................................................................. 1

1.1.1 Basic API ..................................................................................................................................... 1

1.1.2 Advanced API .............................................................................................................................. 1

1.2 Accessing the API on a device (%API_URL%) .................................................................................................. 1

1.2.1 XML encoding ............................................................................................................................. 2

1.2.2 XSD validation ............................................................................................................................ 2

1.2.3 Response codes ......................................................................................................................... 2

2 API security .................................................................................................................................................. 3

2.1 Administrator and API accounts ...................................................................................................................... 3

2.1.1 Admin account ............................................................................................................................ 3

2.1.1.1 “apiuser” user account ......................................................................................... 3

2.1.2 Using the API without authentication ........................................................................................ 3

2.2 Basic access authentication ............................................................................................................................ 4

3 Compatible API .............................................................................................................................................. 5

3.1 Graph and job services ..................................................................................................................................... 5

3.1.1 Put job ........................................................................................................................................ 5

3.1.2 View job ...................................................................................................................................... 8

3.1.3 Delete job ................................................................................................................................. 10

3.1.4 Get files .................................................................................................................................... 11

3.1.5 Set purge settings .................................................................................................................... 12

3.2 Configuration services ................................................................................................................................... 13

3.2.1 Get device info .......................................................................................................................... 13

3.2.2 Get device status ...................................................................................................................... 14

3.2.3 Get solution info ....................................................................................................................... 15

3.2.4 Get solution status ................................................................................................................... 16

3.2.5 Wake up .................................................................................................................................... 17

3.2.6 Cancel scan ............................................................................................................................... 18

3.2.7 Reset Solution .......................................................................................................................... 19

3.3 Extensibility services ..................................................................................................................................... 20

3.3.1 Set button ................................................................................................................................ 20

3.3.2 Remove button ........................................................................................................................ 21

3.4 Accessibility services ..................................................................................................................................... 22

3.4.1 Set API password ..................................................................................................................... 22

iii

3.4.2 Block Embedded Capture UI .................................................................................................... 23

3.4.3 Unblock Embedded Capture UI ................................................................................................ 24

3.5 Logging services ............................................................................................................................................ 25

3.5.1 Enable log ................................................................................................................................. 25

3.5.2 Get log ...................................................................................................................................... 26

3.5.3 Disable log ................................................................................................................................ 26

4 Advanced API .............................................................................................................................................. 27

4.1 Graph and job services .................................................................................................................................. 27

4.1.1 Set graph .................................................................................................................................. 27

4.1.2 Append graph ........................................................................................................................... 32

4.1.3 View graph ............................................................................................................................... 33

4.1.4 Clear graph ............................................................................................................................... 34

4.1.5 Modify node .............................................................................................................................. 35

4.1.6 Delete node .............................................................................................................................. 36

5 Appendix I: API settings reference ................................................................................................................ 38

5.1 Navigation settings ....................................................................................................................................... 38

5.2 Scan settings ................................................................................................................................................. 38

5.3 Metadata and Custom options ...................................................................................................................... 39

5.4 Notifications .................................................................................................................................................. 39

5.5 Destinations ................................................................................................................................................... 40

6 Appendix II: Error codes ............................................................................................................................... 41

List of tables

Table 3-1 Put a new job ........................................................................................................................................................ 5

Table 3-2 View job ................................................................................................................................................................ 8

Table 3-3 Delete job ........................................................................................................................................................... 10

Table 3-4 Get files ............................................................................................................................................................... 11

Table 3-5 Set purge settings .............................................................................................................................................. 12

Table 3-6 Get device info .................................................................................................................................................... 13

Table 3-7 Get device status ................................................................................................................................................ 14

Table 3-8 ADF Status possible values ................................................................................................................................ 15

Table 3-9 Get solution info ................................................................................................................................................. 15

Table 3-10 Get solution status ........................................................................................................................................... 16

Table 3-11 Navigation status possible values ................................................................................................................... 17

Table 3-12 Wake up ............................................................................................................................................................ 17

Table 3-13 Device Status possible values ......................................................................................................................... 18

Table 3-14 Cancel scan ....................................................................................................................................................... 18

Table 3-15 Reset Solution .................................................................................................................................................. 19

Table 3-16 Set button ........................................................................................................................................................ 20

Table 3-17 Remove button ................................................................................................................................................ 21

Table 3-18 Set API Password ............................................................................................................................................. 22

Table 3-19 Block device ..................................................................................................................................................... 23

Table 3-20 Unblock device ................................................................................................................................................. 24

Table 3-21 Enable log ......................................................................................................................................................... 25

Table 3-22 Get log .............................................................................................................................................................. 26

Table 3-23 Disable log ........................................................................................................................................................ 26

Table 4-1 Set graph ............................................................................................................................................................ 27

Table 4-2 Append graph ..................................................................................................................................................... 32

Table 4-3 View graph .......................................................................................................................................................... 33

Table 4-4 Clear graph ......................................................................................................................................................... 34

Table 4-5 Modify node ........................................................................................................................................................ 35

Table 4-6 Delete node ........................................................................................................................................................ 36

Table 5-1 Notification email ............................................................................................................................................... 39

Table 6-1 API Error codes ................................................................................................................................................... 41

List of figures

Figure 3-1 Put job, Request payload example ..................................................................................................................... 6

Figure 3-2 View job, success response example ............................................................................................................... 10

Figure 3-3 Delete job, success response example ............................................................................................................. 11

Figure 3-4 Get files, response example (Applicable only for format=links) ..................................................................... 12

Figure 3-5 Set purge settings, request payload example ................................................................................................. 13

Figure 3-6 Set purge settings, success response example ............................................................................................... 13

Figure 3-7 Get device info, success response example ..................................................................................................... 14

Figure 3-8 Get device status, response example ............................................................................................................... 15

Figure 3-9 Get solution info, response example ................................................................................................................ 16

Figure 3-10 Get solution status, Response example ......................................................................................................... 17

Figure 3-11 Wake up, success response example ............................................................................................................. 18

Figure 3-12 Cancel scan, Success response example ........................................................................................................ 19

Figure 3-13 Reset solution, success response example ................................................................................................... 20

Figure 3-14 Extensibility services, Set button — request payload example ................................................................... 21

Figure 3-15 Extensibility services, Set button — success response example ................................................................. 21

Figure 3-16 Remove button, success response example .................................................................................................. 22

Figure 3-17 Set API password, request payload example ................................................................................................. 23

Figure 3-18 Set API password, success response example ............................................................................................... 23

Figure 3-19 Block Embedded Capture UI, success response example .............................................................................. 24

Figure 3-20 Unblock Embedded Capture UI, success response example ......................................................................... 24

Figure 3-21 Enable log, request payload example ............................................................................................................ 25

Figure 3-22 Enable log, success response example .......................................................................................................... 25

Figure 3-23 Disable log, success response example ......................................................................................................... 26

Figure 4-1 Set graph, request payload example ............................................................................................................... 28

Figure 4-2 Success response example ............................................................................................................................... 32

Figure 4-3 Append graph, success response example ...................................................................................................... 33

Figure 4-4 View graph, success response example ........................................................................................................... 34

Figure 4-5 Clear graph, response example ........................................................................................................................ 35

Figure 4-6 Modify node, request payload example ........................................................................................................... 36

Figure 4-7 Modify node, response example ...................................................................................................................... 36

Figure 4-8 Delete node, response example ....................................................................................................................... 37

1 API Introduction

The HP Embedded Capture (HP EC) Application Programming Interface (API) enables client applications integration that interacts with MFP devices to manage workflow and remote document capture. API services are provided as part of the professional services agreement for HP Embedded Capture 1.1 or higher versions.

1.1 Basic and Advanced modes

The Embedded Capture solution works with a set of FutureSmart and non-FutureSmart MFP devices. FutureSmart offers an advanced set of functionalities that can take advantage of all the power of Embedded Capture. Non-FutureSmart devices cover a subset of those functionalities (basic) with standard document capture capabilities like Scan, metadata (with restrictions), and certain navigation levels (2) that cover the majority of the use cases.

The API is divided into two categories: Basic and Advanced

1.1.1 Basic API

The Basic API is compatible with the entire fleet (FutureSmart and non-FutureSmart devices). API integrators do not need to distinguish between device models. The same API calls and URLs are available on both models.

1.1.2 Advanced API

The Advanced API extends the complexity and flexibility of workflows managed on a device, offering extra functionalities in addition to what the Basic API provides.

1.2 Accessing the API on a device (%API_URL%)

The Embedded Capture API is exposed throughout the MFP in specific URLs by using SSL (recommended).

Although it is possible to use the API in http mode without encryption, this is NOT recommended. Deployment of workflows with associated parameters (including passwords) will be transferred in plain text over the network, and may be exposed to unauthorized access.

Some API calls will send parameters by GET and others by POST. This is specified on each API definition table.

Section 1.1 Basic and Advanced modes 1

NOTE: Changes to the transport protocol — to use or stop using SSL — should be done during device

configuration (Embedded webserver). See the HP Embedded Capture Admin Guide for more information.

NOTE: For all API methods described in this document, URLs have been simplified by replacing the value

with %API_URL%

1.2.1 XML encoding

All API parameters are based on standard XML documents. The conventions used for this XML are the following:

●

PascalCase for elements

●

camelCase for attributes

Example:

1.2.2 XSD validation

Embedded Capture API is validated by an XSD schema that is available for downloading from the devices. Each API includes a “schema” section that helps obtain the XSD document in real time.

To identify any issues with content on a client PC, it is highly recommended that XSD schemas be used to validate the content before sending it to the API.

1.2.3 Response codes

Each API call response message will include a code and a descriptive message. The message description may change on future releases of HP Embedded Capture (HP EC).

TIP: Any client application using the response information may use the error codes in place of strings to

ensure future compatibility.

2 Chapter 1 API Introduction

2 API security

To avoid unauthorized access, all API calls can be password protected by the administrator. Protecting the API guarantees that the MFP cannot be accessed by any client PC or application that does not know the credentials to execute the API calls.

NOTE: It is highly recommended that the API be protected by setting the access control password.

2.1 Administrator and API accounts

2.1.1 Admin account

The admin account corresponds with the device administrator account credentials (admin). An MFP device needs to be protected with an administrator password so that advanced options, network settings, etc... (embedded webserver) can be accessed.

The administrator completes the following operations during the installation and normal setup of Embedded Capture:

●

setButton

●

removeButton

●

setApiPassword

●

put (silent mode)

●

resetSolution

It is, however, recommended that a different password be used for standard API calls. This is explained in the following sections.

2.1.1.1 “apiuser” user account

Setting up this account is optional, but highly recommended. Though once set, it is required for all API operations except the ones specified above (setButton, removeButton, setApiPassword, put (silent mode), resetSolution).

2.1.2 Using the API without authentication

If authentication is not used on the API, certain operations still require setup using an administrator password. This is due to the following standard device usage constraints:

●

setButton, removeButton, resetSolution:

Administrator user/password is required for execution of these calls. When the solution is installed from the administrator console, a default button is created, and this password is already used in a transparent way for the administrator (specified on the device list).

●

putSilent:

Administrator user/password is required to execute this call. Once the solution is installed, the administrator password is remembered by HP Embedded Capture. This is to avoid having to specify a password on the API "put (silent mode)" calls. If the device administrator password is changed, the Embedded Capture “cached” password must be refreshed using ONE of the following two options:

Section 2.1 Administrator and API accounts 3

◦

Execute any API call with basic authentication using admin user/password.

◦

From the administrator console, edit the admin password in all changed devices, and press the

Remove workflow button.

2.2 Basic access authentication

Embedded Capture uses Basic access authentication for any API operation requiring authentication. To transmit credentials through HTTP, this authentication must be used.

For detailed information about basic access authentication, refer to the following:

wiki/Basic_access_authentication

To log in with API user credentials, the user name must be “apiuser” and the password must be the one specified using the SetApiPassword operation.

http://en.wikipedia.org/

4 Chapter 2 API security

3 Compatible API

3.1 Graph and job services

3.1.1 Put job

Table 3-1 Put a new job

?api=jobs&method=put

POST Description Uploads new scan job (simple workflow) to target MFP. Uploading scan job in compatible mode

appends job to existing workflows on device. Uploading scan job with same filtering parameters as an existing one results in two jobs with same menu options displayed on control panel.

Authentication "admin" or "apiuser" basic authentication required for Silent jobs "put" operation. Optional in others.

Payload IN XML: Job details. Contains:

Navigation settings (optional (*))

Scan settings

Custom options

Metadata options

Notification

Destination

Response Code

Schema Request

200 OK — success

Response

(*) Silent job: If navigation settings element is not defined, job is considered silent. Silent job is scan&send workflow that executes immediately after put operation finishes; no user interaction is possible on device control panel. This is an example of typical use of TWAIN driver.

OUT If 200, XML response with job identifier.

If 400, XML response with error code.

400 Bad request

Error code -1: Product not licensed

Error code -3: Error parsing XML payload

Error code -10: Device is busy (silent mode)

Error code -11: Media size unsupported

Error code -12: Unexpected error

401 Unauthorized access — if basic authentication fails

411 Length required — if content length is not or is badly specified

500 Internal Server Error — if too many requests are active. Retry recommended.

?api=jobs&schema=put

?api=jobs&rschema=put

Section 3.1 Graph and job services 5

Figure 3-1 Put job, Request payload example

Destination examples

A scan job can be assigned any of the following destinations:

6 Chapter 3 Compatible API

●

Local

The Local destination saves scanned documents to the device hard drive. They are not sent out of the device, and can only be recovered through an API get operation.

●

FTP

●

Network folder

●

Success response example:

Section 3.1 Graph and job services 7

●

Error response example:

As an example, when two jobs with the same navigation filters “label A” and “label B” are uploaded, both will be visible under “label A.”

Label A: AAC

Label B: FULL EMAIL JOB

NOTE: See APPENDIX I for possible settings and default values.

3.1.2 View job

Table 3-2 View job

?api=jobs&method=view&jobId={jobId}

GET Description Retrieves the job details as they were set up on the put API call.

8 Chapter 3 Compatible API

If the ID is set to 0, returns the details of all the workflow jobs.

If the ID is non-zero, returns the details of the job corresponding to the specified id.

Table 3-2 View job (continued)

Payload IN -

Response Code 200 OK — success

Schema Request -

OUT If 200, XML response with job details.

If 400, XML response with error code.

400 Bad request:

Error code –2: Invalid job id.

Error code –5: Id does not correspond to a job.

401 Unauthorized access — if basic authentication fails.

500 Internal Server Error — if too many requests are active. Retry recommended.

Response

?api=jobs&rschema=view

Section 3.1 Graph and job services 9

+ 32 hidden pages