Query emails by ticket number or folder using SOAP APIs
This article demonstrates how to use the 'QueryEmailsByTicketNumbers' and 'QueryEmailsByFolders' SOAP API functions and also provides a C# code sample to demonstrate implementation.
Tutorial
Querying emails by ticket number / by folder with a SOAP call
To use SOAP to query emails in FocalScope by ticket number, do the following:
- In the [Main menu], select [Screen > Administration]
- Select the [Advanced properties] tab
- Select the [External API > SOAP API] folder
- Click the [Obtain] button to generate a security token.
- Copy the [Security token], you will need to to run the 'CloseTicket' function
- Click the [Open] button to launch the SOAP API test page
- Click the [QueryEmailsByTicketNumbers] link to run the function
- The 'QueryEmailsByTicketNumbers(secToken, rgTicket, fOnlyTicketRoot)' function uses the following parameters:
- string fOnlyTicketRoot - flag indicating email level in the ticket. Can be: False, true, 0, 1
- string[] rgTicket - array comprising of ticket numbers
- The 'QueryEmailsByFolders(secToken, rgFolder, fOnlyTicketRoot, DateFrom, DateTo, DataLimit, PageNo)' function uses the following parameters:
- string[] rgFolder - array of folder names, e.g., Root's Folders/Incoming
- string DateFrom, DateTo - the interval of email received dates with the following format: YYYY-MM-DD HH:MM:SS. Please note: The range can not exceed 1 month
- string DataLimit - amount of rows per page, e.g., 1000
- string PageNo - page number, begins from 1, e.g., 1
Please note: Parameter values for the 'QueryEmailsByTicketNumbers' and 'QueryEmailsByFolders' functions must match the above examples precisely. Also, the security token is mandatory and must not have expired.
Figure 1 - ...
Sample code
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Data;
using System.Data.SqlClient;
using System.Xml;
namespace ConsoleSoapClient
{
class Program
{
static SoapService.SoapApi soapService;
static void QueryEmailsByTicketNumbers(string secToken, string fileName)
{
string[] rgTicket = {"1589","10079","7185","8513","17218","1543" };
string fOnlyTicketRoot = "true";
DataSet ds = new DataSet();
ds = soapService.QueryEmailsByTicketNumbers(secToken, rgTicket, fOnlyTicketRoot);
XmlTextWriter writer = new XmlTextWriter(fileName, null);
writer.Formatting = Formatting.Indented;
ds.WriteXml(writer);
}
static void QueryEmailsByFolders(string secToken, string fileName)
{
string[] rgFolder = { "Shared Items/Ticketboxes/2.4 Other PCR" };
string fOnlyTicketRoot = "0";
string DateFrom = "2013-12-01";
string DateTo = "2013-12-20";
string DataLimit = "100";
string PageNo = "3";
DataSet ds = new DataSet();
ds = soapService.QueryEmailsByFolders(secToken, rgFolder, fOnlyTicketRoot, DateFrom, DateTo, DataLimit, PageNo);
XmlTextWriter writer = new XmlTextWriter(fileName, null);
writer.Formatting = Formatting.Indented;
ds.WriteXml(writer);
}
static void Main(string[] args)
{
soapService = new SoapService.SoapApi();
soapService.Url = "http://localhost/emm/net/soapapi.asmx";
string secToken = "6710ebc2da8754782f1e14ab8b6c7be5";
QueryEmailsByTicketNumbers(secToken, "EmailsByTickets.xml");
QueryEmailsByFolders(secToken, "EmailsByFolders.xml");
}
}
}
Additional Information
- How to use FocalScope categories as custom fields and retrieve the associated tickets using SOAP API
- Please note: In cases where emails contain binary data, please use the QueryEmailsByTicketNumbersBase64 / QueryEmailsByFoldersBase64 functions (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
- To include information about the number of attachments an email has, please use the QueryEmailsWithAttachInfoByTicketNumbersBase64 / QueryEmailsWithAttachInfoByFoldersBase64 functions. To retrieve the attachment(s) of an email, please use the GetEmailAttachmentsByEmails function (see attached EmailAttachInfo.zip file below)