SmarterTrack Help
Community Knowledge Base

SmarterTrack External Provider Technical Documentation

Who Should Use This Document

This document is intended for internal developers looking to extend or customize the functionality of SmarterTrack's login system or ticket and live chat submission process. SmarterTrack users should note that the use of external providers is an advanced feature that requires programming knowledge. To download a sample application, download this sample external provider.

External Providers Overview

SmarterTrack was built with custom configuration and integration in mind. In addition to being able to automate SmarterTrack via Web services, developers and/or system administrators have the ability to extend the functionality of the application through the use of external providers (third-party Web services). By integrating external providers into SmarterTrack, companies can integrate their login system to LDAP, show/hide custom fields based on the department a user chooses, populate fields, run reports based on externally provided information, and more.

In order for your external provider to work in SmarterTrack, the Web service(s) need to follow a specific interface. The external providers discussed in this document utilize the following interfaces:

  • IExternalLoginProvider
  • IExternalCustomFieldProvider
  • IExternalTicketProvider
  • IExternalChatProvider
  • IExternalUserInfoProvider
  • IExternalEventProvider

Multiple external providers can be created in the same Web service as long as the required interfaces are inherited. The interfaces needed for these external providers can all be found in the SmarterTrack.Connector DLL. This file may be included in and distributed with your installation package.

Login Provider

The login provider allows you to customize SmarterTrack's login process. You can change the way users are authenticated in the system, create new users for unregistered logins, and even use cookies from other websites to allow for single sign-on. The login provider utilizes the IExternalLoginProvider interface. For a better understanding of how the login provider works with SmarterTrack, please refer to the flow chart below:

Login External Provider Diagram

Authenticate Method

The authenticate method validates the username and password for access to the system. This call is made when a user attempts to log in through the portal without any existing authentication cookie.

  • Parameters:
    • Inputs:An object containing a generic list of string values. Each object in the list is stored in a specific format (variable=value)
      • AuthPW:Used for validating if the calling software is valid
      • LoginUsername:The username you are authenticating with
      • LoginPassword:The password you are authenticating with
  • Return Type:ExternalLoginProviderResult
    • Message:A message indicating the result of the Web service call
    • Success:A Boolean value indicating the result of the Web service call
    • OutputVariables:A generic list of strings containing several output parameters needed by SmarterTrack. Some of the output is required in order to make SmarterTrack work correctly with this method. Each object in the list is stored in a specific format (variable=value)
      • Authentication:Determines whether or not the authentication check succeeded. Possible values are OK or FAIL
      • EmailAddress:The email address of the user
      • DisplayName:The display name of the user

cf_*:The value of current custom fields. An example of a custom field would be cf_ticket type=phoneticket or cf_display name=Test. These custom field values will be assigned to the user who is logging in. If the provided custom fields do not exist, the value is ignored.

Here is an example of how the authenticate method is used:

//  This function is used to authenticate user credentials when they log in to the interface.
//  The return values are used to create and link an account from SmarterTrack into your system.
//  
//
//  Inputs
//      authPW = Validates that calling software is valid
//      loginUsername
//      loginPassword
//  Outputs
//      Authentication = OK or FAIL
//      EmailAddress = Email address of user
//      DisplayName = Display Name of User
[WebMethod]
public ExternalLoginProviderResult Authenticate(ExternalLoginProviderInputs inputs)
{
    ParsedLoginInputData iData = new ParsedLoginInputData(inputs);
    ExternalLoginProviderResult result;

    // Verify that all necessary criteria to call this function are met
    if (iData.WebServiceAuthorizationCode != WebServicePassword)
        return new ExternalLoginProviderResult(false, "Permission Denied");
    if (string.IsNullOrEmpty(iData.LoginUsername) || string.IsNullOrEmpty(iData.LoginPassword))
        return new ExternalLoginProviderResult(false, "Required Input Missing");

    // This is a sample of how to do a basic username/password check (use your own database or list here)
    if (iData.LoginUsername.ToLowerInvariant() == "myusername" && iData.LoginPassword.ToLowerInvariant() == "mypassword")
    {
        result = new ExternalLoginProviderResult();
        result.Success = true;
        result.Message = "Login Successful";
        result.OutputVariables.Add("Authentication=OK");
        result.OutputVariables.Add("EmailAddress=putUsersEmailAddressHere@example.com"); // optional
        result.OutputVariables.Add("DisplayName=putUsersFullNameHere"); // optional
        return result;
    }

    // Below is a sample Active Directory Authentication implementation
    //string[] unDomainUsernameSplit = loginUsername.Split(new char[] { '/', '\\' }, 2);
    //if (unDomainUsernameSplit.Length == 2)
    //{
    //    if (LDAP.AuthenticateLogin(unDomainUsernameSplit[0], unDomainUsernameSplit[1],
    //        loginPassword, LDAP.NetworkType.ActiveDirectory) == LDAP.LDAPResult.Authenticated)
    //    {
    //        return new ExternalLoginProviderResult(true, "Login Successful", "Authentication=OK");
    //    }
    //}

    // Return a failure if there's no match
    return new ExternalLoginProviderResult(true, "Login Failure", "Authentication=FAIL");
}

GetSignInCookieInfo Method

The GetSignInCookieInfo method validates the username and password for single sign-on from another website. This method is also called when an authentication cookie cannot be found for the currently logged in user. Your web.config file must be set up to use cookies from another site if you choose to use single sign-on. For more information, refer to the SmarterTools Knowledge Base

  • Parameters
    • Inputs:An object containing a generic list of string values. Each object in the list is stored in a specific format (variable=value)
      • AuthPW:Used for validating if the calling software is valid
      • LoginUsername:The username you are authenticating with
  • Return Type:ExternalLoginProviderResult
    • Message:A message indicating the result of the Web service call
    • Success:A Boolean value indicating the result of the Web service call
    • OutputVariables: A generic list of strings containing several output parameters needed by SmarterTrack. Some of the output is required in order to make SmarterTrack work correctly with this method. Each object in the list is stored in a specific format (variable=value)
      • Authentication:Determines whether or not the authentication check succeeded. Possible values are OK or FAIL
      • EmailAddress:The email address of the user
      • DisplayName:The display name of the user
      • cf_*:The value of current custom fields. An example of a custom field would be cf_ticket type=phoneticket or cf_display name=Test. These custom field values will be assigned to the user who is logging in. If the provided custom fields do not exist, the value is ignored.

Here is an example of how the GetSignInCookieInfo method is used:

//  Same as Authenticate function, but does not verify password because cookie is authenticated.  Therefore, your
//  logic will be identical to the Authenticate function, but does not require you to check the password.
//
//  Inputs
//      authPW = Validates that calling software is valid
//      loginUsername
//  Outputs
//      Authentication = OK or FAIL
//      EmailAddress = Email address of user
//      DisplayName = Display Name of User
[WebMethod]
public ExternalLoginProviderResult GetSignInCookieInfo(ExternalLoginProviderInputs inputs)
{
    ParsedLoginInputData iData = new ParsedLoginInputData(inputs);

    // Verify that all necessary criteria to call this function are met
    if (iData.WebServiceAuthorizationCode != WebServicePassword)
        return new ExternalLoginProviderResult(false, "Permission Denied");
    if (string.IsNullOrEmpty(iData.LoginUsername))
        return new ExternalLoginProviderResult(false, "Required Input Missing");

    // This is a sample of how to do a basic username/password check (use your own database or list here)
    if (iData.LoginUsername.ToLowerInvariant() == "myusername")
    {
        ExternalLoginProviderResult result = new ExternalLoginProviderResult();
        result.Success = true;
        result.Message = "Login Successful";
        result.OutputVariables.Add("Authentication=OK");
        result.OutputVariables.Add("EmailAddress=putUsersEmailAddressHere@example.com"); // optional
        result.OutputVariables.Add("DisplayName=putUsersFullNameHere"); // optional
        return result;
    }

    // Below is a sample Active Directory Authentication implementation
    //string[] unDomainUsernameSplit = loginUsername.Split(new char[] { '/', '\\' }, 2);
    //if (unDomainUsernameSplit.Length == 2)
    //{
    //    if (LDAP.AuthenticateLogin(unDomainUsernameSplit[0], unDomainUsernameSplit[1],
    //        "", LDAP.NetworkType.ActiveDirectory) == LDAP.LDAPResult.Authenticated)
    //    {
    //        return new ExternalLoginProviderResult(true, "Login Successful", "Authentication=OK");
    //    }
    //}

    return new ExternalLoginProviderResult(true, "Login Failure", "Authentication=FAIL");
}

CustomFieldProvider

The custom field provider allows you to customize the custom fields that display when a user submits a ticket or live chat and the values associated to each custom field. The custom field provider utilizes the IExternalCustomFieldProvider interface. For a better understanding of how the custom field provider works with SmarterTrack, please refer to the flow chart below:

Custom Field Provider Diagram

GetCustomFieldOptions Method

The GetCustomFieldOptions method allows you to specify which custom fields a user may complete into two distinct steps. This is useful because it enables companies to allow their customers to complete certain fields during the first step of the live chat or ticket submission process and use the information customers provide to determine which custom fields are displayed during the second step.

People often confuse this method with the StartTicket or StartChat methods of other external providers, but these methods perform slightly different functions. See the Ticket Tracking Provider and Live Chat Tracking Provider sections of this document for more information.

  • Parameters:
    • Inputs:An object containing a generic list of string values. Each object in the list is stored in a specific format (variable=value)
      • AuthPW:Used for validating if the calling software is valid
      • LoginUsername:The customer's username
      • DepartmentName:The department name that the Ticket or Live Chat is being started through
      • Location:This is the step that the user is currently on in the Ticket or Live Chat submission process. Possible values for this are PRE or REGULAR
      • cf_*:Value of current custom fields. An example of a custom field would be cf_ticket type=phoneticket or cf_display name=Test. These values would obviously be empty if you were on step 1 of the submission process (location=PRE)
  • Return Type:ExternalCustomFieldProviderResult
    • Message:A message indicating the result of the Web service call
    • Success:A Boolean value indicating the result of the Web service call
    • CustomFieldDataItems:A generic list of properties that will tell SmarterTrack which action(s) to take with each individual custom field
      • CustomFieldName:This is the identifier for the custom field being changed. This value must be identical to the name of the custom field in SmarterTrack
      • DisplayWithInformationLookup:A Boolean value that indicates whether or not this field should be displayed on the first step of the ticket or live chat submission process. If this value is set to false, this custom field will be displayed with the other custom fields on the regular submission page (location=NORMAL)
      • ChangeListOptions:A Boolean value that indicates whether or not a drop-down type custom field should have its list options changed. This works alongside the ListOptions property below
      • ListOptions:A generic list of strings that is used to overwrite the contents of a drop-down menu type custom field. These values will only be used if ChangeListOptions is set to true
      • ChangeRequired:A Boolean value that indicates whether or not the custom field should have its required status changed. This works alongside the NewRequiredValue property
      • NewRequiredValue:A Boolean value that is used to determine if this custom field should be marked as required. This value is only used if ChangeRequired is set to true
      • ChangeVisible:A Boolean value that indicates whether or not the custom field should have its visibility changed. The works alongside the NewVisibleValue property
      • NewVisibleValue:A Boolean value that is used to determine if this custom field should be visible to the user. This value is only used if ChangeVisible is set to true
    • OutputVariables:A generic list of strings containing several output parameters needed by SmarterTrack. Some of the output is required in order to make SmarterTrack work correctly with this method. Each object in the list is stored in a specific format (variable=value)
      • CanStartTickets:Determines whether or a not a ticket can be started. Possible values for this are true and false. If this value if false,
      • CanStartChats: Determines whether or a not a live chat can be started. Possible values for this are true and false. If this value if false, SmarterTrack will display an error message to the user

Here is an example of how the GetCustomFieldOptions method is used:

//  Inputs
//      authPW = Validates that calling software is valid
//      loginUsername
//      departmentName
//      location = PRE or REGULAR (pre called after department selection made.  Regular called after search page and before compose page)
//      cf_* = value of current custom fields, such as "cf_ticket type=phone ticket"
//  Outputs
//      CanStartTickets = true or false
//      CanStartChats = true or false
//		Custom field overrides
[WebMethod]
public ExternalCustomFieldProviderResult GetCustomFieldOptions(ExternalCustomFieldProviderInputs inputs)
{
    ParsedCustomFieldInputData iData = new ParsedCustomFieldInputData(inputs);

    // Verify that all necessary criteria to call this function are met
    if (iData.WebServiceAuthorizationCode != WebServicePassword)
        return new ExternalCustomFieldProviderResult(false, "Permission Denied");

    bool canStartTickets = true;
    bool canStartChats = true;
    ExternalCustomFieldProviderResult result = new ExternalCustomFieldProviderResult(true, "Result okay");
    ExternalCustomFieldData cfdata;

    #region Example: Allow tickets/chats to only certain customers
    /*
     * You could check a database and see if the user has the ability to contact certain departments, for example.
     * In this example, only the user "myusername" is allowed to start tickets and chats for all departments.  
     * Everyone else can only start chats (not tickets), and can only contact the sales department
     */
    //if (iData.LoginUsername == "myusername")
    //{
    //    canStartTickets = true;
    //    canStartChats = true;
    //}
    //else
    //{
    //    result.Message = "You are not currently permitted to contact that department."; // shown in ticket pages
    //    canStartTickets = false;
    //    if (iData.DepartmentName.ToUpperInvariant() == "SALES DEPARTMENT")
    //        canStartChats = true;
    //    else
    //        canStartChats = false;
    //}
    #endregion

    #region Example: Set a custom list of domains for them to choose from
    /*
     * This example shows how to fill custom field drop-down lists for the user based on their login.  In this case,
     * we fill a dropdown list with their accounts listed in our database, so that they can choose which one 
     * the support is for.
     * 
     * It is important that the custom field already exist in SmarterTrack
     * */
    //if (iData.DisplayLocation == DisplayLocations.Page1_Pre && iData.DepartmentName.ToUpperInvariant() == "SUPPORT DEPARTMENT")
    //{
    //    // Here you would look up the options.  For now, we'll assume we brought back abc.com and def.com from our database

    //    cfdata = new ExternalCustomFieldData();
    //    cfdata.CustomFieldName = "Account";
    //    cfdata.ChangeRequired = true;
    //    cfdata.NewRequiredValue = true;
    //    cfdata.ChangeListOptions = true;
    //    cfdata.DisplayWithInformationLookup = false; // Set this to true if you need to show/hide other custom fields based on the value they select.
    //    cfdata.ListOptions.Add("abc.com");
    //    cfdata.ListOptions.Add("def.com");
    //    result.CustomFieldDataItems.Add(cfdata);
    //}
    #endregion

    #region Example: Custom Issue Types by Department
    /*
     * This example shows how to fill custom field drop-down lists for the user based on the department chosen.  In this case,
     * we fill a dropdown list with possible types of issues
     * 
     * It is important that the custom field already exist in SmarterTrack
     * */
    //cfdata = new ExternalCustomFieldData();
    //cfdata.CustomFieldName = "Type of Issue";
    //cfdata.ChangeListOptions = true;
    //cfdata.DisplayWithInformationLookup = false;
    //cfdata.ChangeRequired = true;
    //cfdata.NewRequiredValue = true;
    //cfdata.ChangeVisible = true;
    //cfdata.NewVisibleValue = true;
    //if (iData.DepartmentName.ToUpperInvariant().IndexOf("SALES") != -1)
    //{
    //    cfdata.ListOptions.Add("Change Plan");
    //    cfdata.ListOptions.Add("Help with order");
    //    cfdata.ListOptions.Add("Questions about plans");
    //    cfdata.ListOptions.Add("Questions about features");
    //    cfdata.ListOptions.Add("Help finding a product");
    //}
    //else if (iData.DepartmentName.ToUpperInvariant().IndexOf("SUPPORT") != -1)
    //{
    //    cfdata.ListOptions.Add("Web site issues");
    //    cfdata.ListOptions.Add("Database issues");
    //    cfdata.ListOptions.Add("Email issues");
    //    cfdata.ListOptions.Add("Dedicated server issues");
    //    cfdata.ListOptions.Add("Statistics issues");
    //    cfdata.ListOptions.Add("Network connectivity");
    //}
    //else
    //{
    //    // Removing issue types field, since there's no options
    //    cfdata.ChangeRequired = true;
    //    cfdata.NewRequiredValue = false;
    //    cfdata.ChangeVisible = true;
    //    cfdata.NewVisibleValue = false;
    //}
    //result.CustomFieldDataItems.Add(cfdata);
    #endregion

    result.Success = true;
    result.OutputVariables.Add("CanStartTickets=" + canStartTickets);
    result.OutputVariables.Add("CanStartChats=" + canStartChats);
    return result;
}

Ticket Tracking Provider

The ticket tracking provider is used to determine if a ticket can be started based on the custom field values that have been entered and based on the needs for your company. The ticket tracking provider utilizes the IExternalTicketProvider interface. For a better understanding of how the ticket tracking provider works with SmarterTrack, please refer to the flow chart below:

Ticket Tracking Provider Diagram

In the example below, the custom field provider is used to determine the options available on each step in the ticket submission process and the ticket tracking provider uses the options selected to determine whether the ticket can be started.

Custom field provider used to track ticket submission process

StartTicket Method

The StartTicket method is used to tell SmarterTrack if the ticket can be created. This method is called just before a ticket is submitted (regardless of how the ticket was created). This method may also change the custom fields for the ticket and can be used to override the customer's department selection.

  • Parameters:
    • Inputs:An object containing a generic list of string values. Each object in the list is stored in a specific format (variable=value)
      • AuthPW:Used for validating if the calling software is valid
      • LoginUsername:The customer's username. This is used for tickets submitted through the Web interface
      • EmailFrom:The customer's email address. This is used for tickets submitted through email.
      • DepartmentName:The department's name that the customer is creating a Ticket for.
      • TicketNumber:The ticket number for the ticket about to be created.
      • cf_*:Value of this Ticket's current custom fields. An example of a custom field would be cf_ticket type=phoneticket or cf_display name=Test. At this point in the ticket submission process these values should be completed.
  • Return Type:
    • Message:A message indicating the result of the Web service call
    • Success:A Boolean value indicating the result of the Web service call
    • OutputVariables:A generic list of strings containing several output parameters needed by SmarterTrack. Some of the output is required in order to make SmarterTrack work correctly with this method. Each object in the list is stored in a specific format (variable=value)
      • TicketCreation:Determines whether or a not this ticket can be created. Possible values for this are true and false. If this value if false, SmarterTrack will display an error message to the user and will NOT create the Ticket
      • departmentName:If this value is set, the ticket will be created for this department instead of what the user submitted originally
      • groupName:If this value is set, the ticket will be created for this group and the department this group is associated with instead of what the user submitted originally.
      • departmentID:If this value is set, the ticket will be created for this department instead of what the user submitted originally
      • groupID: If this value is set, the ticket will be created for this group and the department this group is associated with instead of what the user submitted originally.
      • cf_*: Value of this ticket's current custom fields. If these values are set, they will replace any existing values for the custom field

Here is an example of how the StartTicket method is used:

//  This function is called right after the person clicks on the Submit Ticket button.  This gives your provider one last
//  chance to abort the process or store any custom fields.
//
//  Inputs
//      authPW = Validates that calling software is valid
//      loginUsername (for tickets submitted through Web interface)
//      emailFrom (for tickets submitted through email)
//      departmentName
//      subject
//      ticketNumber = the ticket number about to be created
//      cf_* = values of custom fields
//  Outputs
//      TicketCreation = TRUE or FALSE
//      cf_* = output values of custom fields
[WebMethod]
public ExternalTicketProviderResult StartTicket(ExternalTicketProviderInputs inputs)
{
    ParsedTicketInputData iData = new ParsedTicketInputData(inputs);
    ExternalTicketProviderResult result = new ExternalTicketProviderResult();

    // Verify that all necessary criteria to call this function are met
    if (iData.WebServiceAuthorizationCode != WebServicePassword)
        return new ExternalTicketProviderResult(false, "Permission Denied");

    // This would be the place to check custom fields and the person's account to see if they can 
    // submit tickets.  If they can, and you use a pay-per-ticket model, deduct the ticket from
    // the person's account here.

    // For example, to return an error that the person is out of support tickets, use the following code
    // return new ExternalTicketProviderResult(true, "There are no more tickets in your account.", "TicketCreation=FALSE");

    #region Example: Set the customer's custom fields
    /*
     * In this example, we set some hidden custom fields based on the logged in user's information.  These
     * custom fields MUST exist already in SmarterTrack (without the cf_ prefix)
     * */
    //if (iData.LoginUsername.ToLowerInvariant() == "myusername")
    //{
    //    result.OutputVariables.Add("cf_Billing ID=4126");
    //    result.OutputVariables.Add("cf_Plan Type=ASP.NET Semi-dedicated");
    //}
    #endregion

    #region Example: Reroute tickets
    /*
     * In this example, we reroute any tickets with the subject containing Urgent to the Critical Support department.  
     * We also reroute any tickets with a custom field value of "Server Down" to the Server Operations Department
     * (assuming we had that custom field set up in our system).
     * You could also modify this to reroute customers with certain attributes in your database (priority customers).
     * */
    //if (iData.Subject.ToUpperInvariant().Contains("URGENT"))
    //{
    //    result.OutputVariables.Add("departmentName=Critical Support");
    //}
    //string value;
    //if (iData.CustomFields.TryGetValue("Issue Type", out value) && value.ToUpperInvariant() == "SERVER DOWN")
    //{
    //    result.OutputVariables.Add("departmentName=Server Operations Department");
    //}
    #endregion

result.Success = true;
    result.Message = "Ticket Creation Successful";
    result.OutputVariables.Add("TicketCreation=TRUE");
    return result;
}

Live Chat Tracking Provider

The live chat tracking provider is used to determine if a live chat can be started based on the custom field values that have been entered and based on the needs for your company. The live chat tracking provider utilizes the IExternalChatProvider interface. For a better understanding of how the live chat tracking provider works with SmarterTrack, please refer to the flow chart below:

Live Chat Provider Diagram

StartChat Method

The StartChat method is used to tell SmarterTrack if the live chat can be started. This method is called just before a live chat is submitted to the queue. This method may also change the custom fields for the live chat and can be used to override the customer's department selection.

  • Parameters:
    • Inputs:An object containing a generic list of string values. Each object in the list is stored in a specific format (variable=value)
      • AuthPW:Used for validating if the calling software is valid
      • LoginUsername:The customer's username. This is used for live chats submitted through the Web interface
      • DepartmentName: The department's name that the customer is starting a live chat for
      • cf_*:The value of the live chat's custom fields. An example of a custom field would be cf_chat type=support or cf_display name=Test. At this point in the live chat submission process these values should be completed.
  • Return Type: ExternalCustomFieldProviderResult
    • Message:A message indicating the result of the Web service call
    • Success:A Boolean value indicating the result of the Web service call
    • OutputVariables:A generic list of strings containing several output parameters needed by SmarterTrack. Some of the output is required in order to make SmarterTrack work correctly with this method. Each object in the list is stored in a specific format (variable=value)
      • ChatCreation: Determines whether or a not this live chat can be created. Possible values for this are true and false. If this value if false, SmarterTrack will display an error message to the user and will NOT start the live chat
      • departmentName:If this value is set, the live chat will be created for this department instead of what the user submitted originally
      • cf_*:Value of this live chat's current custom fields. If these values are set, they will replace any existing values for the custom field

Here is an example of how the StartChat method is used:

//  This function models the StartTicket function almost exactly.  It is provided so you can make the processes run differently
//  for each.
//
//  Inputs
//      authPW = Validates that calling software is valid
//      loginUsername (for chats submitted through Web interface)
//      emailFrom (for chats submitted through email)
//      departmentName
//      cf_* = values of custom fields
//  Outputs
//      ChatCreation = TRUE or FALSE
//      cf_* = output values of custom fields
[WebMethod]
public ExternalChatProviderResult StartChat(ExternalChatProviderInputs inputs)
{
    ParsedChatInputData iData = new ParsedChatInputData(inputs);
    ExternalChatProviderResult result = new ExternalChatProviderResult();

    // Verify that all necessary criteria to call this function are met
    if (iData.WebServiceAuthorizationCode != WebServicePassword)
        return new ExternalChatProviderResult(false, "Permission Denied");

    // This would be the place to check custom fields and the person's account to see if they can 
    // submit chats.  If they can, and you use a pay-per-chat model, deduct the chat from
    // the person's account here.

    // For example, to return an error that the person is out of support chats, use the following code
    // return new ExternalChatProviderResult(true, "There are no more chats in your account.", "ChatCreation=FALSE");

    // You can also set output custom fields, which will be filled in with the chat.

    #region Example: Set the customer's custom fields
    /*
     * In this example, we set some hidden custom fields based on the logged in user's information.  These
     * custom fields MUST exist already in SmarterTrack (without the cf_ prefix)
     * */
    //if (iData.LoginUsername.ToLowerInvariant() == "myusername")
    //{
    //    result.OutputVariables.Add("cf_Billing ID=4126");
    //    result.OutputVariables.Add("cf_Plan Type=ASP.NET Semi-dedicated");
    //}
    #endregion

    result.Success = true;
    result.Message = "Chat Creation Successful";
    result.OutputVariables.Add("ChatCreation=TRUE");
    return result;
}

User Information Provider

The user information provider is used to retrieve custom user data and display it in the communication tab of a ticket. This provider is useful for businesses that use a different database to track customer account information or for businesses that want to display all available information on a particular user. The user information provider utilizes the IExternalUserInfoProvider interface. For a better understanding of how the user information provider works with SmarterTrack, please refer to the flow chart below:

User Information Provider Diagram

In the example below, the user information provider is querying an external database to retrieve custom user information such as the user's email address, company, number of licenses, and Alexa ranking.

User information provider displaying a users picture and profile information from the database.

GetUserDetails Method

The GetUserDetails method is used to tell SmarterTrack which additional information should be displayed when a ticket is viewed. This method is called on every ticket view in the management interface. This method works by returning HTML that is displayed at the top of the communication tab in each ticket

  • Parameters:
    • Inputs:An object containing a generic list of string values. Each object in the list is stored in a specific format (variable=value)
      • AuthPW:Used for validating if the calling software is valid
      • Username:The customer's username.
      • Email:The customer's email address.
      • BrandName:The brand's name that this ticket is currently assigned to
      • DepartmentName:The department's name that this ticket is currently assigned to
      • Group:The group's name that this ticket is currently assigned to
      • TicketNumber:The identifier for the ticket being viewed
      • InteractionType:For the time being this value is always set to “ticket”. This provider may be used for other purposes in later versions.
    • Message:A message indicating the result of the Web service call
    • Success:A Boolean value indicating the result of the Web service call
    • OutputVariables:A generic list of strings containing several output parameters needed by SmarterTrack. Some of the output is required in order to make SmarterTrack work correctly with this method. Each object in the list is stored in a specific format (variable=value)
      • UserInfoHTML:The HTML that is injected at the top of the communication tab for each ticket. If you do not set this value or if you leave it blank the user information area will not display.
      • OutputVariables:An array of other information pertaining to the user. This functionality isn't currently supported.

Here is an example of how the GetUserDetails method is used:

//  This function is called when a Ticket is viewed in the management interface. 
//  If values are returned for OtherUserInfo a user
//  information area will appear just above the conversation. In the future, this function may 
//  also be used to retrieve information
//  for Live Chats and in the users settings page.
//
//  Inputs
//      authPW = Validates that calling software is valid
//      username = The username for the account you are retrieving information for
//      email = The email address for the user you are retrieving information for
//      brandName = The brand that the Ticket was created in
//      departmentName = The department that the Ticket was created in
//      groupName = The group that the Ticket was created in
//      ticketNumber = the identifier for the Ticket you are retrieving information for
//      interactionType = Where this call is being made from 
//  Outputs
//      UserInfoHtml = The HTML that will be displayed just above the conversation of a ticket
//      OutputVariables = An array of other information pertaining to the user. 
//          This functionality isn't currently supported.
[WebMethod]
public ExternalUserInfoProviderResult GetUserDetails(ExternalUserInfoProviderInputs inputs)
{
ParsedUserInfoInputData iData = new ParsedUserInfoInputData(inputs);
ExternalUserInfoProviderResult result = new ExternalUserInfoProviderResult();

// Verify that all necessary criteria to call this function are met
if (iData.WebServiceAuthorizationCode != WebServicePassword)
return new ExternalUserInfoProviderResult(false, "Permission Denied");

// This would be the place to check account information and add custom user information and HTML

#region Example: Add a user's account number
/* 
*   if (iData.Username.ToLowerInvariant() == "myusername")
*   {
*      result.UserInfoHtml = "Account Number: 000-000000-0000

Partner: Yes";
*   }
*/
#endregion

result.Success = true;
result.Message = "User Account Information Retrieved Successfully";
// result.OutputVariables is unused at this time
return result;
}

Events Provider

The events provider is used to perform custom actions when an event action occurs. SmarterTrack's event system can be configured to fire this provider with details of the event and its conditions. This provider is useful for businesses that wish to notify another system or database of any action taken in SmarterTrack. The event provider utilizes the IExternalEventProvider interface. For a better understanding of how the event provider works with SmarterTrack, please refer to the flow chart below:

Events Provider Diagram

NotifyEventFired Method

The NotifyEventFired method is used to notify another system or database when an event is fired in SmarterTrack. This method is called on any event where the “Notify External Provider” event action is configured. This event action is only available for system level events.

  • Parameters:
    • Inputs:An object containing a generic list of string values. Each object in the list is stored in a specific format (variable=value)
      • AuthPW:Used for validating if the calling software is valid
      • EventType:The numeric ID for this event. See section labeled “SmarterTrack Event Type Identifications” for a complete list of numeric IDs.
      • Args_[Key]: The argument / condition value that was defined in the event
    • Message: A message indicating the result of the Web service call
    • Success: A Boolean value indicating the result of the Web service call

Here is an example of how the NotifyEventFired method is used:

//  This is an example NotifyEventFired function that would be executed when SmarterTrack fires //  the Notify External Provider event action.
//
//  Inputs
//      authPW = Validates that calling software is valid
//      eventType = Numeric identification for the event that was fired.
//      args_[key] = The value of an argument passed in by the event system where [key] is the //  
//                   name of the argument or condition
[WebMethod]
public ExternalEventProviderResult NotifyEventFired(ExternalEventProviderInputs inputs)
{
ParsedEventInputData iData = new ParsedEventInputData(inputs);
ExternalEventProviderResult result = new ExternalEventProviderResult();

// Perform custom notification action here...
//if (iData.EventType == 501000)
//iData.Arguments["title"] ...

// Verify that all necessary criteria to call this function are met
if (iData.WebServiceAuthorizationCode != WebServicePassword)
return new ExternalEventProviderResult(false, "Permission Denied");

result.Success = true;
result.Message = "Event Notification Successful";
return result;
}

SmarterTrack Event Type Identifications

Every event type in SmarterTrack has a numerical identification associated to it that is used when configure the events external provider. When the NotifyEventFired is called, SmarterTrack uses the event identification to specify the action that triggers the event notification.

Event Type ID
KB Article Created 501000
KB Article Modified 501001
KB Article Flagged For Review 501002
KB Article Stale 501003
KB Article Marked As Reviewed 501004
KB Article Deleted 501005
Ticket Created 502000
Ticket Transferred 502001
Ticket Status Changed 502002
Ticket Priority Changed 502003
Ticket Deleted 502004
Ticket Comment Added 502005
Ticket Message Sent 502006
Ticket Idle 502008
Ticket Count Department 502009
Ticket Count Group 502010
Ticket Count Agent 502011
Ticket Follow Up Scheduled 502012
Ticket Followed Up 502013
Ticket Time Log Created 502014
WhosOn Chat Accepted 503001
WhosOn Chat Invited 503002
WhosOn Chat Invite Rejected 503003
WhosOn Chat Invite Ignored 503004
WhosOn Visitor Removed 503005
WhosOn Visitor Purged 503006
WhosOn Online Activity 503007
Chat Channel Joined 505000
Chat Channel Left 505001
Chat Channel Invited 505002
Survey Answered 506000
Survey Offered 506001
Task Created 507000
Task Modified 507001
Task Deleted 507002
Task Started 507003
Task Due 507004
Task Comment Added 507005
Call Log Created 508000
Call Log Modified 508001
Call Log Deleted 508002
Call Log Attached To Ticket 508003
Call Log Detached From Ticket 508004
Call Log Time Log Created 508005
POP Connection Failed 509000
POP Login Failed 509001
POP Download Failed 509002
POP Import Failed 509003
SMTP Connection Failed 510000
SMTP Login Failed 510001
SMTP Delivery Failed 510002
Live Chat Started 511000
Live Chat Ended 511001
Live Chat Transferred 511002
Live Chat Deleted 511003
Live Chat Attached To Ticket 511004
Live Chat Detached From Ticket 511005
Live Chat Incoming Message 511006
Live Chat Outgoing Message 511007
Live Chat Idle 511008
Live Chat Department Count 511009
Live Chat Group Count 511010
Live Chat Agent Count 511011
Live Chat Comment Added 511012
Live Chat Time Log Created 511013
Agent Ticket Status Changed 512000
Agent Live Chat Status Changed 512001

Connecting SmarterTrack to an External Provider

Although there are several different external providers available for SmarterTrack, they are all configured using the same basic process. Follow these steps to connect SmarterTrack to your third-party Web service:

  1. Log into the SmarterTrack management interface as a system administrator.
  2. Click the Settings icon.
  3. Expand the Tools folder.
  4. Click External Providers in the navigation pane. The external provider settings will load in the content pane.
  5. Click the Options tab and select the appropriate checkbox to enable the desired external provider.
  6. Select the appropriate external provider tab: Login, Registration, Custom Fields, Ticket, Live Chat, User Information or Events.
  7. In the Web Service URL field, type the URL to the Web service.
  8. In the Web Service Password field, type the password used to authenticate the Web service.
  9. Click Save.

Any other settings are optional.

Copyright © SmarterTools Inc. All rights reserved.