action.skip

How to use JustOn contact roles?

← PDF and Email FAQ

You can pre-populate the contact and address fields using contact roles set on contacts when executing an invoice run, generating account statements and generating dunning reminders.

JustOn Billing & Invoice Management supports contact roles as defined using the custom picklist field JustOn Contact Role on the Contact object and, if set up in your org, on the Account Contact Relationship object (see Contacts to Multiple Accounts in the Salesforce Help).

There are contact roles for the following use cases:

Use Case Fallback to
Invoice Contact
Invoice Mailing Contact Invoice Contact
Invoice Email Contact Invoice Contact
Invoice Email CC Contact
Invoice Email BCC Contact
Dunning Contact Invoice Contact
Dunning Mailing Contact Invoice Mailing Contact
Dunning Email Contact Invoice Email Contact
Dunning Email CC Contact Invoice Email CC Contact
Dunning Email BCC Contact Invoice Email BCC Contact

JustOn Contact Role Priority

With respect to the JustOn contact role behavior and priority, the following specifics apply:

  • If both JustOn Contact Role on the account–contact relationship and JustOn Contact Role on the contact are set, the role defined on the account–contact relationship (irrespective of whether it is a primary or secondary relation) has priority over the role defined on the contact.
  • If JustOn Contact Role is set both on a direct and an indirect account–contact relationship, the role defined on the direct account–contact relationship (primary relation) has priority over the role defined on the indirect account–contact relationship.

  • JustOn Billing & Invoice Management considers JustOn contact roles defined on primary contacts (related via a direct account–contact relationship) only.

    If you need a JustOn contact role on a secondary contact (related via an indirect account–contact relationship), you must define it on the corresponding ACR record.

  • Salesforce allows time limitations and an explicit Active status for account–contact relationships. These settings, however, do not have influence on the priority of the assigned JustOn contact roles. If an account–contact relationship is valid on a given date, JustOn Billing & Invoice Management will consider the assigned contact role.

    You must make sure to not assign two or more contacts with the same role to an account. If this is the case, the system randomly picks one of them, which may produce unwanted results.

  • Contact role settings on the account–contact relationship (ACR) and on the contact can complement each other, as long as they are not in conflict.

  • For compatibility reasons, JustOn Billing & Invoice Management still supports existing Salesforce Classic Account Contact Roles. If available, they take general precedence over the values set in the JustOn Contact Role fields on the contact or the account–contact relationship.

Info

To keep control simple, use JustOn contact roles either on contacts or on account-contact relationships only. If you decide to use account-contact relationships, JustOn recommends to use JustOn contact roles on account-contact relationships for more flexibility.

The following examples illustrate the behavior.

Combination of non-conflicting roles

contact_role_uc1

Contact ACR JustOn Contact Role
1 1-A Direct = true for account A
1-B Direct = false for account B		 Invoice Email CC Contact set on (indirect) ACR 1-B
2 2-B Direct = true for account B Invoice Email Contact set on (primary) contact 2
3 3-B Direct = false for account B

Creating an invoice for account B will set contact 2 in Email Contact and contact 1 in Email CC.

Priority of a role on an ACR over the same role on a contact

contact_role_uc2

Contact ACR JustOn Contact Role
1 1-A Direct = true for account A
1-B Direct = false for account B		 Invoice Email Contact set on (indirect) ACR 1-B
2 2-B Direct = true for account B Invoice Email Contact set on (primary) contact 2
3 3-B Direct = false for account B

Creating an invoice for account B will set contact 1 in Email Contact.

Priority of a role on a direct ACR over the same role on an indirect ACR

contact_role_uc3

Contact ACR JustOn Contact Role
1 1-A Direct = true for account A
1-B Direct = false for account B		 Invoice Email Contact set on (indirect) ACR 1-B
2 2-B Direct = true for account B Invoice Email Contact set on (direct) ACR 2-B
3 3-B Direct = false for account B

Creating an invoice for account B will set contact 2 in Email Contact.

Random result with the same role on two indirect ACRs

contact_role_uc4

Contact ACR JustOn Contact Role
1 1-A Direct = true for account A
1-B Direct = false for account B		 Invoice Email Contact set on (indirect) ACR 1-B
2 2-B Direct = true for account B
3 3-B Direct = false for account B Invoice Email Contact set on (indirect) ACR 3-B

Creating an invoice for account B will randomly set either contact 1 or contact 3 in Email Contact.

No contact set for a role on a secondary contact

contact_role_uc5

Contact ACR JustOn Contact Role
1 1-A Direct = true for account A
1-B Direct = false for account B		 Invoice Email Contact set on contact 1
2 2-B Direct = true for account B
3 3-B Direct = false for account B

Creating an invoice for account B will ignore the contact role defined on the secondary contact 1, Email Contact will not be set.

Enabling Contact Roles

Defining contact roles requires the field JustOn Contact Role to be available on the page layout of the Contact or Account Contact Relationship object.

Depending on your business requirements or use cases, proceed as follows:

  • For users with a JustOn license, you add the managed field JustOn Contact Role (API name ONB2__ContactRole__c) to the page layout of the Contact object.

  • For users without a JustOn license, the managed Contact field ONB2__ContactRole__c is not visible. If you still must support contact roles on contacts, you create the custom field JustOnContactRole on the Contact object, which replicates the behavior of ONB2__ContactRole__c but is available for other Salesforce users.

    Once the custom field is defined, it takes precedence over the managed field.

  • If you need the contact role functionality on account–contact relationships, you create the custom field JustOnContactRole on the Account Contact Relationship object.

Using Managed Contact Role Field on Contact

To add the managed field JustOn Contact Role (API name ONB2__ContactRole__c) to the page layout of the Contact object:

  1. Click to enter Setup, then navigate to the object management settings of the Contact object.
  2. Click Page Layouts.
  3. In the Contact Layout row, click Edit.
  4. Drag the JustOn Contact Role field to the page layout.

  5. Click Save.

    For help about modifying page layouts, see Managing Pages.

Creating Custom Contact Role Field on Contact

To create the custom field JustOnContactRole on the Contact object to replicate the behavior of ONB2__ContactRole__c:

  1. Click to enter Setup, then navigate to the fields list of the Contact object.

    Open the field configuration for JustOn Contact Role in a new browser window or tab for later reference.

  2. Create the following new field.

    Label API Name Data Type Values
    JustOn Contact Role JustOnContactRole Picklist (Multi-Select) Copy all picklist entries from JustOn Contact Role that are needed for your org's uses cases.
    Make sure to use the same API names for the picklist entries.

    For help about creating fields, see Managing Object Fields in the JustOn Documentation or Create Custom Fields in the Salesforce Help.

  3. Allow the relevant users access to the new field either by adding it to their assigned profiles or permission sets.

    For details, see Set Field Permissions in Permission Sets and Profiles in the Salesforce Help.

  4. Allowlist the new field to make it accessible for database queries.

    To this end, create the new Field Whitelist record JustOnContactRole__c.

  5. Add the new picklist field (API name JustOnContactRole) to the Contact layout.

    Remove, if necessary, the managed field (API name ONB2__ContactRole__c) from the layout.

    For help about modifying page layouts, see Managing Pages or Page Layouts in the Salesforce Help.

Creating Contact Role Field on Account Contact Relationship

Salesforce allows associating one contact to multiple accounts through the Account Contact Relationship object. For details and configuration instructions, see

Once set up accordingly, you can enable JustOn contact roles on account–contact relationships. To this end, you create the custom field JustOnContactRole on the Account Contact Relationship object:

  1. Click to enter Setup, then navigate to the fields list of the Account Contact Relationship object.

    Open the field configuration for JustOn Contact Role on the Contact object in a new browser window or tab for later reference.

  2. Create the following new field.

    Label API Name Data Type Values
    JustOn Contact Role JustOnContactRole Picklist (Multi-Select) Copy all picklist entries from JustOn Contact Role on the Contact object that are needed for your org's uses cases.
    Make sure to use the same API names for the picklist entries.

    For help about creating fields, see Managing Object Fields in the JustOn Documentation or Create Custom Fields in the Salesforce Help.

  3. Allow the relevant users access to the new field either by adding it to their assigned profiles or permission sets.

    For details, see Set Field Permissions in Permission Sets and Profiles in the Salesforce Help.

  4. Allowlist the new field to make it accessible for database queries.

    To this end, create the new Field Whitelist record JustOnContactRole__c.

    If you have already allowlisted the custom field JustOnContactRole as created on the Contact object, do not create a second record. A Field Whitelist record allowlists a field, irrespective of its object.

  5. Add the new picklist field (API name JustOnContactRole) to the Account Contact Relationship layout.

    For help about modifying page layouts, see Managing Pages or Page Layouts in the Salesforce Help.

Defining Contact Roles

Once enabled, you can define contact roles for the invoice, account statement or dunning reminder distribution.

To define a contact role for a contact or account-contact relationship:

  1. Open the relevant contact or account-contact relationship.

    On the contact record, change to the Details tab.

    To edit an account-contact relationship:

    • From the Related Contacts related list on an account record, click next to the relevant contact, then select Edit Relationship.
    • From the Related Accounts related list on a contact record, click next to the relevant account, then select Edit Relationship.

    For details, see Create and Edit Relationships Between Contacts and Accounts in the Salesforce Help.

  2. Click next to the JustOn Contact Role field.

  3. Select the intended use case from the JustOn Contact Role picklist.

  4. Click Save.

    Make sure to not assign two or more contacts with the same role to an account. If this is the case, JustOn randomly picks one of them, which may produce unwanted results.

Info

For compatibility reasons, JustOn still supports existing Salesforce Classic Account Contact Roles. If available, they take general precedence over the values set in the JustOn Contact Role fields.

Contact Role Criterion

Contact role criteria add another selectivity level: they are additional conditions for controlling how JustOn Billing & Invoice Management applies contact roles.

Think of a large organization that has different invoice recipients, depending on specific characteristics of the purchased products or services. With the same contact role set on multiple contacts of this account, JustOn Billing & Invoice Management would produce random results. However, applying criteria that cover the specific characteristics – in addition to the contact roles –, you can still control the targeted assignment of the correct contact to a given invoice.

Implementation and Behavior

Info

Depending on your business requirement, you must, first of all, determine the criteria to be applied and their context (the invoice source data or the account).

The contact role criteria are to be combined with JustOn contact roles. For each applicable combination, you need a new picklist value in your JustOn Contact Role field – depending on your requirements, this can be the managed field or the custom field on the contact or, if set up and used, the custom field on the account-contact relationship.

The criterion/use case combination uses this pattern: criterion : use case. Be aware of the following specifics:

  • The criterion is case sensitive.
  • The colon character : separates the criterion from the use case. In Service : Invoice Contact, for example, Service is the criterion, and Invoice Contact is the contact role use case. Whitespaces around the separator are trimmed, so criterion : use case is the same as criterion:use case. If there are multiple colons in the picklist value, the last colon is used as separator: Service : a : Invoice Contact, for example, produces the criterion Service : a and the use case Invoice Contact.
  • Salesforce imposes limits on custom multi-select picklists (see Picklist Limitations in the Salesforce Help). So your JustOn Contact Role picklist can include up to 500 values and up to 255 characters per value, and users can select up to 100 values at a time on one record.

During the invoice run, JustOn Billing & Invoice Management looks for a contact role criterion on the invoice source record or, as a fallback, on the related account. To this end, you create the field ON_ContactRoleCriterion on the relevant source object or the account (or on both, if necessary). You can use formula logic, the ON field mechanism, Salesforce flows or other automation tools to have the intended criterion set on certain conditions.

If there is a criterion set, JustOn Billing & Invoice Management uses it to select the appropriate contact on invoice creation. If there is no criterion, it proceeds to determine the contact role without criterion.

In addition, JustOn Billing & Invoice Management copies the criterion to the Invoice field Contact Role Criterion for downstream processes:

  • When creating dunning reminders from invoices, JustOn Billing & Invoice Management takes the contact role criterion from Contact Role Criterion on the invoice. If it is empty, it proceeds to determine the contact role without criterion.
  • When creating account statements from balances, JustOn Billing & Invoice Management takes the contact role criterion from ON_ContactRoleCriterion on the related account. If there is no criterion found, it proceeds to determine the contact role without criterion.

With respect to the contact role criterion priority – in combination with JustOn Contact Role Priority –, be aware of the following specifics:

  • A contact role criterion set on an invoice source record takes precedence over a contact role criterion set on an account.
  • If a contact role criterion is found, JustOn Billing & Invoice Management compares it with the available criterion/use case combinations – first on account-contact relationships, then on contacts.
  • A criterion/use case combination is considered only if the criterion exactly matches.
  • If no (or a different) criterion is found, JustOn Billing & Invoice Management proceeds to determine the contact role without criterion. Any defined criterion/use case combinations are ignored because there is no matching criterion.

This results in the following priority of matching targets when a criterion is found:

ACR with criterion
↳ contact with criterion
     ↳ ACR without criterion
          ↳ contact without criterion

Examples

The following examples illustrate the behavior.

No criterion found, priority of contact role without criterion

contact_role_criterion_uc1

Creating an invoice from the subscription will set contact 1 in Email Contact.

Criterion found, priority of matching criterion/use case combination

contact_role_criterion_uc2

Creating an invoice from the subscription will set contact 2 in Email Contact.

Different criteria found, priority of criterion/use case combination from the invoice source record

contact_role_criterion_uc3

Creating an invoice from the subscription will set contact 3 in Email Contact.

No criterion found, priority of contact role without criterion, irrespective of ACR

contact_role_criterion_uc4

Creating an invoice from the subscription will set contact 1 in Email Contact.

Criterion found, priority of matching criterion/use case combination, irrespective of ACR

contact_role_criterion_uc5

Creating an invoice from the subscription will set contact 2 in Email Contact.

Combination of non-conflicting roles

contact_role_criterion_uc6

Creating an invoice from the subscription will set contact 2 in Email Contact and contact 1 in Email CC.

Enabling Contact Role Criterion

Note

Before proceeding to technically enabling the contact role criterion feature, determine the criteria to be applied and their context – that is, you decide which conditions of your invoice source data or your accounts are to control how JustOn Billing & Invoice Management applies contact roles.

After you have determined the contact role criteria, proceed as follows to enable the functionality:

  1. Create the field ON_ContactRoleCriterion on the relevant invoice source object or the account.

    API Name Data Type Notes
    ON_ContactRoleCriterion Text (255)
    Formula (Text)    		 Use formula logic, the ON field mechanism, Salesforce flows or other automation tools to have the intended criterion set on certain conditions.

  2. Add the applicable criterion/use case combinations to the JustOn Contact Role field.

    Depending on your requirements, this can be the managed field or the custom field on the contact or, if set up and used, the custom field on the account-contact relationship.

    For details, see Modifying Picklist Values.