Adapter Services

Overview

The following sections describe how to configure adapter services, which you use for webMethods to Salesforce.com communications.

Before you configure Adapter for Salesforce services, you must configure the connections you plan to use with them. For details, see Configuring Adapter Connections.

Before Configuring or Managing Adapter Services

About this task

To prepare to configure or manage an adapter service

Procedure

  1. Start your Integration Server and Integration Server Administrator, if they are not already running.
  2. Make sure you have Integration Server administrator privileges so that you can access the Adapter for Salesforce administrative screens. For information about setting user privileges, see the IBM webMethods Integration Server Administrator’s Guide for your release.
  3. Using Integration Server Administrator, make sure the WmSalesforceAdapter package is enabled. For instructions, see Enabling and Disabling Packages.
  4. Using Integration Server Administrator, configure an adapter connection to use with the adapter service. For instructions, see Configuring Adapter Connections.
  5. Start Designer if it is not already running.
  6. Using Designer, create a package to contain adapter services, if you have not already done so. When you configure adapter services, define them in user-defined packages instead of in the WmSalesforceAdapter package. For more information about managing packages for the adapter, see Adapter Package Management.
  7. Optionally, you can configure the watt.adapter.salesforce.sobjects.batchSize watt property in Integration Server Administrator to set the batch size for the retrieval of metadata for Salesforce objects. If you do not specify a value for the property, the adapter uses as a default value the maximum limit size of a batch of Salesforce objects (100) set by Salesforce.com.

    For information about configuring the watt.adapter.salesforce.sobjects.batchSize watt property, see the IBM webMethods Integration Server Administrator’s Guide for your release.

Configuring Adapter Services

About this task

You can configure adapter services that perform the following operations:

Operation For more information, see...
Handle a large number of records of a Salesforce object. The service performs the following operations against a batch of Salesforce object records:
  • inserts new records.
  • updates records.
  • inserts or updates records.
  • deletes records.
  • performs a query to find records and return field values from matching records.
Configuring Batch Operation Adapter Services
Insert new records into one or multiple Salesforce objects. Configuring Create Operation Adapter Services
Perform a dynamic SOQL query against a Salesforce object. Configuring Custom Query Operation Adapter Services
Delete records from an organization's data. Configuring Delete Operation Adapter Services
Monitor the status and display the results of a batch operation. Configuring Monitor Batch Operations Adapter Services
Perform a query against a Salesforce object to return field values from matching records. Configuring Query Operation Adapter Services
Retrieve field values of specified records of a Salesforce object. Use this operation when you know the IDs of the records from which you want field values. Configuring Retrieve Operation Adapter Services
Update records of one or multiple Salesforce objects. Configuring Update Operation Adapter Services
Perform an upsert operation to either insert new records into or update records of a Salesforce object. Configuring Upsert Operation Adapter Services
Execute the Salesforce.com getServerTimestamp utility. Configuring Utility Operation Adapter Services
Execute the Salesforce.com getSessionId utility. Configuring Utility Operation Adapter Services
Execute the Salesforce.com getUserInfo utility. Configuring Utility Operation Adapter Services
Execute the Salesforce.com resetPassword utility. Configuring Utility Operation Adapter Services
Execute the Salesforce.com sendEmail utility. Configuring Utility Operation Adapter Services
Execute the Salesforce.com sendMassEmail utility. Configuring Utility Operation Adapter Services
Execute the Salesforce.com setPassword utility. Configuring Utility Operation Adapter Services

Assigning External IDs to sObject Record Fields

About this task

Each record in an sObject is identified uniquely by an Internal ID that Adapter for Salesforce generates automatically. To create a record in a table which has a reference to a record in another sObject, you can mark fields in an sObject with External IDs. When you assign an External ID to a record field, you can identify that record not only by the Internal ID, but also by the External ID field. You can easily access and refer to the value of a field in an sObject designated as an External ID. The adapter service will show all the External ID fields. Select the desired External ID, and save the service.

Important: The External ID fields are used only for Create, Update, and Upsert adapter services.
Note: Adapter for Salesforce uses either the Internal ID or the External ID when making calls to the backend. You cannot use both the Internal ID and the External ID.

For example, as shown in the following screenshot, you can identify uniquely a record in an "Account" sObject by either the automatically generated Internal ID or by designating any custom field, for example, "NYSE_ID", to act as an External ID. When creating an “Opportunity” record for this “Account” record, you would use “NYSE_ID” in place of "Account ID".

Results
Note: You can use External IDs for existing services without modifying the service. To use External IDs for an existing service, you must lock the service for editing and reload the adapter fields.

Configuring Batch Operation Adapter Services

About this task

Use the Batch Operation template to configure a service that handles a large number of records of a Salesforce object. The service performs the following operations against a batch of Salesforce object records:
  • Inserts new records.
  • Updates records.
  • Inserts and updates records (upsert operation).
  • Deletes records.
  • Performs a query to find records and return field values from matching records.

The following table shows the input parameters of the adapter service that you configure.

Note: You must specify a value either for the content or for the filePath input parameter. For information about what the content and file format should be, see the Salesforce documentation.
Input Variable Description
content Takes an object and maps it to actual data. The data type of the content parameter can be byte array, string, InputStream, or Reader.
filePath String Loads the Salesforce object records from a csv file.
encoding String Optional. Indicates the specific encoding for the data that the service passes. The default value is UTF-8.

The following table shows the output parameters of the adapter service that you configure.

Output Variable Description
jobId String The ID of the job created to perform the operation.
batchId String List The ID of the batches of records for which the service returns the results from the executed operation.
Note: The values of the jobId and batchId output variables are used as input variables of the Monitor Batch Operations service. For information about the Monitor Batch Operations service, see Configuring Monitor Batch Operations Adapter Services.

To configure an adapter service using the Batch Operation template

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  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 IBM webMethods Adapter for Salesforce as the adapter type and click Next.
  6. Select the appropriate Adapter Connection Name and click Next.
  7. From the list of available templates, select the Batch 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. Select the Batch Operation tab.
  9. From the Salesforce Object field, select the Salesforce object on which the service will perform the required bulk operation.
  10. From the Salesforce Bulk Operations field, select the type of bulk operation that you want the service to perform:
    • insert
    • update
    • upsert
    • delete
    • query
  11. In the Max number of rows per batch field, specify the number of rows that should be included in each batch. Any positive number is a valid value.
    Note: This field applies only for the insert, update, upsert, and delete operations. You cannot specify a value in this field when you select the query operation in the previous step.
  12. If you selected the upsert bulk operation, from the ID Field Name list, select the field that you want to use to determine whether a record already exists in the Salesforce object.
    At run time, pass a value for this field as input into the adapter service. If the value matches an existing record, the adapter service updates the record. If the value does not match an existing record, the adapter service inserts a new record.
    Note: If you do not specify any value at run time, the adapter service neither inserts nor updates the record.
  13. Select File > Save to save the adapter service.

Results

Note: If you are using JVM version below 1.8, set the property wrapper.java.additional.8=-Dhttps.protocols=TLSv1.2 in the location, webMethods_directory/profiles/IS_default/configuration/wrapper.conf file. Here, 8 is a sample number. Therefore, set it to the next available number. This property should be added under Java Additional Parameters.

Configuring Create Operation Adapter Services

About this task

Use the Create Operation template to configure an adapter service that inserts new records into one or multiple Salesforce objects. For example, you might configure an adapter service that inserts new contacts into the Contact Salesforce object, or a service that inserts new records into both the Contact and Account Salesforce objects. The Create operation wraps the create call of the Salesforce.com Web service API.

The Salesforce.com create call returns a SaveResult object. The adapter service returns the information from the SaveResult object as output.

Output Variable Description
id String The ID of a newly inserted record.
success Boolean Whether the create call successfully inserted a record. If success is:
  • true New record inserted successfully.
  • false New record insertion failed.
errors String List When success is false, errors provides the error codes and descriptions of the errors that the create call encountered.

The input signature of the adapter service contains the name of the Salesforce object or objects that you selected as input parameters. For example, when you select the Account object, the input signature contains Account as input parameter. Each object is a Document List that holds the field values for the records to insert. At run time, pass the adapter service one Document within the sobjects Document List for each record you want to insert.

The output signature of the adapter service contains a results Document List. Each Document in the input sobjects Document List maps to an output Document in the results Document List.

Results

To configure an adapter service that uses the Create Operation template

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  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 IBM webMethods Adapter for Salesforce as the adapter type and click Next.
  6. Select the appropriate Adapter Connection Name and click Next.
    Important: Ensure that the Salesforce.com user account identified by the connection has all the required permissions to insert a record in the Salesforce object that you will select later in the procedure. See Configuring Adapter Services for more information.
  7. From the list of available templates, select the Create 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. In the Select column on the Schema tab, select the check boxes for one or more Salesforce objects into which you want to insert new records.
  9. To use an External ID for a Salesforce object, select the check box for the Salesforce object in the Show External ID column.
  10. To identify the fields to include in the new records:
    1. Select the Create Operation tab.
    2. Click the Populate icon to populate the table with the creatable fields of the selected Salesforce objects.
    3. For each field that you want to include in the new record, select the check box in the Use Field column.

      For example, if you are defining an adapter service that inserts records into the Account and Contact Salesforce objects, you might define the adapter service to provide values for the Account.Name, Account.Type, and Account.ParentId fields, and the Contact.LastName and Contact.FirstName fields.

      The fields and the objects become part of the input signature for the adapter service. When invoking the adapter service, pass the values for these fields as input. The adapter service uses those input values when creating the new records.

      Important: Be sure to select all required fields for a record and all fields required to maintain the referential integrity of the Salesforce object.
      Note: The Create Operation template does not list fields that are automatically created when a new record is added, for example, CreatedDate, CreatedById, LastModifiedDate, LastModifiedById, and SystemModstamp. Although you cannot select these fields, they will be included in new records. Also, the Create Operation template shows only those fields that are marked "creatable" for the create operation.

      At run time, the adapter service determines whether the values specified for the fields are valid, for example ensuring that a date value is specified for a field that has a java.util.Date data type. If an invalid value is detected, the adapter issues an error message and does not attempt to insert the new records.

    4. To create a record in a table that has a reference to a record in another sObject, select the fields in an sObject designated with External IDs. The Relationship Name column shows the sObject record that the selected External ID field relates to. For information about how to assign an External ID to a record field, see Assigning External IDs to sObject Record Fields.
  11. Select File > Save to save the adapter service.

Configuring Custom Query Operation Adapter Services

About this task

Use the Custom Query Operation template to create a query service that allows you to configure a dynamic Salesforce Object Query Language (SOQL) statement, part of which you set at run time using input fields. At run time, the service will create the SOQL statement by combining the contents of the input fields and then executing the statement. This is useful when you need the flexibility to set all or part of an SOQL statement at run time instead of at design time.

The Custom Query Operation service performs a query against a Salesforce object to find records and return selected field values from those records.

Also, when you configure a custom query, you must provide all the fields of the parent object and then the fields of the child object.

For example, in the following query statement: 

SELECT Account.type,Account.Name, Contact.FirstName, Contact.LastName FROM Contact

Provide all the fields of the parent object which is the Contact and then provide all the fields of the child object which are Account.type,Account.Name, Contact.FirstName, Contact.LastName.

Note:

Ensure that all the fields in the parent object is entered before you enter the fields of the child object.

Input and output parameters for the service are optional. An input parameter is required only when the SOQL statement contains the ? placeholder variable. Each ? in the statement corresponds to an input parameter. For example, in the following query statement: 

SELECT ?, Account.Name, (SELECT Contact.FirstName, Contact.LastName 
FROM Account.Contacts) FROM Account ?

you should configure only two input parameters, because the statement contains two ? placeholder variables.

You configure an output parameter only when you want to overwrite the default field name in the output result. For example, in the following query statement: 

SELECT Contact.FirstName, Contact.Account.Name FROM Contact

if you do not configure any output parameters, the service will populate the output result with FirstName and Name as the parameters in the output IData. If you want to overwrite the default parameters with FNAME and AccountName, set the output parameters to FNAME and AccountName.

You must specify the input and output parameters of the adapter service at design time. When you configure the service, the input fields will contain the input for the SOQL statement. The output fields will contain the results from the result set. Make sure that the input and output fields correctly match those of the SOQL statement. If there is any mismatch, the service will generate an exception at run time.

Configuring a Custom SOQL Statement

About this task

Custom SOQL uses the ? placeholder variable to map part of the SOQL statement to the input field. At design time, you need to add an input parameter for each ? placeholder variable in the SOQL statement.

For example, in the following SOQL statement: 

SELECT Account.Id, Account.Name, (SELECT Contact.FirstName, Contact.LastName 
FROM Account.Contacts) FROM Account where Name IN (‘XXX’)

if you want to pass values for Account.Id and the where condition at run time, write the following SOQL statement: 

SELECT ?, Account.Name, (SELECT Contact.FirstName, Contact.LastName 
FROM Account.Contacts) FROM Account ?

In this case, you need to add two input parameters - AccId and whereCondition. When the service executes, specify the following values for the parameters:

  • AccId = Account.Id
  • whereCondition = where Name IN (‘XXX’), where XXX is the actual account name

Configuring a Custom Query Operation Adapter Service

About this task

To configure an adapter service using the Custom Query Operation template

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  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 IBM webMethods Adapter for Salesforce as the adapter type and click Next.
  6. Select the appropriate Adapter Connection Name and click Next.
  7. From the list of available templates, select the Custom 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. Select the Custom Query Operation tab to specify an SOQL statement and the associated input and output parameters.
    1. Select the Include Deleted Records check box to include results from deleted records.
    2. Use the Add icon and set the SOQL parameters as described in the table below.
      Field Description/Action
      Salesforce SOQL Query An SOQL statement. If you need more space to type your statement, use the launch icon to the right to open a text editor window. You can type the statement directly in this field, for example: SELECT Id, Name FROM Account WHERE Name = ‘Sandy’.

      For variable names, use the ? variable placeholder for each variable. For example: SELECT Id, Name FROM Account WHERE Name = ?

      Note: If you use the ? placeholder variable in your SOQL statement, make sure that you enter the corresponding Input Field and Input Field Type information in the same order as they appear in your SOQL statement. In the example given earlier, Name corresponds to the first entry in the Input Field.
      Note: Do not end your SOQL statement with a semi-colon (;) or an exception will be generated.
      Note: You can paste text into this field from the system clipboard. However, you must not cut or copy text from this field to the clipboard for pasting into another application.
      Input Field The name of the input field.
      Input Field Type java.lang.String
      Output Field Output parameters are optional. You configure an output parameter only when you want to overwrite the default field name in the output result.
      Note:

      While mapping the output fields, ensure that the data entered in the output field matches the field name provided in the SOQL statement.

      Native Field Type The native field type of the selected field. Salesforce supports various types of native fields: string, picklist, multipicklist, reference, base64, textarea, phone, id, url, email, encryptedstring, combobox, anyType, time, boolean, int, double, currency, percent, date, datetime. You need to select the appropriate field type.
      Output Field Type The Java data type for the selected native field type. The java field type is automatically selected, after you select the native field type.
  9. Select File > Save to save the adapter service.

Configuring Delete Operation Adapter Services

About this task

Use the Delete Operation template to configure an adapter service that deletes records from your organization's data. For example, you might configure an adapter service that deletes contacts from the Contact Salesforce object. The Delete operation wraps the delete call of the Salesforce.com Web service API.

The input to the adapter service includes an ID String List. At run time, pass the adapter service the ID of each record to delete. Each ID is a String value within the ID String List.

As a response, the Salesforce.com delete call returns a DeleteResult object. The adapter service returns the information from the DeleteResult object as output.

Output Variable Description
id String The ID of a deleted record.
success Boolean Whether the delete call successfully deleted a record.
errors String List If success is false, errors provides the error codes and descriptions of the errors that the delete call encountered.

The IDs of the records to delete in the ID String List input parameter map to the output in the results Document List.

Map

To configure an adapter service that uses the Delete Operation template

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  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 IBM webMethods 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 delete records from the Salesforce object.
  7. From the list of available templates, select the Delete 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. Select File > Save to save the adapter service.

Configuring Monitor Batch Operations Adapter Services

About this task

Use the Monitor Batch Operations template to configure an adapter service that monitors the status and displays the results of the batch operations executed by the adapter’s Batch Operation service.

The input signature of the adapter service contains the values of the jobId and batchId output parameters of the Batch Operation service. For more information about the Batch Operation service, see Configuring Batch Operation Adapter Services.

The following table shows the input parameters of the Monitor Batch adapter service that you configure.

Input Variable Description
jobId String The ID of the job created to perform the batch operation.
batchId String List The ID of the batches of records for which the service returns the results from the executed operation.
filePath String Applies for query operation only. Allows you to view the results of a batch query operation as a file.

The following table shows the output parameters of the adapter service that you configure.

Output Variable Description
Batch Document List
The list contains the following parameters:
  • Batch ID String The ID of the batch specified in the input parameters.
  • Batch Status String The status of the bulk operation performed against the batch with the specified Batch ID.
  • Batch Error Message String Shows any errors that occur when the bulk operation is performed against the batch with the specified Batch ID.
  • Result Document List The result of the bulk operation performed against the batch with the specified Batch ID.
    • Id String The ID of the performed bulk operation in the backend.
    • Status String The status of the bulk operation for a record.
    • Error String Shows any errors that occur when the bulk operation is performed for a record.

The following screenshot shows the Batch output parameter of the Monitor Batch Operations adapter service.

Results

To configure an adapter service using the Monitor Batch Operations template

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  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 IBM webMethods Adapter for Salesforce as the adapter type and click Next.
  6. Select the appropriate Adapter Connection Name and click Next.
  7. From the list of available templates, select the Monitor Batch Operations 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. From the Monitor Batch Operations tab, in the Select Monitor Operation field, select one of the following:
    Field To view
    Batch Information The status of a batch created during an insert, update, upsert, delete, or query operation.
    Batch Information & Results The status and the results of a batch created during an insert, update, upsert, or delete operation.
    Query Operation - Batch Information & Results The status and the results of a batch created during a query operation.
    Query Operation - Batch Results as File The results of a query operation as a file.
  9. Select File > Save to save the adapter service.

Configuring Query Operation Adapter Services

About this task

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.
Results

To configure an adapter service that uses the Query Operation template

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  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 IBM webMethods 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.
    1. Select the Schema tab.
    2. From the Salesforce object list, select the Salesforce object you want to query.
    3. Select the Include Deleted Records checkbox to include all existing and deleted records.
    4. Click the Reload 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.
    1. Select the Query Operation tab.
    2. Click the Populate icon to populate the table with the fields of the selected Salesforce object.
    3. 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.
    1. 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.
    2. 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 Up icon to move the row up, or click the Down 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 > 200000

      In 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.

Configuring Retrieve Operation Adapter Services

About this task

Use the Retrieve Operation template to configure an adapter service that retrieves selected fields from records of a Salesforce object. The Retrieve operation wraps the retrieve call of the Salesforce.com Web service API.

The input to the adapter service includes an ID String List. At run time, pass the adapter service the ID of each record to retrieve. Each ID is a String value within the ID String List.

As a response, the Salesforce.com retrieve call returns the objects that contain the field values of the retrieved records.

The following table describes the output from a Retrieve Operation adapter service:

Variable Description
results Document List Each Document in the Document List contains the selected fields of the retrieved records.

There is a one-to-one mapping between the IDs of the records specified in the ID input parameter to the output in the results Document List.

invalidIds String ListContains the list of invalid IDs.

If the user does not have sufficient privilege or if one or more IDs specified in the input parameter are invalid, the response from the Salesforce.com retrieve() call is null. Adapter for Salesforce cannot retrieve the records for invalid IDs. These invalid IDs are made a part of the invalidIds output parameter.

Note: When there are invalid IDs in the invalidIds output parameter, the number of records in the results output parameter will not match the number of IDs specified in the input signature.

The IDs of the records to retrieve in the IDString List input parameter map to the output in the results Document List.

Map
Note: Salesforce.com imposes restrictions on the number of IDs that can be passed for a single call. Ensure that the number of IDs passed to a single Retrieve operation does not exceed the maximum limit. For more information, see the Force.com Web Services API Developer's Guide.

To configure an adapter service that uses the Retrieve Operation template

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  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 IBM webMethods 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 retrieve records from the Salesforce object that you will select later in the procedure.
  7. From the list of available templates, select the Retrieve 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 from which the adapter service is to retrieve records.
    1. Select the Schema tab.
    2. From the Salesforce object list, select the Salesforce object from which you want to retrieve records.
  9. Identify the fields of the retrieved records that you want returned. If you do not specify fields, the adapter reports an INVALID_FIELD error, which Salesforce.com returns.
    1. Select the Retrieve Operation tab.
    2. Click the Populate icon to populate the table with the fields of the selected Salesforce object.
    3. For each field want returned, select the check box in the Use Field column.
  10. Select File > Save to save the adapter service.

Configuring Update Operation Adapter Services

About this task

Use the Update Operation template to configure an adapter service that updates records of one or multiple Salesforce objects. The update operation wraps the update call of the Salesforce.com Web service API.

As a response, the Salesforce.com update call returns a SaveResult object. The adapter service returns the information from the SaveResult object as output.

Output Variable Description
id String The ID of an updated record.
success Boolean Whether the update call successfully updated a record. If success is:
  • true Records were updated successfully.
  • false Updating records failed.
errors String List When success is false, errors provides the error codes and descriptions of the errors that the update call encountered.

The input signature of the adapter service contains the name of the Salesforce object or objects that you selected as input parameters. For example, when you select the Account object, the input signature contains Account as input parameter. Each object is a Document List that holds the field values and IDs for the records to update. At run time, pass the adapter service one Document within the sobjects Document List for each record you want to update.

The output signature of the adapter service contains a results Document List. Each Document in the input sobjects Document List maps to an output Document in the results Document List.

Results

To configure an adapter service that uses the Update Operation template

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  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 IBM webMethods 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 update records in the Salesforce object that you will select later in the procedure.
  7. From the list of available templates, select the Update 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. In the Select column on the Schema tab, select the check boxes for one or more Salesforce objects into which you want to update records.
  9. To use an External ID for a Salesforce object, select the check box for the Salesforce object in the Show External ID column.
  10. On the Update Operation tab, click the Populate icon to populate the table with the fields of the Salesforce objects you selected.
  11. In the Use Field column, select the check box for every name Id field in the Input Parameter column, where name is the name of the Salesforce object you selected.

    For example, if you selected the Account and Contact Salesforce objects, you have to select the check boxes for the Account.Id and Contact.Id fields respectively.

    The name Id field is included in the input parameters, providing a variable for passing the IDs of the records that the adapter service is to update.

  12. For each field that you want to update in the record, select the check box in the Use Field column.

    For example, if you are defining an adapter service that updates records in the Account and Contact Salesforce objects, you might set up the adapter service to update the Account.Name and Account.Type fields, and the Contact.LastName and Contact.FirstName fields.

    The fields you specify become part of the input signature for the adapter service. When invoking the adapter service, pass the values for the selected fields as input. To reset a non-required field to null, pass a null value for the field.

    Important: When using an update operation adapter service, be sure to specify field values that maintain the referential integrity of the Salesforce objects.
    Note: The Update Operation template lists only fields that you can update for a Salesforce object. If Salesforce.com does not allow you to update a field, for example the MasterRecordId field for a Contact Salesforce object, the adapter service template does not list the field for selection.

    At run time, the adapter service determines whether the values specified for the fields are valid, for example ensuring that a date value is specified for a field that has a java.util.Date data type. If an invalid value is detected, the adapter issues an error message and does not attempt to update the record.

  13. To update a record in a table that has a reference to a record in another sObject, select the fields in an sObject designated with External IDs. The Relationship Name column shows the sObject record that the selected External ID field relates to. For information about how to assign an External ID to a record field, see Assigning External IDs to sObject Record Fields.
  14. Select File > Save to save the adapter service.

Configuring Upsert Operation Adapter Services

About this task

Use the Upsert Operation template to configure an adapter service that inserts records or updates records of a Salesforce object. When attempting to add new records, you can use the upsert operation instead of the create operation to avoid the potential of inserting duplicate records. The upsert operation wraps the upsert call of the Salesforce.com Web service API.

Important: In the Salesforce.com Partner WSDL version 25.0, all records must have the same object type in an upsert() call. When you select multiple Salesforce objects, Salesforce.com throws an exception.

For the upsert operation, you specify the value of a field that the operation uses to determine whether a record already exists. The field must be:

  • For standard objects, a field with the idLookup property. This is usually the object's ID, Name field, or both.
  • For custom objects, a field with the external ID attribute.

If the record does not already exist, the upsert operation inserts it. If the record does exist, the upsert operation updates it. You cannot create or update the values of the fields, which are auto generated by Salesforce.com.

As a response, the Salesforce.com upsert call returns an UpsertResult object. The adapter service returns the information from the UpsertResult object as output.

Output Variable Description
created Boolean Whether the upsert operation inserted or updated the specified record. The value of created is true if the upsert operation inserted the record or false if the upsert operation updated the record.
id String The ID of the created or updated record when success is true. If success is false, id is null.
success Boolean Whether the upsert call successfully inserted/updated the record.
errors String List If success is false, errors provides the error codes and descriptions of the errors that the upsert call encountered.

The input signature of the adapter service uses an sobjects Document List, which holds the field values the upsert operation uses. At run time, pass the adapter service one Document within the sobjects Document List for each record on which you want to act.

The output signature of the adapter service contains a results Document List. Each Document in the input sobjects Document List maps to an output Document in the results Document List.

Results

To configure an adapter service that uses the Upsert Operation template

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  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 IBM webMethods 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 insert/update records in the Salesforce object that you will select later in the procedure.
  7. From the list of available templates, select the Upsert 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. To identify the Salesforce object on which you want the adapter service to act and the field to use to determine whether a record already exists:
    1. Select the Schema tab.
    2. In the Salesforce Object column, select the Salesforce object for which you want to insert/update records from the drop-down list.
      Object

      Designer updates the ID Field Name field with values based on the Salesforce object that you select.

      Note: The Upsert Operation service supports creating/updating records for a single Salesforce object at a time. Adding rows in the Salesforce Object column does not affect the ID Field Name list.
    3. From the ID Field Name list, select the field that you want to use to determine whether a record already exists in the Salesforce object.

      At run time, pass a value for this field as input into the adapter service. If the value matches an existing record, the adapter service updates the record. If the value does not match an existing record, the adapter service inserts a new record.

  9. Include the ID Field Name that you selected earlier in the procedure to the input parameters to provide a variable for passing the value that the upsert operation uses to determine whether a record exists.
    1. Select the Upsert Operation tab.
    2. Click the Add row icon to add one field row to the table.
    3. If the newly added field is not the field you specified for ID Field Name, select that field from the list in the Input Parameter column.
    4. Select the check box in the Use Field column for the field.
      Note: If you do not include the ID Field Name field on the Upsert Operation tab, the upsert operation will insert new records, generating IDs for each record. If you do include the ID Field Name field and a value supplied does not match an existing record, the upsert operation inserts the new record using the value you supply for the field.
  10. To identify the fields of the records for which you want to supply information:
    1. Select the Upsert Operation tab.
    2. Click the Populate icon to populate the table with the fields of the selected Salesforce object.
    3. For each field that you want to supply, select the check box in the Use Field column.
      Important: When using an upsert operation adapter service, be sure to specify field values that maintain the referential integrity of the Salesforce object.
      Note: The Upsert Operation template lists only fields that can be created and updated.

      If the adapter service inserts a record, these are the fields the adapter service supplies for the new record. If the adapter service updates a record, these are the fields the adapter service updates. The fields you specify become part of the input signature for the adapter service.

      At run time, the adapter service determines whether the values specified for the fields are valid, for example, ensuring that a date value is specified for a field that has a java.util.Date data type. If an invalid value is detected, the adapter issues an error message and does not attempt to insert/update the record.

    4. To upsert a record in a table that has a reference to a record in another sObject, select the fields in an sObject designated with External IDs. The Relationship Name column shows the sObject record that the selected External ID field relates to. For information about how to assign an External ID to a record field, see Assigning External IDs to sObject Record Fields.
  11. Select File > Save to save the adapter service.

Configuring Utility Operation Adapter Services

About this task

Use the Utility Operation template to configure an adapter service that invokes one of the following Salesforce.com utilities:

  • getServerTimestamp to retrieve the current Salesforce.com system timestamp.
  • getSessionId to obtain a session ID or an access token that you use to implement custom Salesforce.com operations that the adapter does not support. If you use a normal Salesforce.com connection, getSessionId will return a session ID. If you use an OAuth Salesforce.com connection, getSessionId will return an access token.
  • getUserInfo to obtain personal information about the currently logged-in user, that is, the user account used for the adapter connection. Your adapter service might obtain this information to use for display purposes.
  • resetPassword to change a user's password to a temporary, system-generated value.
  • sendEmail to send a single e-mail message.
  • sendMassEmail to send multiple e-mail messages.
  • setPassword to change the password of a user's password to a specified value.

You select the utility that you want the adapter service to execute. The input and output signatures of the adapter service are based on the inputs and outputs of the selected utility. For more information about utilities and parameters that a utility expects as input or returns as output, see the Force.com Web Services API Developer's Guide.

To configure an adapter service that uses the Utility Operation template

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  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 IBM webMethods 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 execute the utility that you will select later in the procedure.
  7. From the list of available templates, select the Utility 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 utility that you want the adapter service to invoke.
    1. Select the Utility Operation tab.
    2. From the Utility Call list, select the utility you want to use.
  9. View the Input Fields tab to see the inputs for the utility and the Output Fields tab to see the outputs that the utility returns. For a description of the input and output fields, see the Force.com Web Services API Developer's Guide.
  10. Select File > Save to save the adapter service.

Testing Adapter Services

About this task

You can test adapter services using Designer. For more information about testing and debugging services, see the IBM webMethods Service Development Help for your release.

To test an adapter service

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  2. In Designer, expand the package and folder that contain the service you want to test.
  3. Double-click the service you want to test.

    Designer displays the configured service in the service template's Adapter Service Editor.

  4. Select Run > Run As > Run Service.
  5. Optionally, provide the user credentials to connect to Salesforce.com. This user name and password overrides credentials specified in the adapter connection being used for the adapter service.
    Parameter Description/Action
    username The user name used to connect to the Salesforce.com.
    password The password used to connect to the Salesforce.com.

    Salesforce.com requires a security token for access via Force.com Web service API. You can obtain the security token from the Salesforce.com user interface.

    For example, if the password is "mypassword" and the security token is "XXXXXXXXXX", specify the following for Password and Retype Password:

    mypasswordXXXXXXXXXX

    Note: The security token is valid until you reset it, change your password, or have your password reset. The security token is not required, if the endpoint URL is a Salesforce.com sandbox.
  6. Specify values for the input parameters of the adapter service.
  7. Optionally, specify an alternative connection to use by providing the connection name in the $connectionName input parameter.
    Note: Credentials you provide in the username and password fields override any connection. Specifying the $connectionName input parameter changes the connection for this execution of the service. To reconfigure the service to use a different connection, use the setAdapterServiceNodeConnection, which is located in the WmART package's pub.art.service folder. For more information about this service, see the IBM webMethods Integration Server Built-In Services Reference for your release.
  8. Click OK.
  9. Click the Service Result tab to view the output from this service.

Viewing Adapter Services

About this task

You use Designer to view adapter services.

To view an adapter service

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  2. In Designer, expand the package and folder that contain the service you want to view.
  3. Double-click the service you want to view.

    Designer displays the configured service in the service template's Adapter Service Editor.

Editing Adapter Services

About this task

You use Designer to edit adapter services.

To edit an adapter service

Procedure

  1. In Designer, browse to and open the adapter service that you want to edit.
  2. Double-click the service that you want to edit.

    Designer displays the adapter service in the service template's Adapter Service Editor.

  3. Do one of the following:
    • If you have the VCS Integration feature enabled, right-click the service and select Check Out.
    • If you do not have the VCS Integration feature enabled, right-click the service and select Lock for Edit.
    • If you are using the local service development feature, from the Team menu in Designer, select the appropriate option to check out the service. The options available in the Team menu depend on the VCS client that you use.
  4. Modify the values for the adapter service's parameters as needed. For detailed descriptions of the service's parameters, see the section on configuring a service for the specific type of service you want to edit.
  5. After you complete your modifications, save the service and do one of the following:
    • If you have the VCS Integration feature enabled, right-click the service and select Check In. Enter a check-in comment and click OK.
    • If you do not have the VCS Integration feature enabled, right-click the service and select Unlock.
    • If you are using the local service development feature, from the Team menu in Designer, select the appropriate option to check in the service. The options available in the Team menu depend on the VCS client that you use.
  6. Save the service.

Deleting Services

About this task

You use Designer to delete adapter services.

To delete a service

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  2. In Designer, expand the package and folder that contain the service you want to delete.
  3. Right-click the adapter service and click Delete.

Validating Adapter Service Values

About this task

Designer enables Adapter for Salesforce to validate user-defined data for adapter services at design time. You can validate the values for a single adapter service or you can configure Designer to always validate the values for adapter services. Both options could potentially slow your design-time operations.

When you enable data validation for a single adapter service, Designer compares the service values against the resource data that has already been fetched from the selected adapter.

If you select the option to always validate values for adapter services, it will do so for all webMethods WmART-based adapters installed on Integration Server.

For more information about the Adapter Service/Notification Editor and other Designer menu options and toolbar icons, see the IBM webMethods Service Development Help for your release.

Enabling Automatic Validation for a Single Adapter Service

About this task

To enable automatic data validation for a single adapter service

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  2. In Designer, expand the package and folder that contain the service for which you want to enable automatic validation.
  3. Double-click the service for which you want to validate the data.

    Designer displays the configured adapter service in the service template's Adapter Service Editor.

  4. Click the Enable icon.

Enabling Automatic Validation for All Adapter Services

About this task

To always validate the values for all adapter services

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  2. Start Designer.
  3. Select the Window > Preferences > webMethods > Service Development > Adapter Service/Notification Editor item.
  4. Enable the Automatic data validation option.
  5. Click OK.

Changing the Credentials Associated with an Adapter Service at Run Time

About this task

Adapter for Salesforce allows users to specify an alternate connection or user credentials at run-time to invoke the adapter services.

  • Configure the adapter service to use the default connection (with which the service was created) or specify an alternate connection alias, as part of the $connectionNameinput field.
  • Execute the adapter service by overriding the default credentials, as part of the input signature for the adapter service. The input signature for the adapter services contains a separate document structure: ‘overrideCredentials', with fields $username and $password, for specifying the username and password to be used for the adapter service execution.
Override
Note: These dynamic credentials are valid only for the currently selected adapter service during runtime. The adapter service makes a separate login request and gets a new sessionId, with which the service call is executed. The adapter service does not use the connection from the connection pool when dynamic credentials are specified. Ensure that the credentials have sufficient privilege to perform the operation.

If there are no values specified for the $username and $password fields, the adapter service uses the default connection.

Note: When you change the credentials associated with an adapter service at runtime by overriding the default credentials, the adapter communication with Salesforce.com does not use compression.

Reloading Adapter Values

About this task

You can enable Adapter for Salesforce to reload and validate user-defined data for adapter services at design time in Designer. You can reload values for a single adapter service or you can configure Designer so it automatically reloads the values for adapter services. Both options could potentially slow your design-time operations.

When you reload adapter values for a single adapter service, Designer compares the service values against the resource data that has already been fetched from the selected adapter.

If you select the option to always reload values for adapter services, it will do so for all webMethods WmART-based adapters installed on Integration Server.

For more information about the Adapter Service/Notification Editor, other menu options, and toolbar icons, see the IBM webMethods Service Development Help for your release.

Reloading Values for a Single Adapter Service

About this task

To reload the adapter values for a single adapter service

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  2. In Designer, expand the package and folder that contain the service for which you want to enable automatic validation.
  3. Double-click the service for which you want to validate the data.

    Designer displays the configured adapter service in the service template's Adapter Service Editor.

  4. Click the Reload icon.

Reloading Values for All Adapter Services

About this task

To reload the adapter values for all adapter services

Procedure

  1. Review the steps in Before Configuring or Managing Adapter Services.
  2. Start Designer.
  3. Select the Window > Preferences > webMethods > Service Development > Adapter Service/Notification Editor item.
  4. Enable the Automatic polling of adapter metadata option.
  5. Click OK.