salesforce

README

Go Salesforce SDK

go-salesforce-sdk is an unofficial SDK for the Salesforce REST API.

Checkout our release notes for information about the latest bug fixes, updates, and features added to the sdk.

Jump To:

• Installation
• Examples
• Features
• Packages
• Contribute
• Credits

Installation

This SDK comes in two parts: a CLI for generating types and running small commands, and a series of Go packages intended to be used as a library in your applications.

# install the package using go modules
go get github.com/beeekind/go-salesforce-sdk
# install the CLI
go install $GOPATH/src/github.com/beeekind/go-salesforce-sdk/cmd/go-salesforce-sdk

Examples

This SDK consists of a high level and a low level API. The high level API can be found in the root package while all other packages should be considered low level.

We recommend you actually use the low level API as it is much more configurable and still simple to use.

Use these examples, all *_test.go files, the root package, and the godoc, as documentation for using this SDK.

1. Authenticate via the Password or JWT flows by setting environmental variables:

# For the JWT flow (recommended):
# https://mannharleen.github.io/2020-03-03-salesforce-jwt/

export SALESFORCE_SDK_CLIENT_ID=...
export SALESFORCE_SDK_USERNAME=...
export SALESFORCE_SDK_PEM_PATH=...

#For the Password Flow:

export SALESFORCE_SDK_CLIENT_ID=...
export SALESFORCE_SDK_CLIENT_SECRET=...
export SALESFORCE_SDK_USERNAME=...
export SALESFORCE_SDK_PASSWORD=...
export SALESFORCE_SDK_SECURITY_TOKEN=...

1. Generate the types you intend to use

go-salesforce-sdk generate Lead ./ leads 0

1. Use the SDK

import (
    sdk "github.com/beeekind/go-salesforce-sdk"
    "github.com/beeekind/go-salesforce-sdk/requests"
    "github.com/beeekind/go-salesforce-sdk/soql"
    "github.com/beeekind/go-salesforce-sdk/types"
    "github.com/your/project/leads"
)

type LeadsResponse struct {
    types.QueryResponse
    Records []*leads.Lead `json:"records"`
}

func main(){
    var response LeadsResponse
    _, err := requests. 
        Sender(sdk.DefaultClient).
        URL("query").
        SQLizer(soql.
            Select("Id", "Name", "CreatedDate"). 
            From("Lead"). 
            Limit(100)).
        JSON(&response)

    for _, lead := range response.Records {
        // ...
    }
}

Features

---

• Generate type definitions

  • Standard Objects
  • Tooling Objects

• Authentication Mechanisms

  • JWT flow (recommended)
  • Password flow

• Concurrent Processing

  • Pre-compute paginated resources for retrieving all paginated records quickly

• HTTP Client Wrapper

  • HttpTransport customization
  • Ratelimiting
  • GZIP compression

• Querybuilder (based on squirrel)

  • Select
  • Where
    • Equality | Inequality
    • Subqueries
    • Like | NotLike
    • GT | LT | GTE | LTE
    • Conjugations (And | Or)
  • Group By
  • Order By(s)
  • Limit
  • Offset
  • Prefixes
  • Suffixes

• Request Builder

  • URL composition
  • Method
  • URL parameters
  • Headers
  • SOQL embeding
  • Build as http.Response
  • Unmarshal into struct
  • application/x-www-form-urlencoded submissions

• Custom Types

  • Nullable (bool | string | int | float)
  • Date / Datetime
  • Address
  • AlmostBool

• Metadata Response Types

  • /describe
  • /describe/{objectName}
  • Limits
  • Query
  • Tooling/query

• Bulk API v2

  • Ingest
  • Query

• Composite

  • Create
  • Read
  • Update
  • Delete

• Tree

  • ParseNode(typeDefinition)
  • Recursive object nesting

• Execute Anonymous Apex

  • SingleEmailMessage

• And much more...

Packages

Package	Link	Description
go-salesforce-sdk	Link	Root package with high level API methods. Other packages should be considered the low-level API
cmd/go-salesforce-sdk	Link	CLI for generating golang type definitions
apex	Link	Demonstrates using the Execute Anonymous Apex endpoint to send an email
bulk	Link	Methods for bulk uploading and retrieving objects as text/csv
client	Link	Wraps http.Client and provides authentication, ratelimiting, and http.Transport customization
composite	Link	Provides Create, Read, Update, and Delete, operations with the Composite API
metadata	Link	TBD
requests	Link	HTTP request building using the builder design pattern
soql	Link	SOQL (Salesforce Object Query Language) building using the builder design pattern
templates	Link	Templates for generating Type definitions, Response types, Apex code, and other artifacts
tree	Link	Tree API operations for saving nested objects based on their relations. Uses generated types.
types	Link	Type definitions for Salesforce specific types like Date and Datetime

Contribute

Issues and Pull Requests welcome!

Credits

Gophers Slack.

The greater Devops community for keeping me sane through COVID.

Documentation

Index

• Variables
• func Attachment(ID string) ([]byte, error)
• func Count(objectName string) (int, error)
• func Create(objectName string, fields map[string]interface{}) (ID string, err error)
• func DeleteByID(objectName string, ID string) error
• func Describe(objectName string) (describe *metadata.Describe, err error)
• func Document(req requests.Builder, ID string) ([]byte, error)
• func DownloadFile(contentVersionID string) ([]byte, error)
• func Find(query string, dst interface{}) error
• func FindAll(query string, dst interface{}) error
• func FindByID(objectName string, objectID string, fields []string, dst interface{}) error
• func SObjects() (results *metadata.Sobjects, err error)
• func Services() (services map[string]string, err error)
• func Types(structName string, endpoint string) (codegen.Structs, error)
• func UpdateByID(objectName string, ID string, fields map[string]interface{}) error
• func Versions() ([]*client.APIVersion, error)

Variables

var DefaultClient = client.Must(
	client.WithLoginFailover(
		client.WithPasswordBearer(
			os.Getenv("SALESFORCE_SDK_CLIENT_ID"),
			os.Getenv("SALESFORCE_SDK_CLIENT_SECRET"),
			os.Getenv("SALESFORCE_SDK_USERNAME"),
			os.Getenv("SALESFORCE_SDK_PASSWORD"),
			os.Getenv("SALESFORCE_SDK_SECURITY_TOKEN"),
		),
		client.WithJWTBearer(
			os.Getenv("SALESFORCE_SDK_CLIENT_ID"),
			os.Getenv("SALESFORCE_SDK_USERNAME"),
			"../private.pem",
		),
	),
	client.WithLimiter(ratelimit.New(5, time.Second, 5, memory.New())),
)

DefaultClient ...

Functions

func Attachment

func Attachment(ID string) ([]byte, error)

Attachment returns the given Attachment by ID

func Count

func Count(objectName string) (int, error)

Count for the given objectName "Lead" "Account" or "User"

func Create

func Create(objectName string, fields map[string]interface{}) (ID string, err error)

Create created the given objectName

This SDK goes out of its way to not be an ORM which is why the method signature doesnt use a generated type like those derived from the codegen package.

func DeleteByID

func DeleteByID(objectName string, ID string) error

DeleteByID deletes the given objectName with the given ID

func Describe

func Describe(objectName string) (describe *metadata.Describe, err error)

Describe returns the description of a given Salesforce Object

func Document

func Document(req requests.Builder, ID string) ([]byte, error)

Document returns the given Document by ID

func DownloadFile

func DownloadFile(contentVersionID string) ([]byte, error)

DownloadFile returns the given file via its ContentVersion ID

func Find

func Find(query string, dst interface{}) error

Find returns all paginated resources for a given query. If there are many results and/or many fields this method will take longer to execute and use more of your org's API limit.

The parameter dst should be a pointer value to a slice of types matching the expected query records.

func FindAll

func FindAll(query string, dst interface{}) error

FindAll is akin to the queryAll resource which returns soft deleted resources in addition to regular records.

The parameter dst should be a pointer value to a slice of types matching the expected query records.

func FindByID

func FindByID(objectName string, objectID string, fields []string, dst interface{}) error

FindByID returns a single result filtered by Id.

The parameter dst should be a pointer to a type matching the expected query record.

func SObjects

func SObjects() (results *metadata.Sobjects, err error)

SObjects returns the result of a request to the /sobjects endpoint

func Services

func Services() (services map[string]string, err error)

Services are api endpoints for RESTful operations within the Salesforce API

func Types

func Types(structName string, endpoint string) (codegen.Structs, error)

Types returns a golang type definition(s) for the JSON response of an endpoint

func UpdateByID

func UpdateByID(objectName string, ID string, fields map[string]interface{}) error

UpdateByID updates the given objectName with the given ID.

Salesforce update responses return empty response bodies and statusCode 204 upon success.

func Versions

func Versions() ([]*client.APIVersion, error)

Versions returns data on available API versions for the Salesforce REST API

This method is used during authentication so that we may default to the latest REST API endpoint.