Configuring Query Operation Adapter Services
Use the Query Operation template to configure an adapter service that executes a Salesforce Object Query Language (SOQL) query against a Salesforce object, to find records and return selected field values from those records. For example, you might configure an adapter service that queries the Contact Salesforce object to find contacts who have a specific Title and return values for the FirstName, LastName, and Phone fields.
The Query operation wraps the query, queryAll, and queryMore calls of the Salesforce.com Web service API. The query call executes the initial query to retrieve the initial matching records. If the response from the query call indicates that there are additional records to retrieve, the adapter service executes the queryMore call as many times as necessary to retrieve all records. The queryAll call identifies the records that have been deleted because of a merge or delete operation.
At run time when you invoke the service, pass the input parameters to the adapter service if you have specified variables in the WHERE clause. The adapter service generates the query and executes the query.
As a response, the Salesforce.com query and queryMore calls return a QueryResult object, which includes the selected field values of the matching records and a flag indicating whether there are additional matching records to retrieve. The queryAll call returns all existing and deleted records.
The following table describes the output from a Query Operation adapter service:
Variable | Description |
results | Document List Each Document in the Document List contains the selected fields for a record that matched the specified query. |
To configure an adapter service that uses the Query Operation template
2. Start Designer.
3. Right-click the package in which the service should be contained and select New > Adapter Service.
4. Select the parent namespace, type a name for the adapter service, and click Next.
5. Select Adapter for Salesforce as the adapter type and click Next.
6. Select the appropriate Adapter Connection Name and click Next.
Important:
Ensure the Salesforce.com user account identified by the connection has all the required permissions to query records from the Salesforce object that you will select later in the procedure.
7. From the list of available templates, select the Query Operation template and click Finish.
The adapter service editor for the adapter service appears. You can select the Adapter Settings tab at any time to confirm adapter service properties such as the Adapter Name, Adapter Connection Name, and Adapter Service Template, as necessary.
8. Identify the Salesforce object that you want to query.
a. Select the Schema tab.
b. From the Salesforce object list, select the Salesforce object you want to query.
c. Select the Include Deleted Records checkbox to include all existing and deleted records.
d. Click the 
icon to reload the adapter values. 9. Identify the fields of the matching records that you want returned. If you do not specify fields, the adapter throws an error stating MALFORMED_QUERY.
a. Select the Query Operation tab.
b. Click the 
icon to populate the table with the fields of the selected Salesforce object. c. For each field you want returned, select the check box in the Use Field column.
For example, if you are querying the Account Salesforce object, you may select to have the adapter service return the "Account ID" and "Account Name" fields of the matching records.
10. Optionally, define how you want the adapter to sort the retrieved records.
a. For each field you want to sort by, in the Sort Order column select a sort order option. Only specify a sort option for fields you select using the Use Field check box. The adapter ignores sort options that you specify for non-selected fields.
Select this option... | To sort the results in... |
ASC NULLS FIRST | Ascending order by the field value, with the null values at the beginning of the results. |
ASC NULLS LAST | Ascending order by the field value, with the null values at the end of the results. |
DESC NULLS FIRST | Descending order by the field value, with the null values at the beginning of the results. |
DESC NULLS LAST | Descending order by the field value, with the null values at the end of the results. |
b. If you are sorting by multiple fields, move the rows into the order in which you want the adapter to perform the sorts. The adapter performs each sort in the order the rows are listed on the Query Operation tab.
To move a row, select it and then click the
icon to move the row up, or click the
icon to move the row down.
For more information about sorting, including factors that affect sorting and data type limitations, see the Force.com Web Services API Developer's Guide.
11. Optionally, you can use the WHERE field to filter the search results for an object based on specific field values. You specify the filter using Salesforce Object Query Language (SOQL). If you leave the WHEREfield blank, the adapter returns all records in the Salesforce object specified on the Schema tab.
You can either specify the WHERE condition or you can use variables. When you use variables in a WHERE clause, use ${INPUT_FIELD_NAME} to map a part of the clause to the input field. At design time, the service template generates an input field with INPUT_FIELD_NAME, which allows you to specify placeholders within the WHERE clause (conditional Expression) free text area to define input parameters. At run time, the service parses the WHERE clause and replaces the ${INPUT_FIELD_NAME} with the actual contents of the input field.
For example, consider the following WHERE clauses:
Name = '${ name }' and Sales > 200000In this example, the service template will generate an input field for name. At run time, ${name} is replaced with the value of name variable.
If you specify Jack as the value for the name input field, then the resultant WHERE clause is:
Name = 'Jack' and Sales > 200000
Name = '${name}' and Sales > ${amount} In this example, the service template will generate input fields for name and amount .
${
where }
In this example, the service template will generate an input field for where . In the where input field, you can specify any condition.
Type = ‘Customer' or ${condition} In this example, the service template will generate an input field for condition . In the condition input field, you can specify the dynamic condition.
For more information about SOQL and the WHERE conditionExpression, see the Force.com Web Services API Developer's Guide.
12. In the Maximum Rows field, type a positive, whole number to specify the maximum number of records that you want returned. If you want all records to be returned, type 0.
13. Select File > Save to save the adapter service.
