Customizing Operation Form Data
When creating an operation, you can customize the operation form data. This customization has an effect on how the operation form data is displayed during the operation review step.
The customization should be done by the client which initiates the operation before the authentication process is initiated.
For more information about operation form data see the Next Step REST API.
Standard Operation Form Data Attributes
Following attributes are required to be specified for each operation:
title
- title of the operationgreeting
- message for the user related to the operation displayed in web interfacesummary
- summary of the operation shown in push messages
Custom Operation Form Data Attributes
Following structured custom form data attributes are available:
AMOUNT
- amount with currencyNOTE
- free textBANK_ACCOUNT_CHOICE
- choice of a bank accountKEY_VALUE
- generic key-value fieldBANNER
- banner which is displayed above form fieldHEADING
- heading with labelPARTY_INFO
- information about party
Value Formatting
Following form data attributes support value formatting:
AMOUNT
NOTE
KEY_VALUE
HEADING
The value is formatted based on specified format type. The following format types can be used:
TEXT
- value is not formattedLOCALIZED_TEXT
- value is localized using localization key from message resourcesDATE
- value is formatted as date using current locale, expected value format is YYYY-MM-DDNUMBER
- value is formatted as number using current localeAMOUNT
- value is formatted as amount with currency using current localeACCOUNT
- value is not formatted (reserved for future use)
Resource Localization
Form data labels are specified using localization key, such as “operation.title”. This key is localized using resources. See chapter Customizing Web Flow Appearance for details about updating resources.
Form data value localization for custom attributes:
- Form data values are localized in case they use the
LOCALIZED_TEXT
value format type. - Currency in
AMOUNT
form data type is localized using message resource:currency.[currency].name
.
Other form data values are not localized and are displayed as received.
Resource Translation
Resource translation is process of inserting other form data values into existing values.
Example:
operation.summary=Hello, please confirm payment {operation.amount} {operation.currency} to account {operation.account}.
Summary is translated into:
operation.summary=Hello, please confirm payment 100 CZK to account 12345678/0123.
Resource translation is performed on following attribute values:
title
greeting
summary
Java API for Operation Form Data
See example below:
// variable definition
String account = "238400856/0300";
BigDecimal amount = BigDecimal.valueOf(100);
String currency = "CZK";
String note = "Utility Bill Payment - 05/2019";
String dueDate = "2019-06-29";
// operation form data initialization
OperationFormData formData = new OperationFormData();
formData.addTitle("operation.title");
formData.addGreeting("operation.greeting");
formData.addSummary("operation.summary");
formData.addAmount("operation.amount", amount, "operation.currency", currency);
formData.addKeyValue("operation.account", account, ValueFormatType.ACCOUNT);
formData.addKeyValue("operation.dueDate", dueDate, ValueFormatType.DATE);
formData.addNote("operation.note", note, ValueFormatType.TEXT);
// sample operation configuration for bank account choice select
OperationFormFieldConfig bankAccountConfig = new OperationFormFieldConfig();
bankAccountConfig.setId("operation.bankAccountChoice");
bankAccountConfig.setEnabled(false);
bankAccountConfig.setDefaultValue("CZ4043210000000087654321");
formData.getConfig().add(bankAccountConfig);
// operation initialization
final ObjectResponse<CreateOperationResponse> payment = client.createOperation("authorize_payment", data, formData, null, applicationContext);
session.setAttribute("operationId", payment.getResponseObject().getOperationId());
Decorating Operation Form Data in Data Adapter
Operation form data can be decorated in Data Adapter by implementing method decorateFormData
. The additional form attributes appear during the operation review step (after the user was authenticated and operation authorization is required).
Adding bank account choice
The example below decorates operation form data – three bank accounts are added to the BANK_ACCOUNT_CHOICE
attribute:
List<BankAccount> bankAccounts = new ArrayList<>();
BankAccount bankAccount1 = new BankAccount();
bankAccount1.setName("Běžný účet v CZK");
bankAccount1.setBalance(new BigDecimal("24394.52"));
bankAccount1.setNumber("12345678/1234");
bankAccount1.setAccountId("CZ4012340000000012345678");
bankAccount1.setCurrency("CZK");
bankAccounts.add(bankAccount1);
BankAccount bankAccount2 = new BankAccount();
bankAccount2.setName("Spořící účet v CZK");
bankAccount2.setBalance(new BigDecimal("158121.10"));
bankAccount2.setNumber("87654321/4321");
bankAccount2.setAccountId("CZ4043210000000087654321");
bankAccount2.setCurrency("CZK");
bankAccounts.add(bankAccount2);
BankAccount bankAccount3 = new BankAccount();
bankAccount3.setName("Spořící účet v EUR");
bankAccount3.setBalance(new BigDecimal("1.90"));
bankAccount3.setNumber("44444444/1111");
bankAccount3.setAccountId("CZ4011110000000044444444");
bankAccount3.setCurrency("EUR");
bankAccount3.setUsableForPayment(false);
bankAccount3.setUnusableForPaymentReason(dataAdapterI18NService.messageSource().getMessage("operationReview.balanceTooLow", null, LocaleContextHolder.getLocale()));
bankAccounts.add(bankAccount3);
boolean choiceEnabled = true;
String defaultValue = "CZ4012340000000012345678";
List<FormFieldConfig> configs = formData.getConfig();
for (FormFieldConfig config: configs) {
if ("operation.bankAccountChoice".equals(config.getId())) {
choiceEnabled = config.isEnabled();
// You should check the default value against list of available accounts.
defaultValue = config.getDefaultValue();
}
}
Attribute attr = formData.addBankAccountChoice(BANK_ACCOUNT_CHOICE_ID, bankAccounts, choiceEnabled, defaultValue);
Adding form banners
The example below adds a banner on top of the operation form:
formData.addBanner(BannerType.BANNER_WARNING, "banner.warning");
The available banner types are:
- BANNER_ERROR
- BANNER_WARNING
- BANNER_INFO
The second parameter is the localization string with text message of the banner.
Adding banners before fields
The example below decorates operation form data by adding banner above the BANK_ACCOUNT_CHOICE
attribute which was previously added:
formData.addBannerBeforeField(BannerType.BANNER_WARNING, "banner.invalidAccount", attr);
The available banner types are:
- BANNER_ERROR
- BANNER_WARNING
- BANNER_INFO
The second parameter is the localization string with text message of the banner.
The third parameter is the attribute before which the banner is added.
Adding headings
The example below shows how to add a heading attribute:
formData.addHeading("operation.heading1", "operation.headingTop", ValueFormatType.LOCALIZED_TEXT);
The parameters are:
- ID of the heading attribute (label is not displayed, so it is not localized)
- Localization ID of message for heading
- LOCALIZED_TEXT is the value format type for text localization by chosen language
For non-localized version of heading you can use:
formData.addHeading("operation.heading1", "Payment");
Adding party information
The example below shows how to add information about a third party:
// Add information about 3rd party
PartyInfo partyInfo = new PartyInfo();
partyInfo.setName("Tesco PLC");
partyInfo.setLogoUrl("https://www.tescoplc.com/media/474818/plc_image_logo.png?anchor=center&mode=crop&width=820&height=462&rnd=131722809190000000");
partyInfo.setDescription("British groceries and general merchandise retailer");
partyInfo.setWebsiteUrl("https://www.tescoplc.com");
formData.addPartyInfo("operation.partyInfo", partyInfo);
In order to add party information before an existing field instead of appending it after last field, use the addPartyInfoBeforeField()
method.
Adding application context
The example below specifies application context for an operation. The application context is used in CONSENT
step to generate the consent form.
ApplicationContext applicationContext = new ApplicationContext();
applicationContext.setId("DEMO");
applicationContext.setName("Demo application");
applicationContext.setDescription("Web Flow demo application");
applicationContext.getOriginalScopes().add("aisp");
applicationContext.getExtras().put("applicationOwner", "Wultra");
Note that the extras
is a Map which can be used for adding other key-value items required for the consent form. Use the create ApplicationContext
instance when creating the operation.
Operation Form Data JSON
When creating operations using Next Step API, you can specify operation form data using JSON instead of using the Java API.
Note: label
and formattedValue
fields in examples below are always null, because these values are used internally:
label
is localized by taking theid
and localizing it into current languageformattedValues
is constructed using logic based onvalueFormatType
and field value
AMOUNT
:
{
"type": "AMOUNT",
"id": "operation.amount",
"label": null,
"valueFormatType": "AMOUNT",
"formattedValues": {},
"amount": 100,
"currency": "CZK",
"currencyId": "operation.currency"
}
Remarks:
- Always use
AMOUNT
asvalueFormatType
- The
amount
value can use decimal point - Use ISO format of
currency
, the value is localized using message resources (e.g.currency.CZK.name
) - The
currencyId
value is used to determine localization ID for the word “currency”
KEY_VALUE
:
{
"type": "KEY_VALUE",
"id": "operation.account",
"label": null,
"valueFormatType": "ACCOUNT",
"formattedValues": {},
"value": "238400856/0300"
}
Remarks:
- Supported value format types which influence the
formattedValue
:TEXT
- non-localized text (as is)LOCALIZED_TEXT
- localized text (using message resources)DATE
- date formatted in operation localeNUMBER
- generic number formatted in operation localeAMOUNT
- monetary amount formatted in operation localeACCOUNT
- account value (not formatted because the syntax may differ greatly)
NOTE
:
{
"type": "NOTE",
"id": "operation.note",
"label": null,
"valueFormatType": "TEXT",
"formattedValues": {},
"note": "Utility Bill Payment - 05/2019"
}
Remarks:
- The
note
string is not localized, it is taken “as is”.
HEADING
:
{
"type": "HEADING",
"id": "operation.heading1",
"label": null,
"valueFormatType": "TEXT",
"formattedValues": {},
"value": "Heading"
}
Remarks:
- The
label
is ignored, theHEADING
field uses only a value. - The
value
is formatted using givenvalueFormatType
(same value format types as inKEY_VALUE
).
BANNER
:
{
"type": "BANNER",
"id": "banner.error",
"label": null,
"message": null,
"bannerType": "BANNER_ERROR"
}
Remarks:
- The
label
is ignored, theBANNER
field uses only a value. - The banner message is taken from the
id
field by localizing message resource with such ID. - Supported banner types:
- BANNER_ERROR
- BANNER_WARNING
- BANNER_INFO
PARTY_INFO
:
{
"type": "PARTY_INFO",
"id": "operation.partyInfo",
"label": null,
"partyInfo": {
"logoUrl": "https://itesco.cz/img/logo/logo.svg",
"name": "Tesco",
"description": "Objevte více příběhů psaných s chutí",
"websiteUrl": "https://itesco.cz/hello/vse-o-jidle/pribehy-psane-s-chuti/clanek/tomovy-burgery-pro-zapalene-fanousky/15012"
}
}
Remarks:
- The value is structured and it is not localized.