A REST API wrapper for interacting with Salesforce using the Go programming language.
- Read my blog post for an in-depth example
- Read the Salesforce REST API documentation
- Read the Golang documentation
- Installation
- Types
- Authentication
- SOQL
- SObject Single Record Operations
- SObject Collections
- Composite Requests
- Bulk v2
- Other
- Contributing
go get github.com/k-capehart/go-salesforce/v2
type Salesforce struct {
auth *authentication
}
type Creds struct {
Domain string
Username string
Password string
SecurityToken string
ConsumerKey string
ConsumerSecret string
ConsumerRSAPem string
AccessToken string
}
type SalesforceResults struct {
Results []SalesforceResult
HasSalesforceErrors bool
}
type SalesforceResult struct {
Id string
Errors []SalesforceErrorMessage
Success bool
}
type SalesforceErrorMessage struct {
Message string
StatusCode string
Fields []string
}
type BulkJobResults struct {
Id string
State string
NumberRecordsFailed int
ErrorMessage string
SuccessfulRecords []map[string]any
FailedRecords []map[string]any
}
- To begin using, create an instance of the
Salesforce
type by callingsalesforce.Init()
and passing your credentials as arguments - Once authenticated, all other functions can be called as methods using the resulting
Salesforce
instance
func Init(creds Creds) *Salesforce
Returns a new Salesforce instance given a user's credentials.
creds
: a struct containing the necessary credentials to authenticate into a Salesforce org- Creating a Connected App in Salesforce
- Review Salesforce oauth flows
- If an operation fails with the Error Code
INVALID_SESSION_ID
, go-salesforce will attempt to refresh the session by resubmitting the same credentials used during initialization
sf, err := salesforce.Init(salesforce.Creds{
Domain: DOMAIN,
ConsumerKey: CONSUMER_KEY,
ConsumerSecret: CONSUMER_SECRET,
})
if err != nil {
panic(err)
}
sf, err := salesforce.Init(salesforce.Creds{
Domain: DOMAIN,
Username: USERNAME,
Password: PASSWORD,
SecurityToken: SECURITY_TOKEN,
ConsumerKey: CONSUMER_KEY,
ConsumerSecret: CONSUMER_SECRET,
})
if err != nil {
panic(err)
}
sf, err := salesforce.Init(salesforce.Creds{
Domain: DOMAIN,
Username: USERNAME,
ConsumerKey: CONSUMER_KEY,
ConsumerRSAPem: CONSUMER_RSA_PEM,
})
if err != nil {
panic(err)
}
Authenticate with an Access Token
- Implement your own OAuth flow and use the resulting
access_token
from the response to initialize go-salesforce
sf, err := salesforce.Init(salesforce.Creds{
Domain: DOMAIN,
AccessToken: ACCESS_TOKEN,
})
if err != nil {
panic(err)
}
func (sf *Salesforce) GetAccessToken() string
Returns the current session's Access Token as a string.
token := sf.GetAccessToken()
Query Salesforce records
func (sf *Salesforce) Query(query string, sObject any) error
Performs a SOQL query given a query string and decodes the response into the given struct
query
: a SOQL querysObject
: a slice of a custom struct type representing a Salesforce Object
type Contact struct {
Id string
LastName string
}
contacts := []Contact{}
err := sf.Query("SELECT Id, LastName FROM Contact WHERE LastName = 'Lee'", &contacts)
if err != nil {
panic(err)
}
func (sf *Salesforce) QueryStruct(soqlStruct any, sObject any) error
Performs a SOQL query given a go-soql struct and decodes the response into the given struct
soqlStruct
: a custom struct usingsoql
tagssObject
: a slice of a custom struct type representing a Salesforce Object- Review forcedotcom/go-soql
- Eliminates need to separately maintain query string and struct
- Helps prevent SOQL injection
type Contact struct {
Id string `soql:"selectColumn,fieldName=Id" json:"Id"`
LastName string `soql:"selectColumn,fieldName=LastName" json:"LastName"`
}
type ContactQueryCriteria struct {
LastName string `soql:"equalsOperator,fieldName=LastName"`
}
type ContactSoqlQuery struct {
SelectClause Contact `soql:"selectClause,tableName=Contact"`
WhereClause ContactQueryCriteria `soql:"whereClause"`
}
soqlStruct := ContactSoqlQuery{
SelectClause: Contact{},
WhereClause: ContactQueryCriteria{
LastName: "Lee",
},
}
contacts := []Contact{}
err := sf.QueryStruct(soqlStruct, &contacts)
if err != nil {
panic(err)
}
When querying Salesforce objects, it's common to access fields that are related through parent-child or lookup relationships. For instance, querying Account.Name
with related Contact
might look like this:
SELECT Id, Account.Name FROM Contact
To effectively handle the data returned by this query, define your Go structs as follows:
type ContentDocumentLink struct {
Id string
Account Account
}
type Account struct {
Name string
}
Insert, Update, Upsert, or Delete one record at a time
- Review Salesforce REST API resources for working with records
- Only Insert and Upsert will return an instance of
SalesforceResult
, which contains the record ID - DML errors result in a status code of 400
func (sf *Salesforce) InsertOne(sObjectName string, record any) (SalesforceResult, error)
InsertOne inserts one salesforce record of the given type
sObjectName
: API name of Salesforce objectrecord
: a Salesforce object record
type Contact struct {
LastName string
}
contact := Contact{
LastName: "Stark",
}
result, err := sf.InsertOne("Contact", contact)
if err != nil {
panic(err)
}
func (sf *Salesforce) UpdateOne(sObjectName string, record any) error
Updates one salesforce record of the given type
sObjectName
: API name of Salesforce objectrecord
: a Salesforce object record- An Id is required
type Contact struct {
Id string
LastName string
}
contact := Contact{
Id: "003Dn00000pEYQSIA4",
LastName: "Banner",
}
err := sf.UpdateOne("Contact", contact)
if err != nil {
panic(err)
}
func (sf *Salesforce) UpsertOne(sObjectName string, externalIdFieldName string, record any) (SalesforceResult, error)
Updates (or inserts) one salesforce record using the given external Id
sObjectName
: API name of Salesforce objectexternalIdFieldName
: field API name for an external Id that exists on the given objectrecord
: a Salesforce object record- A value for the External Id is required
type ContactWithExternalId struct {
ContactExternalId__c string
LastName string
}
contact := ContactWithExternalId{
ContactExternalId__c: "Avng0",
LastName: "Rogers",
}
result, err := sf.UpsertOne("Contact", "ContactExternalId__c", contact)
if err != nil {
panic(err)
}
func (sf *Salesforce) DeleteOne(sObjectName string, record any) error
Deletes a Salesforce record
sObjectName
: API name of Salesforce objectrecord
: a Salesforce object record- Should only contain an Id
type Contact struct {
Id string
}
contact := Contact{
Id: "003Dn00000pEYQSIA4",
}
err := sf.DeleteOne("Contact", contact)
if err != nil {
panic(err)
}
Insert, Update, Upsert, or Delete collections of records
- Review Salesforce REST API resources for working with collections
- Perform operations in batches of up to 200 records at a time
- Consider making a Bulk request for very large operations
- Partial successes are enabled
- If a record fails then successes are still committed to the database
- Will return an instance of
SalesforceResults
which contains information on each affected record and whether DML errors were encountered
func (sf *Salesforce) InsertCollection(sObjectName string, records any, batchSize int) (SalesforceResults, error)
Inserts a list of salesforce records of the given type
sObjectName
: API name of Salesforce objectrecords
: a slice of salesforce recordsbatchSize
:1 <= batchSize <= 200
type Contact struct {
LastName string
}
contacts := []Contact{
{
LastName: "Barton",
},
{
LastName: "Romanoff",
},
}
results, err := sf.InsertCollection("Contact", contacts, 200)
if err != nil {
panic(err)
}
func (sf *Salesforce) UpdateCollection(sObjectName string, records any, batchSize int) (SalesforceResults, error)
Updates a list of salesforce records of the given type
sObjectName
: API name of Salesforce objectrecords
: a slice of salesforce records- An Id is required
batchSize
:1 <= batchSize <= 200
type Contact struct {
Id string
LastName string
}
contacts := []Contact{
{
Id: "003Dn00000pEfyAIAS",
LastName: "Fury",
},
{
Id: "003Dn00000pEfy9IAC",
LastName: "Odinson",
},
}
results, err := sf.UpdateCollection("Contact", contacts, 200)
if err != nil {
panic(err)
}
func (sf *Salesforce) UpsertCollection(sObjectName string, externalIdFieldName string, records any, batchSize int) (SalesforceResults, error)
Updates (or inserts) a list of salesforce records using the given ExternalId
sObjectName
: API name of Salesforce objectexternalIdFieldName
: field API name for an external Id that exists on the given objectrecords
: a slice of salesforce records- A value for the External Id is required
batchSize
:1 <= batchSize <= 200
type ContactWithExternalId struct {
ContactExternalId__c string
LastName string
}
contacts := []ContactWithExternalId{
{
ContactExternalId__c: "Avng1",
LastName: "Danvers",
},
{
ContactExternalId__c: "Avng2",
LastName: "Pym",
},
}
results, err := sf.UpsertCollection("Contact", "ContactExternalId__c", contacts, 200)
if err != nil {
panic(err)
}
func (sf *Salesforce) DeleteCollection(sObjectName string, records any, batchSize int) (SalesforceResults, error)
Deletes a list of salesforce records
sObjectName
: API name of Salesforce objectrecords
: a slice of salesforce records- Should only contain Ids
batchSize
:1 <= batchSize <= 200
type Contact struct {
Id string
}
contacts := []Contact{
{
Id: "003Dn00000pEfyAIAS",
},
{
Id: "003Dn00000pEfy9IAC",
},
}
results, err := sf.DeleteCollection("Contact", contacts, 200)
if err != nil {
panic(err)
}
Make numerous 'subrequests' contained within a single 'composite request', reducing the overall number of calls to Salesforce
- Review Salesforce REST API resources for making composite requests
- Up to 25 subrequests may be included in a single composite request
- For DML operations, max number of records to be processed is determined by batch size (
25 * (batch size)
) - So if batch size is 1, then max number of records to be included in request is 25
- If batch size is 200, then max is 5000
- For DML operations, max number of records to be processed is determined by batch size (
- Can optionally allow partial successes by setting allOrNone parameter
- If true, then successes are still committed to the database even if a record fails
- Will return an instance of SalesforceResults which contains information on each affected record and whether DML errors were encountered
func (sf *Salesforce) InsertComposite(sObjectName string, records any, batchSize int, allOrNone bool) (SalesforceResults, error)
Inserts a list of salesforce records in a single request
sObjectName
: API name of Salesforce objectrecords
: a slice of salesforce recordsbatchSize
:1 <= batchSize <= 200
allOrNone
: denotes whether to roll back entire operation if a record fails
type Contact struct {
LastName string
}
contacts := []Contact{
{
LastName: "Parker",
},
{
LastName: "Murdock",
},
}
results, err := sf.InsertComposite("Contact", contacts, 200, true)
if err != nil {
panic(err)
}
func (sf *Salesforce) UpdateComposite(sObjectName string, records any, batchSize int, allOrNone bool) (SalesforceResults, error)
Updates a list of salesforce records in a single request
sObjectName
: API name of Salesforce objectrecords
: a slice of salesforce records- An Id is required
batchSize
:1 <= batchSize <= 200
allOrNone
: denotes whether to roll back entire operation if a record fails
type Contact struct {
Id string
LastName string
}
contacts := []Contact{
{
Id: "003Dn00000pEi32IAC",
LastName: "Richards",
},
{
Id: "003Dn00000pEi31IAC",
LastName: "Storm",
},
}
results, err := sf.UpdateComposite("Contact", contacts, 200, true)
if err != nil {
panic(err)
}
func (sf *Salesforce) UpsertComposite(sObjectName string, externalIdFieldName string, records any, batchSize int, allOrNone bool) (SalesforceResults, error)
Updates (or inserts) a list of salesforce records using the given ExternalId in a single request
sObjectName
: API name of Salesforce objectexternalIdFieldName
: field API name for an external Id that exists on the given objectrecords
: a slice of salesforce records- A value for the External Id is required
batchSize
:1 <= batchSize <= 200
allOrNone
: denotes whether to roll back entire operation if a record fails
type ContactWithExternalId struct {
ContactExternalId__c string
LastName string
}
contacts := []ContactWithExternalId{
{
ContactExternalId__c: "Avng3",
LastName: "Maximoff",
},
{
ContactExternalId__c: "Avng4",
LastName: "Wilson",
},
}
results, err := sf.UpsertComposite("Contact", "ContactExternalId__c", contacts, 200, true)
if err != nil {
panic(err)
}
func (sf *Salesforce) DeleteComposite(sObjectName string, records any, batchSize int, allOrNone bool) (SalesforceResults, error)
Deletes a list of salesforce records in a single request
sObjectName
: API name of Salesforce objectrecords
: a slice of salesforce records- Should only contain Ids
batchSize
:1 <= batchSize <= 200
allOrNone
: denotes whether to roll back entire operation if a record fails
type Contact struct {
Id string
}
contacts := []Contact{
{
Id: "003Dn00000pEi0OIAS",
},
{
Id: "003Dn00000pEi0NIAS",
},
}
results, err := sf.DeleteComposite("Contact", contacts, 200, true)
if err != nil {
panic(err)
}
Create Bulk API Jobs to query, insert, update, upsert, and delete large collections of records
- Review Salesforce REST API resources for Bulk v2
- Work with large lists of records by passing either a slice or records or the path to a csv file
- Jobs can run asynchronously or synchronously
func (sf *Salesforce) QueryBulkExport(query string, filePath string) error
Performs a query and exports the data to a csv file
filePath
: name and path of a csv file to be createdquery
: a SOQL query
err := sf.QueryBulkExport("SELECT Id, FirstName, LastName FROM Contact", "data/export.csv")
if err != nil {
panic(err)
}
func (sf *Salesforce) QueryStructBulkExport(soqlStruct any, filePath string) error
Performs a SOQL query given a go-soql struct and decodes the response into the given struct
filePath
: name and path of a csv file to be createdsoqlStruct
: a custom struct usingsoql
tags- Review forcedotcom/go-soql
- Eliminates need to separately maintain query string and struct
- Helps prevent SOQL injection
type ContactSoql struct {
Id string `soql:"selectColumn,fieldName=Id" json:"Id"`
FirstName string `soql:"selectColumn,fieldName=FirstName" json:"FirstName"`
LastName string `soql:"selectColumn,fieldName=LastName" json:"LastName"`
}
type ContactSoqlQuery struct {
SelectClause ContactSoql `soql:"selectClause,tableName=Contact"`
}
soqlStruct := ContactSoqlQuery{
SelectClause: ContactSoql{},
}
err := sf.QueryStructBulkExport(soqlStruct, "data/export2.csv")
if err != nil {
panic(err)
}
func (sf *Salesforce) QueryBulkIterator(query string) (IteratorJob, error)
Performs a query and return a IteratorJob to decode data
query
: a SOQL query
type Contact struct {
Id string `json:"Id" csv:"Id"`
FirstName string `json:"FirstName" csv:"FirstName"`
LastName string `json:"LastName" csv:"LastName"`
}
it, err := sf.QueryBulkIterator("SELECT Id, FirstName, LastName FROM Contact")
if err != nil {
panic(err)
}
for it.Next() {
var data []Contact
if err := it.Decode(&data); err != nil {
panic(err)
}
}
if err := it.Error(); err != nil {
panic(err)
}
func (sf *Salesforce) InsertBulk(sObjectName string, records any, batchSize int, waitForResults bool) ([]string, error)
Inserts a list of salesforce records using Bulk API v2, returning a list of Job IDs
sObjectName
: API name of Salesforce objectrecords
: a slice of salesforce recordsbatchSize
:1 <= batchSize <= 10000
waitForResults
: denotes whether to wait for jobs to finish
type Contact struct {
LastName string
}
contacts := []Contact{
{
LastName: "Lang",
},
{
LastName: "Van Dyne",
},
}
jobIds, err := sf.InsertBulk("Contact", contacts, 1000, false)
if err != nil {
panic(err)
}
func (sf *Salesforce) InsertBulkFile(sObjectName string, filePath string, batchSize int, waitForResults bool) ([]string, error)
Inserts a collection of salesforce records from a csv file using Bulk API v2, returning a list of Job IDs
sObjectName
: API name of Salesforce objectfilePath
: path to a csv file containing salesforce databatchSize
:1 <= batchSize <= 10000
waitForResults
: denotes whether to wait for jobs to finish
data/avengers.csv
FirstName,LastName
Tony,Stark
Steve,Rogers
Bruce,Banner
jobIds, err := sf.InsertBulkFile("Contact", "data/avengers.csv", 1000, false)
if err != nil {
panic(err)
}
func (sf *Salesforce) UpdateBulk(sObjectName string, records any, batchSize int, waitForResults bool) ([]string, error)
Updates a list of salesforce records using Bulk API v2, returning a list of Job IDs
sObjectName
: API name of Salesforce objectrecords
: a slice of salesforce records- An Id is required
batchSize
:1 <= batchSize <= 10000
waitForResults
: denotes whether to wait for jobs to finish
type Contact struct {
Id string
LastName string
}
contacts := []Contact{
{
Id: "003Dn00000pEsoRIAS",
LastName: "Strange",
},
{
Id: "003Dn00000pEsoSIAS",
LastName: "T'Challa",
},
}
jobIds, err := sf.UpdateBulk("Contact", contacts, 1000, false)
if err != nil {
panic(err)
}
func (sf *Salesforce) UpdateBulkFile(sObjectName string, filePath string, batchSize int, waitForResults bool) ([]string, error)
Updates a collection of salesforce records from a csv file using Bulk API v2, returning a list of Job IDs
sObjectName
: API name of Salesforce objectfilePath
: path to a csv file containing salesforce data- An Id is required within csv data
batchSize
:1 <= batchSize <= 10000
waitForResults
: denotes whether to wait for jobs to finish
data/update_avengers.csv
Id,FirstName,LastName
003Dn00000pEwRuIAK,Rocket,Raccoon
003Dn00000pEwQxIAK,Drax,The Destroyer
003Dn00000pEwQyIAK,Peter,Quill
003Dn00000pEwQzIAK,I Am,Groot
003Dn00000pEwR0IAK,Gamora,Zen Whoberi Ben Titan
003Dn00000pEwR1IAK,Mantis,Mantis
jobIds, err := sf.UpdateBulkFile("Contact", "data/update_avengers.csv", 1000, false)
if err != nil {
panic(err)
}
func (sf *Salesforce) UpsertBulk(sObjectName string, externalIdFieldName string, records any, batchSize int, waitForResults bool) ([]string, error)
Updates (or inserts) a list of salesforce records using Bulk API v2, returning a list of Job IDs
sObjectName
: API name of Salesforce objectexternalIdFieldName
: field API name for an external Id that exists on the given objectrecords
: a slice of salesforce records- A value for the External Id is required
batchSize
:1 <= batchSize <= 10000
waitForResults
: denotes whether to wait for jobs to finish
type ContactWithExternalId struct {
ContactExternalId__c string
LastName string
}
contacts := []ContactWithExternalId{
{
ContactExternalId__c: "Avng5",
LastName: "Rhodes",
},
{
ContactExternalId__c: "Avng6",
LastName: "Quill",
},
}
jobIds, err := sf.UpsertBulk("Contact", "ContactExternalId__c", contacts, 1000, false)
if err != nil {
panic(err)
}
func (sf *Salesforce) UpsertBulkFile(sObjectName string, externalIdFieldName string, filePath string, batchSize int, waitForResults bool) ([]string, error)
Updates (or inserts) a collection of salesforce records from a csv file using Bulk API v2, returning a list of Job IDs
sObjectName
: API name of Salesforce objectexternalIdFieldName
: field API name for an external Id that exists on the given objectfilePath
: path to a csv file containing salesforce data- A value for the External Id is required within csv data
batchSize
:1 <= batchSize <= 10000
waitForResults
: denotes whether to wait for jobs to finish
data/upsert_avengers.csv
ContactExternalId__c,FirstName,LastName
Avng7,Matt,Murdock
Avng8,Luke,Cage
Avng9,Jessica,Jones
Avng10,Danny,Rand
jobIds, err := sf.UpsertBulkFile("Contact", "ContactExternalId__c", "data/upsert_avengers.csv", 1000, false)
if err != nil {
panic(err)
}
func (sf *Salesforce) DeleteBulk(sObjectName string, records any, batchSize int, waitForResults bool) ([]string, error)
Deletes a list of salesforce records using Bulk API v2, returning a list of Job IDs
sObjectName
: API name of Salesforce objectrecords
: a slice of salesforce records- should only contain Ids
batchSize
:1 <= batchSize <= 10000
waitForResults
: denotes whether to wait for jobs to finish
type Contact struct {
Id string
}
contacts := []ContactIds{
{
Id: "003Dn00000pEsoRIAS",
},
{
Id: "003Dn00000pEsoSIAS",
},
}
jobIds, err := sf.DeleteBulk("Contact", contacts, 1000, false)
if err != nil {
panic(err)
}
func (sf *Salesforce) DeleteBulkFile(sObjectName string, filePath string, batchSize int, waitForResults bool) ([]string, error)
Deletes a collection of salesforce records from a csv file using Bulk API v2, returning a list of Job IDs
sObjectName
: API name of Salesforce objectfilePath
: path to a csv file containing salesforce data- should only contain Ids
batchSize
:1 <= batchSize <= 10000
waitForResults
: denotes whether to wait for jobs to finish
data/delete_avengers.csv
Id
003Dn00000pEwRuIAK
003Dn00000pEwQxIAK
003Dn00000pEwQyIAK
003Dn00000pEwQzIAK
003Dn00000pEwR0IAK
003Dn00000pEwR1IAK
jobIds, err := sf.DeleteBulkFile("Contact", "data/delete_avengers.csv", 1000, false)
if err != nil {
panic(err)
}
func (sf *Salesforce) GetJobResults(bulkJobId string) (BulkJobResults, error)
Returns an instance of BulkJobResults given a Job Id
bulkJobId
: the Id for a bulk API job- Use to check results of Bulk Job, including successful and failed records
type Contact struct {
LastName string
}
contacts := []Contact{
{
LastName: "Grimm",
},
}
jobIds, err := sf.InsertBulk("Contact", contacts, 1000, true)
if err != nil {
panic(err)
}
for _, id := range jobIds {
results, err := sf.GetJobResults(id) // returns an instance of BulkJobResults
if err != nil {
panic(err)
}
fmt.Println(results)
}
func (sf *Salesforce) DoRequest(method string, uri string, body []byte) (*http.Response, error)
Make a http call to Salesforce, returning a response to be parsed by the client
method
: request method ("GET", "POST", "PUT", "PATCH", "DELETE")uri
: uniform resource identifier (include everything after/services/data/apiVersion
)body
: json encoded body to be included in request
Example to call the /limits
endpoint
resp, err := sf.DoRequest(http.MethodGet, "/limits", nil)
if err != nil {
panic(err)
}
respBody, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(respBody))
Anyone is welcome to contribute.
- Open an issue or discussion post to track the effort
- Fork this repository, then clone it
- Place this in your own module's
go.mod
to enable testing local changesreplace github.com/k-capehart/go-salesforce/v2 => /path_to_local_fork/
- Run tests
go test -cover
- Generate code coverage output
go test -v -coverprofile cover.out && go tool cover -html cover.out -o cover.html
- Note that codecov does not count partial lines so calculations may differ
- Linting
- Install golangci-lint
golangci-lint run
- Create a PR and link the issue