Automatically creating Salesforce contacts when a user signs up

This guide will show you how to use Sequin to automatically create a Salesforce contact when a user signs up for your app.

Use cases

Creating a new Salesforce Contact when a user signs up for your app is a common use case. It allows you to keep your Salesforce instance up to date with the latest user data so your sales, support, and operations teams can work with reliable customer data.

Building a reliable integration with Salesforce and your application using Sequin comes with several benefits:

Maintainability

Simplifying your integration into a single transaction makes your code easier to maintain. You don't need to track down errors in your client-side code or investigate issues with your data pipeline.

Guarantees

A user missing its paired Salesforce contact is a regular, painful problem. There are many reasons why a user might not be synced to Salesforce, but a very common one is that your client-side code (often provided by an analytics tool like Segment) is being blocked by a browser extension. Or, your pipeline / ETL is hitting an error. By creating a direct server-side integration between Salesforce and your application you couple your logic for creating a user with your logic for creating a Salesforce contact. This ensures that a user is always synced to Salesforce when they are created.

Also, when you create a user and a Salesforce contact in the same transaction, you can ensure that the data in your Salesforce instance is clean and consistent. Any error that would cause drift can be handled in-line. For instance, you can ensure that their email is valid before letting the user move on. You can catch duplicates, or, you can ensure that the user's first name and last name are synced to the contact to create personalization. This is especially important if you are using Salesforce as a source of truth for sales and support communications.

Pre-requisites

This tutorial will assume you've followed the Salesforce setup guide to connect your Salesforce instance and database to Sequin. If you haven't, check out our guide on syncing Salesforce with Sequin. Ensure you are syncing the Contact collection to your database.

This tutorial will use node.js and the node-postgres library to automatically create a Salesforce contact when a user signs up for your app. We'll assume you already have a node project setup with pg installed. If you don't, you can follow the node-postgres getting started guide to get up and running.

Step 1: Setup pg clients

First, create a connection to your database using pg. As a best practice, we recommend configuring two Postgres clients in your application so you can route Salesforce queries through the Sequin proxy and route other queries directly to your database.

Direct client

Configure a pg client that connects directly to your database. Queries through this client will be executed directly against your database without any Sequin dependency. You should use this client for all read and write operations that don't touch your Salesforce data - for instance, creating a user account.

require("dotenv").config();
const { Pool } = require("pg");

const direct = new Pool({
  user: "postgres",
  host: "your.database.host",
  database: "yourDatabaseName",
  password: process.env.DIRECT_DB_PASSWORD,
  port: 5432,
});

Friendly reminder: never store your database credentials in your application code. Use environment variables to store your credentials and load them into your application at runtime. For node.js, you can use a .env file and the dotenv library.

Sequin proxy client

Configure another 'pg' client - but this time configure it to connect to the Sequin Postgres Proxy.

You'll find the connection details for your Sequin proxy in the Sequin console. Select your sync and then navigate to the Connection instructions tab to find your proxy user, host, and password. Then enter them into another pg client configuration:

const salesforceProxy = new Pool({
  user: "sequin_▒▒▒▒▒▒.▒▒▒▒▒▒",
  host: "proxy.sequindb.io",
  database: "yourDatabaseName",
  password: process.env.SALESFORCE_DB_PASSWORD,
  port: 5432,
});

Queries through this client will pass through Sequin to ensure any mutations are applied to Salesforce. You should use this client for write operations that touch your Salesforce data - in this tutorial, creating a new contact.

Step 2: Create contact

Now that you have two pg clients configured, you can write a query to create a new contact in Salesforce.

You'll use the salesforce Postgres client to execute this query so that Sequin can sync the new contact to Salesforce. Here is a simple function that will create a new contact in Salesforce:

const createNewContact = async (user, id) => {
  const client = await salesforceProxy.connect();

  try {
    const res = await client.query(
      `INSERT INTO salesforce.contact (first_name, last_name, email, user_id__c) VALUES ('${user.first_name}', '${user.last_name}', '${user.email}', '${id}');`
    );
    console.log(res);
  } catch (error) {
    console.error("Error creating contact:", error);
    throw new Error(error);
  } finally {
    client.release();
  }
};

This function is designed to be called after a user is created. It takes in the user object and the user's id, opens a connection to the database, and then inserts a new contact into Salesforce. The user_id__c field is a custom field on the Salesforce contact object that will link the Salesforce contact to the user. If the contact is successfully created, the connection to the database is closed. If there is an error - for instance a duplicate user is found - a new error will be thrown. This allows you to handle the error in your application code - perhaps letting the new user know that they already have an account.

Step 3: Create user

Now, incorporate the createNewContact() function into your user creation flow. Here is a simple example of a user creation flow that uses the createNewContact function:

const createNewUser = async (user) => {
  const client = await direct.connect();

  try {
    await client.query("BEGIN");
    const newUser = await client.query(
      "INSERT INTO users (first_name, last_name, email) VALUES ($1, $2, $3) RETURNING id",
      [user.first_name, user.last_name, user.email]
    );
    await createNewContact(user, newUser.rows[0].id);
    await client.query("COMMIT");
    console.log("New user created successfully!");
  } catch (error) {
    await client.query("ROLLBACK");
    console.error("Error creating user:", error);
  } finally {
    client.release();
  }
};

This function is designed to be called when a user signs up for your app. It takes in the user object, opens a connection to the database, and starts a new transaction. It then attempts to create a new user before calling the createNewContact function to create a new contact in Salesforce. If both the user and the contact are successfully created, the transaction is committed. If there is an error - for instance the user's email is invalid - the transaction is rolled back. This ensures that the user and the contact are always created together.

Next steps

You've successfully created a new Salesforce contact when a user signs up for your app. This approach ensures every user will be paired to a Salesforce contact upon creation. It also allows you to leverage your business logic in Salesforce to ensure new users have valid emails and are not duplicated, for example.

From here, you can also use this approach to create other Salesforce objects when a user signs up - for instance, mapping the user to a new or existing Salesforce account. Or automatically creating a new opportunity and assigning it to a sales rep.