ServicePRO Software Development Kit (SDK) - Getting Started
Return to Utilities or Technical Documents
Contents [hide]
- 1. SDK Overview
- 2. Pre-requisites
- 3. Getting Started
- 4. Code Samples to use ServicePRO SDK
- 4.1 Login Using AD Authentication
- 4.2 Login Using ServicePRO User Credentials
- 4.3 Add Service Request
- 4.4 Add Memo
- 4.5 Sample: Create new best solution
- 4.6 Sample: Add Asset
- 4.7 Sample: Add Product
- 4.8 Sample: Get Service Request
- 4.9 Sample: Get Quick Message
- 4.10 Sample: Get Folder by ID
- 4.11 Sample: Get User by ID
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:- ServicePRO-SDK - File Directory
- For example: ServicePRO_SDK_14.1.4.4.zip is for version 14.1.4.4
- Readme
- Service Requests Import Utility User Guide
- Online Help for the ServicePRO SDK
- Also available on the Wiki on the Service Requests Import Utility page
Pre-requisites
The following are prerequisites required for using the ServicePRO SDK.Accessible ServicePRO.Server WCF service site (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.8; Visual Studio 2019 or Visual Studio 2017 (15.8 update).
Supported Applications:
This SDK was developed using MS Visual Studio 2019 (C# .NET), .NET framework 4.8.
The SDK DLLs are built for ‘Any CPU’ version.
Support information is as follows:
- Microsoft .NET Framework 4.8.
- 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/ServicePRO.Service/"/> <add key="Username" value="ServicePRO Administrator Username"/> <add key="Userpassword" value="password"/> </appSettings> <startup> <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.8" /> </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.AppSettin gs["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, TimeZoneInfo.Local.StandardName, DateTime.SpecifyKind(DateTime.Now, DateTimeKind.Unspecified), TimeZoneInfo.Local.GetUtcOffset(DateTime.Now),
(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, string kickOutMessage, string preferredSPLoginDomain, 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, clsEnumeration.hsInterface.Unknown,
(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,
(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.App Settings["ServiceURL"]);
_coreServiceManager = new CoreServicesManager();
_loginManager = new LoginServiceManager();
//Step 2: Establish Session before logging in
_coreServiceManager.InitializeSystemAndSession(CultureInfo.CurrentCulture.Name, TimeZoneInfo.Local.StandardName, DateTime.SpecifyKind(DateTime.Now, DateTimeKind.Unspecified), TimeZoneInfo.Local.GetUtcOffset(DateTime.Now),
(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, clsEnumeration.hsInterface.Unknown,
(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,
(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, (stcSolution solution, 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, string hexMessage, Exception ex)=>
{
if (ex == null)
{
//Success operations
}
else
{
//Prompt the user with the details on the exception
}
}
);
}