Temenos Explorer Installation Guide
Overview
This document is the installation guide for Temenos Explorer (TEX) framework. It should not be confused with Transact Explorer which is the user agent for accessing Transact T24 enquiries and versions.
This document does not describe the installation of individual plugin applications (User Agents) hosted within Temenos Explorer. These should be documented by the plugin owner.
There are four key parts to any Temenos Explorer installation:
- Keycloak
- API Gateway
- Temenos Explorer
- Micro Services or Transact APIs
Keycloak configuration is well documented elsewhere, but specific items of note are included here.
API Gateway allows Temenos Explorer plugins to easily access APIs on a variety of servers. This needs to be configured to know the location of Keycloak and of the Micro Services / APIs that are in use. It is envisaged that an Enterprise API gateway will be used in preference in production environments, but that is not essential.
A jboss/WAR deployment may not need to use the API Gateway if all APIs are local to the deployment (same server and port).
Temenos Explorer itself needs configuration to know the location of KeyCloak and to know the specific roles in use.
Micro Services or Transact APIs are a prerequisite and are assumed to already exist and are not described here.
Obtaining Temenos Explorer
Those within the Temenos network can obtain the latest snapshot from http://cloud-ivy.temenosgroup.com/build/TemenosEx/latest/
Those outside the network will need to obtain it from Distribution.
Installation Guide
Keycloak Users and Roles
Keycloak
Keycloak provides installation documentation, so this will not be repeated here, however additional information on Keycloak is here:
https://developer.temenos.com/temenos-explorer/docs/framework/utilities/keycloak
and here:
https://developer.temenos.com/temenos-explorer/docs/developer/keycloak/overview
Users and Roles
The following configuration is required once you have created a Keycloak realm and client:
1) Within the client, create the desired role names.
2) Create the desired users.
3) On each user, assign the desired client roles.
4) If a user has more than one role, create the attribute “default_role” and populate this with the preferred default role that the user should get when logging in.
5) On early Keycloak versions such as V16 & V17 it is necessary to create a mapper in the client to include the default_role attribute in the JWT.
Record the URL at which Keycloak runs, as this will need to be input into the API Gateway and Temenos Explorer config files.
NB: Keycloak V16 includes the suffix “/auth” in the URL, whereas later versions do not.
API Gateway Configuration
The API Gateway is configured in a single file, config.json which is read during startup.
It provides CORS compliance allowing browsers running Temenos Explorer to invoke APIs on any appropriate server and provides logging of API success/failure plus logging of Javascript errors that will not persist on client machines.
Each different service requires configuration entries to enable the API Gateway to recognise requests and distribute to the appropriate endpoint.
Further information available here: https://developer.temenos.com/temenos-explorer/docs/developer/configuration/api-gateway
config.json
| port | Port on which to listen to http requests |
|---|---|
| portHttps | Port on which to listen to https requests (blank if https not used) |
| tokenValidation | Controls validation of the incoming request’s Authorization header JWT none: no validation (not advisable for production) internal: validation decoding the JWT using the Keycloak public key (will not detect token revocation after logout) external: validation by invoking a Keycloak token validation endpoint (preferred option) |
| auth-server-url | Keycloak token validation endpoint prefix |
| realm | Keycloak realm |
| RS256keyid | Keycloak public key – currently unused, may be left blank |
| JWT-Header | Currently unused, may be left blank |
| JWT-Public-Key-File | Filename of Keycloak JWT public key file – used for “internal” token validation |
| sslPrivateKey | Filename of private key file if https used – This file needs to be provided by the organisation running Temenos Explorer |
| sslPublicCert | Filename of public certificate file if https used – This file needs to be provided by the organisation running Temenos Explorer |
| logging | Master switch to control logging to console and/or file |
| consoleLogLevel | Control amount of logging to console: error |
| fileLogLevel | Control amount of logging to file /logs/app.log: error |
| maxLogFileSize | Maximum size of log file before starting new log |
| maxLogFiles | Maximum number of log files to keep |
| echoDelay | Delay before responding to echo requests (used for development/testing only) |
| allowLogAccessUsers | Comma separated list of (authenticated) users allowed to access the logs via the API Gateway /log endpoint |
| corsHeaders | Array of header names “header” and values “value” to respond with on all requests to ensure CORS compatibility |
| services | Array of routings and handlers for each API endpoint described below |
services sub-entries
| Parameter | Description |
|---|---|
| service | Unique/arbitrary service name |
| incomingRoute | URL pattern to match incoming request for this service |
| baseUrl | URL prefix to use to forward the incoming request i.e. real API endpoint prefix |
| getHandler | Function name to invoke for GET requests, normally “genericGet” |
| postHandler | Function name to invoke for POST requests, normally “genericPost” |
| putHandler | Function name to invoke for PUT requests, normally “genericPut” |
| forwardHeaders | Array of headers that should be forwarded or [“*”] to forward all incoming headers |
| headers | Object containing headers to be added to the forwarded request – usually API keys etc |
| queryStrings | Object containing items to be added to the URL’s query section – usually API keys etc |
Example config:
{
"serviceName": "partyMS",
"incomingRoute": "/ms-party-api/api*",
"baseUrl": "http://temenosexplorer2301.northeurope.cloudapp.azure.com:3000",
"getHandler": "genericGet",
"postHandler": "genericPost",
"putHandler": "genericPut",
"forwardHeaders": ["*"],
"headers": {},
"queryStrings": {}
},
The above config will forward requests that are received as http://{this-server-name}:8085/ms-party-api/api to <http://temenosexplorer2301.northeurope.cloudapp.azure.com:3000/ms-party-api/api>
e.g.
http://{this-server-name}:8085/ms-party-api/api/V5.0.0/party/parties
will be forwarded to
http://temenosexplorer2301.northeurope.cloudapp.azure.com:3000/ms-party-api/api/V5.0.0/party/parties
API Gateway Deployment
API Gateway runs as a Node JS application.
From the ApiGateway folder, execute the following:
npm run bootstrap This will install the application and only needs doing once
npm start This runs the application
Alternatively, if API Gateway is to run in a container, the installed application folder should be copied into the container for deployment and should run the npm start command on startup.
Temenos Explorer Configuration
Node vs WAR
Temenos Explorer config files all exist in the TemenosExplorer/public folder. However, Temenos Explorer may be deployed as a Node JS application or as a WAR file running in a web server such as Jboss.
If running as a WAR:
The root folder is ready-built from the TemenosExplorer/public folder. Higher folders are not part of the deployment.
You may wish consider taking advantage of the Temenos Explorer's ConfigServlet to manage web-server-host specific settings (via OS environment variables and template config files), thereby allowing the same physical Temenos Explorer WAR file to be deployed to (and run within) multiple target environments (system-test, production, etc).
TA_config.js
Temenos Explorer’s main configuration file is called TA_config.js (but see/consider ConfigServlet if Temenos Exporer is going to be deployed as a WAR).
Many settings contain the value \$HOSTNAME$:\$PORT$
This value does not need to be replaced unless the relevant item does not exist on the same server and port as the web site. It is automatically replaced by the JavaScript values window.location.hostname and window.location.port at runtime.
Configurations available are:
| Parameter | Settings |
|---|---|
| logging | true / false - Controls browser console debug logging – should be false for production environments. Errors will always be logged |
| UPDATEURL | Update the URL to show the specific page - for deep linking |
| APIS, top["APIS"] | IRIS or MS APIs in use. If IRIS, user info will be obtained from Transact |
| top["LOGINAPIS"] | If IRIS APIS, get user info (appropriate companies etc) from TBSERVER or IRIS - default is IRIS |
| top["APPLICATIONNAME"] | 'Temenos Explorer' - Preferred application name for page title and pre-login page |
| top["AUTHENTICATION"] | ‘KEYCLOAK’ / ‘T24’ / 'CUSTOM' – type of authentication employed – currently Keycloak or T24 Authenticator supported, if CUSTOM, TA_customIAM.js must be developed to match the IAM solution chosen |
| top["ROLESOURCE"] | ‘KEYCLOAK’ / ‘TBSERVER’ - If AUTHENTICATION is KEYCLOAK but LOGINAPIS is TBSERVER, user roles can be loaded either from KEYCLOAK or TBSERVER as required |
| top["MERGEUSERROLES"] | true / false - Permissions and menus from all of user's roles should be merged and role switching turned off? |
| top["AUTHHEADER"] | ‘Authorization’ – request header name containing the authentication token – automatically changed to 'T24auth' if T24 authentication is detected |
| top["ALTERNATEROLEARRAYLOCATION"] | Alternate location in the JWT where roles may exist - e.g.realmAccess.roles |
| top["CUSTOMISATION"] | Controls which L3 customisations should be applied in TEX itself – may not affect plugin applications unless they monitor this value |
| top["missingTranslationAction"] | Text to use when a translation is not found default_or_key – recommended value - show a developer supplied default, or the translation key if no default was supplied default_and_key – show a developer supplied default and the translation key default – show a developer supplied default (or blank if not default supplied, so not recommended) key – show the translation key silent – as per default_or_key but do not log missing translation to console or API Gateway – useful if an incomplete new language is flooding the log with errors |
| top["PREFERNEWBROWSERTAB"] | true / false - If taskBarLocation is 'hide', should we always launch a new browser tab for every menu option? |
| top["APITIMEOUT"] | Number of seconds before slow API responses are terminated and assumed failed |
| top["APISPEEDTHRESHOLD"] | Number of seconds before an API is considered to be “slow” within the health-check window |
| CONFIG | Runtime endpoint and default configurations described below in more detail |
| HEALTHCHECK | Array of endpoints to invoke when performing a health check |
| HEALTHCHECK_PRELOGIN | Array of unauthenticated endpoints to invoke when performing a health check on the pre-login page |
| SESSIONTIMEOUTWARN | Number of seconds before session end warning is shown to the user – less than SESSIONTIMEOUT |
| SESSIONTIMEOUT | Number of seconds before session ends and user is logged off – should be just less than Keycloak/IAM session expiry |
| CONFIG values | Description |
|---|---|
| KEYCLOAKURL | Keycloak authentication URL endpoint This will likely end with /auth for Keycloak V16 but not for later versions |
| KEYCLOAKREALM | Keycloak realm |
| KEYCLOAKCLIENT | Keycloak client |
| KEYCLOAKREDIRECT | URL Keycloak should redirect back to after successful login – if running from a WAR file in Jboss, the application name (usually TemenosExplorer/) will need to be included |
| KEYCLOAKLOGOUTREDIRECT | URL Keycloak should redirect back to after logout – if running from a WAR file in Jboss, the application name (usually TemenosExplorer/) will need to be included |
| TBSERVERROOTURL | Transact Browser server root URL for API calls |
| TESERVER | Location of Transact Explorer APIs |
| TRANSACTAPIPREFIX | URL prefix for Transact IRIS R18 API calls |
| MOCKSERVERROOTURL | Development API mocking only |
| FETCHMOCKROOTURL | Development API mocking only |
| LOGURL | URL to use to log JavaScript and missing translation errors |
| ADDITIONALLOGOUTURL | Additional URL to invoke during logout – do not use |
| PERMISSIONSURL | URL to get XACML based permissions for the current user role |
| PASSKEYCLOAKTOKEN | true / false – include Keycloak token on API requests if “Authorization”:”accesstoken” is passed by plugins (that do not know the token) – should always be true |
| TRANSACTROLES | Array of roles that are permitted to use Temenos Explorer if using T24 authentication instead of Keycloak – or [“unrestricted”] if no restriction to be applied |
| DIRECTION | ‘ltr’ / ‘rtl’ - Default direction for new users until user selects their preference |
| LANGUAGE | Default language code for new users until user selects their preference |
| DATEFORMAT | Default date format for new users until user selects their preference |
| TIMEFORMAT | Default time format for new users until user selects their preference – not currently used |
| NUMERICFORMAT | Default numeric format for new users until user selects their preference |
| LANGUAGES | Array of languages available in the translation file TA_translations.js |
| TIMES | Array of time formats selectable by users – not currently used |
TA_permissions.js
Permissions are given to business operations on a per-role basis, so each role is given its own configuration and list of permissions as described below.
| RoleId | Role ID as it appears in Keycloak |
|---|---|
| Role Description | Human friendly role (short) description |
| TransactRoleId | Transact T24 equivalent role |
| LegalEntity | Transact T24 equivalent company e.g. GB0010001 |
| Startup | Startup plugin for this role after login – can be blank if no startup plugin required |
| StartupParameters | Not currently used - Object to pass to startup plugin – e.g. {"page":"criteria"} |
| Dashboard | Not currently used |
| Menus | String containing a comma separated list of menus to show for this role – see TA_menus.js |
| Permissions | Array of business operations appropriate for this role - these may span multiple plugins if the role can access multiple plugins. Can be an empty array if permissions are instead coming from Generic Config Micro Service at PERMISSIONSURL |
| ServiceRequests | Not currently used |
TA_menus.js
Menus are represented as a json object tree structure. A user’s role usually has just one menu, but can have more as configured in the Menus property in TA_permissions.js
Each menu is simply an array of sub-menus and/or child items which themselves may also be menus or child items.
Menus have the following properties:
| Property | Description |
|---|---|
| MenuId | Unique identifier that can be referred to in TA_permissions.js |
| Menu | Array of menu items |
| type | “menu” / “item” |
| label | Language key for menu’s text |
| open | Always false |
| childItems | Array of sub-menus or menu options |
| actionId | For menu options, this is the name of the plugin. It could also be a URL if a new window is to be launched |
| querystring | Parameters to be passed to the plugin e.g. { "page":"criteria" } |
| data | Redundant - No longer used |
TA_translations.js
Translations are defined in a standard JSON object tree structure in TA_translations.js and are broken down into a handful on namespaces listed below.
| Namespace | Description |
|---|---|
| plugin-title | Titles that appear along the Temenos Explorer navigation bar |
| menu | Menu option labels |
| appBar | Items that relate to the top navigation bar and its popup windows |
| general | General translations for page contents, buttons etc – This is one of the main sections |
| fields | Database field labels/column headings – This is one of the main sections |
Within these sections, individual translations appear. Each translation has a key and within this, each language (2 character locale) has a value of the actual text to display for that language.
The application code references the translations using a value such as “fields.account” and the translator utility converts this based on the selected language to be “Account” or “Compte” as appropriate.
Adding new languages is simply a case of adding a new entry with the appropriate language locale and translation key for each existing translation – e.g. “es”:” Cuenta”, for the fields.account item shown.
Any new language also needs adding to the LANGUAGES property of TA_config.js so that the user may select it (but see/consider ConfigServlet if Temenos Exporer is going to be deployed as a WAR).
Note: Plugin applications can also define additional translations in the same way which will supplement the translations provided in this master translation file.
XACML Policies
Whilst role-specific permissions can be defined in the TA_permissions.js configuration file, it is also possible to load permissions from the Temenos Generic Config Micro Service. In order to do this, a non-empty value must be specified for CONFIG.PERMISSIONSURL in TA_config.js This value will be the uri for the XACML policy (in json format or base64 encoded json) within the GCMS. e.g.
PERMISSIONSURL: 'http://$HOSTNAME$:8085/ms/msgenconfig/api/v1.0.0/system/configurationGroups/SECURITY.POLICY/configuration/{roleid}.json',
The above instructs Temenos Explorer to obtain the policy from the GCMS via the API Gateway, accessing the SECURITY.POLICY group and Temeos Explorer will automatically replace {roleid} in the request with the current user role id (normally defined in Keycloak) to obtain the correct policy at runtime.
Note that permissions obtained from GCMS are supplemental to those already defined in TA_permissions.js, so the role should be defined there with an empty Permissions array if the XACML policy is complete and no supplemental/hard-coded permisions are intended. Alternatively, any items present in the TA_permissions.js Permissions array will be merged with those from the XACML policy.
Temenos Explorer Deployment
Before deploying Temenos Explorer, you should check that any plugin applications are correctly configured according to their installation guide.
WAR Deployment
Once the WAR file’s config files have been adjusted it can be placed in the jboss/standalone/deployments folder and should auto-deploy.
Node Deployment
From the TemenosExplorer folder, execute the following:
npm run bootstrap This will install the application and only needs doing once
npm start This runs the application
Alternatively, if Temenos Explorer is to run in a container, the installed application folder should be copied into the container for deployment and should run the npm start command on startup:
Cloud / SaaS deployment
Cloud deployments rely on containers being created to hold Temenos Explorer and API Gateway. Scripts to build these exist in the root of the BitBucket repo...
Dockerfile-Saas-TemenosExplorer
Dockerfile-Saas-ApiGateway
These can be used to create a container for Temenos Explorer and API Gateway respectively. It is expected that these scripts will be modified based on environment requirements - e.g. choice of web server etc. See later in this section for information about ecxternalised environment variables.
Rebuilding from source
If you have made changes to source (not just config) and need to rebuild, use the command:
npm run build
Rebuilding Temenos Explorer does not rebuild plugin applications! They should be rebuilt independently from within their TemenosExplorer/public/plugins/{plugin-name} folder.
TA_config.js siblings
Temenos Explorer reads its configuration from the TA_config.js file. However, several similarly named copies of this file are present so it is easy for developers to switch between environments/configurations. In addition, there are further copies that improve deployment flexibility:
TA_config.SAAS.configservlet-template.js can be used as a template in conjunction with the ConfigServlet mentioned elsewhere in this guide for WAR file deployments.
TA_config.SAAS.js is used by the Cloud deployment script as a template to obtain environment variables which are populated by the TA_config.SAAS.update.js script run during the Dockerfile-Saas-TemenosExplorer containerisation script.
Environment Variables (externalising config)
When deployed as a container, TEX can obtain its config values from envrionment variables.
TEX supports this by providing a script that may be included in the container start-up called TA_config.SAAS.update.js.
Specifically, in container image build script Dockerfile-Saas-TemenosExplorer, you will see the startup command is “npm run start:saas”.
In package.json, you will see that this script executes the TA_config.SAAS.update.js script. TA_config.SAAS.update.js reads the environment variables and injects these into template TA_config.SAAS.js, which is then used to replace TA_config.js.
Environment variables are clearly identified in the template TA_config.SAAS.js as $ENV.XXX$ and are listed in the table below. They are defined in the Temenos Explorer helm chart.
| Variable | Usage |
|---|---|
| TEX_HEALTHCHECK_POSTLOGIN | json object definition of the healthcheck endpoints |
| TEX_HEALTHCHECK_PRELOGIN | json object definition of the healthcheck endpoints (before login) |
| TEX_APIS | 'IRIS' / 'MS' - Backend APIs are IRIS or Micro services |
| TEX_CUSTOMISATION | string identifying any customisation - blank unless code is writted to read this value and react accordingly |
| TEX_LOGGING | true / false - should there be javascript logging |
| TEX_UPDATE_URL | true / false - should the URL anchor be updated with current page info (assists deep linking) |
| TEX_AUTHENTICATION | 'KEYCLOAK' / 'CUSTOM' - authentication method |
| TEX_API_TIMEOUT | numeric - number of secconds before API calls will be timed out |
| TEX_KEYCLOAK_URL | root url of Keycloak authentication e.g. http://111.222.333.444:8180/auth |
| TEX_KEYCLOAK_REALM | keycloak realm |
| TEX_KEYCLOAK_CLIENT | keycloak client |
| TEX_TB_SERVER_ROOT_URL | root url of Transact Explorer's tb-server e.g. http://$HOSTNAME$:8085/tb-server |
| TEX_TE_SERVER | root url of Transact Explorer e.g. http://$HOSTNAME$:8085 |
| TEX_TRANSACT_API_PREFIX | root url of transact irf-provider container e.g. http://$HOSTNAME$:8085/irf-provider-container/api |
| TEX_LOG_URL | url endpoint to which javascript errors may be logged (usually at the API gateway) e.g. http://$HOSTNAME$:8085/log |
| TEX_ADDITIONAL_LOGOUT_URL | url endpoint to invoke when logout is requested |
| TEX_PERMISSIONS_URL | url endpoint to obtain XACML defined permissions (in json or base64 encoded json) |
| TEX_LANGUAGES | json object definition of available languages |
| TEX_TIMEOUT_WARN | numeric - number of ms before session timeout warning |
| TEX_TIMEOUT_LOGOUT | numeric - number of ms before session timeout forces logout |
| TEX_CUSTOM_JS_URL | url endpoint (in generic config) where customisation javascript is held, normally empty |
| TEX_TRANSLATIONS_URL | url endpoint (in generic config) where custom language definitions are held in json format, normally empty |
| TEX_TASKBAR | hide/bottom/side - default position of task bar |
| TEX_ALTERNATE_ROLE_ARRAY_LOCATION | alternate location of roles in the token - e.g. realmAccess.roles |
| TEX_CONTEXT | contect path of the Temenos Explorer web site - e.g. TemenosExplorer |
| TEX_MERGE_USER_ROLES | false/true - Merge user roles and menus together and disable role switching |
| TEX_AUTH_HEADER | Authorization/T24Auth - header used to path authentication token to IRIS |
| TEX_MS_ROOT_URL | real root url of all Micro Services - e.g. https://111.222.333.444:8443 |
| TEX_TRANSACT_ROOT_URL | root url of irf-provider-container etc via gateway - e.g. https://111.222.333.444:8085 |
| TEX_MS_API_ROOT | root url of all Micro Services via gateway - e.g. https://111.222.333.444:8085 |
| TEX_EPD_MS_PATH | context path of the EPD MS - e.g. /ms-holdings-api/api |
| AZURE_CODE_REQ | false/true - running in AZURE? |
| TRANSACT_PATH | path to Transact IRIS provider APIs - e.g. /irf-provider-container/api |
| TRANSACT_PUBLISHER_PATH | path to Transact IRIS publisher APIs - e.g. /irf-publisher-container/api |
| API_GATEWAY | root url of API Gateway |
Optional additional variables for API Gateway…
| Variable | Usage |
|---|---|
| TEX_TOKEN_VALIDATION | external/internal/none - type of token validation done by the gateway |
| TEX_GATEWAY_CONTEXT | contect path where API gateway is running.g. gateway |
| TEX_PARTY_MS_PATH | context path to PARTY MS APIs - e.g. /ms-party-api/api |
| TEX_ARRANGEMENT_MS_PATH | context path to Arrangements MS |
| TEX_HOLDINGS_MS_PATH | context path of Holdings MS |
| TEX_CONFIG_MS_PATH context | path of Generic Config MS - e.g. /ms-genericconfig-api/api |
| TEX_SR_MS_PATH | context path of Service Request MS |
| TEX_TRANSACT_PATH | as previously mentioned above |
| TEX_TRANSACT_PUBLISHER_PATH | as previously mentioned above |
| TEX_TRANSACT_ROOT_URL | root of Transact's war deployments (Browser, Transact Explorer, tb-server etc) - e.g. https://11.22.33.44:9089 |
| TEX_ANALYTICS_ROOT_URL | root of analytics APIs |
| ANALYTICS_PATH | path to analytics APIs |
| ANALYTICS_AUTH | authorization code for Analytics APIs |
| TRACE_ORIGINAL_ROOT_URL | ignore |
| TRACE_ORIGNAL_PATH | ignore |
| TRACE_ORIGINAL_AUTH | ignore |
| CODAT_ROOT_URL | ignore |
| CODAT_PATH | ignore |
| PAM_BASE_URL | ignore |
| PAM_PATH | ignore |
| DOCUMENT_MS_PATH | ignore |
Document History
| Author | Version | Date |
|---|---|---|
| R. Thorpe | V0.1 | 18/07/2023 |
| R. Thorpe | V0.2 | 03/09/2024 |
| R. Thorpe | V0.3 | 24/09/2024 |