CRM Integration

Pitcher CatalogIQ can integrate with different CRM systems. This guide explains how to integrate with Salesforce and Microsoft Dynamics.

Salesforce Integration

When the instance is configured to have CRM integration enabled and the user is logged in with Salesforce, your app will have access to the Salesforce API token.

Using this token, you can make requests to the Salesforce API to get data from Salesforce. We recommend using the official jsforce library to make requests to the Salesforce API.

On rare occasions it may happen your requests will fail because the token has expired. In this case, you can use the refreshServiceToken method to get the refreshed token.

Using jsforce directly

import { usePitcherApi } from '@pitcher/canvas-ui'
import jsforce from 'jsforce'

const setupSalesforceConnection = async () => {
  const env = await usePitcherApi().getEnv()
  
  // Find Salesforce service
  const salesforceService = env.pitcher.user.connected_services.find(
    service => service.type === 'crm' && service.provider === 'salesforce'
  )
  
  if (!salesforceService) {
    return null
  }
  
  // Create jsforce connection
  const connection = new jsforce.Connection({
    instanceUrl: salesforceService.urls.custom_domain,
    accessToken: salesforceService.access_token
  })
  
  return connection
}

// Query data with jsforce
const queryAccounts = async () => {
  const connection = await setupSalesforceConnection()
  if (!connection) return []
  
  const result = await connection.query('SELECT Id, Name FROM Account LIMIT 10')
  return result.records
}

Store-Based Approach

The recommended pattern is to create a Salesforce authentication store that manages the CRM connection:

// Example of a minimal sf-auth store
export const useSFAuth = defineStore('sfAuth', () => {
  const { env } = storeToRefs(useAppStore())
  const connection = ref(null)
  
  const init = async () => {
    // Find CRM service in connected_services
    const crmService = env.value?.pitcher.user.connected_services
      .find(service => service.type === 'crm')
    
    if (crmService) {
      // Create connection clients for query, sobject, etc.
      connection.value = {
        query: createSfdcQueryClient(crmService.access_token, crmService.urls.query),
        sobject: createSfdcEntityClient(crmService.access_token, crmService.urls.sobjects)
      }
    }
  }
  
  return { connection, init }
})

Using the Connection

With the store initialized, you can use it to query Salesforce data:

// In your component
const { connection } = storeToRefs(useSFAuth())

// Execute a SOQL query
const fetchAccounts = async () => {
  const result = await connection.value?.query('SELECT Id, Name FROM Account LIMIT 10')
  return result?.records || []
}

// Create a record
const createContact = async (data) => {
  return await connection.value?.sobject('Contact', { data })
}

Using the crmQuery API

For simple queries, you can use the built-in crmQuery method:

import { usePitcherApi } from '@pitcher/canvas-ui'

// Execute a CRM query
const accounts = await usePitcherApi().crmQuery({
  query: 'SELECT Id, Name FROM Account LIMIT 10',
  service: 'salesforce' // Optional, defaults to primary CRM service
})

Microsoft Dynamics Integration

When the instance is configured to have CRM integration enabled and user is logged in with Microsoft Dynamics, the app will have access to the Dynamics API token.

The approach to access the Dynamics token is similar to Salesforce:

// Get Dynamics service
const dynamicsService = env.pitcher.user.connected_services.find(
  service => service.provider === 'dynamics' && service.type === 'crm'
)

if (dynamicsService) {
  // Access token for API calls
  const accessToken = dynamicsService.access_token
  
  // URLs for Dynamics endpoints
  const apiUrl = dynamicsService.urls.api
}

For more detailed information on integrating with Microsoft Dynamics, please refer to our Microsoft Dynamics Integration Guide.

Detecting CRM Availability

You can check if CRM integration is available in your app:

// Check if user has any CRM connection
const isCrmAvailable = computed(() => 
  env.value?.pitcher.user.connected_services.some(service => service.type === 'crm')
)