StartSearch method

The StartSearch method requires five parameters: ActiveQuery, ArchiveQuery, StartDate, EndDate and SortField.

• ActiveQuery: A query adhering to the Tealeaf active search syntax.
• ArchiveQuery: A query adhering to dtSearch syntax
• StartDate: An ISO formatted string representing the earliest date/time for which to return sessions (date should be relate to the user's time zone, as the date is converted to GMT on the server).
• EndDate: An ISO formatted string representing the latest date/time for which to return sessions (date should be relate to the user's time zone, as the date is converted to GMT on the server).
• SortField: An integer representing the various post-search sorts that can be applied to a search. The list of sort fields is accessible via the GetSearchSortFields method which provides the ID and text description for each possible sort field.
  • Hit Count - 0
  • Session Index - 1
  • Last Use - 2

To provide the best functionality/availability, StartSearch only initiates the search.

StartDbSearch method

Tealeaf cxReveal enables the capture and insertion of session attribute information into a dedicated database, which can be immediately searched by cxReveal users for sessions.

The StartDbSearch method requires the following parameters.

• All parameters must be URL-encoded.
• All arguments are required.
• If you have fewer than five specified search field arguments, the operator for the non-specified parameters should be set to none.
• SessionFilter: The type of session. Accepted values: ACTIVE, CLOSED (completed) or ALL (universal).
• StartDate: If datespan is set to -1, this is the ISO-format date for the beginning date of the range (e.g. 2007-01-02 is Jan 02, 2007)
• EndDate: If datespan is set to -1, this is the ISO-format date for the end date of the range (e.g. 2007-01-02 is Jan 02, 2007)
• AndParameters: For the specified search terms, this setting denotes whether the query should execute them using an AND or OR operator.
• Attr1Index: Index number to the session attribute that is search field 1 in cxReveal search (0 to 63).
• The session attributes and their index numbers are available for review in the Session Attributes tab of the Event Manager.
• Param1Op: The operator to apply to the field to compare it to the ParamValue.
• Param1Value: The value to which the session attribute is compared
• Attr2Index: Index number to the session attribute that is search field 2 in cxReveal search (0 to 63).
• The session attributes and their index numbers are available for review in the Session Attributes tab of the Event Manager.
• Param2Op: The operator to apply to the field to compare it to the ParamValue.
• Param2Value: The value to which the session attribute is compared
• Attr3Index: Index number to the session attribute that is search field 3 in cxReveal search (0 to 63).
• The session attributes and their index numbers are available for review in the Session Attributes tab of the Event Manager.
• Param3Op: The operator to apply to the field to compare it to the ParamValue.
• Param3Value: The value to which the session attribute is compared
• Attr4Index: Index number to the session attribute that is search field 4 in cxReveal search (0 to 63).
• The session attributes and their index numbers are available for review in the Session Attributes tab of the Event Manager.
• Param4Op: The operator to apply to the field to compare it to the ParamValue.
• Param4Value: The value to which the session attribute is compared
• Attr5Index: Index number to the session attribute that is search field 5 in cxReveal search (0 to 63).
• The session attributes and their index numbers are available for review in the Session Attributes tab of the Event Manager.
• Param5Op: The operator to apply to the field to compare it to the ParamValue.
• Param5Value: The value to which the session attribute is compared

StartDBSearch utilizes the same status and retrieval methods as the StartSearch method.

GetSearchStatus method

GetSearchStatus should be used to check if the search has completed. GetSearchResults should only be called once both Done and DownloadComplete return true.

GetSearchStatus will return the following information:

• Name: the search name
• DocumentsFound: the number of sessions found
• HitsFound: the number of total hits found
• IndexName: the name of the current index being searched
• PercentDone: this is solely for a visual
• Done: this is set when the search and session collation has completed
• CancelState: if the search reports as being cancelled, this value will be a non-zero value
• IndexesSearched: number of search indexes searched thus far
• IndexesTotal: total number of search indexes to search
• SearchTime: elapsed search time in seconds
• Error: if an error occurs, this field will be populated
• DownloadComplete: search results have been retrieved, GetSearchResults can now be called
• NextUpdate: millisecond value for the minimum time to wait before the next GetSearchStatus call.

GetSearchResults method

GetSearchResults should only be called once GetSearchStatus for a search has returned that both Done and DownloadComplete are true.

Aside from the standard session meta-data, TLMiniSession has extra fields that are worth discussing:

• IsActiveSession: If the session still lives in the STC (Short Term Canister), this field will be set. If a CSR is looking for the session for a customer who just experienced a problem, it is likely that the session is still be in the STC)
• ReplayLinkBBR: A URL pointing to the Portal that will cause BBR (Browser Based Replay) to load this session
• ReplayLinkRTV: A URL that will (if it is installed) open the current session in RTV (CX RealiTea Viewer)
• SessionListIndex: This value is used when calling session specific methods and should not be displayed.

GetSessionPagesList method

GetSessionPagesList will return a list of TLMiniPage entries for every page (not every hit) in the session. Each TLMiniPage entry contains all the hit metadata as well as the Iamie, Env, AppData, UrlField, Cookies, TimeStamp, AppEvents, Ref, RspHeaders and RawRequest sections of the hit.

For a given page in the pages list returned by GetSessionPagesList, GetPageResponse can be called to return the HTTP Response for that hit/page.

GetSessionAnnotations method

The GetSessionAnnotations method returns a list of the session annotations in the columns of Username, Timestamp and Text.

Similar to GetSessionReplayLink, GetSessionAnnotations requires the following parameters:

• SessionType - The type of session. Accepted values: ACTIVE, CLOSED or ALL.
• Field - The field used to identify the session. Possible values: TLTSID, TLTUID, SessionAttribute00 to SessionAttribute04.
• Value - The value of Field for which to search.
• MD5 - If set to true, the value is hashed before generating the search query.
• SessionDate - The date of the session. A blank string is valid.
• SessionPreference - The session to return on the chosen date. Accepted values: EARLIESTDT, LATEST or ANY.

Example Code

An example of configuration code in the Portal Application.

using SampleApplication.example;

namespace SampleApplication
{
  class Program
  {
    static void Main(string[] args)
    {
      RevealAPIDemo();
    }

    public bool RevealAPIDemo()
    {
      String DateFormat = "yyyy-MM-dd HH:mm:ss";

      cxRevealAPI reveal = new cxRevealAPI();

      // All API clients must support cookies
      reveal.CookieContainer = new CookieContainer();

      // A fix for the .NET webservice class
      // ServicePointManager.MaxServicePointIdleTime = 0;

      String UserName = "admin";
      String Password = "init";

      String Authenticated = reveal.Authenticate(UserName, Password);

      // Verify that the Authenticate call was successful
      if (Authenticated != null) // Not Authenticated
      {
        Console.WriteLine("Authentication failed: " + Authenticated);
        return false;
      }

      // If this call fails, Cookies are most likely not being 
      // transmitted/stored correctly
      bool VerifyAuth = reveal.VerifyAuthentication();
      if (!VerifyAuth)
      {
        Console.WriteLine("Secondary authentication check failed, please check 
          your cookie settings.");
        return false;
      }

      String ActiveQuery = "(numhits > 0)";
      String ArchiveQuery = "(tltstssesnidx)";

      String StartDate = DateTime.Now.AddHours(-12).ToString(DateFormat);
      String EndDate = DateTime.Now.ToString(DateFormat);

      TLSortField[] SortFields = reveal.GetSearchSortFields();
      //SortFields[0] = Hit Count
      //SortFields[1] = Session Index
      //SortFields[2] = Last Use
      TLSortField HitCount = SortFields == null ? null : SortFields[0];

      int SearchID = reveal.StartSearch(ActiveQuery, ArchiveQuery, StartDate, 
                     EndDate, HitCount == null ? 0 : HitCount.SortID);

      if (SearchID == -1) // -1 on error
      {
        Console.WriteLine("The search failed to start, please check your 
          search parameters.");
        return false;
      }

      TLSearchStatus SearchStatus = null;
      int AttemptsLeft = 5;

      while (SearchStatus == null || !SearchStatus.Done ||
             !SearchStatus.DownloadComplete)
      {
        SearchStatus = reveal.GetSearchStatus(SearchID);
        if (SearchStatus != null && SearchStatus.CancelState != 0) 
        // If the search has been cancelled, stop checking the status
        {
          Console.WriteLine("The search has been cancelled.");
          return false;
        }

        if (SearchStatus != null)
        {
          Console.WriteLine("Percent complete: " + SearchStatus.PercentDone
              + " Done: " + SearchStatus.Done
              + " DownloadComplete: " + SearchStatus.DownloadComplete);

          if (!SearchStatus.Done || !SearchStatus.DownloadComplete)
              Thread.Sleep(SearchStatus.NextUpdate); 
              // Sleep for the time designated by the search status
          else
              break;
        }
        else
        {
          AttemptsLeft--;

          if (AttemptsLeft < 1)
          {
              Console.WriteLine("The search status could not be found.");
              return false;
          }

          Thread.Sleep(500); 
          // Wait 500 ms in case the search start was possibly delayed
        }
      }

      TLMiniSession[] Sessions = reveal.GetSearchResults(SearchID, 100);
      if (Sessions == null)
      {
        Console.WriteLine("Unable to download the search results.");
        return false;
      }

      Console.WriteLine(Sessions.Length + " sessions have been downloaded.");

      TLMiniSession Session = null;
      if (Sessions.Length > 0) // Use the first session found
        Session = Sessions[0];

      if (Session == null)
      {
        Console.WriteLine("No sessions were found.");
        return false;
      }

      Console.WriteLine("The first session from the search results has " + 
                         Session.NumHits + " hits.");
      Console.WriteLine("RTV link for the first session: " + 
                         Session.ReplayLinkRTV);
      Console.WriteLine("BBR link for the first session: " +
                         Session.ReplayLinkBBR);

      // Print out which events are associated with this session
      if (Session.Events == null || Session.Events.Length == 0)
        Console.WriteLine("No events are associated for this session.");
      else
      {
        Console.WriteLine("This session had the following events:");

        foreach (TLMiniEventDefn Event in Session.Events)
          Console.WriteLine("\tEventDesc: " + Event.Description + " - Image 
                              URL: " + Event.ImageURL);
      }

      TLMiniPage[] Pages = reveal.GetSessionPagesList(SearchID, 
                           Session.SessionListIndex);
      if (Pages == null)
      {
        Console.WriteLine("Unable to download the pages list for 
                           this session.");
        return false;
      }

      Console.WriteLine("The first session from the search results has " + 
                         Pages.Length + " pages.");

      TLMiniPage Page = null;
      if (Pages.Length > 0)
        Page = Pages[0];

      if (Page == null)
      {
        Console.WriteLine("There was a problem accessing the first page of 
                           this session.");
        return false;
      }

      Console.WriteLine("Page URL (w/o Params): " + Page.Url);
      Console.WriteLine("Page URL (w/  Params): " + Page.UrlFull);

      TLPageResponse Response = reveal.GetPageResponse(SearchID, 
                                Session.SessionListIndex, Page.HitNumber);
      if (Response == null)
      {
        Console.WriteLine("Unable to download the response for this 
                           page/hit.");
        return false;
      }

      Console.WriteLine("The response for the first page of this session was "
        + (Response.Response == null ? 0 : Response.Response.Length) + " 
                                characters long.");

      return true;
    }
  }
}