Skip to content
CA API Gateway - 9.3
Documentation powered by DocOps

Execute Salesforce Operation Assertion

Last update August 30, 2018

The Execute Salesforce Operation Assertion allows the CA API Gateway to integrate with the SaaS data APIs provided by Salesforce.com.

Tip: when running this assertion in the browser client, a triangular warning icon () may appear next to the dialog when the assertion properties is displayed. You may ignore this icon.

Separate Installation Required

For instructions on how to install this assertion, see Install the Salesforce Integration Solution Kit. Once installed, this assertion is available from the Custom Assertions palette.

Contents:

Context Variables Created by This Assertion

The Execute Salesforce Operation assertion sets the following context variables for each action. Note: The default <prefix> is "sfdc" and can be changed in the wizard.

Action & Variable Description
Action: Create Objects
${<prefix>. sessionURL} Returns the session URL used for the call.
${<prefix>. sessionID} Returns the session ID used for the call.
$<prefix>.count} Returns the number of records processed.
${<prefix>. objectID} On success, returns the object IDs.
${<prefix>.error} Returns error messages, if any.
${<prefix>. warning} Returns warning messages for specific records, if any (for example, “Unknown picklist” or “Field truncated”).
Action: Update Objects
${<prefix>. sessionURL} Returns the session URL used for the call.
${<prefix>. sessionID} Returns the session ID used for the call.
${<prefix>.count} Returns the number of records processed.
${<prefix>. objectID} On success, returns the object IDs; multivalued.
${<prefix>.error} Returns error messages, if any; multivalued.
${<prefix>. warning} Returns warning messages, if any; multivalued.
Action: Retrieve Objects
${<prefix>. sessionURL} Returns the session URL used for the call.
${<prefix>. sessionID} Returns the session ID used for the call.
${<prefix>. sObjectIDs} On success, returns the object IDs; multivalued.
${<prefix>. sObjects. <fieldName>} On success, returns multivalued context variables; (optional).
Action: Retrieve Modified Objects
${<prefix>. sessionURL} Returns the session URL used for the call.
${<prefix>. sessionID} Returns the session ID used for the call.
${<prefix>. ObjectID} On success, returns the object IDs; multivalued.
${<prefix>. lastDateCovered} On success, returns the last date covered.
${<prefix>. sObjects. <fieldName>} On success, returns multivalued context variables; (optional).
${<prefix>. sObjects} On success, returns XML representing the objects (optional); multivalued.
Action: Retrieve Deleted Objects
${<prefix>. sessionURL} Returns the session URL used for the call.
${<prefix>. sessionID} Returns the session ID used for the call.
${<prefix>. sObjects} On success, returns list of objects.
${<prefix>. lastDateCovered} On success, returns the last date covered.
Action: Execute Query
${<prefix>. sessionURL} Returns the session URL used for the call.
${<prefix>. sessionID} Returns the session ID used for the call.
${<prefix>. queryLocator} On success, returns the query locator of the query executed.
${<prefix>.count} Returns the number of records processed.
${<prefix>.done} Returns true or false based on the number of records processed.
${<prefix>.sObjects. <fieldName>} On success, returns multivalued context variables; (optional).
${<prefix>. sObjectXML} On success, returns XML representing the objects (optional); multivalued.
Action: Search Objects
${<prefix>. sessionURL} Returns the session URL used for the call.
${<prefix>. sessionID} Returns the session ID used for the call.
${<prefix>.count} Returns the number of records processed.
${<prefix>. sObjects} On success, returns multivalued context variables.

Using the Assertion

  1. Do one of the following:
    • To add the assertion to the policy development window, drag the assertion from the palette.
    • To change the configuration of an existing assertion, proceed to the next step.
  2. In the policy window, right-click Executive Salesforce Operation and click Execute Salesforce Operation Properties. Alternatively, double-click the assertion in the policy window. The Execute Salesforce Operation Wizard is displayed.
  3. In the list, choose a Salesforce connection to use and then click [Reconnect]. The Salesforce connections are defined using the Manage Salesforce Operation Service Connections task.
  4. Select a Salesforce Action (operation) to perform and then click [Next].
  5. Configure the Salesforce action. See the appropriate section below for details.
  6. Click [Finish] to close the wizard when done.

Creating Objects

To create objects in Salesforce, choose the Create Objects action in the Execute Salesforce Operation wizard. Configure the settings as follows:

Setting Description
Select Object Type Choose the object type to be created from the drop-down list. The object type determines which other fields require population.
Rollback On Error

Select this check box to have the assertion roll back (remove) all objects created during a call if it fails to create an object. The Gateway does not try to create further objects. This setting is the default.

Clear this check box to have the assertion continue to create objects even after a failure. The Gateway does not remove any objects. You must review the returned success/failure status for each object and create policy logic to handle the failures.

Important Information About Rollbacks

Salesforce.com only supports batches up to 200 objects, and the assertion automatically issues multiple calls if necessary. This means that, if the assertion fails to create the 205th object, then the assertion only rolls back objects 201-204. It does not roll back objects 1-200, because they are considered part of the previous call.

Select Assignment Rule For objects of type “Case” or “Lead”, choose the assignment rule to use from the drop-down list.

Select Object Fields

Select the fields to populate when the object is created. Then enter a value for each selected field. You may specify context variables. Mandatory fields are preselected and must be completed.

Tip: You can create more than one object at a time by specifying multivalued context variables for each field. Ensure that all the multivalued variables have the same number of values, otherwise the assertion fails.

Variable Prefix Enter a prefix that is added to the context variables created by this assertion. This prefix ensures uniqueness and prevents the variables from overwriting each other when multiple instances of this assertion appear in a policy.
Truncate values if too long

Select this check box to truncate input values if their length is greater than the maximum length for the given field.

Clear this check box to leave long input values at their full length.

Note: Records with truncated fields are still created successfully. The truncation is noted in the ${<prefix>.warning} context variable.

Updating Objects

To update objects in Salesforce, choose the Update Objects action in the Execute Salesforce Operation wizard. The table below describes the operation's settings.

Configure the settings as follows:

Setting Description
Select Object Type Choose the object type to be updated. The object type determines which other fields require population.
Rollback On Error

Select this check box to have the assertion roll back (remove) all objects created during a call if it fails to create an object. The Gateway does not try to create further objects. This setting is the default.

Clear this check box to have the assertion continue to create objects even after a failure. The Gateway does not remove any objects. You must review the returned success/failure status for each object and create policy logic to handle the failures.

Important Information About Rollbacks

Salesforce.com only supports batches up to 200 objects, and the assertion automatically issues multiple calls if necessary. This means that, if the assertion fails to create the 205th object, then the assertion only rolls back objects 201-204. It does not roll back objects 1-200, because they are considered part of the previous call.

Select Assignment Rule This drop-down is enabled only when you are updating an object of type 'Case' or 'Lead'. Select the Assignment Rule from the drop-down list.

Select Object Fields

Select the fields that you want to populate when updating the object. The “Id” field is mandatory. Provide values for the object you are updating by entering text directly or by referencing context variables.
Variable Prefix Enter a prefix that is added to the context variables created by this assertion. This prefix ensure uniqueness and prevents the variables from overwriting each other when multiple instances of this assertion appear in a policy.
Truncate values if too long

Select this check box to truncate input values if their length is greater than the maximum length for the given field.

Clear this check box to leave long input values at their full length.

Note: Records with truncated fields are still created successfully. The truncation is noted in the ${<prefix>.warning} context variable.

Retrieving Objects

To retrieve objects in Salesforce, choose the Retrieve Objects action in the Execute Salesforce Operation wizard. The table below describes the operation's settings.

Configure the settings as follows:

Setting Description
Select Object Type Choose the object type to be retrieved. The object type determines which other fields require population.
Object ID(s) You can specify one or more Object IDs to retrieve. This field accepts context variables.
Select Fields to be Retrieved Select the fields to be included in the retrieved object information. By default, the “Id” field is selected.
Generate XML Output

Select this check box to return the object information in XML format.

Clear this check box to return the object information in a multi-valued context variable.

Variable Prefix Enter a prefix that is added to the context variables created by this assertion. This prefix ensures uniqueness and prevents the variables from overwriting each other when multiple instances of this assertion appear in a policy.

Retrieving Modified Objects

To retrieve modified objects in Salesforce, choose the Retrieve Modified Objects action in the Execute Salesforce Operation wizard. Configure the settings as follows:

Setting Description
Select Object Type Choose the object type to be retrieved. The object type determines which other fields require population.

Timeframe


Choose a time frame from the drop-down list: Past Hour, Past Day, Past Week, or Custom.

The “Custom” option displays two additional text fields with which you can specify context variables for the custom period:

  • From UTC Time: From UTC Time is mandatory. It cannot be more than 15 days in the past. The required format of custom time frames is: “YYYY-MM-DD HH:MM:SS”.
  • To UTC Time: If To UTC Time is left blank, it defaults to the current time, which is always greater than the "From UTC Time".

Tip: The <prefix>.lastDateCovered value from a previous assertion execution can be used here to ensure full coverage.

Retrieve Object Information

Select this check box to retrieve the GUID of matching objects and the object information for each those objects. Selecting this check box also enables the Select Fields to Be Retrieved setting and the Generate XML Output setting.

Clear this check box to retrieve only the GUID of matching objects.

Select Fields to Be Retrieved Select the fields to be included in the retrieved object information. By default, the “Id” field is selected.
Generate XML Output

Select this check box to return the object information in XML format.

Clear this check box to return the object information in a multi-valued context variable.

Variable Prefix Enter a prefix that is added to the context variables created by this assertion. This prefix ensures uniqueness and prevents the variables from overwriting each other when multiple instances of this assertion appear in a policy.

Retrieving Deleted Objects

To retrieve deleted objects in Salesforce, choose the Retrieve Deleted Objects action in the Execute Salesforce Operation wizard. The assertion returns the GUIDs for any objects that meet the criteria that are specified. Field values cannot be retrieved for deleted objects.

Configure the settings as follows:

Setting Description
Select Object Type Choose the object type to be retrieved. The object type determines which other fields require population.

Enter Timeframe

Choose a timeframe from the drop-down list: Past Hour, Past Day, Past Week, or Custom.

The “Custom” option displays two additional text fields with which you can specify context variables for the custom period:

  • From UTC Time: From UTC Time is mandatory. It cannot be more than 15 days in the past. The required format of custom time frames is: “YYYY-MM-DD HH:MM:SS”.
  • To UTC Time: If To UTC Time is left blank, it defaults to the current time, which is always greater than the "From UTC Time".

Tip: The <prefix>.lastDateCovered value from a previous assertion execution can be leveraged here to ensure full coverage.

Variable Prefix Enter a prefix that is added to the context variables created by this assertion. This prefix ensures uniqueness and prevents the variables from overwriting each other when multiple instances of this assertion appear in a policy.

Executing Queries

To execute queries in Salesforce, choose the Execute Query action in the Execute Salesforce Operation wizard. Configure the settings as follows:

Setting Description

Execute New Query

Select this option to begin a new query. Enter the SOQL query by typing or pasting text or specifying a context variable.
Validate Query button Click this button to validate the query that was entered in the box above.
Include archived and deleted records in result

Select this check box to include archived and deleted records in the results.

Clear this check box to exclude archived and deleted records from the results.

Continue From Previous Query

Select this option to begin the result set after the previously returned result set. Enter either a static query locator or a context variable query locator that is resolved at run time
Return first 500 records only

Select this check box to return only the first 500 records.

Clear this check box to return all the records.

Generate XML Output

Select this check box to return the object information in XML format.

Clear this check box to return the object information in a multi-valued context variable.

Variable Prefix Enter a prefix that is added to the context variables created by this assertion. This prefix ensures uniqueness and prevents the variables from overwriting each other when multiple instances of this assertion appear in a policy.

Searching Objects

To search objects in Salesforce, choose the Search Objects action in the Execute Salesforce Operation wizard. The table below describes the operation's settings.

Configure the settings as follows:

Setting Description

Enter Search Query (SOSL)

Enter the SOSL query by typing or pasting text or specifying a context variable. A maximum of 200 records can be retrieved with each SOSL query.

Validate button Click this button to validate the SOSL query.
Variable Prefix Enter a prefix that is added to the context variables created by this assertion. This prefix ensures uniqueness and prevents the variables from overwriting each other when multiple instances of this assertion appear in a policy.

Exporting/Importing Policies

After importing a policy that uses the custom Execute Salesforce Operation assertion,open the assertion and do one of the following before using the policy:

  • If the assertion has a selected connection, no action is needed.
  • If the assertion has connections but none is selected, then select a connection and save the assertion.
  • If the assertion does not have any connections, use the Manage Salesforce Operation Service Connection task to create a connection. Then open the assertion, select the new connection, and save the assertion. For information about creating connections, see "Managing Salesforce Operation Service Connections" under 2019-05-17_18-47-00_Salesforce Integration Solution Kit.
Was this helpful?

Please log in to post comments.