emc captiva rest services · captiva rest services supports only the json format for resource...

EMC® Captiva® REST Services Version 2.0

Development Guide

EMC Corporation

Corporate Headquarters

Hopkinton, MA 01748-9103

1-508-435-1000

www.EMC.com

Document Revision Date: 1-28-2015, 2:00pm

http://www.emc.com/

Legal Notice

Copyright © 2013-2015 EMC Corporation. All Rights Reserved.

EMC believes the information in this publication is accurate as of its publication date. The information is subject to change

without notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED "AS IS." EMC CORPORATION MAKES NO REPRESENTATIONS OR

WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS

IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.

For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. Adobe and Adobe PDF

Library are trademarks or registered trademarks of Adobe Systems Inc. in the U.S. and other countries. All other trademarks

used herein are the property of their respective owners.

Documentation Feedback

Your opinion matters. We want to hear from you regarding our product documentation. If you have feedback about how we can

make our documentation better or easier to use, please send us your feedback directly at

[email protected]

mailto:[email protected]

Table of Contents

OVERVIEW .....................................................................................................................................................................................................8

1 WHAT ARE THE CAPTIVA REST SERVICES? ................................................................................................................................................................... 8 2 LEARNING CAPTIVA REST SERVICES ............................................................................................................................................................................ 8

DOCUMENT SPECIFICATION SYNTAX ..............................................................................................................................................................9

GENERAL REST DEFINITIONS ......................................................................................................................................................................... 10

3 COMMON DEFINITION - HTTP HEADERS ................................................................................................................................................................... 10 4 HTTP STATUS CODES ............................................................................................................................................................................................. 11 5 SUPPORTED MIME TYPES ....................................................................................................................................................................................... 12 6 HTTP METHODS ................................................................................................................................................................................................... 14 7 HYPERMEDIA, LINK RELATIONS AND URIS .................................................................................................................................................................. 14 8 LINK RELATIONS .................................................................................................................................................................................................... 15

8.1 Public Link Relation Registry ...................................................................................................................................................................... 15 8.2 Captiva Link Relations ................................................................................................................................................................................ 15

9 CROSS-ORIGIN RESOURCE SHARING ......................................................................................................................................................................... 16 10 BASE64 ENCODING ............................................................................................................................................................................................ 17

IMPORTANT FEATURES ................................................................................................................................................................................ 18

11 RETURN STATUS AND CAPTIVA REST ERROR CODES ................................................................................................................................................ 19 12 THE HOME DOCUMENT IS THE ENTRY POINT .......................................................................................................................................................... 22 13 AUTHENTICATION – CREATING A SESSION .............................................................................................................................................................. 22

RESOURCES.................................................................................................................................................................................................. 23

14 ABOUT RESOURCE .............................................................................................................................................................................................. 23 14.1 Link Relations in this Resource ................................................................................................................................................................... 23 14.2 Operations ................................................................................................................................................................................................. 24 14.3 Get the About Resource ............................................................................................................................................................................. 24

15 AD HOC SERVICES RESOURCE ............................................................................................................................................................................... 26 15.1 Link Relations in this Resource ................................................................................................................................................................... 26 15.2 Operations ................................................................................................................................................................................................. 26

15.3 Get Services Operation ............................................................................................................................................................................... 27 16 AD HOC SERVICE RESOURCE ................................................................................................................................................................................ 30

16.1 Link Relations in this Resource ................................................................................................................................................................... 30 16.2 Operations ................................................................................................................................................................................................. 31 16.3 Submit a Service Request Operation .......................................................................................................................................................... 31

17 BATCHES RESOURCE ........................................................................................................................................................................................... 37 17.1 Link Relations in this Resource ................................................................................................................................................................... 37 17.2 Operations ................................................................................................................................................................................................. 37 17.3 Get the Batches Feed ................................................................................................................................................................................. 38 17.4 Create Batch Operation ............................................................................................................................................................................. 42 17.5 Delete All Batches Operation ..................................................................................................................................................................... 47

18 BATCH RESOURCE .............................................................................................................................................................................................. 49 18.1 Link Relations in this Resource ................................................................................................................................................................... 49 18.2 Operations ................................................................................................................................................................................................. 50 18.3 Get Batch Operation .................................................................................................................................................................................. 50 18.4 Update Batch Operation ............................................................................................................................................................................ 53 18.5 Delete Batch Operation.............................................................................................................................................................................. 58

19 DOCUMENT TYPES RESOURCE .............................................................................................................................................................................. 60 19.1 Link Relations in this Resource ................................................................................................................................................................... 60 19.2 Operations ................................................................................................................................................................................................. 60 19.3 Get Document Types Operation ................................................................................................................................................................. 60

20 DOCUMENT TYPE RESOURCE ................................................................................................................................................................................ 64 20.1 Link Relations in this Resource ................................................................................................................................................................... 64 20.2 Operations ................................................................................................................................................................................................. 64 20.3 Get Document Type Operation .................................................................................................................................................................. 64

21 FILES RESOURCE ................................................................................................................................................................................................ 72 21.1 Link Relations in this Resource ................................................................................................................................................................... 73 21.2 Operations ................................................................................................................................................................................................. 73 21.3 Post to Create a Stage File Operation ........................................................................................................................................................ 73 21.4 Delete All Files Operation ........................................................................................................................................................................... 77

22 FILE RESOURCE .................................................................................................................................................................................................. 79 22.1 Link Relations in this Resource ................................................................................................................................................................... 79 22.2 Operations ................................................................................................................................................................................................. 79 22.3 Get File Operation ...................................................................................................................................................................................... 79

22.4 Post a Chunk File Operation ....................................................................................................................................................................... 81 22.5 Delete File Operation ................................................................................................................................................................................. 87

23 HOME DOCUMENT RESOURCE ............................................................................................................................................................................. 89 23.1 Link Relations in this Resource ................................................................................................................................................................... 89 23.2 Operations ................................................................................................................................................................................................. 90 23.3 Get the Home Document ........................................................................................................................................................................... 90

24 SESSION RESOURCE ............................................................................................................................................................................................ 95 24.1 Link Relations in this Resource ................................................................................................................................................................... 95 24.2 Operations ................................................................................................................................................................................................. 96 24.3 Get the Session ........................................................................................................................................................................................... 96 24.4 Login Operation ......................................................................................................................................................................................... 98 24.5 Logoff Operation ...................................................................................................................................................................................... 101

25 TABLES RESOURCE ............................................................................................................................................................................................ 102 25.1 Link Relations in this Resource ................................................................................................................................................................. 103 25.2 Operations ............................................................................................................................................................................................... 103 25.3 Get the Tables Feed ................................................................................................................................................................................. 103

26 TABLE RESOURCE ............................................................................................................................................................................................. 106 26.1 Link Relations in this Resource ................................................................................................................................................................. 106 26.2 Operations ............................................................................................................................................................................................... 106 26.3 Get a Table Operation .............................................................................................................................................................................. 107

AD HOC SERVICE DESCRIPTIONS ................................................................................................................................................................. 111

27 UIM DATA INFORMATION OBJECT ...................................................................................................................................................................... 111 28 CLASSIFY SERVICE ............................................................................................................................................................................................. 112

28.1 Service Name ........................................................................................................................................................................................... 112 28.2 Service Properties ..................................................................................................................................................................................... 113 28.3 Request Items........................................................................................................................................................................................... 113 28.4 Result Items.............................................................................................................................................................................................. 113 28.5 Example Request and Response............................................................................................................................................................... 114

29 CLASSIFY EXTRACT DOCUMENT SERVICE............................................................................................................................................................... 116 29.1 Service Name ........................................................................................................................................................................................... 116 29.2 Service Properties ..................................................................................................................................................................................... 116 29.3 Request Items........................................................................................................................................................................................... 117 29.4 Result Items.............................................................................................................................................................................................. 117

29.5 Example Request and Response............................................................................................................................................................... 118 30 CLASSIFY EXTRACT PAGE SERVICE ....................................................................................................................................................................... 120

30.1 Service Name ........................................................................................................................................................................................... 120 30.2 Service Properties ..................................................................................................................................................................................... 120 30.3 Request Items........................................................................................................................................................................................... 121 30.4 Result Items.............................................................................................................................................................................................. 121 30.5 Example Request and Response............................................................................................................................................................... 122

31 CONVERT IMAGES SERVICE ................................................................................................................................................................................ 124 31.1 Service Name ........................................................................................................................................................................................... 124 31.2 Service Properties ..................................................................................................................................................................................... 124 31.3 Request Items........................................................................................................................................................................................... 125 31.4 Result Items.............................................................................................................................................................................................. 125 31.5 Example Request and Response............................................................................................................................................................... 126

32 EXTRACT DOCUMENT SERVICE ............................................................................................................................................................................ 128 32.1 Service Name ........................................................................................................................................................................................... 128 32.2 Service Properties ..................................................................................................................................................................................... 128 32.3 Request Items........................................................................................................................................................................................... 128 32.4 Result Items.............................................................................................................................................................................................. 129 32.5 Example Request and Response............................................................................................................................................................... 130

33 EXTRACT PAGE SERVICE .................................................................................................................................................................................... 132 33.1 Service Name ........................................................................................................................................................................................... 132 33.2 Service Properties ..................................................................................................................................................................................... 133 33.3 Request Items........................................................................................................................................................................................... 133 33.4 Result Items.............................................................................................................................................................................................. 134 33.5 Example Request and Response............................................................................................................................................................... 134

34 FULL PAGE OCR SERVICE .................................................................................................................................................................................. 137 34.1 Service Name ........................................................................................................................................................................................... 137 34.2 Service Properties ..................................................................................................................................................................................... 137 34.3 Request Items........................................................................................................................................................................................... 138 34.4 Result Items.............................................................................................................................................................................................. 139 34.5 Example Request and Response............................................................................................................................................................... 140

35 PROCESS IMAGE SERVICE ................................................................................................................................................................................... 142 35.1 Service Name ........................................................................................................................................................................................... 142 35.2 Service Properties ..................................................................................................................................................................................... 142

35.3 Request Items........................................................................................................................................................................................... 142 35.4 Result Items.............................................................................................................................................................................................. 143 35.5 Example Request and Response............................................................................................................................................................... 143

36 READ BARCODES SERVICE ................................................................................................................................................................................. 145 36.1 Service Name ........................................................................................................................................................................................... 146 36.2 Service Properties ..................................................................................................................................................................................... 146 36.3 Request Items........................................................................................................................................................................................... 147 36.4 Result Items.............................................................................................................................................................................................. 148 36.5 Example Request and Response............................................................................................................................................................... 149

37 UIMDATA SERVICE ........................................................................................................................................................................................... 151 37.1 Service Name ........................................................................................................................................................................................... 151 37.2 Service Properties ..................................................................................................................................................................................... 151 37.3 Request Items........................................................................................................................................................................................... 152 37.4 Result Items.............................................................................................................................................................................................. 153 37.5 Example Request and Response............................................................................................................................................................... 153

8

OVERVIEW

This document is a guide to using EMC Captiva REST Services (CRS) to interact with the Captiva platform. It is intended for

developers and architects who are building clients against the Captiva REST Services.

1 WHAT ARE THE CAPTIVA REST SERVICES? EMC Captiva REST Services (CRS) are a set of RESTful web service interfaces that interact with the Captiva platform. Being

developed in a purely RESTful style, Captiva REST Services provides you with high efficiency and simplicity in programming,

and also makes all services easy to consume. These advantages make Captiva REST Services the best choice for next

generation applications and mobile applications to interact with the Captiva platform.

Captiva REST Services identifies resources by Uniform Resource Identifiers (URIs). It defines specific media types to represent

resources and drives application state transfers by using link relations. It uses a limited number of HTTP standard methods

(GET, POST, and DELETE) to manipulate these resources over the HTTP protocol.

Captiva REST Services supports only the JSON format for resource representation. JavaScript Object Notation (JSON) is a

lightweight data interchange format based on a subset of the JavaScript Programming Language standard.

2 LEARNING CAPTIVA REST SERVICES This document will provide explanations for all of the Captiva REST Services APIs. There is also a sample called the Captiva

REST Services Sample that will be provided with the installation of the service that can be used to exercise the Captiva REST

Service to help learn the API.

There are some high-level constraints that pertain to the Captiva REST Service (hereafter simply called, "service") that are

important to keep in mind:

1. This service is a JSON service and will not support alternate formats in XML.

2. When the service is installed on IIS it will be configured for support of Cross-Origin Resource Sharing by default. This

can be turned off at any time through the web.config.

3. Requests that result in more than 1000 rows will be truncated. At this time, the service does not support paging of the

resources.

9

4. Data submissions to the service have a 100mb limit. Anything over this limit will generate an error.

5. We support response code suppression per call for client scenarios that prefer the service to always return HTTP Status

Code 200 instead of an HTTP error code. For more information, see the Return Status section. The detailed error will

continue to be in the JSON body under the returnStatus object. To use this feature, just add the

suppress_response_codes query string parameter with any call. For example, the following will suppress response

codes to only produce HTTP Status Code 200: http://myserver.com/session?suppress_response_codes. For

Javascript frameworks that demand a value the following will also work:

http://myserver.com/session?suppress_response_codes=suppress_response_codes. The absence of either of these

options will result in HTTP Status Error Codes to be returned as needed when an error occurs.

There are two very basic common features that are provided by the Captiva REST Service. These are described below.

Batch Creation

Through the Captiva REST Service you can create batches in the Captiva InputAccel Server. To accomplish this you create a

batch, add all your files and values to it, and then submit it. It is an easy process and provides the ability to chunk large files.

Ad Hoc Services

Ad Hoc Services are a collection of special operations that can be performed on data you submit. Each of these Ad Hoc Services

will take a set of Service Properties along with the Request Item information. The Service Properties describe the options that a

service should use when performing its operation. The Request Item information describes all of the data and files that the Ad

Hoc Service should perform its operation on.

DOCUMENT SPECIFICATION SYNTAX

This document will provide a colored and font specific syntax to clarify the specification as follows:

All code samples will be in Black Courier New font.

Optional parameters will be specified with blue square brackets, [optional].

Required parameters will be in blue angle brackets, <param>. For ambiguity in JSON syntax between arrays and optional

parameters using the braces, please see the additional information in the notes for the line in question.

10

Areas of the JSON that can be repeated will be noted with blue square brackets, [REPEATABLE].

All comments for the syntax will be in green Courier New font.

The documentation will use, <URI>, to represent the URI that is discoverable at runtime.

GENERAL REST DEFINITIONS

3 COMMON DEFINITION - HTTP HEADERS Captiva REST Services supports the following common HTTP headers:

HTTP Header Name Description In Request or Response? Value Range

Accept Acceptable media type for the

response.

Request See the topic, "Supported

MIME Types."

Accept-Language The culture codes that are

acceptable to the client per

RFC 2616.

Request The Captiva REST Service

supports the following

cultures: de, en-US, es, fr, it,

ja-JP, ko-KR, pt, ru, zh-CN.

Content-Type MIME type of the request

body or response body.

Request/Response See the topic, "Supported

MIME Types."

The Captiva REST Service

ignores the charset parameter

in the Content-Type header.

All JSON requests will be

processed as UTF8 and all

JSON responses will be in

UTF8.

Content-Length Size of the entity-body, in

decimal number of OCTETs,

Request/Response Non-negative number.

11

sent to the recipient.

Content-Range This is used for chunking

binary files to the server. The

Content-Range entity-header

is sent with a partial entity-

body to specify where in the

full entity-body the partial

body should be applied.

Request The byte range for the chunk

that is being sent. Please see

RFC 2616 for more

information.

Cookie Provide cookie information

submitted by the client.

Request Any acceptable cookie value.

CPTV-TICKET Provides a Captiva Session

Ticket.

Request This is a server generated

string for Captiva Session

Tickets. This also can be used

as a cookie and the service

will use it (our examples use

this alternative option).

Location URI of the newly-created

resource

Response URI

Set-Cookie Sets an HTTP cookie

Response

Response Used by client token.

4 HTTP STATUS CODES Captiva REST Services supports the following HTTP status codes:

Status Code Description

200 OK The request has succeeded. The information returned with the response is dependent on the

method used in the request, for example: GET an entity corresponding to the requested

resource is sent in the response; PUT an entity describing or containing the modified

12

resource.

201 Created The request has been fulfilled and resulted in a new resource being created. The newly

created resource can be referenced by the URI(s) returned in the entity of the response, with

the most specific URI for the resource given by a Location header field. The entity format is

specified by the media type given in the Content-Type header field.

400 Bad Request The request could not be understood by the server due to malformed syntax, missing or

invalid information (such as a validation error on an input field, or a missing required value).

The client should not repeat the request without modifications.

401 Unauthorized The caller is not authorized to access this resource. Please ensure the caller has logged into

the service and supplied proper credentials to create a session with the service.

404 Not Found The request from an authenticated user specifies a URI of a resource that does not exist.

405 Method Not Allowed The HTTP verb specified in the request is not allowed for the resource identified by the

request URI.

415 Unsupported Media Type The server is refusing to service the request because the entity of the request is in a format

not supported by the requested resource for the requested method.

500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the

request.

Captiva REST Services support response code suppression per call for client scenarios that prefer the service to always return

HTTP Status Code 200 instead of an HTTP error code. The detailed error will continue to be in the JSON body under the

returnStatus object. To use this feature, just add the suppress_response_codes query string parameter with any call. For

example, the following will suppress response codes to only produce HTTP Status Code 200:

http://myserver.com/session?suppress_response_codes. For Javascript frameworks that demand a value the following will

also work: http://myserver.com/session?suppress_response_codes=suppress_response_codes. The absence of either of

these options will result in HTTP Status Error Codes to be returned as needed when an error occurs.

5 SUPPORTED MIME TYPES Captiva REST Services supports the following MIME types:

13

MIME Type Description

application/json JSON representation. This can be used for compatible viewing as an alternative to the

more formal application/vnd.emc.captiva+json type when working with the Captiva

REST APIs. This will be in UTF8 encoding.

application/json-home This is the type for the Home Document used for Captiva REST Services.

application/msword Microsoft Word file. This can be used with the Files resource.

application/octet-stream Binary file. This can be used with the Files resource.

application/pdf Adobe PDF file (*.pdf). This can be used with the Files resource.

application/rtf Rich text file. This can be used with the Files resource.

application/vnd.emc.captiva+json Captiva JSON representation. This will be in UTF8 encoding. This is the standard media

type used for the Captiva REST Service's JSON request and responses.

image/jpeg JPEG image. This can be used with the Files resource.

image/png PNG image. This can be used with the Files resource.

image/tiff TIFF image. This can be used with the Files resource.

text/plain Text file. This can be used with the Files resource.

Note:

If the client doesn’t specify the Accept header for the expected response, the REST server uses the default MIME type

application/vnd.emc.captiva+json.

If the client doesn’t specify the Content-Type header for a POST request, the REST server rejects the request with the

HTTP status code 415.

14

6 HTTP METHODS Captiva REST Services supports the following HTTP methods:

GET: Use this method to retrieve a representation of a resource.

POST: Use this method to create new resources, or update existing resources.

DELETE: Use this method to delete a resource.

7 HYPERMEDIA, LINK RELATIONS AND URIS The Captiva REST Service is a hypermedia-driven REST API. The physical URIs used to access the service's resources are

discoverable at runtime through link relations. This is helpful for clients to work with different deployments of the service.

For the client to start, it needs the root address to the service. This is the entry point for the service. Issuing an HTTP GET for

this root entry point will return a Home Document that will contain link relations for all the top level resources exposed by the

service. Here is a snippet of the Home Document as an example:

{

"resources":

{

"http://identifiers.emc.com/linkrel/session": // Link relation for this resource.

{

"href": "<URI>", // Location of this resource.

"hints": // Hints provide information on

{ // allowable verbs and representations.

"allow":["GET", "POST", "DELETE"],

"representations":["application/json","application/vnd.emc.captiva+json"]

}

},

<...Truncated>

The link relation is not a physical location. It is an immutable name encoded as a URI that identifies the purpose of a link. A link

relation is associated with an href that contains the physical address of the link. In resources such as feeds and feed entries,

the link relations will be listed by a links table with rel properties for the href as follows:

"links": // Link relations table.

[

{"rel":"self", "href":"<URI>"} // The "rel" indicates the type of link relation paired with the

// href for the physical URI reference to the resource.

15

],

<Truncated>

Each link relation name (self, edit, about, http://identifiers.emc.com/linkrel/session, etc.) provides immutable identifiers that

indicate what resource it is referencing. Each of the resources documented below will indicate the link relations that are

available and their definition.

All of the physical URIs that do get returned by the Captiva REST Service will be absolute URIs. We will not use relative URIs in

any representation. This allows you to have direct reference to the resource.

8 LINK RELATIONS Captiva REST Services uses the link relations described in the following tables. The first set of link relations describe those that

come from the public registry. The second set are link relations defined within EMC and used by Captiva REST Services.

8.1 Public Link Relation Registry

The Internet Assigned Numbers Authority (IANA) maintains the public link relations registry here:

http://www.iana.org/assignments/link-relations. The following describes those that are used within Captiva REST Services with

links to the detailed specifications.

Link Relation Description Specification

about Returns product information. http://tools.ietf.org/html/rfc6903

edit Points to a resource that can be used to edit the

link’s context.

http://tools.ietf.org/html/rfc5023

self Conveys an identifier for the link’s context. http://www.ietf.org/rfc/rfc4287

8.2 Captiva Link Relations

These are link relations defined within EMC for use by Captiva REST Services.

http://www.iana.org/assignments/link-relations



http://www.ietf.org/rfc/rfc4287

16

Link Relation Description

http://identifiers.emc.com/linkrel/data-batches Provides an href to the Batches resource. This resource allows you access

to create a batch in the Captiva InputAccel Server.

http://identifiers.emc.com/linkrel/doctypes Provides an href to the Document Types resource. This resource allows

you access to the Document Types that are available in the system.

http://identifiers.emc.com/linkrel/files Provides an href to the Files resource. This resource allows you to

generate stage files for Service Requests.

http://identifiers.emc.com/linkrel/login This is the link relation that references the URI to use for performing a

login. This is always an available link relation whether or not the user is

already logged in.

http://identifiers.emc.com/linkrel/logoff This is the link relation that references the URI to use for performing a

logoff. This is always an available link relation whether or not the user is

already logged in.

http://identifiers.emc.com/linkrel/services Provides an href to the Services resource. This resource allows you to

generate Service Requests for Captiva's Ad Hoc Services.

http://identifiers.emc.com/linkrel/session Provides an href to the Session resource to login or logoff from the

service.

http://identifiers.emc.com/linkrel/tables Provides an href to the Tables resource. This resource provides access to

data and lists maintained by the Captiva platform.

9 CROSS-ORIGIN RESOURCE SHARING Web browsers commonly apply same-origin restrictions to network requests unless the server supports Cross-Origin Resource

Sharing (CORS). These restrictions prevent a client-side web application running at one origin from obtaining data retrieved

from another origin. Since the Captiva REST Service supports CORS by default, modern browsers such as Internet Explorer,

FireFox, and Chrome, will allow web applications running in a different origin to interact with the Captiva REST Service. For

http://identifiers.emc.com/linkrel/doctypes

17

detailed information on the CORS specification, please see the W3C's Cross-Origin Resource Sharing specification found here:

http://www.w3.org/TR/cors/.

When the Captiva REST Service is installed it will be configured for support of Cross-Origin Resource Sharing by default. This

can be turned off at any time through the web.config. The default implementation allows all callers from different origins to

utilize the Captiva REST Services.

<emc.captiva>

<cors enable="true" defaultAllow="true">

<entries>



</entries>

</cors>

</emc.captiva>

The <cors> tag provides an enable attribute for enabling or disabling Captiva's implementation of CORS. It is on by default. To

turn off Captiva's CORS implementation just set the enable attribute to "false". The defaultAllow attribute is used to decide

what should happen to callers origins that are not explicitly listed in the <entries> tag. If defaultAllow="true", then they are

allowed; if defaultAllow="false" then they are not allowed.

If you want to have finer grain control over a particular caller's orgin, then you can list it under the <entries> tag. Use an

<add> tag (as shown above) with attributes of origin and allow. The origin attribute should provide the origin URL address

for the caller you want to provide finer grain control. The allow attribute should be set to "true" or "false" to define whether

it is allowed or not.

10 BASE64 ENCODING Certain JSON properties support base64 encoding. Because there may be different base64 encoding variations in the

community, the base64 characters and indexing that we explicitly support (and that are used by the Captiva REST Service) are

defined in the following table.

In the table, the base64 digits in ascending order starting from zero are:

The uppercase characters 'A' to 'Z'

The lowercase characters 'a' to 'z'

The numerals '0' to '9'

http://www.w3.org/TR/cors/

18

The symbols '+' and '/'

The valueless character, '=', is used for trailing padding.

Our implementation relies on the Microsoft .NET implementation of base64 encoding found in the Convert.ToBase64String(...)

and Convert.FromBase64String(...) methods.

The Base64 index table:

Value b64Char

Value b64Char

Value b64Char

Value b64Char

0 A 16 Q 32 g 48 w

1 B 17 R 33 h 49 x

2 C 18 S 34 i 50 y

3 D 19 T 35 j 51 z

4 E 20 U 36 k 52 0

5 F 21 V 37 l 53 1

6 G 22 W 38 m 54 2

7 H 23 X 39 n 55 3

8 I 24 Y 40 o 56 4

9 J 25 Z 41 p 57 5

10 K 26 a 42 q 58 6

11 L 27 b 43 r 59 7

12 M 28 c 44 s 60 8

13 N 29 d 45 t 61 9

14 O 30 e 46 u 62 +

15 P 31 f 47 v 63 /

IMPORTANT FEATURES

There are some important features that you should take note of for using the Captiva REST Services successfully. These are

described below.

19

11 RETURN STATUS AND CAPTIVA REST ERROR CODES The Captiva REST Service will report the status of the request in a special object called returnStatus for all authenticated

users. The returnStatus object will report both success and error information for the call. Like most systems, the HTTP error

space is not sufficient to represent the many different kinds of errors that occur within Captiva. Therefore, the best HTTP error

will be chosen and further error information will be in the returnStatus property of the HTTP response.

In addition, the service will support response code suppression per call for client scenarios that prefer the service to return

HTTP Status Code 200 instead of an HTTP error code. The detailed error will continue to be in the JSON body. To use this

feature, just add the suppress_response_codes query string parameter with any call. For example:

http://myserver.com/session?suppress_response_codes. The absence of this parameter will result in HTTP Status Error

Codes to be returned as needed when an error occurs.

The structure of the returnStatus property that reports a success or error will look like the following:

"returnStatus":

{

"status":<integer>, // Same as HTTP Status Code.

"code":<string>, // An alphanumeric Captiva return code.

"message":<string>, // A Captiva message. The message

// will be localized into supported cultures only.

"server":<string> // Internal reserved member to provide some information about

// the server within a farm that processed the request.

}

The status member contains the HTTP status code that would have been returned if the "suppress_response_codes" parameter

was not given. The code property will contain the Captiva REST error code. The error codes in this release (version 2.0) may be

used for programmatic access and are stable. They will not change between releases. However, the error codes released in the

previous release were unpublished and not stable.

The message property represents the error message and is meant primarily for tracing and debugging only. It does not provide

an application specific end-user message. The message text may differ between releases of the Captiva REST Service with

similar meaning. Therefore, client applications should instead show a more suitable message for their users, based on the error

code property. The "[internal code]" portion of some error messages will contain an internal code useful for engineering and

support. An example for this is, "[M8012] The request was rejected because the authentication session ticket was invalid or

expired."

All published error codes will belong to either a recoverable category or a non-recoverable category. Recoverable errors are

likely to succeed when retried after a small interval. The following table summarizes the published error codes.

20

Error

Code

HTTP

Code

Category Error Message Description

OK0000 200 to

299

Success Success This is used for all successful responses.

EN8001 302 Redirect [internal code] The resource requires

redirection.

This is a standard HTTP redirection response.

EN8010 500 Non-

recoverable

[internal code] Generic non-recoverable

error.

This is a non-recoverable error. Additional

information may be appended to the

message. The operation is likely to fail again

if retried even after a brief delay.

EN8011 400 Non-

recoverable

[internal code] The provided contents

do not conform to a valid request.

The contents of the request do not conform

to a valid request. This happens if

deserialization of the JSON provided fails,

the data types passed in the parameters of

the JSON do not match with the

specification, or the values are not correct

for the service.

EN8012 401 Non-

recoverable

[internal code] The request was rejected

because the authentication session

ticket was invalid or expired.

The service request was rejected because

the authentication session ticket was invalid

or expired.

EN8013 403 Non-

recoverable

[internal code] The user does not have

sufficient permissions for the operation.

The user does not have the required

privileges to access the resource.

EN8014 404 Non-

recoverable

[internal code] The resource for URI

"{0}" was not found.

The specified URI is invalid.

EN8015 405 Non-

recoverable

[internal code] The HTTP method "{1}"

is invalid for the URI resource "{0}".

The HTTP method is invalid for the URI

requested.

EN8016 415 Non-

recoverable

[internal code] The Accept type is not

supported for this request.

The requested accept header type is not

supported.

21

EN8017 415 Non-

recoverable

[internal code] The Content-Type "{0}"

is not supported for this request.

The given content type in the POST is not

supported.

EN8100 500 Non-

recoverable

[internal code] User authentication

failed.

The supplied credentials are not valid.

EN8101 500 Non-

recoverable

[internal code] User authentication with

an external system failed.

The request to authenticate with an external

system, such as a Central Authentication

Service (CAS), failed.

EN8102 500 Non-

recoverable

[internal code] A license is not available

to complete the operation.

The license is not available for the operation.

A retry cannot succeed until a new license is

deployed.

EN8103 500 Non-

recoverable

[internal code] The client module "{0}"

was not found or not configured

correctly.

The required client module type for the given

operation is not deployed. This requires a

configuration change and/or an installation

of the required software on the server.

EN8104 500 Non-

recoverable

[internal code] Invalid service

parameter "{0}".

A service request property is either missing

or has an invalid type or invalid value.

EN8105 500 Non-

recoverable

[internal code] The requested item

count "{2}" for the service "{0}" is

invalid. Expected: {1}.

The service request has an invalid number of

request items.

EN8106 500 Non-

recoverable

[internal code] The file count "{1}"

given in the service request is invalid for

the service "{0}". Expected: {2}.

The service request has an invalid number of

file items.

EN8107 500 Non-

recoverable

[internal code] File with ID "{0}" was

not found. The file could have been

deleted.

The file ID given does not exist in the

session context.

EN8108 500 Non-

recoverable

[internal code] The given file offset

"{1}" for the value name "{0}" is

invalid.

The file chunk data offset is incorrect.

Chunking requires contiguous blocks without

gaps or overlap, except the last chunk may

22

be resubmitted any number of times.

ER8801 500 Recoverable [internal code] Generic recoverable

error.

This is a recoverable error. Additional

information may be appended to the

message. The operation is likely to succeed

if retried after a brief delay.

ER8811 500 Recoverable [internal code] Shared licensed feature

"{0}" with current usage {2} has

exceeded entitlement {1}.

All deployed shared license counts are in

use. A retry after a brief delay may succeed

if a shared license is released by another

client.

ER8812 500 Recoverable [internal code] The client module for the

service "{0}" is not available. All

modules instances are currently busy

processing requests.

All deployed client module instances are

processing other requests and therefore an

attempt to obtain a module failed. The

operation is very likely to succeed if retried

after a small delay.

12 THE HOME DOCUMENT IS THE ENTRY POINT The Home Document is the entry point to the REST Service. It is available to any caller. It is retrieved by performing an HTTP

GET on the base installation path. So for example if the REST service was installed into https://localhost, then performing a

GET on this URI would return the Home Document. Its main purposes it to provide discovery of the URIs necessary to interact

with the service. All clients must start from the Home Document and follow the hrefs given in the link relations to the resources

desired. This is important to ensure that your client applications will always work regardless of the URI changes that may take

place under different deployment configurations of the service.

For more details about the Home Document Resource, please see the appropriate topic under the Resources section.

13 AUTHENTICATION – CREATING A SESSION The service supports either a simple default authentication or custom authentication process. The default authentication

process is that the caller will submit the user's credentials in the body of the JSON request to the URI identified for the login

relation listed in the Session resource.

23

Custom authentication is achieved by implementing a custom authentication plugin on the server-side which the service will

use. Custom authentication information can be optionally passed in the extraAuthInfo property instead of credentials or in

addition to credentials. If credentials are passed they must be passed in the username and password properties. Any credentials

passed and any information in the extraAuthInfo property will be passed on the server-side to the authentication plugin that

was configured. This plugin will be required to authenticate the user and return one or more Captiva Role names that will be

used for access to Captiva services. The authorization of these Captiva Role names can be configured through the Captiva

Administration tool (please see the administration documentation for Captiva InputAccel).

Regardless of which authentication type is used, a few additional required fields are needed in the body as a JSON payload for

login to succeed. These required fields are explained under the documentation for the Session resource. Upon successful login,

a session will be created on the server and a session ticket string will be returned as a cookie called CPTV-TICKET that

subsequent calls can use. The CPTV-TICKET can be either a request header or a cookie during communication with the Captiva

REST Service. All the examples in this document use it as a cookie, but placing the ticket string in a CPTV-TICKET request

header is also supported. Which choice you use may depend on preferences you have for your clients. The session's lifetime is

determined by a timeout setting on the server. If a timeout occurs, then the caller will have to login again.

In addition, there is also a Logoff call that the user can call that will explicitly delete the session. If Logoff is called, then the

session data is completely removed and the user will be required to login again.

For more details about the Session Resource, please see the appropriate topic under the Resources section.

RESOURCES

14 ABOUT RESOURCE This resource provides product information about the Captiva REST Service installation to authenticated users.

14.1 Link Relations in this Resource

None.

24

14.2 Operations

The About resource supports the following HTTP methods:

Method Description

GET Retrieves the server information.

14.3 Get the About Resource

The HTTP method, query parameters, and headers that are supported by this resource are described below.

HTTP Method

GET

Query Parameters

This operation supports the following optional query parameters:

suppress_response_codes

Request Headers

Accept

Accept-Language

Request Body

None.

Response Headers

Content-Length

Content-Type

25

Supported Response Media Types

application/vnd.emc.captiva+json

application/json

Response Status

200 - OK

415 - Unsupported Media Type

500 - Internal Server Error

Response Body

{

"serviceName": <string>, // Name of the service.

"productName": <string>, // Name of the product.

"copyright": <string>, // Copyright string.

"serviceVersion": <string>, // Four part version information for the REST service.

"buildVersion": <string>, // Four part version for the build.

"productVersion": <string>, // Four part product version.

"serverDate": <string>, // Server date in UTC in ISO 8601 (e.g. 2006-04-17T21:22:48.2698750Z).

"serverId": <string> // The server id that serviced the request.

}

Example Request and Response

Example Request

GET https://localhost/about HTTP/1.1

Cookie: CPTV-TICKET=<ticket goes here>

Accept: application/vnd.emc.captiva+json, application/json

Accept-Language: en-US

Example Response

HTTP/1.1 200 OK

Content-Type: application/vnd.emc.captiva+json; charset=utf-8

Content-Length: 383

{

26

"serviceName": "EMC Captiva REST Services",

"productName": "EMC Captiva",

"copyright": "Copyright © 2015 EMC Corporation. All rights reserved. This software is protected,

without limitation, by copyright law and international treaties. Use of this software and the intellectual

property contained therein is expressly limited to the terms and conditions of the License Agreement under

which it is provided by or on behalf of EMC.",

"serviceVersion": "2.0",

"buildVersion": "7.5.1221.0(D)",

"productVersion": "7.5.0.0",

"serverDate": "2014-04-03T00:17:48.0000000Z",

"serverId": "WS-S2e0168f27fff4eb1af09f0721ac45d23"

}

15 AD HOC SERVICES RESOURCE Ad Hoc Services are a collection of special capture service operations for authenticated users that can be performed

immediately on data you submit in an ad hoc fashion without requiring the construction of a workflow. Each of these Ad Hoc

Services will take a Service Request, which is a set of Service Properties along with the Request Item information. The Service

Properties describe the options that a service should use when performing its operation. The Request Item information

describes all of the data and files that the Ad Hoc Service should perform its operation on.



self Provides an href to the referenced feed or entry resource.

15.2 Operations

The Ahoc Services resource supports the following HTTP methods:

27

Method Description

GET Retrieves a list of the Ad Hoc Services that are available.

15.3 Get Services Operation

This operation returns a feed listing all of the Ad Hoc Services.

HTTP Method

GET

Query Parameters



Request Headers

Accept

Accept-Language

Content-Type

Request Body

None.

Response Headers

Content-Length

Content-Type



28

application/json

Response Status

200 - OK

401 - Unauthorized



Response Body

{

"returnStatus": // Returned only if user is authenticated.

{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

},

"id":"<URI>", // Feed instance identifier.

"title":"Services", // Simple localized title for the feed.

"updated":<string>, // Feed date in UTC in ISO 8601 (e.g. 2006-04-17T21:22:48.2698750Z)

"links": // Link relations.

[

{"rel":"self", "href":"<URI>"} // The href will match the URI used to retrieve this.

],

"entries":

[

{

"id":"<URI>", // Item instance identifier.

"title":<string>, // Not localized. Name of the Ad Hoc Service.

"updated":<string>, // Entry date in UTC in ISO 8601 (e.g. 2006-04-17T21:22:48.2698750Z)


[

{"rel":"self", "href":"<URI>"}

],

"content": // JSON object representing the content for this entry.

{

"name":<string>, // Not localized. Name of the Ad Hoc Service.

29

"version":<string> // The version number for the Ad Hoc Service.

}

}

[REPEATABLE] // Other Ad Hoc Service entries.

]

}


Example Request

GET https://localhost/session/services HTTP/1.1




Example Response

HTTP/1.1 200 OK


Content-Length: 5740

{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",

"server":"WS-S2e0168f27fff4eb1af09f0721ac45d23"

},

"id":"https://localhost/session/services",

"title":"Services",

"updated":"2014-04-03T00:17:48.0000000Z",

"links":

[

{

"rel":"self",

"href":"https://localhost/session/services"

}

],

"entries":

30

[

{

"id":"https://localhost/session/services/processimage",

"title":"Process Image Service",

"updated":"2014-04-03T00:17:48.0000000Z",

"links":

[

{

"rel":"self",

"href":"https://localhost/session/services/processimage"

}

],

"content":

{

"name":"processimage",

"version":"1.0.0.0"

}

},

<Truncating for display>

]

}

16 AD HOC SERVICE RESOURCE Ad Hoc Services are a collection of special capture service operations that can be performed immediately on data you submit in

an ad hoc fashion without requiring the construction of a workflow. Each of these Ad Hoc Services will take a Service Request,

which is a set of Service Properties along with the Request Item information. The Service Properties describe the options that a

service should use when performing its operation. The Request Item information describes all of the data and files that the Ad

Hoc Service should perform its operation on.


None.

31

16.2 Operations

The Ahoc Service resource supports the following HTTP methods:

Method Description

POST Submits a Service Request for execution by the ad hoc capture services.

16.3 Submit a Service Request Operation

A Service Request can simply be a collection of files, or files and data, or a hierarchical collection of files and/or data. It can be

as simple or as complex as needed for the Ad Hoc Service you are using. The Service Request is performed by a single POST to

the Services resource URI. If you need file chunking or you want to use the same file for many different Service Requests, then

upload the files prior to submitting the Service Request by uploading them to the Files resource. Then, you can reference the

file IDs for those uploaded files in the Service Request.

Service Properties

Every Service Request needs to include the Service Properties appropriate for the service. These define the options you want

the Ad Hoc Service to use when performing its operation. These are provided in the serviceProps property. The list of Ad Hoc

Services that are available along with their supported Service Properties are listed in the Ad Hoc Service Descriptions section.

Each of the Ad Hoc Services provide a description of its operation, a list of Service Properties that can be used, and information

about what type of data is expected.

Service Request Result

The result from a Service Request is returned synchronously and is provided in the HTTP response to the request.

HTTP Method

POST

Query Parameters



32

Request Headers

Accept

Accept-Language

Content-Type

Request Body

{

"serviceProps": // Required array. Specific to a particular service.

[

{

"name":<string>, // Required string. The name of the service property.

"value":<object> // Required object. The value for the service property.

// The only supported data types are: number, string, bool,

// datetime (must be ISO 8601 string).

}

[REPEATABLE] // Additional service properties are dependent on type of service.

],

"requestItems": // Required array. The type of information to submit here is the

[ // data you want your service to operate on.

{

"nodeId":<integer>, // Required integer. The nodeId does not need to be previously created.

// It is a unique value provided by you.

"values": // The values array will be flat list of name-value pairs.

[

{

"name":<string>, // Required string. The name of the data value.

"value":<object> // Required object. The data for the value. Only supported types

} // are: number, string, bool, datetime (must be ISO 8601 string).

[REPEATABLE] // Subsequent values are optional.

],

"files": // The files array will be a flat list of file information.

[

{

"name":<string>, // Optional string. The name of the file value.

"value":<object>, // Required object. File data value. This can be either:

// base64 file data or a file ID string for a file already

// uploaded to Files resource URI.

"contentType":<string> // Optional string. This is the file content-type that

33

// represents the file type. If not provided, then it is given

// application/octet-stream.

"fileType":<string> // The file type is used for some Ad Hoc Services. See the

// Ad Hoc Service Descriptions for more information on its usage.

}

[REPEATABLE] // Subsequent files are optional.

]

}

[REPEATABLE] // Subsequent requestItems are optional and would allow you to

// bundle multiple items into one call.

]

}

Response Headers

Content-Length

Content-Type



application/json

Response Status

200 - OK

401 - Unauthorized



Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

34

"server":<string>

},

"id":<string>, // Service Request ID in current session.

"serviceName":<string>, // The service name associated with the request.

"executionMilliSeconds":<number>,// The amount of time it took in milliseconds for processing.

"licenseUsedPercent":<number>,// The percent of the license used. If more than one license feature

// is used by the execution, then this represents the max of the usage.

"resultItems": // Contains the result of the processing.

[

{

"nodeId":<integer>, // Node ID for correlating one or more result nodes with request nodes.

"errorCode":<string>, // If an error occurred for this node, then it will be stored here.

// If successful, then this will be an empty string.

"errorMessage":<string>,// The error message if an error occurred or empty string. This will

// be a localized string.

"values": // The values array will be flat list of name-value pairs providing

// the data values of the result.

[

{

"name":<string>, // The name of the data value.

"value":<object> // The data for the value. The data types will only be:

// number, string, bool, datetime (must be ISO 8601 string).

// The data type will need to be inferred from the data value.

}

[REPEATABLE] // Subsequent values are dependent on the nature of the result.

],

"files": // The files array will be a flat list of file information.

[

{

"name":<string>, // The name of the file value. This can be used to correlate the

// response file to the request file.

"value":<object>, // This will be a base64 encoded file or a file ID string

// depending on the service properties used. File IDs begin with

// 'f_', which uses an '_' character that's incompatible with our

// base64 encoding.

"src": // This is a URI for the File ID referencing a file that was

// provided by the service depending on the service and the

// service properties used.

"contentType":<string> // The contentType for the file referenced in the src

// property.

}

35

[REPEATABLE] // Subsequent files are optional.

]

}

[REPEATABLE] // Subsequent resultItems are dependent on what was

// submitted in the request and can be correlated using nodeId.

]

}


Example Request

POST https://localhost/session/services/processimage HTTP/1.1






{

"serviceProps":

[

{

"name":"Profile",

"value":"DistractionRemoval"

}

],

"requestItems":

[

{

"nodeId":1,

"files":

[

{

"name":"DoodadPage1",

"value":"SUkqAAgAAAAPAP4ABAABAAAAAAAEB<Truncating for display>",

"contentType":"image/tiff"

}

]

}

]

}

36

Example Response

HTTP/1.1 200 OK



{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",

"server":"WS-S7699312da37548f4a2bf9921c4a66d90"

},

"id":"REQ2",

"serviceName":"ProcessImage",

"executionMilliSeconds":2847,

"licenseUsedPercent":0,

"resultItems":

[

{

"nodeId":1,

"errorCode":"",

"errorMessage":"",

"values":

[

{

"name":"BlackBarLeft",

"value":0

},

{

"name":"BlackBarTop",

"value":0

},

{

"name":"BlackBarRight",

"value":0

},

{

"name":"BlackBarBottom",

"value":7

37

}

],

"files":

[

{


"value":"f_041623dba3464f8391bbaebd1e9b38f9tif",


}

]

}

]

}

17 BATCHES RESOURCE Through the Captiva REST Service you can create batches in the Captiva InputAccel Server. To accomplish this you create a

Batch, add all your files and values to it, and then dispatch the Batch to the server. It is an easy process and provides the

ability to chunk large files.



self Provides an href to the Batches resource.

edit Provides an href to the Batches resource to allow creation and deletion.

17.2 Operations

The Batches resource supports the following HTTP methods:

38

Method Description

GET Retrieves the batches feed.

POST Creates a batch.

DELETE Deletes all the batches.

17.3 Get the Batches Feed

This will return a batches feed listing the batches in the user's session.

HTTP Method

GET

Query Parameters



Request Headers

Accept

Accept-Language

Content-Type

Request Body

None.

Response Headers

Content-Length

Content-Type

39



application/json

Response Status

200 - OK

401 - Unauthorized



Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

},


"title":"Batches", // Simple title for the feed.


[

{"rel":"self", "href":"<URI>"} // The self link rel href will match the URI used to retrieve this.

],

"entries":

[

{


"title":<string>, // Not localized. Name of the batch given by the creator.

"updated":<string>, // Last updated UTC in ISO 8601 (e.g. 2006-04-17T21:22:48.2698750Z)


[

{"rel":"self", "href":"<URI>"},

{"rel":"edit", "href":"<URI>"}

],

40


{

"id":<string>, // Batch handle ID only for the current session.

"batchName":<string>, // Not localized. Name of batch given by the creator.

"status":<string>, // "C" - Batch created. Caller may add values.

// "P" - Pending Dispatch. No more changes may be made.

// "S" - Batch was sent to the server successfully.

// "E" - Final attempt failed. Batch will not be sent anymore.

"serverBatchId":<string>,// ID created in InputAccel server. Empty if not sent to server.

"captureFlow":<string>, // Name of the CaptureFlow associated with the batch.

"batchRootLevel":<int>, // Batch root level.

"lastUpdate":<string>, // ISO 8601 date-time string of the last update.

"lastError":<string> // Last error message.

}

}

[REPEATABLE] // Other Batch entries.

]

}


Example Request

GET https://localhost/session/batches HTTP/1.1




Example Response

HTTP/1.1 200 OK



{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


41

},

"id":"https://localhost/session/batches",

"title":"Batches",

"links":

[

{

"rel":"self",

"href":"https://localhost/session/batches"

}

],

"entries":

[

{

"id":"https://localhost/session/batches/B32D_1U32D_1",

"title":"Batch_32D_1",

"updated":"2014-04-03T00:17:48.0000000Z",

"links":

[

{

"rel":"self",

"href":"https://localhost/session/batches/B32D_1U32D_1"

},

{

"rel":"edit",


}

],

"content":

{

"id":"B32D_1U32D_1",

"batchName":"Batch_32D_1",

"status":"C",

"serverBatchId":"",

"captureFlow":"NewLoanApplication",

"batchRootLevel":3,

"lastUpdate":"2014-04-03T00:17:48.0000000Z",

"lastError":""

}

},

{


42


"updated":"2014-04-03T00:29:17.0000000Z",

"links":

[

{

"rel":"self",


},

{

"rel":"edit",


}

],

"content":

{

"id":"B32D_2U32D_1",


"status":"C",

"serverBatchId":"",


"batchRootLevel":3,

"lastUpdate":"2014-04-03T00:29:17.0000000Z",

"lastError":""

}

}

]

}

17.4 Create Batch Operation

The Create Batch operation is the first call required to begin the creation of a batch. Subsequent calls are used to add more

values and files to the batch. The final call to complete the batch is through a final update to change its dispatch status, which

submits it to the batch server and will afterwards no longer support updates.

The batch name that you use to create a batch has to be unique when being imported into Captiva InputAccel Server. To help

you accomplish creating unique names you can supply for the "batchName" JSON property any Captiva Format Expression

function (see the Captiva Designer Programming Reference). There are also two additional format tokens you can use for

providing unique names. Please see the table below for details:

43

Syntax Definition Example(s)

{NextIndex} This will provide a 64 bit integer

number that is unique per

Shared-Data Directory.

Consequently, it will maintain its

uniqueness for all servers

associated with that data

directory even through reboots.

However, if the Shared-Data

Directory gets deleted or a new

Shared-Data Directory is used,

then the counter will be reset.

"batchName":"MyBatch_{NextIndex}"

Produces on the server:

MyBatch_1026000000002

{NextId} This will provide a valid Batch

name string that is unique per

Shared-Data Directory.

Consequently, it will maintain its

uniqueness for all servers

associated with that data

directory even through reboots.

However, if the Shared-Data

Directory gets deleted or a new

Shared-Data Directory is used,

then the counter will be reset.

"batchName":"MyBatch_{NextId}"


MyBatch_324_1

Any supported static

function in the Captiva

Expression Language (see

the Captiva Designer

Programming Reference).

[<any text>]{[<Format

Specification>|]<Expres

sion>}[<any text>]

Using the expression language

functions can allow the user of a

GUID or unique time string to be

a part of the Batch Name.

"batchName":"MyBatch_{Tddhhmmss|Now()}_{NextIndex}"


MyBatch_09064934_1026000000003

"batchName":"MyBatch_{S|CreateGuid(0)}"


MyBatch_82fcd238-2fb7-44ac-9acc-a13ce406241d

44

HTTP Method

POST

Query Parameters



Request Headers

Accept

Accept-Language

Content-Type

Request Body

{

"captureFlow":<string>, // Required string. CaptureFlow name.

"batchName":<String>, // Required string. Batch name (schema available). Has to be unique.

"batchRootLevel":<integer> // Required integer. 0 based, must be between 1 and 7.

}

Response Headers

Content-Length

Content-Type



application/json

Response Status

200 - OK

401 - Unauthorized

45



Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

},


"title":<string>, // Not localized. This is the batch name given by the creator.



[



],


{

"id":<string>, // Batch handle ID in current session.






"serverBatchId":<string>, // Id created in InputAccel server. Empty if not sent to server.


"batchRootLevel":<integer>,// Level of the root.

"batchPriority":<integer>,// Batch priority. It must be between 0 and 100. If not supplied,

// it will default to 50.



}

}

46


Example Request

POST https://localhost/session/batches HTTP/1.1





Content-Length: 96

{


"batchName":"Batch_{NextId}",

"batchRootLevel":3

}

Example Response

HTTP/1.1 201 OK

Location: https://localhost/session/batches/B32D_2U32D_1


Content-Length: 804

{

"returnStatus":

{

"status":201,

"code":"OK0000",

"message":"",


},



"updated":"2014-04-02T20:29:17.2268520Z",

"links":

[

{

"rel":"self",


},

47

{

"rel":"edit",


}

],

"content":

{

"id":"B32D_2U32D_1",


"status":"C",

"serverBatchId":"",


"batchRootLevel":3,

"lastUpdate":"2014-04-02T20:29:17.2268520Z",

"lastError":""

}

}

17.5 Delete All Batches Operation

This call deletes all batches in the session. Once called, the deleted batches will no longer be available. Deleting batches

accepts a query string parameter, filter, as shown below. Currently, the only value this parameter supports is *, which

means all batches. This is the only filter value currently supported by the Captiva REST Service and provides for the deletion of

all the batches in the session.

HTTP Method

DELETE

Query Parameters


filter=*


48

Request Headers

Accept

Accept-Language

Content-Type

Request Body

None.

Response Headers

Content-Length

Content-Type



application/json

Response Status

200 - OK

401 - Unauthorized



Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

}

49

}


Example Request

DELETE https://localhost/session/batches?filter=* HTTP/1.1



Example Response

HTTP/1.1 200 OK


Content-Length: 148

{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",

"server":"WS-S842b1bccd3fd4d2e86b33a844adaf5c1"

}

}

18 BATCH RESOURCE The Batch Resource allows a user to update an existing batch that has not yet been dispatched with additional data and files.

The Batch Resource also allows standard retrieval and deletion.



self Provides an href to the Batch resource.

50

edit Provides an href to update a Batch resource.

18.2 Operations

The Batch resource supports the following HTTP methods:

Method Description

GET Retrieves the Batch resource.

POST Updates a Batch.

DELETE Deletes a Batch.

18.3 Get Batch Operation

Only the batches in the current session will be accessible.

HTTP Method

GET

Query Parameters



Request Headers

Accept

Accept-Language

Content-Type

51

Request Body

None.

Response Headers

Content-Length

Content-Type



application/json

Response Status

200 - OK

401 - Unauthorized



Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

},


"title":<string>, // Not localized. This is the batch name given by the creator.

"updated":<string>, // Last updated UTC (e.g. 2006-04-17T21:22:48.2698750Z)


[



52

],


{

"id":<string>, // Batch handle ID in current session.






"serverBatchId":<string>, // Id created in InputAccel server. Empty if not sent to server.


"batchRootLevel":<integer>,// Level of the root.



}

}


Example Request

GET https://localhost/session/batches/B32D_2U32D_1 HTTP/1.1




Example Response

HTTP/1.1 200 OK


Content-Length: 804

{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},


53


"updated":"2014-04-03T00:29:17.0000000Z",

"links":

[

{

"rel":"self",


},

{

"rel":"edit",


}

],

"content":

{

"id":"B32D_2U32D_1",


"status":"C",

"serverBatchId":"",


"batchRootLevel":3,

"lastUpdate":"2014-04-03T00:29:17.0000000Z",

"lastError":""

}

}

18.4 Update Batch Operation

The update operation on the batch is used to add nodes, values and submit the batch. Files can be added in bulk or chunked to

the server using offsets. Typical value names that are used for submission to Captiva InputAccel Server might be: (1) the value

name of "OutputImage" for image file values at the page level; (2) the "UimData" value name for submitting UimData at the

document level. These are not necessary, but are the typical mappings used. Please consult the Captiva InputAccel Server

documentation for the Standard Import module to obtain more detailed information on acceptable values.

The update to the batch will take place with HTTP POST, but functions under PATCH semantics with the following behavior:

1. The nodes object provides the structure for the batch. Individual batch nodes can be added, modified, or removed in

subsequent requests with the following behavior:

54

a. Removing a node: If the parentId = -1, then that node is removed along with all its children and values.

b. Adding a new node: If the nodeId contains a new value not previously submitted, then it will be added to the

batch.

c. Replacing a node: If the nodeId and parentId have the same values as a previous submission, then the service

will simply overwrite and move the node to be the last child of the parent.

d. Moving an existing node to another parent: If the nodeId is the same and the parentId is not -1, then the node

will be moved under the new parent as the last child.

2. The values object provides the list of data values that can be added or modified on a node in subsequent requests with

the following behavior:

a. If the valueName represents a valueName that has not been previously submitted, then it is added to the node

represented by the nodeId; otherwise, the value is updated.

b. If the valueType is a file then the offset property is used to write or append the data. If the offset is zero,

then the data is written. If the offset is non-zero, then the data is appended and must match the length of the

data written so far. There can be no gaps between chunks.

3. If the call to update the batch contains the dispatch property with the value of "S" then the batch will be dispatched to

the server for processing and will no longer be available for updates.

HTTP Method

POST

Query Parameters



Request Headers

Accept

Accept-Language

Content-Type

55

Request Body

{

"dispatch":<string>, // Optional string. When the caller has finalized all updates,

// set this to "S" and the batch will be submitted synchronously.

// It will no longer be available for update.

// If left blank "" it will not be submitted.

"nodes": // Optional array. Nodes are processed in given order.

[

{

"nodeId":<integer>, // Required integer. Has to be non-zero.

"parentId":<integer> // Required integer. 0 for parentId implies root node.

// If parentId is -1, then this means delete the node and its

// children.

}

[REPEATABLE] // Subsequent nodes are optional.

],

"values": // Optional array. Values are processed

[ // in the given order and the last writer wins.

{

"nodeId":<integer>, // Required integer. The nodeId must exist.

"valueName":<string>, // Required string. The name of the value.

"value":<object> // Required object. See valueType for valid types.

"valueType":<string> // Required string. Must be one of: "int", "double", "string",

// "bool", "datetime", "file", or "uimdata".

// "int" – value can be integer or string.

// "double" - value can be either number or literal invariant

// culture string.

// "bool" - value must be sent as literal "true" or "false".

// "datetime" - value must be ISO 8601 string.

// "file" - value must be sent as a base64 encoded string

// or a valid fileId.

// "uimdata" – value must be the UimData JSON object.

"offset":<integer>, // Optional integer. Used only if valueType is "file".

// Offset is used to add or replace a chunk. Chunks must be

// added without gaps. First chunk must start at offset 0.

"fileExtension":<string> // Optional string. Used if valueType="file" and offset is 0.

// Examples: "doc", "png", "tif", "tiff", "jpg".

}

[REPEATABLE] // Subsequent values are optional.

]

56

}

Response Headers

Content-Length

Content-Type



application/json

Response Status

200 - OK

401 - Unauthorized



Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

}

}


Example Request

POST https://localhost/session/batches/B32D_2U32D_1 HTTP/1.1



57




{

"dispatch":"S",

"nodes":

[

{

"nodeId":1,

"parentId":0

}

],

"values":

[

{

"nodeId":1,

"valueName":"OutputImage",

"value":"SUkqAAgAAAARAP4ABAABAAAAAAAAAAAEBBAABAAAAmAgAAAIB<Truncating for display>",

"valueType":"file",

"offset":0,

"fileExtension":"tif"

}

]

}

Example Response

HTTP/1.1 200 OK


Content-Length: 148

{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


}

}

58

18.5 Delete Batch Operation

An individual batch in the session that is in the process of being created can be deleted. Once deleted, the batch can no longer

be accessed. If you try to delete a batch that has been already dispatched, then it will only be removed from the temporary

session and will not be deleted on the Captiva InputAccel Server.

HTTP Method

DELETE

Query Parameters



Request Headers

Accept

Accept-Language

Content-Type

Request Body

None.

Response Headers

Content-Length

Content-Type



application/json

59

Response Status

200 - OK

401 - Unauthorized



Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

}

}


Example Request

DELETE https://localhost/session/batches/MyBatch_324_1 HTTP/1.1



Example Response

HTTP/1.1 200 OK


Content-Length: 148

{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


60

}

}

19 DOCUMENT TYPES RESOURCE This resource provides a list of Captiva Document Types available in the system. Document Types are created using the Captiva

Designer.




19.2 Operations

The Document Types resource supports the following HTTP methods:

Method Description

GET Retrieves a list of the Document Types that are available.

19.3 Get Document Types Operation

This operation returns a feed listing all of the Document Types.

HTTP Method

GET

61

Query Parameters



Request Headers

Accept

Accept-Language

Content-Type

Request Body

None.

Response Headers

Content-Length

Content-Type



application/json

Response Status

200 - OK

401 - Unauthorized



Response Body

{


62

{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

},


"title":"DocTypes", // Simple localized title for the feed.

"updated":<string>, // Feed date in UTC in ISO 8601 (e.g. 2006-04-17T21:22:48.2698750Z)


[


],

"entries":

[

{


"title":<string>, // Not localized. Name of the Document Type.



[


]

}

[REPEATABLE] // Other Document Type entries.

]

}


Example Request

GET https://localhost/session/doctypes HTTP/1.1




Example Response

HTTP/1.1 200 OK


63


{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"https://localhost/session/doctypes",

"title":"DocTypes",

"updated":"2014-04-03T00:17:48.0000000Z",

"links":

[

{

"rel":"self",

"href":"https://localhost/session/doctypes"

}

],

"entries":

[

{

"id":"https://localhost/session/doctypes/simpleform",

"title":"SimpleForm",

"updated":"2014-04-03T00:17:48.0000000Z",

"links":

[

{

"rel":"self",

"href":"https://localhost/session/doctypes/simpleform"

}

]

},

<Truncating for display>

]

}

64

20 DOCUMENT TYPE RESOURCE This resource represents a specific Captiva Document Type. A Document Type is created using the Captiva Designer.




20.2 Operations

The Document Type resource supports the following HTTP methods:

Method Description

GET Retrieves a Document Type.

20.3 Get Document Type Operation

This operation returns a Document Type.

HTTP Method

GET

Query Parameters



65

Request Headers

Accept

Accept-Language

Content-Type

Request Body

None.

Response Headers

Content-Length

Content-Type



application/json

Response Status

200 - OK

401 - Unauthorized



Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

},

66

"id":"<URI>", // Entry instance identifier.

"title":<string>, // Name of the Document Type resource.



[


],

"content":

{

"id":<string>, // ID of the Document Type.

"name":<string>, // Name of the Document Type

"locale":<string>, // The culture of the Document Type

"description":<string>, // The description given for the Document Type.

"project":<string>, // The recognition project name associated with the Document

// Type.

"fields": // A list of fields defined.

[

{

"name":<string>, // Name of the field

"isArray":<boolean>, // Whether the field is an array field.

"indexFieldType":<string>, // Type of field (Number, String, Boolean, DateTime)

"sectionName":<string>, // Form section name to which this field belongs. If

// field is an array type, then this is the table name.

"indexLevel":<integer>, // Used only in the context of hierarchical collection

// of documents. The level must be between 1 and 7. If

// the level is higher than 1, then it is assumed that any

// changes must propagate to all siblings in the context

// of ancestor at that higher level.

"confirmKind":<string>, // Confirmation kind. One of: NeverConfirm, AlwaysConfirm,

// ConfirmOnEmpty.

"isReadOnly":<boolean>, // Is the field read only?

"isRequired":<boolean>, // Is this a required field?

"minValue":<object>, // Minimum value for the field. If null, no lower bound.

// In case of datetime, value is represented as double

// .NET OADate. In case of strings, min length.

"maxValue":<object>, // Maximum value for the field. If null, no upper bound.

// In case of datetime, value is represented as double

// .NET OADate. In case of strings, max length.

"restrictionMask":<string>, // The Restriction mask pattern for validating strings.

// Empty means no pattern check. This is a regex expression

// equivalent to restriction mask pattern.

67

"viewFormat":<string>, // Holds the format string for date and time fields. The

// format string utilizes Microsoft .NET Framework 4.5.2

// custom date and time format specifiers. Standard format

// strings are not supported.

// Example: "dd-MM-yyyy hh:mm:ss tt" should be

// rendered by the client as, "27-10-2009 10:47:50 AM".

"checkDateFromNow":<boolean>, // If true and the datatype for the field is DateTime and

// range check is enabled through Min, Max values, the Min

// and Max values are interpreted as time span and are

// validated with reference to Now(). If false and the

// datatype is DateTime then Min and Max are interpreted

// as absolute date time values.

"isPopulationTrigger":<boolean>, // If true, specifies that this field is a dependent

// field for one or more population rules in the

// Document Type definition. This will be false for only

// one-time rules.

"optionsPopulatedBy":<array>, // This is an array of string field names that when any

// of the fields specified changes, then it should cause

// the valid options for this field to change. This is not

// applicable for only one-time rules.

"isCalculationTarget":<boolean>, // If true, specifies that this field is a data

// calculation target field. This will be false for only

// one-time rules.

"extractFirstValue":<boolean>, // If true, then document level extractions will use values

// from the first page where a non-empty value is found;

// otherwise, it will use the field from the last page where

// a non-empty value is found.

"uiControlInfo": // Information about the control for the field.

{

"controlType":<string>, // Control type. Must be one of TextBox, CheckBox, ComboBox.

"labelText":<string>, // The label for the field.

"tooltip":<string>, // The tooltip for the field.

"choices":

[

{

"name":<string>, // The name of the choice.

"value":<string> // The value of the choice.

}

[REPEATABLE] // Other choices.

]

"multiLine":<boolean>, // True for a multiline TextBox; otherwise false.

68

"rectangle": // Rectangle identified by values in the order of

{ // Left, Top, Width, and Height. All values are Pixels

"left":<integer>, // with a resolution of 96 dpi in both X and Y direction.

"top":<integer>,

"width":<integer>,

"height":<integer>

}

"labelRectangle":<array> // Rectangle identified by values in the order of

{ // Left, Top, Width, and Height. All values are Pixels

"left":<integer>, // with a resolution of 96 dpi in both X and Y direction.

"top":<integer>,

"width":<integer>,

"height":<integer>

}

}

}

[REPEATABLE] // Other field entries.

]

}

}


Example Request

GET https://localhost/session/doctypes/simpleform HTTP/1.1




Example Response

HTTP/1.1 200 OK



{

"returnStatus":

{

"status":200,

"code":"OK0000",

69

"message":"",


},

"id":"http://localhost/session/doctypes/simpleform",

"title":"SimpleForm",

"updated":"2014-05-06T20:35:15.9864335Z",

"links":

[

{

"rel":"self",

"href":"http://localhost/session/doctypes/simpleform"

}

],

"content":

{

"id":"SimpleForm",

"name":"SimpleForm",

"locale":"en-US",

"description":"",

"project":"Test",

"fields":

[

{

"name":"TextBox1",

"isArray":false,

"indexFieldType":"String",

"sectionName":"Main",

"indexLevel":0,

"confirmKind":"NeverConfirm",

"validationExpression":null,

"isReadOnly":false,

"isRequired":true,

"minValue":null,

"maxValue":null,

"restrictionMask":"",

"viewFormat":"",

"checkDateFromNow":false,

"isPopulationTrigger":false,

"optionsPopulatedBy":[],

"isCalculationTarget":false,

"extractFirstValue":true,

70

"uiControlInfo":

{

"controlType":"TextBox",

"labelText":"TextBox1",

"tooltip":"TextBox1",

"choices":null,

"multiLine":false,

"rectangle":

{

"left":0,

"top":0,

"width":50,

"height":50

},

"labelRectangle":

{

"left":0,

"top":0,

"width":0,

"height":0

}

}

},

{

"name":"TextBox2",

"isArray":false,



"indexLevel":0,



"isReadOnly":false,

"isRequired":true,

"minValue":null,

"maxValue":null,


"viewFormat":"",





71


"uiControlInfo":

{


"labelText":"TextBox2",


"choices":null,

"multiLine":false,

"rectangle":

{

"left":0,

"top":60,

"width":50,

"height":50

},

"labelRectangle":

{

"left":0,

"top":0,

"width":0,

"height":0

}

}

},

{

"name":"TextBox3",

"isArray":false,



"indexLevel":0,



"isReadOnly":false,

"isRequired":true,

"minValue":null,

"maxValue":null,


"viewFormat":"",




72



"uiControlInfo":

{


"labelPosition":"Left",


"choices":null,

"multiLine":false,

"rectangle":

{

"left":0,

"top":120,

"width":50,

"height":50

},

"labelRectangle":

{

"left":0,

"top":0,

"width":0,

"height":0

}

}

}

]

}

}

21 FILES RESOURCE The Files resource is used to create a stage file. Ad Hoc Services can use stage files referenced in Service Requests and so can

Batches. The benefit of creating a stage file is that it allows them to be referenced in more than one Service Request for an Ad

Hoc Service as well as easy reference during Batch updates. In addition, a stage file can be sent whole or chunked using binary

or base64 encoding to the server to allow the client better control over sending large files (see the File resource below for an

example). All file submissions regardless of the type have a 100mb limit. Responses to file uploads will always provide a unique

file ID in which to reference the file for later use in Service Requests.

73


None.

21.2 Operations

The Files resource supports the following HTTP methods:

Method Description

POST Creates a stage file.

DELETE Deletes stage files.

21.3 Post to Create a Stage File Operation

You can only create one stage file at a time. To create a stage file, you simply provide a POST to the files URI with the file

information you want stored. Upon the first POST a unique fileId will be created by the server. File data can be posted either

in base64 encoding as a JSON post or as a binary to the server.

If you need to chunk this in pieces to the server, then subsequent requests must be made to the URI represented by the src

property or the URI provided by the Location header returned from the first chunk. Additional chunks append to the file and you

can always retry/re-post the last chunk. The chunks need to be posted without gaps in order to be successful.

HTTP Method

POST

Query Parameters



74

Request Headers

Accept

Accept-Language

Content-Type

Content-Range

Supported Media Types for Creating Stage Files

application/json

application/msword

application/octet-stream

application/rtf

application/pdf


image/jpeg

image/png

image/tiff

text/plain

Request Body

There are two ways to create a stage file:

Create the stage file using a JSON post with base64 encoding.

Post the file as binary using the appropriate Content-Type.

Request Body Using JSON

{

"data":<string>, // The file data must be sent as a base64 encoded string.

"contentType":<string>, // Optional. The acceptable Content-Type for the file. If not provided,

// then application/octet-stream will be assumed.

"offset":<integer> // Optional. Only used for chunking. The offset has to be counted in bytes

75

// and is used to add or retry a chunk. Chunks must be added without gaps.

}

Request Body Using Binary

<Binary data>

Response Headers

Content-Length

Content-Type



application/json

Response Status

200 – OK

401 – Unauthorized



Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

},

"id":<fileid>, // The file handle ID in the current session.

"contentType":<string>, // The media type for the file.

"src":"<URI>", // URI for direct access to file data.

"updated":<string> // ISO 8601 date-time string of the last update.

76

}

Example Request and Response for Binary Creation

Example Request

POST https://localhost/session/files HTTP/1.1




Content-Type: image/jpeg


<Binary here: Binary data not shown>

Example Response

HTTP/1.1 201 Created

Location: https://localhost/files/f_128b1931b51643979a2580f5820dec4fjpg


Content-Length: 362

{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"f_128b1931b51643979a2580f5820dec4ftif",

"contentType":"image/jpeg",

"src":"https://localhost/session/files/f_128b1931b51643979a2580f5820dec4fjpg",

"updated":"2014-03-31T22:22:35.1995491Z"

}

Example Request and Response for base64 Chunking

Please see the example in the File resource below.

77

21.4 Delete All Files Operation

This call deletes all stage files in the session including those returned by service calls. Once called, the deleted files will no

longer be available. Deleting files accepts a query string parameter, filter, as shown below. Currently, the only value this

parameter supports is *, which means all files. This is the only filter value currently supported by the Captiva REST Service and

provides for the deletion of all the files in the session.

HTTP Method

DELETE

Query Parameters


filter=*


Request Headers

Accept

Accept-Language

Request Body

None.

Response Headers

Content-Length

Content-Type



application/json

78

Response Status

200 – OK




Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

}

}


Example Request

DELETE https://localhost/session/files?filter=* HTTP/1.1



Example Response

HTTP/1.1 200 OK


Content-Length: 148

{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


79

}

}

22 FILE RESOURCE A stage file is created by using the Files resource. A stage file can be appended, retrieved, or deleted.


None.

22.2 Operations

The File resource supports the following HTTP methods:

Method Description

GET Retrieves a stage file.

POST Appends or retries a stage file chunk.

DELETE Deletes a stage file.

22.3 Get File Operation

Retrieving an actual file that was previously POSTed is simply performed by executing a GET on the files URI with the fileId as

shown below. This will return the actual file data.

HTTP Method

GET

80

Query Parameters



Request Headers

Accept

Accept-Language

Request Body

None.

Response Headers

Content-Length

Content-Type


application/msword


application/rtf

application/pdf

image/jpeg

image/png

image/tiff

text/plain

Response Status

200 – OK


81



Response Body

Binary data.


Example Request

GET https://localhost/session/files/f_128b1931b51643979a2580f5820dec4fjpg HTTP/1.1


Example Response

HTTP/1.1 200 OK




22.4 Post a Chunk File Operation

Chunking a file in pieces to the server requires that the POST be made to the URI represented by the src property or the URI

provided by the Location header returned from the first chunk. Additional chunks append to the file and you can always

retry/re-post the last chunk. Chunking requires the data for the file to be sent in base64 or binary encoding. The chunks need

to be posted without gaps in order to be successful.

HTTP Method

POST

Query Parameters



82

Request Headers

Accept

Accept-Language

Content-Type

Content-Range

Supported Media Types for Creating Stage Files

application/json

application/msword


application/rtf

application/pdf


image/jpeg

image/png

image/tiff

text/plain

Request Body

{

"data":<string>, // The file data must be sent as a base64 encoded string.

"contentType":<string>, // Optional. The acceptable Content-Type for the file. If not provided,

// then application/octet-stream will be assumed.

"offset":<integer> // Optional. Only used for chunking. The offset has to be counted in bytes

// and is used to add or retry a chunk. Chunks must be added without gaps.

}

Request Body Using Binary

<Binary data>

83

Response Headers

Content-Length

Content-Type



application/json

Response Status

200 – OK




Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

},

"id":<fileid>, // The file handle ID in the current session.

"contentType":<string>, // The media type for the file.

"src":"<URI>", // URI for direct access to file data.

"updated":<string> // ISO 8601 date-time string of the last update.

}

Example Request and Response for base64 Chunking

Example of First Chunk Request


84





Content-Length: 119

{

"data":"VGhpcyBpcyBvbmx5IGFuIGV4YW1wbGUgb2YgdGhlIGZpcnN0IGNodW5rLg",


"offset":0

}

Example Response




Content-Length: 362

{

"returnStatus":

{

"status":201,

"code":"OK0000",

"message":"",


},

"id":"f_128b1931b51643979a2580f5820dec4fjpg",



"updated":"2014-03-31T22:22:35.1995491Z"

}

Example of Second Chunk Request

POST https://localhost/session/files/f_128b1931b51643979a2580f5820dec4fjpg HTTP/1.1





Content-Length: 120

85

{

"data":"VGhpcyBpcyBvbmx5IGFuIGV4YW1wbGUgb2YgdGhlIHNlY29uZCBjaHVuaw",


"offset":43

}

Example Response

HTTP/1.1 200 OK


Content-Length: 362

{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"f_128b1931b51643979a2580f5820dec4fjpg",



"updated":"2014-03-31T22:22:36.1995491Z"

}

Example Request and Response for Binary Chunking

Example of First Chunk Request







Content-Range: bytes 0-19999/60200


86

Example Response




Content-Length: 362

{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"f_128b1931b51643979a2580f5820dec4ftif",



"updated":"2014-03-31T22:22:35.1995491Z"

}

Example of Second Chunk Request

POST https://localhost/session/files/f_128b1931b51643979a2580f5820dec4fjpg HTTP/1.1






Content-Range: bytes 20000-60199/60200


Example Response

HTTP/1.1 200 OK


Content-Length: 362

{

"returnStatus":

{

87

"status":200,

"code":"OK0000",

"message":"",


},

"id":"f_128b1931b51643979a2580f5820dec4fjpg",



"updated":"2014-03-31T22:22:36.1995491Z"

}

22.5 Delete File Operation

An individual file can be deleted. Once deleted, the file can no longer be accessed.

HTTP Method

DELETE

Query Parameters



Request Headers

Accept

Accept-Language

Request Body

None.

Response Headers

Content-Length

Content-Type

88



application/json

Response Status

200 – OK




Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

}

}


Example Request

DELETE https://localhost/session/files/f_128b1931b51643979a2580f5820dec4fjpg HTTP/1.1



Example Response

HTTP/1.1 200 OK


Content-Length: 148

{

89

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


}

}

23 HOME DOCUMENT RESOURCE The Home Document is an entry point to the Captiva REST Service. It is available to any caller. It is retrieved by performing an

HTTP GET on the base installation path. So for example if the REST service was installed into https://localhost, then performing

a GET on this URI would return the Home Document. Its main purposes it to provide discovery of the URIs necessary to interact

with the service. All clients must start from the Home Document and follow the hrefs given in the link relations to the resources

desired. This is important to ensure that your client applications will always work regardless of the URI changes that may take

place under different deployment configurations of the service.


Link Relations are used to access other resources and perform specific operations in the Captiva REST Service.


about Provides an href to the Product Information resource. This resource

display product information about the Captiva REST Service.

http://identifiers.emc.com/linkrel/data-batches Provides an href to the Batches resource. This resource allows you access

to create a batch in the Captiva InputAccel Server.

http://identifiers.emc.com/linkrel/doctypes Provides an href to the Document Types resource. This resource allows

you access to the Document Types that are available in the system.

http://identifiers.emc.com/linkrel/files Provides an href to the Files resource. This resource allows you to

generate stage files for Service Requests.

90

http://identifiers.emc.com/linkrel/services Provides an href to the Services resource. This resource allows you to

generate Service Requests for Captiva's Ad Hoc Services.

http://identifiers.emc.com/linkrel/session Provides an href to the Session resource to login or logoff from the

service.

http://identifiers.emc.com/linkrel/tables Provides an href to the Tables resource. This resource provides access to

data and lists maintain by the Captiva platform.

23.2 Operations

The Home Document resource supports the following HTTP methods:

Method Description

GET Retrieves the Home Document resource.

23.3 Get the Home Document

The HTTP method, query parameters, and headers that are supported by this resource are described below.

HTTP Method

GET

Query Parameters



Request Headers

Accept

91

Accept-Language

Request Body

None.

Response Headers

Content-Length

Content-Type


application/json-home

application/json

Response Status

200 - OK



Response Body

{

"resources":

{

"about":

{

"href": "<URI>",

"hints":

{

"allow":["GET"],


}

},

"http://identifiers.emc.com/linkrel/data-batches":

{

"href": "<URI>",

92

"hints":

{



}

},

"http://identifiers.emc.com/linkrel/doctypes":

{

"href": "<URI>",

"hints":

{

"allow":["GET"],


}

},

"http://identifiers.emc.com/linkrel/files":

{

"href": "<URI>",

"hints":

{

"allow":["POST", "DELETE"],


}

},

"http://identifiers.emc.com/linkrel/services":

{

"href": "<URI>",

"hints":

{

"allow":["GET"],


}

},

"http://identifiers.emc.com/linkrel/session": // Link relation for this resource.

{

"href": "<URI>", // Location of this resource.

"hints": // Hints provide information on

{ // allowable verbs and representations.



}

93

},

"http://identifiers.emc.com/linkrel/tables":

{

"href": "<URI>",

"hints":

{

"allow":["GET"],


}

}

}

}


Example Request

GET https://localhost HTTP/1.1

Accept: application/json-home, application/json


Example Response

HTTP/1.1 200 OK

Content-Type: application/json-home; charset=utf-8


{

"resources":

{

"about":

{

"href": "https://localhost/about",

"hints":

{

"allow":["GET"],


}

},

"http://identifiers.emc.com/linkrel/data-batches":

{

94

"href": "https://localhost/session/batches",

"hints":

{



}

},

"http://identifiers.emc.com/linkrel/doctypes":

{

"href": "https://localhost/session/doctypes",

"hints":

{

"allow":["GET"],


}

},

"http://identifiers.emc.com/linkrel/files":

{

"href": "https://localhost/session/files",

"hints":

{

"allow":["POST", "DELETE"],


}

},

"http://identifiers.emc.com/linkrel/services":

{

"href": "https://localhost/session/services",

"hints":

{

"allow":["GET"],


}

},

"http://identifiers.emc.com/linkrel/session":

{

"href": "https://localhost/session",

"hints":

{



95

}

},

"http://identifiers.emc.com/linkrel/tables":

{

"href": "https://localhost/tables",

"hints":

{

"allow":["GET"],


}

},

}

}

24 SESSION RESOURCE The session will provide the URIs for the login and logoff operations. This resource is available to any caller. Login and Logoff

each have separate link relations that provide a corresponding href that should be used for the operation.




http://identifiers.emc.com/linkrel/login This is the link relation that references the URI to use for performing a

login. This is always an available link relation whether or not the user is

already logged in.

http://identifiers.emc.com/linkrel/logoff This is the link relation that references the URI to use for performing a

logoff. This is always an available link relation whether or not the user is

already logged in.

96

24.2 Operations

The Session resource supports the following HTTP methods:

Method Description

GET Retrieves the Session resource.

POST Provides a login operation.

DELETE Provides a logoff operation.

24.3 Get the Session

HTTP Method

GET

Query Parameters



Request Headers

Accept

Accept-Language

Request Body

None.

Response Headers

Content-Length

97

Content-Type



application/json

Response Status

200 - OK



Response Body

{

"id":"<base>/session",

"title":"Session", // Localized based on Accept-Language.

"links":

[


{"rel":"http://identifiers.emc.com/linkrel/login", "<URI>"},

{"rel":"http://identifiers.emc.com/linkrel/logoff", "<URI>"}

]

}


Example Request

GET https://localhost/session HTTP/1.1



Example Response

HTTP/1.1 200 OK


Content-Length: 334

98

{

"id":"https://localhost/session",

"title":"Session",

"links":

[

{"rel":"self", "href":"https://localhost/session"},

{"rel":"http://identifiers.emc.com/linkrel/login", "href":"https://localhost/session"},

{"rel":"http://identifiers.emc.com/linkrel/logoff", "href":"https://localhost/session"}

]

}

24.4 Login Operation

The Login Operation should take place under a secure connection (HTTPS/SSL) so that the credential submission is encrypted.

Upon successful login a session will be created referencing a Captiva Ticket for further communication under the same session.

The Captiva Ticket is provided in the response in two places. It is returned as a Secure HttpOnly cookie, which will

automatically be destroyed when the browser is closed. Secondly, it is also returned in the response body assigned to the

ticket property, which is useful for clients that need better control of the ticket.

There are new values for the licenseKey and applicationId documented below for Captiva REST Services 2.0. If you need to

take advantage of the new features available in version 2.0, then you must use the new keys and be subject to the new

licensing rules. If you use the older licenseKey and applicationId values, then these will still work for features in version

1.0, but will fail if any request is made for 2.0 features.

HTTP Method

POST

Query Parameters



Request Headers

Accept

99

Accept-Language

Content-Type

Request Body

{

"culture":<string>, // Required string. RFC 4646 culture code supported by Captiva.

// If non-empty, overrides accept language.

"licenseKey":<string>, // Required string. License key string. In order to use any of

// the new REST Services 2.0 features, then this should be

// LICE075-D09A-64E3.

"deviceId":<string>, // Required string. A unique ID for this device.

"applicationId":<string>, // Required string. In order to use any of the new

// REST Services 2.0 features, then this should be

// APP3075-D09A-59C8.

"username":<string>, // Required for default authentication (clear text).

"password":<string>, // Required for default authentication (clear text).

"extraAuthInfo":<string> // Required for custom authentication.

}

Response Headers

Content-Length

Content-Type

Set-Cookie



application/json

Response Status

200 - OK

401 - Unauthorized



100

Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

},

"ticket":<string> // The session ticket to be used for subsequent requests.

}


Example Request

POST https://localhost/session HTTP/1.1




Content-Length: 204

{

"culture":"en-US",

"licenseKey":"LICE075-D09A-64E3",

"deviceId":"SomeDeviceID",

"applicationId":"APP3075-D09A-59C8",

"username":"John",

"password":"mypassword1",

"extraAuthInfo":""

}

Example Response

HTTP/1.1 200 OK

Set-Cookie: CPTV-TICKET=<ticket goes here>; Path=/; Secure; HttpOnly


Content-Length: 435

{

101

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"ticket":<ticket goes here>

}

24.5 Logoff Operation

As long as the request is well-formed, it will always return HTTP status code 200 whether or not the ticket is valid or invalid.

HTTP Method

DELETE

Query Parameters



Request Headers

Accept

Accept-Language

Cookie

CPTV-TICKET

Request Body

None.

102

Response Headers

Content-Length

Content-Type



application/json

Response Status

200 - OK


Response Body

None.


Example Request

DELETE https://localhost/session HTTP/1.1



Example Response

HTTP/1.1 200 OK

25 TABLES RESOURCE The server maintains different tables that provide information about key pieces of data to authenticated users. These tables are

provided in the Tables resource.

103




self Provides a reference to the feed or entry depending on its location.

25.2 Operations

The Tables resource supports the following HTTP methods:

Method Description

GET Retrieves the Tables resource.

25.3 Get the Tables Feed

HTTP Method

GET

Query Parameters



Request Headers

Accept

Accept-Language

104

Request Body

None.

Response Headers

Content-Length

Content-Type



application/json

Response Status

200 – OK

401 - Unauthorized



Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

},


"title":"Tables", // Simple localized title for the feed.


[

{"rel":"self", "href":"<URI>"} // The href will match the URL used to retrieve this.

],

"entries":

105

[

{


"title":<string>, // Display name of the table.

"updated":<string>, // Last updated UTC (e.g. 2006-04-17T21:22:48.2698750Z)


[


]

}

[REPEATABLE]

]

}


Example Request

GET https://localhost/tables HTTP/1.1




Example Response

HTTP/1.1 200 OK


Content-Length: 602

{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"https://localhost/tables",

"title":"Tables",

"links":

[

106

{"rel":"self", "href":"https://localhost/tables"}

],

"entries":

[

{

"id":"https://localhost/tables/captureflows",

"title":"CaptureFlows",

"updated":"2014-03-31T22:20:07.8948201Z",

"links":

[

{"rel":"self", "href":"https://localhost/tables/captureflows"}

]

}

]

}

26 TABLE RESOURCE The server maintains different tables that provide information about key pieces of data to authenticated users. These tables are

listed in the Tables resource.




self Provides a reference to the current entry.

26.2 Operations

The Table resource supports the following HTTP methods:

107

Method Description

GET Retrieves the Table resource.

26.3 Get a Table Operation

HTTP Method

GET

Query Parameters


sort


view

Each table supports query options for views and sorting. These query operations can be combined with the ampersand.

Query

Parameter Description

Data

Type Syntax

sort Used to sort the result. String ?sort=<field [desc | asc]>[,REPEATABLE]

Note: Sort is followed by a comma-separated list of fields

and each field can have an optional sort order separated by

a space. If the sort order is not specified, then the default

sort order is ASC. If this query parameter is not provided at

all, then the result will be sorted based on its first column in

ascending order.

view Fields or properties to return. String ?view=<:view-name | comma-delim-field-list>

Note: A view is followed by either a view name preceded by

108

a colon or a list of fields. These are mutually exclusive. Two

predefined views are provided: ":all" and ":default". Both of

these are equivalent for Captiva and will return all columns

for the data. If this query parameter is not provided, then

the result will include all column data.

Examples:

GET https://localhost/tables/captureflows?<query-options>

GET https://localhost/tables/captureflows?view=name,createtime&sort=createtime asc

GET https://localhost/tables/captureflows?view=:default

GET https://localhost/tables/captureflows?view=createtime,name

GET https://localhost/tables/captureflows?sort=name

Request Headers

Accept

Accept-Language

Request Body

None.

Response Headers

Content-Length

Content-Type



application/json

Response Status

200 – OK

109


404 - Not Found



Response Body

{


{

"status":<integer>,

"code":<string>,

"message":<string>,

"server":<string>

},


"title":<string>, // Localized display name of the feed.



[


],


{

"id":<string>, // Unique identifier for the table.

"tableName":<string>, // Localized display name of the table.

"fieldNames":[[<string-name1>, ...]], // A comma-delimited list of names for each column.

"rows":

[

[[<object-field1>, <object-field2>, ...]], // Array of objects JSON encoded (string,

[[<object-field1>, <object-field2>, ...]], // int, array, object, etc).

[[<object-field1>, <object-field2>, ...]] // Ex. [123,"text",[1,2,3],{"name":"value"}]

[REPEATABLE]

]

}

}

110


Example Request

GET https://localhost/tables/captureflows HTTP/1.1




Example Response

HTTP/1.1 200 OK



Content-Length: 648

{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"https://localhost/tables/captureflows",

"title":"CaptureFlows",

"updated":"2014-03-31T22:22:35.1995491Z",

"links":

[

{"rel":"self", "href":"https://localhost/tables/captureflows"}

],

"content":

{

"id":"captureflows",

"tableName":"CaptureFlows",

"fieldNames":["Name","CreateTime"],

"rows":

[

["NewLoanApplication","2013-04-01T00:43:12.0000000Z"],

["DepositCheck","2013-02-22T09:12:43.0000000Z"]

]

111

}

}

AD HOC SERVICE DESCRIPTIONS

There are several Ad Hoc Services available for use. Each Ad Hoc Service will perform operations based on the service

properties that were given. In the sections that follow, each Ad Hoc Service will be described along with the available service

properties and expectations concerning the data that can be submitted.

27 UIM DATA INFORMATION OBJECT The UIM data information object is returned by some Ad Hoc Services. This object contains information about the Captiva

Document Type associated with a set of one or more images along with the data for the fields. This object is defined as follows.

{

"docType":<string>, // The name of the document type.

"locale":<string>, // The culture code.

"flaggedReason":<string>, // Specifies the reason for the validation error. This will

// only be filled on "Populate" and "PopulateAndValidate"

// commands if there is an error. Otherwise, it is null.

"nodeList":

[

{

"name":<string>, // Name of the field.

"isArray":<bool>, // True if this is an array field; otherwise, false.

"indexFieldType":<string>, // Specifies the type of field. Will be one of: "number",

// "string", "boolean", "datetime".

"labelText":<string>, // The label for the field to show in the UI.

"isRequired":<boolean>, // True if this is a required field; otherwise, false.

"controlType":<string>, // This will be the type of UI control. Will be one of:

// "TextBox", "ChkBox", "ComboBox".

"data": // Contains all the data for the field(s).

[

{

"arrayIndex":<integer>, // If the field is an array field, this is the array index.

"value":<object>, // The value of the field.

112

"fieldError": // This contains the error information for the field.

{

errorCode:<integer>, // The error code assigned to the field.

recoverable:<boolean>,// True if the error is recoverable; otherwise, false.

message:<string> // The error message.

},

"mustConfirm":<boolean>, // True if the user must confirm; otherwise, false.

"choices": // Provides the list of choices for the control.

[

{

"name":<string>, // The name of the choice.

"value":<string> // The value of the choice.

}

[REPEATABLE]

]

}

[REPEATABLE]

]

}

]

}

28 CLASSIFY SERVICE The Classify Service will perform Classification on the images submitted and return available Captiva Document Type and

Template information if successful.

28.1 Service Name

Classify

113

28.2 Service Properties

name value

"Project" Required String. Recognition project name as specified in Captiva Designer. If

omitted, then an error is returned.

28.3 Request Items

Number of Request Items

This Ad Hoc Service supports one or more items.

Values Per Request Item

No values are needed or used.

Files Per Request Item

There can only be one file per request item object. It can either be an embedded file or a reference to a file ID previously

posted to the Files Resource. The File Type property for the file is ignored for this service.

28.4 Result Items

The result item objects will be put in the same order as the request items that were submitted. This can be correlated using the

nodeId property if needed.

Values Per Result Item

name value

"DocumentTypeName" String. This is the Captiva Document Type name. e.g. "Form1040EZ". Empty if no match was

found.

114

"TemplateId" String. This is the image template ID provided by the Classify Ad Hoc Service. This will be

"-1" if no match was found.

"DocBoundary" Number. Indicates whether this page defines a document boundary. Valid values are the

following integers:

0 - means no document boundary and indicates a page other than first and last page.

1 - means this is the first page of the document.

2 - means this is the last page of the document.

Files Per Result Item

No files are returned by this Ad Hoc Service.

28.5 Example Request and Response

Example Request

POST https://localhost/session/services/classify HTTP/1.1






{

"serviceProps":

[

{

"name":"Project",

"value":"Sample1"

}

],

"requestItems":

[

{

"nodeId":1,

115

"files":

[

{




}

]

}

]

}

Example Response

HTTP/1.1 200 OK


Content-Length: 814

{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"REQ1",

"serviceName":"Classify",



"resultItems":

[

{

"nodeId":1,

"errorCode":"",

"errorMessage":"",

"values":

[

{

"name":"DocumentTypeName",

"value":"Doodads"

116

},

{

"name":"TemplateId",

"value":"1"

},

{

"name":"DocBoundary",

"value":1

}

]

}

]

}

29 CLASSIFY EXTRACT DOCUMENT SERVICE The Classify Extract Document Service will perform classification and extraction on each item submitted and return an UIM

object containing information from the result of classification and extraction.

29.1 Service Name

ClassifyExtractDocument


name value



117

29.3 Request Items






Each item can have one or more files. It can either be an embedded file or a reference to a file ID previously posted to the Files

Resource. The File Type property for the file is ignored for this service.

If the request item contains more than one image, then the document type associated with the first classified page is used for

the document. The extraction results for all pages are merged into a single document. If a given field has conflicting values

from different pages, then the value is set according to the "Extract Page" visual property for that field in the document type

definition.

29.4 Result Items




name value

"UimData" Object. This is a UIM data information object, which contains the result of the

classification and extraction operations.



118


Example Request

POST https://localhost/session/services/classifyextractdocument HTTP/1.1






{

"serviceProps":

[

{

"name":"Project",

"value":"Sample1"

}

],

"requestItems":

[

{

"nodeId":1,

"files":

[

{




}

]

}

]

}

Example Response

HTTP/1.1 200 OK



{

119

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"REQ1",

"serviceName":"ClassifyExtractDocument",



"resultItems":

[

{

"nodeId":1,

"errorCode":"",

"errorMessage":"",

"values":

[

{

"name":"UimData",

"value":

{

"docType":"Doodads",

"locale":"en-US",

"flaggedReason":null,

"nodeList":

[

{

"name":"Field1",

"isArray":false,

"indexFieldType":"string",

"labelText":"Field1",

"isRequired":false,


"data":

[

{

"arrayIndex":0,

"value":"My field data.",

"fieldError":null,

120

"mustConfirm":false,

"choices":null

}

]

}

]

}

}

]

}

]

}

30 CLASSIFY EXTRACT PAGE SERVICE The Classify Extract Page Service will perform classification and extraction on each item submitted and return a UIM object

containing information from the result of classification and extraction.

30.1 Service Name

ClassifyExtractPage


name value



121

30.3 Request Items








30.4 Result Items




name value

TemplateId String. This will return the template ID if successfully classified. Otherwise, the

service will return "-1".


classification and extraction operations.



122


Example Request

POST https://localhost/session/services/classifyextractpage HTTP/1.1






{

"serviceProps":

[

{

"name":"Project",

"value":"Sample1"

}

],

"requestItems":

[

{

"nodeId":1,

"files":

[

{




}

]

}

]

}

Example Response

HTTP/1.1 200 OK



{

123

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"REQ1",

"serviceName":"ClassifyExtractPage",



"resultItems":

[

{

"nodeId":1,

"errorCode":"",

"errorMessage":"",

"values":

[

{

"name":"TemplateId",

"value":"1"

},

{

"name":"UimData",

"value":

{


"locale":"en-US",


"nodeList":

[

{

"name":"Field1",

"isArray":false,



"isRequired":false,


"data":

[

124

{

"arrayIndex":0,


"fieldError":null,


"choices":null

}

]

}

]

}

}

]

}

]

}

31 CONVERT IMAGES SERVICE The Convert Images Ad Hoc Service provides image conversion capability as defined by an image conversion profile defined in

Captiva Designer.

31.1 Service Name

ConvertImages


name value

"PdfAuthor" String. This is for PDF generation only and supplies the Author property for the

PDF.

125

"PdfKeywords" String. This is for PDF generation only and supplies the Keywords property for the

PDF.

"Profile" Required String. The Image conversion profile name to use for the conversion.

"ReturnFileDataInline" Boolean. If true, then the resulting file is returned inline in the result item as a

base64 encoded file. If omitted or false, then the resulting file is returned as a fileId

and can be retrieved through the Files resource.

"PdfSubject" String. This is for PDF generation only and supplies the Subject property for the

PDF.

"PdfTitle" String. This is for PDF generation only and supplied the Title property for the PDF.

31.3 Request Items




No values are necessary or used.



Resource.

The File Type property for the file must specify the file extension for the file, such as: "tif", "png", "jpg", etc. This is used by the

Convert Images Ad Hoc Service for further typing of the file.

31.4 Result Items

The result item objects will be put in the same order as the request items that were submitted.

126


No values are returned in the result item objects.


There will be one or more files returned based on what was submitted.


Example Request

POST https://localhost/session/services/convertimages HTTP/1.1






{

"serviceProps":

[

{

"name":"Profile",

"value":"ImageProfile1"

}

],

"requestItems":

[

{

"nodeId":1,

"files":

[

{



"contentType":"image/tiff",

"fileType":"tif"

}

]

127

}

]

}

Example Response

HTTP/1.1 200 OK


Content-Length: 788

{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"REQ1",

"serviceName":"ConvertImages",



"resultItems":

[

{

"nodeId":1,

"errorCode":"",

"errorMessage":"",

"files":

[

{


"value":"f_128b1561b51643979a2580f5820abc4ftif",

"src":"https://localhost/session/files/f_128b1561b51643979a2580f5820awe8qtif",


}

]

}

]

}

128

32 EXTRACT DOCUMENT SERVICE The Extract Document Service will perform extraction on each item submitted and return a UIM object containing information

from the result.

32.1 Service Name

ExtractDocument


name value



32.3 Request Items




name value

"DocumentTypeName" String. The Document Type name to be used for extraction. This is ignored if the

TemplateIds property is passed.

"TemplateIds" Array of Strings. The image template IDs assigned in the recognition project that

are used for extraction. If not supplied, then the DocumentTypeName must be

129

specified.

RepeatLastTemplate Boolean. If true and if the TemplateIds array has fewer entries than the request

item has files, the last template ID is applied to the remaining files in the request

item.



Resource. The File Type property for the file is ignored for this service.

If the TemplateIds property is not included in the request, more than one image is sent, and the DocumentTypeName is

specified, then the images are processed as follows. First, the templates in the specified document type are ordered by name

(not ID). Then, the first template in the list is used for the first file in the request item, the second template in the list is used

for the second file in the request item, and so forth. If the request item contains more images than there are templates in the

document type, then the extra images are not processed for data extraction.

32.4 Result Items




name value


extraction operation.



130


Example Request

POST https://localhost/session/services/extractdocument HTTP/1.1






{

"serviceProps":

[

{

"name":"Project",

"value":"Sample1"

}

],

"requestItems":

[

{

"nodeId":1,

"values":

[

{


"value":"Doodads"

},

{

"name":"TemplateIds",

"value":null

},

{

"name":"RepeatLastTemplate",

"value":false

}

],

"files":

[

{

131




}

]

}

]

}

Example Response

HTTP/1.1 200 OK



{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"REQ1",

"serviceName":"ExtractDocument",



"resultItems":

[

{

"nodeId":1,

"errorCode":"",

"errorMessage":"",

"values":

[

{

"name":"UimData",

"value":

{


"locale":"en-US",

132


"nodeList":

[

{

"name":"Field1",

"isArray":false,



"isRequired":false,

"controlType":"TextBox"

"data":

[

{

"arrayIndex":0,


"fieldError":null,


"choices":null

}

]

}

]

}

}

]

}

]

}

33 EXTRACT PAGE SERVICE The Extract Page Service will perform extraction on each item submitted and return a UIM object containing information from

the result.

33.1 Service Name

ExtractPage

133


name value



33.3 Request Items




name value

"DocumentTypeName" String. The Document Type name to be used for extraction. This is optional if the

TemplateId property is passed.

"PageIndex" Number. The zero-based page index within Document Type. If omitted, then it

defaults to 0. This is optional if the TemplateId property is passed.

"TemplateId" String. The image template ID assigned in the recognition project that should be

used for extraction. If not supplied, then the DocumentTypeName should be

specified.




If the DocumentTypeName and PageIndex are specified, then the data will be extracted based on the index of the template in

the order of the template names (not IDs) in the specified document type. If the PageIndex is greater than the number of

templates in the document type, then the image is not processed for data extraction.

134

33.4 Result Items




name value


extraction operation.




Example Request

POST https://localhost/session/services/extractpage HTTP/1.1






{

"serviceProps":

[

{

"name":"Project",

"value":"Sample1"

}

],

"requestItems":

[

{

135

"nodeId":1,

"values":

[

{


"value":"Doodads"

}

],

"files":

[

{




}

]

}

]

}

Example Response

HTTP/1.1 200 OK



{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"REQ1",

"serviceName":"ExtractPage",



"resultItems":

[

{

136

"nodeId":1,

"errorCode":"",

"errorMessage":"",

"values":

[

{

"name":"UimData",

"value":

{


"locale":"en-US",


"nodeList":

[

{

"name":"Field1",

"isArray":false,



"isRequired":false,


"data":

[

{

"arrayIndex":0,


"fieldError":null,


"choices":null

}

]

}

]

}

}

]

}

]

}

137

34 FULL PAGE OCR SERVICE The Full Page OCR Ad Hoc Service will provide full page OCR processing on submitted images and return the OCR content in the

specified output type.

34.1 Service Name

FullPageOCR


name value

OcrEngineName Required String. This specifies the OCR engine name to use. This version only

supports the value "Nuance".

AutoRotate Boolean. This is an optional value specifying whether auto rotation should be

enabled for the engine. The default is true.

Language String. This optional value specifies the language for the engine. The default is

"Automatic". It can be any of the following values:

"Automatic", "BrazilianPortuguese", "English", "French", "German", "Italian",

"Japanese", "Korean", "Russian", "SimplifiedChinese", "Spanish".

Tradeoff String. This optional value specifies the tradeoff value for the engine to determine

accuracy in relation to speed under which the OCR engine should perform. The

default is "Accurate". This can be one of the following values:

"Accurate", 'Balanced", "Fast".

138

34.3 Request Items




name value

OutputType Required String. This setting specifies the OCR output type for the request item. It

can be one of these values: "Pdf", "Rtf", "Text", "Word".

The additional values you can make on the request item are based on what is assigned to the OutputType. These are each

explained below by OutputType.

Values for OutputType "Pdf"

Name value

Format String. Can be one of these optional values: "Classic", "Edited', "ImageOnText",

"ImageSubstitutes". If not provided, the default value is "Classic".

Values for OutputType "Rtf"

name value

Version String. There is only one supported value at this time, which is optional. It is:

"Word2000". If not provided, it will default to "Word2000".

RetentionLayout String. Can be one of these optional values: "PlainText", "FontAndParagraph",

"TruePage", "TruePageWithColumns". If not provided, the default is

"TruePageWithColumns".

139

Values for OutputType "Text"

Name value

Format String. Can be one of these optional values: "PlainText", "CommaSeparated",

"Formatted", "WithLineBreaks". If not provided, the default value is

"WithLineBreaks".

Encoding String. Can be one of these optional values: "Ansi", "Unicode". If not provided, the

default is "Unicode".

Values for OutputType "Word"

Name value

Version String. Can be one of these optional values: "Word2003", "Word2007". If not

provided, the default value is "Word2007".

RetentionLayout String. Can be one of these optional values: "PlainText", "FontAndParagraph",

"TruePage", "TruePageWithColumns". If not provided, the default is

"TruePageWithColumns".



Resource. The supported file input types for color and grayscale images are: JPEG and PNG. The supported file input type for

binary images is TIFF G4.

34.4 Result Items



No values are returned in the result item objects.

140


There will be one file returned per request item based on the OutputType specified in the request item.


Example Request

POST https://localhost/session/services/fullpageocr HTTP/1.1





Content-Length: 644

{

"serviceProps":

[

{

"name":"OcrEngineName",

"value":"Nuance"

}

],

"requestItems":

[

{

"nodeId":1,

"values":

[

{

"name":"OutputType",

"value":"text"

}

],

"files":

[

{



141


}

]

}

]

}

Example Response

HTTP/1.1 200 OK


Content-Length: 737

{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"REQ1",

"serviceName":"FullPageOCR",



"resultItems":

[

{

"nodeId":1,

"errorCode":"",

"errorMessage":"",

"files":

[

{


"value":"f_122b1551b51444979a2580f5820awe8qtext",

"src":"https://localhost/session/files/f_122b1551b51444979a2580f5820awe8qtext",

"contentType":"text/plain"

}

]

}

142

]

}

35 PROCESS IMAGE SERVICE The Process Image Ad Hoc Service provides image processing capability as defined by an image processor profile defined in

Captiva Designer.

35.1 Service Name

ProcessImage


name value

"Profile" Required String. The Image processor profile name to use.

"ReturnFileDataInline" Boolean. If true, then the resulting file is returned inline in the result item as a

base64 encoded file. If omitted or false, then the resulting file is returned as a fileId

and can be retrieved through the Files resource.

35.3 Request Items





143




35.4 Result Items



The values returned depend on the filters defined in the Image processor profile in Captiva Designer. Each filter may return one

or more values. Please see the Image Processor Guide help documentation for learning what return IA Values are specified for a

particular filter.


There will be one or more files returned based on what was submitted.


Example Request

POST https://localhost/session/services/processimage HTTP/1.1






{

"serviceProps":

[

{

"name":"Profile",

"value":"ImageProfile1"

}

],

144

"requestItems":

[

{

"nodeId":1,

"files":

[

{




}

]

}

]

}

Example Response

HTTP/1.1 200 OK



{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"REQ1",

"serviceName":"ProcessImage",



"resultItems":

[

{

"nodeId":1,

"errorCode":"",

"errorMessage":"",

"values":

145

[

{

"name":"CropTop",

"value":50

},

{

"name":"CropBottom",

"value":50

},

{

"name":"CropLeft",

"value":50

},

{

"name":"CropRight",

"value":50

}

],

"files":

[

{


"value":"f_128b1561b51643979a2580f5820abc4ftif",

"src":"https://localhost/session/files/f_128b1561b51643979a2580f5820qsz1mtif",


}

]

}

]

}

36 READ BARCODES SERVICE The Read BarCodes Ad Hoc Service will provide barcode extraction processing.

146

36.1 Service Name

ReadBarCodes


name value

"BarcodeTypes" Required String. Comma separated list of available barcodes. List of barcodes

types:

Addon2, Addon5, AustralianPost, BCDMATRIX, Codabar, Code25_Datalogic,

Code25_IATA, Code25_Industrial, Code25_Interleaved, Code25_Invert,

Code25_Matrix, Code32, Code39, Code93, DataMatrix, EAN13, EAN8,IntelligentMail,

PDF417, Postnet, QRCode, RoyalPost, Type128, UCC128, UPC_A, UPC_E

"Characters" Number. Exact number of characters to search for in the barcode text. Valid values

range from 0 to 100.

"Decode" Boolean. If true, then it decodes the results into readable strings; otherwise, if

false (the default), then it will not decode into readable strings.

"MinHeight" Number. Minimum height of barcode. Valid values range from 0 (default) to 1000.

"Mode" String. Barcode detection modes let you switch between normal and enhanced

detection types. If omitted, defaults to "Normal". Valid values:

"Enhanced": Provides better results by performing additional image preprocessing,

but takes longer to complete.

"Normal": Enables quick barcodes detection.

"Orientation" String. Specifies the orientation of the barcodes detection. If omitted, then it

defaults to "HorizontalVertical". Valid values are:

147

"Horizontal"

"HorizontalVertical"

"HorizontalVerticalDiagonal"

"Vertical"

"ScanDistance" Number. Specifies the scan distance (in pixels) between line sweeps. Useful when

searching for 1D type barcodes. Reducing the value improves detection of barcodes

which are short relative to their height. Valid values are 1 to 10. If omitted, defaults

to 5.

"UseChecksum" Boolean. A value that is an indication of whether the checksums are used. If

omitted, then it defaults to false.

"UseRegion" String. A region to select for barcode detection in order to improve the barcode

detection process. It defaults to empty (not used).

36.3 Request Items








148

36.4 Result Items



Each result item object may have zero or more properties depending on the success of the Read BarCodes Ad Hoc Service to

provide barcode information. The following possible values for each result item object may be returned:

name value

"Barcode{0}_Conf" Number. The barcode value’s confidence as a percentage number. Valid confidence

values are 0 to 100. {0} is the index for the detected barcodes. The index values

run from 0 to 9 in order of detection.

"Barcode{0}_Height" Number. The barcode's height in pixels. {0} is the index for the detected barcodes.

The index values run from 0 to 9 in order of detection.

"Barcode{0}_Text" Number. The barcode's text value. {0} is the index for the detected barcodes. The

index values run from 0 to 9 in order of detection.

"Barcode{0}_Type" String. The barcode's type name. {0} is the index for the detected barcodes. The

index values run from 0 to 9 in order of detection.

"Barcode{0}_Width" Number. The barcode's width in pixels. {0} is the index for the detected barcodes.

The index values run from 0 to 9 in order of detection.

"Barcode{0}_X" Number. The barcode’s X coordinate in pixels. {0} is the index for the detected

barcodes. The index values run from 0 to 9 in order of detection.

"Barcode{0}_Y" Number. The barcode’s Y coordinate in pixels. {0} is the index for the detected

barcodes. The index values run from 0 to 9 in order of detection.

"Barcodes_Count" Number. The number of barcodes detected.

149




Example Request

POST https://localhost/session/services/readbarcodes HTTP/1.1






{

"serviceProps":

[

{

"name":"BarcodeTypes",

"value":"Addon2,Addon5,BCDMATRIX,Codabar,Code25_Datalogic,Code25_IATA,Code25_Industrial,

Code25_Interleaved,Code25_Invert,Code25_Matrix,Code32,Code39,Code93,DataMatrix,EAN13,EAN8,PDF417,Postnet,

Type128, UCC128, UPC_A, UPC_E"

}

],

"requestItems":

[

{

"nodeId":1,

"files":

[

{




}

]

}

]

}

150

Example Response

HTTP/1.1 200 OK



{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"REQ1",

"serviceName":"ReadBarCodes",



"resultItems":

[

{

"nodeId":1,

"errorCode":"",

"errorMessage":"",

"values":

[

{

"name":"Barcode0_Conf",

"value":68

},

{

"name":"Barcode0_Height",

"value":52

},

{

"name":"Barcode0_Type",

"value":"EAN8"

},

{

"name":"Barcode0_Width",

"value":86

151

},

{

"name":"Barcode0_X",

"value":224

},

{

"name":"Barcode0_Y",

"value":322

},

{

"name":"Barcodes_Count",

"value":1

}

]

}

]

}

37 UIMDATA SERVICE The UimData Ad Hoc Service will provide either UIM (Unified Indexing Model) data population or validation or both population

and validation. The population and validation rules referenced below are developed in Captiva Designer when constructing a

Document Type. Please see the Captiva Designer documentation for more information about rules and Document Types.

37.1 Service Name

UimData


No Service Properties are needed for this Ad Hoc Service.

152

37.3 Request Items




name value

"Command" String. One of the following: "Validate", "Populate", or "PopulateAndValidate".

"Validate": UimData is validated as per validation rules.

"Populate": UimData fields are populated using population rules.

"PopulateAndValidate": UimData fields are populated using population rules and

then the data is validated per data validation rules.

"TriggerReference" String. Name of the field that is used as a population trigger or population target.

Used only for Populate or PopulateAndValidate commands. If this is empty or not

provided, then the service will run all the rules on the supplied UimData. If it is

populated, then it will only run rules that are not one-time rules.

"TriggerKind" String. One of "Calculate", "Lookup" or "PopulateOptions". Used only for Populate

or PopulateAndValidate commands.

"Calculate": The first expression population rule where TriggerReference is used as

the target field is run. This can also be an array field name with a valid row index

specified in PopulateTriggerRow.

"Lookup": All population rules of type DatabaseLookup are run in the specified

order, where the TriggerReference is one of the trigger fields. This can also be an

array field name with a valid row index specified in PopulateTriggerRow.

"PopulateOptions": The first DatebaseLookup rule is run where TriggerReference is

one of the trigger fields and the Choice values are populated by the first two

columns of the result set. This can also be an array field name with a valid row

index specified in PopulateTriggerRow.

153

"PopulateTriggerRow" Integer. This is a zero based row index for array field based population. This

property is ignored if no field name was supplied in the "triggerReference" property

or if the field name supplied is not an array field. The operation will also fail if the

index supplied for this property is invalid for the supplied array field name.

"UimData" Object. This is a UIM data information object that you want the service to use for

performing the command.


No files are necessary or used.

37.4 Result Items




name value


service operation.




Example Request

POST https://localhost/session/services/uimdata HTTP/1.1


154





{

"serviceProps":[],

"requestItems":

[

{

"nodeId":1,

"values":

[

{

"name":"Command",

"value":"Populate"

},

{

"name":"TriggerReference",

"value":"ID"

},

{

"name":"TriggerKind",

"value":"Lookup"

},

{

"name":"UimData",

"value":

{

"docType":"Employee",

"locale":"en-US",


"nodeList":

[

{

"name":"ID",

"isArray":false,


"labelText":"ID",

"isRequired":false,


155

"data":

[

{

"arrayIndex":0,

"value":"1234",

"fieldError":null,


"choices":null

}

]

},

{

"name":"Name",

"isArray":false,


"labelText":"Name",

"isRequired":false,


"data":

[

{

"arrayIndex":0,

"value":"",

"fieldError":null,


"choices":null

}

]

}

]

}

}

]

}

]

}

Example Response

HTTP/1.1 200 OK


156


{

"returnStatus":

{

"status":200,

"code":"OK0000",

"message":"",


},

"id":"REQ1",

"serviceName":"UimData",



"resultItems":

[

{

"nodeId":1,

"errorCode":"",

"errorMessage":"",

"values":

[

{

"name":"UimData",

"value":

{

"docType":"Employee",

"locale":"en-US",


"nodeList":

[

{

"name":"ID",

"isArray":false,


"labelText":"ID",

"isRequired":false,


"data":

[

{

157

"arrayIndex":0,

"value":"1234",

"fieldError":null,


"choices":null

}

]

},

{

"name":"Name",

"isArray":false,


"labelText":"Name",

"isRequired":false,


"data":

[

{

"arrayIndex":0,

"value":"John Doe",

"fieldError":null,


"choices":null

}

]

}

]

}

}

]

}

]

}

emc captiva rest services · captiva rest services supports only the json format for resource...

Documents