Skip to content

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.

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) Specifies the name of the document that contains the field mapping definition in JSON.
ON_Mapping Text Area (Long) Specifies the field mapping definition in JSON.
Takes precedence over ON_MappingName.

Info

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

If the two fields are set, ON_Mapping 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.

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 white-listed (custom setting) if they are custom fields on a standard object without ON_ prefix.

■ 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 each OrderNo item.

■ Update start date and end date:

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

items

The mapping items allows to define field values for the resulting invoice line items or subscription items. Each item is referred to by an order number, which must be unique. Field references are also replaced with values from the source object and its children.

items.ORDERNO.tiers

Info

tiers is used by the subscription builder only.

The mapping tiers allows to define (multiple) 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.

Next steps:

Billing Arbitrary Objects
Automatically Building Subscriptions

Return to JustOn Administration.