How to query emails by ticket number and by folder using SOAP API calls

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:

1. In the [Main menu], select [Screen > Administration]
2. Select the [Advanced properties] tab
3. Select the [External API > SOAP API] folder
4. Click the [Obtain] button to generate a security token. 
   1. Copy the [Security token], you will need to to run the 'CloseTicket' function
5. Click the [Open] button to launch the SOAP API test page
6. Click the [QueryEmailsByTicketNumbers] link to run the function
7. The 'QueryEmailsByTicketNumbers(secToken, rgTicket, fOnlyTicketRoot)' function uses the following parameters:
   1. string fOnlyTicketRoot - flag indicating email level in the ticket. Can be: False, true, 0, 1 
   2. string[] rgTicket - array comprising of ticket numbers
8. The 'QueryEmailsByFolders(secToken, rgFolder, fOnlyTicketRoot, DateFrom, DateTo, DataLimit, PageNo)' function uses the following parameters:
   1. string[] rgFolder - array of folder names, e.g., Root's Folders/Incoming
   2. 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
   3. string DataLimit - amount of rows per page, e.g., 1000
   4. string PageNo - page number, begins from 1, e.g., 1

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)