Skip to content

iamber12/go-salesforce

BranchesTags
 
 

Repository files navigation

go-salesforce

A REST API wrapper for interacting with Salesforce using the Go programming language.

GoDoc Go Report Card codecov MIT License Mentioned in Awesome Go

Table of Contents

Installation

go get github.com/k-capehart/go-salesforce

Authentication

  • To begin using, create an instance of the Salesforce type by calling salesforce.Init() and passing your credentials as arguments
  • Once authenticated, all other functions can be called as methods using the resulting Salesforce instance

Types

type Salesforce struct {
    auth *authentication
}

type Creds struct {
    Domain         string
    Username       string
    Password       string
    SecurityToken  string
    ConsumerKey    string
    ConsumerSecret string
}

Init

func Init(creds Creds) *Salesforce

Returns a new Salesforce instance given a user's credentials.

Client Credentials Flow

sf, err := salesforce.Init(salesforce.Creds{
    Domain:         DOMAIN,
    ConsumerKey:    CONSUMER_KEY,
    ConsumerSecret: CONSUMER_SECRET,
})
if err != nil {
    panic(err)
}

Username-Password Flow

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)
}

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)
}

GetAccessToken()

func (sf *Salesforce) GetAccessToken() string

Returns the current session's Access Token as a string.

fmt.Println(sf.GetAccessToken())

SOQL

Query Salesforce records

Query

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 query
  • sObject: 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 = 'Capehart'", &contacts)
if err != nil {
    panic(err)
}

QueryStruct

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 using soql tags
  • sObject: 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: "Capehart",
    },
}
contacts := []Contact{}
err := sf.QueryStruct(soqlStruct, &contacts)
if err != nil {
    panic(err)
}

Handling Relationship Queries

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:

Example SOQL Query
SELECT Id, Account.Name FROM Contact

Corresponding Go Structs

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
}

SObject Single Record Operations

Insert, Update, Upsert, or Delete one record at a time

InsertOne

func (sf *Salesforce) InsertOne(sObjectName string, record any) error

InsertOne inserts one salesforce record of the given type

  • sObjectName: API name of Salesforce object
  • record: a Salesforce object record
type Contact struct {
    LastName string
}
contact := Contact{
    LastName: "Stark",
}
err := sf.InsertOne("Contact", contact)
if err != nil {
    panic(err)
}

UpdateOne

func (sf *Salesforce) UpdateOne(sObjectName string, record any) error

Updates one salesforce record of the given type

  • sObjectName: API name of Salesforce object
  • record: 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)
}

UpsertOne

func (sf *Salesforce) UpsertOne(sObjectName string, externalIdFieldName string, record any) error

Updates (or inserts) one salesforce record using the given external Id

  • sObjectName: API name of Salesforce object
  • externalIdFieldName: field API name for an external Id that exists on the given object
  • record: 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",
}
err := sf.UpsertOne("Contact", "ContactExternalId__c", contact)
if err != nil {
    panic(err)
}

DeleteOne

func (sf *Salesforce) DeleteOne(sObjectName string, record any) error

Deletes a Salesforce record

  • sObjectName: API name of Salesforce object
  • record: a Salesforce object record
    • Should only contain an Id
type Contact struct {
    Id       string
}
contact := Contact{
    Id: "003Dn00000pEYQSIA4",
}
deleteErr := sf.DeleteOne("Contact", contact)
if deleteErr != nil {
    panic(deleteErr)
}

SObject Collections

Insert, Update, Upsert, or Delete collections of records

InsertCollection

func (sf *Salesforce) InsertCollection(sObjectName string, records any, batchSize int) error

Inserts a list of salesforce records of the given type

  • sObjectName: API name of Salesforce object
  • records: a slice of salesforce records
  • batchSize: 1 <= batchSize <= 200
type Contact struct {
    LastName string
}
contacts := []Contact{
    {
        LastName: "Barton",
    },
    {
        LastName: "Romanoff",
    },
}
err := sf.InsertCollection("Contact", contacts, 200)
if err != nil {
    panic(err)
}

UpdateCollection

func (sf *Salesforce) UpdateCollection(sObjectName string, records any, batchSize int) error

Updates a list of salesforce records of the given type

  • sObjectName: API name of Salesforce object
  • records: 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",
    },
}
err := sf.UpdateCollection("Contact", contacts, 200)
if err != nil {
    panic(err)
}

UpsertCollection

func (sf *Salesforce) UpsertCollection(sObjectName string, externalIdFieldName string, records any, batchSize int) error

Updates (or inserts) a list of salesforce records using the given ExternalId

  • sObjectName: API name of Salesforce object
  • externalIdFieldName: field API name for an external Id that exists on the given object
  • records: 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",
    },
}
err := sf.UpsertCollection("Contact", "ContactExternalId__c", contacts, 200)
if err != nil {
    panic(err)
}

DeleteCollection

func (sf *Salesforce) DeleteCollection(sObjectName string, records any, batchSize int) error

Deletes a list of salesforce records

  • sObjectName: API name of Salesforce object
  • records: a slice of salesforce records
    • Should only contain Ids
  • batchSize: 1 <= batchSize <= 200
type Contact struct {
    Id       string
}
contacts := []Contact{
    {
        Id: "003Dn00000pEfyAIAS",
    },
    {
        Id: "003Dn00000pEfy9IAC",
    },
}
err := sf.DeleteCollection("Contact", contacts, 200)
if err != nil {
    panic(err)
}

Composite Requests

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

InsertComposite

func (sf *Salesforce) InsertComposite(sObjectName string, records any, batchSize int, allOrNone bool) error

Inserts a list of salesforce records in a single request

  • sObjectName: API name of Salesforce object
  • records: a slice of salesforce records
  • batchSize: 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",
    },
}
err := sf.InsertComposite("Contact", contacts, 200, true)
if err != nil {
    panic(err)
}

UpdateComposite

func (sf *Salesforce) UpdateComposite(sObjectName string, records any, batchSize int, allOrNone bool) error

Updates a list of salesforce records in a single request

  • sObjectName: API name of Salesforce object
  • records: 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",
    },
}
err := sf.UpdateComposite("Contact", contacts, 200, true)
if err != nil {
    panic(err)
}

UpsertComposite

func (sf *Salesforce) UpsertComposite(sObjectName string, externalIdFieldName string, records any, batchSize int, allOrNone bool) error

Updates (or inserts) a list of salesforce records using the given ExternalId in a single request

  • sObjectName: API name of Salesforce object
  • externalIdFieldName: field API name for an external Id that exists on the given object
  • records: 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",
    },
}
updateErr := sf.UpsertComposite("Contact", "ContactExternalId__c", contacts, 200, true)
if updateErr != nil {
    panic(updateErr)
}

DeleteComposite

func (sf *Salesforce) DeleteComposite(sObjectName string, records any, batchSize int, allOrNone bool) error

Deletes a list of salesforce records in a single request

  • sObjectName: API name of Salesforce object
  • records: 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",
    },
}
err := sf.DeleteComposite("Contact", contacts, 200, true)
if err != nil {
    panic(err)
}

Bulk v2

Create Bulk API Jobs to query, insert, update, upsert, and delete large collections of records

Types

type BulkJobResults struct {
    Id                  string
    State               string
    NumberRecordsFailed int
    ErrorMessage        string
}

QueryBulkExport

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 created
  • query: a SOQL query
err := sf.QueryBulkExport("SELECT Id, FirstName, LastName FROM Contact", "data/export.csv")
if err != nil {
    panic(err)
}

QueryStructBulkExport

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 created
  • soqlStruct: a custom struct using soql 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)
}

InsertBulk

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 object
  • records: a slice of salesforce records
  • batchSize: 1 <= batchSize <= 10000
  • waitForResults: denotes whether to wait for jobs to finish and return any errors if they are encountered during the operation
type Contact struct {
    LastName string
}
contacts := []Contact{
    {
        LastName: "Lang",
    },
    {
        LastName: "Van Dyne",
    },
}
_, err := sf.InsertBulk("Contact", contacts, 1000, true)
if err != nil {
    panic(err)
}

InsertBulkFile

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 object
  • filePath: path to a csv file containing salesforce data
  • batchSize: 1 <= batchSize <= 10000
  • waitForResults: denotes whether to wait for jobs to finish and return any errors if they are encountered during the operation

data/avengers.csv

FirstName,LastName
Tony,Stark
Steve,Rogers
Bruce,Banner

_, err := sf.InsertBulkFile("Contact", "data/avengers.csv", 1000, true)
if err != nil {
    panic(err)
}

UpdateBulk

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 object
  • records: a slice of salesforce records
    • An Id is required
  • batchSize: 1 <= batchSize <= 10000
  • waitForResults: denotes whether to wait for jobs to finish and return any errors if they are encountered during the operation
type Contact struct {
    Id       string
    LastName string
}
contacts := []Contact{
    {
        Id:       "003Dn00000pEsoRIAS",
        LastName: "Strange",
    },
    {
        Id:       "003Dn00000pEsoSIAS",
        LastName: "T'Challa",
    },
}
_, err := sf.UpdateBulk("Contact", contacts, 1000, true)
if err != nil {
    panic(err)
}

UpdateBulkFile

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 object
  • filePath: 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 and return any errors if they are encountered during the operation

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

_, err := sf.UpdateBulkFile("Contact", "data/update_avengers.csv", 1000, true)
if err != nil {
    panic(err)
}

UpsertBulk

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 object
  • externalIdFieldName: field API name for an external Id that exists on the given object
  • records: 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 and return any errors if they are encountered during the operation
type ContactWithExternalId struct {
    ContactExternalId__c string
    LastName             string
}
contacts := []ContactWithExternalId{
    {
        ContactExternalId__c: "Avng5",
        LastName:             "Rhodes",
    },
    {
        ContactExternalId__c: "Avng6",
        LastName:             "Quill",
    },
}
_, err := sf.UpsertBulk("Contact", "ContactExternalId__c", contacts, 1000, true)
if err != nil {
    panic(err)
}

UpsertBulkFile

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 object
  • externalIdFieldName: field API name for an external Id that exists on the given object
  • filePath: 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 and return any errors if they are encountered during the operation

data/upsert_avengers.csv

ContactExternalId__c,FirstName,LastName
Avng7,Matt,Murdock
Avng8,Luke,Cage
Avng9,Jessica,Jones
Avng10,Danny,Rand

_, err := sf.UpsertBulkFile("Contact", "ContactExternalId__c", "data/upsert_avengers.csv", 1000, true)
if err != nil {
    panic(err)
}

DeleteBulk

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 object
  • records: a slice of salesforce records
    • should only contain Ids
  • batchSize: 1 <= batchSize <= 10000
  • waitForResults: denotes whether to wait for jobs to finish and return any errors if they are encountered during the operation
type Contact struct {
    Id       string
}
contacts := []ContactIds{
    {
        Id: "003Dn00000pEsoRIAS",
    },
    {
        Id: "003Dn00000pEsoSIAS",
    },
}
_, err := sf.DeleteBulk("Contact", contacts, 1000, true)
if err != nil {
    panic(err)
}

DeleteBulkFile

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 object
  • filePath: 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 and return any errors if they are encountered during the operation

data/delete_avengers.csv

Id
003Dn00000pEwRuIAK
003Dn00000pEwQxIAK
003Dn00000pEwQyIAK
003Dn00000pEwQzIAK
003Dn00000pEwR0IAK
003Dn00000pEwR1IAK

_, err := sf.DeleteBulkFile("Contact", "data/delete_avengers.csv", 1000, true)
if err != nil {
    panic(err)
}

GetJobResults

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
  • Can be used when you want to check the results of a job, but at a later time
type Contact struct {
    LastName string
}
contacts := []Contact{
    {
        LastName: "Grimm",
    },
}
jobIds, err := sf.InsertBulk("Contact", contacts, 1000, false)
if err != nil {
    panic(err)
}
time.Sleep(time.Second)
for _, id := range jobIds {
    results, err := sf.GetJobResults(id) // returns an instance of BulkJobResults
    if err != nil {
        panic(err)
    }
    fmt.Println(results)
}

Other

DoRequest

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))

Contributing

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 changes
    • replace github.com/k-capehart/go-salesforce => /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
  • Create a PR and link the issue

About

Salesforce REST API client written in Go

pkg.go.dev/github.com/k-capehart/go-salesforce

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • Go 100.0%