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:
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 login 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:
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:
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.
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:
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:
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.
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:
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:
- Log into the SmarterTrack management interface as a system administrator.
- Click the Settings icon.
- Expand the Tools folder.
- Click External Providers in the navigation pane. The external provider settings
will load in the content pane.
- Click the Options tab and select the appropriate checkbox to enable the desired
external provider.
- Select the appropriate external provider tab: Login, Registration, Custom Fields, Ticket, Live
Chat, User Information or Events.
- In the Web Service URL field, type the URL to the Web service.
- In the Web Service Password field, type the password used to authenticate the Web
service.
- Click Save.
Any other settings are optional.
Copyright © SmarterTools Inc. All rights reserved.