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 (or generic)
• custom

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.