qbo.Import: ImportFile/Apply

Overview

The qbo.Import module has been extended to support bulk-applying a method signature to every row returned by a statement. Examples include:

• • Add a workflow to all loans matching some search criteria

  • Add a task to all foreclosures matching some search criteria

  • Send an email to all contacts matching some search criteria

User Interface

The Loan.Search.xslt has been extended to support adding tasks and workflows. For example, to add a workflow to all loans in CA with a UPB greater than $500,000

• • Navigate to Loans, click the advanced search dropdown, and choose State: CA and UPB: 500,000-10,000,000 and search

  • From the result's Option menu, choose Add Workflow

  • From the Choose Workflow popup, choose apply to 'All Matching Records', choose your workflow, and click Save

The popup that invokes ImportFile/Apply is GenericTemplate.popup.xslt, and makes the following assumptions:

• • If you choose 'Selected Records', Apply will only be called for the selected rows, regardless of how many rows where returned

    • in this case, Apply is executed in real time, and the user must wait for the results to finish processing before navigating away from the page

    • the user will get an alert '{X} row affected', where X is the number of rows that the method signature was applied to

  • If you choose 'All Matching Records', Apply will be called for every row returned by the query, regardless of any rows that are checked (or not checked)

    • in this case, Apply is queued, so the user does not need to wait for the results

    • the user will get an alert that the request was queued, and a confirmation number (the Queue.MessageID)

A generic user interface for this method can be found at /Import/ImportFile.ashx/BatchApply.

API Details

The method signature for ImportFile/Apply is:

ImportFile/Apply?ClassName={ClassName}&Operation={Operation}&{Parameters to pass to ClassName/Operation}&Signature={Method Signature}

The Signature parameter may use substitution in it's query string of parameters. If substitution is specified, the parameters are substituted against the row of data returned by ClassName/Operation. For example:

ImportFile/Apply?ClassName=Loan&Operation=SmartSearch&SmartSearch=123123&Signature=Decision/Save?Object=Loan%26ObjectID={LoanID}%26Template=Hello World

does the following:

• • Executes Loan/SmartSearch?SmartSearch=123123

  • For each row returned, builds a method signature from Decision/Save?Object=Loan&ObjectID={LoanID}&Template=Hello World

    • this will replace {LoanID} with the LoanID column returned by Loan/SmartSearch

    • if the Hello World workflow already exists for a loan returned by the operation, normal repeatability rules apply

    • any column from Loan/SmartSearch may be used in this method signature

A more complex example is:

ImportFile/Apply?ClassName=Contact&Operation=Search&State=MA&Signature=Message/Send?ToAddress={Email}%26Subject=Hello {FirstName}%26BodyText=Welcome to QBO, {Suffix} {LastName}!

does the following:

• • Executes Contact/Search?State=MA

  • For each row returned, builds a method signature from Message/Send?ToAddress={Email}&Subject=Hello {FirstName}&BodyText=Welcome to QBO, {Suffix} {LastName}!

    • this will replace {Email}, {FirstName}, {Suffix} and {LastName} with the matching column returned by Contact/Search

Beware of the ampersand Gotcha!

The Signature parameter is itself a query string. If you're typing the full URL to leverage ImportFile.ashx/Apply, you must replace & with %26 manually. For example:

• • Signature=Decision/Save?Object=Loan&ObjectID={LoanID}: the value of Signature parsed on the server will be Decision/Save?Object=Loan

  • Signature=Decision/Save?Object=Loan%26ObjectID={LoanID}: the value of Signature parsed on the server will be Decision/Save?Object=Loan&ObjectID={LoanID}

If you are not typing the Signature query string directly, but use javascript to calculate the value being passed over the wire, javascript will take care of this substitution for you! For example:

<form>

  <input type="hidden" name="ClassName" value="Loan"/>

  <input type="hidden" name="Operation" value="Search"/>

  <input type="hidden" name="State" value="MA"/>

  <input type="hidden" name="Signature" value="Decision/Save?Object=Loan&ObjectID={LoanID}"/>

</form>

When parsing this data to pass to the server, the browser / javascript will recognize that the value being passed for the Signature parameter includes ampersands, and will automatically substitute & with %26 for you. See Templates/Application/GenericTemplate.Popup.xslt for an example.

Audit Trail: ImportFile/Batch

If you wish to include an audit trail with your use case, you can call ImportFile/Batch instead of ImportFile/Apply. ImportFile/Batch will:

• • Create an ImportFile record,

  • Create ImportFileQueue records for each row returned by the query, and

  • Queue ImportFile/Import

This allows you to have an audit trail (in the form of ImportFileQueue rows), and breaks the activity into smaller chunks (each row's method signature is queued as a separate job).