Display Balances in Payment Currency in Payslip

By design, the Global Payslip displays the balances in the currency for which they were created and calculated. A currency conversion may be applied at the time of payment, and the Payslip would show this appropriately within the Net Pay Distribution region.

The following worked example demonstrates how one might modify the Payslip template in order for it to convert the displayed balances into the currency used for Payment

Note: It must be acknowledged however that making the Payslip template convert the displayed balances from the currency used to calculate them within the Payroll Run into another currency used for Payment, could lead to rounding issues.

  • A pre-requisite step would be to configure the Payroll Archive in order for it to extract the necessary exchange rates that were used for Payments, such that the Payslip template can subsequently apply them to the balances
  • Payroll Archive HCM Extract Setup Configuration to Store Exchange Rates
  • Configure the Payroll Archive in order for it to extract the necessary exchange rates as follows:
    • Navigate: Payroll Calculation work area > Manage Fast Formulas
    • Create Extract Rule formula to obtain exchange rates for your LDG

  • Note: It is necessary to specify a Legislative Data Group in this dialog box in this case.
    • Populate the Formula with text:

DEFAULT FOR DATA_ELEMENT_CODE IS ‘USD>USD’ INPUTS ARE DATA_ELEMENT_CODE (TEXT)

IF NOT WSA_EXISTS(‘XRATE:’+DATA_ELEMENT_CODE) then (

RULE_VALUE = GET_RATE(substr(DATA_ELEMENT_CODE,1,instr(DATA_ELEMENT_CODE,’>’)-1) ,substr(DATA_ELEMENT_CODE,instr(DATA_ELEMENT_CODE,’>’)+1) ,PAY_GET_RATE_TYPE(‘T’))

WSA_SET(‘XRATE:’+DATA_ELEMENT_CODE, RULE_VALUE) /* Cache Rate */

) ELSE RULE_VALUE = WSA_GET(‘XRATE:’+DATA_ELEMENT_CODE, ‘1’) /* Get Cached Rate */ return RULE_VALUE

  • Compile the Formula
  • Note: The above formula assumes the Payroll Archive effective date is the same as all the Pre-Payments (and that the rate(s) had not been re-loaded/changed, i.e were static, between the two process executions), in order for the same rate value(s) to be retrieved independently by both those processes
  • Navigate: Data Exchange > Manage HCM Extract Definitions
  • Enter Search criteria:
  • Legislative Data Group Payroll Archive
  • Click Search
  • Navigate: Global Archive Payroll Relationships
  • Create a new Formula-based Detail Extract Record
  • This example shows the extract record name of User Retrieve Exchange Rate with an XML tag name of REC_GET_XCHG_RATE

  • Create one Extract Data Element per payment currency where type is Rule within the new record created in the previous step Important Notes:
    • The data element(s) created here should reference the Extract Rule formula created in the first step
    • The short code should follow the format: from_currency_code>to_currency_code, for example, AED>USD (to facilitate the above data-driven rule formula from currency code of AED to currency code USD)
    • The element xml tag name should follow the format RATE from=”from_currency_code” to=”to_currency_code”, for example Rate from “AED” to= “USD”
    • Use xml tag attributes to specify the two currencies, in order to help facilitate a more data-driven BIP Payslip Template Customization

  • Navigate: Actions > Generate Formula

  • Navigate: Actions > Compile Formula

  • Run Payroll Archive
  • Navigate: Payment Distribution > View Person Process Results
  • View exchange rates archived by the Archive Periodic Payroll Results task

  • BIP Payslip Template Customization
  • GLOBAL TEMPLATE EXAMPLE
  • Steps above must be completed before proceeding with the following
  • Note: These steps are based on the Global Payslip template; however, if you have an existing customizations, your steps may need to vary or your results may vary
  • Using the modified version of PayslipMainTemplate.rtf, set a variable storing a default/dummy exchange rate of 1 to cover the standard case where employees are paid in the default LDG currency and no conversion is necessary (see above code as a ‘conversion’ from USD to USD), insert a BIP Form Field within the <?for-each:GLB_ARCH_CBID?> grouping/looping tag containing the following code:

    <?xdoxslt:set_variable($_XDOCTX,’XRATE:USD>USD’,1)?>

    <?for-each:../../REC_GET_XCHG_RATE/RATE?>

    <?xdoxslt:set_variable($_XDOCTX,concat(‘XRATE:’,@from,’>’,@to),.)?>

    <?end for-each?>

    <?xdoxslt:set_variable($_XDOCTX,’CBID’,GLB_PAY_ARCH_CBID_INFORMATION/CALC_BREAKDOWN_ID)?>

    <?xdoxslt:set_variable($_XDOCTX,’PAYMENT_CC’,../../../PAYMENT_DETAILS[CALC_BREAKDOWN_ID=xdoxslt:get_variable($_ XDOCTX,’CBID’)][1]/CURRENCY)?>

  • Note: If USD is not your default LDG currency code used for your payroll calculations, substitute USD in the above code for your default LDG currency code and, if needed, add further logic to set similar variables storing a default/dummy exchange rate of 1 for any further currencies in use
  • Find the exchange rate(s) within in the XML and store in variable(s) named ‘XRATE:from_currency_code>to_currency_code’ For example, ‘XRATE:AED>USD’
  • Find the payment currency code used for payment and store in variable named ‘PAYMENT_CC’ and, number from the first payment record found for the person, in the case where there are multiple payments
  • In the modified version of PayslipSubTemplates.rtf for your locale, Change the BIP Form Field code for displaying each monetary balance amount
  • For example, to multiply the given balance amount (if non-null) with the stored exchange rate for the given payment currency, change from

    <?PAYMENT?>

    To

    <?if@inlines:PAYMENT!=”?>

    <?PAYMENT*xdoxslt:get_variable($_XDOCTX,concat(‘XRATE:AED>’,xdoxslt:get_variable($_XDOCTX,’PAYMENT_CC’)))?>

    <?end if?>

  • Note: There are other monetary balance amount tags such as <?YEAR?> and <?GLB_PAY_ARCH_PAY_ASG_INFO/SALARY_AMOUNT?>
  • Verify your modified Main template will import the correct modified version of the sub-template (via the import statement), from the location for modified templates
  • Upload the modified templates as described in previous steps
  • For example Payslip output follows both the delivered and the modified Global templates, for a UAE employee paid in USD.

Example Output from Supplied Global Payslip

Example Output from Modified Global Payslip

  • COUNTRY-SPECIFIC TEMPLATE EXAMPLE
  • Steps to modify country-specific versions of the Payslip template would basically be the same as the above customization example based on the Global template; however, depending on the exact differences between the Global template and the country-specific version, the details may vary slightly
  • For example, Navigate: BIP Catalog > Human Capital Management > Payroll > Regulatory and Tax Reporting > Emirates > shipped template for UAE is HRXAEPayslip.rtf
  • Rather than calling the respective Global sub-templates, it is best practice to implement a UAE-specific version of both the Employee Information details table and the Net Pay Distribution details table
  • Note: The UAE-specific version of the Employee Information details table conveys more information than the Global version, such as an additional field for displaying the Contributory Salary balance amount, which would also need to be modified as a part of this worked-example

Example UAE-specific template

  • Using the modified version of HRXAEPayslip.rtf, set a variable storing the default/dummy exchange rate from AED to AED to cover the standard case where the person is paid in AED and no conversion is necessary (see above example code as a ‘conversion’ from AED to AED), insert a BIP Form Field within the <?for-each:GLB_ARCH_CBID?> grouping/looping tag, containing the following code:

    <?xdoxslt:set_variable($_XDOCTX,’XRATE:AED>AED’,1)?> <?for-each:../../REC_GET_XCHG_RATE/RATE?> <?xdoxslt:set_variable($_XDOCTX,concat(‘XRATE:’,@from,’>’,@to),.)?> <?end for-each?>

    <?xdoxslt:set_variable($_XDOCTX,’CBID’,GLB_PAY_ARCH_CBID_INFORMATION/CALC_BREAKDOWN_ID)?>

    <?xdoxslt:set_variable($_XDOCTX,’PAYMENT_CC’,../../../PAYMENT_DETAILS[CALC_BREAKDOWN_ID=xdoxslt:get_variabl e($_XDOCTX,’CBID’)][1]/CURRENCY)?>

  • Note: Add further logic to set similar variables storing a default/dummy exchange rate of 1 for any other currencies in use
  • Find the exchange rate(s) within in the XML and store them in variables similarly named ‘XRATE:from_currency_code>to_currency_code’ For example, ‘XRATE:AED>USD’.
  • Find the payment currency code used for payment and store in variable named ‘PAYMENT_CC’ and, number from the first payment record found for the person, in the case where there are multiple payments
  • In the modified version of PayslipSubTemplates.rtf for your locale, change the BIP Form Field code for displaying Contributory Salary amount
  • For example, to multiply the Contributory Salary amount (stored in a variable called ‘CS’) by the stored exchange rate for the given payment currency change from

    <?xdoxslt:get_variable($_XDOCTX,’CS’)?> to <?xdoxslt:get_variable($_XDOCTX,’CS’)*xdoxslt:get_variable($_XDOCTX,concat(‘XRATE:AED>’,xdoxslt:get_variable($_XDO CTX,’PAYMENT_CC’)))?>

  • Note: There are other monetary balance amount tags such as <?YEAR?> and <?GLB_PAY_ARCH_PAY_ASG_INFO/SALARY_AMOUNT?>
  • In the modified version of PayslipSubTemplates.rtf for your locale, change the BIP Form Field code for displaying each monetary balance amount
  • For example, to multiply the given balance amount (if non-null) with the stored exchange rate for the given payment currency change from

    <?PAYMENT?> to <?if@inlines:PAYMENT!=”?>

    <?PAYMENT*xdoxslt:get_variable($_XDOCTX,concat(‘XRATE:AED>’,xdoxslt:get_variable($_XDOCTX,’PAYMENT_CC’)))?> <?end if?>

Note: There are other monetary balance amount tags such as <?YEAR?> and <?GLB_PAY_ARCH_PAY_ASG_INFO/SALARY_AMOUNT?>

  • Ensure your modified Main template will import the correct modified version of the sub-template (via the import statement), from the location for modified templates.
  • Upload the modified templates as described in previous steps
  • For example Payslip output follows both the delivered and the modified Global templates, for a UAE employee paid in USD
  • Note: The above steps are by way of an example based on the shipped UAE template; they may possibly need to be altered depending on any existing modifications you might have already made to that template
  • Example Payslip output follows for both the shipped and then modified UAE templates, for someone paid in USD.

Example Output from Supplied UAE Payslip

Example Output from Modified UAE Payslip