5/31/2021 External Service Implementation Guide

You are here: Home > Front Office - PM > Front Office > External Service Implementa on Guide

[Link] Service [Link]#_Toc47321229%3FTocPath%3DHome%7CF… 1/13

5/31/2021 External Service Implementation Guide

External Service Implementa on Guide

[Link] Service [Link]#_Toc47321229%3FTocPath%3DHome%7CF… 2/13

5/31/2021 External Service Implementation Guide

Introduc on
This product guide aims to describe the different ways to use an external service, to call an external service, to implement an external service in WealthSuite Front
Office - Por olio Management (PM) as well as the rules to respect at the performance and security levels.

Terminology

Term Explanation

External An external service lets you integrate the data, rules, etc in Front
service Office - PM that are calculated, stored, and processed outside Front
Office - PM.

External An External Service Profile links a financial function to external

Service Profile services.

External By scripting, an external service can be called.

service called
by scripting

Audience
This product guide is intended for Super Users and Implementa on Consultants.

[Link] Service [Link]#_Toc47321229%3FTocPath%3DHome%7CF… 3/13

5/31/2021 External Service Implementation Guide

Managing external services

To establish a dialogue between Front Office - PM and an external service, a request is built based on Front Office - PM en es, and the external service response is
retrieved in logical en es.

External service defini on

The external service defini on represents the way to access the external service.

The business key is the code and the nature.

The URL contains the address to call a service adapter for the external service (http/https).
The method is always a POST with an application/JSON content considered as private protocol as its backward compatibility is not
guaranteed, which is why a service adapter has to be used. For more information, refer to the WealthSuite Front Office - Portfolio Management
Web - ServiceAdapter Customisation Guide.
The Time-out represents the time in seconds before considering the response as an error when there is no answer.
Proxy field contains the host and port of the proxy server. Each external service can use a dedicated proxy. Format:
proxyhost:port. Additionally, it is also possible to provide the credentials of the proxy server. Format:
proxyhost:port:username:password

External service composi on

The following sec ons describe the composi on of the external service:

Request definition
Response definition

Request defini on
The data sent while calling an external service, also named "Request", is built with exis ng data. In the external service composi on, rows with "Out (TAP->Ext)"
direc on compose the request.

At least one row composes the request, but if several rows compose the request, then the rank defines the order in which the rows must be taken into account for
the composi on.

The source entity is an entity from where data to build the request is drawn (e.g., extended_pos). The source entity is always mandatory.
The target entity is a logical entity that holds needed information for the external service. The target entity is optional. When there is no target
entity, the source entity is directly used to compose the request. If a target entity is specified, a screen based on the target entity lets you
define with a default value the way to build each attribute (i.e., from which attribute of, for example, extended_pos).

INIT("extended_pos").instr_id.code

A filter lets you reduce the number of rows from the source entity used by selecting, for example, only positions on stocks. The filter can also
be based on other entities, like domain for example, to call an external service only if the domain is on a single portfolio.

Response defini on
The data received a er calling an external service, also named "Response", is built by the external service. In the external service composi on, rows with "In (Ext-
>TAP)" direc on compose the response. The composi on of the response can be simple (e.g., only one row on one en ty) or complex (e.g., several rows on several
en es) with or without link to each other. As for the request, the rank defines the order in which the rows must be taken into account for the composi on.

The source entity is an entity generated by the external service. The source entity is always mandatory.
The target entity is also a logical entity. The target entity is optional. In some cases the source entity cannot be used directly; some information
needs to be retrieved or computed. When there is no target entity, the source entity is enabled (see section Available entities in hierarchy).
When it is target entity only, this one is enabled. If a target entity is specified, a screen based on the target entity lets you define with a default
value the way to build each attribute.
A filter lets you reduce the number of rows from the source entity used by selecting only useful items. Then, only filtered data is available (see
section Available entities in hierarchy).

Involved en es
There are no restric ons for the source en es usable on the request part. Only exis ng en es in hierarchy (memory of the func on), before calling the external
service, are available.

Examples:

In the Valuation function, main available entities are:

extended_pos
portfolio
instrument
In the Ordering function for buying a security, available entity is only:
buy_operation

Logical en es
To establish a dialogue between Front Office - PM and an external service, common en es are necessary. Most of the me, these en es are used only temporarily,
and the resulted data should not persist therefore, logical en es are relevant.

[Link] Service [Link]#_Toc47321229%3FTocPath%3DHome%7CF… 4/13

5/31/2021 External Service Implementation Guide

Available en es in hierarchy
A er calling the external service, a part of the involved en es is available for use.

En es from the request part are always available. This is not the case for en es of the response part; intermediate en es are removed from the hierarchy
(memory) and only final en es are kept therefore, available for use. An intermediate en ty means that in the composi on, the source en ty is linked to a target
en ty.

[Link] Service [Link]#_Toc47321229%3FTocPath%3DHome%7CF… 5/13

5/31/2021 External Service Implementation Guide

Calling external services

An external service is callable in the following ways:

Integrated in the heart of a financial function. For some functions, the compliance function contains this hardcoded call that involves the Risk
and Lombard compliance. The View Portfolio Objectives function, however, contains this hardcoded call that involves the Risk. For more
information about Risk and Lombard integration, refer to the WealthSuite Front Office – Portfolio Management – Compliance Reference Guide.
Linked to a financial function
Scripting with specific keywords

Linked to a financial func on

The External Service Profile aims to link external services to a financial func on. For more informa on about the External Service Profile defini on, refer to the
WealthSuite Front Office – Por olio Management Web – User Guide.

The external service is called at the end of the financial func on, before the formats construc on, which gives the ability to build formats based on en es
populated by the external service or to add elements built on en es populated by the external service.

Example: Add a risk external service on Valua on func on:

A specific format based on a logical entity, generated by an external service, displays the risk at portfolio level.
A format based on extended_pos displays, in a specific element, the risk at the position level. In this case, the risk data is retrieved by script
keywords such as GET_BEST_OBJECT or GET_OBJECT_ARRAY.

Scrip ng with specific keywords

An external service is callable with the following script keywords:

GET_EXTERNAL_RECORD
GET_EXTERNAL_ARRAY

For more informa on about these script keywords, refer to the WealthSuite Front Office - Por olio Management - Script Language Reference Guide.

Implementa on of an external service call is allowed in:

Default value and filter and input control on entities (screen and user levels)
Format*
Filter on case rule
Valuation rule
Trading constraint

*If an external service is called by scrip ng on a format, then this external service should be called for each row of the format. By using the profiling, the external
service is called only once. Depending on the context, it is preferable to use the profiling.

[Link] Service [Link]#_Toc47321229%3FTocPath%3DHome%7CF… 6/13

5/31/2021 External Service Implementation Guide

Deployment using external services

The following image shows the logical deployment of Front Office – PM using external services:

The external service mechanism uses a synchronous paradigm and has no transac onal guarantee. It must be used with care as it has performance impacts. Using
the integra on framework must always be considered before se ng up a new external service as local access to data is always faster.

Currently, using external services exploited from the GUI is possible but can lead to new connec ons with the service adapter if used with scrip ng on, but not
limited to, default values, input control, filter, constrained list, and valua on rule. This is not the case for financial func ons as these connec ons are from the
financial server. Check with the IT department if such new connec ons are more suitable.

Performance regarding data enrichment in financial func ons must be carefully designed as to not calling the external service for each row.

Using profiling, external services can be called only once before format processing and then used in memory for each format. An example is provided in sec on
Calling external service by profiling in Valua on func on.

[Link] Service [Link]#_Toc47321229%3FTocPath%3DHome%7CF… 7/13

5/31/2021 External Service Implementation Guide

Security
The connec on between the financial server/GUI and the service adapter should be defined using h ps. The service adapter can limit this connec on to limit the
access.

When the external service needs to react based on the connected user, the code of the connected user (or other iden fier represen ng the user) must be part of the
request defini on, and it is the responsibility of the service adapter to authen cate with the external service using this informa on or to provide it.

[Link] Service [Link]#_Toc47321229%3FTocPath%3DHome%7CF… 8/13

5/31/2021 External Service Implementation Guide

Known limita ons

Currently, there is no provision for HTTPS proxies in QT, that is, it does not support secure connec ons to proxy servers. Hence, proxy servers defined in external
service cannot use a secure connec on.

[Link] Service [Link]#_Toc47321229%3FTocPath%3DHome%7CF… 9/13

5/31/2021 External Service Implementation Guide

Examples of implementa on
The following sec ons provide examples of external service implementa ons:

Retrieving last quote from external service for instruments

Creating orders from instrument list proposed by external service
Checking an order session

Retrieving last quote from external service for instruments

In this example, while crea ng an order on a quoted instrument, the last quote is retrieved from an external service.

Proposed default value in an order screen on a ribute quote_n:

IF ( instr_id.calc_rule_e = 1 {Quoted},

GET_EXTERNAL_RECORD(GET_ENTITY("ude_price_response"),"EXT_INSTR_MKT_PRICE" ).last_quote_n

, DEFAULT() )
External service defini on
External service is EXT_INSTR_MKT_PRICE.
Composi on of the external service
Screen (based on target
Rank Direction Source entity Target Entity Filter
entity)

1 Out TAP buy_operation ude_price_request UDE_INSTR_PRICE_BUY No

à Ext) filter

2 Out (TAP sell_operation ude_price_request UDE_INSTR_PRICE_SELL No

à Ext) filter

1 In (Extà ude_price_response - - No
TAP) filter

Request en ty defini on
The en ty ude_price_request must contain the informa on needed by the external service such as the Instrument ISIN code, Currency, Provider, opera on nature,
etc.

There is the possibility to define only one external service per opera on nature or, like in this example, to define only one external service but to have in its
composi on one row per opera on nature with a link to a specific screen.
Response en ty defini on
In this example, the en ty ude_price_response must contain at least the price last_quote_n.

Crea ng orders from instrument list proposed by external service

In this example, while crea ng an order, a list of instruments is proposed by an external service.

Proposed filter in a stock order screen on a ribute instr_id:

IF ( por olio_id <> NULL AND order_type_id <> NULL AND op_currency_id <> NULL,

( &id IN (GET_EXTERNAL_ARRAY(GET_ENTITY("ude_stock_available"),"EXT_STOCK_PROPOSED",&instr_id,3,&instr_id.ref_curr_id = op_currency_id)))

External service defini on
External service is EXT_STOCK_PROPOSED.
Composi on of the external service
Rank Direction Source entity Target Entity Screen (based on target entity) Filter

1 Out (TAP buy_operation ude_stock_request UDE_STOCK_PROPOSED_BUY No

à Ext) filter

1 In (Ext à ude_stock_response ude_stock_available UDE_STOCK_PROPOSED_CHECK *

TAP)

*A filter can be useful to exclude, for example, instruments unknown in Front Office - PM, or to apply other addi onal business rules. Example of a filter to exclude
unknown instruments:

GET_OBJECT("instrument",INIT("ude_stock_response").code).id <> NULL

Request en ty defini on
The en ty ude_stock_request must contain the informa on needed by the external service such as Por olio, Client, linked Strategy, Currency, Market Segment, etc.

[Link] Service [Link]#_Toc47321229%3FTocPath%3DHome%7C… 10/13

5/31/2021 External Service Implementation Guide
Response en ty defini on
The en ty ude_stock_response contains the response from the external service with a list of instruments. The external service should only give instrument code or
ISIN code. But, to propose a list of instruments, the id is necessary therefore, we need to transform the external service response.

The en ty ude_stock_available contains at least the instrument id.

In this example, we have some posi ons like money markets that are managed in another so ware. There is no possibility for Front Office – PM to calculate, for
example, the future cash flows for these posi ons unless the other so ware is called to retrieve and display this informa on. In this case, the following op ons are
available:

Calling external service by scripting in Valuation function

Calling external service by profiling in Valuation function

Calling external service by scrip ng in Valua on func on

Proposed script in a format based on extended_pos:

next_flow_m element:

IF ( instr_id.nature_e = 5 {Money Market},

GET_EXTERNAL_RECORD(GET_ENTITY("ude_future_cflow_response "),"EXT_MM_FUTURE_CFLOWS" ,,&flow_d,1).flow_m

, DEFAULT() )

next_flow_d element:

IF ( instr_id.nature_e = 5 {Money Market},

GET_EXTERNAL_RECORD(GET_ENTITY("ude_future_cflow_response "),"EXT_MM_FUTURE_CFLOWS" ,,&flow_d,1).flow_d

, DEFAULT() )

Calling external service by profiling in Valua on func on

A link between the external service and the Valua on func on exists in the External Service Profile of the user or in the used Channel Profile. When the valua on is
executed, the external service is called, and the resulted en es are then available in the hierarchy of the Valua on func on. The script keywords GET_BEST_OBJECT
and GET_OBJECT_ARRAY can return informa on from these resulted en es.

Proposed scripts in a format based on extended_pos:

next_flow_m element:

IF ( instr_id.nature_e = 5 {Money Market},

GET_BEST_OBJECT(GET_ENTITY("ude_future_cflow_response"),&extended_pos_id=id,,&flow_d,1,,,,,,,,,,,,,,,,,,1 {Data from memory}).flow_m

next_flow_d element:

IF ( instr_id.nature_e = 5 {Money Market},

GET_BEST_OBJECT(GET_ENTITY("ude_future_cflow_response"),&extended_pos_id=id,,&flow_d,1,,,,,,,,,,,,,,,,,,1 {Data from memory}).flow_d

Proposed scripts in a format based on resulted en ty ude_future_cflow_response:

flow_m element:

flow_m

flow_d element:

flow_d

Here, all future flows are returned, not only the next one.

From a business perspec ve, the op on to retrieve the full list of future cash flows would be more relevant within the Journal func on.
External service defini on
External service is EXT_MM_FUTURE_FLOWS.
Composi on of the external service
Screen (based on
Rank Direction Source entity Target Entity Filter
target entity)

1 Out (TAP extended_pos ude_future_cflow_request UDE_FUTURE_CFLOW *

à Ext)

[Link] Service [Link]#_Toc47321229%3FTocPath%3DHome%7C… 11/13

5/31/2021 External Service Implementation Guide

Screen (based on
Rank Direction Source entity Target Entity Filter
target entity)

1 In (Ext à ude_future_cflow_response No
TAP) filter

*A filter can be used to send only the money market posi ons:

instr_id.nature_e = 5 {Money Market}

Request en ty defini on
The ude_future_cflow_request en ty must contain the informa on needed by the external service such as Por olio, Instrument code, Currency, etc.

Depending on the usage of the resulted en es, it can be useful to also send the id of the extended_pos.
Response en ty defini on
The ude_future_cflow_response en ty contains the response from the external service with a list of future cash flows. The external service can contain informa on
such as Por olio, Instrument Code, Currency, Flow Amount, Flow Date, extended_pos_id, etc.

Checking an order session

When checking orders in a session, from a business and performance point of view, a global order-by-order check is preferable. In this example, an external service is
called to check the global validity of the session and the external service returns a list of messages with their severity. These messages are analysed by the Case Rule
func onality to possibly generate cases. Depending on the severity of the message, the session can be traded or not, similar to other cases currently managed in the
applica on.

To perform this check, the external service is linked to the Pre-Trade Compliance Checking func on by the External Service Profile.

Case Rule:

Function = Pre-Trade Check Strategy

Entity = ude_chk_ordsession_message
External service defini on
External service is EXT_CHECK_ORDER_SESSION.
Composi on of the external service
Screen (based on
Rank Direction Source entity Target Entity Filter
target entity)

1 Out (TAP ext-operation ude_chk_ordsession_request UDE_CHK_SESSION No

à Ext) filter

1 In (Ext à ude_chk_ordsession_response - - No
TAP) filter

2 In (Ext à ude_chk_ordsession_message - - *
TAP)

*A filter can be used to send only the messages based on their severity and types:

Severity > 2 AND type IN ("Cash", "Constraint", "Mifid", "Por olio", "Client")
Request en ty defini on
The ude_chk_ordsession_request en ty must contain the informa on needed by the external service such as Por olio, Strategies linked to the por olio, Constraints
linked to the por olio, Client, Instrument ISIN code, Currency, Posi on Amount, Cash Account, Id of ext_opera on, etc.
Response en ty defini on
The ude_chk_ordsession_response en ty contains the global response from the external service.

The ude_chk_ordsession_message en ty contains the response from the external service with a list of messages. This en ty can contain informa on such as Id of
ext_opera on, Por olio, Instrument Code, Message, Severity, Type, etc.

[Link] Service [Link]#_Toc47321229%3FTocPath%3DHome%7C… 12/13

5/31/2021 External Service Implementation Guide

Logging traces for request/responses

In this sec on, you will learn about defining the AAASVCTRACE environment variable (and ini alizing it to any value) to enable the genera on of traces in the
AAAMSG folder:

File format and content

File naming convention

File format and content

The generated file is created in CSV format, allowing it to be easily opened with Microso Excel to display the content of the memory while preparing data to send as
well as to retrieve data from the External Service, together with their eventual intermediate conversions.

The first record in the file shows the content of the domain that was used at the me the External Service is called.

The following records represent the source (TA en es) and target (UDE en es) records prepared for the request, as defined in the composi on of the External
Service.

Finally, the last records represent the source (UDE en es) and target (TA en es) records retrieved from the response, also defined in the composi on of the
External Service.

File naming conven on

The file name conven on is <External Service Code>-<UserCode>-<FINServerName>_YYYY-MM-DD-hh'h'mm'm'ss's'.uuuuuu_(<ThreadNumber>).csv

The file is unique for every call and its name is composed as follows:

<External Service Code> External Service code

<UserCode> User code

<FINServerName> Financial server name

YYYY-MM-DD Current creation date

hh'h'mm'm'ss's' Current creation time

uuuuuu Microseconds (6 digits)

(<ThreadNumber>) Current thread number

.csv File extension

Example:

UDE_RISK_IN_VALO_01-FDV-W9036CHU_S1_2017-02-14-11h22m33s.066000_(00000000044A7D40).csv

Published on: 03/05/2021

[Link] Service [Link]#_Toc47321229%3FTocPath%3DHome%7C… 13/13