Optionally provide private feedback to help us improve this article...

Thank you for your feedback!


Searching tickets via the InstantKB .NET API

Using the InstantKB .NET API you can easily query the InstantKB database to return support tickets created by users. We've provided in this article several examples on how to achieve this using the InstantKB .NET API. These examples are provided in C# and would require you reference the InstantKB assemblies from your .NET projects.

Add the necessary using statement 

At the top of your C# class add the necessary using or imports statement...

using InstantASP.InstantKB;

Now we have access to all the business logic exposed within the InstantASP.InstantKB namespace.

Getting Started

Let's start with a simple example that shows how to return all tickets created by a specific user within InstantKB. This C# code would look like so...

// get current authenciated InstantKB user
var identityProvider = Providers.UserIdentity.UserIdentityProvider.Instance();
var currentUser = identityProvider.GetAuthenticatedUser();
var t = new Business.TicketsRepository(currentUser);
// get page 1, with 50 results per page where the CreatedByUserID equals 123
var tickets = t.SelectTickets(1, 50, new SearchEventArgs()
{
CreatedByUserID = 123
});

if (tickets != null)
{
foreach (var ticket in tickets)
{
Response.Write(ticket.TicketTitle + "<br/>");
}
}

In this example only tickets created by the user with UserID 123 within the tabs our current authenticated user has access to would be returned. There are a few important things to note within this example before we provide further examples.

The TicketsRepository Class & Restrciting Results

Notice the following in the example above...

var t = new Business.TicketsRepository(currentUser);

Here we are constructing a new TicketsRepository object and passing in the current authenticated user. The TicketsRepository class requires a InstantASP.InstantKB.Component.User object to be passed into it's public constructor. The supplied user object is important as it's used for security purposes to ensure tickets are only returned from the tabs that the supplied user object has access to or permission to see.

For further information on controlling access to tabs for users please see Controlling Access To Tabs.

For example let's say our current authenticated user or the user passed into the TicketsRepository constructor only has access to the "Knowledgebase" tab via the InstantKB role based security. In this instance as the supplied user object cannot access any ticket tab the above code example would return no results as the supplied user object does not have permission to view or query any ticket tab.

In addition if the supplied user object is not a support agent or administrator within InstantKB only support tickets created by the user you pass into the TicketsRepository constrcutor will be returned. To search all support tickets regardless of who created the ticket the user object you supply must be a support agent or administrator within InstantKB. For example to search all support tickets you could use...

var t = new Business.TicketsRepository(new Components.User()
{
IsAdministrator = true
});
var tickets = t.SelectTickets(1, 10, new Components.SearchEventArgs()
{
Keywords = "Test"
});

if (tickets != null)
{
foreach (var ticket in tickets)
{
Response.Write(ticket.TicketTitle + "<br/>");
}
}

With this hopefully explained we'll continue to provide further examples of how you can query and return tickets within InstantKB. These examples will simply extend the code example provided above and will demonstrate the different properties you can use to filter returned tickets.

Return Tickets Created By a Specific User

To show all support tickets for a specific user you can use the CreatedByUserID property available within the SearchEventArgs class to filter returned support tickets as shown below...

var context = HttpContext.KnowledgeBaseContext.Current;
var t = new Business.TicketsRepository(context.CurrentUser);
var tickets = t.SelectTickets(1, 10, new Components.SearchEventArgs()
{
CreatedByUserID = context.CurrentUser.UserID
});
if (tickets != null)
{
foreach (var ticket in tickets)
{
Response.Write(string.Format("ID: {0}<br/>", ticket.TicketID));
}
}

You may be asking why we are both passing a user object tinto the TicketsRepository constructor and setting the CreatedByUserID property to the same user objects UserID. Surely we just need to pass the current user into the TicketsRepository constructor to restrcit results right? We'll not quite. For example if you don't set the CreatedByUserID property but pass a user object into the TicketsRepository constructor and this user object belongs to either an administrator or support agent role then all support tickets will be returned regardless of who created the ticket. To ensure we can filter results even if the user object passed into the TicketsRepository constrcutor is an administrator or support agent we also set the CreatedByUserID property.

This is not an issue if the user you pass into the TicketsRepository constrcutor is not an administrator or support agent. If the supplied user is not an administrator or support agent then the CreatedByUserID property will be ignored and only tickets created by the user passed int othe  TicketsRepository constrcutor will be returned.‚Äč

IMPORTANT
For secyrity purposes to use the CreatedByUserID property and query for support tickets created by other users the user object passed into the TicketsRepository constrcutor must belong to an administrator or support agent role. If the user object passed into the TicketsRepository constrcutor does not belong to an administrator or support agent role the returned tickets will be restricted to only those created by the user passed into the TicketsRepository constrcutor. This is explained further below with the "Returning Tickets Created By Others" section.

In the above example only tickets created by the current authenciated user will be returned.

Returning Tickets Created By Others

If we wanted to return tickets created by other users we need to ensure the user object being passed into the TicketsRepository constrcutor belongs to an administrator or support agent role within InstantKB. For example using the code below we can query all tickets created by UserID 123...

var t = new Business.TicketsRepository(new Components.User()
{
UserID = 1,
IsAdministrator = true
});
var tickets = t.SelectTickets(1, 10, new Components.SearchEventArgs()
{
CreatedByUserID = 123
});
if (tickets != null)
{
foreach (var ticket in tickets)
{
Response.Write(string.Format("ID: {0}<br/>", ticket.TicketID));
}
}

Whilst using the code below would only return tickets created by UserID 1 regardless of the CreatedByUserID propery value as the user object passed into the TicketsRepository constrcutor does not belong to a support agent or administator role...

var t = new Business.TicketsRepository(new Components.User()
{
UserID = 1
});
var tickets = t.SelectTickets(1, 10, new Components.SearchEventArgs()
{
CreatedByUserID = 123
});
if (tickets != null)
{
foreach (var ticket in tickets)
{
Response.Write(string.Format("ID: {0}<br/>", ticket.TicketID));
}
}

Furtther Examples

To show all overdue tickets (tickets where the due date has passed) you would modify the above example example like so...

var tickets = t.SelectTickets(1, 50, new SearchEventArgs()
{
TicketIsOverdue = true
});

You can of course combine filters. For example let's say we wanted to return all overdue tickets for a user with UserID 123 we could combine these...

var tickets = t.SelectTickets(1, 50, new SearchEventArgs()
{
CreatedByUserID = 123,
TicketIsOverdue = true
});

Oet let's say we wanted to return all tickets assigned to a specific support agent we could use the "AssignedToUserID" and supply the support agents user ID. For example...

var tickets = t.SelectTickets(1, 50, new SearchEventArgs()
{
AssignedToUserID =  123
});

Let's say we wanted to return all tickets with a specific status, priority or workflow step we could use...

var tickets = t.SelectTickets(1, 50, new SearchEventArgs()
{
StatusID = 10,
PriorityID = 3,
WorkFlowStepID = 4
});

Again if multiple filters are supplied InstantKB will perform an AND operation so in the example above only tickets that have a StatusID of 10 AND a PriorityID of 3 AND a WorkflowStopID of 4 would be returned.

As you can probably guess by now you can also perform a keyword search in a very similar way. For example to return all tickets that contained the terms Acme or Inc you would use...

var tickets = t.SelectTickets(1, 50, new SearchEventArgs()
{
Keywords = "Acme Inc"
});

Let's say you wanted to return tickets from specific tabs. You can do so as shown below...

var tickets = t.SelectTickets(1, 50, new SearchEventArgs()
{
Keywords = "Texting"
TabIDs = new string[] {"4", "5", "6"}
});

Where TabIDs is a string array containing the InstantKB_Tabs.TabIDs of the tabs you wish to return results from. Again the supplied user object must also have access to the supplied TabIDs.

That's It!

We hope these examples help you get started with our API to query and return tickets. IF there are any specific examples we would add to this article to assist please don't hesitate to submit a support request.