action.skip

Custom Placeholders

Placeholders are symbols for fields of Salesforce or JustOn objects (like address fields or invoice data), which are to be replaced with actual values upon text rendering. Placeholders are used, for example, in templates (v1), counters or booking texts.

Basically, there are two types of placeholders:

Built-in Placeholders

JustOn Billing & Invoice Management provides a set of generic, built-in placeholders. These placeholders are defined in the software package. They cannot be modified nor be found in the custom setting Custom Placeholders.

The current built-in placeholders include:

Placeholder Description
[CMPI_AccountHolder] Retrieves the customer's account holder from the JustOn Cash Management payment instrument.
[CMPI_BIC] Retrieves the customer's BIC from the JustOn Cash Management payment instrument.
[CMPI_DDMandateGranted] Retrieves the Direct Debit Mandate Granted date from the JustOn Cash Management payment instrument.
[CMPI_DDMandateReference] Retrieves the direct debit mandate reference from the JustOn Cash Management payment instrument.
[CMPI_IBAN] Retrieves the customer's IBAN from the JustOn Cash Management payment instrument.
[CMPI_MaskedPAN] Retrieves the masked account number from the JustOn Cash Management payment instrument.
[CMPI_BankName] Retrieves the customer's bank name from the JustOn Cash Management payment instrument.
[CMPI_Type] Retrieves the type from the JustOn Cash Management payment instrument.
[CurrentMonth]
[InvoiceLink] Provides a link to the internal payment page (up to JustOn 2.48).
Deprecated
[LastMonth]
[NextMonth]
[NumberOfPages]
[ObjectName] Can only be used in transaction CSV file names.
[OfLabel]
[PageCounter]
[PageLabel]
[PaymentDueDate]
[PaymentLink] Provides a link to the payment page of the (legacy) JustOn Self-Service Extension (as of JustOn 2.49).
Deprecated
[PaymentPageURL] Provides a link to the payment page after integrating with a payment service provider via JustOn Cash Management.
[TaxRate] Can only be used in the tax label field on the template.
[Today]

Custom Placeholders

As opposed to the built-in placeholders, custom placeholders can be modified. If you need additional placeholders for any other custom fields you may have defined, like, for example, the Account object, you can create new custom placeholders.

Custom placeholders always take precedence over built-in placeholders with the same name. This allows for overwriting built-in placeholders using custom placeholders in order to apply custom retrieval logic.

Info

During the installation, JustOn Billing & Invoice Management creates placeholders for many standard and custom fields of JustOn objects. These placeholders, which are referred to as default placeholders, cover the most common fields required when compiling the invoice information to be printed.

JustOn can add new placeholders with every software update.

JustOn Billing & Invoice Management implements custom placeholders using the custom setting Custom Placeholders.

Custom Placeholder Information

The following fields are available for custom placeholders:

Field Required Description
Name Specifies the name of the placeholder, which must be unique.
Decimal Places Specifies the number of decimal places to be printed when rendered as numerical value. Defaults to 2 when left blank.
Fallback if fields empty Specifies a comma-separated list of fields that must all be empty in order to trigger the fallback mechanism. This prevents mixing up of address data if, for example, only single fields of an address (like the street name) are empty. When configured properly, the fallback address is only used when all fields of the primary address are empty.
Fallback if field missing If checked, triggers the fallback mechanism if the primary field is empty.
Fallback rule Specifies the name of the placeholder that is used when the fallback mechanism is triggered by one of the conditions defined above.
Field Specifies the name of the field that is retrieved from the source object.
Custom fields on standard objects must be allowlisted in order to be available as custom placeholders.
Render as Defines the rendering mode for the placeholder, like TEXT, DATE, MONTH, PERCENT, AMOUNT, AMOUNTISO, NUMBER, DECIMALABS, FIELDLABEL, PLAIN, LOCALAMOUNT, LOCALAMOUNTISO.
Source Specifies the name of the source object from which the actual value is retrieved.
Default refers to the current context. For example, the placeholder [GrandTotal] (with the source Default) relates to GrandTotal__c of the invoice if used in an invoice template. If used in a dunning template, however, it relates to GrandTotal__c of the dunning.

Depending on the context, the following sources are available and can be used in the Source field:

Context Possible Sources Description
Invoice Invoice/Default
Account
BusinessEntity
CM_PaymentInstrument
EmailContact
PaymentInstrument
RelatedInvoice
Subscription
Can be used for the PDF and the email subject/body
Invoice Line Item InvoiceLineItem
RelatedInvoice
Can be used in the invoice table in the PDF
Dunning Dunning/Default
Account
BusinessEntity
EmailContact
Can be used for the PDF and the email subject/body
Statement Detail DunningDetail
RelatedInvoice
Can be used in the statement detail table in the PDF
Balance Balance
RelatedInvoice
Can be used in the account statement balance table
Commonly used default placeholders
Placeholder Source Field
[AccountAccountName] Account Name
[AccountBillingCity] Account BillingCity
[AccountBillingCountry] Account BillingCountry
[AccountBillingPostalCode] Account BillingPostalCode
[AccountBillingState] Account BillingState
[AccountBillingStreet] Account BillingStreet
[ContactEmail] EmailContact Email
[ContactEmailFirstName] EmailContact FirstName
[ContactEmailLastName] EmailContact LastName
[ContactEmailSalutation] EmailContact Salutation
[DirectDebitMandateGranted] Default DirectDebitMandateGranted__c
[DirectDebitMandateReference] Default DirectDebitMandateReference__c
[DirectDebitSequenceType] Default DirectDebitSequenceType__c
[DiscountRate] Default DiscountRate__c
[DisplayType] Default DisplayType__c
[Email] Default Email__c
[EmailBCC] Default EmailBCC__c
[EmailCC] Default EmailInvoiceCC__c
[EmailFirstName] Default EmailFirstName__c
[EmailLastName] Default EmailLastName__c
[EmailSalutation] Default EmailSalutation__c
[GrandTotal] Default GrandTotal__c
[InvoiceDate] Default Date__c
[InvoiceNo] Default Name
[InvoiceServicePeriodEnd] Default ServicePeriodEnd__c
[InvoiceServicePeriodStart] Default ServicePeriodStart__c
[MailingCity] Default MailingCity__c
[MailingCountry] Default MailingCountry__c
[MailingFirstName] Default MailingFirstName__c
[MailingLastName] Default MailingLastName__c
[MailingPostalCode] Default MailingPostalCode__c
[MailingSalutation] Default MailingSalutation__c
[MailingState] Default MailingState__c
[MailingStreet] Default MailingStreet__c
[OrderDiscount] Default AEDiscount__c
[PaymentDue] Default PaymentDue__c
[PaymentMethod] Default PaymentMethod__c
[ServicePeriodEnd] InvoiceLineItem ServicePeriodEnd__c
[ServicePeriodStart] InvoiceLineItem ServicePeriodStart__c
[ShippingCity] Default ShippingCity__c
[ShippingCountry] Default ShippingCountry__c
[ShippingPostalCode] Default ShippingPostalCode__c
[ShippingState] Default ShippingState__c
[ShippingStreet] Default ShippingStreet__c

For a complete overview of the available custom placeholders, navigate to Custom Settings > Custom Placeholders > Manage in Setup. This displays the list of custom placeholders that you can use in templates.

Defining Custom Placeholder

To add a new custom placeholder:

  1. Click to enter Setup, then open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of Custom Placeholders.

  3. Click New.
  4. Specify the details as necessary.

    The mandatory information include the name, field, render as and source.

  5. Click Save.

    This creates the new custom placeholder, which can then be used immediately as [placeholdername].

    Info

    Using a new custom placeholder for a custom field on a standard object requires allowlisting the relevant field.

Adjusting Custom Placeholder Display

You can modify the way custom placeholders are rendered.

For date placeholders, you can apply an individual format to overwrite the standard date format. To this end, add the intended format as a parameter to the placeholder, like [InvoiceDate:MM/yy].

Example Date Format String
Sep 17 MMM yy
2017-10-01 yyyy-MM-dd
Fri, Sep 1, 2017 EEE, MMM d, yyyy

Info

For details about supported formats, refer to the Simple Date Format syntax in the Java Documentation.

For text placeholders, you can apply filters to modify the rendered output. The syntax is [placeholder|filter].

JustOn supports the following placeholder filters:

Filter Description
Example
urlencode Encodes the rendered text into the application/x-www-form-urlencoded format, that is, replaces all non-alphanumeric characters (except for hyphen, low line and full stop) with a percent sign followed by two hex digits, and spaces with plus signs.
[InvoiceLink|urlencode]
linebreak If the rendered text is not blank, inserts a line break after the rendered text. Consequently, if a field is not set, there will be no empty line.
Recipient address (all in one line):
[AccountName|linebreak][ContactName|linebreak][RecipientStreet|linebreak][RecipientPostalCode] [RecipientCity]
cut:x Renders only x characters of the placeholder text, where x is a natural number.
[AccountName|cut:20]
no-persist "Copies" the placeholder as a variable to the invoice record, to be replaced only when the PDF is actually rendered. This allows for changes to specific values after an invoice is finalized. It guarantees that the correct value is inserted after all calculations are done, in particular, when using the [Balance] placeholder.
[Balance|no-persist]

Info

You can combine filters, like [AccountName|cut:20|linebreak].

Disabling Placeholders on Invoice Line Items

Under certain circumstances, you may need to disable placeholders on invoice line items. If, for example, you retrieve the product title or description from an external system, they may contain text with square brackets that JustOn must not consider as placeholder mark but as actual brackets.

The following checkbox field on the invoice line item controls the rendering:

Field Default Value Description
Ignore Placeholders false Disables the evaluation of placeholders when finalizing invoices and rendering the PDF.

Info

You can use the ON field mechanism, Salesforce flows or other automation tools to have the Ignore Placeholders field set automatically when generating invoices and invoice line items.