Not logged in - Login

  User Manual

  Tech Support

ServicePRO Software Development Kit (SDK) - Getting Started

Return to Utilities or Technical Documents

SDK Overview

This page outlines the usage of the ServicePRO Software Development Kit (SDK), including its purpose, prerequisites, installation and sample codes for use with the SDK.

What is ServicePRO SDK?

ServicePRO SDK is an API (.Net Class Library) used to access the ServicePRO Database.

What is possible with SDK?

ServicePRO SDK allows you to perform the following functions against the ServicePRO Database programmatically from a client application developed in .NET platform:
  • Manage service requests:
    • Get service request detail from ServicePRO Database
    • Add new service request       
    • Delete a service request
    • Add memo to a service request
    • Send quick message
    • Get service request detail
    • Get specific Request Properties
    • Get Service Requests Listing Data
  • Manage ServicePRO Objects – User, Company, Asset, Queue, Team, Role, Category, Product:
    • Add New, Update, Retire, Delete objects
    • Get specific Object Information
  • Manage Knowledge base:
    • Get, update, publish, retire or restore Knowledge base article (best solution)
    • Get best solution list

Having these functions available programmatically means that you can integrate these tasks into custom tools for exporting and importing data to and from ServicePRO.

Additional Resources

The ServicePRO SDK, Sample Open Source Code projects, and the Service Requests Import utility compile are available in a ZIP file per version under the following folder:

Pre-requisites

The following are prerequisites required for using the ServicePRO SDK.

Accessible ServicePRO.Server WCF service site

  • ServicePRO.Server WCF site is included with ServicePRO installation package

List of DLL files:

  • HelpSTAR.PCL.Common.dll
  • HelpSTAR.PCL.ObjectDesigner.dll
  • HelpSTAR.Transport.Hybrid.dll
  • ICSharpCode.SharpZipLib.dll
  • ServicePRO.Sdk.Windows.dll
  • ServicePRO.Sdk.Windows.XML

.NET Framework requirements, Visual Studio version requirements

  • Microsoft .NET framework 4.6.1; Visual Studio 2013 or later.

Supported Applications: This SDK was developed using MS Visual Studio 2013 (C# .NET), .NET framework 4.6.1. The SDK DLLs are built for ‘Any CPU’ version. Support information is as follows:

  • .NET 4.6.1 or later
  • SDK should work with Windows Forms, WPF and ASP.NET applications. The SDK has been tested so far with WPF and Windows Forms applications.

Getting Started

The client application project should add reference to the DLLs specified below in order to make ServicePRO SDK Method Calls. Also, in the client application, in order to use ServicePRO.SDK namespace, should add a Using Directive with ServicePRO.SDK namespace as “Using ServicePRO.Sdk.Windows”.

And the application developed using SDK should have access to ServicePRO WCF Service.

From project's reference menu, add reference to the following DLLs:

  • HelpSTAR.PCL.Common.dll
  • HelpSTAR.PCL.ObjectDesigner.dll
  • HelpSTAR.Transport.Hybrid.dll
  • ICSharpCode.SharpZipLib.dll
  • ServicePRO.Sdk.Windows.dll

The following Namespaces should be used in order to utilize ServicePRO SDK Methods:

  • using HelpSTAR.PCL.Common;
  • using HelpSTAR.PCL.ObjectDesigner.Elements;
  • using ServicePRO.Sdk.Windows;
  • using ServicePRO.Sdk.Windows.Managers;

The ServicePRO WCF service website URL and user credentials may be specified in the client application's app.config file (or Web.Config, in the case of ASP .NET web applications) and retrieved in the Application Code before establishing the session.

Alternatively, this information can be hardcoded in the client application code as well or set with constants.

       <?xml version="1.0" encoding="utf-8" ?>
       <configuration>
         <appSettings>
              <add key="serviceURL" value="http://YourServer/HelpSTAR.Server/"/>
              <add key="Username" value="ServicePRO Power Username"/>
              <add key="Userpassword" value="password"/>
         </appSettings>
         <startup>
              <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.6.1" />
         </startup>
       </configuration>

Code Samples to use ServicePRO SDK

Login Using AD Authentication

Sample Code to initialize & establish session and to login to ServicePRO Database for making further SDK Calls [C# .NET – WPF]:

//Step 1: Set Server URL (This is stored in client application's app.config file: )
ServerSettings.SetServiceUri(System.Configuration.ConfigurationSettings.AppSettings["ServiceURL"]);
//Step 2: Establish session  
private stcSession _session;
private CoreServicesManager _coreServiceManager;
private RequestServicesManager _requestManager;
private ObjectDesignerManager _udfManager;
private LoginServiceManager _loginManager;
private ManageObjectsServicesManager _objectManager;
private KnowledgeBaseServiceManager _knowledgebaseManager;

_coreServiceManager = new CoreServicesManager();
_udfManager = new ObjectDesignerManager();
_loginManager = new LoginServiceManager();
_requestManager = new RequestServicesManager();
_objectManager = new ManageObjectsServicesManager();
_knowledgebaseManager = new KnowledgeBaseServiceManager ();

_coreServiceManager.InitializeSystemAndSession(CultureInfo.CurrentCulture.Name, string.Format("{0};{1}",TimeZoneInfo.Local.StandardName, TimeZoneInfo.Local.DisplayName), DateTime.SpecifyKind(DateTime.Now, DateTimeKind.Unspecified),
                (stcSession result, Exception serviceException) =>
                {
                    if (serviceException != null)
                    {
                        MessageBox.Show(serviceException.ToString(), "Error");
                        return;
                    }
                    _session = result.Clone();

                    //Step 3: Get available domains (for login)
                    _loginManager.GetAvailableDomains(_session, Environment.UserDomainName, Environment.UserName,
                        (stcSession domainResult, string serverVersion, Exception serverException) =>
                        {
                            if (serverException != null)
                            {
                                MessageBox.Show(serverException.ToString(), "Error");
                                return;
                            }
                            _session = domainResult.Clone();
                            stcListItem selectedDomain = _session.AvailableDomains.FirstOrDefault(item => item.Id == 0);

                            //Step 4: Login
                            _loginManager.Login(selectedDomain, _session, "admin4", "password", true,
                                (stcUserLoginInfo loginInfo, Exception loginException) =>
                                {
                                    if (loginException != null)
                                    {
                                        MessageBox.Show(loginException.ToString(), "Error");
                                        return;
                                    }

                                    //Step 5: If login successful then initialize user session on the server
                                    if (loginInfo.LoginStatus == clsEnumeration.hsCheckLogin.hsSuccess)
                                    {
                                        _loginManager.InitializeUserSession(loginInfo.UserId, _session, string.Empty,
                                            (clsEnumeration.ConcurrentValidation conValidation, stcSession resultSession, Exception initializeException) =>
                                            {
                                                if (initializeException != null)
                                                {
                                                    MessageBox.Show(initializeException.ToString(), "Error");
                                                    return;
                                                }
                                                _session = resultSession.Clone();
                                                this.Dispatcher.Invoke(() =>
                                                {
                                                    TextBlockLoginInfo.Text = string.Format("Logged in as {0}", _session.User.User.Name);
                                                });
                                            });
                                    }
                                });
                        }
                    );
                });

Login Using ServicePRO User Credentials

Sample Code to initialize & establish session and to login to ServicePRO Database for making further SDK Calls [C# .NET – WPF]:

//Step 1: Set Server URL (This is stored in client application's app.config file)
ServerSettings.SetServiceUri(System.Configuration.ConfigurationSettings.AppSettings["ServiceURL"]);

       _coreServiceManager = new CoreServicesManager();
       _loginManager = new LoginServiceManager();
       //Step 2: Establish Session before logging in 
            _coreServiceManager.InitializeSystemAndSession(CultureInfo.CurrentCulture.Name, string.Format("{0};{1}", TimeZoneInfo.Local.StandardName, TimeZoneInfo.Local.DisplayName), DateTime.SpecifyKind(DateTime.Now, DateTimeKind.Unspecified),
                (stcSession result, Exception serviceException) =>
                {
                    if (serviceException != null)
                    {
                        MessageBox.Show(serviceException.ToString(), "Error");
                        return;
                    }
                    _session = result.Clone();

                     //get the username and password from the app.config file
                    string username = System.Configuration.ConfigurationSettings.AppSettings["Username"];
                    string password = System.Configuration.ConfigurationSettings.AppSettings["Userpassword"];

                    //Step 3: Login with ServicePRO User Crendentials
                    _loginManager.Login(null, _session, username, password, true,
                        (stcUserLoginInfo loginInfo, Exception loginException) =>
                        {
                            if (loginException != null)
                            {
                                MessageBox.Show(loginException.ToString(), "Error");
                                return;
                            }

                            //Step 4: If login successful then initialize user session on the server
                            if (loginInfo.LoginStatus == clsEnumeration.hsCheckLogin.hsSuccess)
                            {
                                _loginManager.InitializeUserSession(loginInfo.UserId, _session, string.Empty,
                                    (clsEnumeration.ConcurrentValidation conValidation, stcSession resultSession, Exception initializeException) =>
                                    {
                                        if (initializeException != null)
                                        {
                                            MessageBox.Show(initializeException.ToString(), "Error");
                                            return;
                                        }
                                        _session = resultSession.Clone();
                                        MessageBox.Show(string.Format("Logged in as {0}", _session.User.User.Name));
                                        
                                    });
                            }
                        });
                });

Add Service Request

private void AddServiceRequest()
        {
            RequestServicesManager _requestManager = new RequestServicesManager();
            stcRequest request = new stcRequest();
            request.Id = 0; //int
            request.WKF = clsEnumeration.hsWorkFlow.WF_QUEUE; 
            request.WKFId = 1; // Queue id
            request.Status =clsEnumeration.hsStatus.STS_IN_QUEUE;
            request.ObjectTypeId = 0; //Generic Service Request [For Custom types, we have to pass appropriate values]
            request.Title = "Request Created From SDK"; //string
            request.Requester = new stcListItem() { Name = "HS Admin", Id = 1 };
            request.DateLogged = DateTime.Now;
            request.Priority = clsEnumeration.hsPriority.PRI_CRITICAL;
            request.ProblemTypeId = 30048; // valid category id
            request.Memo = new stcMemo() //To set the first Memo
            {
                AuthorId = 1,
                DateWorked = DateTime.Now,
                MemoTime = DateTime.Now,
                FormatType = clsEnumeration.HsMemoFormatType.Text,
                Memo = "Request created from ServicePRO SDK",
                Type = 16387
            };
            ObservableCollection<stcUserFieldsTableValue> udfData = new ObservableCollection<stcUserFieldsTableValue>(); //to be populated with values for Custom Fields if it's a Custom Type Service Request
            
            _requestManager.SaveRequest(_session.Key, request, new ObservableCollection<stcAttachmentFolder>(),
                                                                new ObservableCollection<HelpSTAR.Hybrid.Common.stcAttachment>(), //No Attachments
                                                                udfData, new ObservableCollection<stcFollowUp>(), //No Reminders
                                                                null, DateTime.Now, new int[] { }, new stcRequest[] { }, null,
                                                                clsEnumeration.UpdateRecurrenceItemPrompt.None, null, null, null,
                                        (stcRequest savedRequest, Exception ex) =>
                                        {
                                            if (ex != null)
                                            {
                                                MessageBox.Show("Error\r\n" + ex.ToString(), "ServicePRO");
                                                return;
                                            }
                                            else
                                            {
                                                MessageBox.Show("Request #" + savedRequest.Id + " Added Successfully");
                                            }
                                        });

        }

Add Memo

private void AddMemo()
        {
              RequestServicesManager _requestManager = new RequestServicesManager();

            //First get the request
            _requestManager.GetRequest(_session.Key, 1579, false, 
                (stcRequest request, int repMemoCount, stcPrivilegeRequest requestPrivileges, bool hasAttachments, bool isPinned, Snapshot snapshotVersion, Exception ex)=>
                {
                    if (ex != null)
                    {
                        MessageBox.Show(ex.ToString());
                        return;
                    }
                    //Success operations
                    //Structure request contains the service request detail data;
                    stcMemo _stcMemo = new stcMemo();
                    _stcMemo.RequestId = 1579;
                    _stcMemo.AuthorId = 1;
                    _stcMemo.Memo = "New memo from SDK";
                    _stcMemo.FormattedMemo = "";// formatted HTML string
    
                    if (!string.IsNullOrEmpty(_stcMemo.FormattedMemo) &&
                        _stcMemo.FormatType == clsEnumeration.HsMemoFormatType.Text)
                        _stcMemo.FormatType = clsEnumeration.HsMemoFormatType.Html;

                    _stcMemo.TimeCode = clsEnumeration.hsTimeCode.Time1;
                    _stcMemo.PrivateMemo = true;
                    _stcMemo.Type = 16387; // int value
                    _stcMemo.SecondsWorked = 3; //int 
                    _stcMemo.DateWorked = DateTime.Now; // datatime value

                    request.Memo = _stcMemo; //add the memo to the request
                    ObservableCollection<stcUserFieldsTableValue> udfData = new ObservableCollection<stcUserFieldsTableValue>(); //to be populated with values for Custom Fields if it's a Custom Type Service Request
                    Concurrency concurrencyLocker = new Concurrency() { ObjectId = 1579, Status = clsEnumeration.ConcurrencyStatus.None };
                   //save the request with the new memo
                    _requestManager.SaveRequest(_session.Key, request, new ObservableCollection<stcAttachmentFolder>(),
                                                                new ObservableCollection<HelpSTAR.Hybrid.Common.stcAttachment>(), //No Attachments
                                                                udfData, new ObservableCollection<stcFollowUp>(), //No Reminders
                                                                null, DateTime.Now, new int[] { }, new stcRequest[] { }, null,
                                                                clsEnumeration.UpdateRecurrenceItemPrompt.None, concurrencyLocker, null, null,
                                        (stcRequest savedRequest, Exception e) =>
                                        {
                                            if (e != null)
                                            {
                                                MessageBox.Show("Error\r\n" + e.ToString(), "ServicePRO");
                                                return;
                                            }
                                            else
                                            {
                                                MessageBox.Show("Memo added to Request #" + savedRequest.Id + " Successfully");
                                            }
                                        });

                    }
                );
        }

Sample: Create new best solution

private void CreateNewBestSolution()
        {
              KnowledgeBaseServiceManager _knowledgebaseManager = new KnowledgeBaseServiceManager();

            var addSolution = new stcSolution()
            {
                AuthorId = 1,
                DateCreated = DateTime.Now,
                DateLastModified = DateTime.Now,
                DateMemoCreated = DateTime.Now,
                Hits = 0,
                SolutionStatus = clsEnumeration.hsSolutionStatus.hsDraft,
                RevisionNumber = 1,
                LastRevision = 0,
                NextRevision = 0,
                FolderId = 1, //Valid Folder ID 
                InActive = false,
                StandardMemo = "test best solution detail",
                ProblemDescription = "This is the problem description", //String value
                FormatType = clsEnumeration.HsMemoFormatType.Html,
                FormattedMemo = "test best solution detail",
                ProblemTypeId = 30048, //category id
                ObjectTypeId = 0, // generic best solution
                Id = 0,
                Title = "Best Solution Title", //String value
            };

            List<int> _checkedReferenceSolutionList = new List<int>();
            _knowledgebaseManager.SaveSolution(addSolution, true, _checkedReferenceSolutionList, null, _session.Key, (int result, Exception ex) =>
                {
                    if (ex == null)
                    {
                        //Success operations
                    }
                    else
                    {
                        //Prompt the user with the details on the exception
                    }
                });
        }

Sample: Add Asset

private void AddAsset()
        {
              ManageObjectsServicesManager _objectManager = new ManageObjectsServicesManager();

            stcAsset Asset = new stcAsset();
            Asset.ObjectTypeId = 0;
            Asset.Tag = (Asset.Tag == null ? string.Empty : Asset.Tag);
            Asset.Name = "SDK Asset Name";
            Asset.Qty = 1;

            _objectManager.SaveAsset(_session.Key, new List<stcAsset> { Asset }, Asset.Name, new List<stcUDFParamsIndexed>() { new stcUDFParamsIndexed() }, 
                (stcServiceResult result, Exception ex) =>
                {
                    if (ex != null)
                    {
                    //Prompt the user with the details on the exception
                    }
                    if (result.IsSuccessful)
                    {
                        //Success operations
                        
                       }
                }
                );
        }

Sample: Add Product

private void AddProduct()
        {
              ManageObjectsServicesManager _objectManager = new ManageObjectsServicesManager();

            stcProduct Product = new stcProduct();
            Product.Id = 0;
            Product.Name = "SDK Product Name";
            Product.Description = "This is my product.";
            Product.ObjectTypeId = 0; //Generic Product
            Product.CompanyId = 1;
            Product.InActive = false;

            stcCompanyProduct[] hsCompanyProducts = null;
            int[] deletedVendors = null;
            stcUserFieldsTableValue[] theUDFValues = null;

            if (!string.IsNullOrEmpty(Product.Name))
            {
                _objectManager.SaveProduct(_session.Key, Product, hsCompanyProducts, deletedVendors, theUDFValues,
                    (stcProduct ResultProduct, stcServiceResult result, Exception ex) =>
                    {
                        if (ex != null)
                        {
                            MessageBox.Show(ex.ToString(), "Error!");
                        }
                        if (result.IsSuccessful)
                        {
                            //Success operations
                            MessageBox.Show("Product [" + ResultProduct.Name + "] added successfully!");
                        }
                        else
                        {
                            MessageBox.Show(result.Message);
                        }
                    });
            }
            else
            {
                MessageBox.Show("Name cannot be empty!");
            }
        }

Sample: Get Service Request

private void GetServiceRequest()
        {
              RequestServicesManager _requestManager = new RequestServicesManager();

            _requestManager.GetRequest(_session.Key, 1579, false, 
                (stcRequest request, int repMemoCount, stcPrivilegeRequest requestPrivileges, bool hasAttachments, bool isPinned, Snapshot snapshotVersion, Exception ex)=>
                {
                    if (ex != null)
                    {
                        MessageBox.Show(ex.ToString());
                    }
                    //Success operations
                    //Structure request contains the service request detail data;
                    }
                );
        }

Sample: Get Quick Message

private void GetQuickMessage()
        {
              RequestServicesManager _requestManager = new RequestServicesManager();
            int requestId = 1579;
            clsEnumeration.hsSortDirection sort = clsEnumeration.hsSortDirection.Asc;
            int startRow = 0;
            int endRow = 200;

            _requestManager.GetRequestQuickMessagesAndReminders(_session.Key, requestId, sort, startRow, endRow, 
                (int rowCount, ObservableCollection<Dictionary<string, object>> result, ObservableCollection<Dictionary<string, object>> authorAvatars, Exception serviceException) =>
                {
                    if (serviceException != null)
                    {
                        MessageBox.Show(serviceException.ToString());
                        return;
                    }
                    else
                    {
                        //Success operations
                    }
                }
                );
        }

Sample: Get Folder by ID

private void GetFolderById()
        {
              RequestServicesManager _requestManager = new RequestServicesManager();

            int _queueId = 1; //any valid ID from tblqueue 
            stcQueue _selectedQueue;
            _requestManager.GetQueueDetails(_session.Key, _queueId,
            (stcQueue queueDetails, Exception ex) =>
            {
                if (ex != null)
                {
                    MessageBox.Show(ex.ToString(), "Error");
                    return;
                }
                _selectedQueue = queueDetails;
            });
        }

Sample: Get User by ID

private void GetUserById()
        {
ManageObjectsServicesManager _objectManager = new ManageObjectsServicesManager();
            int _UserId = 1; //any valid ID from tbluser
            _objectManager.GetUser(_session.Key, _UserId, 
                (stcUserDTO result, Exception ex)=>
                {
                    if (ex == null)
                    {
                        //Success operations
                    }
                    else
                    {
                        //Prompt the user with the details on the exception
                    }
                }
                );
        }