HP Embedded Capture CLI Reference Guide
Contents
1. 3 RW alle E 3 2 1 1 1 apiuser user account 3 2 1 2 Using the API without authentication 3 2 2 BASIC access AUN MEI UIC eege 4 SE SEENEN 5 3 1 Graph and job services Xm 5 J I WG JOD BEE 5 SAVIN OD EE 8 D3 CUETO e e EEN 10 MAGELES a D N NN N N N N N 11 3 1 5 Set purge settings 12 3 2 Configuration services L U R 13 S TG6EdEVI NTO EE 13 ZZ Get E G SCIIS uuu S NA I N NN RU NE 14 3 2 3 Get solution INTO 15 3244 GET solution stats LLL tnt n nn vinas K 16 ILE LI e EE 17 3 2 0 Cancel SCAN E 18 EN RESet S0 WI aa D S V O N 19 3 3 Extensibility Services D LP _ N O UR MU UU MD EIE VE 20 E Sel bill RNC ae ei au A vies vess ussenes 20 3 32 REMOVE DUTTON N N S N N N N N O N N N MS 21 3 4 AECOSSIDIIDUSBEUICOS S V N NN N N N N N EN EN N N 22 3 4 1 Set API password PM 22 3 4 2 Block Embedded Capture Ul L LU LULU Een 23 3 4 3 Unblock Embedded Capture Ul2. 24 53 5 LOggING SCTYICOS ERE e 25 A Ree S a e 25 AS ZU e uuu ulus 26 3 5 3 DODIES ka a N N NN D S 26 GAGA F s A DN N E E EAE Nn O 27 DN Beien CUA FOO E le van N m mju 27 AT Seta E BE 27 A 2 Append graD EE 32 AI Vi W Di uuu u kuu umu nD u ns 33 414 Clear e u N N NN N N N NNI 34 45 Modi io ss uuu dugas 35 PE Vg GD ot e TE 36 5 Appendix i API settings reference 38 5 1 NaVid ti0fi tili0G sa xa Ass ni ms 38 5 2 SCAN SENOS ose e 38 5 3 Metadata and Custom options 39 S d IN OUI CALI OINS sa an anna nn m nn IU Ud DMUdUE 39 SE 40 6 ASDENd i Error ep deu ii ii iii ai ia 41 List of tables Table 3 1 Table 3 2 Table 3 3 Table 3 4 Table 3 5 Table 3 6 Table 3 7 Table 3 8 Table 3 9 Table 3 10 Table 3 11 Table 3 12 Table 3 13 Table 3 14 Table 3 15 Table 3 16 Table 3 17 Table 3 18 Table 3 19 Table 3 20 Table 3 21 Table 3 22 Table 3 23 Table 4 1 Table 4 2 Table 4 3 Table 4 4 Table 4 5 Table 4 6 Table 5 1 Table 6 1 Mie e DD u u u uu uuu NN 5 VIEW JOD E 8 Delete JOD a a N M S 10 EE N N N AN 11 Set purge settings
3. 25 Disable log success response example 26 Set graph request payload example uu u 28 SHEET 32 Append graph success response example aa 33 View graph success response example 34 Clear graph response example 35 Modify node request payload example 36 Modify node response example Uu aaa 36 Delete node response example 37 1 APliintroduction The HP Embedded Capture HP EC Application Programming Interface API enables client applications integration thatinteracts 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
4. 18 Cancel scan Success response example 19 Reset solution success response example 20 Extensibility services Set button request payload example 21 Extensibility services Set button success response exampPle 21 Remove button success response example 22 Set API password request payload example 23 Set API password success response example 23 Block Embedded Capture Ul success response example 24 Unblock Embedded Capture Ul success response example 24 Enable log request payload example 25 Enable log success response example
5. Response version 1 1 0 xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocatione SAPI URLS7 apisgraphiamp rschemaeview OperationStatus lt Code gt 0 lt Code gt Message Request Completed lt Message gt lt OperationStatus gt Content Graph MenuOption name 001 IypicalGrapn disablelnactivitylimecute False ide deaca780 f7cf A7el a3f5 B225b7f7305615 Description Select an option lt Description gt Buttons Button action Back label Back gt Butron actione Exir lahel Exit gt lt Buttons gt lt Edges gt lt RootParent gt Parent ide 7361fa2d 6c6f 4af6 9519 83f0b167e16c gt lt Edges gt lt MenuOption gt See SetGraph payload lt Dialog creen name Node disableInactivityTimeout False id 75 6lfa d c f daf6 93515 83f bl67el6c Description Message Description Buttons Button action Back label Back Button action Exit label Exit Button action Next l b l N ext gt Burtons Message Document file type Scan ScanBasicOptions FileType talt br sgt 5canned pages 1 Scan ScanNumPages talt br agt Scanned files W Scan FileCount amp alt br amp gt amp lt br amp gt amp lt WHILE typee process scope cycle delimiter alt br agt agt Process Name t alt br a gt 4 Process Result 1 Process BesultMessage talt br sgt Files Process FileCount 4 4 lt br segt alt WHILEsgt lt Me
6. perationStarus Content gt lt Response gt 3 4 3 Unblock Embedded Capture UI Table 3 20 Unblock device amp API UHL api accessibilit y xmethod unblock GET Description Payload Response Code Schema Reguest Response Reactivates solution button on device control panel After unblocking Embedded Capture Ul users will be able to execute workflows normally IN OUT If 200 XML response with code 0 If 400 XML response with error code 200 OK success 400 Bad request Error code 10 Device is busy Error code 12 Unexpected error 401 Unauthorized access if basic authentication fails 500 Internal Server Error if too many requests are active Retry recommended amp API URLS api common amp rschema default Figure 3 20 Unblock Embedded Capture Ul success response example xml version 1 0 encoding UTF 8 Response version 1 1 0 xmlns xai http www w3 o0rg 2001 XMLSchema instance xsi noNamespaceS5chemaLocation AFI URHL api common amp amp rschema default lt OperationStatus gt lt Code gt O0 lt Code lt Message gt Reqnuest Completed lt Message gt lt OperationStatus gt lt Content gt Response Chapter 3 Compatible API 3 5 Logging services 3 5 1 Enable log Table 3 21 Enable log amp API URL S api logging amp method enable POST Description Method that enables the Logging Service during a specified number of days If specifying 0 Days
7. Ap HP Embedded Capture HP EC API Reference Guide Version 1 3 0 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 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 RR OCA K an nn nn os im 1 1 1 Basic and Advanced modes 1 Fl TE SUC RE 1 Z Advanced WE 1 1 2 Accessing the API on a device API_URL 1 UNE ME ACUN 6 A a Sus ss 2 1 22 XSD e EE 2 12 5 OSD OSC COC EEN 2 Be YT P REENEN 3 2 1 Administrator and API accounts
8. Capture e setButton e removeButton e setApiPassword e put silent mode e 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
9. DefaultValue lt MinValue gt 5 lt MinValue gt lt MaxValue gt 15 lt MaxValue gt CustomBeqularExpression lt Style gt lt IsPassword gt False lt 1lsPassword gt PossibleValues PossibleValue value 1 lt PossibleValue gt PossibleValue value 2 lt PossibleValue gt PossibleValue value 3 lt PossibleValue gt PossibleValue value 4 lt PossibleValue gt PossibleValues lt Formoption gt FormOption key metadataPassword name Metadata Password type Text gt lt Visibility gt ReadwWrite lt Visibility gt Description Example of password lt Description gt DefaultValue random Pass lt DefaultValue gt lt MinValue gt 5 lt MinValue gt lt MaxValue gt 15 lt MaxValue gt CustomBeqularExpression lt Style gt IsPassword True c IsPassword FormoOption FormOption key metadataRadioList name Metadata Radio List type RadioList gt lt Visibility gt ReadwWrite lt Visibility gt Section 4 1 Graph andjob services 29 lt Description gt xampl of Radio List lt Description gt lt DefaultValue gt value 2 lt Defaultvalua gt h gt lt MinValue gt 5 lt MinValue gt lt MaxValue gt 15 lt MaxValue gt lt CustomRegularExpression gt lt style gt lt IsPassword gt False lt IsPassword gt lt PossibleValues gt lt PossibleValue gt value 1 lt PossiblevValue gt lt PossibleValue gt value 2 lt PossibleValue gt lt PossibleValue gt value 3 lt PossibleValue gt lt PossibleV
10. lt BasicOptions gt lt BackgroundCleanup gt Value0 lt BackgroundCleanup gt lt BlankImageRemovalModeroff lt Blank mageRemovalMod gt lt ColorDropoutMode gt Off lt ColorDropoutMode gt lt ColorMode gt Color lt ColorModa gt lt Contrast djustment gt Valued lt Contrast djustment gt CropMode Off CropMode customLenqgth 2 9 CustomLength CustomWidth 2 16 Customwidth lt Darkness djustment gt Valvuel lt Darknessadjustment gt lt DuplexFormat gt Flip lt DuplexFormat gt lt FileType gt Jpeg lt FileType gt lt Job ssemblyMode gt Off lt JobAssemblyHode gt Media Orientation gt Landscape lt Media rient tion gt lt Media ize gt A4 lt MediaSize gt lt MediaSource gt Flatbed lt MediaSource gt lt MediaWeightAdjustment gt NotApplicable lt MediaWeightAdjustment gt lt MisfeedDetectionMode gt Off lt MisfeedDetectionMode gt lt OutputQuality gt Medium lt OutputQuality gt lt FlexMode gt Simplex lt PlexMode gt lt PreviewMode gt Off lt PreviewMode gt lt ProgressDialogMode gt 0ff lt ProgressDialogMode gt lt R solution gt Res150x150 lt Resolution gt lt Sharpness djustment gt Valued lt Sharpn ess djustm ent gt lt TextPhotoOptimization gt Mir dl lt TextPhotoOoptimization gt lt Basic ptions gt lt FileOptions gt lt PdfEncryptionPassword gt lt OcrLanguage gt NotApplicable lt OcrLanguage gt lt PdtCompressionMode gt Normal lt PdfCompressionMode gt TiffCompress
11. lt Visibility gt ReadwWrite lt Visibility gt Description Example of IP Validation lt Description gt DefaultValue 15 16 17 18 DefaultValue MinValue 2 147484E 09 MinValue xMaxValue 2 147484E 09 MaxValue zCustomBeqularExpression 25 0 5 2 0 4 0 9 01 0 9 0 9 2 V 25 0 5 2 0 4 0 9 01 0 9 0 9 N 25 0 5 2 0 4 0 9 01 0 9 0 9 N 25 0 5 2 0 4 0 9 01 O 9 0 9 x CustomkRegularExpression gt lt Style gt lt IsPassword gt False lt IlsPassword gt FormOption FormOption key metadataRegExprDNI name Custom Expr DNI type Text gt lt Visibility gt ReadwWrite lt Visibility gt lt Descripticn gt Example of DNI Validation lt Description gt lt DefaultValue gt 12345678A lt DefaultValue gt MinValue 2 147484E 09 MinValue MaxValue 2 147484E 059 MaxValue CustomBeqularExpression 0 9 8 a zA Z 5z CuatomBeqularExpression lt Style gt IsPassword False IsPassword FormOption 28 Chapter 4 Advanced API FormOption key metadataMail name Metadata Mail type Text gt lt Visibility gt ReadwWrite lt Visibility gt Description Example of mail lt Descripticn gt DefaultValue albertv hp com DefaultValue lt MinValue gt 2 147484B 09 lt MinValue gt tMaxValue gt 147484E 09x MaxValue gt CustomkegularExpression gt a zA 20 9 a zA 20 9 a zA 20 9 2 4 5 CustomBequla
12. perationStarus lt Content gt Besponse 4 1 5 Modify node Table 4 5 Modify node SAPI URL api graph8method modifyNode8includeScheduled fboolean POST Description Payload Response Code Modifies a graph node on the target MFP By including scheduled nodes they can be modified in order to change their parameters before they are executed includeScheduled optional Not supported in EC 1 2 0 its default value is false IN XML Node OUT If 200 XML response with code 0 If 400 XML response with error code 200 OK success 400 Bad request Error code 3 Error parsing xml payload Error code 5 Id not corresponding to a valid node Error code 8 Unsupported scan settings if it is a scan node Error code 10 Device is busy Error code 12 Unexpected error 401 Unauthorized access if basic authentication fails Section 4 1 Graph and job services 35 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 SAPT URL api graph8schema modifyNode Response amp API URLS api common amp rschema default Figure 4 6 Modify node request payload example lt xml version 1 0 ncodin UTF 8 gt Request versiom l l 0 gt Form name Modified Metadata Name id fel2s3dc 902c 4f45 aled 7411001le6b64 gt lt Title gt Modified Metadata Titl
13. Retry recommended Schema Request Response amp API URLS api config amp rschema getSolutionlnfo Figure 3 9 Get solution info response example xml version 1 0 encoding UTF 8 Response version 1 1 0 xmlns xsi http www w3 o0rg 2001 XMLSchema instance zxsi noNamespaceSchemaLocation API URL api contig amp amp rschema getSolutionInfo OperationStatus zCode c Code zxMessage Request Completedc Message lt OperationsStatus gt lt Content gt lt Solutioninto gt Version gt l l 0 lt Version gt lt IsLicensed gt trues lsLicensed gt IsBlocked falsec IsBlocked lt LogLevel gt ralls LogLevel gt lt AdvancedWorkflowSupport gt stroue lt AdvancedWorkflowSupport gt lt SolutioniInfo gt lt Content gt z Response 3 2 4 Get solution status Table 3 10 Get solution status es ee S S S S LLLILLLLLLLLLLLLLLLLLLLLILLLLLLLLLLLLLLLL LLLLLL LLLLLLLLLLLLLLLLLLILLLLLLLLLLLILLLLLLLIILILLIILLLLLLLLLLLLLLILLLBILILL LLLILLLIULLLLLLLLLLLLLLLLLLLLIO SAPI URL api config amp method getSolutionStatus GET Description Returns device status information Information returned includes Operating status Navigating scanning processing unknown Error condition indicating whether the status is at the moment interrupted by some error condition For example if there is no paper on ADF Payload IN OUT If 200 XML response with solution status Response Code 200 OK success 401 Unauthorized acces
14. control configuration to be lost authentication agent embedded authentication Upon creating a new button the application access will need to be reconfigured Requires basic authentication with device admin credentials IN OUT If 200 XML response with code 0 If 400 XML response with error code 200 OK success 400 Bad request Error code 10 Device is busy Error code 12 Unexpected error 401 Unauthorized access if basic authentication fails Section 3 3 Extensibility services 21 Table 3 17 Remove button continued 500 Internal Server Error if too many requests are active Retry recommended Schema Request Response SAPI URLS api ccommon amp rschema default Figure 3 16 Remove button success response example lt xml version 1 0 encoding UTF 8 Response version 1 1 0 xmlns xsi http www w3 o0rg 2001 XMLSchema instance xsi noNamespaceSchemaLocation API URL api common amp amp rschema default gt lt OperationStatus gt lt Code gt 0 lt Code gt lt Mezsage gt Reguest Completed lt Message gt lt OperationStatus gt lt Content gt lt Response gt 3 4 Accessibility services 3 4 1 Set API password Table 3 18 Set API Password SAPI URL S api accessibility amp amethod setApiPassword POST Description Sets a password for API authentication By default password is not set and therefore API is not protected For security reasons it is recommended that API
15. xmlns xsi http www w3 o0rg 2001 XMLSchema instance xsi noNamespaceSchemaLocation amp API URL api common amp amp rschema default perationStatus Code 0 Code Message Request Completed Message OperationStatus Content gt lt Response 3 4 2 Block Embedded Capture UI Table 3 19 Block device SAPI UnRL api accessibility method block GET Description Disables the Embedded Capture Home screen button on the control panel This is highly recommended before performing administration tasks that need to change workflows structure and may affect the user scanning Payload IN 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 10 Device is busy Error code 12 Unexpected error 401 Unauthorized access if basic authentication fails 500 Internal Server Error if too many requests are active Retry recommended Schema Request Response SAPI URIL apiscommon amp rschema default Section 3 4 Accessibility services 23 24 Figure 3 19 Block Embedded Capture UI success response example xml version 1 0 encoding UTF 8 2 lt Kesponse veraion 1 1 0 xmlns xsi http www wo org 2001 AMLSchema instance xsi noNamespaceSchemaLocation API URL api common kamp rschema de fault gt lt OperationsStatus gt Code U Code lt Message gt Reguest Completed Message
16. 2 Configuration services 19 Figure 3 13 Reset solution success response example lt xml version 1 0 encoding UTF 8 Response version 1 1 0 xmlns xsi http www w3 o0rg 2001 XMLSchema instance xsi noNamespaceSchemaLocation APT URL api common amp rschema default xOperationStatus lt Code gt 0 lt Code lt Message gt Request Completed lt Message gt z OperationS5tatus zContent lt Responge gt 3 3 Extensibility services 3 3 1 Set button Table 3 16 Set button SAPI URL S api extensibility amp 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 Icon requirements Family Ty Size width x height NFsmartl G l06xl4S9px NFsmart40 60x55px NFsmart 48x44px FSMART 66x66px Authentication Requires basic authentication using device admin credentials Payload IN XML button details OUT If 200 XML response with code 0 If 400 response with error code Response Code 200 OK success 400 Bad reguest Error code 3 Error parsing xml payload 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 m
17. E 12 GEL CO IME NN N N N N N NA A veneer carsonenans 13 SU CCC Km IG a K V A N D N N MM 14 ADF Status possible values 15 EES ESCHER 15 Ee d leie EE 16 Navigation status possible values 17 W k TT EE 17 Device Status possible values 18 CAA GOV Std nn pin pi EEE a 18 FS SEE SVEN ON so aa NN nn m s U 19 EE 20 REMOVE DUO is ap nj nj aries 21 ei E e E 22 O We EH 23 Bi e Cola KCC VIGO EE 24 bl o E 25 fidet EE 26 IS AD LC ou E 26 EE 27 n pe qipi u O V N N N NN NN N N s 32 EE eegener 33 EENEG 34 MOV DITS RR x 35 M e u Q 36 Ketten ET 39 EELER 41 vi List of figures Figure 3 1 Figure 3 2 Figure 3 3 Figure 3 4 Figure 3 5 Figure 3 6 Figure 3 7 Figure 3 8 Figure 3 9 Figure 3 10 Figure 3 11 Figure 3 12 Figure 3 13 Figure 3 14 Figure 3 15 Figure 3 16 Figure 3 17 Figure 3 18 Figure 3 19 Figure 3 20 Figure 3 21 Figure 3 22 Figure 3 23 Figure 4 1 Figure 4 2 Figure 4 3 Figure 4 4 Figure 4 5 Figure 4 6 Figure 4 7 Figure 4 8 Put job Request payload exam
18. 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 amp API URLS api common amp rschema default 3 5 3 Disable log Table 3 23 Disable log KH amp API UHL api logging8method disable GET Description Disable the Logging Service Payload IN OUT If 200 XML response with code 0 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 amp API URL S api common amp rschema default Figure 3 23 Disable log success response example lt xml version 1 0 encoding UTF 8 Response versaion 1 1 0 xmlnsa xs3i http www w3 o0rg 2001 XMLSchema instance xsi noNamespaceSchemaLocation APT URLS api common amp amp rschema default OperationStatus zCode z Code zMessage Request Completed lt Message gt z OperationStatus zContent gt lt Response 26 Chapter 3 Compatible API 4 Advanced API The Advanced mode APlis only available on FutureSmart devices To distinguish between device models when using Advanced API cal
19. Response SAPI URL S api common amp rschema default Figure 3 5 Set purge settings request payload example lt xml version 1 0 encoding UTF 8 gt lt Request version 1 1 0 gt lt ExpirationTime gt 10000 lt ExpirationTime gt lt CollectorPeriod gt 3600 lt CollectorPeriod gt lt Reguest gt Figure 3 6 Set purge settings success response example lt Jxml version 1 0 encoding UTF 8 Response version 1 1 0 xmlns xai http www w3 o0rg 2001 XMLSchema instance xsi noNamespaceSchemaLocation SAPT URL api common amp rschema default gt OnerationStatus zCode c Code lt Message gt Request Completed lt Message gt lt OperationsStatus gt lt Content gt Response 3 2 Configuration services 3 2 1 Get device info Table 3 6 Get device info SAPI URL api config8method getDevicelnfo GET Description Gets the device information Information returned includes Device model Device IP Section 3 2 Configuration services 13 Table 3 6 Get device info continued Device Family FutureSmart or Non FutureSmart Hostname Tray width mm Tray height mm Payload IN OUT If 200 XML response with device info 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 amp API URLS api config amp rsche
20. URL method getFiles amp amp jobId jobId tamp page 6 lt Document gt lt Content gt lt Response gt 3 1 5 Set purge settings Table 3 5 Set purge settings amp API UHL api jobs8 method setPurgeSettings POST Description Sets the Expiration time and the Garbage Collector period for dynamic scan jobs in the MFP These variables control the time that a job will remain in the device Expiration time corresponds to the amount of time that dynamic jobs remain in the device Collector period corresponds to time interval within subseguent cleanup operations of expired jobs Collector period must be smaller than Expiration time Both values are defined in seconds By default Collector period is set to 30 Minutes and Expiration Time to 12 Hours Collector period valid Range is between 1800 sec 30 minutes and 84000 sec 24 hours Expiration Time is not constrained 12 Chapter3 Compatible API 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 reguest 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 Schema Request SAPI URLS api jobs amp schema setPurgeSettings
21. 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 http mfp ip address hp device hp extensibility ec clientservices api parameters 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 ET 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 ET 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 e PascalCase for elements e camelCase for attributes Example DestinationElement typeAttribute email metadata ttribute true gt 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 URLS5 api jobs amp schema put 1 2 3 Response codes
22. lt Media ize label Media Size lt Visibility gt RaadOnly lt Visibility gt lt Defaultvalue gt A3 lt Defaultvalue gt lt M di Siz gt PdfCompressionMode label Pdf Compression Mode gt lt Visibility gt ReadWrite lt Visibility gt lt DefaultValue gt Normmal lt DefaultValue gt lt PdfCompressionMode gt TiffCompressionMode label Tiff Compression Mode gt lt Visibility gt ReadWrite lt Visibility gt DefaultValue NotApplicablac DefaultValue lt Tiffcompr ssionMode gt cXpsCompressionMode label XPS Compression Mode lt Visibility gt ReadWrite lt Visibility gt 30 Chapter4 Advanced API lt DefaultValue gt NotApplicable lt DefaultValue gt XpsCompressionMode lt OcrLanguage label Ocr Language lt Visibility gt ReadWrite lt Visibility gt lt DefaultValue gt NotApplicable lt DefaultValue gt lt OcrLanguage gt lt PdfEncryptionPassword label Pdf Encryption Password gt lt Visibility gt ReadWrite lt Visibility gt lt DefaultValue gt MyPass lt DefaultValue gt lt PdfEncryptionP ssword gt lt ScanSettings gt lt Edges gt lt Parent id 2 5a1253dc 902c 4f49 a0ed 7411001e6b64 lt Edges gt lt Scan0ptionsScreen gt lt ScanProcess name Node id cafeod914 2468 4333 89ac 094ed79 467b gt lt Settings gt ShowProgressScreen Truec ShowProgressScreen lt WaitingText gt Scamning lt WaitingText gt lt ShowWai ting mage gt True ShowWaitingImage gt lt Settings gt
23. protection be used to avoid unauthorized access to scanned documents or workflows information Once API password is set all operations will require basic authentication with credentials Username apiuser Password the password defined Alternatively device admin user password can be used for API authentication To unset API password an empty string must be unspecified in payload xml Authentication Requires basic authentication with device admin credentials Payload IN XML Containing the password of the administrator of the API 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 Chapter 3 Compatible API Table 3 18 Set API Password continued Schema Request amp API URL api accessibilitty amp schema setApiPassword Response SAPI URL apiscommon amp rschema default Figure 3 17 Set APl password request payload example lt xml varsionz 1 0 ancodings UTF B 5 Request version 1 1 0 gt lt ApiPassword gt API Password lt ApiPassword gt lt Reguest gt Figure 3 18 Set API password success response example lt xml version 1 0 encoding UTF 8 Response version 1 1 0
24. 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 Payload IN XML Configuration parameters OUT If 200 XML response with code O 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 Schema Request API URL api logging amp schema enable Response SAPI URL S api common amp rschema default Figure 3 21 Enable log request payload example lt xml version 1 0 encoding UTF 8 gt lt Request version 1 1 0 gt lt NumberOfDays gt 2 lt NumberOfDays gt lt Reguest gt Figure 3 22 Enable log success response example xml versionz 1 0 encoding UTP 8 gt Response versionz 1 1 0 xmlns xsis http www w3 org 2001 XMLSchema instance amp si noNamespaceSchemaLocation TAPI URL 7Api cOmmon amp amp rschema default gt lt OperationStatus gt lt Code gt 0 lt Code gt Message Request Completed lt Message gt lt OperationStatus gt lt Content gt Response gt Section 3 5 Loggingservices 25 3 5 2 Get log Table 3 22 Getlog SAPI URL S api logging amp method get
25. 1 a3 8 822b7E730615 Description 5elect an option lt Description gt Buttons Button action Back label Back gt Burton action Exit label Bxit gt lt Buttons gt lt Edges gt lt RootFarent gt Parent id 7361fa2d 6c6f 4af 6 95159 83E 0b1l67el6c lt Edges gt lt Menutption gt MenuOption name ScreenSelection disablelnactivitylimeout False id d327059c 098D 4522 272 c3d h acedfd gt Description 5elect an option lt Description gt Buttons Button action Back label backMn gt Button action Exit label exitMn gt lt Buttons gt lt Edges gt Parent id deaca7 80d fYclf 47el a3f8 8222p7f730615 gt lt Edges gt lt Menutption gt Form name Metadata Name disableInactivitylimeout False id 5el2553dc 902c 4f49 aDed 7411001e6b64 Description Metadata Title lt Description gt lt Buttons gt Button action Back label Back gt Burton action Next label Next gt lt Buttons gt FormOptions FormOption key metadataText name Metadata Text type Text gt lt Visibility gt ReadwWrite lt Visibility gt Description Example of text Description DefaultValue random text lt DefaultValue gt lt MinValue gt 5 lt MinValue gt lt MaxValue gt 1l15 lt MaxValue gt CustomBeqularExpression lt Style gt lt IsPassword gt False lt lsPassword gt lt Formoption gt FormOption key metadataRegExprIP name Custom Expr IP type Text gt
26. 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 v L AC TIP Any client application using the response information may use the error codes in place of strings to ensure future compatibility lt 9xml version 1 0 encoding UTF 8 Besponse version 1 1 0 xmlns xsi http www w3 o0rg 2001 XMLSchema instance xsi noNamespaceSchemaLocation API URLS api common amp rschema fault gt OperationStatus Message Job id does not correspond to a valid job lt Message gt perationStatus lt Content gt BResponse Chapter 1 API Introduction 2 APlsecurity 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 E NOTE Itis 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
27. accounts 3 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 org 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 4 Chapter 2 API security 3 Compatible API 3 1 Graph and job services 3 1 1 Putjob Table 3 1 Put a new job SAPI URL api jobs 8 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 reguired 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 Silent job If navig
28. alue gt value 4 lt PossibleValue gt lt PossibleValues gt lt FormOption gt lt Form ptions gt amp Edges Parent id d327059c 0980 4322 9272 c3d9bBaccdfd gt lt Edges gt Form lt ScanOptionssScreen name ScanOptionsScreen disableInactivityTimeout False id 2b94b08b Tedd 46c5 90ea bd3a3969c92b gt lt Description gt Select scan options lt Description gt Buttons gt lt Button action Back label Back gt Button action Next label Next gt lt Buttons gt lt ScanSettings gt lt Resolution label Resolution gt lt Visibility gt ReadWrite lt Visibility gt lt DefaultValue gt Res150x150 lt DefaultValue gt lt Resolution gt lt PreviewMode label Preview Mode gt lt Visibility gt Readonly lt Visibility gt lt DefaultValue gt Off lt DefaultValue gt lt PreviewMode gt MediaOrientation label Media Orientation gt lt Visibility gt ReadWrite lt Visibility gt lt DefaultValue gt Landscape lt DefaultvValue gt lt MediaOrientation gt lt CustomLength label Custom Length gt lt Visibility gt ReadOnly lt Visibility gt lt DefaultValue gt 2 9 lt DefaultValue gt lt CustomLength gt ColorMode label Color Mode gt lt Visibility gt ReadWrite lt Visibility gt lt DefaultValue gt Color lt DefaultValue gt lt ColorMode gt lt FileType label File Type gt lt Visibility gt ReadWrite lt Visibility gt lt DefaultValue gt Jpeg lt DefaultValue gt lt FileTypa gt
29. any requests are active Retry recommended Schema Request SAPI URLSs aspi extensibility amp rschema setButton Response amp API URLE apiccommon amp rschema default 20 Chapter3 Compatible API Figure 3 14 Extensibility services Set button request payload example lt xml version 1 0 encoding UTF 8 7 gt lt Request version 1 1 0 gt lt Button gt lt Title gt EC lt Title gt lt Description gt Title lt Description gt Icons lt NFsmart gt ImageEncodedInBase64 lt NFsmart gt lt NFsmarti10 gt ImageEncodedInBase64 lt NFsmarti0 gt lt NFsmart40 gt ImageEncodedInBase64 lt NFsmart40 gt lt Fsmart gt ImageEncodedInBase64 lt Fsmart gt lt Icons gt lt Button gt lt Request gt Figure 3 15 Extensibility services Set button success response example xml version 1 0 encoding UTF 8 Response version 1 1 0 xmlns xsis http www w3 org 2001 XMLSchema instance si noNamespaceSchemaLocations amp API URL 7Apiscommon amp amp rschema default lt OperationStatus gt Code 0 Code lt Message gt Reguest Completed lt Messaqe gt OperationStatus Content gt c Response 3 3 2 Remove button Table 3 17 Remove button SAPI URLSs api extensibility amp method removeButton GET Description Authentication Payload Response Code Removes a Home screen button on the device Attention Removing the solution button will cause all access
30. ation settings element is not defined job is considered silent Silent job is scan amp 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 Response 200 OK success 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 Schema Request SAPI URLS api jobs amp schema put Response SAPT URL api jobs8rschema put Section 3 1 Graph and job services 5 Figure 3 1 Put job Request payload example lt xml version 1 0 encoding UTF 8 7 gt lt Request version 1 1 0 gt lt Job gt lt NavigationSettings gt lt LabelA value AAA gt lt LabelB value FULL EMAIL JOB gt lt JobDescription value THIS IS MY JOB gt Permanent value true gt lt HideDeleteButton value true gt lt HideFileName value true gt lt oneButton value false gt lt HavigationSettings gt lt ScanSettings gt lt Type value tiff gt Color val
31. authentication fails 500 Internal Server Error if too many requests are active Retry recommended Response amp API URL api config amp rschema wakeup Section 3 2 Configuration services 17 Figure 3 11 Wake up success response example 4 xMml version 1 0 encoding UTF 8 7 gt Response versionz 1 1 0 xmlns xsisz http www w3 org 2001 XMLSchema instance xSi noNamespaceSchemaLocation SAPI URLs api config amp amp rschema wakeup lt OperationStatus gt lt Code gt 0 lt Code gt equest Completed lt Message gt lt Operation tatus gt Content DeviceStatus l DeviceS5tatus Content Response 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 amp API URI api config amp method cancelScan GET Description Cancels interrupts the scanning process on the device Payload IN OUT If 200 XML response with code O If 400 XML response with error code Response Code 200 OK success 400 Bad request Error code 10 Device is busy 401 Unauthorized access if basic authentication fails 500 Internal Server Error if too many request are active Retry recommended Schema Request Response amp API URL apiscommon amp rschema default Chapter 3 Compatible API Figure 3 12 Cancel scan Success response
32. b id Error code 5 Id does not correspond to a job Error code 12 Operation error 401 Unauthorized access if basic authentication fails 500 Internal Server Error if too many requests are active Retry recommended Schema Request Response SAPI URLS api common default Figure 3 3 Delete job success response example xml version 1 0 encoding UTF 8 Response version 1 1 0 xmlnsas xsi http www w3 o0rg 2001 XMLSchema instance zsi noNamespaceSchemaLocation API URL api common amp amp rschema default gt lt OperationStatus gt lt Code gt O0 lt Code gt zMessage Request Completed lt Message gt perationStatus Content gt z Response 3 1 4 Get files Table 3 4 Get files pr sp FF i SAPI URL api jobs8method getFiles8jobld fjobldj8format fformat GET Description Retrieves the files scanned by the job corresponding to the specified id If the format is set to zip returns all files in a zip If the format is set to boundary returns all files as a MIME multipart message http en wikipedia org wiki MIME If the format is set to links returns an xml with direct links to download files For silent jobs no user interaction on the control panel the getFiles is a blocking operation i e no result is returned until files are ready or the job is cancelled Payload IN Section 3 1 Graph and job services 11 Table 3 4 Get f
33. cuments to the device hard drive They are not sent out of the device and can only be recovered through an API get operation lt Local gt zEmail lt FileName value scanxx gt lt DestAddress value youdyou com gt FromAddress value me me com CcAddress value cc8cc com BccAddress value bco boec com Subject value Here is the scanned image gt lt Port value 25 gt Notification value true gt lt Email gt FTP Ftp Address value 1 2 3 4 Port value 21 gt Path value path pathi gt zMetadataFPath value path path2 gt FileName value scan gt lt UserName value username gt lt Password value pass gt lt Ftp gt Network folder lt NetworkFolder gt lt Domain value WORKGROUP gt lt Path value net path gt zMetadataPath vyalue net path gt FileName value scan gt lt UserName value username gt Password value password gt lt NetworkFolder gt Success response example Section 3 1 Graph and job services 7 lt xml version 1 0 encoding UTF 8 Response version 1 1 0 xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation API URL api jobs amp amp rschema put lt Operationstatus gt lt Code gt 0 lt Code gt lt Message gt Request Completed Messaqge gt OperationStatus Content lt JobId gt 35 JobId gt lt Content gt lt Respons
34. d amp API URLS api common amp rschema default Request payload example ET NOTE Seethe Request payload on the API set graph method Figure 4 3 Append graph success response example xml version 1 0 encoding UTF 8 gt Response version 1 1 0 xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation API URL api default amp amp rschema default OperationsStatus zCode U code lt Message gt Reguest Completed lt Message gt OperationStatus Content gt lt Response gt 4 1 3 View graph Table 4 3 View graph SAPI URL 4 api graph amp method view amp includeScheduled boolean GET Schema Description Payload Response Code Request Response Gets the graph from device The graph fetched corresponds to the graph stored on device at the moment of the api call execution As a result it does not include dynamic jobs already executed neither nodes already scheduled whatever its status is includeScheduled optional Not used in EC1 2 0 its default value is false IN OUT If 200 XML response with the graph data 200 OK success 401 Unauthorized access if basic authentication fails 500 Internal Server Error if too many requests are active Retry recommended SAPI URL S api graph amp rschema view Section 4 1 Graph and job services 33 Figure 4 4 View graph success response example xm l versionz 1 0 encoding UTF 8 gt
35. e e Errorresponse example lt xml version 1 0 encoding UTF 8 Response version 1 1 0 xmins xsi http www w3 org 2001 MLSchema instance x i noN m p c Sch m Loc tion f PI URL t api job amp rsch ma put gt lt Code gt 3 lt Code gt lt Message gt The given job is invalid lt Message gt lt OperationStatus gt lt Content gt lt Response gt 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 Control Panel Snapshot This is an inactive image of the device Control Panel To update the image with current information click Refresh Image below elect the pending job ET NOTE See APPENDIX I for possible settings and default values 3 1 2 View job Table 3 2 View job SAPI URLS api jobs amp method view amp jobld jobld GET Description Retrieves the job details as they were set up on the put API call If the ID is set to O 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 8 Chapter 3 Compatible API Table 3 2 View job continued Payload Response Code Schema Request Response OUT If 200 XML response with job details If 400 XML response with error code 200 0K success 400 Bad request Error code 2 Invalid job id Erro
36. e lt Title gt lt Buttons gt lt System utton action Back label Back gt SystemButton action Hext label Next gt lt Button gt lt Form ptions gt Form Options c Formoptions Form lt Request gt Figure 4 7 Modify node response example xml version 1 0 encoding UTF 8 7 gt Response version 1 1 0 xmlns xsiz http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation API URL S api common amp rschema default gt lt OperationStatus gt lt Code gt 0 lt Code gt lt Message gt Request ompleted lt Hessage gt lt OperatLlonstatus gt lt Content gt c Response 4 1 6 Delete node Table 4 6 Delete node SAPI URL api graph amp method deleteNode amp nodeld nodeld amp includeScheduled boolean GET Description Payload Response Code 36 Chapter4 Advanced API Removes a node from graph Removing a node will also remove any sub graph depending directly exclusively on this node NOTE If not provided includeScheduled is considered false HP EC 1 2 0 only supports includeScheduled false IN OUT If 200 XML response with code 0 If 400 XML response with error code 200 OK success 400 Bad request 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 Lengt
37. ediaSize string mur TRUE PageContent string Null FALSE QualityMode string Null FALSE Sharpness integer 1 FALSE Darkness integer 1 FALSE BackgroundRemoval integer 1 FALSE Orientation string Null FALSE Multipage boolean false FALSE NumOfPages integer 1 FALSE 38 Chapter 5 Appendix l API settings reference NAME Type Color Resolution Duplex Source MediaSize PageContent QualityMode Sharpness Darkness BackgroundRemoval Orientation Multipage NumOfPages POSSIBLE VALUES jpg pdf tiff mtiff xps color bw grayscale 75 150 200 300 400 600 boolean auto adf flatbed auto letter legal exec a3 a4 ab b5 b5_env j_double_postcard dl env 66 66 text graphic mixed small medium large 155725 3 4 5 4152 35 4 9 865 4 8 qua 3 459 9 ebe 7 98 9 portrait landscape boolean integer 5 3 Metadata and Custom options Metadata and Custom options are both optional When specifying Custom options there are a set of possible options Any other option will raise an exception KEY removeBlankPages duplexEditable userName bitRate POSSIBLE VALUES on off 44 true false String integer 5 4 Notifications Notification tag is mandatory with a valid type and condition Table 5 1 Notification email NAME Port DestAddress Fro
38. eeding 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 Table 6 1 API Error codes Error code Old error codes NSE Generic description 1 11 Product not licensed 2 8 Invalid reguest parameters 3 10 Error parsing reguest xml payload 4 The given admin password is invalid Please update it non FutureSmart only 5 5 Id not corresponding to a valid job 6 8 Job settings could not be loaded 7 8 Unexpected error creating zip file 8 Unsupported scan settings 9 n a 10 7 Device is busy Please repeat operation within a few seconds 11 9 Unsupported media size value 12 4 Unexpected error Old error codes indicate values that product NSE notified on similar situations They are provided as a reference for backwards compatibility for programmers adapting client applications for integration with HP Embedded Capture API 41
39. example Jxml version 1 0 encoding UTF 8 Response version 1 1 0 xmlns xai http www w3 o0rg 2001 XMLSchema instance si noNamespaceSchemaLocation APT URL api common amp amp rschema default gt lt OperationStatus gt lt OperationStatus gt lt Code gt O0 lt Code gt lt Message gt Request Completed lt Message gt lt Content gt c Response 3 2 7 Reset Solution Table 3 15 Reset Solution amp API URL api config amp method resetSolution GET Schema Description Authentication Payload Response Code Request Response This function restores the solution as if it was newly installed on a clean device o Removes all process data such as scanned files pending jobs etc o 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 Upon creating a new button access will have to be reconfigured Requires basic authentication with device admin credentials IN OUT If 200 XML response with code 0 If 400 XML response with error code 200 OK success 400 Bad request Error code 10 Device is busy Error code 12 Unexpected error 401 Unauthorized access if basic authentication fails 500 Internal Server Error if too many requests are active Retry recommended amp API URL S api common amp rschema default Section 3
40. h 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 SAPI URL apiscommon8rschema default Figure 4 8 Delete node response example lt xml version 1 0 encoding UTF 8 Response version 1 1 0 xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation API URL api common amp amp rschema default gt lt Operationstatus gt zCode c Code lt Message gt Request Completedc Message lt OperationStatus gt Content gt Response Section 4 1 Graph andjob services 37 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 1 Navigation settings NAME TYPE DEFAULT REQUIRED PUT LabelA string Default Name TRUE LabelB string mr FALSE JobDescription string Null FALSE Permanent boolean m TRUE HideDeleteButton boolean false FALSE HideFileName boolean false FALSE OneButton boolean false FALSE ShowSummaryScreen boolean true FALSE 5 2 Scan settings NAME TYPE DEFAULT REQUIRED PUT Type string TRUE Color string TRUE Resolution string TRUE Duplex boolean TRUE Source string um TRUE M
41. iles 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 Schema Request Response SAPT URL api jobs getFiles Figure 3 4 Get files response example Applicable only for format links lt xml version 1 0 encoding UTF 8 gt lt Response version 1 1 0 xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation API URL 9 Aapi jobs amp amp rschema getFiles OperationStatus lt Code gt 0 lt Code gt lt Messaqge gt Request Completed lt Message gt lt Operationstatus gt Content lt Document gt API URL 9methodegetFiles amp amp jobId jobId amp amp page 1 Document lt Document gt API URLt method getFilestamp jobId jobId amp page 2 lt Document gt lt Document gt API URL method getFiles amp amp jobId jobId amp page 3 lt Document gt lt Document gt API URL method getFiles amp jobld job dj amp page d lt Document gt lt Document gt API URL method getFilez amp amp jobId jobId amp amp page 5 lt Document gt lt Document gt API
42. ionMode NotApplicable TiffCompressionMode lt XpsCompressionMode gt Normal lt xXpsCompressionMode gt lt FileOptions gt lt NSEOptions gt lt NumPages gt 1 lt NumPages gt lt Permanent gt True lt Permanent gt lt NSEOptions gt lt Edges gt parent idz 2b94b08b 7cdd 46c5 90ea bd3a39696092bh gt lt Edges gt lt ScanProcess gt lt DialogScreen name Node disableInactivityTimeout False id 7361fa2d 6c6f 4af6 9519 B3 f b167el amp c lt Description gt Message lt Description gt Buttons Section 4 1 Graph and job services 32 Button action Back label Back gt Button action Exit label Exit gt Button action Next label Nexrt gt lt Buttons gt lt Message gt Document file type Scan ScanBasicOptions FileType lt br gt Scanned pages Scan ScanNumPages amp lt br amp gt Scanned files Scan FileCount 4lt br a gt 4lt br gt amp 1t WHILE type process scope cycle delimiter amp lt br amp gt amp gt Process Name amp 1t br amp gt amp Process Result Process ResultMessage ilt br gt Files Process FileCount amp lt br amp gt amp lt WHILE amp gt Message lt Edges gt Parent id 2b94b08b Todd 46c5 90ea bd3a3969c92b gt lt Edges gt lt DialogScreen gt lt Graph gt lt Reguest gt Figure 4 2 Success response example xml version 1 0 encoding UTF 8 gt Response version 1 1 0 xmlns xsi http ww
43. ls in a mixed fleet itis highly recommended that you use the getDevicelnfo API call Family 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 1 Set graph Table 4 1 Set graph SAPI URLS api graph amp method set POST Description Creates a graph on target MFP A graph is represented on the MFP as a workflow that may include all its components This operation replaces the previous graph on the MFP Payload IN XML Graph 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 1 Product not licensed Error code 3 Error parsing xml payload Error code 8 Unsupported scan settings 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 SAPI URL api graph8schema set Response SAPI URL S api common amp rschema default Section 4 1 Graph and job services 27 Figure 4 1 Set graph request payload example lt 39xml version 1 0 encoding UTF 8 2 gt Request version 1 1 0 Graph lt MenuOption name 001 TypicalGraph disableInactivityTimeout False id deaca780 f7cE 47e
44. mAddress Subject TYPE DEFAULT VALUE REQUIRED PUT Integer 25 FALSE String var TRUE String mar TRUE String Scanning Notification FALSE Section 5 3 Metadata and Custom options 39 5 5 Destinations e Destination tag obligatory e Typeattribute mandatory Metadata attribute optional default value false Destination email NAME TYPE DEFAULT VALUE REQUIRED PUT Port Integer 25 FALSE DestAddress String K TRUE FromAddress String m TRUE CcAddress String ar FALSE BccAddress String nr FALSE Subject String Scanning Notification FALSE FileName String Document FALSE Notification Boolean false FALSE Destination FTP i M A x NAME TYPE DEFAULT VALUE REQUIRED PUT Address String n TRUE Port Integer 25 FALSE Path String ur FALSE UserName String mn TRUE Password String mm FALSE FileName String Document FALSE MetadataPath String m nr FALSE Destination Network Folder NAME TYPE DEFAULT VALUE REQUIRED PUT Domain String 25 TRUE Path String mm TRUE UserName String mm FALSE Password String K FALSE FileName String Document FALSE MetadataPath String K FALSE 40 Chapter5 Appendix l API settings reference Appendix Il 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 n
45. ma getDevicelnfo Figure 3 7 Get device info success response example 2 zxml version 1 0 encoding UTF 8 lt Response version 1 1 0 xmlns xsi http www w3 o0rg 2001 XMLSchema instance xsi noNamespaceSchemaLocation sait URrL api config amp amp rschema getDeviceInfo OperationStatus H lt Code gt 0 lt Code gt zMessage Request Completed lt Message gt lt OperationStatus gt lt Content gt Device Info gt zModel CM3530 Model lt Family gt Non Futuresmart lt Family gt lt IP gt 11 11 11 11 lt IP gt lt Hostnamerdevice hp corp net lt Hostn m gt Iray lt Width gt 216 lt Width gt lt Height 400 Height gt z Iray lt Devicelnfo gt lt Content gt z Response 3 2 2 Get device status Table 3 7 Get device status SAPT URL api configx8method getDeviceStatus GET Description Returns device status information The information returned includes Disk space in bytes ADF status Payload IN OUT If 200 XML response with device status 14 Chapter 3 Compatible API 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 Schema Request Response SAPI URL api config8rschema getDeviceStatus Figure 3 8 Get device status response example lt xml version 1 0 encoding UTF 8 standalone no gt Res
46. ple 6 View job success response example u 10 Delete job Success response example 11 Get files response example Applicable only for format links 12 Set purge settings request payload example u 13 Set purge settings success response example aa 13 Get device info success response example 14 Get device status response example 15 Get solution info response example 16 Get solution status Response example 17 Wake up success response example
47. ponse version 1 2 0 xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation API URL api config amp rschema getdevicestatus gt lt OperationStatus gt lt Code gt 0 lt Code gt Message Request Completed lt Messaqge gt lt OperationStatus gt Content lt DeviceStatus gt lt DiskAvaitlable gt 10024681472 lt DiskAvailable gt lt Adfstatus gt 0 lt AdfStatus gt lt PlatbedStatus gt 2 lt FlatbedStatus gt lt DeviceStatus gt lt Content gt lt Response gt Table 3 8 ADF Status possible values Code Meaning Explanation 1 Ready There is paper for scan 0 Empty There is no paper for scan 1 Initializing Device is still booting 2 Unsupported Device does not support ADF Flatbed status monitoring 3 Not present Device has no ADF Flatbed 3 2 3 Get solution info Table 3 9 Get solution info I OU S 1 SAPT URL api config amp method getSolutionInfo GET Description Returns solution information Information returned includes Solution version License information Blocked for users through the accessibility block command Log level all off AdvancedWorkflowSupport true false Section 3 2 Configurationservices 15 Table 3 9 Get solution info continued Payload IN OUT If 200 XML response with solution info Response Code 200 OK success 401 Unauthorized access if basic authentication fails 500 Internal Server Error if too many request are active
48. r 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 SAPI URL S api jobs amp rschema view Section 3 1 Graph and job services 9 Figure 3 2 View job success response example lt 3xml version 1 0 encoding UTF 8 2 gt lt Response version 1 1 0 xmlns xsi http www w3 org 2001 ZMLSchema instance xsi noNamespaceSchemaLocation API URL api jobstamp rschem view gt OperarionStatus Code 0 Code lt Message gt Reguest Completed Message perationStarus Content Job status pending id 5 creationDare 04 03 2013 13 15 28 NavigationSettings lt Label value i gt lt LabelB value FULL EMAIL JOB gt lt JobDescription value THIS IS MY JOB gt Permanent value true gt lt HideDeleteButton value true gt lt HideFileName value true gt OneButton value false gt ShowSummaryScreen value false gt NavigationSertings ScanSettings Iype value tirr Color value bw gt Resolution value 150 gt Duplex value true gt Source value auto lt Media ize value a4 PageContent value text gt QualityMode value medium gt lt Sharpness value 3 Darkness value 4 gt BackgroundBRemoval value 4 Orientation value landscape gt Multipage value true NumOfPages value 3 l
49. rExpression lt Style gt lt IsPassword gt False lt lsPassword gt lt Formoption gt FormOption key metadataIlnt name Metadata Int type Int gt lt Visibility gt ReadwWrite lt Visibility gt lt Description gt Example of int lt Description gt lt DefaultValue gt 5 lt DefaultValue gt lt MinValue gt 5x MinValue gt lt MaxValue gt 15 lt MaxValue gt CustomBeqularExpression lt Style gt lt IsPassword gt False lt lsPassword gt lt Formoption gt FormOption key metadataDecimal name Metadata Decimal type Decimal lt Visibility gt ReadwWrite lt Visibility gt Description Example of Decimal lt Description gt DefaultValue 5 25 DefaultValue lt MinValue gt 5 lt MinValue gt MaxValue 15 MaxValue CustomBeqularExpression lt Style gt lt IsPassword gt False lt lsPassword gt lt Formoption gt FormOption key metadataBool name Metadata Bool type Bool gt lt Visibility gt ReadwWrite lt Visibility gt lt Description gt Example of Bool lt Descripticon gt DefaultValue true DefaultValue lt MinValue gt 1 lt MinValue gt lt MaxValue gt 1 lt MaxValue gt CustomBeqularExpression lt Style gt lt IsPassword gt False lt 1lsPassword gt lt Formoption gt FormOption key metadataComboList name Metadata Combo List type ComboList gt lt Visibility gt ReadwWrite lt Visibility gt Description Example of Combo List lt Description gt DefaultValue value 2
50. s if basic authentication fails 500 Internal Server Error if too many requests are active Retry recommended Schema Request Response API URL api config amp rschema getSolutionStatus 16 Chapter 3 Compatible API Figure 3 10 Get solution status Response example lt 9xml version 1 0 encoding UTF 6 2 gt Response version 1 1 0 xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation amp API URL api configtamp rschema getsolutionstatus gt lt Operation tatus gt lt Code gt 0 lt Code gt lt Message gt Reguest Completed Message perationStatus Content SolutionStartus OperaringStatus 2 OperatingStatus lt ErrorCondition gt false lt ErrorCondition gt SolutionStatus lt Content gt Eesponse Table 3 11 Navigation status possible values Code 0 1 Unknown Navigating Scanning Processing Idle 3 2 5 Wake up Table 3 12 Wake up amp API UHRL 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 With this API call it is possible to force the wake up programmatically so that it is ready when the user arrives Payload IN OUT If 200 XML response with current status Schema Response Code Request 200 OK success 401 Unauthorized access if basic
51. solution works with a set of Futuresmart and non FutureSmart MFP devices FutureSmart offers an advanced set ef functionalities that cap 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 APlis 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 Advanced Mode FutureSmart only Advanced workflows unlimited levels unlimited scans and digital sends custom prompts macros Compatibility mode all FutureSmart amp non FutureSmart Basic workflows simple navigation unique digital send notifications 1 2 Accessing the API on a device SAPI URL The Embedded Capture API is exposed throughout the MFP in specific URLs by using SSL recommended https mfp ip address hp device hp extensibility ec clientservices api parameters Although it is possible to use the API in http mode without
52. ssage gt lt Edges gt Parent id 2b954b08b 7cdd 46c5 930ea bd3a393693c92b lt Edges gt DialogScreen lt Graph gt Content Besponse 4 1 4 Clear graph Table 4 4 Clear graph SAPI URL api graph method clear8includeScheduled fboolean 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 Payload IN OUT If 200 XML response with code 0 If 400 XML response with error code Response Code 200 OK success 34 Chapter4 Advanced API Table 4 4 Clear graph continued Schema Request Response 400 Bad request Error code 2 Invalidrequest 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 amp API URLE apiccommon amp rschema default Figure 4 5 Clear graph response example lt xml version 1 0 encoding UTF 8 3 Besponse version 1 1 0 xmlns xsi http www w3 org 2001 ZMLSchema instance xsi noNamespaceSchemaLocation API URLS api common amp amp rschema default OperarionStatus Code 0 Code lt Message gt Reguest Completed lt Message gt
53. t Scansettings gt lt MetadataOptions gt lt Param key CUSTOMI value MYCUSTOMT lt Param key CUSTOM 2 value MYCUSTOUM2 lt Metadatatptions gt lt Notification gt lt Condition gt always lt Condition gt lt Email gt DestAddress value You amp tyou com lt From ddress value Me amp me com Subject value NOTIFICATTION gt Email lt Notification gt lt Destination gt lt Metadata gt true lt Metadata gt lt Email gt FileName value scanXX gt DestAddress value you amp tyou com lt From ddress value me amp me com CcAddress value ccicc com BccAddress value bcc bcc com Subject value Here is the scanned image gt lt Email gt lt Destination gt lt Job gt lt Content gt lt Responge gt 3 1 3 Delete job Table 3 3 Delete job SAPI URL 4 api jobs amp method delete amp jobld jobld 10 Chapter 3 Compatible API 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 jobld is set to O all jobs in the graph are removed If jobld is non zero only the specified job is removed Payload IN OUT If 200 XML response with code O If 400 XML response with error code Response Code 200 OK success 400 Bad request Error code 2 Invalid jo
54. ue bw gt lt Resolution value 150 gt Duplex value true gt lt Source value auto gt lt MediaSize value a4 gt lt PageContent value text gt lt QualityMode value medium gt lt Sharpness value 3 gt lt Darkness value 4 gt lt BackgroundRemoval value 4 gt Orientation value landscape gt lt Multipage value true gt lt NumOfPages value 3 gt lt ScanSettings gt lt CustomOptions gt lt Param key removeBlankPages value on gt lt CustomOptions gt lt MetadataOptions gt lt Param key metatadataKeyl value metadataDefaultValuel gt lt Param key metatadataKey2 value metadataDefaultValue gt lt MetadataOptions gt lt Notification gt lt Condition gt always lt Condition gt lt Email gt lt DestAddress value Youfyou com gt lt FromAddress value Meime com gt lt Port value 7 gt lt Email gt lt Notification gt lt Destination gt lt Metadata gt true lt Metadata gt lt Email gt FileName value scanxx gt lt DestAddress value youdyou com gt FromAddress value metme com gt lt CcAddress value cc cc com gt lt BecAddress value bcctbcc com gt Subject value Here is the scanned image gt lt Email gt lt Destination gt lt Job gt lt Request gt Destination examples A scan job can be assigned any of the following destinations 6 Chapter 3 Compatible API Local The Local destination saves scanned do
55. w w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation API URL api default amp amp rschema default UperationsStatus lt Code gt O0 lt Code lt Message gt Reguest Completed lt Message gt lt OperationStatus gt Content gt lt Response gt ET NOTE Seesectien Appendix te checlcthe settings possible and default values 4 1 2 Append graph Table 4 2 Append graph SAPI URL api graph method append8parentlD nodeld POST Description Appends a new subgraph on target MFP existing workflow graph If parent node Id is not provided the new graph will be appendedto the root node on the device and will appear as a new menu option when accessing the first EC screen Payload IN XML Graph OUT If 200 XML response with code O If 400 XML response with error code Response Code 200 OK success 400 Bad reguest Error code 1 Product not licensed Error code 3 Error parsing xml payload Error code 5 Id not corresponding to a valid job Error code 8 Unsupported scan settings Error code 10 Device is busy silent mode Error code 12 Unexpected error 401 Unauthorized access if basic authentication fails Chapter 4 Advanced API Table 4 2 Append graph continued Schema Request Response 411 Length required if content length is not or is badly specified 500 Internal Server Error if too many requests are active Retry recommended amp API UHL api graph schema appen
Download Pdf Manuals
Related Search