Map Transaction Journals with Contracts and Orders

Learning Objectives

After completing this unit, you’ll be able to:

• Map Transaction Journal fields with Contract and Order fields.
  
• View sample mappings for Transaction Journal and reference object fields.
  
• Explain how the Get Eligible Program Rebate Types API operates.
  

What Are Field Mappings?

As you learned in the previous units, the eligibility criteria for a rebate type drives the list of rebates available for selection on a contract. The eligibility criteria also drives which rebate types show up as applicable on orders based on the products added.

When the rebate types are displayed on the Eligible or Applied tabs of the Program Rebate Types Panel, the application evaluates the criteria and finds rebate types that match Account Territory on Contract with what’s set up as the eligibility conditions for rebate types. As you may recall, the eligibility conditions are set up to filter records based on Transaction Journal fields.

For the application to evaluate this, it must know how a Contract’s Account Territory field maps to a similar field in Transaction Journal. Or, how an Order Line Item’s Product field maps to the Product Name field in Transaction Journal.

With a highly configurable integration, you can map any object and its fields with Transaction Journal and its fields. This helps you run an evaluation of eligible and applied rebate types on any object’s record.

The option you use to define product-based eligibility criteria (either Define Eligibility or Included or Excluded Products) determines which rebate types show in the Eligible tab of the Program Rebate Types component. To ensure rebate types are filtered for the eligible products, map any required fields with the Transaction Journal fields.

How to Create the Field Mappings

To create the field mappings, Cindy had to download the configuration data of the ObjectHierarchyRelationship metadata API, make the required changes, and upload it again. To download the configuration data from an org, perform the retrieve() call in any API tool. 

Cindy retrieved the configuration data using the API call. Next, she created a .txt component file to define the mapping. ObjectHierarchyRelationship components have the suffix ObjectHierarchyRelationship.settings and are stored in the ObjectHierarchyRelationship folder. She created one file per mapping.

1. Contract and TransactionJournal (parentObjectMapping)
   
2. Order and Transaction Journal (parentObjectMapping)
   
3. Order Item and Transaction Journal (childObjectMapping)
   
   

If a mapping isn’t created, the following scenarios take place.

• The list of Eligible rebate types for a contract displays all rebate types, irrespective of the conditions set up on Rebate Type.
  
• Applied rebate types aren't visible in the Applied tab even if the Account in the contract is already enrolled in rebate programs.
  

Cindy then used these steps to map the fields between Contract and Transaction Journal, and Order and Transaction Journal.

1. Create a mapping XML to define the input and output objects and field mappings.
   
2. Deploy the mapping XML in the org using an API call.
   

Cindy already defined a custom field Account Territory on both Contract and Transaction Journal objects. The custom field is of picklist data type and has the following values, APAC, AMER, and EMEA.

The Mapping XML

Let’s take a look at the mapping samples to understand this better. A mapping component file contains the following key attributes.

Here’s an example of the field mappings between Contract and Transaction Journal. The fields mapped are Account ID, and Account Territory on Contract with Member ID, and Account Territory on Transaction Journal.

<?xml version="1.0" encoding="UTF-8"?>
<ObjectHierarchyRelationship xmlns="http://soap.sforce.com/2006/04/metadata">
  <parentObjectMapping>
    <inputObject>Contract</inputObject>
    <outputObject>TransactionJournal</outputObject>
    <mappingFields>
      <inputField>AccountId</inputField>
      <outputField>MemberId</outputField>
    </mappingFields><mappingFields>
      <inputField>Account Territory</inputField>
      <outputField>Account Territory</outputField>
    </mappingFields>
  </parentObjectMapping>
  <usageType>EligibleProgramRebateType</usageType>
 </ObjectHierarchyRelationship>

Here’s an example of the field mappings between Order and Transaction Journal. The fields mapped are Account ID on Order with Member ID on Transaction Journal. Fields are also mapped for Product2 on Transaction Journal with Product on Order Item.

<?xml version="1.0" encoding="UTF-8"?>
<ObjectHierarchyRelationship xmlns="http://soap.sforce.com/2006/04/metadata">
  <parentObjectMapping>
    <inputObject>Order</inputObject>
    <outputObject>TransactionJournal</outputObject>
    <mappingFields>
      <inputField>AccountId</inputField>
      <outputField>MemberId</outputField>
    </mappingFields>
</parentObjectMapping>
 <childObjectMapping>
   <inputObject>OrderItem</inputObject>
   <outputObject>TransactionJournal</outputObject>
   <mappingFields>
     <inputField>Product2Id</inputField>
     <outputField>ProductId</outputField>
   </mappingFields>
 </childObjectMapping>
<usageType>EligibleProgramRebateType</usageType>
</ObjectHierarchyRelationship>

The source object’s AccountId to Transaction Journal’s MemberId mapping tells the system how to determine applied rebate types. If the source object’s account has a current rebate program membership, the associated rebate types are shown.

Deploy!

The deployment makes use of the ObjectHierarchyRelationship metadata API. Cindy prepared the package. 

Each package contains one mapping xml file and a package.xml file. The mapping .xml files are added in the .settings file. The package.xml file is a project manifest that basically defines the API version of the org and the type of metadata. For more details, see Deploying and Retrieving Metadata with the Zip File. 

The structure of the two deployment packages in the API tool look like the following.

Contract Mapping package:

ObjectHierarchyRelationship
  ObjectHierarchyRelationshipContract.settings
package.xml

Order Mapping package:

ObjectHierarchyRelationship
  ObjectHierarchyRelationshipOrder.settings
package.xml

Once Cindy zipped up the folder she was ready to deploy!

Cindy uploaded the zip folder with the component files for mappings and the package.xml file. She needed to deploy this zip file into the Rayler Parts org so that the changed configuration data was uploaded to Salesforce. Here’s how she did it.

1. Create a folder with the package.xml file in the root and a sub level folder with the component names.
   
2. Zip the folder.
   
3. Visit Postman or any other API tool of your choice, and log in with your username and password.
   
4. Click the Migration tab. Select the Deploy section.
   
5. Click the Choose file option.
   
6. Confirm all of the options for deployment.
   
7. Click Deploy.
   
8. Wait for the process to complete. If not successful, check the file for errors.
   

To understand how to retrieve and deploy in Postman using Metadata API, refer to the Postman Learning Center.

To learn more about working with Postman in Salesforce, refer to the Quick Start: Connect Postman to Salesforce module. For support from the Open Source community, use Stackoverflow. However, you may use any API tool of your choice and perform the deploy() call.

Once Cindy successfully completed the first configuration step, she turned her attention to the next set of requirements: designing a screen flow that allows Vance to add eligible rebate types to the contract.

The API-Powered Card

Before she created the screen flow, she wanted to understand what happens under the hood.

The Program Rebate Types Panel card retrieves a list of all eligible rebate types, and the information is surfaced on the Eligible tab of the card. This action is triggered with the Get Eligible Program Rebate Types API. Check out this topic for details. 

Cindy didn’t need to act on this information, but it’s helpful for her to know that there’s an API that powers and drives the information on the Program Rebate Types Panel card. Cindy can use the API directly to create or modify the UI to show the eligible rebates.

Here’s the qualification criteria for what defines an eligible rebate type.

• The reference object (Contract) must be mapped with Transaction Journal.
  
• The rebate type must be marked Integratable (checkbox on the Rebate Type record).
  
• The rebate type must be Active (checkbox on the Rebate Type record).
  
• The eligibility criteria of the rebate type must match the data of the reference record. If the rebate type doesn’t have any eligibility criteria defined, it shows up as eligible for all records for the reference object.
  

The API also retrieves a list of already applied rebate types for the reference record if the Member ID in the associated rebate program matches the Account ID of the reference record. These rebate types are shown on the Applied tab of the Program Rebate Types Panel card.

Resources

• Salesforce Help: Field Mappings for Eligible and Applied Rebate Types
• Salesforce Help: Create Mappings for Eligible and Applied Rebate Types
• Salesforce Developer Guide: ObjectHierarchyRelationship