Overcast Components accessing backend data by reference


View backend data in Salesforce UI without copying

Introduction

In this pattern, you will use multiple Real-time Integration Scenarios to show real-time SAP data related to the record shown in a record detail page. You will use Overcast Components to create a widget view, detail view, and list view of SAP data.
 



This pattern will focus on Overcast Components shown in a Salesforce record detail page, but Overcast Components are not restricted or limited to only record detail page. Overcast Components use Salesforce Lightning Component technology and thus can be used anywhere Lightning Components can.

When to choose

You should choose Overcast Components when

  1. Users need live data / the data changes frequently.

  2. The Salesforce application does not require the data to function.

  3. The data set is too large to synchronize into Salesforce (with this pattern, you only load the specific data that the user needs to see).

  4. Users need access to a process in SAP that should not be or cannot reasonably be replicated into Salesforce (copying data mostly implies copying business logic).

Disadvantages

The disadvantages of this pattern are the following.

  1. Does not integrate SAP data into Salesforce records because it is read-only.

  2. Since no data is stored in Salesforce, it cannot be used in conjunction with Salesforce Reporting and Flows/Workflows.

  3. Does not save data to SAP because it is read-only.

There are other patterns that do not have these disadvantages.

What to avoid

  1. Make sure to remove unused fields or entities/data structures. Larger APIs take longer to process. The larger the API, the larger the component metadata definition, and the longer the load and display time.

  2. Prefer a few smaller, simpler components than one large, complex composite component.

  3. Avoid displaying too much data in one view, or one record. If the user wants more details, allow them to click the record to view the details.

Monitoring & Logging

Overcast Component real-time requests are logged in the Monitoring screen when an error occurs or when the log level is set to debug or greater. Overcast Component real-time requests can be very frequent, so successful requests are not logged to avoid unnecessary logging. Custom logs can be output from Enhancement Points.

Audit logs for all requests to the Overcast Service can be obtained from Vigience.

For development and debugging, the log level for the Real-Time Integration Scenario that backs the Overcast Components can be changed to log request data. This change should not be made in production because of the sheer volume of logging that will result.

Error Handling & Recovery

System errors are logged to the Monitoring screen when a request fails. The failed requests should be retried by the user after the system is restored.

Business errors, like when data is not found or there are bad inputs, are returned to the end user and shown in a toast message to the user. They are not logged to the Monitoring screen.

You can output your own logs using the enhancement point for each component. Your Apex debug logs will available in the Salesforce Developer Console. Read the documentation here to output logs to the Monitoring screen.

Customizations

Customizations to Overcast Components are primarily made in the Component Builder. There we can perform changes to the configuration of the component, like displaying or hiding fields, adding or removing sections, and creating the links between records and input parameters.

To implement advanced transformations on data before displaying it to the user, or customizing the UI at runtime based on data, custom code can be executed by creating a plugin class for each Overcast Component. Read the API documentation here for creating a plugin class.

Advanced Considerations

Multi-language

Components support multiple languages. To display UI text in the user's display language add Salesforce Custom Labels to section and field labels, then add translations to those Custom Labels.

Many of the standard Overcast Components are already multi-language enabled by using Custom Labels. Add translations to those custom labels for the languages you need.

It is recommended to use Custom Labels in the field labels instead of replacing text with translations directly because workforces are diverse and businesses grow, so it becomes more likely that your users will use different display languages.

To retrieve localized response data, when supported by the backend system, per-user authentication should be used so the backend system will use the user's language to retrieve localized texts.

 

Implementation

This section describes the implementation steps for this design pattern.

SAP BAPI Implementation Example

In this example, you will learn how to display SAP invoice data on a Salesforce account record. Initially, it will show a few invoices in the widget, and then show more when the user clicks for more, and display the invoice details when the user clicks an invoice.

This example is described in a step-by-step tutorial here.

This example is a simplified version of the SAP Invoice History Overcast Component and is provided for demonstrating how to create a three-part component with a BAPI. Use the standard SAP Invoice History component from the Component Library for use in production.

SAP Table Implementation Example

In this example, you will learn how to display SAP customer data on a Salesforce account record. Initially, it will show a few fields, then when the user clicks for more details it will show all fields.

 

  1. Create a new Real-Time Integration Scenario. Set the name as SAPCustomersRT and give it a description. Select the SAP Connection String and search for KNA1VV. This will create a single Apex class for the Integration Scenario called SAPCustomerRT.cls.

    1. Select the following fields

      KUNNR

      Customer number

      VKORG

      Sales Org.

      VTWEG

      Distr. Channel

      SPART

      Division

      INCO1

      Incoterms

      INCO2

      Incoterms 2

      STCD1

      Tax Number 1

      STCD2

      Tax Number 2

      STKZA

      Equalization tax

      STKZU

      Liable for VAT

      STCEG

      VAT Reg. No.

    2. Leave all options as default values.

    3. Save & Activate the Integration Scenario.

  2. On the Integration Scenario screen after the activation completed successfully, click Create Component from the Overcast Components section. This is for the summary widget.

    1. Set Label to Customer Summary and Name to CustomerSummary and click Create component.

    2. In the Preview Settings modal

      1. Preview object = Account

      2. For Preview record, search for an existing record.

      3. Preview component type = Widget

    3. Open Parameter Mappings tab.

      1. Click New. Now we link the SAP customer number from the account record to the KUNNR field on KNA1VV.

        1. Parameter = KNA1VV

        2. Field = KUNNR

        3. Reference Type = Reference Field

        4. Reference Value = SAP Account Identifier

    4. Open Sections tab.

      1. Select Query Parameters.

        1. Turn off the Query Parameters section. This removes the filter button, which is next to the refresh button.

        2. Hide all fields except KUNNR.

      2. Select Query Results.

        1. Hide all fields except INCO1 and INCO2.

        2. Set Section Settings.

          1. Remove the Label.

          2. Structure Type = Structure

          3. Section Type = Panel

    5. Click Update Preview. Click the refresh button in the preview to show data from SAP.

    6. Click Save.

  3. Now, for the detail widget, we will clone the summary widget. Click Save as.

    1. Label = Customer Detail

    2. Developer Name = CustomerDetail

  4. Now, we will add all the fields to the CustomerDetail component.

    1. Open the Component tab.

      1. Set Static Label = Customer Detail.

    2. Click Dynamic label options.

      1. Add the following JSON snippet.

        {
    "parameters": [
        "FIELD:KNA1VV.KUNNR"
    ],
    "template": "Customer Detail ({0})"
}
      2. This sets the dynamic label to display the field, Customer Number (KNA1VV.KUNNR), in the label template, Customer Detail (XXXX).
      3. Click Update.

    3. Open the Sections tab, select the output section, No Label (previously Query Results), then the Fields tab, then click Show All.

    4. Click Save.

  5. Open the CustomerSummary component again. We will add a link so the user can navigate to CustomerDetail.

    1. In the Component tab, click Master action link. At the time of writing, a JSON text entry modal appears.

    2. Add the following JSON snippet.

      {
    "action": {
        "component": "DetailViewer",
        "componentDef": "CustomerDetail"
    },
    "label": "View more"
}
    3. This sets the following parameters
      1. Sets the action to open the DetailViewer page with the CustomerDetail component.
      2. Sets the label of the link to View more.
    4. Save the component.
  6. Add CustomerSummary to an Account record page, save, and open a record that has an SAP account number.
    1. The summary should only show Incoterms 1 and Incoterm 2.
    2. There should be a refresh button.
    3. There should be no filter button.
    4. There should be a link at the bottom labeled View more.
    5. Click View more. A new page will open.
    6. All the fields should be displayed.
  7. You have successfully completed the SAP table implementation example.

Enhancement Point

Here we will describe how to create a plugin for the Overcast Components, CustomerSummary & CustomerDetail, from SAP table implementation example.

This sample code will print "No value" for each blank field. It reads the fields from the component so that when a field is added or removed from the component the code does not need to be updated.

  1. Create a class called CustomerComponentPlugin.

  2. Copy the plugin template from here.

  3. Replace afterScenarioCall() from the template with this snippet.

global void afterScenarioCall(
    Map<String, Object> returnedData, 
    overcast.ComponentDefinition.Component cmp, 
    Map<String, Object> settings
) {                
    // Set all blank fields to report the text "No value".
    List<Object> records = (List<Object>)returnedData.get('KNA1VV');
    if (records == null || records.isEmpty()) {
        return;
    }
    // Check if the definition has changed is not what we expect. 
    // You can alternatively throw an exception to alert the tester that 
    // this code needs to be updated too.
    if (cmp.sections == null || cmp.sections.size() < 2 || cmp.sections[1].structureName != 'KNA1VV') {
        return;
    }

    Map<String, Object> record = (Map<String, Object>)records[0];

    // Read the field names from the component. 
    for (overcast.ComponentDefinition.Field field : cmp.sections[1].fields) {
        if (String.isEmpty(String.valueOf(record.get(field.name)))) {
            record.put(field.name, 'No value');
        }
    }
}

 

  1. Open CustomerSummary component in the Component Builder.

  2. Click Component Settings.

    1. Set Apex Plugin Class = CustomerComponentPlugin

    2. Click Save component.

  3. Perform the same step for CustomerDetail.

  4. With both components saved, reload the Account page and review the changes. The plugin will display the text "No value" for blank fields.

Error Handling & Logging

Custom logging can be output from the enhancement point Apex class. The template contains a logger, which we will use.

Add this text at the end of the afterScenarioCall() method to output an INFO level log.

this.logger.addLog(overcast.LogLevel.INFO, 'Added text "No value" to blank fields.');

 

Normally, requests via an Overcast Component do not appear in the Monitoring screen, but this will add a log to the request so an entry will appear in the Monitoring screen.

Advanced Considerations

Multi-language

Follow the steps below Custom Labels to an Overcast Component in the Component Builder for each location.

  1. Dynamic component label. In the SAP table implementation example above, you added a dynamic label. Let's Rreplace the template with a Custom Label.

    1. Create a Custom Label named CustomerComponentTitleTemplate with the text "Customer Detail ({0})".

    2. Add all required translations to the Custom Label.

    3. Update the template with the Custom Label

{
    "parameters": [
        "FIELD:KNA1VV.KUNNR"
    ],
    "template": "$Label.c.CustomerComponentTitleTemplate"
}

 

  1. Static component label. In the SAP table implementation example above, you added a static label for the summary component. Replace the static label with a Custom Label.

    1. Create a Custom Label named CustomerComponentTitle with the text "Customer Summary".

    2. Add all required translations to the Custom Label.

    3. Replace label with $Label.c.CustomerComponentTitle.

  2. Sections and fields. Add Custom Labels to section and field labels in this format $Label.c.LabelName. This is the same method for the static component label.

To retrieve localized response data, when supported by the backend system, per-user authentication should be used so the backend system will use the user's language to retrieve localized texts.