Skip to content

Dispatch: From Salesforce.com

Dispatch Process

Sync & Save PLUS Dispatch follows these steps each time a Salesforce.com dispatch job runs:

  1. Sync & Save queries salesforce.com for records to dispatch using the query entered in the Source SOQL Statement box.

    • See here for more information on the SOQL language and here for a list of table and field names.
    • The SOQL Statement should only return records that have not already been dispatched.
    • Click the preview button to see the resulting records.

  2. Sync & Save transforms the data received using the format configured on the format tab.

    • Click the refresh button on the left side of the screen to populate the first 25 records produced by the SOQL Statement.
    • Set the date range on the right side of the screen to include at least one submission for this form and click Populate Fields to build the list of available fields to populate.
    • Map the data you wish to upload by dragging fields from the left side of the screen.
    • The @mobileNumber field is not required. However, if it is included the record status will be set to "Sent" and the record will be delivered to the correct mobile unit, otherwise the status will be set to "Pending".
    • Note that Date Time type fields should be populated with UTC/GMT values.

  3. Sync & Save uploads each dispatch record to the doForms web service which pre-populates the form fields and sends it to the correct mobile device (if specified).
  4. Sync & Save executes the Post Dispatch Statement for each dispatch record after receiving a response back from the doForms web service.

    • This should generally be used to mark the record as having been successfully dispatched so that it is no longer included in the results of the Query SQL.
    • All the data fields returned by the Query SQL statement are available as parameters for this  statement. Add an @ symbol before the field name to include the field as a parameter (e.g. @DispatchKey above).
    • The special parameter fields @DispatchKey and @DispatchStatus (see below) are also available.
    • Records that fail to be dispatched successfully will have the @DispatchStatus = -1 and @DispatchKey = "".
    • Click the preview button to view a sample sql statement prepared with the parameter values replaced.

  5. Sync & Save queries the doForms web service for the status of all current dispatch records and executes the Status Sync Statement for each record received.

    • This step is generally used to keep salesforce.com up to date as records advance through the dispatch workflow.
    • The only parameter fields available to this step are @DispatchStatus and @DispatchKey.
    • Leave this field blank if you don't wish to download updated status values from doForms.
    • Click the preview button to view a sample sql statement prepared with the parameter values replaced.

@DispatchKey

The @DispatchKey parameter is populated with the value of the key field for the dispatch record from the doForms web service. The value is an approximately 90 character long text string.

@DispatchStatus

The @DispatchStatus parameter is populated with the following numeric values from the doForms web service:

  1. Pending -- Received by the doForms web service, but no action has been taken.
  2. Scheduled -- Scheduled to be sent to a mobile device.
  3. Sent -- Sent to a mobile device.
  4. Received -- Received by a mobile device.
  5. Viewed -- Viewed by the user on the mobile device.
  6. Rejected -- Rejected by the user.
  7. Completed -- Completed by the user.

Sample Jobs

Dispatch Tasks connected to Cases

Use the following statements to dispatch salesforce.com Tasks that are connected to Cases:
  1. Source SOQL Statement
    • SELECT Id, Subject, Description, TYPEOF Owner WHEN User THEN Mobile_Device_Number__c END, TYPEOF What WHEN Case THEN CaseNumber, Subject, Status END FROM Task WHERE Dispatch_Key__c = '' AND What.Type = 'Case' AND Owner.Type = 'User'
    • This statement requires two custom fields:
      • Mobile_Device_Number added to the User table. This is used to store the mobile number that the record will be dispatched to. If a different user field such as MobilePhone or Phone already contains the correct value, then that field could be used instead.
      • Dispatch_Key added to Task table. This is used to save the doForms key value once the record has been dispatched. This field must be marked as an External ID.
    • Once there is a value in the Dispatch_Key__c field, the record will not be included in the query.
    • Note that you can add additional fields to the query.
  2. Post Dispatch Statement
    • UPDATE Task SET Dispatch_Key__c = @DispatchKey WHERE Id=@Id
    • This statement records the doForms Dispatch Key in the salesforce.com custom field Dispatch_Key__c. This removes the record from the Source SOQL Statement so that it is not dispatched again.
  3. Status Sync Statement
    • UPDATE Task SET Status = CASE @DispatchStatus WHEN 4 THEN 'Received' WHEN 5 THEN 'In Progress' WHEN 6 THEN 'Rejected' WHEN 7 THEN 'Completed' END WHERE Dispatch_Key__c = @DispatchKey
    • This statement updates the Task Status as it changes in doForms. Note that doForms status of 1 to 3 are not updated because they correspond to the default salesforce.com value of Not Started.
    • This statement requires two custom Task Status values: Received, Rejected.
    • If the Dispatch_Key__c field is not set as an External ID in salesforce.com, this statement will fail.
To use this job follow these steps:
  1. Download a pre-configured Dispatch job here (SF Task Dispatch). Save the xml file to your local machine and then import into Sync & Save.
  2. In the new job, configure your Login Settings for salesforce.com.
  3. Add a custom field to salesforce.com User: Mobile_Device_Number. Populate the field with values that match the Mobile Number for your doForms Mobile Units.
  4. Add a custom field to salesforce.com Task: Dispatch_Key
  5. Add two custom Status values to salesforce.com Task Status: Received, Rejected
  6. In salesforce.com, add a Task to an existing Case. In the SF Task Dispatch job, click the Preview button next to the Source SOQL Statement to make sure the task appears.
  7. Search for "Salesforce Task Dispatch" in the doForms public forms library and add it to your list of forms.
  8. Add a web service for the Salesforce Task Dispatch form and configure the Target Connection Settings on the SF Task Dispatch job to match.
  9. Run the SF Task Dispatch job and check the Dispatch tab of doForms to verify that the Task you created in step 6 created a Dispatch record.
  10. Complete the dispatched record in doForms. Be sure to add information to the Task Comments field.
  11. Download a pre-configured Submissions job here (SF Task Submissions). Save the xml file to your local machine and then import into Sync & Save.
  12. On the SF Task Submissions job, configure the General Connection Settings to match the doForms web service, and the Login Settings to connect to salesforce.com.
  13. Run the SF Task Submissions and check the salesforce.com task to see that the Comments field has been populated with the information you entered in doForms in step 10.

Dispatch Tasks connected to Accounts

Dispatching Tasks that are connected to Accounts would follow the same general approach as above. The primary difference would be the Source SOQL Statement:

SELECT Id, Subject, Description, TYPEOF Owner WHEN User THEN Mobile_Device_Number__c END, TYPEOF What WHEN Account THEN Name, AccountNumber, Phone END FROM Task WHERE Dispatch_Key__c = '' AND What.Type = 'Account' AND Owner.Type = 'User'

Dispatch New Leads

Dispatching new Leads would follow the same general approach as above. The Source SOQL could be:

SELECT Id, Name, Company, Phone, Description, TYPEOF Owner WHEN User THEN Mobile_Device_Number__c END FROM Lead WHERE Dispatch_Key__c = '' AND Owner.Type = 'User'

Feedback and Knowledge Base