jXchange Behaviors
Canonicals
Canonicals normalize data that is common to all business service providers. It is a representation of data that is the same through all providers. Documentation can be found within the XSD contract files.
Nulls
JHA Null notifies the business service to ignore the specified element.
| Nil Value | MOD | ADD |
|---|---|---|
| True | Remain | Set to Default |
| Element Value | Core Value Before | Core Value After |
|---|---|---|
| < element> </ element> | ‘Y’ | ‘Y’ |
| < element/> | ‘Y’ | ‘Y’ |
| JHANull = True | ‘Y’ | ’ ' |
SvcPrvdInfo
The SvcPrvdInfo tag is intended to indicate that any element under this XML branch will not be available for third party (non-JH) consumption. Elements mapped under the SvcPrvdInfo node are not available by default and require bank‑level custom coding. To obtain access to any of these elements, each financial institution must submit a Custom Work Request (CWR) for implementation. In some instances an element found under this node may also be found elsewhere within the API when it has been determined that the element should be made available for general consumption.
Version Tags
Version tags that are found throughout the contracts represent the point where new elements have been added for enhancements purposes. The labels, such as ver_1 or ver_2, do not represent a specific jXchange point release, but indicate the number of additions to that specific contract.
X_
To limit the size of the response payload and in an attempt to return relevant information to the request, jXchange incorporates the use of x_ elements for inquiries. These elements function as canonical values to specify the specific information needed by the consumer of the web service.
For example, when performing an account inquiry on a deposit account, not all information available is useful or needed for that specific request. The information needed can be limited to a much smaller set of values to work with. The x_ values are added to the request array element, IncXtendElemArray. The valid values are found in the corresponding response for that particular operation. If requested, the x_ value is found in the matching complex element in the response.
Element Types
| Element Type | Description | Example |
|---|---|---|
| MType | Major messaging complex. All other element types are carried within either a request or response MType complex for messaging. A request or response MType may contain one or more of each of the other element types, though not required. An MType is the only complex containing an Rq or Rs designation to denote whether it is a request or response message complex. | AcctInqRq_MType, AcctInqRs_MType |
| CType | Structural complex contained within an MType, AType. x_Type, and/or another CType complex. May contain one or more of any or all of the other types except for an MType. (CType, AType, x_Type, or simple element types.) | InAcctId_CType, DepAcctInqRec_CType, DepInfoRec_CType |
| AType | Array complex contained within a CType, x_Type, and/or an MType complex. It will contain one or multiple iterations of a single element that may be of CType, x_Type, AType, or a simple element type. Only the one specified element will appear in an array, though that specified element may appear multiple times. | IncXtendElemArray_AType, CondNotfArray_AType |
| x_Type | Optional complex element with the same structure as a CType complex element, but that will only be returned to a third party client by specific request from the client. The request is made using an IncXtendElemArray_AType complex in the request message. The x_Type can be contained within a CType, MType, AType, or within another x_Type. | X_DepInfoRec_CType, XDepAcctInfo_CType |
| Simple | Simple element type that can be contained in any or all of the other element types. The simple type is the only element type that contains a value. A simple type will not contain any other element. | AvlBal_Type, CurBal_Type |
MTOM
MTOM, Message Transition Optimization Mechanism, is supported by jXchange. It supports sending attachments in a web service message. More information may be found here.
Institutional Routing
The ABA nine digit number assigned to financial institutions for the purpose of routing can be used as the routing number.
Institution Routing ID: Routing Number is required. The bank’s ABA number is used as the Routing Number.
Institution Environment: Required when using the Institution Routing ID.
The Institution Routing ID and Institution Environment must be used together and are both in
the jX heading. There could be two environments with the same ID (ABA number), such as bank
123456789 PROD and 123456789 TEST. In the jXchangeHDR, you can specify both InstRtId and
InstEnv, and they are used during authorization to validate that you have access to the specified
institution and environment. If they are not specified, the jXchange servers default them to the institution
and environment that the user name is attached to with default values. Only a single institution can be
configured as the default for a given user name. jXchange 2012.0 and higher allows for a single user
name to have access to multiple configured institutions by using the InstRtId and InstEnv elements to
guide the routing of the message. This feature is not guaranteed to be available as it is a security choice
for the banks to make. But you can ensure that your software can handle specifying InstRtId and InstEnv
for future compatibility. These values are delivered with the credentials from the installation team for any
particular bank.
Search Record Request and Response Behavior via Cursor Usage
To keep boundaries and payloads efficient, search services are designed to return large data sets in segments using the MaxRec and Cursor elements.
For example: Account 1234/D has 145 transaction records that could be returned using the Account History Search (AcctHistSrch) API. The consumer does not know how many records could be provided, but does know they can accept 50 records at a time. The chart below shows the flow of the MaxRec and Cursor element in use.
Search Wildcards in jXchange
Search message request filter elements are decorated with an attribute that clearly conveys to the service provider the search expression. The search type attribute is enumerated with the values; Exact, StartsWith, EndsWith, Contains, and ContainsAll. These enumerated values could evolve based on industry standard operand expressions.
A service provider cannot require exact case matches. For example, if a consumer submits a last name data value of ~mcgrath~ then the service provider should respond back with any data values that match regardless of case which could include but not limited to ~McGrath~, ~Mcgrath~, ~mcgrath~, ~MCGRATH~ or any combination of case difference thereafter.
The search type value [ContainsAll] was placed into production in Release 2015.0.08. The [ContainsAll] should return the matched values that contain all of the values included in the search type attribute. This differs from the canonical value [Contains] which is much broader. The specific example is provided below.
Not all search message request filters qualify for wildcard searches. These include but not limited to enumerated elements, key elements, and range selection elements.
Request: <LastName SrchType="Exact">Smi</LastName>
Response: <LastName>Smi</LastName>
<FirstName>John</FirstName>
<LastName>Smi</LastName>
<FirstName>Joe</FirstName>
Request: <LastName SrchType="Contains">Smi</LastName>
Response: <LastName>Smi</LastName>
<FirstName>John</FirstName>
<LastName>Smi</LastName>
<FirstName>Joe</FirstName>
<LastName>LockSmith</LastName>
<FirstName>Jane</FirstName>
Request: <LastName SrchType="EndsWith">Smi</LastName>
Response: <LastName>Dritiesmi</LastName>
<FirstName>Lucas</FirstName>
Request: <LastName SrchType="StartsWith">Smi</LastName>
Response: <LastName>Smith</LastName>
<FirstName>Mike</FirstName>
<LastName>Smitherrens</LastName>
<FirstName>Jason</FirstName>
<LastName>Smitty</LastName>
<FirstName>James</FirstName>
Request: <ComName SrchType="ContainsAll">Martha G jones</ComName>
Response: <ComName>Martha G Jones</ComName>
<ComName>G Martha Jones</ComName>
<ComName>Jones G Martha</ComName>
<ComName>Martha Glayds Jonestien</ComName>
End of Day Core Processing and jXchange
Nightly processing, End of Day (EOD), Nightly Updates, Daily Updates, DayEnd are all synonymous terms describing a core banking task that completes a business day. This task is a core requirement that involves many functions that are too numerous to list here but a few items are to post transactions to account history, accrue interest, create reports, update account balances and many other responsibilities. The duration of nightly processing can vary greatly from institution to institution. During the processing window, it is important that data remains in a state that is consistent throughout processing. To ensure the integrity of the data, integration messages through jXchange are limited to Inquiry and Search functions only. These messages are identified by the suffixes of ‘Inq’ and ‘Srch’. Operations that end with ‘Add’, ‘Mod’ and ‘Validate’ are restricted during the processing window.
Below are the specific behaviors based on the 3 JHA banking cores that provide services to jXchange.
SilverLake and CIF 20/20 – Core Applications
Inquiry and Search APIs
Inquiry and Search operations are always available and are not restricted during End of Day (EOD) nightly processing. Except for Store Forward Messages (XferAdd, XferMod and XferSrch), the core programs called Business Services, are EOD aware, which means they know the last point during EOD processing where they can safely add or update records. The Store Forward Messages continue to behave as normal during Nightly Processing. The difference is SilverLake will hold the transaction and apply it to the next business day.
Addition and Modification APIs
When calling an operation that is not available during nightly processing, a fault response will be returned with the error code of ‘34’ and a description of “Function is not available during Nightly Updates”. The operation will remain unavailable until processing has completed.
Here is an example message response for an operation that is not available during the processing window when one the following core applications are present.
Addition APIs - SilverLake Enhancement
Several jXchange Add messages can now be made available during end-of-day (EOD) processing. Previously, the Add messages included in this enhancement were unavailable during the majority of the EOD and would return the Error 34 described in the above section.
The following messages can now be made available during EOD processing. Data from these messages is captured in new tables during this process. That data is then merged into the counterpart live tables once EOD process completes. Some of these services were already available during the first portions of the EOD, but they can now be made available for the entirety of the EOD.
| Message Name | Description | Core Service Name |
|---|---|---|
| AcctAdd (D,S,X,T) | Account Add | DDACCTADD, CDACCTADD |
| AcctAddValidate(D,S,X,T) | Account Add Validate | DDACCTADD, CDACCTADD |
| AcctIDGen | Account ID Generation | JHACCTGEN |
| AddrAdd | Address Add | CFADDRADD |
| CustAdd | Customer Add | CFCUSTADD |
| CustRelAdd | Customer Relationship Add | CFRELTADD |
| IdVerifyAdd | ID Verify Add | CFMLIDADD |
| TrnAdd (D,S,X) | Checking Account Transaction Add | DDCRDRADD |
Core Director – Core Application
During the processing window, only Inquiry and Search based operations are available. Core Director’s JX interface won’t allow for any ‘Add’ or ‘Mod’ functions and if called, the error 1097 will be returned indicating Dayend is in progress. The operation will be available when DayEnd completes.
Additional products
SilverLake and CIF 20/20 share the same platform with additional JHA complimentary products. Among them are Netteller Host functions, Passport Host functions StreamLine and Argo Host functions. These products also provide additional business services to jXchange operations.
CPS/ATM Switch
For institutions using Jack Henry CPS, stand-in processing is managed at the switch/host level. CPS provides stand-in functionality that authorizes card transactions based on a file sent to the switch/host. These transactions are then forwarded to the core system once end-of-day (EOD) processing is complete or the core is back online.
If the financial institution (FI) uses a third-party switch or host, responsibility for handling outages falls on that provider.
Currently, CPS does not offer an API that enables inquiries or transaction additions through JX to the switch/host.
Summary
If an Inquiry or Search operation returns an error indicating it is not available during Nightly Processing or Dayend, a support call should be placed by the bank to the JH Call Center requesting the appropriate core provider group to assist. When SilverLake or CIF 20/20 is the core application, then the support case should be placed with the iAdapter Support provider group. When Core Director is present then with the CD/ACCESS provider group.
- Have a how-to question? Seeing a weird error? Get help on StackOverflow.
- Register for the Developer Office Hours where we answer technical Q&A from the audience.