The simplest mapping action is one where data is mapped to/from the API into a single Salesforce object. The main object that you are mapping to is called the 'Base' object. You will see this definition as a 'Base Object Only' configuration.
We will use this sample to introduce the basics of field mapping - and use this as a way to introduce the terms we use in the Nexus tool.
Note: in order to perform the functions in this step you MUST download your connector definition from the Connecter Hub first.
Access the Connector functions by navigating to the Installed Connectors found in the Nexus Admin page. Select the 'View Connector Functions' option from the right-side drop down menu.
You will then see a listing of all of the different endpoints associated with the API. In order to complete the setup - you will have to perform mapping on each of these. These have already been defined for the connector, so in general, you will not want to create or delete a Connector Function unless performing an advanced configuration that we will cover later. You don't have to map every Connector Function if your business use case does not require use of specific endpoints.
Select one of the endpoints to begin performing the mapping function for the data events associated with it. To do this - select the View Data Events from the right hand drop-down menu.
When you select the option to View Data Events, you will typically see 2 Data Events for each Endpoint. This is because a typical API communication involves both an Outbound message (the payload that is sent to the remote system). The response from the remote system is the Inbound message (the payload received in response to the API request). If the API is a one-way API message (typically called a Callback or Webhook), meaning the message is originated in the remote system as an unsolicited message, we will only have one Data Event listed (and this will be an Inbound message). You will need to configure both parts of the message (Inbound and Outbound) in order to complete a standard API call.
Select the desired Data Event by choosing Record Details on the right-hand dropdown menu. We'll start with the Outbound event.
Once you've selected the Data Event, there are 3 tabs that are displayed to enable visibility to all of the different elements of the message. The first tab is the basic header information about the Data Event. Typical information included here is the name of the Data Event, the directionality (Inbound or Outbound), and the type of configuration (Base Object Only). The second tab has a listing of the object(s) that have data elements involved in the Data Event. Typically there is only one object involved - making the listing contain only one object. We will address multiple objects in a later article. The third tab is the one that has fields listed for each data item contained in the endpoint. These fields are the ones that were downloaded when you selected the Connector in the Connector Hub.
The 1st tab is contains the details about this Data Event. You can edit it and add any Notes as desired.
Select the 2nd tab to review what type of API connection is required. For this example - we'll only set up a single object update - which means we will only update Base Object Only. The Base Object is the primary object that data will be moved into. When we look at deploying multiple objects in an update - there will be multiple entries on this screen.
Select the "Create New Data Event Object" button.
Fill in the Base object Name. Use the Salesforce API name. This means that standard Salesforce objects will have the object name. Custom Salesforce objects will have the '__c' suffix. The Data Event Object Label will auto-fill based on the input made in the first 2 fields, but you can name it whatever you choose. This will be the label on the object tab when field mapping, so it is best to keep this as descriptive as possible. Save this record to identify the fields that will be available when you select the 3rd tab on this page.
Note: If you haven't set up a Data Event Object, there will be no data displayed in the 'Fields' tab.
Before we start mapping, there are a few things to consider regarding data models and field types. The API data elements may not exactly match up with what is in Salesforce, so it is very important to have a thorough understanding of both the Salesforce data AND the API definitions. It may be necessary to create additional custom fields on the Salesforce object to be able to map a value so that it conforms with the expected format. An example may be an address in the API is expecting a Street, City, State, Zip in a single line, so a custom formula field would need to be created on the object to format the address fields in that manner. Another example could be enum values in the API may not exactly match to Picklist values in Salesforce, so some translation would need to be made.
You will need to expand the prompt for each field, and provide the mapping between the field identified in the API endpoint, and the field that should be connected to that item in the Salesforce data schema. Click on the Edit button to enable the Salesforce field mapping. You'll be able to select any field (of the appropriate type) to map to the API Field Name. When you download the API definitions from the Connector Hub, the fields are defined with specific data types (e.g. Date, Number, Text). When you select the mapping dropdown, only Salesforce fields that are compatible with the API field's data type will be available for selection (e.g. you can't map a Date field to a Number field). Note: for rapid entry with less scrolling - start at the bottom of the list.
When mapping a single base object, you can still access parent object fields by selecting the lookup field.
A new dropdown with the parent object fields will become available and you can select the desired field from that object.
Once you have made the mapping selection in the dropdown, click Save to save the selection. Repeat this process for each Outbound Data Event Field in the Message. When finished, click the 'Return to List' button in the top right and select the 'Record Details' option for the Inbound Data Event.
As with Outbound events, there may also be mismatches in the data type or format of the response elements from the API in the Inbound events. Sometimes it can be necessary to create custom fields as a landing spot for the data that could be manipulated with a FLOW or Apex Trigger to be able to save it to the Salesforce object. In some cases, it is preferable to create an entire 'Bucket Object' with fields specifically created to match the API output that could then be written to the final desired destination in Salesforce.
Repeat the process of creating a Data Event Object for the Inbound event with the same Salesforce object used for the Outbound event. The Fields tab on the Inbound events has additional configuration features. First off, click 'Edit DML Type' and choose 'Insert' or 'Upsert'. The 'Reference Only' option for advanced mapping that we will explore later in this guide. If the Object has Record Types, then you can 'Edit Record Type' and make that selection as well.
If the DML Type selected is 'Upsert', then there will need to be either the Salesforce Id or an External Id field mapped so the system knows which record to update. How to choose will depend on the details of the API request. For example, in a POST, the response may include a unique id that you would want to save as an External Id. In such cases, there is a pre-built API Field called 'OriginatingRecordId'. This is the Salesforce Id of the record that initiated the callout, so mapping that to 'Id' will tell Nexus which record to update. It is also important to in an Upsert to select the 'Overwrite Existing Salesforce Data' checkbox.
It is possible that there may be fields required on the Salesforce object that are not part of the API Response. In this case you would need to use the 'Create New Data Event Field Map' button. Here you can leave the 'Inbound Field Name' blank but select the 'Salesforce Field API Name' and select the Default Value dropdown. In this dropdown, select the type of data you wish to insert (this selection will be dependent upon the type of data defined for the particular field you are working with). Next, input the default value that will ALWAYS be inserted into this field.
Note: DO NOT select the Default Value Data Type option unless you need to use it as it will cause a conflict with the API value and throw and error.
You can also select settings to insert NULL values, or you can choose to always overwrite data in Salesforce - using the selection boxes on the field data update. As stated above, use the Overwrite checkbox for Upserts to insure the data is written to the Salesforce record.