RatesRESTService

ESD Interface Control Document

 

Service Version 5.0

Document Version 1.6

Updated 03/03/2015

 

 

 

 

 

U.S. Bank Internal

This document may not be shared with third parties without approval from the Enterprise Service Development (ESD) department. Please contact the ESD Documentation Shared Mailbox for further information.



Updating the Document Properties

1. Select the File tab.

2. Select Properties > Advanced Properties. The Document Properties window appears.

3. Select the Summary tab and complete the following steps:

    - Enter your name in the Author field.

    - Enter one or more unique search terms for this service, separated by commas, in the Keywords field.

4. Select the Custom tab and complete the following steps:

    - Select Service Name in the Properties list.

    - Enter the current service version in the Value field and click Modify.

    - Repeat for Service Version, Document Version, Updated Date and ICD Template Version.

5. Click OK.

6. Select Select > Select All on the Home tab, then press F9 to refresh the document property updates.

7. Click Print on the File tab to display the updated document property values in the headers and footers.

Note: The headers and footers will not show the document properties updates in the Print Layout view.

8. Click Save to save the updated document and then you can begin your content updates.

Note: To view/hide instructions, click the Show/Hide button  on the Home tab. It is not necessary to delete the instructions before publishing this ICD, but be sure to hide all instructional text by clicking the Show/Hide button before doing a final save.

 

Removing the Watermark

1. Select the Page Layout tab.

2. Select Remove Watermark from the Watermark drop-down list.

 

Adjusting Page Orientation to Landscape

1. Highlight the text on the page you want to make landscape.

2. Select the Page Layout tab.

3. Select Landscape from the Orientation drop-down list.

Document Revision History

[Use this table to indicate high-level changes and ICD document editing changes to this service version. Detailed changes for project-related changes should be put in the Change Log. Note: Delete the first row before inserting your text.]

See the Service Change Log for more details about service version changes.

Date

Version

Description

Author

11/23/2013

1.0

Initial version (GetAutoLoanRates resource only)

Erik Brown

02/26/2014

1.1

Added GetCurrentDepositRates, GetCurrentCertificateofDepositRates, GetHomeEquityRates, GetMortgageRates resources

Erik Brown

02/28/2014

1.2

Changes after review feedback.   In system description and diagrams, changed “Apache” to “Reverse Proxy”.  Changed End-to-End Timeouts diagram to show ATMBranchLocator impact.  StatusCode consistency, HostFieldName information.  Important:  all URLs for REST services include /public in URL before the service name.

Erik Brown

03/26/2014

1.3

Needed to add ZipCode to GetHomeEquityRatesRequest. Changed BranchIdentifier to BranchNumber in GetHomeEquityRatesRequest

Erik Brown

4/14/2014

1.4

Fixed Tier2 and Tier3 URLs

Erik Brown

06/26/1014

1.5

Adding element description info for HomeEquityProductType

Erik Brown

03/03/2015

1.6

Added “The list of branches is filtered to eliminate drive-up and ATM-only branches.” to the processing specifications for all operations except GetMortgageRates

Erik Brown


Table of Contents

Service Description.............................................................................................................. 6

Service URL.............................................................................................................................. 6

Request Methods....................................................................................................................... 6

Data Formats............................................................................................................................. 6

Special Considerations............................................................................................................. 7

Assumptions.............................................................................................................................. 7

References................................................................................................................................ 7

High-Level Web Service Interface Specifications........................................................... 8

System Interface Diagram......................................................................................................... 8

System Interaction Diagrams..................................................................................................... 9

Security Specifications............................................................................................................. 9

Tier 2 Consumer Authorization...................................................................................................................... 9

Tier 3 Consumer Authorization.................................................................................................................... 10

Processing Specifications....................................................................................................... 10

Exception Processing.............................................................................................................. 10

Service Time-Out Specifications............................................................................................ 11

Detailed Interface/Message Specifications by Service Operation............................ 11

GetAutoLoanRates.................................................................................................................. 11

Operation Description................................................................................................................................. 11

Processing Specifications.......................................................................................................................... 11

Functional Scenarios.................................................................................................................................. 14

Pagination or Scrolling for Results Using the GetList Aggregate............................................................... 14

Operation to Data Source Reference Table................................................................................................ 15

Field/Element Specifications...................................................................................................................... 15

Exception Processing................................................................................................................................. 17

GetCurrentCertificateofDepositRates....................................................................................... 17

Operation Description................................................................................................................................. 17

Processing Specifications.......................................................................................................................... 17

Functional Scenarios.................................................................................................................................. 17

Pagination or Scrolling for Results Using the GetList Aggregate............................................................... 17

Operation to Data Source Reference Table................................................................................................ 17

Field/Element Specifications...................................................................................................................... 17

Exception Processing................................................................................................................................. 17

GetCurrentDepositRates.......................................................................................................... 17

Operation Description................................................................................................................................. 17

Processing Specifications.......................................................................................................................... 17

Functional Scenarios.................................................................................................................................. 17

Pagination or Scrolling for Results Using the GetList Aggregate............................................................... 17

Operation to Data Source Reference Table................................................................................................ 17

Field/Element Specifications...................................................................................................................... 17

Exception Processing................................................................................................................................. 17

GetHomeEquityRates.............................................................................................................. 17

Operation Description................................................................................................................................. 17

Processing Specifications.......................................................................................................................... 17

Functional Scenarios.................................................................................................................................. 17

Pagination or Scrolling for Results Using the GetList Aggregate............................................................... 17

Operation to Data Source Reference Table................................................................................................ 17

Field/Element Specifications...................................................................................................................... 17

Exception Processing................................................................................................................................. 17

GetMortgageRates.................................................................................................................. 17

Operation Description................................................................................................................................. 17

Processing Specifications.......................................................................................................................... 17

Functional Scenarios.................................................................................................................................. 17

Pagination or Scrolling for Results Using the GetList Aggregate............................................................... 17

Operation to Data Source Reference Table................................................................................................ 17

Field/Element Specifications...................................................................................................................... 17

Exception Processing................................................................................................................................. 17

HeartBeat................................................................................................................................ 17

Operation Description................................................................................................................................. 17

Processing Specifications.......................................................................................................................... 17

Functional Scenarios.................................................................................................................................. 17

Pagination or Scrolling for Results Using the GetList Aggregate............................................................... 17

Operation to Data Source Reference Table................................................................................................ 17

Field/Element Specifications...................................................................................................................... 17

Exception Processing................................................................................................................................. 17

Connection Information.................................................................................................... 17

Tier 2 Environment Configuration........................................................................................... 17

Tier 3 Environment Configuration........................................................................................... 17

Disaster Recovery (DR) Testing................................................................................................ 17

Service Change Log........................................................................................................... 17

Service Name 1.0 – PRJ0000####......................................................................................... 17

Operation Name.......................................................................................................................................... 17

Refactored Service and Operation Cross-Reference Table....................................... 17

Operation Name...................................................................................................................... 17

Appendix A................................................. Definitions, Acronyms and Abbreviations            17


Service Description

[The Architects write the service and operation descriptions before the ICD is completed and enter them in the Repository. The service description should be copied from the Long Desc field in the Repository entry for the service.]

Important: Do not delete topics in this template. If a topic does not apply to your initiative, enter NA under the heading and indicate the reason the topic is not applicable.]

Loan officers and customers need to easily pull the current rates for various interest-bearing or interest-earning products. The RatesRESTService 5.0 is used to retrieve rates for various certificates of deposit, deposits, loans or lines of credit, credit cards, auto loan rates, and home equity loans or lines of credit products offered by U.S. Bank.

Note: The sixth operation exposed by RatesService_V_5_0, GetStandardAndSpecialCDRates, is not exposed as a resource in RatesRESTService_V_5_0, because that was not a requirement.

This service is a RESTful web service that provides the same functionality the SOAP-based RatesService. These two services share the same underlying code.  This service is exposed and open to the public via the internet. The service is secured using HTTPs plus a WS-Security header containing a UsernameToken.

Service URL

The consuming application for this RESTFul service may need to construct the URL dynamically based on the choices included in the operations. The consuming application must be prepared to build the URL at run time.

The syntax for the URL is: scheme://domain:port/path?query_string#fragment_id

The elements of this syntax are as follows:

Š       Scheme – Currently ESD only supports HTTPS in the scheme.

Š       Domain – The virtual host name assigned to the web server in the DNS servers. The host name can be either a physical server name, a load balancing Big IP/Wide IP, or a proxy server.

Š       Port – An optional element. If not passed, then the default 443 is used.

Š       Path – The URL path is very similar to its directory structure. The values are delimited by a forward slash (/). ESD categorizes the path in the following way:

o   Service name

o   Operation name

o   Choices within the operation name

Š       Query String – The input parameter values sent to the host and delimited by an ampersand (&).

Š       Fragment ID – Not used in ESD implementations.

Note: See the specific operation for further details about the supported request methods.

Request Methods

[Describe which RESTFul request method is used in this service. Remove any that do not apply.] http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

The RESTFul service should support one or more of the following request methods:

Š       GET – This method is commonly used for inquiry requests. Input values are sent through the URI.

Note: See the specific operation for further details about the supported request methods.

Data Formats

[Specify which format the consumer needs to follow when sending the request or response.]

RESTFul services support various data formats between both the request and response:

Š       XML – Extensible Markup Language. A markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. Although the design of XML focuses on documents, it is widely used for the representation of arbitrary data structures, for example in web services.

Š       JSON – JavaScript Object Notation. A text-based open standard designed for human-readable data interchange. It is derived from the JavaScript scripting language for representing simple data structures and associative arrays, called objects. It is used primarily to transmit data between a server and web application, serving as an alternative to XML.

Š       Text – Plain Text, Form-Encoding. The contents of an ordinary sequential file readable as textual material without much processing, usually opposed to formatted text and to "binary files" in which some portions must be interpreted as binary objects (encoded integers, real numbers, images, etc.). Files that contain markup or other meta-data are generally considered plain-text, as long as the entirety remains in directly human-readable form (as in HTML, XML and so on).

Š       URI – Uniform Resource Identifier. A string of characters used to identify a name or a web resource. Such identification enables interaction with representations of the web resource over a network (typically the World Wide Web) using specific protocols. Schemes specifying a concrete syntax and associated protocols define each URI.

The service may support more than one format, but the consumer can specify the format they choose within the request.

Note: See the specific operation for further details about the supported request methods.

Special Considerations

[If applicable, list any special considerations when consuming the service here, for example that it is a channel service or it includes non-public information (NPI), etc. Change the text to NA if there are no special considerations.]]

Consider the following special considerations when consuming this service:

Assumptions

[Use the following standard text, but indicate any further assumptions about the consumers of this service.]

The audience has knowledge of and understands the following technologies:

Š       XML

Š       REST

Š       URI

Note: ESD designed RatesRESTService 5.0 as an enterprise Web service with the assumption that any application could be a consumer of this service.

References

[Add the names of any other documents or artifacts you referenced to create or update this ICD. Include links to the references, if appropriate.]

ESD referenced the following documents or artifacts while creating or updating this ICD:

Š       RatesRESTService_V_5_0.wadl

Š       MessageRatesRESTService_V_5_0.xsd

Š       USBSOATypeLibrary_V_3_0.xsd

Š       USBSOACoreComponentsLibrary_V_3_0.xsd


 

High-Level Web Service Interface Specifications

This topic illustrates both the system interface and interactions and covers specifications related to service security, processing, exception processing and time-outs.

System Interface Diagram

[Provide a diagram that illustrates the (two or more) systems participating in the interface and the connection (or pipe) between them.]

The following diagram (Figure 1) gives a high-level view of the pieces involved in the RatesRESTService 5.0 service, which is an enterprise Web service that could be used by any application. The diagram shows the process of how consumers connect to enterprise services through the Reverse Proxy, which routes the call to the Oracle Service Bus (OSB) that hosts virtualized services, instead of connecting directly to them.

[Work with the ESD Architect assigned to the project to choose one of the following five diagrams that most appropriately illustrates the service interface and delete the rest.]

Figure 1            RatesRESTService_V_5_0


 

System Interaction Diagrams

[Provide diagrams that show the system events/interactions, the messages/files generated from the events/interactions and all of the possible responses. Typically, there should be one diagram per system interaction.]

RatesRESTService 5.0 presents multiple scenarios for processing requests. The following interaction and sequence diagrams illustrate each scenario and provide better insight about how the components interact.

The following diagram (Figure 2) shows how the system routes all requests between consumers and services through OSB. This is true for both internal and external Web services. The following diagram illustrates the role OSB plays in the sequence following a consumer call to a service operation.

Note: This diagram is a brief overview of this interaction and not a complete picture of how OSB and other involved software components work together in the service environment.

Figure 2            Sequence Diagram

Note: A proxy pattern is used and the proxy gateway is used as a policy enforcement point for authentication.

Security Specifications

[Discuss any security-related controls that must be implemented by this service’s interface.]

The following topics describe the U.S. Bank security specifications this service interface must implement.

Tier 2 Consumer Authorization

No Security Specifications

To consume this service, there is no username or password needed. The data transmitted between the consumer and the service is encrypted using the one-way SSL key.

Consumer Authorization

[Determine if this information is needed or not. Remove it if not.]

Mutual authentication, or two-way authentication (which is sometimes written as 2WAY authentication), refers to two parties authenticating each other suitably. In technology terms, this refers to clients or users authenticating themselves to servers and those servers authenticating themselves to the clients or users in such a way that both parties are assured of the others' identities. Trusted third parties that use shared secrets, as in Kerberos v5, or cryptographic means, as with a public key infrastructure, can also validate identities.


 

Tier 3 Consumer Authorization

No Security Specifications

To consume this service, there is no username or password needed. The data transmitted between the consumer and the service is encrypted using the one-way SSL key.

Consumer Authorization

[Determine if this information is needed or not. Remove it if not.]

ESD uses WS-Security 1.0 to handle service authentication. ESD expects all clients to provide a WS-Security Username Token in the WS-Security header in all service calls. SSL-mutual authentication provides the payload authentication between OSB and the TIBCO service layer. See the Oracle Service Bus (OSB) WS-Security Mechanism document on the ESD SharePoint site for more information.

Processing Specifications

[Discuss any processing specifications that are applicable at the service level.]

This topic describes the most common processing pattern used by the service operations. If this pattern does not apply to an operation, that operation will contain a description of its unique processing pattern.

Š       Processing starts with the client application sending the request message to the service URL over HTTPS using one or more of the identified request methods.

Š       OSB proxy service converts RESTFul request to SOAP request and forwards to physical service using SOAP over JMS.

Š       The BW Process Engine (engine) monitors the specified JMS request queue for messages. When the engine detects a message on the queue it initiates the BW Process associated with that service operation.

Š       The BW process Engine invokes a stored procedure hosted by the USBRateTool database to retrieve the product rates data.   It creates a reply message with this information.

Š       The system sends a reply to another EMS-based response queue, which OSB monitors.

Š       OSB proxy service converts RESTFul response to http then sends a response to the client.

Š       There is a time-out limit related to messaging on both the client and host sides. When a time-out occurs, the system sends the USBSOAPFault in the response.

Exception Processing

[Discuss any processing exceptions the consumer should be aware of in connection with this service. Determine if this information is needed or not.]

Consumers access all services through the OSB gateway layer. Consumers must handle the following two types of faults, generated by either the gateway or implementation layers, when calling any of the ESD-hosted services:

Š       W3 Standard Fault (gateway-generated fault)

Š       USBSOAPFault (implementation-generated fault)

Refer to the technical implementation service guide for directions on implementing enterprise error codes for replies and fault messages. (This topic was called Error Codes in earlier ICD versions.)

Consumers that access this service through a reverse proxy will not see USBSOAPFaults as they will be converted to an http code 403/Forbidden reply.

Note: Each operation includes documentation on the specific error messages impacting that operation.


 

Service Time-Out Specifications

[Discuss the service time-out specs the consumer should be aware of in connection with this service. Determine if this information is needed or not.]

When time-outs occur, consumers should receive an USBSOAPFault in the following places:

Š       OSB Gateway:  W3C Standard Fault

Š       TIBCO Service layer: USBSOAPFault.

Important:

Š       Consumers need to set the time-out value higher than the OSB Gateway time-out value.

Š       Individual operations can have different time-out values, which are documented in the specific operation topics.

Š       The highest operation time-out values are set during the overall TIBCO service implementation. For example, a service has three operations. If the first and second operations need 10 seconds to process, but the third operation needs 20 seconds, then the TIBCO service time-out value is set at 20 seconds.)

At the TIBCO Service implementation for RatesRESTService 5.0, ESD determined that timeout of more than 18 seconds is appropriate.

The following diagram shows the end-to-end time-out intervals for the various system components involved in the RatesRESTService 5.0 service.

Figure 3            End-To-End Timeout Intervals

Detailed Interface/Message Specifications by Service Operation

[Provide a detailed specification for each message/file identified in the previous topic. Describe what an operation provides based on its inputs.]

This topic provides detailed processing specifications about the REST resources for this service.

GetAutoLoanRates

[Note: The operation name is part of the URI value. Repeat this topic for all the operations included in a service.]

The following topics describe this operation.

Operation Description

[The Architects write the service and operation descriptions before the ICD is completed and enter them in the Repository. The operation description should be copied from the Long Desc field in the Repository entry for the service.]

 [Describe what this operation does in terms of information included in the request and reply and any tasks it performs, for example validations or information transfer.]

The GetAutoLoanRates operation is used to query the rate tool database and return the automotive loan product rates. The operation also returns the annual percentage rate (APR), discount and origination rates.

Processing Specifications

[Provide a description about how to actually use the documented operation. For example discuss how to use the data windowing feature of the operation, if it is present, and any other pertinent information needed to consume this operation. Refer to the service’s Error! Hyperlink reference not valid. if that is sufficient to document the processing specifications for most of its operations.]

This topic describes the most common processing pattern used by the service operations. If this pattern does not apply to an operation, that operation will contain a description of its unique processing pattern.

Š       See Processing Specifications for service-level processing specifications.

Š       This operation takes a choice of branch number/zip code/USB Region Id, plus optional loan amount and the loan term in months, and loan product (e.g. new car loan, refinance) as input parameters.  It returns a list of current auto loan rate “tiers”.   Tier information includes the loan product type (new, refinance, used through dealer, used through a private party), tier minimum and maximum $ amounts (e.g.  $3000-$4999.99), tier minimum and maximum terms in months (e.g.  37 to 48), the rate, and origination fee.    Adding the optional loan amount, loan term, and loan product input parameters filters down the number of tiers returned in the response.                                                               

Š       If sent a zip code in the request, the TIBCO BW process will invoke the ATMBranchLocatorService_V_8_0 GetListATMorBranch operation to retrieve the nearest branch number.  The list of branches is filtered to eliminate drive-up and ATM-only branches.

Š       The TIBCO BW process will make one stored procedure call to the USBRateTool database to retrieve the auto loan rate data.

USBRateTool Stored Procedure Flow

There is one OSB/TIBCO service call and one SQL server stored procedure used by this operation. The process flow is explained in this diagram:

USBRateTool Stored Procedure

SEL_MobileAuto_XML

This stored procedure exists in the USBRateTool SQL server database. It returns the auto loan rates info.

PROCEDURE SEL_MobileAuto_XML (

       @RegionCD     char(4)       = NULL ,

       @BranchID     int           = NULL ,

       @Amount       decimal(18,2)        ,

       @Term         smallint )

 

Only one of the first two input parameters is required. If both are provided, then the @RegionCD will be determined by @BranchID.

 

Sample call with results:

 

EXEC SEL_MobileAuto_XML NULL,    1,   NULL, 45

 

<Summary Branch="1" RegionCD="(not provided)" AcapsKEY="AUTOF" Amount="(Not provided)" Term="45">

    <Tier TierMIN="3000.00" TierMAX="5999.99" OrigFee="100.00">

           <Term TermMIN="37" TermMAX="48">

                  <Rates FinType="NEW" Rate="2.87000"/>

                  <Rates FinType="USED_DLR" Rate="2.87000"/>

                  <Rates FinType="USED_PP" Rate="3.37000"/>

                  <Rates FinType="REFI" Rate="2.87000"/>

           </Term>

    </Tier>

    <Tier TierMIN="6000.00" TierMAX="9999.99" OrigFee="75.00">

           <Term TermMIN="37" TermMAX="48">

                  <Rates FinType="NEW" Rate="2.00000"/>

                  <Rates FinType="USED_DLR" Rate="2.10000"/>

                  <Rates FinType="USED_PP" Rate="3.76000"/>

                  <Rates FinType="REFI" Rate="2.87000"/>

           </Term>

    </Tier>

    <!--...probably a total of 6 <Tier> elements if I understand the data in the test environment..   -->

    <Tier TierMIN="30000.00" TierMAX="50000.00" OrigFee="50.00">

           <Term TermMIN="37" TermMAX="48">

                  <Rates FinType="NEW" Rate="2.87000"/>

                  <Rates FinType="USED_DLR" Rate="2.87000"/>

                  <Rates FinType="USED_PP" Rate="3.37000"/>

                  <Rates FinType="REFI" Rate="2.87000"/>

           </Term>

    </Tier>

</Summary>

Functional Scenarios

[Document any functional scenarios, if they exist, that help the consumer understand the operation better.]

The following scenarios demonstrate how to set up the operation for functional testing and usage.

N/A

Pagination or Scrolling for Results Using the GetList Aggregate

[Keep this topic as-is if an operation uses the standard scrolling/pagination or delete the text and insert NA after the heading if this topic is not applicable to an operation.]

ESD enterprise services use the GetList aggregate type in both requests and replies for services that require scrolling. The usage is slightly different for both requests and replies between service implementation and consumption.

NA


 

Operation to Data Source Reference Table

Service Operation Name

Source System Name

Source System Transaction / Message Name

GetAutoLoanRates

SQL Server Database

USBRateTool SEL_MobileAuto_XML

GetAutoLoanRates

ATM Branch Locator Service (Microsoft Bing Locator Service)

GetListATMorBranch

Field/Element Specifications

[Define the individual fields/elements found in the message/file. Include information like data type, length, whether it is required or optional, valid ranges, etc.]

This section explains all of the field-level elements for the request and response aggregates.

 


GetAutoLoanRates Request URI Parameters

Name

Type

Width

Req?

Description

Host Field Name

  /GetAutoLoanRates

 

 

Y

 

 

application

string

1 to 30

Y

Requesting Application Identifier – Contact ESD to determine an application specific value

Value for logging and troubleshooting

transactionid

string

36

Y

UUID – Universally Unique Identifier, A unique identifier value

Value for logging and troubleshooting

output

string

3 or 4

N

Reply data format

Allows choice -XML or JSON. Default is XML

Anything besides case insensitive “ json” is XML

 

callback

string

1 to 30

N

JSONP Callback

Callback will be wrapped around JSON data if included

(Applies only if output=json)

 

branchnumber

string

1 to 4

N/Y *

The US Bank branch number

 

zipcode

string

5

N/Y *

A code established by a countrys postal service to facilitate mail delivery.  This is a 5 digit numeric

code in the U.S.

 

regionid

string

1 to 5

N/Y *

A US Bank region code

 

loanamount

decimal

15.2

Y

The amount of the loan

 

loantermmonths

Non-negative integer

1 to 9999

Y

The number of months in the term of the loan

 

loanproduct

string

4 to 8

N

Loan product:   New or Used through Dealer, Used through a private party, Refinance.  Values:

NEW|USED_DLR|USED_PP|REFI

 

* - A request requires at least one branchnumber, zipcode, or regionid (shaded box border). 

Y/N represents a parameter that is overall not required (as one of the other “or’s” can be supplied) but is required if the specific type is used. 

(if one of branchnumber, zipcode, or regionid is not supplied, a validation error will be indicated in the reply)

GetAutoLoanRatesReply

Depending on the output and callback parameters supplied, the reply is either:

output=json and callback=fn_name :                    JSONP (JSON data wrapped in function name)

output=json :                                                          JSON data

output=xml (or ‘output’ parameter not specified):         XML

Name

Type

Width

Req?

Description

Host Field Name

Status

 

 

Y

 

 

   StatusCode

Integer

 

Y

00 = success

100 = error

Refer to the Status Code section

   Severity

String

 

Y

Enumeration

(Info, Error & Warning)

   StatusDescription

String

 

Y

Message Status Description 

   ServerStatusCode

String

 

N

Return Code from Host Systems

    ServerStatusDescription

String

 

N

Return Status Description from Host Systems 

   AdditionalStatus

 

 

N

 

N/A

 AutoLoanRates

AutoLoanRatesDetail

 

N

Repeats for each auto loan product

 

   RetrievedDate

Date

 

Y

Date when the rates are retrieved

(current date)

   RateTier

AutoLoanRateTierDetail

 

Y

Repeats 1 or more times per rate “tier”

 

       RateProductType

String

 

Y

Type of Auto Loan product:

Š       NEW    -- new car

Š       “USED_DLR” – used car through dealer

Š       “USED_PP” – used car through private party

Š       “REFI” -- refinance

@FinType

        TierMinimumLoan

        Amount

Amount

 

Y

Minimum $$ in the range of loan amounts for this tier

@TierMIN

        TierMaximumLoan

        Amount

Amount

 

Y

Maximum $$ in the range of loan amounts for this tier

@TierMAX

        TierMinimumTermIn

        Months

Non-negative integer

 

Y

Minimum number of loan term months for this tier

@TermMIN

        TierMaximumTermIn

        Months

Non-negative integer

 

Y

Maximum number of loan term months for this tier

@TermMAX

       Rate

Decimal

15.5

Y

Loan Rate  (e.g. 2.87000)

@Rate

       OriginationFee

Decimal

9.2

Y

Loan Origination Fee

@OrigFee

 

Example GET for GetAutoLoanRates:

https://publicrestservice.usbank.com/public/RatesRestService_V_5_0/GetAutoLoanRates?application=RIB&output=xml&zipcode=80130&loanamount=24000&loantermmonths=12

https://publicrestservice.usbank.com/public/RatesRestService_V_5_0/GetAutoLoanRates?application=RIB&output=json&zipcode=80130&loanamount=24000&loantermmonths=12

https://publicrestservice.usbank.com/public/RatesRestService_V_5_0/GetAutoLoanRates?application=RIB&output=json&zipcode=80130&loanamount=24000&loantermmonths=12&callback=MyCallback

https://publicrestservice.usbank.com/public/RatesRestService_V_5_0/GetAutoLoanRates?application=RIB&output=json&branchnumber=1


Exception Processing

[Document operation-specific error codes here.]

This topic describes the service specifications for SOAP faults and status aggregate error codes. See Exception Processing for additional details about the USBSOAPFault and W3 standards.

Š       Consumer will either receive the SOAP fault or the ESD standard status aggregate in the response, which tracks the execution status of the service operation.

Š       If the request data is not valid a USBSOAPFault with IssueIdentifier set to 400 will be returned.

Š       If the request causes and unhandled exception, a USBSOAPFault with IssueIdentifier set to 500 will be returned.

Š       When a service does not execute successfully, the consumer receives the SOAP fault, which the [USBOAPFault / W3 standard fault / custom fault] operation produces.

Š       When a service executes successfully, the consumer receives the ESD standard status aggregate.

Note that using this service through a reverse proxy will result in faults being converted to an http 403/Forbidden response.

Service layer returns a SuccessCode of 0 in the status aggregate, but if the host returns any conditional error codes, consumers use the table to determine the cause of the issue.

Š       ESD maps all undocumented error code/condition to StatusCode 100, which is General Error. [Add any additional exception processing details here.]


StatusCode

Hogan PAS simulator needs to be used to identify the following error scenarios:

The status code is the IFX code.

Description is IFX description plus the host description

Status Code

Severity

Status Description

Server Status Code

Server Status Description

Additional details

0

Info

Success

200

ACTION SUCCESSFUL

 

1120

Warning

No Records Match Selection Criteria

N/A

N/A

No loan details could not be obtained due to loan terms, loan amounts not in the correct range.


GetCurrentCertificateofDepositRates

[Note: Repeat this topic for all the operations included in a service.]

Operation Description

[The Architects write the service and operation descriptions before the ICD is completed and enter them in the Repository. The operation description should be copied from the Long Desc field in the Repository entry for the service.]

 [Describe what this operation does in terms of information included in the request and reply and any tasks it performs, for example validations or information transfer.]

The GetCurrentCertificateofDepositRates operation is used to retrieve a list of current certificate of deposit (CD) product rates, including bonus rates and disclosures where applicable, and return the information to the consumer application. Input parameters include the customer type, a list of product and sub product codes, branch number, region id, category id and zip code.

Processing Specifications

[Provide a description about how to actually use the documented operation. For example discuss how to use the data windowing feature of the operation, if it is present, and any other pertinent information needed to consume this operation. Refer to the service’s Error! Hyperlink reference not valid. if that is sufficient to document the processing specifications for most of its operations.]

This topic describes the most common processing pattern used by the service operations. If this pattern does not apply to an operation, that operation will contain a description of its unique processing pattern.

Š       See Processing Specifications for service-level processing specifications.

Š       This operation takes product code, sub-product code, opening balance, rate effective date and a region identifier as input parameters and returns a list of current certificate of product rates, including step-up rates where applicable, information back to the consumer application.

Š       The consumer application has the flexibility of retrieving rates based on product and sub-product code.

Š       If sent a zip code in the request, the TIBCO BW process will invoke the ATMBranchLocatorService_V_8_0  GetListATMorBranch operation to retrieve the nearest branch number.  The list of branches is filtered to eliminate drive-up and ATM-only branches.

Š       If this operation is sent a zip code where the nearest branch is further than 250 miles away (and the “Out-of-Footprint” functionality is turned on through configuration), the operation will return rates for the “Out-of-Footprint” branch (24-hour banking).    (PM12297) 

Š       The TIBCO BW process will make one call to the data source HOGAN PAS to retrieve the rate information.

Functional Scenarios

[Document any functional scenarios, if they exist, that help the consumer understand the operation better.]

The following scenarios demonstrate how to set up the operation for functional testing and usage.

NA

Pagination or Scrolling for Results Using the GetList Aggregate

[Keep this topic as-is if an operation uses the standard scrolling/pagination or delete the text and insert NA after the heading if this topic is not applicable to an operation.]

ESD enterprise services use the GetList aggregate type in both requests and replies for services that require scrolling. The usage is slightly different for both requests and replies between service implementation and consumption.

NA

Operation to Data Source Reference Table

This table shows the operation and the provider system of record (SOR).

Service Operation Name

Source System Name

Source System Transaction/Message Name

GetCurrentCertificateofDepositRates

[HOGAN PAS]

HOGAN PAS

ERATEIP0

GetCurrentCertificateofDepositRates

ATM Branch Locator Service (Microsoft Bing Locator Service)

GetListATMorBranch

Field/Element Specifications

[Define the individual fields/elements found in the message/file. Include information like data type, length, whether it is required or optional, valid ranges, etc.]

This section explains all of the field-level elements for the request and response aggregates.


GetCurrentCertificateofDepositRates Request URI Parameters

Name

Type

Width

Req?

Description

Host Field Name

  /GetCurrentCertificateofDepositRates

Y

 

 

application

string

1 to 30

Y

Requesting Application Identifier – Contact ESD to determine an application specific value

Value for logging and troubleshooting

transactionid

string

36

Y

UUID – Universally Unique Identifier, A unique identifier value

Value for logging and troubleshooting

output

string

3 or 4

N

Reply data format

Allows choice -XML or JSON. Default is XML

Anything besides case insensitive “ json” is XML

 

callback

string

1 to 30

N

JSONP Callback

Callback will be wrapped around JSON data if included

(Applies only if output=json)

 

branchnumber

string

1 to 4

N/Y *

The US Bank branch number

X77098-RSI-BRANCH

zipcode

string

5

N/Y *

A code established by a countrys postal service to facilitate mail delivery.  This is a 5 digit numeric

code in the U.S.

NA

productcode

string

3

Y

Hogan Product Code

A 3-character code used to identify a product.  Valid codes:

DDA = Checking and Savings Accounts

CDA = Certificate of Deposit Account

REA = Retirement Account

LOC = US Bank Reserve Line

ATM = UBANK ATM Card 

CHX = UBANK Check Card

STM = Combined Statement

PKG = Package

X77098-RSI-PROD-CODE

subproductcode

string

2

Y

Hogan subproduct code

Identifies a specific sub unit of a product and is based on a set of features associated with an account.

This is not a definitive (or confirmed accurate) list, but these product codes can have these SubProductCodes:

DDA: 92,GS,EC,NL,GW,86,MM,PS,32,33,RS

REA: RM

CDA: K4,R3,J1,J2,R1,S1,J7,J8

X77098-RSI-SUB-PROD-CODE

openingbalance

amount

 

N

Balance amount of the certificate of deposit that will be used to look up the rate information.  Note if this is left blank then an array of rates by amount will be returned

X77098-RSI-BALANCE

rateeffectivedate

date

 

Y

Date that the rate is to take effect

The effective date for the assigned interest rate. 

e.g. 2014-07-03

X77098-RSI-EFF-DATE

 

* - A request requires at least one branchnumber, zipcode, or regionid (shaded box border). 

Y/N represents a parameter that is overall not required (as one of the other “or’s” can be supplied) but is required if the specific type is used. 

(if one of branchnumber, zipcode, or regionid is not supplied, a validation error will be indicated in the reply)

GetCurrentCertificateofDepositRatesReply

Name

Type

Width

Req?

Description

Host Field Name

Status

 

 

Y

 

 

   StatusCode

Integer

 

Y

00 = success

100 = error

Refer to the Status Code section

   Severity

String

 

Y

Enumeration

(Info, Error & Warning)

 

   StatusDescription

String

 

Y

Message Status Description 

 

   ServerStatusCode

String

 

N

Return Code from Host Systems

 

    ServerStatusDescription

String

 

N

Return Status Description from Host Systems 

 

   AdditionalStatus

 

 

N

 

N/A

CertificateofDepositsRates

CertificateofDepositsRates (repeating 0 or more)

 

N

This will be either the rate by amount asked for or the entire table of rates by amounts.

 

  OpeningAmount

usbsoatl:Amount

 

Y

This is the minimum amount of the certificate of deposit that this rate information is for

X195-OUT-BAL

  TermInDaysCount

usbsoatl:NumberNonNegative04

4

N

This is the term of the certificate of deposit expressed in days.  This is only present if the TypeCode filed is set to NonePerodicSchedule

X195-OUT-TERM-D

  TermInMonthsCount

usbsoatl:NumberNonNegative04

4

N

This is the term of the certificate of deposit expressed in months.  This is only present if the TypeCode filed is set to NonePerodicSchedule

X195-OUT-TERM-M

  AnnualPercentageRate

usbsoatl:Rate5Decimal

 

Y

This is the annual percentage rate used to compute interest paid on the certificate of deposit.  This field will be left blank if this is not a single term rate over the life of the instrument.

X195-OUT-APR

 AnnualPercentageYieldRate

usbsoatl:Rate5Decimal

 

Y

This is the annual percentage yield rate on the certificate of deposit.  This field will be left blank if this is not a single term rate over the life of the instrument.  This filed will represent the blended APY for certificate of deposits that have periodic rates defined.

X195-OUT-APY 

OR

X77098-RSR-STPUP-BLEND-APY

  TypeCode

mrs:TypeCodeEnumeratedList

 

Y

This is an enumerated list specifying the type of rate information being returned.  The enumerated list is: “NonePerodicSchedule” or “PerodicSchedule (Stepup Rate)”

NA

  PeriodRateList

Sequence from 0 to many

0 to many

Y

This is a list of periods and rate information associated with each period.  This information will only be present of the TypeCode is set to “PerodicSchedule”

 

    PeriodCount

usbsoatl:NumberNonNegative02

2

Y

This is a count from 1 to N of the period this rate information is associated with.

NA

    PeriodCode

usbsoatl:String0001

1

Y

This code will be one of three values: ‘M’ for Month, ‘D’ for Day and ‘Y’ for year.  This indicates the period length will be specified in one of these units.

X77098-RSR-PERIOD-CODE

    PeriodTermCount

usbsoatl:NumberNonNegative04

4

Y

This is the count of how long the period is specified in units described by the PeriodCode.

X77098-RSR-STUP-TERM

    AnnualPercentageRate

usbsoatl:Rate5Decimal

 

Y

This is the annual percentage rate used to compute interest paid on the certificate of deposit for this period.

X77098-RSR-STUP-RATE


Example GETs for GetCurrentCertificateofDepositRates:

https://publicrestservice.usbank.com/public/RatesRestService_V_5_0/GetCurrentCertificateofDepositRates?application=ICApply&output=xml&ProductCode=CDA&SubProductCode=R1&BranchNumber=1&RateEffectiveDate=2014-04-05

https://publicrestservice.usbank.com/public/RatesRestService_V_5_0/GetCurrentCertificateofDepositRates?application=ICApply&output=json&ProductCode=CDA&SubProductCode=R1&ZipCode=80130&RateEffectiveDate=2014-04-05&callback=MyCallBackFunction&OpeningBalanceAmount=25000

Exception Processing

[Document operation-specific error codes here.]

This topic describes the service specifications for SOAP faults and status aggregate error codes. See Exception Processing for additional details about the USBSOAPFault and W3 standards.

Š       Consumer will either receive the SOAP fault or the ESD standard status aggregate in the response, which tracks the execution status of the service operation.

Š       If the request data is not valid a USBSOAPFault with IssueIdentifier set to 400 will be returned.

Š       If the request causes and unhandled exception, a USBSOAPFault with IssueIdentifier set to 500 will be returned.

Š       When a service does not execute successfully, the consumer receives the SOAP fault, which the [USBOAPFault / W3 standard fault / custom fault] operation produces.

Š       When a service executes successfully, the consumer receives the ESD standard status aggregate.

Note that using this service through a reverse proxy will result in faults being converted to an http 403/Forbidden response.

Service layer returns a SuccessCode of 0 in the status aggregate, but if the host returns any conditional error codes, consumers use the table to determine the cause of the issue.

Š       ESD maps all undocumented error code/condition to StatusCode 100, which is General Error. [Add any additional exception processing details here.]


StatusCode

Hogan PAS simulator needs to be used to identify the following error scenarios:

The status code is the IFX code.

Description is IFX description plus the host description

Status Code

Severity

Status Description

Server Status Code

Server Status Description

Additional details

0

Info

Success

200

ACTION SUCCESSFUL

 

1120

Warning

No Records Match Selection Criteria

N/A

N/A

No loan details could not be obtained due to loan terms, loan amounts not in the correct range.


GetCurrentDepositRates

[Note: Repeat this topic for all the operations included in a service.]

Operation Description

[The Architects write the service and operation descriptions before the ICD is completed and enter them in the Repository. The operation description should be copied from the Long Desc field in the Repository entry for the service.]

 [Describe what this operation does in terms of information included in the request and reply and any tasks it performs, for example validations or information transfer.]

The GetCurrentDepositRates operation is used to retrieve a list of current deposit product rates, including bonus rates and disclosures where applicable, and return the information to the consumer application. Input parameters include the customer type, a list of product and sub product codes, branch number, region id, category id and zip code.

Processing Specifications

[Provide a description about how to actually use the documented operation. For example discuss how to use the data windowing feature of the operation, if it is present, and any other pertinent information needed to consume this operation. Refer to the service’s Error! Hyperlink reference not valid. if that is sufficient to document the processing specifications for most of its operations.]

This topic describes the most common processing pattern used by the service operations. If this pattern does not apply to an operation, that operation will contain a description of its unique processing pattern.

Š       See Processing Specifications for service-level processing specifications.

Š       This operation takes the following input parameters: customer type (e.g. CONSUMER), one of region id/branch number/zip code, an optional account balance, and a choice between a list of product/sub product codes and a category id (where a category is something like “consumer checking and savings accounts).   It returns a list of current deposit product rates, including bonus rates and disclosures where applicable, information back to the client application.

Š       The consumer application has the flexibility of retrieving rates based on either a product/sub-product code combination or by one of the location identifier choices made available to them i.e. branch, zip code, or region id.

Š       If sent a zip code in the request, the TIBCO BW process will invoke the ATMBranchLocatorService_V_8_0  GetListATMorBranch operation to retrieve the nearest branch number.  The list of branches is filtered to eliminate drive-up and ATM-only branches.

Š       If this operation is sent a zip code where the nearest branch is further than 250 miles away (and the “Out-of-Footprint” functionality is turned on through configuration), the operation will return rates for the “Out-of-Footprint” branch (24-hour banking).    (PM12297) 

Š       The TIBCO BW process will make one or more stored procedure calls to USBRateTool based on customer type and product to get rate information.


USBRateTool Stored Procedure Flow

There are three SQL server stored procedures used in this operation. The process flow is explained in this section. Some of the parameters are option and TIBCO BW will skip some of the parameters and some parameters are hard coded values which are populated from the TIBCO BW global variables.


USBRateTool Stored Procedure

SEL_PricingRegionByBranchID

Exist in USNRateTool SQL server database. Returns the RegionID.

PROCEDURE dbo.SEL_PricingRegionByBranchID(

       @BranchID     smallint,

       @EffectiveDT  smalldatetime = NULL)

Sample call: EXEC SEL_PricingRegionByBranchID 8003

SEL_RatesAndDisclosures

Exist in USNRateTool SQL server database. Returns the Rates info.

CREATE PROCEDURE [dbo].[SEL_RatesAndDisclosures] (

       @CategoryTypeID  tinyint     = 1   , -- eg. 0 Credit; 1 Deposit; 2 Small Bus; ... DEPOSIT (1) is the only valid NON-NULL option

       @CategoryID      tinyint     = NULL, -- eg. 7 Consumer Checking and Savings; 9 Business Checking and Savings; ...

       @BranchID        int         = NULL,

       @RegionCD        char(4)     = NULL,

       @ProdCD          varchar(4)  = NULL,

       @SubProdCD       char(2)     = NULL)

 

For Mortgage Rates

CREATE PROCEDURE [dbo].[SEL_RatesAndDisclosures] (

PROCEDURE [dbo].[SEL_RatesAndDisclosures] (

       @CategoryTypeID  tinyint     = 7   , -- eg. 0 Credit; 1 Deposit; 2 Small Bus; a new one will be created for Mortgage

       @CategoryID      tinyint     = NULL, -- a new one will be created for Mortgage; either this or the above parameter will work

       @BranchID        int         = NULL, -- either this or the @RegionCD will be required

       @RegionCD        char(4)     = ‘DFLT’, -- either this or the @BranchID will be required

       @ProdCD          varchar(4)  = NULL, -- unused by Mortgage; either pass NULL or simply omit

       @SubProdCD       char(2)     = NULL  -- unused by Mortgage; either pass NULL or simply omit

Functional Scenarios

[Document any functional scenarios, if they exist, that help the consumer understand the operation better.]

The following scenarios demonstrate how to set up the operation for functional testing and usage.

NA

Pagination or Scrolling for Results Using the GetList Aggregate

[Keep this topic as-is if an operation uses the standard scrolling/pagination or delete the text and insert NA after the heading if this topic is not applicable to an operation.]

ESD enterprise services use the GetList aggregate type in both requests and replies for services that require scrolling. The usage is slightly different for both requests and replies between service implementation and consumption.

NA


Operation to Data Source Reference Table

This table shows the operation and the provider system of record (SOR).

Service Operation Name

Source System Name

Source System Transaction/Message Name

GetCurrentDepositRates

SQL Server Database

USBRateTool

Sp - SEL_RatesAndDisclosures

Sp- SEL_PricingRegionByBranchID

GetCurrentDepositRates

ATM Branch Locator Service (Microsoft Bing Locator Service)

GetListATMorBranch

Field/Element Specifications

[Define the individual fields/elements found in the message/file. Include information like data type, length, whether it is required or optional, valid ranges, etc.]

This section explains all of the field-level elements for the request and response aggregates.

See section USBRateTool Stored Procedure Flow for mapping details.

 


GetCurrentDepositRates Request URI Parameters

Name

Type

Width

Req?

Description

Host Field Name

application

string

1 to 30

Y

Requesting Application Identifier – Contact ESD to determine an application specific value

Value for logging and troubleshooting

transactionid

string

36

Y

UUID – Universally Unique Identifier, A unique identifier value

Value for logging and troubleshooting

output

string

3 or 4

N

Reply data format

Allows choice -XML or JSON. Default is XML

Anything besides case insensitive “ json” is XML

 

callback

string

1 to 30

N

JSONP Callback

Callback will be wrapped around JSON data if included

(Applies only if output=json)

 

customertype