SAINT Bernard: Beneath the Fur (part 3)

by Sean Gubler on 9/26/11

Last time (part 2) we covered the SAINT.Export methods… this time we’ll talk SAINT.Import.

Once you’ve started exploring SAINT Bernard and have downloaded some SAINT records you’ll feel an itching to update those records. You can update in a couple of ways. First, you can do some direct editing in the data grid. Secondly, if you really want to do some serious updating you can click over to the “Bulk Update” tab an create some rules that will update thousands of records within a few seconds. Despite how you update, the time will come for you to send your updated records back to SiteCatalyst so that they are represented in your reports – enter the “Upload Records” button.

As long as SAINT Bernard recognizes at least one updated record in your data set you’ll be allowed to push this button. Once pushed, the app then goes in to “Sending” mode and will show you a status screen for a few seconds…

Then you’ll get a “Success” notification (hopefully) – and you can rest assured that your updates have been sent to SiteCatalyst and will be showing up in your reporting soon. Oh, you’ll also likely get an email from SiteCatalyst (not SAINT Bernard) telling you your import is looking fine.

Let’s explore what is going on beneath the fur. Just as with the Exporting process the Importing process is a sequence of 3 different API method calls.
The 3 methods are…

  1. SAINT.ImportCreateJob
  2. SAINT.ImportPopulateJob
  3. SAINT.ImportCommitJob

I will briefly describe how each of these method calls are used. If you download the SB source code you can see much of the ActionScript code for calling these methods in the com.saintbernard.utils.OMTRWebService.as file.

 

 

Method: Saint.ImportCreateJob    Token cost: 1  (documentation)

This method is required to define the import. None of the actual records get passed through on this one however. I will make a few comments on the parameters.

  • check_divisions – I always specify “1” here. I figure more error checking is better than less.
  • description – not particularly important, SAINT Bernard always uses “SAINT Bernard Import” as the value
  • email_address -  this is why SAINT Bernard asks for your email address when you first sign in, the API requires it here so that it can sent out email notifications (not one of my favorite API features BTW).
  • export_results – I always give “0” here; I’ve never understood the use case for doing otherwise.
  • header – this one is important; the first item in the array is always “Key” while the rest are the names of the other associated classification reports.
  • overwrite_conflicts -  I always use “1” here.
  • relation_id – this is the number id of the base variable being classified (example, s.products => 51); these can be looked up via another API method (SAINT.GetCompatibilityMetrics) but SAINT Bernard has them hard coded in the SaintBernardGlobal.reportMap object.
  • report_suite_array – in the case of SAINT Bernard this array always just contains a single report suite id, but you can import to multiple report suites in theory.

This method returns a jobID. This is important to save as it will be a required value for making the subsequent method calls.

 

Method: Saint.ImportPopulateJob    Token cost: 1  (documentation)

This is where you send all of the records. Not many parameters are required here since you gave most of those in the previous call.

  • job_id – the id returned from the Saint.ImportCreateJob
  • page – an integer for which page of data you are sending since you can call this method multiple times for a single import; always start with page “1” (not “0”).
  • rows – this is an array of string arrays; each array of strings is a SAINT record that needs to be the same length as the “header” array that was sent via the SAINT.ImportCreateJob call.

This method will return a message status that hopefully says “Success”. If so, you can either call this method again with more rows or move to the final step and “Commit” this import job.

 

Method: Saint.ImportCommitJob    Token cost: 1  (documentation)

This one is very simple. You simple pass it the job_id that you received on the SAINT.ImportCreateJob call. By doing so you are telling SiteCatalyst that you are done sending records (i.e. “Populating”) and to get to work on this import. SiteCatalyst can take several minutes, even hours sometimes, to work your SAINT import into the related reports.

 

That’s all I have to say about these import methods. Please post questions or comments on this topic. Also, let me know if there are other aspects of SAINT Bernard that you think would be interesting to explore in this series.

-Sean

Must be logged in to comment. or register now to comment!