@bolomio/salesforce-connector

The @bolomio/salesforce-connector package provides a connector that allows you to interact with the standard Salesforce API. It offers functions for creating records, executing SOQL and SOSL queries, and more.

Features

Interact with standard salesforce api
Create SObject Record
Update SObject Record
Upsert SObject Record by External ID
Execute Composite Request
Execute SOQL query
Execute SOSL query
Interact with custom apex rest api.
Get Knowledge Articles List using Knowledge Article API

Installation

You can install the package using npm:

npm install @bolomio/salesforce-connector

Usage

To use the Salesforce Connector, you need to create an instance of it by calling the makeSalesforceConnector function with the required configurations.

const { makeSalesforceConnector } = require('@bolomio/salesforce-connector')

// Create the Salesforce Connector instance
const connector = makeSalesforceConnector({
  baseUrl: 'https://your-salesforce-instance.com/',
  accessToken: 'your_access_token',
})

Authorization

To authorize your requests, you have multiple options:

Pass the access token directly in the options when creating the connector instance. NB: if the access token is passed - a before request hook will be created to set the token in the authentication header.

const { makeSalesforceConnector } = require('@bolomio/salesforce-connector')

// Create the Salesforce Connector instance
const connector = makeSalesforceConnector({
  baseUrl: 'https://your-salesforce-instance.com/',
  accessToken: 'your_access_token',
})

Set the authorization header yourself in the beforeRequest hook.

const { makeSalesforceConnector } = require('@bolomio/salesforce-connector')

// Create the Salesforce Connector instance
const connector = makeSalesforceConnector({
  baseUrl: 'https://your-salesforce-instance.com/',
  hooks: {
    beforeRequest: [
      (options) => {
        console.log('Setting token')
        options.headers['Authorization'] = 'Bearer {your_access_token}'
      },
    ],
  },
})

Make sure to replace 'https://your-salesforce-instance.com/' with the actual Salesforce instance URL and 'your_access_token' with the valid access token obtained through a secure authentication process.

Note: to receive an access token you can use the @bolomio/salesforce-authorizer

Functions

composite

Executes a collection of standard api requests

async function compositeExample() {
  try {
    const result = await connector.composite({
      allOrNone: true,
      compositeRequest: [
        connector.compositeRequests.soqlQuery({
          referenceId: 'reference_id_account_1',
          queryStatement: 'SELECT Id FROM Account LIMIT 1',
        }),
        connector.compositeRequests.createSObject({
          record: {
            LastName: 'Koko',
            AccountId: '@{reference_id_account_1.records[0].Id}',
          },
          sObjectName: 'Contact',
          referenceId: 'reference_id_contact_1',
        }),
      ],
    })
    console.log('1 composite executed successfully:', result.compositeResponse[0])
    console.log('2 composite executed successfully:', result.compositeResponse[1])
  } catch (error) {
    console.error('Error executing composite:', error)
  }
}

compositeExample()

createSObject

Create a new record of a specific Salesforce object using the provided data.

async function createSObjectExample() {
  const sObjectName = 'Account'
  const record = {
    Name: 'Acme Corporation',
    Industry: 'Technology',
  }

  try {
    const result = await connector.createSObject({ sObjectName, record })
    console.log('Record created successfully:', result)
  } catch (error) {
    console.error('Error creating record:', error)
  }
}

createSObjectExample()

updateSObject

Update a record of a specific Salesforce object using the provided data.

async function updateSObjectExample() {
  const sObjectName = 'Account'
  const recordId = '0011t00000B0lOMAAZ'
  const record = {
    Name: 'Acme Corporation',
    Industry: 'Technology',
  }

  try {
    await connector.updateSObject({ sObjectName, recordId, record })
    console.log('Record updated successfully')
  } catch (error) {
    console.error('Error updating record:', error)
  }
}

updateSObjectExample()

upsertSObjectByExternalId

Insert or Update (Upsert) a Record Using an External ID.

async function upsertSObjectByExternalIdExample() {
  const sObjectName = 'Account'
  const sObjectFieldName = 'AccountExternalId__c'
  const externalId = 'Account-123'
  const record = {
    Name: 'Acme Corporation',
    Industry: 'Technology',
  }

  try {
    const result = await connector.upsertSObjectByExternalId({ sObjectName, sObjectFieldName, externalId, record })
    console.log('Record upserted successfully:', result)
  } catch (error) {
    console.error('Error upserting record:', error)
  }
}

upsertSObjectByExternalIdExample()

soqlQuery

Execute a SOQL (Salesforce Object Query Language) query and retrieve the results.

async function soqlQueryExample() {
  const queryStatement = 'SELECT Id, Name, Industry FROM Account WHERE Industry = \'Technology\''

  try {
    const result = await connector.soqlQuery({ queryStatement })
    console.log('Query results:', result)
  } catch (error) {
    console.error('Error executing SOQL query:', error)
  }
}

soqlQueryExample()

soslQuery

Execute a SOSL (Salesforce Object Search Language) query and retrieve the results.

async function soslQueryExample() {
  const queryConfiguration: {
      q: '00001',
      in: 'PHONE',
      fields: ['Name'],
      sobjects: [{ name: 'Contact' }],
    }

  try {
    const result = await connector.soslQuery({ queryConfiguration })
    console.log('Query results:', result)
  } catch (error) {
    console.error('Error executing SOSL query:', error)
  }
}

soslQueryExample()

apexRest

Execute a http request against a custom apex rest endpoint. Salesforce Documentation

Get Example

async function apexRestGetExample() {
  const companyId = 'bolo-id'

  try {
    const result = await connector.apexRest({
      method: 'GET',
      requestURI: `/bolo-companies/${companyId}`,
    })
    console.log('Get result:', result)
  } catch (error) {
    console.error('Error executing get request: ', error)
  }
}

apexRestGetExample()

Put Example

async function apexRestPutExample() {
  const companyId = 'bolo-id'
  
  // the json body to be used in the request
  const json = {
    name: 'bolo'
  }

  try {
    const result = await connector.apexRest({
      method: 'PUT',
      requestURI: `/bolo-companies/${companyId}`,
      json
    })
    console.log('Put result:', result)
  } catch (error) {
    console.error('Error executing put request: ', error)
  }
}

apexRestPutExample()

Post Example with no content response

async function apexRestPostWithNoContentResponseExample() {
  // the json body to be used in the request
  const json = {
    name: 'bolo'
  }

  try {
    await connector.apexRest({
      method: 'POST',
      requestURI: `/bolo-companies/`,
      json
    })
  } catch (error) {
    console.error('Error executing post request: ', error)
  }
}

apexRestPostWithNoContentResponseExample()

getKnowledgeArticlesList

Execute an http request against the Knowledge Article API to list articles. Salesforce Documentation

Get Knowledge Articles List Example

async function getKnowledgeArticlesListExample() {
  const language = 'en-US'

  try {
    const result = await connector.getKnowledgeArticlesList({ 
      language,
      queryParams: {
        sort: 'ViewScore',
        channel: 'Pkb',
        pageSize: 10,
      }
    })
    console.log('Knowledge result:', result)
  } catch (error) {
    console.error('Error executing get request: ', error)
  }
}

Upcoming

Other features will be added that use the standard salesforce api:

Contributing

Contributions are welcome! If you encounter any issues or have suggestions for improvements, please feel free to open an issue or submit a pull request. Make sure to follow the contribution guidelines.

License

This project is licensed under the GNU General Public License.