Understanding Connector Operations

Note: This topic describes the fundamental concepts to understand when using Connector operations. For operation configuration for specific types of Connectors, see the individual Connector documentation under 2 - Application Connectors.

The operation represents a specific action or API call against the application or data source defined by the connection. For example, the operation is where you define which web service call to make (e.g., Get Purchase Orders, Update Account), the FTP directory and file filter to get, how to batch commit database inserts, which e-mail addresses to send to, etc.

The configuration options differ widely between Connectors due to the capabilities of each application's or data source's API. Most application operations provide a simple wizard interface to configure the operation and import the request and/or response profiles to use in the Process to map to/from, etc. When available, always use the wizard to configure the operation.

Operations and Data Profiles

For data source Connectors such as HTTP, Disk, FTP, SFTP and Mail the data format or profile is independent from the operation: you can technically send any type of data you want to an FTP directory or HTTP URL. Of course your integration requirements will probably dictate that format but technically they are unrelated. That is not the case for application Connectors. Connector operations for applications expect a specific format or profile (typically an XML profile type) representing a request message to that application or a response message from it. The XML profile(s) is automatically generated for you during the configuration of the operation using the import wizard.

When retrieving data from a Connector the document data returned will "look like" the response profile defined in the Operation. You will use this profile when mapping to another format or whenever you need to reference a specific field in a Process step configuration. Similarly when sending data to a Connector the document data to send must "look like" the request profile specified in the Operation. You will use this profile when mapping from another format or whenever you need to reference a specific field in a Process step configuration.

When sending to a Connector, you need to map the document data to the XML profile defined in that Connector's operation. If you pass the wrong data into an operation, the Connector call will fail. For example, although a "Create Customer" profile and an "Update Customer" profile may look almost identical and have the same fields, it is important to understand they are different and require separate operations and separate profiles.

Using Filters and Setting Dynamic Parameter Values

Operations for application Connectors are typically configured with filters to limit the results returned. These filters are usually supplied with a value passed in from the Process step that is calling the operation, including a Connector step. Standard data source Connectors like Disk, FTP, SFTP, Mail and HTTP client/server also support parameters. Message filters are defined statically. Most "Send" operations typically do not implement filters and therefore do not require parameters to be configured.

When configuring a filter in the operation you specify which field to filter by and the comparison operator, but you do not specify the value to compare. For example, in the operation you will configure something like "Customer Name Equals _____". The value for that "blank" is provided when you use the operation in your Process, either in a Connector step or as a Connector call look-up in a variety of places. The value itself can be any number of things, from a static value, a value from the current document data, or a special value like the current date or the last run date of the Process. Click here for the full list of parameter value types.

This parametrized design allows for more flexible and enables reusability. This allows you to use the same operation component in a variety of situations and does not tie you to a specific type of input value.

Configuring Operation Filters

This example uses the Salesforce Operation for demonstration purposes. The exact configuration differs between Connectors. See the individual Connector documentation under 2 - Application Connectors for more information. Not all types of Connectors support filters in this way.

General Procedure: To Add Filters to an Operation

Create a new operation or edit an existing one.
Click the Options tab.
(Optional) Click the Import button and use the wizard to generate the XML profile and configure the operation.
At the bottom of the page, add a filter.
Configure the filter with a user-defined name, the field to filter against and a comparison operator.
The user-defined name will be displayed as the operation's "inputs".

Note: This filter name will display in the list of operation inputs when the operation is referenced.
Save the operation.
Create a new Process and edit the Start step.
The Start Shape dialog opens.
On the General tab, select the appropriate Connector type, an existing connection and the operation from above.
Click the Parameters tab.
Click the Add ( ) icon to add a new parameter. This parameter will represent the value to pass into one of the filters defined in the operation.
Click the Browse ( ) icon next to Input and select a filter to provide a value for and click OK.
Notice this value is the same as the user-defined filter name above.
Set Type to Static.
Specify a value to pass into the operation input and click OK.
See Setting Parameters for more information.

You can create multiple filters and add multiple parameters and mix static and dynamic values. One common dynamic value to use in the Start step is to create a filter that extracts records where the "last modified date" is greater than some value, and pass in the special Last Run Date value as the parameter. This is how you can design incremental synchronizations.

Database Connector Filters

The Database Connector is a little different from the other application Connectors because the "filters" are actually defined by the SQL statement defined in the Database profile referenced in the operation instead of being defined within the operation itself. However, setting these parameter values is no different than it is for the other application Connectors. The list of available inputs are the list of elements under the Parameters section of the Database Profile.

Additional Information on Filters

Implicit Filters

Some types of Connector operations have actions with "implicitly" defined filters. You do not have to configure them; they simply appear in the list of operation inputs. For example, the NetSuite Connector Get action allows you to query a single record with its internal ID. The operation automatically creates a filter called internalID.

Setting Request Profile Values Directly

Some types of application Connector operations do not have the ability to create filters, however you can directly assign values for values elements in the request XML profile before the request is sent to the application. For example, the QuickBooks Connector allows you to set the various criteria fields directly, such as FromModifiedDate and RefNumber.

Same Object, Different Operations with Different Filters

An operation represents a specific call to an application but also with specific settings, including filters. This means you can have two separate "Query Customers" operations, but one filters by Name and the other filters by External Id. Then when you need to look up a customer by name, use the filter by name operation; when you need to look up a customer by external ID, use the filter by external ID operation.