Data elements in an ISO8583 payload are identified by their position within the message string. The position of each data element within the message is specified by its field number and its position within that field.

Sample Raw ISO8583 Message Payload

This is an incoming MTI 1200 ISO8583 message with binary values on the left and the message string on the right. When unpacked, this MTI 1200 looks like this:

Those values can be seen in the message string. GLU.Ware needs to be configured to unmarshall those values so the payload can be unpacked.

Sample ISO8583 MTI 0800 Message Payload:

0000 30 38 30 30 82 38 00 00 00 00 00 00 04 00 00 00 0800.8……….

0010 00 00 00 00 30 33 32 32 31 31 30 35 34 30 32 37 ….032211054027

0020 30 35 31 35 31 33 30 35 34 30 30 33 32 32 33 30 0515130540032230

0030 31 1

An ISO8583 message is made of the following parts:

Message type indicator (MTI)
One or more bitmaps, indicating which data elements are present. It consists of primary bitmap and secondary bitmap. This isn’t human readable.
Data elements, the actual information fields of the message- can be readable.

The placements of fields in different versions of the standard varies; for example, the currency elements of the 1987 and 1993 versions of the standard are no longer used in the 2003 version, which holds currency as a sub-element of any financial amount element.

https://www.ibm.com/docs/en/integration-bus/10.0?topic=formats-iso8583-messaging-standard

Unmarshalling of ISO parameters from the above data element section of an ISO payload relies on the specified position of the parameter in the data payload. The above data payload prints out with this value:

03221105402705151305400322301

This is unmarshalled in GLU by specifying the position and length of each parameter. Field lengths are specified in the packager:

Example above unmarshalls as follows:
Field[(7) Value (0322110540)] to Param :[transmissionDateAndTime]
Field[(11) Value (270515)] to Param :[systemTraceAuditNumber]
Field[(12) Value (130540)] to Param :[timeLocalTransaction]
Field[(13) Value (0322)] to Param :[dateLocalTransaction]
Field[(70) Value (301)] to Param :[NetMngInfoCode]

Unmarshalling Example in GLU.Console

Field 11 has a Field Number and some Field Data Settings:

Note: Subfields are referenced as field.subField: 63.2

**transmissionDateAndTime** from Date(NOW) parameter

This tells the GE that the transmissionDateAndTime parameter comes from Field #7 and is 10char.
This gives us the value above: 0322110540

That leaves the remainder of the payload to be broken down into the remaining parameters.

The parameters can then be used in requests to other systems in different protocols/content types as needed. Standard handler options are available for these values if required.

Unmarshalling from Content of ISO8583 values

Further unmarshalling of the contents of an ISO8583 value is also possible. For example, XML sent inside ISO8583 can be unmarshalled by the path of the required value.

Example:

<isomsg direction="incoming">
	<!-- org.jpos.iso.packager.GenericPackager[packagerISO8583.xml] -->
	<field id="0" value="1210"/>
	<field id="3" value="310000"/>
	<field id="4" value="000000002000"/>
	<field id="7" value="0308134849"/>
	<isomsg id="62">
		<!-- org.jpos.iso.packager.GenericSubFieldPackager -->
		<field id="3"><![CDATA[18IFSFData3584<IFSFData xmlns:ns0="http://www.nrf-arts.org/IXRetail/namespace">
	<ProductSets>
		<MessageText>~0011*      Terms and Conditions Apply      **    For queries contact Us    **     Customer Care 0860 30 40 50      *\</MessageText>
		<BalanceOfPoints>000000020</BalanceOfPoints>
		<PointsForTransaction>00000020</PointsForTransaction>
		<BasePointsEarned/>
		<AvailablePointsBalance>0000002725</AvailablePointsBalance>
		<NewPointsBalance>0000002725</NewPointsBalance>
		<PointsToMoneyRatio>000100</PointsToMoneyRatio>
		<RedemptionRefNumber>167827</RedemptionRefNumber>
	</ProductSets>
</IFSFData>]]></field>
	</isomsg>
	<field id="63" value="1CLRG4112033663407SLEV"/>
</isomsg>

The path for RedemptionRefNumber is IFSFData.ProductSets.RedemptionRefNumber- this would return the specific value for that XML parameter: 167827

Marshalling Example in GLU.Console

To respond to an ISO8583 request, the Marshalling is similar for simple payloads:

Specify the Field #:

Specify the parameter to be sent with parameter length:

For parameters with variable length, the value can be left-padded with leading characters (usually) zero OR the length can be calculated and added to the header of that parameter.

Create a value from other parameters:

To build up a single ISO parameter from multiple GLU parameters you add them in sequence and specify the position each value has for the ISO parameter:

This creates an ISO amount format with additional ISO info: accountType, currency etc:

Field[54] : 1002800C000002079748

Broken down from the above:
10 = accountType
02 = amountType
800 =currencyISOUGS (ISO currencyCode)
C = amountSign (Credit or Debit)
000002079748 = amountTransaction – this is an amount of 2079748, left padded with zeros to fill the required char count for the field. This value was previously rounded in the Derived Parameter.

Length Calculation

Get the Length:

2. Get length of the length (how many char for fieldLength):

3. Marshall these values into the required parameter:

Template:

18IFSFData${lengthField12722Length}${Field12722Length}${Field12722AllData}

Value:
Field[127.22] :
18IFSFData3588<IFSFData xmlns:ns0=”http://www.nrf-arts.org/IXRetail/namespace”><ProductSets><MessageText>* Terms and Conditions Apply ** For queries contact Pick n Pay ** Customer Care 0800 11 22 88 *</MessageText><BalanceOfPoints>46047</BalanceOfPoints><PointsForTransaction>0000215</PointsForTransaction><BasePointsEarned>0</BasePointsEarned><AvailablePointsBalance>0000046262</AvailablePointsBalance><NewPointsBalance>0000046262</NewPointsBalance><PointsToMoneyRatio>000100</PointsToMoneyRatio><RedemptionRefNumber>BP0000049184</RedemptionRefNumber></ProductSets></IFSFData>

The Blue Text is the Value (AllData)
The 588 is the length of AllData ((number of characters for the AllData value)
The 3 is the length (number of characters for the 588 length value)

Connector Settings

Packager:
An ISO8583 packager is responsible for encoding the data into the correct message format before sending it over the network, and for decoding the received message into usable data. It also performs tasks such as error checking, data validation, and data formatting to ensure that the message is transmitted accurately and efficiently.

Channel Type:
Refers to the type of communication channel used for transmitting ISO8583 messages between systems.

Send Message Length:
Adds the length of the message to the request.

ISO8583 Log Examples

A q2.log is generated in an ISO8583 GLU.Engine.
This happens before ISO8583 payloads are ingested into the GLU.Engine and print in the gluware.log.
Any investigation into an ISO8583 issue should start with the q2.log.
The q2.log uses the specified packager to validate payloads.

_{<isomsg direction="incoming">
  <!-- org.jpos.iso.packager.GenericPackager[packagerISO8583.xml] -->
  <field id="0" value="1200"/>
  <field id="3" value="310000"/>
  <field id="4" value="000000002000"/>
  <field id="7" value="0308131930"/>
  <field id="11" value="167827"/>
  <field id="12" value="230308011930"/>
  <field id="22" value="123456789112"/>
  <field id="49" value="200"/>
  <field id="59" value="292"/>
  <field id="63" value="1CLRG4112033663407SLEV"/>
</isomsg>}

When something goes wrong you might see an error packing/unpacking field X:

<session-error>
    <iso-exception>
      org.jpos.iso.IFA_LLCHAR: Problem unpacking field 12 (org.jpos.iso.ISOException: Field length 98 too long. Max: 25) unpacking field=127

This is saying Field 127.12 is too long.
This can be misleading – if any of the fields sent have different length compared to what the packager is expecting, the first field to fail will print in the log.
In this case, an extra Field was being sent- this skewed the unmarshalling/packager validation of subsequent Fields.
The best troubleshooting approach is to get the request message that was sent to compare it to what the packager supports/requires and what the config in the GLU.Engine is looking for. If the 3rd party is anable to change their request, the packager can be updated to cater for their payload.
If the extra parameter is required for further use in the GLU.Engine, it can be unmarshalled.
If it’s not required, the GLU.Engine can pass the value through without unmarshalling.

If there is no error in the q2.log, troubleshooting can continue with the gluware.log:
Standard Unmarshalling, Handler, Derived values and protocol translation issues or errors will print in the gluware.log.

Author: Jono Hacking

ISO 8583 Connector