• Plugin version: v3.3.0
• Released on: 2025-05-14
• Changelog

For other versions, see theVersioned plugin docs.

For plugins not bundled by default, it is easy to install by runningbin/logstash-plugin install logstash-input-salesforce. SeeWorking with plugins for more details.

For questions about the plugin, open a topic in theDiscuss forums. For bugs or feature requests, open an issue inGithub. For the list of Elastic supported plugins, please consult theElastic Support Matrix.

This Logstash input plugin allows you to query Salesforce using SOQL and puts the results into Logstash, one row per event. You can configure it to pull entire sObjects or only specific fields.

In order to use this plugin, you will need to create a new Salesforce Connected App with OAuth enabled.More details can be found here:https://help.salesforce.com/apex/HTViewHelpDoc?id=connected_app_create.htm

You will also need a username, password, and security token for your Salesforce instance.More details for generating a token can be found here:https://help.salesforce.com/apex/HTViewHelpDoc?id=user_security_token.htm

In addition to specifying an sObject, you can also supply a list of API fields that will be used in the SOQL query.

If your infrastructure uses an HTTP proxy, you can set theSALESFORCE_PROXY_URI environment variable with the desired URI value (e.gexport SALESFORCE_PROXY_URI="http://proxy.example.com:123").

This example prints all the Salesforce Opportunities to standard out

input {  salesforce {    client_id => 'OAUTH CLIENT ID FROM YOUR SFDC APP'    client_secret => 'OAUTH CLIENT SECRET FROM YOUR SFDC APP'    username => 'email@example.com'    password => 'super-secret'    security_token => 'SECURITY TOKEN FOR THIS USER'    sfdc_object_name => 'Opportunity'  }}output {  stdout {    codec => rubydebug  }}

This plugin supports the following configuration options plus theCommon options described later.

Also seeCommon options for a list of options supported by all input plugins.

• Value type isstring
• There is no default value for this setting.

By default, this uses the default Restforce API version. To override this, set this to something like "32.0" for example.

• Value type isstring
• There is no default value for this setting.

The filter to add to the Salesforce query when a previous tracking field valuewas read from thetracking_field_value_file.The string can (and should) contain a placeholder%{last_tracking_field_value} thatwill be substituted with the actual value read from thetracking_field_value_file.

This clause is combined with anysfdc_filtersclause that is configured using theAND operator.

The value should be properly quoted according to the SOQL rules for the fieldtype.

Examples:

"changed_data_filter" => "Number > '%{last_tracking_field_value}'"

"changed_data_filter" => "LastModifiedDate >= %{last_tracking_field_value}"

• This is a required setting.
• Value type isstring
• There is no default value for this setting.

Consumer Key for authentication. You must set up a new Salesforce connected app with OAth enabled to use this plugin. More information can be found here:https://help.salesforce.com/apex/HTViewHelpDoc?id=connected_app_create.htm

• This is a required setting.
• Value type ispassword
• There is no default value for this setting.

Consumer Secret from your oauth enabled connected app.

• Value type isnumber
• There is no default value for this setting.

The interval in seconds between each run of the plugin.

If specified, the plugin only terminates when it receives the stopsignal from Logstash, e.g. when you press Ctrl-C when running interactively,or when the process receives a TERM signal. It will query and publishevents for all results, then sleep untilinterval seconds from the startof the previous run of the plugin have passed. If the plugin ran for longerthaninterval seconds, it will run again immediately.

If this property is not specified or is set to -1, the plugin will run once and then exit.

• This is a required setting.
• Value type ispassword
• There is no default value for this setting.

The password used to login to Salesforce.

• This is a required setting.
• Value type ispassword
• There is no default value for this setting.

The security token for this account. For more information about generating a security token, see:https://help.salesforce.com/apex/HTViewHelpDoc?id=user_security_token.htm.

• Value type isarray
• Default value is[]

These are the field names to return in the Salesforce query If this is empty, all fields are returned.

• Value type isstring
• Default value is""

These options will be added to theWHERE clause in the SOQL statement. Additional fields can be filtered on by addingfield1 = value1 AND field2 = value2 AND...​.

• Value type isstring
• There is no default value for this setting.

The url of a Salesforce instance. Provide the url if you want to connect to your Salesforce instance instead oflogin.salesforce.com ortest.salesforce.com at login.

Use either this or theuse_test_sandbox configuration option but not both to configure the url to which the plugin connects to.

• This is a required setting.
• Value type isstring
• There is no default value for this setting.

The name of the Salesforce object you are creating or updating.

• Value type isnumber
• Default value is60

The timeout to apply to REST API calls to Salesforce, in seconds. If a connection to Salesforce cannot be made in this time, an error occurs.If it takes longer than the timeout for a block of data (e.g. query results) to be read, an error occurs.

• Value type isboolean
• Default value isfalse

Setting this to true will convert Salesforce's++NamedFields__c++ to++named_fields__c++.

• Value type isstring
• There is no default value for this setting.

The field to track for incremental data loads. This field willbe used in anORDER BY ... ASC clause that is added to the Salesforce query.This fieldshould also be used in thechanged_data_filter clauseto actually achieve incremental loading of data.

The last value (which is the highest value if the query sorts by this field ascending)value for this field will be saved to the file at the path configured bytracking_field_value_file, if specified.

This field should ideally be strictly ascending for new records. Anautonumber field is ideal for this.

The standardLastModifiedDate field can be used, but since it is notstrictlyascending (multiple records can have the sameLastModifiedDate, thechanged_data_filter should account for this by using the>=operator, and duplicates should be expected.

Note that Salesforce does not guarantee that the standardId field has ascendingvalues for new records (https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_testing_best_practices.html).Therefore, usingId as tracking field risks missing records and is not recommended.

If this field is not already included in thesfdc_fields, it is added.

• Value type isstring
• There is no default value for this setting.

The full path to the file from which the latest tracking field value from the previousplugin invocation will be read, and to which the new latest tracking field value will bewritten after the current plugin invocation.

This keeps persistent track of the last seen value of the tracking field used for incrementalloading of data.

The file should be readable and writable by the Logstash process.

If the file exists and achanged_data_filter is configured,a changed data filter clause is added to the query (and combined with anysfdc_filtersclause that is configured using theAND operator).

If the result set is not empty, the value fortracking_field from the last row iswritten to the file.

• Value type isboolean
• Default value isfalse

Set this to true to connect to a sandbox sfdc instance logging in through test.salesforce.com

Use either this or thesfdc_instance_url configuration option but not both to configure the url to which the plugin connects to.

• Value type isboolean
• Default value isfalse

Set this to true to connect to the sfdc tooling api instead of the regular sfdc rest api. Seehttps://developer.salesforce.com/docs/atlas.en-us.api_tooling.meta/api_tooling for details about the sfdc tooling api. Use cases for the sfdc tooling api include reading apex unit test results, flow coverage results (e.g. coverage of elements of sfdc flows) and security health check risks.

• This is a required setting.
• Value type isstring
• There is no default value for this setting.

A valid salesforce user name, usually your email address. Used for authentication and will be the user all objects are created or modified by

These configuration options are supported by all input plugins:

• Value type ishash
• Default value is{}

Add a field to an event

• Value type iscodec
• Default value is"plain"

The codec used for input data. Input codecs are a convenient method for decoding your data before it enters the input, without needing a separate filter in your Logstash pipeline.

• Value type isboolean
• Default value istrue

Disable or enable metric logging for this specific plugin instance by default we record all the metrics we can, but you can disable metrics collection for a specific plugin.

• Value type isstring
• There is no default value for this setting.

Add a uniqueID to the plugin configuration. If no ID is specified, Logstash will generate one. It is strongly recommended to set this ID in your configuration. This is particularly useful when you have two or more plugins of the same type, for example, if you have 2 salesforce inputs. Adding a named ID in this case will help in monitoring Logstash when using the monitoring APIs.

input {  salesforce {    id => "my_plugin_id"  }}

• Value type isarray
• There is no default value for this setting.

Add any number of arbitrary tags to your event.

This can help with processing later.

• Value type isstring
• There is no default value for this setting.

Add atype field to all events handled by this input.

Types are used mainly for filter activation.

The type is stored as part of the event itself, so you can also use the type to search for it in Kibana.

If you try to set a type on an event that already has one (for example when you send an event from a shipper to an indexer) then a new input will not override the existing type. A type set at the shipper stays with that event for its life even when sent to another Logstash server.