Forem: Salesforce Developers

Creating Custom API Endpoints in Salesforce with Apex

Michael Bogan — Tue, 31 Jan 2023 21:41:53 +0000

Part One: SOAP-based APIs

Simple Object Access Protocol (SOAP) is a messaging protocol based on requests and responses using an XML format. Although some legacy systems still use SOAP over SMTP, the transport method typically used for SOAP requests is HTTP. As an API protocol, SOAP is platform- and language-agnostic, allowing for two applications running on completely different systems to communicate with one another.

This post is part of a two-part series covering how to create custom API endpoints in Salesforce with APEX. In Part One, we’ll walk through how to create a SOAP-based API endpoint for other applications to use when communicating with your Salesforce org.

A Brief Introduction to SOAP

Each SOAP message is contained in an “envelope” which has a header and a body. The header contains application-related information, such as the date when the message was generated or ids related to the message context. The body contains the actual message. Here is an example SOAP message with a format that would be used for authenticating to Salesforce:



<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:enterprise.soap.sforce.com">
   <soapenv:Header>
      <urn:LoginScopeHeader>
         <urn:organizationId>12345</urn:organizationId>
         <urn:portalId>abcde</urn:portalId>
      </urn:LoginScopeHeader>
   </soapenv:Header>
   <soapenv:Body>
      <urn:login>
         <urn:username>johndoe</urn:username>
         <urn:password>mypassword</urn:password>
      </urn:login>
   </soapenv:Body>
</soapenv:Envelope>

Since each message has the same structure, SOAP is system agnostic. For example, an application running on a Windows 11 machine can send a message to another application running on a Unix-based web server.

Though the message can be sent using SMTP or HTTP, SOAP messages should ideally be sent with HTTPS, with either simple or mutual authentication.

SOAP is mostly used to create an API or web service to exchange server-to-server information. Therefore, it is very important for the two systems to establish trust. Salesforce provides multiple ways to accomplish authentication.

The relationship between SOAP and WSDL

Although all SOAP messages have the same structure, the SOAP specification doesn’t define other aspects, such as message format or transport protocol. The Web Services Description Language (WSDL) describes the message formats, transport details, and operations of the web service. The WSDL file can be considered a contract between the client and the service.

How to Create a SOAP-based API in Salesforce

Now that we have covered the fundamentals, let’s begin implementing our SOAP API.

Set up a Salesforce org

First, you need a Salesforce org. Salesforce provides free Developer edition orgs, and signing up for one is straightforward. Go to the sign-up page and provide your details. You should receive an invite link within a few minutes.

Creating a global class with Apex

To create a SOAP web service in Salesforce, we will need to create a globally defined Apex custom class. In our class, we’ll use the webservice keyword and static definition modifier for every method we want to expose. Adding the webservice keyword automatically gives global access to the method it is added to.

In order to create this class in our shiny, new org, we go to Setup, and then find Custom Code -> Apex Classes. In the table listing existing classes, we click New.

To learn more about Apex and how to create classes, check out this Trailhead page and the Apex documentation.

Below, we have a sample ContactAPI class that exposes a createContact method used to create new Contact records in Salesforce. The method accepts a Contact’s details as parameters and inserts a new Contact record.

If successful, it returns the ID of the newly created Contact along with a message. In case of a failure, it returns an error message. Please copy the code and paste it into the newly created empty class.



global class ContactAPI {
  webservice static String createContact (String firstName, String lastName, String contactEmail, String salutation) { 
    try {
      Contact newContact = new Contact();
      newContact.Salutation = salutation;
      newContact.FirstName = firstName;
      newContact.LastName = lastName;
      newContact.Email = contactEmail;

      insert newContact;
      return 'Successfully inserted new Contact! Id:' + String.valueOf(newContact.Id);
    } catch (Exception e) {
      return 'Error:' + e.getMessage();
    }
  }
}

Next, we click Save.

That’s it! Our web service is ready for operations. We have successfully created a SOAP API in Salesforce.

Generate the WSDL

We now need to generate a WSDL file and provide it to the external application or third-party developers which can then consume it to call our createContact method.

Salesforce provides two out-of-the-box WSDL files to integrate client applications with Salesforce:

The Enterprise WSDL is optimized for a single Salesforce org. It’s strongly typed, meaning it contains objects and field definitions for this particular org. Whenever there is a change in the metadata (object and/or fields) in the Salesforce org, a new WSDL needs to be generated and provided to the client (to consume again).
The Partner WSDL is optimized for use with many Salesforce orgs. It’s loosely typed, and it doesn’t change based on an org’s specific configuration.

In order to utilize our web service, we’ll use the WSDL for our Apex class (to actually call our web service), and we’ll use the Enterprise WSDL to authenticate to Salesforce.

After creating our ContactAPI class, we see it show up in the list of Apex classes. In the row for ContactAPI, we click on the WSDL link to generate a WSDL.

This will open a new tab with our WSDL, which will look similar to this:

We save this file to our local machine, naming it contactAPI-wsdl.xml.

To generate the Enterprise WSDL for our Salesforce org, we go to the Setup page, and then find Integrations -> API. Then, we click on Generate Enterprise WSDL.

Your generated WSDL should look similar to this:

We save this file to our local machine, naming it enterprise_wsdl.xml.

To generate the WSDL for your Apex Class:

Go to the Setup page.
Type and select Apex Classes.
Find your class. In our case it’s ContactAPI. Click on the name.
On the next screen you will have the class page where you have the Generate WSDL button.

Test and validate

To ensure that the web service works, we’ll consume it by calling it from our web application and see if it responds correctly. We’ll also cover how to validate our API with unit testing.

Consume the API

For the purpose of this demo, we’ll use SoapUI, which is an open-source tool to test SOAP (and other protocols) web services. With SoapUI installed and running, we create a new SOAP Project, providing a name and selecting our enterprise_wsdl.xml file as the initial WSDL.

We now have all available Salesforce SoapBindings listed on the left.

First, we need to authenticate our web application to Salesforce. We do this by using the login call and providing our login credentials.

Use a security token

For added security, we also need to add a Security Token to our password to authenticate. We can get a security token by going to the Settings page and selecting Reset My Security Token on the left. Then, press the button with the same name. We will then receive our security token by email.

Log in with the token and credentials

With our token in hand, we select the login SoapBinding in SoapUI. Ensure you have the correct URL depending on your org. If you just signed up for a developer account, the URL should be https://login.salesforce.com. If you are testing this in a Sandbox, then the URL should be https://test.salesforce.com. Ideally, the generated Enterprise WSDL will already have the correct URL.

For demo testing, we can comment out all other parameters except username and password.

We press the green Play button on the top left of the window to send the request. We receive a response that looks like this:

The critical pieces that we are looking for in the response are sessionId and serverUrl. In order to call our web service, we need to provide the sessionId together with other parameters in our call. We copy down this sessionId, as we will need this later.

Call our SOAP API

Let’s call our ContactAPI class and create a Contact in Salesforce. To do this, we need to add our ContactAPI WSDL file, contactAPI-wsdl.xml, to our project. We right-click on the project folder and select Add WSDL.

After adding the WSDL, it also appears in the left menu like below. Double-click on Request 1 to see the request. For this example, we can remove everything from the SOAP envelope header except for the SessionHeader with sessionId node.

After removing the unwanted nodes, we provide the sessionId that we copied from our login call earlier. Then, in the Body section of the envelope, we provide the details of the contact to be created.

We press the green Play button on the top left. Vóila! We have successfully created a Contact in Salesforce and received its Id.

Check Salesforce org for new contact

Let’s look inside our Salesforce org to see if everything was created correctly. We go to our Salesforce org, click the App Launcher waffle icon on the left and then type Contact in the search bar to find and select Contacts.

By default, we land on the Contacts page with the Recently Viewed Contacts list view. Click the down arrow and select either All Contacts or My Contacts list view.

Note: If you are in a Developer org, you will see a bunch of dummy Contacts (and other records) that Salesforce creates for you to test the platform.

We type the name of our newly created contact in the list search box on the right, and we see our new contact!

When we click on the Contact name, we end up on the Details page for that Contact.

Call our SOAP API with invalid data

Lastly, in order to ensure that our API is working properly, let’s send a bad request to see what we get as a response. We’ll simply send another request to our SOAP web service, but this time replace the . in the email address with a , instead.

This time, we receive an error message (as we programmed in the API).

The entire error message reads like this:



Error:Insert failed. First exception on row 0; first error: INVALID_EMAIL_ADDRESS, Email: invalid email address: sheila@gmail,com: [Email]

This shows that our SOAP-based API is working as designed. With this foundation, we can build other SOAP-based APIs to create records for different objects.

Unit Testing

Besides consuming our SOAP-based API, another way to validate it works properly is through testing. Test Driven Development (TDD) is at the core of Salesforce development. To ensure stability and reliability of the platform, Salesforce requires your custom code to have a minimum of 75% code coverage via unit tests in order to deploy it to a production environment.

Let’s create some unit tests for our web service.



@isTest
private class TestContactWebService {
  static testMethod void testInsertNewContact() {
    // Create test data for positive test
    String salutation = 'Mr.';
    String firstName = 'Max';
    String lastName = 'Bond';
    String emailAddress = 'm.bond@mi5.gov.uk';

    Test.startTest();
    //Call the method with parameters
    String result = ContactAPI.createContact(firstName, lastName, emailAddress, salutation);
    Test.stopTest();

    Contact newContact = [SELECT FirstName FROM Contact WHERE LastName = 'Bond'];
    System.assertEquals(newContact.FirstName, 'Max', 'Assert Error: Please check the ContactAPI class');
  }

  static testMethod void testInsertNewContactFail() {
    // Create test data for failing test
    String salutation = 'Mr.';
    String firstName = 'Max';
    String lastName = 'Bond';
    // The email address has , instead of .
    String badEmailAddress = 'm.bond@mi5,gov,uk';

    Test.startTest();

    //Call the method with parameters
    String result = ContactAPI.createContact(firstName, lastName, badEmailAddress, salutation);
   Test.stopTest();

   // This should contain the Error substring that we added to the catch block above.
   System.assert(result.contains('Error:'), 'Fail Assert Error: Please check the ContactAPI class');
  }
}

In our unit test, we created two scenarios: a “happy path” that verifies valid inputs result in a newly created Contact record, and a “sad path” where we expect the API to return an error on invalid inputs. Salesforce also provides a Trailhead on unit testing in Apex.

Conclusion

In this post, we only scratched the surface in terms of the capabilities that Salesforce provides when it comes to SOAP. As we saw, the generated Enterprise WSDL makes a long list of SoapBindings available. In addition, we can create our own custom classes and SOAP-based web services.

If you have a (legacy) application that uses SOAP to communicate with other systems, you now have the tools to connect that application to your Salesforce org. With enterprise-level security baked into the platform, you can be sure that your connection is safe and your data is protected.

In Part Two of our series, we’ll cover REST APIs, demonstrating how to use Apex to create a custom REST API endpoint for our Salesforce org.

Salesforce Functions with Heroku Data for Redis

Michael Bogan — Tue, 27 Dec 2022 18:33:06 +0000

Salesforce Functions and Heroku Data Series: Part Two of Three

This article is part two of a three-part series on using Heroku Managed Data products from within a Salesforce Function. In part one, we focused on Salesforce Functions with Heroku Postgres. Here in part two, we’ll explore Salesforce Functions with Heroku Data for Redis. Finally, in part three, we’ll cover Salesforce Functions and Apache Kafka on Heroku.

Introduction to Core Concepts

What is a Salesforce Function?

A Salesforce Function is a custom piece of code used to extend your Salesforce apps or processes. The custom code can leverage the language and libraries you choose while being run in the secure environment of your Salesforce instance.

For example, you could leverage a JavaScript library to calculate and cache a value based on a triggered process within Salesforce. If you are new to Functions in general, check out “Get to Know Salesforce Functions” to learn about what they are and how they work.

What is Heroku Data for Redis?

Heroku Data for Redis is a Redis key-value datastore that is fully managed for you by Heroku. That means that Heroku takes care of things like security, backups, and maintenance. All you need to do is use it. Because Heroku is part of Salesforce, this makes access and security much easier. The Heroku Dev Center documentation is an excellent place to find more details on Heroku Data for Redis.

Examples of Salesforce Functions + Heroku Data for Redis

Redis is commonly used for ephemeral data that you want quick access to. Examples include cached values, a queue of tasks to be performed by workers, session or state data for a process, or users visiting a website. While Redis can persist data to disk, it is primarily used as an “in-memory” datastore. Let’s review several use cases to give you a better idea of how Salesforce Functions and Redis can fit together.

Use Case #1: Store state between function runs

There may be times when a process has multiple stages, with each stage requiring a function run. When the next function runs, you want to capture the state of that function run to be used by the next function that runs.

An example of this might be a price quoting process that requires some backend calculations at each stage. Different people or teams might perform the steps in the process. It’s possible they don’t even all belong within a single Salesforce Org. However, the function that runs at each stage needs to know about the previous outcome.

Use Case #2: Managing a queue for worker processes

This use case is concerned with flexibility around background jobs. Because applications built on Salesforce run on a multitenant architecture, Salesforce places restrictions on CPU and memory usage for applications. Long-running programs are often out of bounds and restricted.

Then how might you run a long or heavy task for your Salesforce Org? The answer is Salesforce Functions. You can wire up your function to gather the information needed and insert it into Redis. Then, your Heroku worker processes can retrieve the information and perform the tasks.

Use Case #3: Cache the results of expensive operations

In this last use case, let’s assume that you have an expensive query or calculation. The result does not change often, but the report that needs the result runs frequently. For example, perhaps we want to match some criteria across a large number of records that seldom change. We can use a Salesforce Function to do the work and Redis to store the result. Subsequent executions of the function can simply grab the cached result.

How do I get started?

To get started, you’ll need to have a few pieces in place—both on the Salesforce Functions side and the Heroku side.

Prerequisites
- Access to Salesforce Functions
- Access to Heroku Data services
Getting started with Salesforce Functions
- Getting Started

Accessing Heroku Data for Redis from a Salesforce Function

Once you have covered the prerequisites and created your project, you can run the following commands to create a Function with Heroku Data for Redis access.

To create the new JavaScript Function, run the following command:

$ sf generate function -n yourfunction -l javascript

That will give you a /functions folder with a Node.js application template.

Connecting to your Redis instance

Your function code can use the dotenv package for specifying the Redis URL as an environment variable and the node-redis package as a Redis client. Connecting to Redis might look something like this:

import "dotenv/config";
import { createClient } from 'redis';

async function redisConnect() {
  const redis = createClient({
    url: process.env.REDIS_URL,
    socket: {
      tls: true,
      rejectUnauthorized: false
    }
  });
  await redis.connect();
  return redis;
}

For local execution, using process.env and dotenv assumes that you have a .env file that specifies your REDIS_URL.

Store data in Redis

The actual body of your Salesforce Function will involve performing some calculations or data fetches, followed by storing the result in Redis. An example may look like this:

export default async function (event, context) {
  const redis = await redisConnect();
  const CACHE_KEY = `my_cache_key`;
  const CACHE_TTL_SECONDS = 86400;

  // Check Redis for cached value
  let cached_value = await redis.get(CACHE_KEY);

  if (cached_value) {
    return { result: cached_value }
  } else {
    // Perform some calculation
    const calculated_value = await perform_long_running_computation();

    // Store in Redis
    redis.set(CACHE_KEY, calculated_value, {
      EX: CACHE_TTL_SECONDS,
      NX: true
    });
    // Return result
    return { result: calculated_value }
  }
}

Test your Salesforce Function locally

To test your Function locally, you first run the following command:

$ sf run function start

Then, you can invoke the Function with a payload from another terminal:

$ sf run function -l http://localhost:8080 -p '{"payloadID": "info"}'

For more information on running Functions locally, see this guide.

Associate your Salesforce Function and your Heroku environment

After verifying locally that our Function runs as expected, we can associate our Saleseforce Function with a compute environment. (See this documentation for more information about how to create a compute environment and deploy a function.)

Now, associate your functions and Heroku environments by adding your Heroku user as a collaborator to your function’s compute environment:

$ sf env compute collaborator add --heroku-user username@example.com

The environments can now share Heroku data. Next, you will need the name of the compute environment so that you can attach the datastore to it.

$ sf env list

Lastly, attach the datastore.

$ heroku addons:attach <your-heroku-redis> --app <your-compute-environment-name>

Here are some additional resources that may be helpful for you as you begin implementing your Salesforce Function and accessing Heroku Data for Redis:

Conclusion

And just like that, you’re up and running with a Salesforce Function connecting to Heroku Data for Redis!

Salesforce Functions give you the flexibility and freedom to work within your Salesforce application to access Heroku data—whether that data is in Postgres, Redis, or even Kafka. In this second part of our series, we’ve touched on using Salesforce Functions to work with Heroku Data for Redis. While this is a fairly high-level overview, you should be able to see the potential of combining these two features. In the final post for this series, we’ll integrate with Apache Kafka on Heroku.

Salesforce Functions with Heroku Postgres

Michael Bogan — Mon, 19 Dec 2022 15:16:06 +0000

Salesforce Functions and Heroku Data Series: Part One of Three

This article is the first of a three-part series on utilizing Heroku Managed Data products from within a Salesforce Function. In this article, we will focus on use cases for Heroku Postgres. In parts two and three, we’ll discuss creating Salesforce Functions that use Heroku Data for Redis and Apache Kafka on Heroku.

Introduction to Core Concepts

What is a Salesforce Function?

A Salesforce Function is a custom piece of code used to extend your Salesforce apps or processes. The custom code can leverage the language and libraries you choose while running in the secure environment of your Salesforce instance.

For example, you could leverage a JavaScript library to update your Heroku Postgres Database based on a triggered process within Salesforce. If you are new to Salesforce Functions in general, “Get to Know Salesforce Functions” is a good place to learn more about what a Salesforce Function is and how it works.

What is Heroku Postgres?

Heroku Postgres is a Postgres database that Heroku manages for you. That means that Heroku takes care of things like security, backups, and maintenance. All you have to do is use it. The best place to learn the details of Heroku Postgres is in the Heroku Devcenter documentation.

Examples of Salesforce Function + Heroku Postgres

Now that we know more about Functions and Heroku Postgres, what can we do with them together? There are several ways to think of Functions, but one of the most useful is to think about them as aiding integration or extension of your Org(s). For example, when something happens in Salesforce, do some other task.

At a high level, you would want to use Heroku Postgres with your Salesforce Function if you:

Need to access a relational database as part of your function’s operation
Need to integrate with a Heroku Postgres instance that is part of another system
Need to offload a “heavy” task from your Salesforce Org and store relational data to achieve it

The above patterns are not the only ones, but they are perhaps the most common. The use cases below are examples of these patterns in action.

Use Case #1: De-dupe account records for multiple Salesforce Orgs

A common problem in a growing company is having multiple Salesforce Orgs with customers duplicated across them. Sometimes, this occurs because the company has acquired another company, and both companies share the customer.

In other cases, the company just had different business lines, and the customer was part of both. In reality, if we know two customers are really the same customer, then we want to treat them as one customer. It often takes a long time (if ever) to merge this Org data, so what do we do?

One approach is to sync account information from both Orgs via Heroku Connect into Heroku Postgres, and trigger a Salesforce Function that can look for duplicates. We may run this function on demand for certain activities or set it up to run after creating new accounts. An example of this is whenever the system encounters “Customer’s email already exists in [Parent Company]”. The following diagram illustrates this use case:

Use Case #2: Update customer-facing website when new inventory is added

Many companies use Salesforce as the “source of truth” for critical information, but they have a customer-facing website on Heroku. In this use case, when an item (such as an inventory number) is updated in Salesforce, a Salesforce Function is triggered to update Heroku Postgres, which backs the website that displays this information for customers.

This pattern could be extended to do other things, such as fetch additional information to store with the record in Heroku Postgres or purge the cache. This can be useful when the information is needed for the website, but you don’t need to store it in Salesforce.

Use Case #3: Generate reports for large data sets

In a large organization that uses Salesforce heavily, there can be overlapping tasks by many users. Often, end users are unaware of their impact on the shared system. Moving heavy operations or reports off the Org can allow other operations to perform better. An easy way to do this is to sync the required data to Heroku Postgres via Heroku Connect and perform the operation via a Salesforce Function. This opens up options for optimizing and leveraging open source tools and libraries to process the data.

This pattern also works well if the result needs to be written back to Salesforce. An example of that would be if you needed to calculate sales territories but store the results back in the Salesforce Org.

Salesforce Functions are a powerful new feature in the Salesforce ecosystem. Heroku Postgres is a battle-tested market leader in managed Postgres. Together, they open up many use cases. In combination with additional services offered by Heroku, there are many options for getting the most out of your Salesforce data. In the next section, we’ll briefly examine how to get started with your own use cases.

How do I get started?

There are some things you will need—some on the Salesforce Functions side and some on the Heroku side. These resources will point you in the right direction.

Prerequisites
- Access to Salesforce Functions
- Access to Heroku Data services
Getting started with Salesforce Functions
- Getting Started

Accessing Heroku Postgres from a Salesforce Function

Once you have covered the prerequisites and you create your project, you can run the following commands to create a Function with Heroku Postgres access.

To create the new JavaScript Function, run the following command:

$ sf generate function -n yourfunction -l javascript

That will give you a /functions folder with a Node.js application template.

Connecting to your database

Of course, your Salesforce function code will need to include some specific pieces to ensure a proper connection to the database. The simplest approach would be to include dotenv package for specifying the database URL as an environment variable and the pg package as a Postgres client.

import "dotenv/config";
import pg from "pg";
const { Client } = pg;

Within your function code, you’ll need to connect to your Postgres database. Here is an example of a connection helper function:

async function pgConnect() {
  const client = new Client({
    connectionString: process.env.DATABASE_URL,
    ssl: {
      rejectUnauthorized: false
    }
  });
  await client.connect();
  return client;
}

This assumes that you have a .env file that specifies your DATABASE_URL.

Query and store

In the following example function, we retrieve some data from our Salesforce Org, and then we store it in Postgres.

export default async function (event, context, logger) {
  // Send request to Salesforce data API to retrieve data
  const sfid = await context.org.dataApi.query(
    `SELECT Id FROM Account WHERE Name = 'Example Company'`
  );

  // Connect to postgres
  const pg = await pgConnect();

  // Store data result in postgres
  client.query(`INSERT INTO companies (sfid) VALUES ($1)`, [sfid]);

  // Close connection
  pg.end()
}

Test your Salesforce Function locally

To test your Function locally, you first run the following command:

$ sf run function start

Then, you can invoke the Function with a payload from another terminal:

$ sf run function -l http://localhost:8080 -p '{"payloadID": "info"}'

For more information on running Functions locally, see this guide.

Associating your Salesforce Function and your Heroku environment

Now that everything is working as expected, let's associate the Function with a compute environment. (For more information about how to create a compute environment and deploy a function, take a look at the documentation.)

You can associate your Salesforce Function and Heroku environments by adding your Heroku user as a collaborator to your function’s compute environment:

$ sf env compute collaborator add --heroku-user username@example.com

The environments can now share Heroku data.

Next, you will need the name of the compute environment so that you can attach the datastore to it.

$ sf env list

Lastly, you can attach the datastore.

$ heroku addons:attach <your-heroku-postgres-database> --app <your-compute-environment-name>

Here are some additional resources that may be helpful for you as you begin implementing your Salesforce Function and accessing Heroku Postgres:

Now, you’re off to the races!

Conclusion

Salesforce Functions open up many possibilities for working within your Salesforce app to access and manipulate Heroku data. In this first part of our series, we’ve touched on using Salesforce Functions to work with Heroku Postgres. In our next part of the series, we’ll integrate Salesforce Functions with Heroku Data for Redis. Then, in our final post for this series, we’ll integrate with Apache Kafka on Heroku. Stay tuned!

Light DOM and Lightning Web Components in Salesforce

Michael Bogan — Mon, 12 Dec 2022 17:59:17 +0000

Lightning Web Components (LWC) from Salesforce are based on standard Web Components built using HTML and JavaScript. They are lightweight, easy to build, and perform well in modern browsers. When building LWCs, you’ll become familiar with the concept of composition: piecing together simple building-block components within the body of a more complex component.

Regarding composition, LWC leverages the Shadow Document Object Model (DOM) web standard, which encapsulates the internal structure of a Web Component and makes it inaccessible to code and components outside of the component. The alternative to this approach is Light DOM, which Salesforce makes available in beta.

In this post, we’ll explore in detail the concept of Light DOM in Salesforce development. We’ll begin with an overview of the DOM concept, followed by the differences between Shadow DOM and Light DOM. Finally, we’ll look at how this plays out in LWC, along with how to implement Light DOM in LWC.

What is the DOM?

Taking the definition from MDN, the DOM is “the data representation of the objects that comprise the structure and content of a document on the web.” That means: The DOM provides a way to represent a web page in a tree-like structure as nodes and objects. This makes it easier for developers to manipulate and build out any logic as required.

Image Source

It’s important to note that the DOM is independent of any programming language. A web application built using any language or framework would typically provide access to the DOM and its components in one way or another.

The Shadow DOM

Perhaps you’ve come across the “Shadow DOM”, which is basically an extension of the DOM that allows hidden DOM trees to be attached as elements in the regular DOM tree. MDN uses this graphic to represent the Shadow DOM:

Image Source

The intent of the Shadow DOM is to provide encapsulation for an individual component in the DOM, keeping the markup structure, style, and behavior of that component hidden and separate from other code on the page. Developers can share that component as a full DOM tree (“shadow tree”), ensuring that no outside code can manipulate that tree. This helps keep the code well segregated and avoids clashing.

Light DOM versus Shadow DOM

The term “Light DOM” is just another name used for the normal or regular DOM, to distinguish it from the Shadow DOM. The “Shadow Boundary” separates the Light DOM from the Shadow DOM. LWC, just like any Web Component, enforces the Shadow DOM on every component. By using the Light DOM approach, which is currently a feature in beta Service and generally available only for Salesforce Experience Builder sites, components are attached to the host element instead of its shadow tree.

Let’s look at what this means in greater detail.

Shadow DOM in LWC

Because the Shadow DOM web standard is not implemented in all browsers that Salesforce supports, LWC uses a Shadow DOM polyfill named Synthetic Shadow DOM. The following markup shows a sample shadow tree structure:



<c-my-app>
  #shadow-root
    <div>
        <p>My Tasks</p>
    </div>
    <c-my-item>
      #shadow-root
        <div>
            <p>Item 1</p>
        </div>
    </c-my-item>
</c-my-app>

Shadow DOM prevents us from extracting DOM elements by using references to document or document.body. Instead, an LWC component needs to access the tree by using this.template.querySelector().

CSS is also affected by Shadow DOM encapsulation. Style from outside of the component can only affect the top level of the component and cannot affect parent, child, or sibling CSS.

The LWC architecture leverages Lightning Locker Service to enforce DOM access containment. Components are segregated from one another by using namespaces, and each component can only traverse its DOM and access elements in the same namespace. This is a significant limitation (albeit intentional), making the component inaccessible to programmatic code. This measure prevents script injections and style leaks. Light DOM allows developers to circumvent this security restriction.

Light DOM in LWC

To lift DOM access restrictions imposed by the Shadow DOM, Salesforce has introduced the concept of working with Light DOM in LWC. Even though the feature is currently in beta, it’s clearly the way forward for DOM manipulation for LWCs.

The idea is this: Since the LWC resides outside the Shadow DOM, none of the Shadow DOM limitations apply to the component.

Below is a brief comparison of how Shadow DOM and Light DOM impact an LWC.

Feature	Light DOM	Shadow DOM
Global CSS Theming with a master style sheet	Full Support	No Support, CSS is defined at component level and does not cascade.
Third-Party Tools	Full Support for DOM traversal	Limited support as third-party tools can only access their parent component.
Programmatic DOM Access	Not limited by namespace	Limited by namespace
Portability	Portable but cause breaking changes	Portable with secure access
Highly Customizable UI	Good fit	Not a good fit

Light DOM in LWC: An Example

Let’s look at a simple example of how Light DOM works with an LWC component. This is a simple template directive for a MyApp LWC that uses the Shadow DOM by default.



<template>
    <my-header>
        <p>My Tasks</p>
    </my-header>
</template>

To enable light DOM, we simply need to set the renderMode property as follows:



import { LightningElement } from 'lwc';

export default class MyApp extends LightningElement {
    static renderMode = 'light';
}

Next, we change our template directive to use Light DOM instead of Shadow DOM:



<template lwc:render-mode='light'>

    <my-header>

        <p>My Tasks</p>

    </my-header>

</template>

Accessing Elements using Light DOM in LWC

Elements can be accessed in Light DOM using the document.querySelector() method. This is a powerful way for developers to access and manipulate elements as needed.

In Light DOM, we would use this.querySelector. In Shadow DOM, we would need to use this.template.QuerySelector.

Event Propagation using Light DOM in LWC

When it comes to event propagation, Light DOM is a big uplift for developers. Shadow DOM retargets any events which cross the shadow boundary. There is no such event retargeting in Light DOM, and it’s easy for developers to identify the exact UI element that triggered an event instead of getting a reference to the underlying component.

Guidelines for using Light DOM in LWC

Salesforce has provided a set of guidelines and limitations for developers using Light DOM, which you can find here.

Conclusion

LWC provides a simple and powerful approach to crafting complex web components. Up to this point, while Salesforce has used the Shadow DOM standard in LWC for the purposes of encapsulation and secure access, developers may encounter many scenarios in which the Light DOM approach is fitting and appropriate. With Light DOM now offered in beta, Salesforce developers can now make the choice for themselves based on their use case.

Scaling Your Compute Resources on Salesforce

Michael Bogan — Mon, 05 Dec 2022 13:43:21 +0000

The Salesforce development platform offers many powerful features to provide your team with apps that can unlock new workflows. For many years, the platform has run on a trifecta of technologies: Visualforce (to view the data), Apex (to handle the data), and Salesforce itself (to store the data).

Apex is like many other object-oriented languages, and it has a Java-like syntax. However, Apex runs directly on Salesforce servers, allowing developers to build and deploy an app without worrying about where to host it or how to secure their data.

The challenge of Apex and long-running commands

Applications built on Salesforce run on its multitenant architecture, so server resources like CPU and memory are shared among different organizations. With shared resources, however, wouldn’t it be possible for the code for one org’s app to consume so much processor time and memory space that it affects other users in that same org? An example of this could be a command that takes several minutes to complete.

Salesforce prevents situations like this from occurring by restricting how apps on its platform run. If any app has the potential to interfere with other users, it is restricted from completing its command execution. Long-running programs can potentially interrupt other work by hogging the limited resources available.

If so, how might Salesforce developers build apps that execute long-running commands which can scale with user growth while not impacting performance?

Salesforce Functions to the rescue

Enter Salesforce Functions, which are small programs written in JavaScript, TypeScript, or Java and deployed onto Salesforce’s servers. Functions can perform the resource-intensive work and be invoked directly from Apex. When the Salesforce Function completes the request, it can send its results back to the originating Apex application, which then performs any additional tasks on those results.

Salesforce Functions run in their own container and don’t affect other tenants on the Salesforce platform. The memory and CPU limits are much higher, allowing you to execute longer running and more complex tasks. Because Salesforce Functions run on the Salesforce platform, security is baked in; there’s no risk of privacy loss as everything runs within the same trust boundary.

In this article, we’ll take a closer look at how to migrate a long-running Apex operation into a Salesforce Function, along with some general tips around the Salesforce DX suite.

Prerequisites

This article will require you to have some understanding of both Apex and TypeScript, but don’t worry if you’re not an expert. We’ll go through every piece of code to explain what is happening.

Although the completed version of our code is available as a GitHub repository, you may also want to download some of the CLI tools which Salesforce provides to follow along (or for your own future projects).

First, install the sfdx CLI, which is a tool that helps simplify common operations for Salesforce developers when building applications.
It’s important that whatever you build and deploy doesn’t affect your “real” production Salesforce organization. So, create a separate scratch org that this app can interact with. To get your own scratch org, sign up for a free Developer Edition account.
To use Salesforce Functions, you’ll need to register for a Salesforce Functions trial by contacting your Salesforce account executive.
Finally, you can also install the Salesforce VS Code extension to make deploying your code a little bit easier. This step is optional.

Touring the existing code

Open up the file at force-app/main/default/classes/Dogshow.cls and take a look at its contents:

public class Dogshow {
   public static void updateAccounts() {
       // Get the 5 oldest accounts
       Account[] accounts = [SELECT Id, Description FROM Account ORDER BY CreatedDate ASC LIMIT 5];

       // Set HTTP request
       HttpRequest req = new HttpRequest();
       req.setEndpoint('https://dog.ceo/api/breeds/image/random');
       req.setMethod('GET');

       // Create a new HTTP object to send the request object
       Http http = new Http();
       HTTPResponse res = http.send(req);

       String body = res.getBody();

       Map<String, String> m = (Map<String, String>) JSON.deserialize(jsonStr, Map<String, String>.class);
       String dogUrl = m.get('message');

       // loop through accounts and update the Description field
       for (Account acct : oldAccounts) {
           acct.Description += ' And their favorite dog can be found at ' + dogUrl;
       }

       // save the change you made
       update accounts;
     }
}

These 30 lines perform a fairly simple function:

It grabs the five oldest Salesforce accounts using SOQL.
It issues an HTTP request to https://dog.ceo/dog-api/, which is a site that returns a JSON object with a random URL link to a very cute dog.
The Apex code then updates the description for those five accounts to indicate that that dog is their favorite.

This code is fairly innocuous, but it introduces two situations that present some real problems:

When issuing an HTTP request, several factors can affect your program. For example, the server you issue requests to could be overloaded and slow to respond. While your own code may be performant, you’re at the mercy of anything outside of your control, such as an external data source.
Although we only iterate on five accounts here, what if we built an app that needed to iterate over 500 or 5,000? Looping through them one by one would be a slow, albeit unavoidable, process.

This is an opportunity for a Salesforce Function to take over some of this work. Our Apex class can provide a list of accounts to update to a Salesforce Function. That Salesforce Function can then issue HTTP requests and update the accounts.

Before seeing what that full migration might look like, let’s first write that Salesforce Function.

Developing the Salesforce Function

Using the sfdx CLI, we can easily create a new Salesforce Function in TypeScript using a single command:

$ sf generate function -n dogshowfunction -l typescript

This creates a set of files under functions/dogshowfunction. The most important of these is index.ts, which is where our main Salesforce Function code will reside. However, the other files are also important, dealing with testing and linting code, as well as defining TypeScript generation and the Salesforce deployment process.

Let’s focus on index.ts. In this file, you’ll note that there’s one function exported, and it takes three parameters:

event: This describes the payload of data that is coming in from your Apex code.
context: This contains the authorization logic necessary to communicate with Salesforce.
logger: This is a simple logger that also integrates with Salesforce.

The template code which the CLI generates shows how powerful Salesforce Functions are:

They can accept any JSON data sent over from Apex.
They can work directly with Salesforce data.
They integrate directly with the platform in such a way as to handle all the authentication and security for you.

Best of all, since this particular function runs on Node.js, you can install and use any NPM package to supplement your code. Let’s do that right now by installing node-fetch to issue our HTTP request:

$ npm i node-fetch

Our Salesforce Function will be responsible for issuing our HTTP requests and updating our five accounts. To implement that functionality, our function might look something like this:

export default async function execute(event: InvocationEvent<any>, context: Context, logger: Logger): Promise<RecordQueryResult> {
   const accounts = event.data.accounts;

   accounts.forEach(async (account) => {
       const response = await fetch('https://dog.ceo/api/breeds/image/random');
       const data = await response.json();
       const message = ` And their favorite dog is ${data.message}`

       const recordForUpdate = {
           type: 'Account',
           fields: {
             id: account.id,
             Description: `${account.Description} ${message}`
           }
         }
       context.org.dataApi.updateRecord(recordForUpdate);
   });
}

Let’s break down what’s going on in the code snippet above.

Our event argument is essentially a JSON object which we will define in our Apex code. Although this JSON object doesn’t exist yet, we can assume that it will have the id and Description of the account we want to update, based on the behavior of our previous Apex code.

From here, it’s important to note that the context argument is essentially an instantiation of the Node.js SDK for Salesforce Functions. Since we can assume that this account data is provided as an array, we can simply iterate through each item, plugging in the record data as part of our update command.

Migrate the Apex Code

With our Salesforce Function defined, we can now replace the previous Apex logic with a call to this new function. Issuing a call to a Salesforce Function is surprisingly simple: We only need to know the name of our function and provide the data we want to send it, as shown below:

public class Dogshow {
   public static void updateAccounts() {
       // Get the 5 oldest accounts
       Account[] accounts = [SELECT Id, Description FROM Account ORDER BY CreatedDate ASC LIMIT 5];

       // Set up the function
       functions.Function dogshowFunction = functions.Function.get('ApexToSalesforceFunctionsMigration.dogshowfunction');

       // Create a list to hold the record data
       List<Map<String, String>> jsonObj = new List<Map<String, String>>();
       for (Account account : accounts) {
           Map<String, Object> obj = new Map<String, Object>();

           obj.put('id', account.Id);
           obj.put('Description', account.Description);

           // Add an object to the record list
           jsonObj.add(obj);
       }
       // Send the record list to the function
       functions.FunctionInvocation invocation = dogshowFunction.invoke(JSON.Serialize(jsonObj));

       // if the function had a return value, it would be available here
       invocation.getResponse();
     }
}

Just like that, we’ve taken the long-running operation out of our Apex code and offloaded it to a Salesforce Function. Now, we can be certain that our operation will continue to run even though it uses resources more heavily.

The implications of Salesforce Functions cannot be overstated. With Salesforce Functions handling our need for time-consuming, resource-heavy operations, apps built on the Salesforce platform now have much more potential for scaling up seamlessly.

Conclusion

Salesforce Functions provide a way to improve workflows while building effective and durable projects. Without the memory and CPU limits you would experience in Apex, you can leverage Salesforce Functions for the execution of long-running commands, bringing scalability without a negative impact on performance.

We’ve only begun to discuss the amazing capabilities provided by Salesforce Functions. To learn more about them, Salesforce Functions provides plenty of guides detailing specific tasks, along with various Trailhead recipes that are worth looking into.

Salesforce Functions for Caching Expensive Queries

Michael Bogan — Mon, 14 Nov 2022 13:40:02 +0000

Caching is a strategy that can help you conserve resources and improve performance. When you have an oft-run expensive query with a result that seldom changes, caching is an ideal solution. By caching the result of that query, you can return the cached result when necessary. The result is the same, but you save the need to run the expensive query. Everybody wins.

In this article, we will walk through the use of Salesforce Functions to cache expensive queries. For instance, we want to query for some value across a large number of records, and the page requiring this query is often loaded. However, the result will not change from one query execution to the next.

Introduction to the Problem

In our demo, the example query will be “the number of companies with more than 10,000 employees.” We imagine a use case in which there’s a page that our sales team loads often, and part of the page shows the total number of companies in our Salesforce org that match this condition. Ideally, the expensive query is not run every time the page loads, but instead we would implement a caching mechanism.

To solve this, we will:

Leverage Heroku Connect to sync our list of companies from Salesforce to Heroku Postgres (or use a table already in Postgres).
Create a Salesforce Function to query Postgres and return that count.
Store the resulting value in Heroku Redis for a specified amount of time.
Use a Salesforce Function to check for the value in Redis. If the value exists in Redis, then return it. If not, then run the query and store the result in Redis.

The data flow looks like this:

Of course, Apex does have a Platform Cache API for facilitating caching for certain use cases. For our use case—and for demo purposes—we’ll explore this caching solution that uses Salesforce Functions.

Before we proceed, let’s briefly introduce each of the pieces in our system.

Salesforce Function: A feature of Salesforce that allows you to run some code (JavaScript or Java are currently the supported languages) that is still in the secure area of your Salesforce org, but is not running on your org. This allows you to offload workloads that are heavy or may cause you to exceed limits.
Heroku Connect: A tool within the Salesforce family for bidirectional data syncing between your Salesforce org and Heroku Postgres. Similar to Salesforce Functions, you can leverage this tool without impacting your Salesforce limits.
Heroku Postgres: A fully managed instance of PostgreSQL (a relational database) on Heroku.
Heroku Redis: A fully managed instance of Redis (an in-memory key-value store) on Heroku.

Prerequisites

To use all of the above components, you must have the following pieces in place:

A Heroku account
A Heroku app created, with Postgres and Redis add-ons attached
A Salesforce org with Functions enabled
A local Salesforce Functions development environment
[Optional] Heroku Connect syncing to Postgres (a sample dataset is provided)

With the prerequisites in place, we can start connecting them. First, we’ll walk through connecting the environments. Then, we’ll look at the code needed to make the magic happen.

Accessing Heroku Data Services from a Salesforce Function

With your accounts and access in place, we can move forward with the Function itself. Let’s assume that you are starting a fresh project and have an empty Postgres database.

If you are new to Functions, then we recommend going through this basic process to get a feel for things before you involve additional parts. If you already have a Salesforce project or are syncing the data via Heroku Connect, then you can modify the following commands to suit your needs.

First, create a Salesforce DX project to give your function a home.

sfdx force:project:create -n MyDataProj

Next, navigate to the project directory and run the following command to create a fresh JavaScript function.

sf generate function -n yourfunction -l javascript

This will create a /functions folder with a Node.js application template.

Next, associate your Salesforce Function and your Heroku environments by adding your Heroku user as a collaborator to your Function’s compute environment:

sf env compute collaborator add --heroku-user <yourherokuaccount@email.com>

The environments can now share Heroku data services.

Next, you will need to obtain the name of the compute environment so that you can attach the datastores to it.

sf env list

To attach the Heroku datastores, you also need the names of the add-ons. You can get the name of the add-ons with the following command:

heroku addons -a <yourherokuapp>

The output will look similar to the following. The “name” of each add-on is shown in purple (for example, postgresql-closed-46065).

With the names of the compute environment and your add-ons, run the following commands to attach Postgres and Redis to your compute environment:

heroku addons:attach <your-heroku-postgres-name> --app <your-compute-environment-name>

heroku addons:attach <your-heroku-redis-name> --app <your-compute-environment-name>

Now that we have connected our Salesforce Function environment with our Heroku datastores, we can write our Salesforce Function code.

Implementing the Salesforce Function

Before we begin writing the JavaScript for this Salesforce Function, let's set up our local development environment with the necessary libraries. In the deployed environment, our Function will get the data connection information from environment variables. For our local environment, we will use the dotenv node package to read a file named .env with this information. We can create that file with the following command:

heroku config -a <yourherokuapp> --shell > .env

Next, let’s install the packages we need to interact with Postgres and Redis, along with dotenv:

npm install dotenv pg redis

Our project setup is done. Let’s write our function code.

Connect to Heroku Postgres and Redis

Let’s start by adding the code that allows us to read and store data in Heroku Postgres and Heroku Redis. (Note: The Heroku Devcenter has some helpful documentation on connecting to Postgres and Redis from Node.js.)

Our function code will live in the index.js file of the functions folder in our project (for example, MyDataProj/functions/index.js). We open that file and add the following lines to the top. These lines will import the modules we just installed.

import "dotenv/config";
import pg from "pg";
const { Client } = pg;
import { createClient } from 'redis';

The main part of the function is the section that is being exported. The value returned from this block will be returned to the caller of the function.

export default async function (event, context, logger) {

}

To keep our code clean and modular, let’s first write several helper functions at the bottom of the file. We need functions that we can call to manage our connection to Postgres and Redis. Under (and outside of) the exported function, we add the following two helper functions:

/* Helper functions */

// Connect to PostgreSQL
async function pgConnect() {
   const DATABASE_URL = process.env.DATABASE_URL;
   if (!DATABASE_URL) {
     throw new Error("DATABASE_URL is not set");
   }
    const client = new Client({
     connectionString: DATABASE_URL,
     ssl: {
       rejectUnauthorized: false
     }
   });
    await client.connect();
   return client;
 }

// Connect to Redis
async function redisConnect() {
   const REDIS_URL = process.env.REDIS_URL;
   if (!REDIS_URL) {
     throw new Error("REDIS_URL is not set");
   }
    const redis = createClient({
       url: process.env.REDIS_URL,
       socket: {
           tls: true,
           rejectUnauthorized: false
       }
       });
    await redis.connect();
   redis.on('error', err => {
       console.log('Error ' + err);
   });
   return redis;
 }

Load in a sample dataset

To keep our example simple, let’s load a small dataset into Postgres. We can create a table called “company” by running the database commands found in the following gist. Download the contents of that gist to a file called company.sql. To run the database commands from the Heroku CLI, do the following:

heroku pg:psql -a <yourherokuapp>

DATABASE=> \i /path/to/company.sql

You can verify that your sample dataset has been loaded by running the following query:

DATABASE=> select * from company;

Write the main function

We’re all set up! Now, we just have a little bit of code to write for our actual function. The code for our function is available as a gist and looks like this. You can copy this into your index.js file. We’ll step through and explain each section of the code.

export default async function (event, context, logger) {
   logger.info(`Invoking Datafunction with payload ${JSON.stringify(event.data || {})}`);

   const redis = await redisConnect();
   let cached = {};

   // Check Redis for cached entry first
   let big_biz_count = await redis.get(`big_biz`);

    if (big_biz_count) {
       // If cached entry found, return it and be done.
       logger.info(`Found cache entry = ${big_biz_count}`);
       cached = "true"
       redis.quit();

       return { big_biz_count, cached }
   }  else {
      // If cached entry not found, then:
      // 1. Run the Postgres query
      // 2. Store the result in Redis
      // 3. Return the result and be done
       logger.info(`did not find in cache, returned ${big_biz_count}`);
       cached = "false"
       const pg = await pgConnect();
       const { rows } = await pg.query('SELECT COUNT(*) FROM company WHERE employees>10000;');
       big_biz_count = rows[0].count.toString();

       redis.set(`big_biz`, big_biz_count, {
         EX: 30, // seconds to keep before expiring
         NX: true
       });

       // Close the connections   
       redis.quit();
       pg.end();

       // Return the value from Postgres, now stored in Redis
       return { big_biz_count, cached }
   }
}

An explanation of the code

As mentioned at the beginning of this article, we want to find out how many companies have more than 10,000 employees and return that number. We want to cache the number because it is an “expensive query”. In our example, the table is small, so it is not that expensive. However, it represents an “expensive query” that we may want to run in real life. You get the idea.

Let’s walk through the main sections of our function code.

1) Connect to Redis and see if the value is there.

  const redis = await redisConnect();
  let cached = {};
  let big_biz_count = await redis.get(`big_biz`);

2) If the value is there, meaning it has been cached, then we can return the cached value and be done.

  if (big_biz_count) {
    cached = "true"
    redis.quit();
    return { big_biz_count, cached }

3) If no cached value was found, then we have no choice but to run the query on our Postgres database.

  }  else {
    cached = "false"
    const pg = await pgConnect();
    const { rows } = await pg.query('SELECT COUNT(*) FROM company WHERE employees>10000;');
    big_biz_count = rows[0].count.toString();

4) Then, we store the value returned from our query in Redis.

    redis.set(`big_biz`, big_biz_count, {
      EX: 30, // seconds to keep before expiring
      NX: true
    });

5) Finally, we close our datastore connections, and we return the query result.

    redis.quit();
    pg.end();
    return { big_biz_count, cached }

You might prefer to refactor the code a little bit or add some error handling. However, at this most basic level, that’s all there is to it.

Test the function

Now that we have a Salesforce Function, we can test it locally. First, we start up the function server.

sf run function start

Then, we invoke the Function with a payload from another terminal.

sf run function -l http://localhost:8080 -p '{"payloadID": "info"}'

When you invoke the function against the test database for the first time, you should see the following output because there was no value in the cache:

After this first run, however, the value is stored in our Heroku Redis instance. A subsequent run of the Salesforce Function returns the same value, but this time, cached is true.

When we added the value to Redis, we set the cache expiration to 10 seconds. This makes it easier to test. However, in a real-world environment, the lifespan of your cache values should make sense for your business use case. For example, if the result changes after a nightly run of a report, then you could set the cache value to expire every 24 hours. Better yet, you can create another Salesforce Function that updates the cache with the new value as soon as the report finishes.

The entire contents of index.js can be downloaded here.

Conclusion

We did it. Caching is an excellent strategy for reducing resource load while providing faster responses. With Salesforce Functions, we can connect our Salesforce orgs to Heroku datastores (such as Postgres and Redis) and build mechanisms for caching. Salesforce Functions allow us to perform tasks that might ordinarily be load-heavy, cause timeouts, or exceed other limits imposed by Salesforce. Caching is just one use case, but it can yield tremendous benefits, and it’s easy to implement. Now, go have fun with it!

Build a Java Backend that Connects with Salesforce

Michael Bogan — Wed, 02 Nov 2022 12:50:47 +0000

Part One: Java Calling Salesforce

The Salesforce ecosystem is pretty massive. Developers need to work hard to stay up-to-date with the latest and greatest features and tools coming from Salesforce. In this article, we’ll mix a little bit of the old and the new. We’ll combine Java-based applications with Salesforce, and we’ll do so via web services.

Java is a programming language and computing platform first released by Sun Microsystems back in 1995. Since then, we’ve seen the rise of Web 2.0 and web programming languages, containers, microservices, and cloud-native architectures. Yet even now, many new products and digital services designed for the future continue to rely on Java. Java will be around for the foreseeable future.

Meanwhile, Salesforce has established itself as the world’s top CRM and customer success platform. With today’s enterprises relying on multi- and hybrid-cloud setups with applications that need to integrate seamlessly with one another, it’s not surprising that Java applications and the Salesforce Cloud need to intersect. So how do we get our Java and Salesforce.com (SFDC) applications integrated and talking with one another?

In this article, we’ll discuss how to implement this integration using the Web Services Connector (WSC). We’ll use an example use case—a business that wants to use its Java application to manipulate Salesforce org data—and show you how to set up your developer environment and connect the pieces.

However, before we start, let’s talk briefly about Salesforce and its API-first approach.

Salesforce and the API-first Approach

If you’re familiar with the SFDC ecosystem, then you will know that Salesforce takes an API-first approach when building features on its platform. In fact, Salesforce was one of the first companies to deploy web APIs! While the platform has many great built-in capabilities, Salesforce wants to enable its customers to create the capabilities and custom experiences they need for their own platforms. By offering APIs, Salesforce ensures that SFDC can be customized and connected to any external application that can interact with web services. Some of the APIs from Salesforce (and there are a lot of them) include:

Suffice it to say that Salesforce has its platform pretty well-covered by APIs, opening up access to its capabilities for countless different use cases. That being said, let’s dive into our use case.

In our example use case, we have a Java application that helps a business generate leads for their sales organization. That business would like the Java application to push the qualified leads directly to their Salesforce CRM, avoiding the need for manually entering lead data into Salesforce.

To integrate Java and Salesforce, we’ll use the Salesforce SOAP API and the Web Services Connector (WSC) library, which serves as a wrapper layer that simplifies working with the API in Java.

Initial Setup

The initial setup of our Java developer environment requires taking several steps. Fortunately, we had guidance from this Salesforce tipsheet. Nonetheless, we’ll provide an overview of the major steps here.

Install the Java Developer Kit (JDK)

To use Salesforce APIs in our Java application, we’ll install the Java Developer Kit (JDK) at version 11.0 or later. You can do that by visiting this page and finding the appropriate binary for your local machine.

Install Eclipse

Next, you’ll need a Java development IDE. While there are several options available to you, the steps for our walk-through will go with the Eclipse IDE. You can find the latest Eclipse IDE packages here. Download and install the IDE on your local machine.

Install the WSC

Since we’ll be using the Salesforce SOAP API, we need to install the WSC.

Download WSC pre-built .jar files

The Maven repository for the WSC shows all of the versions available:

Navigate to the page for the version that matches the API version of Salesforce that you’re using. In our example, we’ll use 56.0.0.

Under Files, we click on View All. This takes us to the ` of actual .jar files we will need to download.

Download the following four files to your local machine:

force-wsc-56.0.0-javadoc.jar
force-wsc-56.0.0-sources.jar
force-wsc-56.0.0-uber.jar
force-wsc-56.0.0.jar

We will use these files to generate stub files with the WSDLs from our Salesforce org.

Generate and download the WSDL for your Salesforce org

Next, we’ll generate an WSDL to use in generating our .jar stub files. We can’t use pre-built .jar files here because the WSDL is specific to our Salesforce Org. If there are custom objects and fields defined in our Org, then the WSDL will reflect those, and the generated .jar will contain them.

We log into our Salesforce developer organization. Then, we navigate to Setup, Platform Tools, Integrations, API. We click on “Generate Enterprise WSDL.”

This will open a new tab in your browser, displaying your WSDL file. Save this file to your local machine with the name sfdc.wsdl. Put it in the same folder where you downloaded the WSC .jar files.

Generate Java stub file

To use the SOAP API with Java, we need to generate .jar stub files for use in our application project. We run the following command to generate the stub file:

`
$ java -classpath force-wsc-56.0.0-uber.jar com.sforce.ws.tools.wsdlc sfdc.wsdl sfdc_stub.jar

[WSC][wsdlc.main:72]Generating Java files from schema ...
[WSC][wsdlc.main:72]Generating 1206 java files.
[WSC][wsdlc.main:72]Compiled 1210 java files.
[WSC][wsdlc.main:72]Generating jar file ... sfdc_stub.jar
[WSC][wsdlc.main:72]Generated jar file sfdc_stub.jar
`

Create Java Project in Eclipse

In Eclipse, start a new Java project and a new Java class, Main, using the following code:

`
package wsc;
// Depending on wsdl chosen, change this to enterprise or partner
import com.sforce.soap.enterprise.;
import com.sforce.soap.enterprise.sobject.;

import com.sforce.ws.*;

public class Main {
public static void main(String[] args) {
ConnectorConfig credentials = new ConnectorConfig();
credentials.setPassword("YourPassword!apPenDdedSecurityToken);
credentials.setUsername("yoursalesforceusername@yourdomain.com");

EnterpriseConnection connection;
try {
  connection = Connector.newConnection(credentials);
  Lead le = new Lead();
  le.setLastName("AcmeEnterprises");
  le.setCompany("JavaPush");
  le.setIndustry("Hospitality"); 
  connection.create(new Lead[]{ le });
} catch (ConnectionException e) {
  e.printStackTrace();
}

}
}
`

Add .jar files to project

Next, we need to connect the generated four .jar files with the build path for our project. Right-click on your project and select Build Path, Configure Build Path.

In the modal that comes up, navigate to Java Build Path in the left side panel. Click on the Libraries tab. Select Modulepath, and then click the Add External JARs button. Find the four .jar files that you downloaded from the Maven repository and the generated stub file (sfdc_stub.jar), and add them. Then, click on Apply and Close.

Test the Application

We are all set up, with our code and our .jar files all in place. Now, right-click on your Main.java file in Eclipse. Select Run As -> Java Application.

After we run our application, we navigate to Sales Leads in our Salesforce org, and we see that we have a new lead!

Our Java application has successfully tapped into our Salesforce org through the SOAP API, using the WSC to insert a new lead!

Next Steps

Now that we have verified the initial proof of concept, you can begin expanding your Java application to perform other operations, including reads, updates, and deletions. You can incorporate your own custom business logic to create a Java application that handles your Salesforce org data for you!

For more information on many of the core concepts we covered, here are links to helpful resources:

Swift and Pure Functions

Adrian Ruvalcaba — Fri, 08 Jul 2022 14:51:59 +0000

I worked on the Salesforce Events iOS team from 2016 to 2020. During this time, we used functional reactive principles to improve our codebase. The benefits that stood out to me the most were:

Crash rate dropped from one crash in every 100 launches to one in every 40 thousand.
Bug rate dropped and bug resolution times decreased.
Increased development velocity.

What are Pure Functions?

A function is pure if it always returns the same value for a given set of inputs.
A pure function is free of side effects.

Side effects are: reads or writes to state outside of the function's set of input params.

Here's a contrived example of an impure function.

//not pure
//has side effects
//doesn't always return same values for input
struct Adder {
    var sum: Int = 0
    var left: Int = 0
    var right: Int = 0

    func add () {
        self.sum = self.left + self.right
    }
}

And a pure example which meets our two criteria above: returns same output for given input; and is free of side effects.

func pureAdd (left: Int, right: Int) → Int {
    return left + right
}

Cost Per Test

Writing tests that assert that a given set of inputs produce the correct output is as straightforward as a test can get. No mocking or state initialization are required.

Given the example functions above, testing pureAdd can be done compactly.

assertEqual(pureAdd(1, 99), 100)
assertEqual(pureAdd(1, 0), 1)
assertEqual(pureAdd(2, 2), 4)

While the non pure example requires more setup per assertion.

let adder = Adder()
adder.left = 1
adder.right = 0
adder.add()
assertEqual(adder.sum, 1)

In general, the more side effects a function has, the higher the cost per test

Test Effectiveness of Pure functions

The goal of unit tests should be to prove that the function under test produces the correct output for the input space.

For the function isTrue(input: Bool) -> Bool the input space has two possibilities: true and false. So, to prove correctness we'll need two assertions:

assertEqual(isTrue(true), true)
assertEqual(isTrue(false), false)

If we add a second Bool param, we double the input space and double the number of assertions needed to prove correctness:

assertEqual(areTrue(true, true), true)
assertEqual(areTrue(true, false), false)
assertEqual(areTrue(false, false), false)
assertEqual(areTrue(false, true), false)

For pure functions, the number of assertions needed to prove correctness is a product of the input space. This means that limiting the input space helps lower testing effort for proving correct output for all input.

To lower the input space we should favor using input parameters with a discrete number of possible values. For example, consider using enum vs String when possible because an enum has a finite set of values while a String has an unbounded number of possible values.

Test Effectiveness of Non-Pure functions

For non-pure functions proving correct output for the input space is considerably more challenging for a few reasons:

The input into a non-pure function may include object and global state.
This expanded input space increases the number of assertions needed to prove correctness.
As seen above, the scaffolding cost per test is often higher for these functions.
Shared state can change externally before the function completes.

Given the increased effort required, proving correctness may become intractable for these functions and we instead target code coverage.

While coverage is a good metric to help make sure functions have some level of unit testing, I don't believe having code coverage is equivalent to ensuring correctness of the function.

Closing Thoughts

Thanks for reading. This post was focused on how pure functions can benefit us with regard to testing. However, there are many more benefits to be gained from functional programming and Swift like concurrency, reactive and composition that are worth exploring.

Working with Salesforce APIs? Of CORS!

Michael Bogan — Mon, 06 Jun 2022 14:07:08 +0000

The fundamental capabilities of the internet can be boiled down to one simple interaction: a call and a response. One machine (the client) sends requests to another machine (the server), which responds with a reply. This back-and-forth request-and-response cycle is how every phone, television, smart fridge, or computer sends and receives data.

However, there are several security risks inherent in this model, from application vulnerabilities to DDoS attacks. In this post, we’ll take a closer look at how Cross-Origin Resource Sharing, or CORS, mitigates these risks and how it operates. By working with a small Node.js app that interacts with several Salesforce APIs, we will see the differences in responses when CORS is enabled and disabled, as well as what effect it has on our client.

First, let’s take a deeper look at what CORS is and why it exists.

Web Pages Call External Resources

Whenever a browser requests a web page, the server sends back a chunk of HTML. The browser then draws that HTML and, crucially, continues to ask the server for more information when necessary. For example, if there’s any content that can’t be parsed, such as images or videos, or code that needs to be executed (such as JavaScript), then the browser continues making requests to the server, and the server happily fulfills them.

Security Risks

Suppose you’re browsing around at salesforce.com, and your browser encounters some JavaScript that executes a request to trailhead.com. For example, say a piece of code wants to get a list of a user’s completed trails using the fetch API:

let response = await fetch('https://api.trailhead.com/user/1/trails');

On the surface, this JavaScript code is pretty innocuous, but it presents a fundamental question about how the web operates: If a browser is loading salesforce.com, should it also be able to load data from trailhead.com? One’s instinct might be to say, “Yes, of course.” But if we allow salesforce.com to load from trailhead.com, why not allow loading code from heroku.com, github.com, or google.com? Why not just load code from anywhere?

Walking the slippery slope of making requests from any site in the world also introduces the security risks mentioned above. In this example, without any boundaries, trailhead.com can’t control who is requesting data from them. What would be ideal is if a server could make a list of whom it trusts to be given access out on the web. Perhaps trailhead.com will allow users on salesforce.com to load scripts, but not from anywhere else.

Enter CORS!

CORS is designed to plug this hole. A server dictates not only which domains can access its resources, but the types of HTTP verbs as well. If a client isn’t able to satisfy the server’s CORS requirements, then data cannot be executed or delivered. CORS is a concept that extends beyond any one programming language and is configured on a web server, such as nginx or Apache. Most crucially, it’s enforced by the browser: there’s no way around it, and data enforced by CORS can’t be accessed by browser clients outside of that context. CORS is designed to walk the line between enabling a client’s productivity and enforcing a server’s security.

CORS is enforced through HTTP Headers, which can be thought of as additional metadata attached to HTTP requests and responses. You might be familiar with adding headers for authentication (such as Authorization: token xxx) or to specify the data types the client understands (via Accept). CORS has its own category of headers, which a server uses to state where a browser may load its resources from.

To demonstrate what this means in practice, let’s take a look at how a demo app using the Salesforce platform interacts with CORS.

Demo prerequisites

Before getting started, make sure that your Salesforce instance supports access to its API. If you don’t have access to the Salesforce platform, then you can create a free Developer Edition account. You can use this org to test what developing on the Salesforce platform looks like.

Requesting Salesforce resources

Open a browser tab and navigate to https://jsfiddle.net. In the box that says JavaScript, paste these lines of code:

const run = async () => {
const response = await fetch('https://myInstance-dev-ed.my.salesforce.com/services/data');
const responseJson = await response.json();
responseJson.forEach( (e) => document.write(e.label + "<br/>"));
document.body.style.background = "white";
}
run();

Replace myInstance-dev-edwith the actual name of your Salesforce instance. Click Run in the top menu bar. You should see….nothing.

However, if you open the Browser Console, you’ll see a message indicating that CORS has blocked access:

Access to fetch at 
'https://myInstance-dev-ed.my.salesforce.com/services/data' from origin 
'https://fiddle.jshell.net' has been blocked by CORS policy: No 
'Access-Control-Allow-Origin' header is present on the requested resource. 
If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

What’s going on here? Well, Salesforce provides semi-open access to its data and assets. In this case, we tried to use JavaScript’s fetch function to make a request and retrieve some JSON data. However, due to CORS, we were blocked from doing so. Unauthorized access is exactly what CORS was designed to prevent.

Specifically, we were blocked by the lack of a proper Access-Control-Allow-Origin definition. This header states which URLs a browser is permitted to load resources from. If this information is missing, then the browser simply cannot load the external resource, which in this case was the content at the /services/data path of our Salesforce instance. There are many other types of CORS headers, such as Access-Control-Allow-Methods, which defines which HTTP methods a browser is permitted to make.

Enabling CORS in Salesforce

Fortunately, it doesn’t take much to enable CORS on the Salesforce APIs. Follow the short steps in this guide, and enter https://fiddle.jshell.netas the allowed domain:

Make sure there’s no trailing slash at the end of this URL.

Click Save, then run that code snippet one more time. Voila! It’s not much, but you should see a list of some Salesforce editions.

Other CORS Considerations

While Salesforce takes the utmost effort to provide a way to securely retrieve data, other platforms might not be as secure. Fortunately, CORS also provides the ability to pass in credentials.

Credentials are useful if you’re navigating on a site that, unlike Salesforce, does not use an authentication mechanism. By setting an additional option in your client-side JavaScript request (credentials: "include"), your browser’s cookies are sent over along with the request. Cookies have been used as an identifying mechanism since the very early days of the internet. Although they’ve largely been abandoned as an authentication method, some websites still do use them as such. It’s the server’s responsibility to receive the cookies and perform any additional validations on them.

Since CORS support is largely a consideration for servers (that is, servers should have CORS enabled by default), there isn’t much else for the client to do. There are different modes that a client can set, which have a variety of purposes. For example, if you’re building a series of microservices, then you may find that the same-origin’s strict domain matching may be useful for doubly ensuring that requests and responses come from the same domain.

We’ve largely been talking about CORS and JavaScript, but there’s another important component to web development where CORS can step in: the humble <iframe>. The iframe element allows you to embed the contents from another URL into a web page. What keeps me from registering www.not-salesforce.com and just setting the page to the contents of Salesforce? CORS, of course!

Conclusion

Ultimately, not every server supports open CORS access, and it’s at the server’s discretion. Improperly configured CORS settings have the potential to impede legitimate user workflows, but disabling CORS entirely will certainly make your application more vulnerable to attacks from malicious clients. In general, as a developer, if an action can be done on the server, it’s more likely to be safer than performing work on the client, so make sure you are disabling CORS for a good reason if you’re thinking of it.

We’ve just taken a brief look at Salesforce APIs here. You can also manipulate data or retrieve all sorts of Apex data. We encourage you to take a look at the Force.com REST API Developer Guide for more information on what the APIs allow you to do. You can also find a bevy of tutorials on Trailhead to help you build your integrations with the platform.

Building a Kotlin Mobile App with the Salesforce SDK, Part 3: Synchronizing Data

Michael Bogan — Mon, 02 May 2022 18:49:22 +0000

This is our final post in our three-part series demonstrating how to use the Salesforce Mobile SDK to build an Android app that works with the Salesforce platform. In our first post, we showed you how to connect to your org. Our second post showed you how to edit and add data to your org from your app. This post will show you how to synchronize data from your Salesforce org to your mobile device and handle scenarios such as network loss. Let’s get right into it!

Working with Mobile Sync

One of the hardest aspects of mobile development is dealing with data synchronization. How do you handle the situation when you need to add a new broker, but you’re offline? Or what if two agents are updating the same broker—how can you handle the merging of those two changes?

With the Salesforce Mobile SDK, these real-world issues are handled for you by a system called Mobile Sync. Mobile Sync has you map your phone’s local data to the data in Salesforce; it also requires you to define operations for fetching and pushing data—what it calls syncDown and syncUp.

Define the shape of data to be synced

To get started with Mobile Sync, create a file in res/raw called brokerstore.json:

{
 "soups": [
   {
     "soupName": "brokers",
     "indexes": [
       { "path": "Id", "type": "string"},
       { "path": "Name", "type": "string"},
       { "path": "Title__c", "type": "string"},
       { "path": "Phone__c", "type": "string"},
       { "path": "Mobile_Phone__c", "type": "string"},
       { "path": "Email__c", "type": "string"},
       { "path": "Picture__c", "type": "string"},
       { "path": "__local__", "type": "string"},
       { "path": "__locally_created__", "type": "string"},
       { "path": "__locally_updated__", "type": "string"},
       { "path": "__locally_deleted__", "type": "string"},
       { "path": "__sync_id__", "type": "integer"}
     ]
   }
 ]
}

This file defines the shape of the data on your phone, as well as some additional metadata that’s necessary for the sync.

Next, create a file called brokersync.json:

{
 "syncs": [
   {
     "syncName": "syncDownBrokers",
     "syncType": "syncDown",
     "soupName": "brokers",
     "target": {"type":"soql", "query":"SELECT Name, Title__c, Phone__c, Mobile_Phone__c, Email__c, Picture__c FROM Broker__c LIMIT 10000"},
     "options": {"mergeMode":"OVERWRITE"}
   },
   {
     "syncName": "syncUpBrokers",
     "syncType": "syncUp",
     "soupName": "brokers",
     "target": {"createFieldlist":["Name", "Title__c", "Phone__c", "Mobile_Phone__c", "Email__c", "Picture__c"]},
     "options": {"fieldlist":["Id", "Name", "Title__c", "Phone__c", "Mobile_Phone__c", "Email__c", "Picture__c"], "mergeMode":"LEAVE_IF_CHANGED"}
   }
 ]
}

These are the operations that Mobile Sync will use when syncing data down and up.

The code to complete the Mobile Sync process depends on several factors, such as when you want to perform a synchronization, as well as hooking into the Android event cycle when a device loses (and regains) connectivity.

The following code samples will show you a complete example of what needs to happen to get synchronization working, but they should be considered high-level concepts, and not necessarily production-ready enterprise-grade code.

Set up periodic sync

With that said, let’s take a look at how to implement synchronization. First, add this line to the end of our onResume(client: RestClient) method in MainActivity.kt:

setupPeriodicSync();

Next, we’ll add a new variable and a new function to the MainActivity class:

private val SYNC_CONTENT_AUTHORITY =
   "com.salesforce.samples.mobilesyncexplorer.sync.brokersyncadapter"

private fun setupPeriodicSync() {
   val account = MobileSyncSDKManager.getInstance().userAccountManager.currentAccount

   ContentResolver.setSyncAutomatically(account, SYNC_CONTENT_AUTHORITY, true)
   ContentResolver.addPeriodicSync(
       account, SYNC_CONTENT_AUTHORITY,
       Bundle.EMPTY, 10
   )
}

Since we’re using ContentResolver in our function, let’s make sure to import it by adding this line alongside the other import statements near the top of MainActivity.kt:

import.android.content.ContentResolver

We have defined two methods that trigger synchronization. setupPeriodicSync will run a sync every 10 seconds. This is much too frequent for a production environment, but we’ll set it this way for demonstration purposes.

Mapping sync operations to our data and UI

We will show the next few code samples all at once, and discuss what they’re doing afterward.

In app/java/com.example.sfdc, create a new file called BrokerSyncAdapter.kt and paste these lines into it:

package com.example.sfdc

import android.accounts.Account
import android.content.AbstractThreadedSyncAdapter
import android.content.ContentProviderClient
import android.content.Context
import android.content.SyncResult
import android.os.Bundle
import com.salesforce.androidsdk.accounts.UserAccount
import com.salesforce.androidsdk.accounts.UserAccountManager
import com.salesforce.androidsdk.app.SalesforceSDKManager
import com.example.sfdc.BrokerListLoader

class BrokerSyncAdapter
   (
   context: Context?, autoInitialize: Boolean,
   allowParallelSyncs: Boolean
) :
   AbstractThreadedSyncAdapter(context, autoInitialize, allowParallelSyncs) {
   override fun onPerformSync(
       account: Account, extras: Bundle, authority: String,
       provider: ContentProviderClient, syncResult: SyncResult
   ) {
       val syncDownOnly = extras.getBoolean(SYNC_DOWN_ONLY, false)
       val sdkManager = SalesforceSDKManager.getInstance()
       val accManager = sdkManager.userAccountManager
       if (sdkManager.isLoggingOut || accManager.authenticatedUsers == null) {
           return
       }
       if (account != null) {
           val user = sdkManager.userAccountManager.buildUserAccount(account)
           val contactLoader = BrokerListLoader(context, user)
           if (syncDownOnly) {
               contactLoader.syncDown()
           } else {
               contactLoader.syncUp() // does a sync up followed by a sync down
           }
       }
   }

   companion object {
       // Key for extras bundle
       const val SYNC_DOWN_ONLY = "syncDownOnly"
   }
}

Now, in that same folder, create BrokerListLoader.kt with these lines:

package com.example.sfdc

import android.content.AsyncTaskLoader
import android.content.Context
import android.content.Intent
import android.util.Log
import com.salesforce.androidsdk.accounts.UserAccount
import com.salesforce.androidsdk.app.SalesforceSDKManager
import com.salesforce.androidsdk.mobilesync.app.MobileSyncSDKManager
import com.salesforce.androidsdk.mobilesync.manager.SyncManager
import com.salesforce.androidsdk.mobilesync.manager.SyncManager.MobileSyncException
import com.salesforce.androidsdk.mobilesync.manager.SyncManager.SyncUpdateCallback
import com.salesforce.androidsdk.mobilesync.util.SyncState
import com.salesforce.androidsdk.smartstore.store.QuerySpec
import com.salesforce.androidsdk.smartstore.store.SmartSqlHelper.SmartSqlException
import com.salesforce.androidsdk.smartstore.store.SmartStore
import org.json.JSONArray
import org.json.JSONException
import java.util.ArrayList

class BrokerListLoader(context: Context?, account: UserAccount?) :
   AsyncTaskLoader<List<String>?>(context) {
   private val smartStore: SmartStore
   private val syncMgr: SyncManager
   override fun loadInBackground(): List<String>? {
       if (!smartStore.hasSoup(BROKER_SOUP)) {
           return null
       }
       val querySpec = QuerySpec.buildAllQuerySpec(
           BROKER_SOUP,
           "Name", QuerySpec.Order.ascending, LIMIT
       )
       val results: JSONArray
       val brokers: MutableList<String> = ArrayList<String>()
       try {
           results = smartStore.query(querySpec, 0)
           for (i in 0 until results.length()) {
               brokers.add(results.getJSONObject(i).getString("Name"))
           }
       } catch (e: JSONException) {
           Log.e(TAG, "JSONException occurred while parsing", e)
       } catch (e: SmartSqlException) {
           Log.e(TAG, "SmartSqlException occurred while fetching data", e)
       }
       return brokers
   }

   @Synchronized
   fun syncUp() {
       try {
           syncMgr.reSync(
               SYNC_UP_NAME
           ) { sync ->
               if (SyncState.Status.DONE == sync.status) {
                   syncDown()
               }
           }
       } catch (e: JSONException) {
           Log.e(TAG, "JSONException occurred while parsing", e)
       } catch (e: MobileSyncException) {
           Log.e(TAG, "MobileSyncException occurred while attempting to sync up", e)
       }
   }

   /**
    * Pulls the latest records from the server.
    */
   @Synchronized
   fun syncDown() {
       try {
           syncMgr.reSync(
               SYNC_DOWN_NAME
           ) { sync ->
               if (SyncState.Status.DONE == sync.status) {
                   fireLoadCompleteIntent()
               }
           }
       } catch (e: JSONException) {
           Log.e(TAG, "JSONException occurred while parsing", e)
       } catch (e: MobileSyncException) {
           Log.e(TAG, "MobileSyncException occurred while attempting to sync down", e)
       }
   }

   private fun fireLoadCompleteIntent() {
       val intent = Intent(LOAD_COMPLETE_INTENT_ACTION)
       SalesforceSDKManager.getInstance().appContext.sendBroadcast(intent)
   }

   companion object {
       const val BROKER_SOUP = "brokers"
       const val LOAD_COMPLETE_INTENT_ACTION =
           "com.salesforce.samples.mobilesyncexplorer.loaders.LIST_LOAD_COMPLETE"
       private const val TAG = "BrokerListLoader"
       private const val SYNC_DOWN_NAME = "syncDownBrokers"
       private const val SYNC_UP_NAME = "syncUpBrokers"
       private const val LIMIT = 10000
   }

   init {
       val sdkManager = MobileSyncSDKManager.getInstance()
       smartStore = sdkManager.getSmartStore(account)
       syncMgr = SyncManager.getInstance(account)
       // Setup schema if needed
       sdkManager.setupUserStoreFromDefaultConfig()
       // Setup syncs if needed
       sdkManager.setupUserSyncsFromDefaultConfig()
   }
}

What did we just do? Each file has a specific role, and while the objects and fields will certainly be different for your app, the functions and philosophies of these classes are the same:

BrokerListLoader is responsible for mapping the sync operations you defined in brokersync.json with the Kotlin code that will actually perform the work. Notice that there are syncUp and syncDown methods that use the Mobile SDK’s SyncManager to load the JSON files and communicate back and forth with Salesforce.
BrokerSyncAdapter can perhaps best be thought of as the code that’s responsible for scheduling the synchronization. That is, it’s the entry point for BrokerListLoader, and can be called by UI elements (such as during a refresh button click) or Android system events (such as connectivity loss).

Lastly, we need to add one line to our AndroidManifest.xml file (in app/manifests). Our new sync functionality will need special Android permissions, which we ask the user to allow upon app installation at runtime. Add the following line with WRITE_SYNC_SETTINGS to the end of your manifest:

  <uses-permission android:name="com.example.sfdc.C2D_MESSAGE" />
  <uses-permission android:name="android.permission.WRITE_SYNC_SETTINGS" />
</manifest>

Testing sync

Our last step is to test that mobile sync works. With the emulator running, you should be logged in and see a list of brokers. This list should mirror the broker list that you see in your web browser on your local machine. In your web browser, edit one of the broker names, and save that change.

Then, in your emulator, you can power off the phone or switch to another application and then switch back to your sfdc-mobile-app. You should see your list of broker names updated with the change you made in your browser:

And that’s all! Again, this is just a foundational building block for you to learn from. In just about 150 lines of code, we’ve devised a solution for a rather complicated series of moving parts:

Mapping Salesforce custom objects to JSON
Setting up a timer to periodically sync data back and forth between a Salesforce org and a mobile device
Handling errors (and recovering from issues) around network connectivity

Conclusion

The Salesforce Mobile SDK makes it tremendously easy to connect mobile devices with Salesforce data. In this post, you learned how to query and manipulate data from your phone, and saw the results reflected instantaneously on Salesforce. You also learned about Mobile Sync and its role in anticipating issues with connectivity.

And yet, with all of this information, there’s still so much more that the Salesforce Mobile SDK can do. Take a look at the complete documentation on working with the SDK. Or, if you prefer to do more coding, there are plenty of Trailhead tutorials to keep you busy. We can’t wait to see what you build!

Building a Slack App with Native SFDC Integration

Michael Bogan — Wed, 13 Apr 2022 14:36:35 +0000

Synchronizing Data

At last, we’ve arrived at the final part of our series on using Salesforce’s Slack Starter Kit to quickly scaffold a deployable Slack App that interacts with Salesforce data. The Slack Starter Kit makes it tremendously easy to authenticate with Salesforce, organize your code into reusable chunks, and deploy the project to Heroku for live access. We’ve largely based this series on these video tutorials showcasing how to build Slack Apps.

In our first post, we got acquainted with the Slack Starter Kit and set up our development environment. In our second post, our Slack app issued a query to fetch data from a Salesforce org and then presented the result with UI components from Block Kit. Now, we’re going to extend that pattern to showcase how you can edit Salesforce data entirely within Slack. Let’s get started!

Photo by Edgar Moran on Unsplash

Creating a shortcut

Outside of the Block Kit UI, Slack has support for two other interactivity systems: Slash Commands and shortcuts. Slash Commands are entered by a user in Slack’s text input (available in every channel), while shortcuts are graphical in nature. Since they’re easier to visualize, we’ll demonstrate shortcuts by creating a shortcut that will fetch our list of contacts and give us the ability to edit them.

Adding a shortcut (or a Slash Command, for that matter) first requires that you tell Slack the name of the command. Go to your app’s Overview page on Slack, and then click Interactivity & Shortcuts:

Click Create New Shortcut, and select Global as your shortcut type, then click Next. On the next page, enter these values:

Name: Edit contacts
Short Description: Edits contacts on SFDC
Callback ID: edit-contact-shortcut

Click on Create, then click Save Changes. Switch over to your Slack workspace, and click on the plus sign in the text area. You’ll be able to browse all of your workspace shortcuts. Here, you’ll also see the brand new shortcut you just created:

This shortcut doesn’t do anything yet, but this process is necessary for Slack to know about your shortcut. Next, let’s add the code to handle the event that fires whenever someone clicks on this shortcut.

Wiring up the shortcut

In your code editor, navigate to apps/slack-salesforce-starter-app/listeners/shortcuts/index.js. This is the spot where we connect shortcut events to the code that’s executed. There’s already one shortcut given to us by the Starter Kit: whoami. The given line suggests to us what we need to do: We call a function called shortcut and pass in a string and a function name. In this case, our string is the callback ID we previously defined, and our function name is the code we’ve yet to write. Change the file contents to look like this:

const { whoamiCallback } = require('./whoami');
const { editContactCallback } = require('./edit-contact');

module.exports.register = (app) => {
   app.shortcut('who_am_i', whoamiCallback);
   app.shortcut('edit-contact-shortcut', editContactCallback);
};

We’re laying the groundwork here by saying: “Slack App, if you get a shortcut with a callback ID of edit-contact-shortcut run editContactCallback.”

In this same folder, create a file called edit-contact.js, and paste these lines into it:

'use strict';

const {
  editContactResponse,
  authorize_sf_prompt
} = require('../../user-interface/modals');

const editContactCallback = async ({ shortcut, ack, client, context }) => {
  try {
    await ack();
    if (context.hasAuthorized) {
      const conn = context.sfconnection;
      await client.views.open({
        trigger_id: shortcut.trigger_id,
        view: await editContactResponse(conn)
      });
    } else {
      // Get BotInfo
      const botInfo = await client.bots.info({ bot: context.botId });
      // Open a Modal with message to navigate to App Home for authorization
      await client.views.open({
        trigger_id: shortcut.trigger_id,
        view: authorize_sf_prompt(context.teamId, botInfo.bot.app_id)
      });
    }
  } catch (error) {
    // eslint-disable-next-line no-console
    console.error(error);
  }
};

module.exports = { editContactCallback };

Now, this might look intimidating, but most of it simply concerns the authentication boilerplate, ensuring that a user has an active SFDC connection. In the first logical path (if context.hasAuthorized is true), we execute a function called editContactResponse, which accepts our open Salesforce connection. In the negative case, we ask the user to go to the Home tab to reauthenticate, just as we did in Part 1 of this tutorial.

Navigate to the apps/slack-salesforce-starter-app/user-interface/modals folder, and create a file called edit-contact-response.js. Here, we’ll pop open a modal with contact information similar to the rows we saw in the Home tab in Part 2 of this tutorial:

'use strict';
const { Elements, Modal, Blocks } = require('slack-block-builder');

const editContactResponse = async (conn) => {
  const result = await conn.query(
    `Select Id, Name, Description FROM Contact`
  );
  let records = result.records;

  let blockCollection = records.map((record) => {
    return Blocks.Section({
      text: `*${record.Name}*\n${record.Description}`
    }).accessory(
      Elements.Button()
        .text(`Edit`)
        .actionId(`edit_contact`)
        .value(record.Id)
    );
  });

  return Modal({ title: 'Salesforce Slack App', close: 'Close' })
    .blocks(blockCollection)
    .buildToJSON();
};

module.exports = { editContactResponse };

The main difference between the code in Part 2 and this block is that we’re using an array called blockCollection, which lets us construct an array of blocks (in this case, Section blocks). blocks knows how to take this array and transform it into a format that Slack understands, which makes it super simple to create data through a looped array, as we’ve done here. In Part 2 of our series, we constructed a giant string of data. By using BlockCollection, however, we can attach other Slack elements—such as buttons—which we’ve done here.

Lastly, in apps/slack-salesforce-starter-app/user-interface/modals/index.js, we’ll need to export this function, so that it can be imported by our edit-contact.js function:

'use strict';
const { whoamiresponse } = require('./whoami-response');
const { editContactResponse } = require('./edit-contact-response');
const { authorize_sf_prompt } = require('./authorize-sf-prompt');

module.exports = { whoamiresponse, editContactResponse, authorize_sf_prompt };

After you’ve deployed this new code to Heroku via git push, switch to your Slack workspace and try executing the shortcut; you’ll be greeted with a dialog box similar to this one:

Updating Salesforce data

We’re able to fetch and display Salesforce data. Now, it’s time to connect the Edit button to change Salesforce data!

Many of Slack’s interactive components have an action_id, which, like the callback_id, serves to identify the element which a user acted upon. Just like everything else in the Starter Kit, there’s a special directory where you can define listeners for these action IDs: apps/slack-salesforce-starter-app/listeners/actions. In the index.js file there, let’s add a new line that ties together the action ID with our yet-to-be-written functionality:

'use strict';
const { appHomeAuthorizeButtonCallback } = require('./app-home-authorize-btn');
const { editContactButtonCallback } = require('./edit-contact-btn');

module.exports.register = (app) => {
  app.action('authorize-with-salesforce', appHomeAuthorizeButtonCallback);
  app.action('edit_contact', editContactButtonCallback);
};

In this same folder, create a new file called edit-contact-btn.js, and paste these lines into it:

'use strict';
const {
  editIndividualContact,
  authorize_sf_prompt
} = require('../../user-interface/modals');

const editContactButtonCallback = async ({ body, ack, client, context }) => {
  const contactId = body.actions[0].value;
  try {
    await ack();
  } catch (error) {
    // eslint-disable-next-line no-console
    console.error(error);
  }

  if (context.hasAuthorized) {
    const conn = context.sfconnection;
    const result = await conn.query(
      `SELECT Id, Name, Description FROM Contact WHERE Id='${contactId}'`
    );
    let record = result.records[0];
    await client.views.push({
      trigger_id: body.trigger_id,
      view: editIndividualContact(record)
    });
  } else {
    // Get BotInfo
    const botInfo = await client.bots.info({ bot: context.botId });
    // Open a Modal with message to navigate to App Home for authorization
    await client.views.push({
      trigger_id: body.trigger_id,
      view: authorize_sf_prompt(context.teamId, botInfo.bot.app_id)
    });
  }
};

module.exports = { editContactButtonCallback };

The beginning and ending of this file should look familiar: We’re sending an ack response back to Slack to let it know that our app received the event payload (in this case, from clicking on the Edit button). We’re also checking whether or not we’re still authenticated. Here, we’re doing a single DB lookup using the ID of the contact, which we attached as a value to the Edit button when constructing our UI.

This chunk of code creates another modal design which we need to define. Back in apps/slack-salesforce-starter-app/user-interface/modals, create a file called edit-individual-contact.js and paste these lines into it:

'use strict';
const { Elements, Modal, Blocks } = require('slack-block-builder');

const editIndividualContact = (record) => {
  return Modal({ title: 'Edit Contact', close: 'Close' })
    .blocks(
      Blocks.Input({ blockId: 'description-block', label: record.Name }).element(
        Elements.TextInput({
          placeholder: record.Description,
          actionId: record.Id
        })
     )
   )
   .submit('Save')
   .callbackId('edit-individual')
   .buildToJSON();
};

module.exports = { editIndividualContact };

Here, we’ve created a modal with a single block: an input element. The element will be pre-populated with the contact’s description. We can edit this block and change the description to whatever we want.

There are two important notes to point out in this code snippet:

Notice that we’re attaching an actionId to the input element. This is analogous to the ID we attached to the Edit button earlier, except this time, it’s dynamically generated based on the ID of the record we’re editing.
You’ll also notice that we have another ID, the callbackID, which is attached to the modal itself. Keep the existence of these IDs in the back of your mind: we’ll address both of these in a moment. For now, open up the index.js file in this same directory, and require/export this new modal-creating function:

const { editIndividualContact } = require('./edit-individual-contact');
// ...
module.exports = {
  whoamiresponse,
  editContactResponse,
  editIndividualContact,
  authorize_sf_prompt
};

Now when you click the Edit button, you’ll be prompted to change the description:

We now need to send this updated text to Salesforce. Click on the Save button and…nothing happens. Why? Well, Slack has a different set of events for interactions like these, called view submissions. The Starter Kit provides a good jumping off point when building an app, but it doesn’t handle every Slack use case, including this one. But that’s not a problem—we’ll add the functionality ourselves!

Within the apps/slack-salesforce-starter-app/user-interface folder, create a new folder called views. Just like before, our Save button here has an action ID to identify it: edit-individual-contact. We’ll head back into apps/slack-salesforce-starter-app/listeners/actions/index.js to configure this to a function:

const { editIndividualButtonCallback } = require('./edit-individual-btn);

// ... 

app.action('edit-individual-contact', editIndividualButtonCallback);

Create a new file called edit-individual-contact.js, and paste these lines into it:

'use strict';

const { submitEditCallback } = require('./submit-edit');

module.exports.register = (app) => {
  app.view('edit-individual', submitEditCallback);
};

This format is identical to the other listeners provided by the Slack Starter Kit. The only difference is that we are calling the view method. We also need to register this listener alongside the others. Open up apps/slack-salesforce-starter-app/listeners/index.js, and require/register the new view listener:

const viewListener = require('./views');

module.exports.registerListeners = (app) => {
  // ...
  viewListener.register(app);
};

Next, in apps/slack-salesforce-starter-app/listeners/views, create another file called submit-edit.js and paste these lines into it:

'use strict';
const { editContactResponse, authorize_sf_prompt } = require('../../user-interface/modals');

const submitEditCallback = async ({ view, ack, client, context }) => {
  try {
    await ack();
  } catch (error) {
    // eslint-disable-next-line no-console
    console.error(error);
  }

  if (context.hasAuthorized) {
    const contactId = view.blocks[0].element.action_id;
    const newDescription =
      view.state.values['description-block'][contactId].value;
    const conn = context.sfconnection;
    await conn.sobject('Contact').update({
      Id: contactId,
      Description: newDescription
    });

    await client.views.open({
      trigger_id: view.trigger_id,
      view: await editContactResponse(conn)
    });
  } else {
    // Get BotInfo
    const botInfo = await client.bots.info({ bot: context.botId });
    // Open a Modal with message to navigate to App Home for authorization
    await client.views.push({
      trigger_id: view.trigger_id,
       view: authorize_sf_prompt(context.teamId, botInfo.bot.app_id)
    });
  }
};

module.exports = { submitEditCallback };

Let’s discuss those IDs that we set before. When Slack sends event payloads over to our app, it automatically generates an ID for every input element by default. That’s because Slack doesn’t know what the underlying data is. It’s your responsibility to name the elements via action IDs. Slack uses these IDs as keys to populate the payload. When you receive Slack’s payload, you can use the keys you provided to parse the data the user entered.

Now, if you go through the flow to edit your contact’s description, you’ll notice that the modal will correctly save. To verify that the data on the Salesforce side was updated, run sfdx force:org:open in your terminal and navigate to the Contacts tab.

Conclusion

The Slack Starter Kit has made it an absolute breeze to build a Slack App that listens to user events. Beyond that, though, it also makes interacting with Salesforce and Heroku an absolute pleasure. We’ve covered just about everything that the Starter Kit can do. If you’d like to learn more about how Slack and Salesforce can work together, check out our blog post on building better together. Also, the backend framework that interacts with Salesforce is the wonderful JSforce project. Be sure to check out both its documentation and the Salesforce API Reference to learn more about what you can build!

Building a Slack App with Native SFDC Integration

Michael Bogan — Tue, 05 Apr 2022 13:38:35 +0000

Building a Slack App: Designing a UI

This post is a continuation of our series based on a video series explaining how to build Slack Apps that integrate with Salesforce APIs. With the Slack Starter Kit from Salesforce, Slack app developers can offload common concerns like Salesforce authentication, directory hierarchies, reusable code, and deployments to Heroku. The end result is less time spent wrangling code and more time building features for your app.

In our last post, we familiarized ourselves with the starter kit and set up our development environment to build a basic Slack app. In this post, we’ll continue building on that Slack app, focusing on how the Slack Starter Kit makes it easy to develop two essential components of every Slack app:

Listening for user interactions
Drawing a user interface.

Responding to events

If you’ve ever developed a front-end web app using JavaScript or CSS, you’re probably familiar with the basic tenets of event handling. Events in this context are defined as the actions a user takes on your website. For example, a mouse pointer clicking on a link emits an onclick event; a pointer linking over a piece of text emits onhover; a keyboard keystroke emits onkeypressed; and so on.

Photo by Stephen Phillips - Hostreviews.co.uk on Unsplash

In Slack, there’s a multitude of events you can listen to, ranging from individual events (when a message is posted or pinned) to global changes (when channel names or visibilities are changed) to the administrative (when an app is installed or a new emoji is uploaded). The full list of emitted events is truly impressive. The process for listening to an event is as follows:

First, your app needs to define a webhook URL. This is a path on your server which can receive POST requests from Slack.
Next, in your App Manifest, you identify the events which you’d like to capture.
When an event occurs in a workspace where your app is installed, a JSON payload is sent to your app. Every event has its own unique payload.

When your app receives the event from Slack, you can do anything you want: respond to the user, pop open a dialog to ask for more information, or simply store some information away in your database. There’s only one important point to remember: you must respond to Slack within three seconds. This is to let Slack know that your app received its payload and is working on a response. You can do that work in the background—perhaps on a different thread, taking as long as you need—but only after you let Slack know everything is 200 OK.

Let’s take a look at how event handling works in practice. Head on over to your App Manifest, and scroll down to the bottom of the page, near the settings key. It should look like this:

settings:
  event_subscriptions:
    request_url: https://<your-app-name>.herokuapp.com/slack/events
    bot_events:
      - app_home_opened
  interactivity:
    is_enabled: true
    request_url: https://<your-app-name>.herokuapp.com/slack/events

This section identifies where Slack should send its payload once an event occurs. The bot_events key already defines one event to listen to, app_home_opened, which is triggered once your app is opened in Slack.

Now, open up the local copy of your Starter Kit in your IDE; navigate to apps/slack-salesforce-starter-app/listeners/events/app-home-opened.js. As we saw in the last post, the Starter Kit has an opinionated directory structure to resolve any ambiguities as to where modifications should be made. In this case, the events folder is responsible for defining all of our event responses, just like the shortcuts folder defined our slack command in the previous article. Search for the first occurrence of the following line:

client.views.publish

As the method name implies, this function uses a Slack SDK to call an API named views.publish. The main view for this event is created by a function called authorization_success_screen, which can be found in apps/slack-salesforce-starter-app/user-interface/app-home/auth-success.js.

Let’s make a few changes to these files. On line 16, add this line to fetch the timestamp of the event:

let event_ts = event.event_ts;

Change both authorization_success_screen calls to include this variable as a new argument:

view: authorization_success_screen(
  currentuser.username,
  event_ts
)

Finally, open up auth-success.js, change the method signature to include event_ts, and modify the displayed string to include this information:

'use strict';

const { HomeTab, Blocks } = require('slack-block-builder');

const authorization_success_screen = (username, event_ts) => {

  // preceding code remains unchanged

       Blocks.Section({
           text: `It's ${event_ts}, and you are successfully authenticated to Salesforce as ${username}.`
       })
   );
// continued code remains unchanged

Commit this change, and deploy it to Heroku as before:

$ git add .
$ git commit -m "Add event timestamp"
$ git push heroku main

When the deployment is done, navigate to your app’s tab in the left-hand Slack menu. You should see a different string, which shows the timestamp of when you opened the app.

Creating a UI

Responding to app_home_opened can be a useful event to listen to whenever your app needs a centralized location to fetch data. Because of this, our next step will be to fetch data from Salesforce and present it in our Slack UI.

To design and present layouts, Slack provides a system known as Block Kit. Just as HTML is a markup language for the web, and Visualforce is a markup language for Salesforce, Block Kit is a markup language for Slack—except it uses JSON. For example, here’s what a button designed in Block Kit might look like:

{
  "type": "button",
  "text": {
    "type": "plain_text",
    "text": "Save"
  },
  "style": "primary"
}

Block Kit ensures that every Slack App has a consistent user interface. Because of this, there’s a limited set of UI elements that you can use.

When working with Block Kit, you design your layout in JSON. Then, you use the Slack API to POST that JSON to a channel, tab, or direct message.

We already have a system in place for listening to an event and presenting text, so let’s build on that foundation. Before we work in Slack, though, let’s add some data to our fresh Salesforce org. To launch your browser directly to your Salesforce org, you can run the following command:

sfdx force:org:open

In the Setup menu, search for the Data Import Wizard. Choose CSV as your data type, then copy-paste the following lines into a new file called data.csv:

Contact First Name, Contact Last Name, Contact Description
Arden, Isabela, Lorem ipsum dolor sit amet
Rowina, Arti, Proin a est sit amet quam varius efficitur.
Aislin, Oedipus, Praesent et euismod sem
Sindri, Filbert, Proin facilisis sit amet libero vulputate sodales
Cyril, Gratien, Nulla at massa eu turpis venenatis egestas

Upload this file as your data source. Importing this data should only take a minute or two. You can navigate to the Contacts tab if you’d like to be extra sure and verify that these names exist.

Next, we’re going to make changes similar to the ones we made before when adding the event timestamp. A variable called conn is available to use, which serves as a connection to Salesforce. We can use it to query for Contact data, which is what we’re interested in displaying in Slack.

Navigate to apps/slack-salesforce-starter-app/user-interface/app-home/auth-success.js. We’ll await the resolving of the promise in this function, and we’ll include the existing connvariable as a new argument:

view: await authorization_success_screen(
                   currentuser.username,
                   event_ts,
                   conn
               )

And once again, open up auth-success.js and change the method signature to include conn. You also need to declare the function as async:

'use strict';

const { HomeTab, Blocks } = require('slack-block-builder');

const authorization_success_screen = async (username, event_ts, conn) => {

// continued code remains unchanged for now

Next, with this connection, we’re going to issue a query to Salesforce to get our newly created Contact records. We’ll then display them in the Home tab of our Slack app.

Since we already have a connection to Salesforce, fetching the data is as easy as issuing an SQL query. Place this code right before the place where the homeTab variable is defined:

const result = await conn.query(
  `SELECT Name, Description FROM Contact`
);
let records = result.records;

let fields = records.map((record) => {
  return `*${record.Name}*: ${record.Description}`;
});

Then, at the bottom of the blocks method call, add these lines, which represent the UI you’re constructing out of Block Kit:

Blocks.Section({
  text: `It's ${event_ts}, and you are successfully authenticated to Salesforce as ${username}.`
}),
Blocks.Header({ text: 'Contacts' }),
Blocks.Divider(),
Blocks.Section({
  text: fields.join('\n')
})

If you navigate back to your Slack App’s Home tab, you’ll see your organization’s list of contacts!

Learning more

We’ve built a Slack app that fetches data from Salesforce and presents that data in a UI using a framework called Block Kit. In our next post, we’ll send data from Slack back to Salesforce!

Before then, you might want to familiarize yourself with how Block Kit works. Slack provides the Block Kit Builder, which is a playground for their UI elements. Under the hood, the Slack Starter Kit uses the Block Builder to simplify the UI assemblage we worked with.