CA API Gateway 9.1

9.4 9.1

Execute Salesforce Operation Assertion

 
gateway90
 
The custom
Execute Salesforce Operation
 assertion allows CA API Gateways to integrate with the SaaS data APIs provided by Salesforce.com.
This is an extra-cost assertion that requires separate licensing. For instructions on how to install this assertion, refer to the
CA API Gateway - Custom Assertions Installation Manual
.
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.
Context variables created by the Execute Salesforce Operation assertion
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.
Installing and configuring the Salesforce Custom Assertion package in the Gateway installs and enables the Execute Salesforce Operation assertion in the Policy Manager. The Administrator is responsible for installing and configuring the Salesforce Custom Assertion package on the Gateway. For more information, refer to the
Custom Assertion Installation Manual
.
When running this assertion in the browser client, a triangular warning icon (Exclamation_in_triangle.png) may appear next to the dialog box when the assertion properties is displayed. You may ignore this icon.
Using the Assertion
  1. Do one of the following:
    • To add the assertion to the policy development window, see "Adding an Assertion".
    • To change the configuration of an existing assertion, proceed to the next step.
  2. In the Policy Manager’s 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. The table below describes the operation's settings.
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 so that, if the assertion fails to create an object, the assertion removes (rolls back) the objects it previously created during the call and does not try to create more. This setting is the default.
Clear this check box so that, if the assertion fails to create an object, the assertion will continue to create objects and it will not remove any objects. You will have to look at the returned success/failure status for each object and create policy logic to handle the failures.
Salesforce.com only supports batches up to 200 objects, and the assertion automatically issues multiple calls if required. This means that, if the assertion fails to create the 205th object, then the assertion only rolls back objects 201-204. It will not roll back objects 1-200 because they were 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.
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 will fail.
Variable Prefix
Enter a prefix that will be added to the context variables created by this assertion. This prefix will ensure uniqueness and will prevent 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.
Records with truncated fields will still be successfully created. The truncation will be 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 so that, if the assertion fails to create an object, the assertion removes (rolls back) the objects it previously created during the call and does not try to create more. This setting is the default.
Clear this check box so that, if the assertion fails to create an object, the assertion will continue to create objects and it will not remove any objects. You will have to look at the returned success/failure status for each object and create policy logic to handle the failures.
Salesforce.com only supports batches up to 200 objects, and the assertion automatically issues multiple calls if required. This means that, if the assertion fails to create the 205th object, then the assertion only rolls back objects 201-204. It will not roll back objects 1-200 because they were 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 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 leveraging context variables.
Variable Prefix
Enter a prefix that will be added to the context variables created by this assertion. This prefix will ensure uniqueness and will prevent 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.
Records with truncated fields will still be successfully created. The truncation will be 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 will be 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 will be added to the context variables created by this assertion. This prefix will ensure uniqueness and will prevent 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. 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.
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 will default to the current time and always be greater than the From UTC Time.
The
<prefix>.lastDateCovered
 value from a previous assertion execution can be leveraged 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 will be 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 will be added to the context variables created by this assertion. This prefix will ensure uniqueness and will prevent 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 table below describes the operation's settings.
The assertion will return the GUIDs for any objects that meet the criteria 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 will default to the current time and always be greater than the From UTC Time.
The
<prefix>.lastDateCovered
 value from a previous assertion execution can be leveraged here to ensure full coverage.
Variable Prefix
Enter a prefix that will be added to the context variables created by this assertion. This prefix will ensure uniqueness and will prevent 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. The table below describes the operation's settings.
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 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 will be added to the context variables created by this assertion. This prefix will ensure uniqueness and will prevent 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 will be added to the context variables created by this assertion. This prefix will ensure uniqueness and will prevent 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.

Content feedback and comments