Salesforce query service
Salesforce query service
The Salesforce Query Service can be used to submit SOQL queries to Salesforce. SOQL is an acronym for Salesforce Object Query Language and is a query language developed by Salesforce for retrieving information.
In contrast to SQL, SOQL cannot be used to create, update or delete data. It is only used to retrieve information. If you wish to create, update or delete Salesforce records, you are referred to the Salesforce Create Service, Salesforce Update Producer and Salesforce Delete Producer components, respectively.
The Salesforce Query Service has the option of either statically defining a query during component configuration or extracting the query from the specified ConnectMessagePart.
In the table below, you will find an explanation of these properties. All attributes with a ‘*’ are mandatory.
|
Attribute |
Description |
|
Name* |
By default, we fill this out with the technical ‘tag’, followed by a serial number. Changing the name is optional. |
|
Enabled |
Set this value to true, if you want this service to be enabled. |
|
MessagePart In |
The incoming ConnectMessagePart that might specify a SOQL query. |
|
Salesforce Instance |
The Salesforce instance refers to the server your Salesforce organization lives on. It is visible in the first part of the url after you log in to your Salesforce account. Valid examples are eu27, ap5, and na12. |
|
Key Password |
The password of the key pair in the keystore. If left empty it defaults to the keystore password. |
|
MessagePart Out |
The outgoing ConnectMessagePart that contains the query results. |
|
Key Alias |
The alias of the key pair in the ConnectPlaza keystore. The private key is used to sign the JWT. A certificate with the public key needs to be registered in Salesforce when a connected app is created. |
| Client ID | The client ID of the Salesforce connected app. |
| Username | The username of the Salesforce account you wish to use to authenticate the Salesforce API calls. |
| Use Body |
Get the SOQL query from the message body. |
| Authentication |
Select the way you wish to authenticate your Salesforce API calls. Note that each authentication method has different requirements. Consult ConnectPlaza's technical documentation for more details. |
| Security Token |
The security token of the Salesforce account you wish to use to authenticate the Salesforce API calls. Note that if you do not possess the security token you can request Salesforce to generate a new one. Consult the Salesforce documentation for the details. When Authentication is set to OAUTH2_PASSWORD or SOAP_PASSWORD |
| Client Secret |
The client password of the Salesforce connected app. When Authentication is set to OAUTH2_PASSWORD or OAUTH2_REFRESH_TOKEN |
| Password |
The password of the Salesforce account you wish to use to authenticate the Salesforce API calls. When Authentication is set to OAUTH2_PASSWORD or SOAP_PASSWORD |
| Refresh Token |
The OAuth2 refresh token for the specified connected app. Note that you can set the expiration date of the refresh token in your Salesforce connected app configuration. It is advised to set it to never expire. When Authenticationi s set to OAUTH2_REFRESH_TOKEN |
| Query |
You can specify the SOQL query here. Consult your Salesforce documentation for the correct syntax. When Use Body is set to false |
| Query All |
Should records that have been deleted because of a merge or delete be included in the query results? When Use Body is set to false |
| Cache Expiration |
The expiration time in minutes of entries in the cache. The cache is used to store Salesforce object descriptions which are in turn used to format API requests. Note that if this value is small it might result in many redundant API calls. However, if the value is large, changes made to Salesforce object types might take longer to propagate to the cache. Advanced |
| Description |
Description of the purpose of this component. This will be part of the documentation printed out in the Diagram of this interface. |
When extracting the query from a ConnectMessagePart it is assumed that the body consists of a plain text SOQL query.
After executing the query, the result will be stored as XML in the outgoing ConnectMessagePart. For example, after executing the query “SELECT Name FROM Account LIMIT 2” you might expect the following output:
<records>
<record type=”Account”>
<field name=”Name” value=”foo”/>
</record>
<record type=”Account”>
<field name=”Name” value=”bar”/>
</record>
</records>The top-level element is always records. The records element can have multiple record subelements. Each record always has a type attribute and optionally an id attribute. Furthermore, each record has zero or more fields. Each field must have a name and a value attribute.
The following output is the result of executing the query “SELECT Id, Rating FROM Account LIMIT 2”:
<records>
<record type=”Account” id=”0013X00002SQA0SQAX”>
<field name=”Rating” value=”Hot”/>
</record>
<record type=”Account” id=”0013X00002SQyy3QAD”>
</record>
</records>Note that the id value is added as an attribute to a record and not in the form of a separate field. Furthermore, the rating field is omitted from the second account record because that account has value null for rating. So if the requested field value is null, it is omitted from the output.
When using aggregate SOQL queries the result is still stored in a record element. The type attribute of the record attribute will in this case be “AggregateResult”. The computed value is stored in a field element with the name “expr0”. For example, after executing “SELECT COUNT(Name) FROM Account” we get:
<records>
<record type=”AggregateResult”>
<field name=”expr0” value=”42”/>
</record>
</records>Finally, see the article on authentication for the different available options as well as their corresponding requirements.