Skip to content

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 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
[CurrentMonth]
[InvoiceLink] Provides a link to the internal payment page (up to JustOn 2.48).
[PaymentLink] Provides a link to the payment page of the JustOn Self-Service Extension (as of JustOn 2.49).
[LastMonth]
[NextMonth]
[OfLabel]
[PageCounter]
[PageLabel]
[TaxRate] Can only be used in the tax label field at 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.

Info

During the installation, JustOn 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 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 whitelisted 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
EmailContact
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
[PaymentDueDate] Default PaymentDueDate__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. In Setup, 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].

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. [AccountName|linebreak]
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 processes or other automation tools to have the Ignore Placeholders field set automatically when generating invoices and invoice line items.