Adapter Polling Notifications

Overview

Adapter for Salesforce facilitates polling of data with Salesforce.com using the adapter polling notification templates. These templates enable a user to specify the sObjects needed to poll Salesforce.com at specified periodic intervals for any changes in the organization's data. This essentially includes creating, updating, and deleting records. The adapter uses the data replication APIs provided by Force.com Web services, getUpdated() and getDeleted(), to implement the polling notification.

Before you configure Adapter for Salesforce polling notifications, you must configure the connections you plan to use with them. See Configuring Adapter Connections for details.

For a description of adapter polling notifications, see Adapter Polling Notifications.

If you are using the adapter in a clustered environment, you will need to configure the polling notifications so that they run effectively. For more information, see Polling Notification Support in Integration Server Clusters.

Before Configuring Adapter Polling Notifications

About this task

Before you configure a Adapter for Salesforce polling notification

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 polling notification. See Configuring Adapter Connections for instructions.
  5. Start IBM webMethods Designer if it is not already running.
    Note: Use the Service Development perspective in Designer. For more information, see the IBM webMethods Service Development Help for your release.
  6. Using Designer, create a user-defined package to contain the polling notification, if you have not already done so. When you configure adapter notifications, you should always define them in user-defined packages. For more information about managing packages for the adapter, see Managing the Adapter Package.

What to do next

Note: You must schedule and enable a polling notification before you can use it.

Configuring Adapter Polling Notifications

About this task

The polling notification template is designed to work on a single Salesforce object at a time. The object must be replicable (that is, the replicateable field for the Object must be set to "true"; for more information, see the Force.com Web Services API Developer's Guide). Adapter for Salesforce defines two polling notification templates, one for capturing any create or update changes and another for any records deleted.

Adapter for Salesforce uses the getUpdated() call to implement Upsert Notifications and getDeleted() call for Delete Notifications. The call takes three input parameters: startDate, endDate and sObject as explained below:

  • startDate: The initial start date is calculated by the polling notification based on the day count parameter provided by the user. For subsequent calls, the start date is used as the latestDateCovered from the previous notification.
  • endDate: The current date is used as the end date by the polling notification.
  • sObject: The object selected by the user during creation of the polling notification.

Creating an Upsert Polling Notification

About this task

An Upsert Notification publishes an output document containing the IDs of the updated sObjects for the given time interval.

To configure an Upsert polling notification

Procedure

  1. Review the steps in Before Configuring Adapter Polling Notifications.
  2. Start Designer.
  3. Right-click the package in which the notification should be contained and select New > Adapter Notification.
  4. Select the parent namespace, type a name for the adapter notification, and click Next.
  5. Select IBM webMethods Adapter for Salesforce as the adapter type and click Next.
  6. Select Upsert Notification as the Template Name and click Next.
  7. Select the appropriate Adapter Connection Name and click Next. This specifies the connection that the notification will use to connect to the Salesforce.com resource.
  8. The name of the publishable document associated with this notification displays. Click Finish.
  9. The editor for the adapter notification appears. The tabs that appear on the editor are explained below:
    • Upsert Polling: This tab enables you to configure the notification. There are two fields on this tab.
      • DayCount: The notification uses the value in this field to calculate the initial start date when the notification runs. The value must be between 1 and 30 days.
      • Salesforce object: This field identifies the object type for which the create or update notification is required. When the notification is created, Upsert notification does the validation check to ensure that the sObject is replicable.
    • Adapter Settings: Select this tab to confirm adapter service properties such as the Adapter Name, Adapter Connection Name, and Adapter Notification Template, as necessary.
    • Output Fields: This tab displays the output that will be used by ART for creating the document to be published.
      • id[ ]: Array of IDs of each object that has been updated.
      • latestDateCovered: The timestamp of the process when the records are fetched from Salesforce within the range startdate and enddate.
    • Permissions: This tab is provided by ART and contains user-specified permissions for notifications. For information about using the Permissions tab to assign an access control list (ACL) to an element, see the IBM webMethods Service Development Help for your release.

    Make the appropriate selections on these tabs for your notification.

  10. From the File menu, select Save to save your settings.
  11. After you create a polling notification using Designer, you must open that notification in Integration Server Administrator to schedule and enable it. See Managing Polling Notifications for information about scheduling and enabling a polling notification.

Creating a Delete Polling Notification

About this task

A Delete Notification publishes an output document containing the IDs of the deleted sObjects for the given time interval.

To configure a Adapter for Salesforce Delete polling notification

Procedure

  1. Review the steps in Before Configuring Adapter Polling Notifications.
  2. Start Designer.
  3. Right-click the package in which the notification should be contained and select New > Adapter Notification.
  4. Select the parent namespace, type a name for the adapter notification, and click Next.
  5. Select IBM webMethods Adapter for Salesforce as the adapter type and click Next.
  6. Select Delete Notification as the Template Name and click Next.
  7. Select the appropriate Adapter Connection Name and click Next. This specifies the connection that the notification will use to connect to the Salesforce.com resource.
  8. The name of the publishable document associated with this notification displays. Click Finish.
  9. The editor for the adapter notification appears. The tabs that appear on the editor are:
    • Delete Polling: This tab enables you to configure the notification. There are two fields on this tab.
      • DayCount: The notification uses the value in this field to calculate the initial start date when the notification runs. The value must be between 1 and 30 days.
      • Salesforce object: This field identifies the object type for which the delete notification is required. When the notification is created, Delete notification does the validation check to ensure that the sObject is replicable.
    • Adapter Settings: Select this tab to confirm adapter service properties such as the Adapter Name, Adapter Connection Name, and Adapter Notification Template, as necessary.
    • Output Fields: This tab displays the output that will be used by ART for creating the document to be published.
      • deleteRecords[ ].id: The ID of the record that has been deleted.
      • deleteRecords[ ].deleteDate: The date when the object was deleted.
      • latestDateCovered: The timestamp of the process when the records are fetched from Salesforce within the range startdate and enddate.
    • Permissions: This tab is provided by ART and contains user-specified permissions for notifications. For information about using the Permissions tab to assign an access control list (ACL) to an element, see the IBM webMethods Service Development Help for your release.

    Make the appropriate selections on these tabs for your notification.

  10. From the File menu, select Save to save your settings.

What to do next

After you create a polling notification using Designer, you must open that notification in Integration Server Administrator and schedule and enable it. See Managing Polling Notifications for information about scheduling and enabling a polling notification.

Managing Polling Notifications

About this task

You must schedule a polling notification and then enable it before you can use the notification. Use Integration Server Administrator along with the following procedures to do so.

Note: You must have Integration Server administrator privileges to 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.

To manage polling notifications

Procedure

  1. In Integration Server Administrator, select Adapters > IBM webMethods Adapter for Salesforce.
  2. From the navigation area, select Polling Notifications.
  3. From the Polling Notifications table, provide values for the following fields for each adapter polling notification:
    Field Description/Action
    Notification Name The name of the notification.
    Package Name The name of the package for the notification.
    Enabled
    Note: You must schedule a polling notification before you can enable it. To schedule a polling notification, click the Schedule icon described in these procedures.

    After you schedule a polling notification, you can use this option to enable (Yes) or disable (No) a polling notification. Click on the current value in this field to change its value.

    Enabling and disabling a notification affects how its trigger is created and dropped. For details, see Polling Notification Types.

    If there is no polling notification scheduled for a given adapter notification, Not Scheduledappears in this field. Click the Create icon to create a polling notification as described in step 4.

    Edit Schedule Click the Create/Edit icon to create or modify polling notification parameters.
    Note: You must disable a polling notification before you can edit it.

    Continue to step 4.

    View Schedule Click on the View Schedule icon to review the parameters for the selected polling notification. Click Return to IBM webMethods Adapter for Salesforce to go back to the main polling notification page.
  4. To create or modify schedule parameters for the selected adapter polling notification, click the Create/Edit icon and provide values for the following fields:
    Field Description/Action
    Interval (seconds) Type the polling interval time in seconds.
    Overlap
    Note: Do not use this option; otherwise, when you enable this notification, it may lock up tables and cause Integration Server to fail.
    Immediate Enable this option to start polling immediately.
  5. Click Save Schedule.
  6. After you create a polling notification, you can enable it. Use the Enabled field described in step 3 to enable a polling notification.

Exporting Configured Adapter Polling Notifications

About this task

You can export polling notifications from one Integration Server to another Integration Server. You do not need to disable notifications in order to export them. In most cases, the current state of the notifications in the package that you export is retained. However, if you deploy to a different Integration Server and connect to a different database, then you should first disable the notification.

Note: A given notification can run on only one Integration Server at a time.

The start date of the polling notification is stored in the shared cache location. When the notifications are exported, if the notification is unable to fetch the start date from the cache, the start date for the first notification will be calculated based on the day count configured for the adapter polling notification. When Integration Server with the exported notifications starts, each configured notification starts to poll the changed data from Salesforce.com.

If you want to export configured polling notifications in a disabled state, you need to disable the notifications before you export the package containing them. To enable or disable a polling notification, see Managing Polling Notifications.

For more information about Insert Notifications, Update Notifications, or Delete Notifications, see Polling Notification Types.

For more information about exporting packages, see the IBM webMethods Integration Server Administrator’s Guide for your release.

Viewing Polling Notifications

About this task

You use Designer to view polling notifications.

To view a polling notification

Procedure

  1. Review the steps in Before Configuring Adapter Polling Notifications.
  2. In Designer, expand the package and folder that contain the polling notification you want to view.
  3. Double-click the notification you want to view.

Results

Designer displays the notification in the notification template's Adapter Notification Editor.

Editing Polling Notifications

About this task

You use Designer to edit polling notifications.

To edit a polling notification

Procedure

  1. Review the steps in Before Configuring Adapter Polling Notifications.
  2. In Designer, expand the package and folder that contain the polling notification you want to edit.
  3. Select the notification you want to edit.

    Designer displays the notification in the notification template's Adapter Notification Editor.

  4. Do one of the following:
    • If you have the VCS Integration feature enabled, right-click the polling notification and select Check Out.
    • If you do not have the VCS Integration feature enabled, right-click the polling notification 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 polling notification. The options available in the Team menu depend on the VCS client that you use.
  5. Modify the values for the polling notification's parameters as needed. For detailed descriptions of the notification's parameters, see Configuring Adapter Polling Notifications for the specific type of notification you want to edit.
    Note: When you edit a notification, all the parameters in the adapter notification are reset.
  6. After you complete your modifications, save the polling notification and do one of the following:
    • If you have the VCS Integration feature enabled, right-click the notification 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 notification 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 notification. The options available in the Team menu depend on the VCS client that you use.

Deleting Polling Notifications

About this task

You use Designer to delete adapter polling notifications.

Note: Before you delete the notification, be sure that you first disable it. To disable a polling notification, see Managing Polling Notifications.

To delete a polling notification

Procedure

  1. Review the steps in Before Configuring Adapter Polling Notifications.
  2. In Designer, expand the package and folder that contain the polling notification you want to delete.
  3. Right-click the notification and click Delete.

Validating Polling Notification Values

About this task

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

When you enable data validation for a single adapter polling notification, Designer compares the notification 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 polling notifications, it will do so for all webMethods WmART-based adapters installed on Integration Server.

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

Validating Values for a Single Adapter Service

About this task

To validate adapter polling notification values for a single adapter service

Procedure

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

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

  4. Click the Validate icon.

Validating Values for All Polling Notifications

About this task

To validate adapter notification values for all polling notifications

Procedure

  1. Review the steps in Before Configuring Adapter Polling Notifications.
  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.

Reloading Adapter Values

About this task

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

When you reload adapter values for a single polling notification, Designer compares the notification 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 polling notifications, 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 Polling Notification

About this task

To reload the adapter values for a single adapter polling notification

Procedure

  1. Review the steps in Before Configuring Adapter Polling Notifications.
  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 Notification Editor.

  4. Click the Reload icon.

Reloading Values for All Adapter Notifications

About this task

To automatically reload the values for all adapter notifications

Procedure

  1. Review the steps in Before Configuring Adapter Polling Notifications.
  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.