version 3 release 23 (v3r23) uetr and its implementation · 2020. 3. 17. · instruction pattern...

box_UETR_v3r23.docx Edition 2019-12-31

Version 3 Release 23 (V3R23)

UETR and its Implementation

Table of Contents i

Table of Contents

1 INTRODUCTION TO UETR ............................................................................................................. 1

2 REQUIREMENTS FOR UETR ......................................................................................................... 2

2.1 FIELD 121 ................................................................................................................................... 2 2.2 FIELD 111 ................................................................................................................................... 3

3 IMPLEMENTATION IN BOX ........................................................................................................... 4

3.1 GPI [TAG 121 (UETR) IN USER HEADER] HANDLING IN BOX ........................................................ 4 3.2 BACKEND PLUGINS ...................................................................................................................... 5 3.3 TRANSPORT OF GPI FIELDS TO BACKEND...................................................................................... 6

3.3.1 Removing the UETR .......................................................................................................... 6 3.3.2 Mervabrige Plugin .............................................................................................................. 6 3.3.3 Generic Flat Buffer Plugin .................................................................................................. 6 3.3.4 Generic Flat Buffer Embargo Check Plugin ....................................................................... 6 3.3.5 Generic Attributes of Referenced Original Message Processing Sequence (MPS) .......... 7

4 GUI: INSERTING UETR (AND SERVICE IDENTIFIER) IN FIN MESSAGES ................................ 8

4.1 FIELDS 111 AND 121 ................................................................................................................... 8 4.2 MT202COV UETR ..................................................................................................................... 8

5 WORKFLOW ................................................................................................................................... 9

5.1 INTRODUCING CONTENT PROCESSING INSTRUCTION (CPI) CPIM_GPIPROC .................................... 9 5.1.1 Match Search Interval ...................................................................................................... 10 5.1.2 Match BIC8 List................................................................................................................ 10 5.1.3 Match Found Label .......................................................................................................... 10 5.1.4 Match Not Found Label ................................................................................................... 10 5.1.5 Parameter Data in CPI using a FIN GPI Processing Instance ........................................ 10 5.1.6 Working Theory of cpim_gpiproc ..................................................................................... 10

5.2 DETAILED WORKFLOW SETUP AND CONFIGURATION (EXAMPLE) .................................................. 11 5.2.1 Sample Workflow Elements ............................................................................................. 11

5.2.1.1 Schema of GTI Workflow MATCHCOV202................................................................................ 12 5.2.1.2 CPI: COV 202 Matching Configuration ...................................................................................... 13 5.2.1.3 Application Queue Tasks ........................................................................................................... 13

5.2.1.3.1 Application Queue View: MATCH Pending 202 COV Messages ......................................... 13 5.2.1.3.2 Application Queue View: MATCH 202 COV Matching Failed .............................................. 15

6 DISCLAIMER ................................................................................................................................. 17

Introduction to UETR 1

1 Introduction to UETR

The purpose of this document is to give an overview of the UETR implementation in and its implications on BOX. The following will give a brief overview over GPI and , at its heart, UETR. UETR as part of the SWIFT Global Payments Innovation initiative (GPI) stands for ‚Unique End-to-End Transaction Reference‘. The Global Payments Innovation has been initiated to enable a faster payment and in consequence a same day usage of funds; it enables transparency of fees and tracking of payments and a full unaltered remittance information. The core element of GPI is UETR, which is

a) the SWIFT cross border payments equivalent of a parcel tracking number

b) generated by the payer and passed through, without modification, the SWIFT network and any intermediary banks through to the payee (beneficiary)

c) used within the SWIFT GPI Tracker to enable banks and corporates to track and monitor in real time the end to end progress of all GPI payments

Please note, GPI/tracker/UETR is continuously evolving and changes will most likely occur with every SWIFT change. Due to this, the present documentation V3R22.3 reflects the current status of SWIFT release 2018.


2 Requirements for UETR

Starting with the SWIFT Standard MT Release 2018, it is required to set the UETR in the FIN user header (block 3) for the following MT messages (November 2018)

MT103

MT103 REMIT

MT103 STP

MT202

MT202 COV

MT205

MT205 COV

The User header block (block 3) must be present and must contain field 121 Unique End-to-End Transaction Reference (UETR). In cases where the sender is acting as intermediary and a UETR is present in the received message, the UETR must be passed on, unchanged, to the next message in the transaction chain. In all other cases, a new UETR must be used.

For MT 202 COV, when the underlying customer credit transfer is an MT 103, field 121 in the header block 3 of the MT 103 must be copied, unchanged, to field 121 in the header block 3 of the MT 202 COV.

2.1 Field 121

The UETR (Unique End to End Transaction Reference) must be:

a. unique

The UETR reflects a globally unique value independent of the respective organization adhering to the Universal Unique Identifier (UUID) or Globally Unique Identifier (GUID), which is compliant with IETF standard RFC4122, version 4 of the generation algorithm

b. assigned by the initiating party

c. indicated in field 121 within block 3 of the MT header

d. 36 characters – made up to 32 hexadecimal characters, shown in 5 parts divided by hyphens/dashes as follows:

o xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx

o Where:

▪ x is any lowercase hexadecimal character

▪ 4 – fixed value

▪ y – either: 8, 9, a, b

Sample message:

• without UETR

{1:F01YOURCODEZABC1234567890}{2:I103YOURBANKXJKLU3003}{3:{113:SEPA}{108:

ITESTSEPA}}{4:

• with UETR


ITESTSEPA}{121:xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx}}{4:


2.2 Field 111

Field 111 is to be placed in the header section block 3, and is to be used as indicated below by SWIFT GPI members only.

Current values are

• 001 – SWIFT GPI Customer Credit Transfer (gCCT)

• 001- SWIFT GPI Cover services (gCOV)

• 002 – will be used in future for the SWIFT GPI Stop and Recall (gSRP) service

• ??? – for future services

Sample Message:


ILOVESEPA}{111:001}{121:xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx}}{4:

Implementation in BOX 4

3 Implementation in BOX

Since BOX Version 3.20.3, the values of the tags 111 and 121 of the user header are extracted and written to FIN generic attribute field (TEXT63_9). The format of the data is <value_of_tag_121>. This generic attribute field can be

➢ displayed in SWIFT Generic Journals and Application Queues in column GPII Trans-Ref, accessed with the UETR keyword in Analysis1

➢ used as filter attribute in GRTA ➢ used in FIN duplicate check analysis ➢ used in the genflatbuf exchange plugin in an export template ➢ used in the genflatbuf embargo check plugin in an export template with the @UETR@

token In BOX Web Application message entry panels, a UETR is automatically generated for the MTs in which field 121 in user header is mandatory.

3.1 GPI [Tag 121 (UETR) in User Header] Handling in BOX

The following gives a description of the GPI handling in the message entry GUI (New Message/New Message From/New Message From Template/Modify Message.):


3.2 Backend Plugins

With BOX Messaging Hub 3.22.3, the UETR can be generated and is now inserted on reception by the expgi_genflatbuf, expgi_mervabridge, expgi_wbifnba and the expgi_saaba backend exchange plugins (if configured and not already set in the message). The Service Identifier, if applicable, can also be inserted.

The behavior can be configured in the PLUGIN config section with a new GPI config section,

i.e.[LCG<XXXX>.F002.GENFLATBUF_PLUGIN.GPI].

The following parameters can be set: GPI_UETR_MSG_LIST Optional, contains a comma separated list of MTs

for which the GPI UETR should be inserted. If not set the default for the actual SWIFT release is used. 103, 202, 205 for SR2018, empty list before. The items in the list can contain a '*' wildcard character at the end of the item for one or more characters.

MT202COV_UETR_MATCH_BIC_LIST Optional, this parameter contains a comma separated

list of sender BIC8s for which a matching MT103 is searched for a received MT202COV to set the GPI UETR in the MT202COV. Default is an empty list. The items in the list can contain a '*' wildcard character at the end of the item for one or more characters, If no matching MT103 was found, the GPI UETR will not be set and the message validation status will be set to INVALID, validation code will be set to U13 (this can be overwritten if the plugin performs a message validation subsequently) and the message will be send to the validation failure pattern.

SERVICE_ID_GENERATION_BIC_LIST

*, PTSADESA, PTSADESS, P*, Q*, R* Optional, this parameter contains a comma separated

list of sender BIC8s for which the service identifier 001 is inserted in tag 111 of block 3 of the received fin message (if service identifier is not already set). Default is an empty list The message type of the message must be found in GPI_UETR_MSG_LIST. The items in the list can contain a '*' wildcard character at the end of the item for one or more characters,

MT202COV_MATCH_INTERVAL Optional, this parameter sets the search interval for

matching MT103s for received MT202COV. Only MT103s with creation dates not older than specified with this parameter will be checked for matching.

Default=2 REMOVE_GPI_UETR Optional, If set to YES the GPI UETR (tag 121 in

block 3 of a FIN message) will be removed before the message is send to the backend application. Default = NO

REMOVE_GPI_SERVICE_IDENTIFIER Optional, This parameter defines if the service type (tag 111 in block 3) will be removed by the FIN CBT from the message before sending to SWIFT. If set to YES the service type will be removed for all message types listed in GPI_UETR_MSG_LIST. Default=NO

SDA_PROTREP_SW_GPI_TX_ID Aliases used within Analyses 1 to assess the GPITxIdentifier of the transmit report. ISDREP_PROTREP_SW_GPI_TX_ID

The mervabridge plugin returns the UETR (if available) of a message in the ACK/NAK report in the ComIbmDni/Dnf/FIN/UETR node. In the workflow, the GPI UETR (MT202COV) can be set to the UETR of the matching MT103 with the new GPI processing CPI (cpim_gpiproc). For this the Parameter ‘Data’ of the CPI must be set to MATCH202COV. The configuration of the GPI processing instance applies accordingly to the configuration of the GPI section in the


exchange plugins. This matching functionality in the backend plugins allows to search for and insert the UETR from the underlying MT103 for scenarios in which the MT202COV was created in BOX prior to the MT103. The matching criteria used by BOX are

a) the sender BIC11

b) the related reference, field 21 (which must correspond to transaction reference field 20 of the MT103).

The search range is restricted to the MT103 with creation dates not older than specified in parameter MT202COV_MATCH_INTERVAL and the same client prefix in the message owner data.

If no matching MT103 is found, the GPI UETR will not be inserted and the message validation status will be set to INVALID, validation code will be set to U13 (this can be overwritten if the plugin performs a message validation subsequently) and the message will be sent to the Instruction Pattern Sequence configured in parameter VALIDATION_FAILURE_PATTERN of the LCG (a pattern can be configured even if message validation is not switched on for the LCG).

Sample config section for an LCG (SR2018, with default of GPI_UETR_MSG_LIST):

[LCG<BACKEND42>.F002.GENFLATBUF_PLUGIN.GPI]

MT202COV_MATCH_INTERVAL 3

MT202COV_UETR_MATCH_BIC_LIST ZYSADES0,PTSADES*

SERVICE_ID_GENERATION_BIC_LIST PTSADESB

3.3 Transport of GPI fields to backend

3.3.1 Removing the UETR

If not configured otherwise, the FIN message is sent via backend application plugins unchanged and with all its user header fields.

In case the backend application is unable to handle the GPI fields, a parameter is provided for the backend plugins to remove the UETR from the FIN message.

To remove the UETR in the FIN message, before it is sent to the backend application, add the parameter REMOVE_GPI_UETR to the respective plugin section, as follows

[LCGXXX.F002.XXX_PLUGIN]

REMOVE_GPI_UETR YES

3.3.2 Mervabrige Plugin

The mervabridge plugin returns the UETR (if available) of a message in the ACK/NAK report in the ComIbmDni/Dnf/FIN/UETR node.

3.3.3 Generic Flat Buffer Plugin

The content of generic attribute field TEXT63_9 that contains <value_of_tag_121> can be used in export templates with token @FIN_UETR@

3.3.4 Generic Flat Buffer Embargo Check Plugin

In the generic flat buffer embargo check plugin a new template token for access of the UETR from the FIN generic attributes has been added, FIN_UETR.


3.3.5 Generic Attributes of Referenced Original Message Processing Sequence (MPS)

To access the UETR from the FIN generic attributes of the referenced original MPS, a new template token s provided: FIN_REFORIG_UETR

GUI: Inserting UETR (and Service Identifier) in FIN Messages 8

4 GUI: Inserting UETR (and Service Identifier) in FIN Messages

4.1 Fields 111 and 121

The BOX Web Application automatically generates the UETR in the message entry panels of all MTs, for which the UETR is mandatory.

It also offers the option to generate a UETR for all category 1 and 2 MTs in form of a button ‘Generate UUID’.

Field 111 Service type identifier (which is reserved for GPI customers) can be entered manually in the message entry panels.

4.2 MT202COV UETR

The message entry panels for MT202COV offer a button ‘'Look For Original EToE Trans. Ref.’, which can be used to search for the underlying MT103 and insert the UETR if found.

Workflow 9

5 Workflow

5.1 Introducing Content Processing Instruction (CPI) cpim_gpiproc

To introduce GPI to BOX and to set the GPI UETR in a MT202COV to the UETR of the matching MT103, a new Content Processing Instance (CPI) has been introduced to bind the GPI processing into the BOX’s workflow. As with all configuration changes, the setup of the CPI will have to be done in a change set. The following graph shows the CPI location, using ‘add’ a new instance can be created.

A list of message types can be chosen to create a selective list, for which a GPI UETR should be inserted. In case of a wildcard ‘*’, all applicable messages are selected.

Workflow 10

5.1.1 Match Search Interval

The value of Match Search Interval reflects the CreationDate interval used in case of search of matching MT103 for MT202COV in days. Only MT103 not older than the given number of days will be checked.

5.1.2 Match BIC8 List

Here, a list of comma-separated BIC8s is maintained, for which a matching MT103 will be searched for MT202COV messages to insert the UETR from the MT103 into the MT202COV. The list items can also contain a wildcard ‘*’ character at the end, like AAABITMM,PTSA*

5.1.3 Match Found Label

The value for this parameter must be the continue pattern label if matching MT103 for MT202COV was found.

5.1.4 Match Not Found Label

The value for this parameter must be the continue pattern label if no matching MT103 for MT202COV was found

5.1.5 Parameter Data in CPI using a FIN GPI Processing Instance

In Extended Control of the CPI, the Processing Method must be set to ‘FIN GPI Processing’.

Field Parameter Data must contain ‘MATCH202COV’

5.1.6 Working Theory of cpim_gpiproc

Reception of MT202COV without UETR prior to the underlying MT103

The MT202COV could not be enriched with the MT103’s UETR. Consequently, the backend gateway sets the message validation status to INVALID and the validation code U13 if the message is valid in all other aspects.

The workflow for such a message starts with the validation failure pattern configured in parameter VALIDATION_FAILURE_PATTERN of the LCG.

If the IPS configured in VALIDATION_FAILURE_PATTERN contains an SBI that identifies

MT202COV without UETR, the workflow can continue with a specific workflow to handle those

MPSs.

When identified by the SBI, the respective MT202COV can be ‘halted’ in an application queue,

that is either manually operated or regularly restarted. The start of the application queue triggers a GPI processing CPI now trying to find a matching MT103. The workflow continues with the IPS

Workflow 11

configured in the FIN GPI Processing Instance Label. If unsuccessful, the MPS is tagged back to the application queue, if successful, the workflow continues.

5.2 Detailed Workflow Setup and Configuration (Example)

The workflow part dealing with the UETR check, identification and matching process is divided in the following parts, of which the configuration will be explained in detail in the following chapters.

5.2.1 Sample Workflow Elements

Assumed are

Analysis1 module

FIN_IC_0045_SWI_SBI_01_LoopCheck

GPI Content Processing Instance

COV202 Matching

Instruction Pattern Sequences

FIN_IC_0045_SWI_UETR_Handling

FIN_IC_0046_SWI_UETR_NextLoop

FIN_IC_0047_SWI_UETR_Parking

Application Queue Definitions/FIN Generic Journal Instances

FIN202COVMatchingPending

FIN202COVMatchingFailed

Sample statement to identify MT202COV without UETR:

Variables

MessageType = mpsga(63_1);

UH119 = mpsga(63_8);

VALIRESULT = mpsga(63_31);

UETR = mpsga(63_9);

UETR = mpsga(UETR); (also possible variable)

Statement

if ((MessageType == "202") AND (UH119 == "COV") AND

(VALIRESULT=="U13"))

{

setips FIN_IC_0045_SWI_UETR_Handling;

print ("Sender = " + Sender + "OwnerInfo = " +

OwnerInfo);

return;

}

else setips ToValidationFailure

return;

Workflow 12

5.2.1.1 Schema of GTI Workflow MATCHCOV202

Workflow 13

5.2.1.2 CPI: COV 202 Matching Configuration

5.2.1.3 Application Queue Tasks

5.2.1.3.1 Application Queue View: MATCH Pending 202 COV Messages

Workflow 14

Workflow 15

5.2.1.3.2 Application Queue View: MATCH 202 COV Matching Failed

Workflow 16

Disclaimer 17

6 Disclaimer

INTERCOPE International Communication Products Engineering GmbH (Intercope) and the stylized logo is the registered trademark of Intercope and its subsidiaries, in Germany and certain other countries. All other trademarks mentioned in this document are the acknowledged property of their respective owners. Intercope provides this publication "as is" without warranty of any kind, either express or implied, including, but not limited to, the implied warranties of non-infringement, merchantability or fitness for a particular purpose. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. Intercope may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. This information may contain sample application programs in source language, which illustrate programming and implementation techniques. You may copy, modify, and distribute these samples programs in any form without payment to Intercope, for the purposes of developing, using, marketing or distributing application programs for which the sample programs are written. These examples have not been thoroughly tested under all conditions. Intercope, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. Intercope shall not be liable for any damages arising out of use of the sample programs. Intercope grants the right to reproduce, distribute and display these publications solely within your enterprise provided that all proprietary notices are preserved. Intercope does not allow derivative works of these publications, or to reproduce, distribute or display these publications or any portion thereof outside your enterprise, without the express consent of Intercope. Without written permission of Intercope no part of this publication may be modified and/or reproduced in any way.

INTERCOPE GmbH Himmelstrasse 12-16, 22299 Hamburg, Germany +49 40 514 52 0 [email protected] https://www.intercope.com Copyright © 2019 INTERCOPE International Communication Products Engineering GmbH. All Rights Reserved.

http://www.intercope.com/

version 3 release 23 (v3r23) uetr and its implementation · 2020. 3. 17. · instruction pattern...

Documents