AAAdvancedCustomisationPart3 PDF
AAAdvancedCustomisationPart3 PDF
As a first step of this last chapter of the AA Advanced Customisation course, let
us try to jog our memory and review some core concepts regarding the Open
Financial Services module and how it is used. Later we will see how AA
transactions are dealt with by OFS.
Online processing
• TELNET mode – for processing messages online from third-party
systems (e.g. messages posted by a SWIFT interface)
• SESSION mode – for processing messages online from Temenos
interfaces (e.g. Browser or ARC-IB interfaces)
Let us now review briefly the message syntax for an OFS transaction. This is
composed of 5 parts separated by commas.
Operation
The ‘Operation’ part of the message contains the name of the application
that we are going to use to post our transaction. Eg: ACCOUNT.
Options
As its name imply, the ‘Options’ part of the message is optional since
many of the parameters here may be defaulted. This contains many sub-
parts, separated from one another through a forward slash sign. The sub-
parts are Version name/Function/Process type/ GTS.Control
value/No.of.authorisers. E.g. TRG/I/VALIDATE//2
Version name – this must a valid version suffix (e.g. if the version name is
ACCOUNT,TRG then the value contained by this parameter will be just
TRG). As comma versions don’t have any suffix, they cannot be used
here.
Function – a T24 function such as I, R, A,H,V. Note that C and P is not
supported.
Process Type – this may be VALIDATE or PROCESS and controls
whether the transaction is to be validated (i.e. checked for error) or
User Information
This consists of the Sign On Name, Password and Company code of the user
whose SMS credential are going to be used in the transaction
E.g INPUTT/123456/GB0010001
Transaction ID
The ‘Transaction Id’ part of the message contains the key of the record used
within the transaction. This is optional for new transactions if the underlying
application is configured for Automatic ID Generation.
The transaction ID parameter is, instead, mandatory for See , Authorize, Delete,
Reverse, History-Restore and Validate functions or when we are trying to edit a
specific record. The transaction ID can also contain an optional Message ID for
the message.
For eg 20548/20081010001 .
In this case the 20548 is the record id and 20081010001 is the message id. This
message id, which is an optional information, could be used by external systems
to uniquely identify each OFS message.
Message Data
The message data portion of the message structure contains the data
required to create or update the transaction. Message portion follows the
format
Fieldname=data
Eg CUSTOMER=100297
When you need to assign values to multi values or sub values , you may
follow the format
Fieldname :multi value number : sub value number = data
Eg CUSTOMER:1:1=100297
This implies the first sub value belonging to the first multi value of the field
CUSTOMER is assigned a value of 100297. The first multi value or sub value is
taken as the default in the absence of positions If ‘NULL’ is specified as field data,
OFS will blank the field of all data.
The message data portion of the message can be repeated for each field
separated by a comma (,).
The first one is a sample request to input an account record. This has not used a
version. The mandatory field values have been specified.
The second request is one to authorise the record previously input. This does not
contain values in the data portion. PROCESS has not been specified either since
that is the default process type.
The diagram on this slide shows the syntax of this type of messages.
As you probably remember, the structure is very much similar to a Transaction
Request. The options part has been omitted, since it is not relevant to an enquiry.
However commas are given to indicate the placeholder, and retain the general
structure of an OFS message.
ENQUIRY.SELECT
The first portion of an enquiry request must always be
ENQUIRY.SELECT. This is the name of the routine that is used to run
queries and return the data, abbreviated as ENQ when you are invoking it
in CUI or GUI Interfaces.
User information
The user information portion of the message structure is the same as that
of the transaction type request.
Enquiry Name
You will specify here the @ID of the T24 ENQUIRY record which should be
executed. (i.e. the enquiry name placed in this OFS message part must be found
under the ENQUIRY application of T24).
Message data
The message data portion, finally, contains
• The message data portion of the enquiry message structure contains the
selection criteria passed to the enquiry.
• The message data portion of the message can be repeated for each selection
criteria separated by a comma (,).
• This is optional depending on the Enquiry
The three different parts of a Selection Criteria part of the MESSAGE DATA are:
• Selection Field – denotes the name of the field of that must be either a field
in the STANDARD.SELECTION for the file on which the enquiry is based
(ie- the application that is specified in FILE.NAME field of the ENQUIRY
application )or a value set in SELECTION.FLDS field of the ENQUIRY
application.
• Operand – denotes the operand that must be used for selection for the value
specified in the SELECTION.FLDS field of the ENQUIRY application. The
operands can be EQ, NE, GE, GT, LE, LT, UL, LK and NR. The operand
must be separated from the selection fields using a colon (:).
• Field Value – denotes the data value for the values specified in the
SELECTION.FLDS (field of the ENQUIRY application) and the operand for
selection. This must be separated from the operand using a equal sign (=).
E.g. ACCOUNT.NUMBER:EQ=11107
ENQUIRY.SELECT,,INPUTT/654321,%ACCOUNT
ENQUIRY.SELECT,,INPUTT/654321,%ACCOUNT,
CURRENCY:EQ=USD,CATEGORY:EQ=1000
In the coming slides, we are going to see how OFS can support multiple updates
on all kind of applications above with just one transaction.
Please note that the OFS message syntax has not changed at all to support the
creation and updates of contracts in the Arrangement Architecture module
1. Operation
As you are aware of, the section contains the name of the application that
needs to be updated. For AA, this will always store the value
AA.ARRANGEMENT.ACTIVITY, i.e. the application used to define
which activities are performed on an arrangement. In AA, every action
you take on an arrangement is an activity. When you create a new
arrangement, you are performing an activity called LENDING-NEW-
ARRAMGEMENT. When you wish to decrease the term of the
arrangement or the amount of the arrangement, then the activity is
LENDING-DECREASE-TERM.AMOUNT.
2. Options
The structure of this section stays the same. It contains the suffix of the
AA.ARRANGEMENT.ACTIVITY version to be used if any, the
function to be used and the value ‘VALIDATE’ or ‘PROCESS’ to
denote whether the transaction just needs to be validated or committed
etc. Example : TRG/I/VALIDATE
3. User Information
No change. This part of the message contains, like for all other kind of
transaction, Sign On Name/Password/Company Code of the user whose
SMS credentials are going to be checked when the OFS message is posted
to T24.
4. Transaction ID
No change here, either. As usual, it holds the Transaction ID and, in case,
the unique Message ID
5. Message Data
The ‘Message Data part contains the data required to create or update the
transaction action. As for non-AA transactions, the existing format for
message data is FIELD.NAME:Multi Value Position:Sub Value
Position:=VALUE. As you are already aware, the name of the application
that you need to specify in the OFS message is always
AA.ARRANGEMENT.ACTIVITY – therefore the OFS message should
contain values for the record in AA.ARRANGEMENT.ACTIVITY. Take
a look at the fields in AA.ARRANGEMENT.ACTIVITY. These fields’
values need to be supplied in the OFS message – e.g.
ARRANGEMENT=NEW, ACTIVITY=LENDING-NEW-
ARRANGEMENT,EFFECTIVE.DATE=20120620,CUSTOMER=100301
,PRODUCT=NEGOTIABLE.LOAN,CURRENCY=USD.
You may have noticed that the value ‘NEW’ to which we initialise the
field ARRANGEMENT is later transformed into a standard
AA.ARRANGEMENT ID, i.e. AA120307GNCY and also that, so far, we
have not specified the content of any of the product’s properties. We will
explain these two point and see an example of a complete OFS request
in the next slides.
Let us try to sum up what we have learnt so far about AA Transactions in OFS
with an example. The request displayed in this slide shows the 5 blocks forming
an AA transaction request (even if the Data Message part is still incomplete, as
we will see)
3. OFS message
We have to specify PROPERTY, FIELD.NAME and FIELD.VALUE in the OFS
message because these fields belong to the
AA.ARRANGEMENT.ACTIVITY application. These fields are used by
AA.ARRANGEMENT.ACTIVITY to import the supplied property values
into the respective properties for that arrangement. This is because it is not
possible to send an OFS request directed towards a specific property that is
part of the arrangement.
If you take a look at the entire OFS message to create a new arrangement in AA
via OFS. As you can see, the values for the various properties which in-turn
update values in AA.ARR.XXX applications are supplied using the amended
OFS syntax. If you have multiple properties for which values need to be
supplied, then you may do so, by supplying values as specified here
PROPERTY:1:1=COMMITMENT,FIELD.NAME:1:1=AMOUNT:1:1,FIELD.VA
LUE:2:1=8000,FIELD.NAME:1:2=TERM:1:1,FIELD.VALUE:1:2=Y1,
PROPERTY:2:1=SETTLEMENT,FIELD.NAME:2:1=PAYIN.ACCOUNT:1:1,FI
ELD.VALUE:2:1=6077
above. It only contains values for the properties COMMITMENT and SETTLEMENT
that belong, respectively, to the property class TERM.AMOUNT and to the property
class SETTLEMENT. This means that the values for all other the properties
associated with the NEGOTIABLE.LOAN product have been defaulted from
product conditions or version’s settings.
We can choose to test our OFS message through a direct TELNET connection,
which is currently an obsolete way of using the TELNET mode but it is quite
handy for testing purposes (normally we would connect to T24 in TELNET mode
through a listener e.g. TCServer).
In order to do so, we access the jshell prompt and start a tSS (T24 Server Session)
using the ID of an OFS.SOURCE record of type TELNET to feed the correct
connection parameters to the session.
Once the session is started, we can supply our OFS request and then press enter to
post it.
Look at the highlighted section in the output. It is the new AA.ARRANGEMENT
id that has been generated. Please note that only partial output of the OFS
message is displayed .
Like all other kind of OFS messages, AA transactions can be posted to T24
through all the 4 modes of OFS – namely TELNET, SESSION, GLOBUS and
BATCH. We have seen an example of a message posted in the TELNET mode, in
the previous slide. We know that OFS works through SESSION, as well, because
of all the previous OFS requests we have posted through the Browser Interface
during this training course. We can now have a look to how OFS messages for
AA are posted in the GLOBUS, mode instead.
As you will certainly remember from the OFS course, there are two APIs which
can be embedded in T24 subroutines to post OFS messages –
The routine shown in the previous slide has to be written, compiled and set up in
PGM.FILE as a type ‘M’ record. As soon as we run the routine from T24, the
OFS message contained in it is written to F.OFS.MESSAGE.QUEUE
Please note that note that, even if a mainline routine is used here, ANY kind of
T24 routines may embed OFS messages – so we could have used a TYPE ‘S’ or
‘B’ routine or maybe even an EB.API routine used for Versions (e.g.
Authorisation routines etc).
For further information regarding Inter Application calls with GLOBUS mode,
please refer to the Oper Financial Services training course.
The last mode through which we can post messages to T24 is BATCH. Like for
TELNET, OFS requests can use BATCH directly or through listeners like
TCServer. In this case, we will show an example of a direct BATCH connection.
As we know, in order to work we the BATCH mode, we need to define an
OFS.SOURCE record with SOURCE.TYPE field set to BATCH and mentioning
the IN.QUEUE and OUT.QUEUE directories from which the appropriate
phantom (linked to the OFS.SOURCE record) will pick up requests and write
responses, respectively. It is crucial that the processing phantom is linked to the
correct OFS.SOURCE for it to know from which queue OFS requests have to be
read and also the field RUN.ROUTINE in this EB.PHANTOM record should
always be set to OFS.QUEUE.MANAGER as this is the routine which initiates
OFS processing in BATCH mode. As we know, the BATCH processing will be
started as soon as this EB.PHANTOM record is verified.
Let us now introduce the concept and use of a T24 API called
OFS.BULK.MANAGER. Please note that OFS.BULK.MANAGER is not a
published T24 API. It is internally used by the OFS framework in T24. To start
with, we need to understand the flow of a standard message in OFS and then see
what changes if the message processed is an AA transaction.
Let us take the example of a transaction to set up a new account issued through
the Browser interface of T24.
1. tSS (which stands for T24 Server Session) is a process spawned by a T24
server listener (e.g. TCServer) and it enables this component to send requests to
the OFS framework. This was originally called
OFS.CONNECTION.MANAGER and then rechristened to tSS to comply with
the standard name structure for T24 process names (similarly to tSM and tSA). To
sum up, tSS is an interface between a T24 server listener and OFS. The OFS
message is posted to T24 via tSS anytime it relies on a listener – in case we have,
instead, a message posted to T24 in BATCH mode though an IN QUEUE, the
routine that picks up OFS strings from the queue is called
OFS.QUEUE.MANAGER. For GLOBUS mode, as we have seen, this task is
performed by the OFS.MESSAGE.SERVICE service.
2. When tSS receives a request, this process passes it to the
OFS.PROCESS.MANAGER routine which checks whether the incoming request
is a delivery request or not (in case it is, the application name in the OFS message
will be ‘DE.CARRIER’). If the request isn’t a delivery request, then
The above screen shot shows how messages used to be processed when
OFS.BULK.MANAGER was not used for transaction processing.
1. Imagine a situation where in an input on an account record is committed using
T24 Browser. The request to commit the record passes through the Application
Server (where e.g. Jboss is installed and the Servlet component is deployed), then
is received by the listener on the T24 Application server (e.g. TCServer) and then
it reaches tSS .
2. Assume that this is the OFS message that reaches tSS (Note that requests from
Browser rely on BROWSERXML syntax but to ease the process of learning,
message in OFS syntax has been used here). tSS would have invoked
OFS.PROCESS.MANAGER, OFS.SESSION.MANAGER and finally
OFS.REQUEST.MANAGER.
3. Once the Request Manager routines kicks in, the actual application in charge of
updating the appropriate Database Table with the new record is invoked
(ACCOUNT in this case). The logic within the ACCOUNT application will
a. Validate data
b. Make ready the record to be written into the appropriate
ACCOUNT data file (Live or Unauthorised, depending on the number of
authorisers)
c. Make ready the record(s) to be written to other concat files, live
files, other application’s data files (E.g. CUSTOMER.ACCOUNT)
Once the data is all set to be written, the ACCOUNT application (or any
application in T24 for that matter), branches off to the transaction processing
framework.
The term “transaction processing framework” here refers to a set of internal calls made by
the main application to the UNAUTH.RECORD.WRITE API (which is called when a
record is committed) and to the AUTH.RECORD.WRITE API (which is called when a
record is authorised). These T24 APIs internally call another one named
JOURNAL.UPDATE.
JOURNAL.UPDATE is the T24 API that takes care of transaction management in T24. It
internally invokes the EB.TRANS API with the first parameter set to START in order to
mark the beginning of a transaction block, i. e. a set of transactions which are either all
executed successfully after being written to cash or which are all rolled back in case even
only one of them fails. While a transaction block in open, all records that need to be
written to disk are written to cache and then a check is performed to see if the writes have
been successful. If yes, EB.TRANS (END,’’) is called to denote the end of a transaction
block. At this point, all data is flushed from memory to disk. If not successful, EB.TRANS
with ABORT set as first parameter is called to abort the whole block of transactions. At
this point in time, all records that were written to cache memory are flushed out of it.
The crucial thing that you need to note here is that, though multiple files and applications
get updated, the OFS request that came in is just ONE. Where as for arrangements in AA,
this will not be the case. Let us discuss this in detail as we proceed.
(Note that there are other activities listed in the record which will also be triggered but
only some of them will result in an actual table update as not all the mentioned
property classes may be mandatory in a product)
end its own transaction block . What this evaluates to is, the first message might be
successfully processed and hence committed to the database, but if there is an error in
the second message, the second message alone will fail and will proceed with the next
one. At the end, there will be a situation where in some of the messages would have
got processed while some would not have. Is that OK? When you input an
arrangement, you want all related applications to be updated or none to be updated. If
this is what you want then OFS.BULK.MANAGER controlling transaction
management is correct.
1. What you see on the bottom part of this slide, is a screenshot representing a
part of an AA.PROCESS.DETAILS record which got created when a new
arrangement was input. You have seen such records before. But, if take a look
at the highlighted section, you will notice that the for the application
AA.ARR.ACTIVITY.MESSAGING (used in the ,AA.NONINPUT version)
the function used is ‘M’. What does this M signify?
2. To understand this, take a look at the AA.ACTIVITY.CLASS record of
LENDING-NEW-ARRANGEMENT
If you look at the ACTIVITY.MESSAGING property classes specified in
LENDING-NEW-ARRANGEMENT, it has the field User Input set to NO for
the SEND.MESSAGE action. So far, we had only seen examples of Activities
applied to Property Classes for which the USER.INPUT field was set to YES
(see slide 155).
As the name suggests, the field ‘User Input’ specifies whether an action on a
given property’s arrangement condition can be performed manually by a user
or not. When USER.INPUT is set to NO, it denotes that user manual update is
not permitted. Any activity for which ‘User Input’ is set to ‘NO’, when an
OFS message is formed, ‘M’ is the function that will be used as part of the
OFS message. Unlike I or A or D or any other T24 function that you are
already aware of, M works differently. When function is ‘M’, the underlying
application’s call to UNAUTH.RECORD.WRITE/AUTH.RECORD.WRITE
will not be triggered’. More details on this as you proceed.
When we commit or authorize a record in any application in T24, the route that it
follows is what is depicted diagrammatically. First, the THE.TEMPLATE routine
is called followed by the .INITILIASE to perform any application specific
initialization. Once done, the fields and their properties are read and the fields are
built and are ready to be displayed. First, the ID is accepted, validated and if the
key validation is successful, the corresponding record is fetched from the disk or
a new record is created as the case may be (RECORD.READ). Once the record
has been read and after the user has filled in the appropriate fields, the record data
is validated and overrides are, in case, generated. Once all validations are
successful and all override messages are accepted or corrected, the data control
passes to the T24’s transaction processing framework. The
UNAUTH.RECORD.WRITE API or the AUTH.RECORD.WRITE API are
called to write into unauthorized or to live files respectively (concat files and
connected live files are also updated if it is so coded in the application). If
function is I only UNAUTH.RECORD.WRITE will be called and if function is A
only AUTH.RECORD.WRITE will be called. This will not be the case for a 0
authorizer version. In this case, both will be called.
When function used is M, an application takes the normal route, but once the
record is read and stored in memory, it restrains from performing any validation
on the record and therefore does not call the T24’s transaction processing
framework. The control passes to the action routine.
Understand this with an example. In the LENDING-NEW-ARRANGEMENT
activity class, the property class ACTIVITY.MESSAGING was specified with
action SEND.MESSAGE and with the USER.INPUT field set to NO (see slide
160). When ever M function is used, it denotes that data in that particular
application will not be altered manually. In this case, data in
AA.ARR.ACTIVITY.MESSAGING is not going to be altered manually. The data
in it is just read and used. Since there is no data alteration, the sections in light
yellow in the slide above are not invoked. After the current record is read, the
application control skips the routines in light yellow and moves directly to the
action routine.
Let us now analyse the structure of an OFS request aimed to simulate an activity.
The example shown in this slide is the simulation of a new lending arrangement
creation (the product used is NEGOTABLE.LOAN). The same structure,
however, applies to any simulated activity.
The structure of this kind of OFS message is very similar to the structure of an
OFS message aimed to create a new activity in AA, with a few significant
changes.
1. The first important difference is that, of course, the application name used in
the Operation part of the message is always AA.SIMULATION.CAPTURE
for simulated activities, instead of AA.ARRANGEMENT.ACTIVITY
2. Options are supplied or (in this case) left blank and defaulted in the usual
way.
3. The User Information’s credentials are supplied as in any OFS message
4. Transaction Id, in this example, is not supplied as also
AA.SIMULATION.CAPTURE supports Auto ID generation – so T24 will
automatically assign an Id to our new simulated activity
5. Data Message part:
a. Since this is a new activity to create a new record in
AA.ARRANGEMENT, we assign to the field ARRANGEMENT the
value ‘NEW’. T24 will automatically create a new
AA.ARRANGEMENT ID.If we were in a scenario where a simulated
activity has to be performed on an existing arrangement (for instance,
disbursing the amount of a loan we have already created), we would
From the response we get (partially shown in the screenshot on the top of this
slide), we can see that our transaction request has been successfully processed, as
the Success / Fail indicator is set to 1.
Now we will authorise the previous request to analise the response we get.
We are now about to discuss some important APIs which can be used within OFS
messages to build AA transaction requests.
AA.GET.ARRANGEMENT.CONDITIONS
This routine can be used by any application to retrieve the product conditions that
apply to an arrangement for a particular effective date (default value is TODAY)
The records and ids for the property conditions that apply are returned
AA.GET.PUBLISHED.RECORD
This routine will analyse the published property / product structure and return the
published record detail. It is intended to be used only from the Arrangement level
AA.GET.ACTIVITY.CLASS
This simple routine returns the activity class to which the activity belongs
AA.GET.ARRANGEMENT.PRODUCT
This routine returns the product that the arrangement is running on and the
properties linked to it
What is the name of the Property Class which allows advices to be linked to AA
products?
ACTIVITY.MESSAGING.
Yes, individual advices can be suppressed on the arrangement record by setting the
SEND.ADVICE field to ‘NO’ within the ‘Messaging’ property.
Which application name do we use in the ‘Operation’ part of an OFS message when we
want to request a new arrangement creation?
AA.ARRANGEMENT.ACTIVITY