Using Data Mapping

Data mappings allow for retrieving the data required for the generic invoice run or the automatic subscription build from virtually any fields of any objects. This mechanism facilitates a more flexible mapping configuration if the ON field mechanism is not sufficient enough.

Data Mapping Configuration

The field mapping is defined in JSON notation and can either be stored as a Salesforce document or directly in a field on the record that is to be processed.

API Name	Data Type	Description
ON_MappingName	Text (255) or Formula (Text)	Specifies the name of the file that contains the field mapping definition in JSON. Deprecated, accessible via the Documents tab in the Salesforce Classic UI only. Use ON_MappingId instead.
ON_MappingId	Text (255) or Formula (Text)	Specifies the 18-digit, case-safe Salesforce record ID of the file that contains the field mapping definition in JSON. Takes precedence over ON_MappingName.
ON_Mapping	Text Area (Long)	Specifies the field mapping definition in JSON. Make sure to write all JSON code in a single line without spaces. Takes precedence over ON_MappingId and ON_MappingName.

Info

You only need one of the above fields, depending on where you store the mapping configuration.

ON_Mapping always takes precedence. If ON_MappingName and ON_MappingId are set, ON_MappingId takes precedence.

The mapping can be used to

• define relationships by external IDs,
• add additional values to the target object fields,
• write values from the parent record to individual items, or
• write values from child records to the parent.

Note

Be aware that the data types of the mapped fields must be identical.

Data Mapping JSON Structure

The following listing illustrates the mapping structure.

{
    "externalIdFields":{
        "Account__c":"ExternalId__c"
    },
    "fields":{
        "Field__c":"$FIELDNAME",
        "StartDate__c":"$FIELDNAME"
    },
    "fieldsToUpdate":["StartDate__c"],
    "items":{
        "ORDERNO":{
            "fields":{
                "Title__c":"$FIELDNAME",
                "Checkbox__c":true
            },
            "fieldsToUpdate":["Title__c"],
            "tiers": [
                {
                    "Quantity__c":42.0,
                    "Price__c":"$ORDERNO.FIELDNAME",
                    "Type__c":"Flat",
                    "Target__c":"Price"
                },
                {
                    "Quantity__c":null,
                    "Price__c":47.11,
                    "Type__c":"Default",
                    "Target__c":"Price"
                }
            ]
        },
        "XYZ" : {
            "fields":{...},
            "tiers":[...]
        }
    }
}

externalIdFields

The mapping externalIdFields is used to define lookup relationships from the invoice or subscription to other records, like account or template. This may be required, for example, if ON_Account is not set or if the invoice or subscription is to be assigned to another account. It can also be used to link an invoice or a subscription to existing records without knowing or storing their Salesforce IDs in an external system.

externalIdFields is a map where the keys are lookup field names on the invoice or subscription. Its values are field names on the target object that are configured as an external ID.

Link to an account with the external ID foo12345:

"externalIdFields":{
    "Account__c":"ExternalId__c"
}

There must be an account with ExternalId__c = foo12345. ON_Account on the source object must be set to foo12345.

fields

The mapping fields allows to directly define field values for the resulting invoice or subscription. Field references like $FIELDNAME and $ORDERNO.FIELDNAME are matched with the corresponding fields on the source object and its children, and are then replaced with their values.

Be aware that $ORDERNO is case-sensitive and that fields that are referred to by $FIELDNAME have to be allowlisted if they are custom fields on a standard object without ON_ prefix (see Field Whitelist).

Replace field references:

Assume a source object with CloseDate = 2017-12-01 and a child source object with ON_OrderNo = SETUP and Price = 47.11.

The mapping looks as follows:

"fields":{
    "StartDate__c":"$CloseDate",
    "SetupPrice__c":"$SETUP.Price"
}

Result after the replacement:

"fields":{
    "StartDate__c":"2017-12-01",
    "SetupPrice__c":47.11
}

fieldsToUpdate

Info

fieldsToUpdate is used by the subscription builder only.

The mapping fieldsToUpdate defines the target fields of the subscription or the subscription item that are to be updated (see Enabling Subscription and Subscription Items Update). It can be set for the subscription and each OrderNo item.

Update start date and end date:

"fieldsToUpdate" : ["StartDate__c", "EndDate__c"]

items

The mapping items allows to define field values for invoice line items or subscription items to be created or updated. Be aware of the following specifics:

• Each item must be referred to by a unique identifier (ORDERNO).

  When building subscription and items, this value maps the OrderNo field of the item.

  When building invoices and invoice line items, this value is not transferred to the produced records, but must still be unique for the mapping configuration.

• Field references like $FIELDNAME are also replaced with values from the source object and its children.

Create invoice line items:

Assume a source object that defines a title, a quantity and a price, and have the generic invoice run produce corresponding invoice line items. The mapping may look like this:

{
    "items":{
        "ILI1":{
            "fields":{
                "Title__c":"$FIELDNAME",
                "Quantity__c":"$FIELDNAME",
                "UnitPrice__c":"$FIELDNAME"
            }
        },
        "ILI2":{
            "fields":{
                "Title__c":"$FIELDNAME",
                "Quantity__c":"$FIELDNAME",
                "UnitPrice__c":"$FIELDNAME"
            }
        }
    }
}

items.ORDERNO.tiers

Info

tiers is used by the subscription builder only.

The mapping tiers allows to define (multiple) price tiers or commission tiers. Each mapping defines field values as key-value pairs.

The field Target defines whether the tier is considered as a price tier or a commission tier. Field references are also replaced with values from the source object and its children.

Note

Define tiers either using the mapping or with the master subscription item, not both.