Categories as custom fields for linked tickets with APIs
This article demonstrates how to use FocalScope Categories as custom fields and how to generate a report for categorized tickets using the SOAP API.
Tutorial
Preparing categories
For the sake of demonstration we will create three categories. The first, Work Number, will be used as a custom field to hold numerous unique dynamic values. It is required to tick the [dynamic values (skip prompt)] flag for this category (see the article How to configure and use FocalScope's Ticket Categories for more information) to ensure the best user experience and optimal system performance. The other two categories will be regular categories used to illustrate how categories can be used as columns in reports.
To continue with the example, please follow these steps:
- Create a dynamic category called Work Number and make sure the [dynamic values (skip prompt)] flag is ticked for this category
- Designate the category Work Number to several tickets with values ID10014, ID10015, ID10016
- Create a regular category Query Type with values Question and Suggestion
- Create a regular category Status with values In progress and Resolved
- Designate the categories Query Type and Status with values to the same tickets
Generating a report for categorized FocalScope tickets using SOAP
We will now generate a report filtered by the Work Number category with the Status and Query Types categories serving as report columns. The report will contain all tickets with work numbers assigned to them.
Please note: It is required to do some simple programming to generate the report. The code sample provided below is in C# programming language and utilizes .NET framework to make a SOAP call.
To use SOAP to generate a statistical report for categorized FocalScope tickets, do the following:
- In the [Main menu], select [Screen > Administration]
- Select the [Advanced properties] tab
- Select the [External API > SOAP API] folder
- Modify the code sample attached to this article and change the QueryEmailTicket function parameters as follows:
- Copy the SOAP service URL from the [Service link] field into soapService.Url property of the SOAP client object
- Generate the security token by clicking the [Obtain] button and copy it to the parameter "secToken"
- Specify sCatNameFilter = "Work Number" to filter tickets by the Work Number category
- Specify rgCatValFilter = { "ID10014", "ID10015" }, which are the work numbers we're interested in
- Specify rgCategoryColumns = {"Work Number", "Status", "Query Type" } to display the Work Number, Status, and Query Type categories as columns in the report
- Compile and run the sample
- The program creates an XML file named res.xml
- In the resulting file you will see all tickets inside the Work Number category having values ID10014 and ID10015 while the Work Number, Status, and Query Type categories appear as columns in the report
Figure 2 - Generating a SOAP query
Sample code
using System;
using System.Text;
using System.Data;
using System.Xml;
namespace ConsoleSoapClient
{
class Program
{
static void Main(string[] args)
{
SoapService.SoapApi soapService = new SoapService.SoapApi();
soapService.Url = "http://localhost/emm/net/SoapApi.asmx";
string secToken = "679ce3a602e862b4b8dab94cada958d8";
string sCatNameFilter = "Work number";
string[] rgCatValFilter = { "ID10014", "ID10015" };
string[] rgCategoryColumns = {"Work number", "Status", "Query type" };
DataSet ds = new DataSet();
ds = soapService.QueryEmailTicket(secToken, sCatNameFilter, rgCatValFilter, rgCategoryColumns);
XmlTextWriter writer = new XmlTextWriter("res.xml", null);
writer.Formatting = Formatting.Indented;
ds.WriteXml(writer);
}
}
}
Additional Information
- How to configure and use FocalScope's Ticket Categories
- How to query emails by ticket number and by folder using SOAP API calls
- Please note: In cases where emails contain binary data, please use the QueryEmailTicketBase64 function (see attached Program-Base64.zip file below). This way, the email body data you retrieve via the SOAP query will be encoded in Base64, and you will need to decode it