HP Embedded Capture (HP EC) API Reference Guide Version 1.3.
© Copyright 2014 Hewlett-Packard Development Company, L.P. 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.
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 ....
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 ............................................................
List of tables Table 3-1 Put a new job ........................................................................................................................................................ 5 Table 3-2 View job ................................................................................................................................................................ 8 Table 3-3 Delete job ...................................................................................................................
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 .............................................................................................................
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.
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 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).
◦ Execute any API call with basic authentication using admin user/password. or ◦ 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: http://en.wikipedia.
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.
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. ● Email ● FTP ● Network folder ● Success response example: Section 3.
● 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. If the ID is set to 0, returns the details of all the workflow jobs.
Table 3-2 View job (continued) Payload IN - OUT If 200, XML response with job details. If 400, XML response with error code. Response Code 200 OK — success 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. Schema Request Response ?api=jobs&rschema=view Section 3.
Figure 3-2 View job, success response example 3.1.
Table 3-3 Delete job (continued) GET Description Removes a job by changing its status to “cancelled.” Deleted jobs will still appear in an API view request, but with a cancelled status until they get purged by the Embedded Capture garbage collector. If the jobId is set to 0, all jobs in the graph are removed. If jobId is non-zero, only the specified job is removed. Payload IN — OUT If 200, XML response with code 0. If 400, XML response with error code.
Table 3-4 Get files (continued) OUT If 200, XML response with files or xml with direct download links. If 400, XML response with error code. Response Code 200 OK – success 400 Bad request: Error code -2: Invalid job id Error code -5: Id does not correspond to a job Error code -6: Error loading job information Error code -7: Error creating zip 401 Unauthorized access – if basic authentication fails 500 Internal Server Error – if too many requests are active. Retry recommended.
Table 3-5 Set purge settings (continued) Payload IN XML Configuration parameters OUT If 200, XML response with code 0 If 400, XML response with error code Response Code 200 OK – success 400 Bad request: Error code -3: Error parsing xml payload 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.
Table 3-6 Get device info (continued) Payload Response Code ◦ Device Family (“FutureSmart” or “Non-FutureSmart”) ◦ Hostname ◦ Tray width (mm) ◦ Tray height (mm) IN — OUT If 200, XML response with device info. 200 OK — success 401 Unauthorized access — if basic authentication fails 500 Internal Server Error — if too many requests are active. Retry recommended. Schema Request — Response ?api=config&rschema=getDeviceInfo Figure 3-7 Get device info, success response example 3.2.
Table 3-7 Get device status (continued) Response Code 200 OK — success 401 Unauthorized access — if basic authentication fails 500 Internal Server Error — if too many requests are active. Retry recommended.
Table 3-9 Get solution info (continued) Payload Response Code IN — OUT If 200, XML response with solution info. 200 OK — success 401 Unauthorized access — if basic authentication fails 500 Internal Server Error — if too many request are active. Retry recommended. Schema Request — Response ?api=config&rschema=getSolutionInfo Figure 3-9 Get solution info, response example 3.2.
Figure 3-10 Get solution status, Response example Table 3-11 Navigation status possible values Code Meaning 0 Unknown 1 Navigating 2 Scanning 3 Processing 4 Idle 3.2.5 Wake up Table 3-12 Wake up ?api=config&method=wakeup GET Description Wakes up device if in standby mode. If device is in standby mode, starting the operation with Embedded Capture is delayed by the wake up process.
Figure 3-11 Wake up, success response example Table 3-13 Device Status possible values Code Meaning Explanation 1 OK Device is awake 0 KO Device is not awake -1 Initializing Device is still booting 3.2.6 Cancel scan Table 3-14 Cancel scan ?api=config&method=cancelScan GET Description Cancels/interrupts the scanning process on the device.
Figure 3-12 Cancel scan, Success response example 3.2.7 Reset Solution Table 3-15 Reset Solution ?api=config&method=resetSolution GET Description This function restores the solution as if it was newly installed on a clean device: ◦ Removes all process data such as scanned files, pending jobs etc. ◦ Restores default solution settings: Deactivates logs, removes icon, resets purge settings and API passwords. WARNING! Removing the solution button will cause all access control configuration to be lost.
Figure 3-13 Reset solution, success response example 3.3 Extensibility services 3.3.1 Set button Table 3-16 Set button ?api=extensibility&method=setButton POST Description Creates or modifies the Home screen button on the device. If any fields are not specified, a default value will be used. If Embedded Capture had no button (silent mode), it will change to a non-silent mode (interactive) after the button creation.
Figure 3-14 Extensibility services, Set button — request payload example Figure 3-15 Extensibility services, Set button — success response example 3.3.2 Remove button Table 3-17 Remove button ?api=extensibility&method=removeButton GET Description Removes a Home screen button on the device. Attention: Removing the solution button will cause all access control configuration to be lost (authentication agent, embedded authentication...).
Table 3-17 Remove button (continued) 500 Internal Server Error – if too many requests are active. Retry recommended. Schema Request — Response ?api=common&rschema=default Figure 3-16 Remove button, success response example 3.4 Accessibility services 3.4.1 Set API password Table 3-18 Set API Password ?api=accessibility&method=setApiPassword POST Description Sets a password for API authentication. By default, password is not set, and therefore API is not protected.
Table 3-18 Set API Password (continued) Schema Request ?api=accessibility&schema=setApiPassword Response ?api=common&rschema=default Figure 3-17 Set API password, request payload example Figure 3-18 Set API password, success response example 3.4.2 Block Embedded Capture UI Table 3-19 Block device ?api=accessibility&method=block GET Description Disables the Embedded Capture Home screen button on the control panel.
Figure 3-19 Block Embedded Capture UI, success response example 3.4.3 Unblock Embedded Capture UI Table 3-20 Unblock device ?api=accessibility&method=unblock GET Description Reactivates solution button on device control panel. After unblocking Embedded Capture UI, users will be able to execute workflows normally.
3.5 Logging services 3.5.1 Enable log Table 3-21 Enable log ?api=logging&method=enable POST Description Method that enables the Logging Service during a specified number of days. If specifying 0 Days, the Logging Service will be enabled permanently. NOTE: Take into consideration that enabling the log permanently will shorten the printer’s hard disk lifetime, and may also affect performance.
3.5.2 Get log Table 3-22 Get log ?api=logging&method=get GET Description Method that retrieves the logs of Embedded Capture. The logs are returned in a text file that is downloaded by http protocol. Payload IN — OUT If 200, response with the file Response code 200 OK — success 401 Unauthorized access – if basic authentication fails 500 Internal Server Error – if too many requests are active. Retry recommended. Schema Request — Response ?api=common&rschema=default 3.5.
4 Advanced API The Advanced mode API is only available on FutureSmart devices. To distinguish between device models when using Advanced API calls in a mixed fleet, it is highly recommended that you use the getDeviceInfo API call ( element) on Compatible mode to filter and choose the devices that will accept the advanced calls between the ones that would reject them. 4.1 Graph and job services 4.1.
Figure 4-1 Set graph, request payload example 28 Chapter 4 Advanced API
Section 4.
30 Chapter 4 Advanced API
Section 4.
Figure 4-2 Success response example NOTE: See section Appendix I to check the settings possible and default values. 4.1.2 Append graph Table 4-2 Append graph ?api=graph&method=append&parentID={nodeId} POST Description Appends a new subgraph on target MFP existing workflow graph. If parent node Id is not provided, the new graph will be appended to the root node on the device and will appear as a new menu option when accessing the first EC screen.
Table 4-2 Append graph (continued) 411 Length required – if content length is not or is badly specified 500 Internal Server Error – if too many requests are active. Retry recommended. Schema Request ?api=graph&schema=append Response ?api=common&rschema=default Request payload example: NOTE: See the Request payload on the API “set” graph method. Figure 4-3 Append graph, success response example 4.1.
Figure 4-4 View graph, success response example 4.1.4 Clear graph Table 4-4 Clear graph ?api=graph&method=clear&includeScheduled={boolean} GET Description Clears the full graph from the device. If includeScheduled is not set, this call has no effect on processes already scheduled for execution. includeScheduled(optional): Not supported in EC 1.2.0; its default value is false.
Table 4-4 Clear graph (continued) 400 Bad request Error code -2: Invalid request parameters Error code -10: Device is busy 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. Schema Request — Response ?api=common&rschema=default Figure 4-5 Clear graph, response example 4.1.
Table 4-5 Modify node (continued) 411 Length required – if content length is not or is badly specified 500 Internal Server Error – if too many requests are active. Retry recommended. Schema Request ?api=graph&schema=modifyNode Response ?api=common&rschema=default Figure 4-6 Modify node, request payload example Figure 4-7 Modify node, response example 4.1.
Table 4-6 Delete node (continued) Error code -5: Id not corresponding to a valid node Error code -10: Device is busy (silent mode) 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 Schema Request Response — ?api=common&rschema=default Figure 4-8 Delete node, response example Section 4.
5 Appendix I: API settings reference The following completes the information provided in the API XSD documents that are more related to the structure and content type. Depending on the device model, some parameters may vary, and are subject to device specific capabilities outlined in the specifications. 5.
NAME POSSIBLE VALUES Type “jpg”, “pdf”, “tiff”, “mtiff”, “xps” Color “color”, “bw”, “grayscale” Resolution “75”, “150”, “200”, “300”, “400”, “600” Duplex boolean Source “auto”, “adf”, “flatbed” MediaSize “auto”, “letter”, “legal”, “exec”, “a3”, “a4”, “a5”, “b5”, “b5_env”, “j_double_postcard”, “dl_env” PageContent “text”, “graphic”, “mixed” QualityMode “small”, “medium”, “large” Sharpness “1”, “2”, “3”, “4”, “5” Darkness “0”, “1”, “2”, “3”, “4”, “5”, “6”, “7”, “8” BackgroundRemoval “1”
5.
6 Appendix II: Error codes The following table provides a summary of all possible API error codes returned when something does not work as expected, or in some cases, to inform of a situation needing attention from the user/operator side, possibly requiring a retry of the failed operation. The generic error message indicates the category of the error, but the description is different for each API call, providing more detailed information of each case.
