FedLine Web Check Services FedImage Services Gateway Retrieval Interface Guide

Transcription

1 FedLine Web Check Services FedImage Services Gateway Retrieval Interface Guide 2015 Federal Reserve Banks 1

2 Table of Contents PREFACE... 3 OVERVIEW... 4 SECTION I... 5 FEDIMAGE GATEWAY RETRIEVAL ARCHITECTURE OVERVIEW... 5 FEDIMAGE GATEWAY RETRIEVAL ARCHITECTURE... 6 NECESSARY AUTHORIZATION FORMS... 8 SECTION II... 9 AUTOMATED AGENT DEVELOPMENT... 9 DOWNLOADING AND INSTALLING CLIENT AND SERVER CERTIFICATES... 9 IMAGE RETRIEVAL PROCESS GATEWAY IMAGE RETRIEVAL COMMUNICATIONS GATEWAY APPLICATION PROGRAMMING INTERFACE <requestpackage> Section <itemrequest> Section <itemselection> Section <criteria> Section Section Query Field Names <view> Section <responsepackage> Section <statusresponse> Section <itemdetail> Section <view> Section ERROR CODES TESTING THE SOLUTION PRODUCTION VALIDATION DEPLOYMENT GUIDELINES SERVICE HOURS AND TECHNICAL SUPPORT LEGAL NOTICES

3 Preface This FedImage Gateway Retrieval Service Interface Guide is written for financial institution and vendor personnel who are responsible for deploying and supporting connectivity to the FedImage Archive Services via a FedImage Gateway Retrieval Service. FedImage Gateway Retrieval is a component of FedImage Services and included in the suite of FedLine Web Check Services. This document provides an overview of the FedImage Gateway Retrieval Service and walks the user through the process of deploying such service, including the following: FedImage Gateway Retrieval architecture The features and functions of the FedImage Gateway Retrieval Overview of the integration process Application Programming Interface and testing standards Service availability standards Technical support procedures Important Note: This document is not meant to imply or suggest any responsibility on the part of the Federal Reserve to assist or be a part of the design or development of the depository institution s image retrieval application. The sample code solutions provided in this document are for purposes of explanation only and may not provide functional solutions for any particular environment. The technical description of a FedImage Gateway Retrieval client contained in this document is intended for reference only. The Federal Reserve, through its technical liaisons, will respond on a best effort basis to questions concerning the application interface and information contained in this document. ABA Number vs. Routing Number Please note that the FedImage Gateway Retrieval Service Interface Guide uses the terms "ABA", "ABA Number" as shorthand references to financial institution's routing number. "ABA", "ABA number" and "routing number" are intended to be synonymous. 3

4 Overview FedImage Services is a suite of products that offers capture, archive, retrieval and delivery of check images. Check images are captured at various Federal Reserve Offices and transmitted to a national FedImage Archive located at two sites in the Federal Reserve System. The FedImage Archive Service provides flexible length for short and long-term storage of images. Short-term storage utilizes RAID technology thus providing immediate retrieval capabilities. Long-term storage utilizes digital tape technology housed within an Automated Tape Library (ATL). FedImage Retrieval Service offers a comprehensive array of retrieval options for the purposes of viewing, printing, faxing and/or ing items stored in the archive. Retrieval requests can be submitted in four different methods: (1) Web inquiry, (2) recurring requests, (3) request file (RORR), and (4) FedImage Gateway Retrieval. The FedImage Gateway Retrieval Service is an open-standards, TCP/IP-based extension to FedImage Services that allows depository institutions that subscribe to FedImage Services the ability to incorporate check image query capabilities within their customized applications. Such solutions use open-standards and Internet-based technologies to retrieve check images, on-demand, from the FedImage Archive in the Federal Reserve and to display those images according to the financial institution's branding and presentation requirements. Using the FedImage Gateway Retrieval service, a depository institution's systems can obtain check images from the FedImage Archive in response to requests from the depository institution's internal or external customers. At no point does the end-user of the service need to know where the images are coming from. For example, a financial institution could provide its home-banking customers with access to their check images through the FedImage Gateway Retrieval without the need store those images within that application. Other applications that can be image enabled include Adjustments/exceptions processing, customer service and corporate cash management. The overall process for deploying a FedImage Gateway Retrieval solution is outlined below, with each function described in more detail in the sections that follow: 1. The financial institution 1 reviews the documentation to understand the FedImage Gateway Retrieval architecture. 2. The financial institution develops a deployment strategy for the FedImage Gateway Retrieval solution. 3. The financial institution completes the necessary authorization forms and requests a Federal Reserve- issued digital certificate for their FedImage Gateway Retrieval implementation. 4. The financial institution begins interface and retrieval application development process in accordance to the specifications provided by the Federal Reserve. 5. The financial institution begins testing the interface against the FedImage Services QA environment. 6. Upon successful testing in QA, financial institution is connected to the FedImage Services production environment. 7. Upon successful production piloting, the financial institution begins formal deployment of their solution. 1 Depending on the particular situation, financial institution may refer to software vendor(s) or third party service providers. 4

5 Section I FedImage Gateway Retrieval Architecture Overview The FedImage Gateway Retrieval is an open-standards, TCP/IP-based extension that allows FedImage services subscribers the ability to incorporate check image query capabilities within their customized applications. This is accomplished by leveraging web services technologies to create an automated software agent that resides at the financial institution and which exchanges data securely, using standard XML data- type definitions and SSL encryption, with the FedImage Archive in the Federal Reserve. The FedImage Gateway Retrieval architecture consists of a browser-less HTTP (S) automated software agent residing at the financial institution that communicates with a corresponding agent at the Federal Reserve using 128-bit SSL-based encryption. The automated agent authenticates itself using a Federal Reserve-issued digital certificate, and communicates with the Federal Reserve using standard HTTP (S) communications ports. The communications process involves three high-level operations: 1. Establishing an SSL Session Authorization using a Federal Reserve-issued digital certificate. 2. Providing an item(s) request in the form of an XML document. 3. Downloading the image(s). Image requests received by FedImage Gateway Retrieval are processed against those items archived in shortterm storage supported by RAID technology. The length of short-term storage varies from 7 business days to one calendar year depending on the FedImage Archive Service selected by the financial institution. At the end of short-term storage, items are archived in long-term storage using tape technology for up to 11 years. Access to items in long term storage is available to financial institution personnel via standard web browser application within the FedLine for the Web Services. The Federal Reserve identifies all FedImage Gateway Retrieval requests as those originating from the specific digital certificate issued. Thus, although the images may be requested on behalf of another party, FedImage Services automatically limits access to only those images authorized under the specific digital certificate. Those digital certificates authorized to retrieve items for multiple ABAs will only be implemented upon execution of required legal agreements. Since the FedImage Gateway Retrieval communicates with the FedImage Archive e in real-time and retrieves images on-demand, its performance is heavily dependent on the: Design of the automated software agent. Bandwidth available between the financial institution and the Federal Reserve. The development of an automated software agent is the responsibility of the financial institution. The financial institution is also responsible for the design and integration of the appropriate security controls for managing access to the FedImage Gateway Retrieval solution. This packet provides the Application Programming Interface (API) required for data communications with the FedImage Archive, and describes the associated processes for establishing connectivity to the Federal Reserve environment. This packet does not describe how to integrate the FedImage Gateway Retrieval within various security architectures, although it does offer some considerations when doing so. Since the FedImage Gateway Retrieval solution leverages the public Internet for transmission of data, its performance is directly related to the speed and utilization of the connection between the Federal Reserve and the financial institution s application. 5

6 The FedImage Gateway Retrieval architecture is illustrated in the diagram below in the context of an on-line banking image retrieval example: FedImage Gateway Retrieval Architecture 6

7 FedImage Gateway Retrieval Deployment Considerations The first step in architecting an automated agent for your institution is to review the attached materials and understand how to best integrate the FedImage Gateway Retrieval into the solution being provided. Some questions that should be considered are: 1. What are the performance characteristics this solution must accommodate? Because the FedImage Gateway Retrieval queries images on-demand, using the public Internet for communications, allowances must be made for retrieval times. 2. How far back to you want to provide your users with access to their items? The FedImage Gateway Retrieval accesses items stored in short term storage that uses disk technology. The length of this storage can vary from 30 business days to 1 year depending on the service selected. Storage length options include 30 business days, 60 business days, 6 calendar months or 12 calendar months. When electing to extend the short-term storage length, deployment is limited to items from that day forward. 3. What are the reliability and availability requirements for this solution? FedImage Gateway Retrieval extends image retrieval functionality to a much larger set of customers than in the past. This may have ramifications on the reliability/uptime requirements of the overall solution. FedImage Gateway Retrieval is available on 7x24 basis. 4. Are there any firewall or router restrictions that need to be reviewed to enable FedImage Gateway Retrieval from your institution? You should consult with your or customer s technical staff to address them. 5. In addition to Federal Reserve security requirements, are there any local security policies that need to be considered to properly secure your FedImage Gateway Retrieval solution? 6. What image type are items archived in? FedImage Services support capture and storage of items in black and white. 7. Which index fields are used to index specific financial institution s checks? The FedImage Archive stores each check by 17 different index fields. Although great care has been taken to standardize, which fields are used to archive a check can vary from one financial institution to another and in some cases within each institution. The search fields to retrieve checks via FedImage Gateway Retrieval need to correspond to those used in archiving the items. 8. Which index parameters are typically used to retrieve items via FedImage Gateway Retrieval? The routing number (ABA) and the process date must always be provided. In addition most users elect to identify items by account number and process control number (which represents check number). Amount field is not recommended due to potential miscoding errors that would prevent item from being located. Criteria submitted must match the database in order for the item to be found. 9. For commercial accounts, check number is typically in the Aux On Us field and not in the Process Control field. How does the query need to be structured to locate these items? If the processing application can identify these accounts then the query can be structured based on the account type. For example, query for commercial accounts includes Aux On Us field while for consumer accounts Process Control field. In some cases, accounts are not distinguishable. In these cases, upon failure of the primary query a second query could be submitted with the Aux On Us field rather than the Process Control field. Please note that some bill pay applications place the check number in the Aux On Us field. 10. Can sequence number be used as part of the query? Yes, sequence number can be used to 7

8 locate items. Care must be taken as within the past year Federal Reserve has standardized on a 10 digit sequence number but many back end customer systems are still being populated with only 9 digits. A 10 digit number must be submitted for queries since the conversion took place. 11. What does addenda record provide? With the enablement of Check 21 Act, many financial institutions include deposit related information such as Bank of First Deposit (BOFD) and subsequent endorsements as an electronic addenda record during the check capture process. Such data may or may not be located on the actual check image. In order to display such data, your viewing application can take advantage of new elements provided in the XML query response package. 12. Why does the length of some fields vary in size? With the implementation of Check 21 Act, certain fields have been expanded to support new industry standards. The account number field has been expanded from 15 to 19 digits and Check number has been expanded from 6 to 15 digits. Please note that this only impacts newly archived checks when the enhancements are implemented. 13. How extensive will you want to log FedImage Gateway Retrieval transactions locally? The FedImage Gateway Retrieval presents itself to the FedImage Archive using a single digital certificate; thus it is impossible to record the exact nature of a given image request. You may want to consider implementing logging capabilities to assess the types of retrievals that are being made by your users. Necessary Authorization Forms In order to deploy FedImage Gateway Retrieval solution you must agree to the terms set forth in certain electronic access agreements. These documents may include the following authorizations: Operating Circular 3: This document reviews the agreements governing any electronic transmissions with the Federal Reserve System. Under certain circumstances, third party service providers may choose to utilize a single digital certificate to support FedImage Gateway Retrieval by multiple financial institutions. In these cases, an additional agreement must be executed by each financial institution, the service provider and Federal Reserve Bank. End User Authorization Form: This form designates two contact points in your organization that will be jointly responsible for the distribution and maintenance of Federal Reserve-issued FedImage Gateway digital certificates. FedImage Gateway Retrieval Credential request form: This form is requirement to request Federal Reserve-issued FedImage Gateway-specific digital certificates. 8

9 Section II Automated Agent Development The FedImage Gateway Retrieval solution is a browser-less HTTP(S) web service that must support SSL with client authentication using certificates, cookies and XML documents. Support for proxy negotiation may also be required to traverse a firewall in the financial institution's infrastructure. The development of this solution is the responsibility of the financial institution deploying the FedImage Gateway Retrieval. The material that follows provides additional overview of the FedImage Gateway Retrieval architecture relevant to the development of the solution. Although the financial institution has many development options available for developing this solution, the examples that follow assume the following: The FedImage Gateway Retrieval solution will be developed in Java. This document includes sample code developed in the IBM WebSphere Studio Application Developer environment due to its support of various JDK (Java Development Kit) environments. JDK 1.4, including Sun security support JSSE (Java Secure Socket Extension), was used to develop an automated agent for internal testing. The solution can be used standalone or as a driver for a larger system running on a Java Application Server supporting JRE 1.4. A Federal Reserve-issued digital certificate will be used for authentication. The institution supports Microsoft Internet Explorer 6.X browsers (for digital certificate management activities). Downloading and Installing Client and Server Certificates The Federal Reserve System (FRS) requires X.509 certificate authentication of all FedImage Gateway Retrieval solutions. The following process can be used to acquire a digital certificate: 1. Complete the necessary authorization forms to request a digital certificate from the Federal Reserve. You will be provided Authorization and Reference number information needed to retrieve the certificates. 2. Follow the procedures outlined in the FedLine Web Certificate Retrieval Procedures document to download your Federal Reserve Bank-issued digital certificate. Please have both your Reference number and Authorization code available. Note: A Microsoft Internet Explorer browser must be used to download your Federal Reserve Bank issued certificate. 9

10 Image Retrieval Process The illustration below highlights the communications required to retrieve a single check image. There are three high level operations that occur during every image request: 1. Establishing an SSL Session Authorization using a certificate. 2. Providing an item request(s), for a single item, in the form of an XML document. 3. Downloading the image(s). Gateway Image Retrieval Communications 1. Establishing an SSL session follows the standard SSL session definition process. The default URL for Gateway access is: 2. Request an image using the appropriate XML message. If the request is successful, the server returns an XML document containing a URL corresponding to the image. If the request is unsuccessful, an XML document is returned with an error code. 3. The following is an example of a response that will be returned for items with addenda records and expanded fields (account number and check number). The addenda records can be displayed if the application elects to do so. If not, the application must be able to handle receipt of such records. The Return Code and Reason Code for this response is 0 and the Return Code and Response Code for item detail is 0. Sample Request <?xml version="1.0" encoding="utf-8"?> 10

11 <requestpackage> <itemrequest> <description>retrieve images</description> <itemselection> <itemtype>both</itemtype> <timeout>100</timeout> <maxitemsreturned>1</maxitemsreturned> <criteria> <connector>and</connector> <name>routing and Transit Number</name> <value> </value> <name>process Date</name> <value> </value> <name>account Number</name> <value> </value> <name>amount</name> <value>450000</value> <name>process Control</name> <value>1517</value> </criteria> <view> <viewtype>fbw</viewtype> <compression>png</compression> <density>0</density> <binarize>0</binarize> </view> </itemselection> </itemrequest> </requestpackage> Sample Response <?xml version="1.0" encoding="utf-8"?> <responsepackage> <response> <returncode>0</returncode> <reasoncode>0</reasoncode> <requestid> </requestid> <successfulitems>1</successfulitems> <totalitems>1</totalitems> <itemdetail> <handle>irb001/payor- X937:p1qlib1g/1/ :0098/ : : /v CAA3-10FAAA ^/</handle> <storagetier>1</storagetier> <repository>payor-x937</repository> <returncode>0</returncode> <reasoncode>0</reasoncode> <index name="process Date" value=" "/> <index name="routing and Transit Number" value=" "/> <index name="account Number" value=" "/> 11

12 <index name="item Sequence Number" value=" "/> <index name="amount" value=" "/> <index name="check Number" value=" "/> <index name="aux On Us" value=" "/> <index name="process Control" value="001517"/> <index name="epc" value="0"/> <view> <viewtype>fbw</viewtype> <viewformat>png</viewformat> <imagekey> IMG48213.PNG</imageKey> </view> <addendarecord> <addendarecordtype>28</addendarecordtype> <addendarecordnumber>03</addendarecordnumber> <addendart> </addendart> <addendadate> </addendadate> <addendaisn> </addendaisn> <addendatruncationflag>n</addendatruncationflag> </addendarecord> <addendarecord> <addendarecordtype>28</addendarecordtype> <addendarecordnumber>02</addendarecordnumber> <addendart> </addendart> <addendadate> </addendadate> <addendaisn> </addendaisn> <addendatruncationflag>n</addendatruncationflag> </addendarecord> <addendarecord> <addendarecordtype>28</addendarecordtype> <addendarecordnumber>01</addendarecordnumber> <addendart> </addendart> <addendadate> </addendadate> <addendaisn> </addendaisn> <addendatruncationflag>n</addendatruncationflag> </addendarecord> <addendarecord> <addendarecordtype>26</addendarecordtype> <addendarecordnumber>1</addendarecordnumber> <addendart> </addendart> <addendadate> </addendadate> <addendaisn> </addendaisn> <addendatruncationflag>y</addendatruncationflag> </addendarecord> </itemdetail> </response> </responsepackage> 4. Please note that the handle XML tag is about 400 bytes or more. The current software version returns an image handle approximately 100 bytes in length. 5. Each image is then retrieved using the URL in the XML response message from the previous step. 6. The following is an example of sample code that would be returned for items stored without addenda records. Although the request Return Code of 3004 indicates an error, the Reason Code of 1 indicates a successful retrieval of at least 1 view of the item. Please note that the item detail Return Code is also 4 while the Reason Code is 0 indicating a successful retrieval. This response will apply to all items archived prior to deployment of Check 21 Act enhancement that support storage of addenda records. Lastly, the account number field and check number field for these items have not been expanded; they are the original length that the item was archived as. 12

13 Sample Request <?xml version="1.0" encoding="utf-8"?> <requestpackage> <itemrequest> <description>retrieve images</description> <itemselection> <itemtype>both</itemtype> <timeout>100</timeout> <maxitemsreturned>1</maxitemsreturned> <criteria> <connector>and</connector> <name>routing and Transit Number</name> <value> </value> <name>process Date</name> <value> </value> <name>account Number</name> <value> </value> <name>amount</name> <value>3136</value> <name>process Control</name> <value>1045</value> </criteria> <view> <viewtype>fbw</viewtype> <compression>png</compression> <density>0</density> <binarize>0</binarize> </view> </itemselection> </itemrequest> </requestpackage> Sample Response <?xml version="1.0" encoding="utf-8"?> <responsepackage> <response> <returncode>3004</returncode> <reasoncode>1</reasoncode> <messages>partial results returned.</messages> <requestid> </requestid> <successfulitems>1</successfulitems> <totalitems>1</totalitems> <itemdetail> <handle>irb001/cl-gate:pdt1l2c0/1/ :0038//v xaa1-15faaa ^/</handle> <storagetier>1</storagetier> <repository>cl-gate</repository> <returncode>4</returncode> 13

14 <reasoncode>0</reasoncode> <index name="process Date" value=" "/> <index name="routing and Transit Number" value=" "/> <index name="account Number" value=" "/> <index name="item Sequence Number" value=" "/> <index name="amount" value=" "/> <index name="check Number" value="000000"/> <index name="aux On Us" value=" "/> <index name="process Control" value="001045"/> <index name="epc" value="0"/> <view> <viewtype>fbw</viewtype> <viewformat>png</viewformat> <imagekey> IMG48212.PNG</imageKey> </view> </itemdetail> </response> </responsepackage> 7. The following is an example of a response that exceeded the <maxitemsreturned> value of the requesting xml but it is a successful retrieval. The Return Code of 3004 and Response Code of 3 indicate that more than one item found meets the search criteria. By evaluating the item detail, the Return Code of 4 and Reason Code of 0 indicate successful return of only 1 item. Please note that field size for account number and check number are likely to be expanded but may not necessarily be. Sample Request <?xml version="1.0" encoding="utf-8"?> <requestpackage> <itemrequest> <description>retrieve images</description> <itemselection> <itemtype>both</itemtype> <timeout>100</timeout> <maxitemsreturned>1</maxitemsreturned> <criteria> <connector>and</connector> <name>routing and Transit Number</name> <value> </value> <name>process Date</name> <value> </value> <name>account Number</name> <value> </value> <name>amount</name> <value>13400</value> <name>process Control</name> <value>0384</value> 14

15 </criteria> <view> <viewtype>fbw</viewtype> <compression>png</compression> <density>0</density> <binarize>0</binarize> </view> </itemselection> </itemrequest> </requestpackage> Sample Response <?xml version="1.0" encoding="utf-8"?> <responsepackage> <response> <returncode>3004</returncode> <reasoncode>3</reasoncode> <messages>partial results returned.</messages> <requestid> </requestid> <successfulitems>1</successfulitems> <totalitems>2</totalitems> <itemdetail> <handle>irb001/cl-cv2:pdt1l2c0/1/ :0098//v caa1-14faaa ^/</handle> <storagetier>1</storagetier> <repository>cl-cv2</repository> <returncode>4</returncode> <reasoncode>0</reasoncode> <index name="process Date" value=" "/> <index name="routing and Transit Number" value=" "/> <index name="account Number" value=" "/> <index name="item Sequence Number" value=" "/> <index name="amount" value=" "/> <index name="check Number" value="000384"/> <index name="aux OnUs" value=" "/> <index name="process Control" value="000384"/> <index name="epc" value="0"/> <view> <viewtype>fbw</viewtype> <viewformat>png</viewformat> <imagekey> IMG48214.PNG</imageKey> </view> </itemdetail> </response> </responsepackage> 8. The following is an example of a request for an older item that is already stored on tape media (tier2). These items are not accessible to the FedImage Gateway service. Although this request response contains Return Code of 3004 and Response Code of 1, the item detail Return Code is 7 and the Reason Code is 0. This represents a retrieval failure as the item is not available to the FedImage Gateway process. Sample Request <?xml version="1.0" encoding="utf-8"?> <requestpackage> <itemrequest> <userrequestid>user</userrequestid> <description>retrieve images</description> 15

16 <itemselection> <itemtype>both</itemtype> <timeout>100</timeout> <maxitemsreturned>1</maxitemsreturned> <criteria> <connector>and</connector> <name>routing and Transit Number</name> <value> </value> <name>process Date</name> <value> </value> <name>account Number</name> <value> </value> <name>amount</name> <value>14599</value> <name>process Control</name> <value>0000</value> </criteria> <view> <viewtype>fbw</viewtype> <compression>png</compression> <density>0</density> <binarize>0</binarize> </view> </itemselection> </itemrequest> </requestpackage> Sample Response <?xml version="1.0" encoding="utf-8"?> <responsepackage> <response> <returncode>3004</returncode> <reasoncode>1</reasoncode> <messages>partial results returned.</messages> <requestid> </requestid> <successfulitems>1</successfulitems> <totalitems>1</totalitems> <itemdetail> <handle>irb001/cl-cv2:pdt1l2c0/2/ :0017//v zaa1-102faaa ^/</handle> <storagetier>2</storagetier> <repository>cl-cv2</repository> <returncode>7</returncode> <reasoncode>0</reasoncode> <index name="process Date" value=" "/> <index name="routing and Transit Number" value=" "/> <index name="account Number" value=" "/> <index name="item Sequence Number" value=" "/> 16

17 <index name="amount" value=" "/> <index name="check Number" value="000099"/> <index name="aux On Us" value=" "/> <index name="process Control" value="000000"/> <index name="epc" value="0"/> </itemdetail> </response> </responsepackage> 9. The latest release of FedImage software has added a new Return Code to indicate that a duplicate item has been detected. As part of FRB s initiative to provide check endorsement data (addenda records), some of the non-addenda documents will be merged with the addenda records and stored again. When this occurs, the retrieval process with detect that both the old and new format of the item are stored, and will retrieve only the new format with the addenda records. In this case, the request response contains Return Code of 3004 and Response Code of 2 while the item detail Return Code is 0 and the Reason Code is 0. This represents a successful retrieval. Please note that account number and check number may or may not be expanded. Sample Request <?xml version="1.0" encoding="utf-8"?> <requestpackage> <itemrequest> <userrequestid>michael_t._ensley_bos_ui</userrequestid> <description>retrieve images</description> <itemselection> <itemtype>both</itemtype> <timeout>100</timeout> <maxitemsreturned>1</maxitemsreturned> <criteria> <connector>and</connector> <name>routing and Transit Number</name> <value> </value> <name>process Date</name> <value> </value> <name>item Sequence Number</name> <value> </value> <name>amount</name> <value>13400</value> <name>process Control</name> <value>384</value> </criteria> <view> <viewtype>fbw</viewtype> <compression>png</compression> <density>0</density> <binarize>0</binarize> </view> 17

18 <view> <viewtype>bbw</viewtype> <compression>png</compression> <density>0</density> <binarize>0</binarize> </view> </itemselection> </itemrequest> </requestpackage> Sample Response <?xml version="1.0" encoding="utf-8"?> <responsepackage> <response> <returncode>3004</returncode> <reasoncode>2</reasoncode> <messages>partial results returned.</messages> <requestid> </requestid> <successfulitems>1</successfulitems> <totalitems>2</totalitems> <itemdetail> <handle>irb001/cl-cv2:pdt1l2c0/1/ :0098//v caa1-14faaa ^/</handle> <storagetier>1</storagetier> <repository>cl-cv2</repository> <returncode>0</returncode> <reasoncode>0</reasoncode> <index name="process Date" value=" "/> <index name="routing and Transit Number" value=" "/> <index name="account Number" value=" "/> <index name="item Sequence Number" value=" "/> <index name="amount" value=" "/> <index name="check Number" value="000384"/> <index name="aux OnUs" value=" "/> <index name="process Control" value="000384"/> <index name="epc" value="0"/> <view> <viewtype>fbw</viewtype> <viewformat>png</viewformat> <imagekey> IMG48217.PNG</imageKey> </view> <view> <viewtype>bbw</viewtype> <viewformat>png</viewformat> <imagekey> IMG48218.PNG</imageKey> </view> </itemdetail> </response> </responsepackage> 10. In certain cases, operators other than EQUAL To will need to be utilized to locate a particular item. The following sample code provides an example of the IN operator. <name>account Number</name> <operator>in</operator> <value> </value> <value> </value> 18

19 <value> </value> <value> </value> <value> </value> <value> </value> <value> </value> <value> </value> <value> </value> <value> </value> ""IN allows up to 100 values to be specified. Items will be returned that match any of the supplied values." 19

20 Gateway Application Programming Interface The following tables outline the specific XML definitions required to exchange data with the FedImage Archive service. Because the Federal Reserve will occasionally enhance these definitions, it is recommended that you obtain the latest version of these API's. Item Request The items requested to be retrieved are determined based on the item selection section of the XML statement. This section specifies: Whether the request is for index information or image information including indexes Limit information on the allowed maximum size of the hit list One of the following types of selection criteria For indexes: Field Criteria (Field name, operator, and value(s)) For images: Item Handles (These are returned from prior index requests) Image View and formatting information View Type the financial institution will provide the developer with information on the appropriate view type. FBW front black white BBW back black white FGS front gray scale BGS back gray scale USER User data View Format (Compression type (--image may need to be recompressed to a different format for the application) Binarization (Convert from gray scale to black white) Density number of pixels per inch Sample of Customer-Specific Production Information Prior to establishing queries to the production environment, Federal Reserve will provide specific information on how items are stored and indexed. This will include the following: Customer: RTN: Capture Site: Certificate ID: Image Type: ISN: B+W 10 digit Item Sequence Number 20

21 Check# Length of Storage: Archive: URL: Aux on Us / Process Control field 60 days, 6 months or 1 year on disk Cleveland or Minneapolis or FRB FedImage Archive Item Request Field Descriptions A request package consists of the XML string containing information required to request indexes and images from IRB. The request is composed of sections defined by elements. These sections and elements are described below: <requestpackage> - root level element for the request package. It contains all other elements. <itemrequest> - one itemrequest for each requestpackage. This section lists the information to be used to select indexes and images from the archive. <itemselection> - processing options and specific criteria for items to be requested <criteria> - the criteria to be used to retrieve indexes and images from the archive - if a field based query is requested rather than a handle based query the field section lists the information used to select items from the archive. <view> - the processing options for each view, or image segment, to be returned for every item in this request <requestpackage> Section XML Field Name Type Description Request Type Field Specifies the type of request. In this case it will always say Gateway for a Gateway Retrieval request type. Item Request Section One item Request per request Package <itemrequest> Section XML Field Name Type Description Item Request Section Contains a single request for items. User Request ID Field Identification for this request Description Field Description of this request Item Selection Section One item selection per item request 21

22 <itemselection> Section XML Field Name Type Description Item Selection Section Contains information used by IRB to request index and image information Timeout Field Number of seconds the IRB server will wait before timing out (giving up) on an index request. Max Items Returned Field Maximum number of items IRB will return unless system configured absolute maximums are lower. Ignore Tier On Failover Field Used during failover scenarios to indicate whether images are to be retrieved from slower storage tiers. Specify 0 (the default) to indicate that the list of image handles are to be retrieved if and only if all of their storage tiers are equal to or faster than what was returned in the storage Tier value of their original index request. Specify 1 if images are to be retrieved from any failover repository regardless of storage tier. Item Type Field Sets the type of request. Supported values are: index = index only both = index and image Repository Field Sets the name of a repository-search-list defined in the IRB configuration file. All repositories defined in the repository-search-list will be searched in parallel. This value is not used for requests with handle criteria. Criteria Section One criteria section per item Selection Value Field One or more views for each item retrieved <criteria> Section XML Field Name Type Description criteria Section Contains the search criteria for IRB. If indexes are requested, connector / field criteria should be used. If images are requested, handle criteria should be used. handle Field A set of values which uniquely identifies a single item in the repository. During an index request, this handle is calculated and returned. It is then used to request the item's image. connector Field The connector is used to logically connect the field name operator - value triplets when performing a field criteria search. The only valid value for connector is AND. There is no default. field Section One or more fields specified for the criteria OR 22

23 Section XML Field Name Type Description field Section Contains search criteria for a single field in the form of a field name, operator, and field value(s). name Field Index field name corresponding to a specific index in the repositories operator Field Sets the operator that defines how the supplied field value(s) are to be compared to the repository index. The following values may be specified: EQ EqualTo LT LessThan GT GreaterThan NE NotEqualTo LE LessThanOrEqualTo GE GreaterThanOrEqualTo IN In BETWEEN Between Most operators support only a single value. IN allows up to 100 values to be specified. Items will be returned that match any of the supplied values. BETWEEN allows either one or two values. If only a single value is supplied, then the result will be the same as if the EqualTo operator was selected. If two values are supplied, then items will be returned that are equal to or between the two values. value Field Contains the value to be searched on in the query. Query Field Names XML Field Name Type Description Routing and Transit Number Int This is a mandatory field. It accepts only integers, and its maximum length is 9. Process Date Int This is a mandatory field. It accepts dates only in YYYYMMDD; other formats are not allowed. Amount Int This optional field accepts only integers, not decimal values. The maximum length of this field is 10. Aux On Us Int This optional field accepts only integers. The maximum length of this field is 15. Some business account check numbers are in this field. The financial institution should supply information to the developer on the use of this query option. 23

24 Query Field Names XML Field Name Type Description The Sequence Number Int This optional field accepts only integers. The maximum length of this field is 15. Process Control Int This optional field accepts only integers. The maximum length of this (known as Check field is 6. This holds the check number. NOTE: If the check number Number) is in the Aux On Us field it will not be in this field. Account Int This optional field accepts only integers. The maximum length of this field is 19. This is the field that has been expanded from 17 previously. Check Number Int This optional field accepts only integers. The maximum length of this field is 15 (previously 6). This field may contain the check number if the Process Control field is filled in. Capture Site Int This optional field accepts only integers. The maximum length of this field is 9. EPC Int This optional field accepts only integers. The maximum length of this field is 9. <view> Section XML Field Name Type Description view Section Specifies a particular image segment and defines any formatting to be applied to it. View sections are only applicable to requests for images. There should be a view section for each image segment to be returned. If no view sections are specified the system defaults will be applied. view Type Field Possible view types depend upon the type of searched repository. For ISS possible view types are: FBW = Front Black White FGS = Front Gray Scale (no longer provided by FRB) BBW = Back Black White BGS = Back Gray Scale (no longer provided by FRB) USER = User defined segment compression Field Specifies the desired format of the output image. Allowed values are: ASIS = return image with no conversion JPG = convert image to JPG PNG = convert image to PNG (portable network graphics) density Field Specifies the desired density of the output image in pixels per inch. Specify zero (the default) to indicate that the density is to be left as is. Because black-white image segments typically have greater density than 24

25 <view> Section XML Field Name Type Description grayscale images, the density parameter provides a way to make them the same. binarize Field Sets the desired binarization threshold. To request binarization set threshold to a value from 1 to 100, where 1 will result in a completely white image and 100 will result in a completely black image. Specify zero (the default) to indicate that binarization is not to be performed. Item Request-Response XML An Item Request-Response consists of the XML definition containing information returned from a call to the Gateway service. The response is composed of sections defined by elements. These sections and elements are described below: <responsepackage> - root level element for the response package. It contains all other elements. <statusresponse> - includes the elements returned for a status request. <response> - includes the elements returned for all the items in a results request. <itemdetail> - contains the elements giving detailed information about each item <view> - contains the elements giving detailed information about each view <addendarecord> - provides detailed information about each addenda record returned (for example, Bank of First Deposit addenda record and subsequent endorsements). There is one addenda record element for each addenda record returned. <repositorysummary> - the summary statistic information for each response broken down by repository. <responsepackage> Section XML Field Name Type Description responsepackage Section Contains elements that describe the results of a specific request. returncode Field Value indicating whether the associated request was successful (0) or partially successful (4) - one or more views requested is not available; The item detail return code and reason code must be evaluated to determine status of the request. Note: This will be the case for all items archived prior to enhancing item storage with addenda records. reasoncode Field If return code is non-zero, the reason code could contain further information about the partial success or potential error. requestid Field ID of the associated request. The value in the <requestid> field is also 25

26 <responsepackage> Section XML Field Name Type Description referred to as the Dex job tracking number. message Field Text of message when returncode>0. successfulitems Field Number of items with successful return codes. totalitems Field Count of the number of items returned. itemdetail Section Zero or more Item Detail elements containing information about each item returned in the request. <itemdetail> Section XML Field Name Type Description Item Detail Section The elements containing information about each item returned in the request. Handle Field A set of values which uniquely identifies a single item in the repository. This handle is calculated and returned from the request. It can be used to request an item's image. storage Tier Field If storage tier processing is active for this repository, a positive value will be returned where 1 indicates the fastest storage media, 2 is next fastest, and so on. It is the responsibility of the client application to assign meaning to specific storage tier values. A value of 0 (zero) indicates that storage tier processing is not active for this repository. repository Field This repository is the specific repository that the item was found in. return Code Field The return code for the individual item. 0 = success 4 = successful retrieval but one or more views requested are not available. (This will be the case for all items archived prior to enhancing item storage with addenda records.) 7= failed retrieval; indicates that the image is on tape storage (tier 2) and is not accessible to the FedImage Gateway Retrieval process. reason Code Field The reason code for the individual item. Non-zero value indicates failed query. index Section Within an item, there are multiple fields of text information defining the item. Each field has an index field name and an index field value. This section will be repeated for each field defined. This element has two attributes: name the name of the index field value the value in the field view Section Defines image segment and any formatting applied to it. There will be a view section for each image segment returned. 26

27 <view> Section XML Field Name Type Description view Section Defines image segment and any formatting applied to it. There will be a view section for each image segment returned. view Type Field Possible view types depend upon the type of searched repository. For Archive Server, possible view types are: FBW = Front Black White FGS = Front Gray Scale BBW = Back Black White BGS = Back Gray Scale USER = User defined segment view Format Field Specifies the desired format of the output image. Allowed values are: ASIS = return image with no conversion JPG = convert image to JPG PNG = convert image to PNG (portable network graphics) image Key Field HTML link to image for this view. <addendarecord> Section XML Field Name Type Description addendarecord Section Defines the addenda record. addendarecord Type Field Specifies the type of X9 addenda record returned. addendarecordnumber Field Specifies the addenda record number for this record. addendart Field Specifies the routing number for this addenda record. addendadate Field Specifies the business date for this addenda record. addendaisn Field Specifies the item sequence number for this addenda record. addendatruncationflag Field Specifies the truncation flag setting for this addenda record. Possible values for this fields are Y and N. 27

28 Error Codes The following table outlines the various status messages that may be returned by the Gateway service: FedImage Services Gateway Retrieval Error Codes The following table documents the messages and codes used by Gateway Server to indicate various error scenarios. The errors go into <returncode><reasoncode><messages> tags of the response XML. The DexGatewayImageServlet uses the absence of image data to indicate error in retrieving/creating the from/to the cache. Successful Transaction Return Code Reason Code Description 0 0 Successful Completion Errors returned by Gateway Application Server Return Code Reason Code Description An internal error has occurred. HTTP Get not supported Missing input XML Invalid user: <username> Internal Exception in processxmlrequest\n exception.tostring() Exception Occurred while connecting to RMI\n exception.tostring() Missing user identification. Errors returned by DEX Synchronous Server Return Code Reason Code Description DexException.toString(); Exception.toString(); Error in Request Processing Item Validation Failed, no criteria provided Item Validation Failed, no field list criteria in criteria provided Item Validation Failed, no RTN criteria provided Item Validation Failed, more than one RTN with Account Number criteria Item Validation Failed, only RTN criteria valid with OR connector Item Validation Failed, no Date criteria provided Item Validation Failed, no RTN values provided in RTN criteria Item Validation Failed, one or more RTNs are not numeric Item Validation Failed, requested RTN(s) result in only RTNs which are not valid according to User's RTN List(s) Item Validation Failed, unknown criteria operator for RTN criteria Item Validation Failed, RTN List profile for user is empty Item Validation Failed, no Account Number values provided in Account Number criteria Item Validation Failed, one or more Account Numbers are not numeric Item Validation Failed, requested Account Number(s) result in only Account Numbers which are not valid according to the User's RTN Account List(s) Item Validation Failed, unknown criteria operator for Account Number Criteria. 3nnn + 0 Indicates an IRB error. The IRB return code is added to the base In some cases, a nonzero return is acceptable. The itemdetail return code and reason code must be evaluated to determine the final status of the request Successful Completion Partial results returned (at least one of the requested image views is not available in the repository). Need to inspect detail response codes to determine the cause. One or more requested views are not available. Maximum number of items returned was exceeded. This could be caused by non-specific query criteria or duplicate item. Combination of conditions from reason codes 1 and 2. 28