Example Messaging Relationship Setup

Before you begin creating relationships and mappings, you must make sure that:

• An administrator has granted you permission to manage messaging data
• You have set up or identified the relevant source objects and fields that you want to send data from and have permission to edit them
• You have set up or identified the relevant target objects and fields that you want to send data to and have permission to edit them

In this example, we want to send data from a custom object called Work Order and its child, Work Order Line. We want to send data to the Certinia Billing Document and Billing Document Line Item. Further information about the fields used is described below.

In this example, the Foundations (ERP) registered product will be used to represent the publication side of the messaging relationship where we specify the data we want to send. The Billing Central (BC) registered product will be used to represent the subscription side of the messaging relationship where we specify how to save sent data.

If your org is already set up for messaging, registered product records might already exist for ERP and BC.

For more information about how registered products are created, see Registered Products.

To begin, we must create a message type, which describes the general purpose of the data being transferred.

For this example, we want to create a new message type called Update that has a parent of WorkOrder. We create the WorkOrder parent message type first. This enables us to group other message types that we create in the future that also relate to work order information.

When the parent message type is created, we can create a new message type for Update, specifying WorkOrder as the parent. This creates a new message type with a unique developer name of WorkOrder.Update, which describes the location of the message type.

For more information, see Creating Custom Message Types.

When you view message types from the Publications & Subscriptions subtab of the Foundations Setup tab, the new Update message type is shown grouped below the parent WorkOrder message type. Any other message types created in the future that contain a WorkOrder parent will also be shown in this section of the message types tree. See the next section for more information about the information shown on the Foundations Setup tab.

The Foundations Setup tab provides a high-level overview of all aspects of your messaging integrations. You can:

• View the list of message types and the products that publish and subscribe to messages in each category
• Manage message log retention settings
• Schedule jobs to delete or send messages

For more information, see Foundations Setup.

The next step is to create a relationship on the message type. Message types can contain several publications and subscriptions, the combination of which is known as a messaging relationship.

You can view the message type by clicking its name on the Publications & Subscriptions subtab of the Foundations Setup tab.

To create the relationship:

1. Click Manage Relationship on the message type. Here, you have options to select an existing publication and subscription or create new ones. As none exist on this message type yet, we can create new ones with the following information.
2. For the publication:
   1. Select "New Publication".
   2. Specify the publishing product. This is the ERP product.
   3. Search for and select the object that will provide the source data. For this example, select "Work Order".
   4. Specify the field that can be used to uniquely identify the records you send. By default, the record ID is used as the default value as it is always unique.
3. For the subscription:
   1. Select "New Subscription".
   2. For the subscription type, select "Standard".
   3. Select the subscribing product. For this example, this is the BC product.
   4. Search for and select the object that you want to send data to.
   5. Specify the field on the target object in which you want to store the source's unique identifier. This enables you to keep source and target records in sync. In this example, we want to use a custom lookup field called Work Order to store this information.
      Tip:

      By using a lookup on the target record, we can display a link back to the source record, if required.

   6. Click Save.

Your relationship is displayed in the Relationship and Mapping Details section of the page and you're ready to add mappings to it.

For more information, see Creating a Messaging Relationship.

This section provides information about simple mappings. In this example, we want to send the following details from fields on work order records and create billing document records that contain this information.

Key: * - Required fields on the target.

For each field you want to send from the source object, create a mapping:

1. On the relationship, click Add Mapping.
2. Enter a message key that describes the information you are sending. For example, for Document Type, enter Doc Type.
3. Leave the source type as "Field".
4. For the source field path, select the name of the source field. For example, "Document Type".
5. Leave the target type as "Field".
6. For the target field, select the name of the target field. For example, "Document Type".
7. Click Save.

If you want to assign specific record types to your records, you can send static data or information from a field in your message. For more information, see Sending and Receiving Record Types.

For more information about mapping options, see Adding Mappings to a Messaging Relationship.

Data transformation tables enable you to change data received in a message so that it is appropriate for the target field. You can create data transformation tables that contain one or more data transformations. Each data transformation contains one or two source values and the target value.

In this example, we want to create a mapping from the source field Billing Country to the target field Project Type. The Project Type field shows whether a billing document is categorized as domestic or international. We have work orders with a billing country of GB, HK, and US. We want to show US work orders as domestic project types on the billing document and any others as international.

To transform billing country details sent from the work order to the billing document, we can create a simple data transformation table that contains this information.

To create the data transformation table:

1. From the Data Transformation Tables tab, click New.
2. Enter a name for the table, for example Project Type.
3. Enter a description to help others understand how this table is used.
4. Click Save.

To create the data transformations for each value you want to change:

1. From viewing the Project Type data transformation table, view the related list and click New.
2. For source value 1, enter the name of the first billing country you want to transform. For example, GB.
3. Leave source value 2 blank.
4. For target value, enter the value you want to display on the target record. For example, International.
5. Click Save & New.
6. Repeat Steps 2 to 5 to transform HK to International.
7. Repeat Steps 2 to 4 to transform US to Domestic.
8. Click Save.

On the messaging relationship, create a new mapping from Billing Country to Project Type and apply the data transformation table to the mapping:

1. On the relationship, click Add Mapping.
2. Enter a message key that describes the information you are sending. For example, Project Type.
3. For the target type, select "Transformed Data".
4. For the source field path, select the name of the source field. For example, "Billing Country".
5. Leave the target type as "Field".
6. For the target field, select the name of the target field. For example, "Project Type".
7. Select the Project Type data transformation table you created.

It's also possible to create data transformations that contain two source values. For more information about more complex data transformations, see Data Transformation Tables and Creating a Data Transformation Table.

A child relationship enables you to send data from a record that is related to the source record to a record that is related to the target record. In this example, we want to send data from:

• Work orders to billing documents, and
• Related work order lines to related billing document lines

To do this, we first need to create a child relationship mapping:

1. On the relationship, click Add Mapping.
2. Enter a message key that describes the information you are sending. For example, for this child relationship, enter Work Order Lines.
3. For the source type, select "Child Relationship".
4. For the source child relationship, select the name of the related object. Related objects are displayed by their API name. In this example, select "Work_Order_Lines__r".
5. Leave the target type as "Child Relationship".
6. For the target child relationship, select the name of the related object. For example, "ChildBillingDocumentLineItems__r".
7. For this example, do not select a child filter field. More information about filtering is available in the next section.
8. Select the record creation method to determine whether records are kept in sync. For this example, we want to synchronize records that we create using messaging, so select "Update Matching". This option means that changes to source records are applied to the corresponding target records.
9. As we have specified that we want to keep records in sync, select the fields that are used to identify matches:
   • Unique Identifier on Source: For this example, we want to use the record ID.
   • Identifier Reference on Target: For this example, we want to use a custom text field called Work Order Line.
     Note:

     If you want to use custom target child types, the field that you specify as the identifier reference on target for the child relationship mapping must be a text field. If you plan to use only the default target child type for your child mappings, you can use a lookup field. For more information about target child types, see [Optional] Define and Use Target Child Types in Child Mappings.

   You might recognize these fields as being the same as those on the messaging relationship. This is because the child relationship itself is a relationship between two objects.
10. Click Save.

Now that you've created a child relationship, you can add mappings to it. Without specific mappings on the child relationship for any required fields, no target records can be created.

For more information about mapping options, see Adding Mappings to a Messaging Relationship.

This section provides information about simple child mappings. In this example, we want to send the following details in work order line records and create billing document line item records that contain this information.

You add a child mapping to a child relationship in a very similar way to a messaging relationship. The following table describes the mappings we want to create for the child relationship.

Key: * - Required fields on the target.

For each field you want to send from the child source object, create a mapping:

1. On the relationship, click in the Work Order Lines child relationship row and click Add Child Mapping.
2. Enter a message key that describes the information you are sending. For example, for Shipping Account, enter Shipping Account.
3. Leave the source type as "Field".
4. For the source field path, select the name of the source field. For example, "Shipping Account".
5. Leave the target type as "Field".
6. For this example, do not select a target child type. The mapping is automatically assigned the Default target child type. More information about target child types is available in a following section.
7. For the target field, select the name of the target field. For example, "Shipping Account".
8. Click Save.

It's possible to create filters that relate to your mappings so that records are only created when specific criteria is met.

You can set filters that apply to the main target object on the subscription or to child relationship mappings. This section provides an example of adding filters to child relationship mappings. For information about how to add a filter to the main target object, see Adding Filters to Subscriptions.

When you specify a child filter key, a child record is only created or updated when the message value for that key is true. For example, if you define a child filter key based on an Active checkbox, records are only created or updated if the checkbox is selected on the source record.

For this example, we want to only create billing document line items if the work order line contains a net value greater than 0. To achieve this, we created a formula field of type checkbox on the Work Order Line called Chargeable Line. The formula for this field is: Net_Value__c > 0.00. This means that when the Net Value field contains a value greater than 0, the Chargeable Line checkbox is selected automatically. The messaging filter can use this information to determine whether to create a billing document line item. If the checkbox is selected, the value "true" is included in the message. If the checkbox is not selected, the value in the message is "false".

Now you can set up a mapping that uses this information to filter child records. In this example, we're going to add the filter to the existing Work Order Lines child relationship.

To update the child relationship mapping:

1. On the relationship, click in the Work Order Lines child relationship row and click Edit.
2. For the child filter field, select "Chargeable Line". You don't need to make any other changes.
3. Click Save.

You'll see that a new Chargeable Line key is automatically created under the Work Order Lines relationship with the specified field as the source. The message needs to include the key for Foundations to use it as a filter.

This key is also optionally available for you to use in a mapping. To do this:

1. On the relationship, click in the Chargeable Line mapping row and click Edit.
2. Specify target details.
3. Click Save.

In some circumstances, you might want to create multiple records for each child source record you receive via messaging.

For example, for each work order line you receive, you want to create:

• A billing document that stores the work order line information, and
• A second billing document line item to represent a fixed fee that is automatically charged to the customer. For each line, you want to include a $20 installation fee.

To achieve this, you can use target child types on child mappings. When you create a child mapping, you have the option to enter a target child type. You can use this to create categories for your child records.

For the example above, we want to set up a new target child type of Admin Fee and always send specific fixed values to the required fields on the billing document line item.

The following table describes the mappings we want to create for the child relationship.

Key: * - Required fields on the target.

For each target field, create a mapping using the Admin Fee target child type:

1. On the relationship, click in the Work Order Lines child relationship row and click Add Child Mapping.
2. Enter a message key that describes the information you are sending. For example, for Product or Service, enter Admin - Product.
3. For the source type, select "Static".
4. For the source description, enter a description of the fixed data you want to send for this key. For example, Installation Fee.
5. For the source data, enter the exact data you want to send. This is the data that you want to store in the target field. For example, Installation.
6. Leave the target type as "Field".
7. Enter the name of the target child type. For example, Admin Fee.
8. For the target field, select the name of the target field. For example, "Product or Service".
9. Click Save. The target child type that you saved is available to select for the other child mappings you create.

For more information and other ways to use target child types, see Splitting Source Data into Multiple Target Records.

If there is information that exists on a source parent record, you can create a mapping directly from that field to a child target field.

For this example, we want to send the company name that is stored on the work order to the billing document line item. To achieve this, we created a text field on the Billing Document Line Item called Company.

To create a mapping from a parent source to a child target field:

1. On the relationship, click in the Work Order Lines child relationship row and click Add Child Mapping.
2. Enter a message key that describes the information you are sending. For example, for Company, enter Parent Company.
3. For the source type, select "Parent Field".
4. For the parent, select the name of the field that you want to send data from. For example, "Company (Work Order)".
5. Leave the target type as "Field".
6. For this example, do not select a target child type. The mapping is automatically assigned the Default target child type.
7. For the target field, select the name of the target field. For example, "Company".
8. Click Save.

In some circumstances, you might send data in your message that is useful for more than one field on the target record. In this example, the document date on the work order can be used to populate both of the following fields on the billing document:

• Document Date
• Document Due Date

In this example, the Document Date field is already specified as the source on the Doc Date mapping. If these fields will always have the same source, you can reduce admin by reusing the Doc Date key and source on a separate mapping.

1. On the relationship, click in the row for the key you want to reuse, such as Doc Date, and click Reuse Key.
2. For the target type, select "Field".
3. For the target field, select the name of the target field. For example, "Document Due Date".
4. Click Save. The mapping is created and the key and source show that they reuse the information from the original mapping.

Editing the source for either mapping updates the source on both mappings.

This option enables you to create a mapping to a lookup where record names are not unique.

For this example, we want to map a field to the Billing Department lookup on the Billing Document object. In our org, the name of the department alone is not unique across all billing department records. The combination of the record name and the company is unique, so can be used to identify a single record.

For more information about advanced lookup mappings, see Creating Mappings to Lookups with Common Record Names.

To create a mapping to a lookup with a common name:

1. On the relationship, click Add Mapping.
2. Enter a message key that describes the information you are sending. For example, for Department, enter Billing Department.
3. Leave the source type as "Field".
4. For the source field path, select the name of the source field. For example, "Department".
5. For the target type, select "Advanced Lookup".
6. For the target lookup, select the name of the target field. For example, "Billing Department".
7. Enter the field that provides the additional identifier for the source object. For this example, select "Company". If a key doesn't already exist for this field, Foundations creates it automatically.
8. Enter the additional identifier for the target record. For this example, select "Company".
9. Click Save.

When you have created mappings, enable the publication and subscription associated with the message type.

For more information, see Enabling and Disabling Publications and Subscriptions.

You can optionally set up return data for your relationships.

Return data helps you to confirm that data has been transferred between your applications.

Return data enables a subscribing application to publish a response when it receives a message from another app. The app that published the original message can subscribe to the delivery response and display the following information on source records:

• A lookup to the linked target record
• A status field to show whether the message delivery was successful
• An errors field to store details of any errors that occurred

Return data can be set up easily from the relationship. Details of a relationship's return data enablement are visible from the Relationship and Mapping Details and the Return Data Details sections of the relationship.

For more information, see Return Data Overview and Enabling Return Data.

Foundations activation methods enable you to quickly and easily define how you want to send messages. You can select from default automated methods, Salesforce flows, or custom code.

For this example, we want to send a message every time a work order record is created or updated and want to use Foundations default actions to achieve this.

To do this:

1. On the relationship, click Manage Activation.
2. Select the Default activation method.
3. Select the Immediate delivery method.
4. Click Save.

For more information about the available activation methods, see Activating a Messaging Relationship.

In this example, we've set messaging up to send data as soon as a record is created or updated so no scheduled job is required. If your delivery method specifies that you want to send messages asynchronously, you can set up a scheduled job to define when messages are sent.

To configure the Message Delivery job to run daily:

1. Click the Foundations Setup tab.
2. Click the Scheduled Jobs subtab.
3. In the Message Delivery row, click .
4. In the Time section, specify the time you want the job to run.
5. In the Day/Date section, select Every Day.
6. In the Month section, select Every Month.
7. In the Year section, select Every Year.
8. Click Apply Changes.
9. Select the Scheduled checkbox for the Message Delivery row.

For more information, see Scheduling Message Delivery.

You can specify the type of messages you want to retain from the Message Logs subtab of the Foundations Setup tab.

When you're setting up and testing messaging initially, we recommend that you set the logging level to All. When your org is fully configured, Errors is sufficient. For more information, see Configuring Message Retention.

You can also view details of the messages you've retained to help you get started. For more information, see Monitoring Message Delivery.