The latest version of the Workstars SDK is v3. It requires .NET 4.5+ and is available via the NuGet Package Manager which comes included with recent versions of Visual Studio. For more information about NuGet please see http://docs.nuget.org/consume/installing-nuget#installing-and-updating-nuget-client. Alternatively, the source code is available from https://bitbucket.org/workstars/api-sdk-dotnet/
Installation using NuGet Package Manager
- From the .NET Solution Explorer, right click on the project where you want to add the NuGet package and select Manage NuGet Packages
- The following screen appears, search for Workstars and click Install
- It’s now ready to use, see examples below
Code examples
Testing the connection
This example uses the Test function which calls the API and if the connection is successful, returns “Hello World”. You can use this to ensure you can connect to our API from your corporate network.
using System;
using WorkstarsSDK.Services;
using WorkstarsSDK.Models.Results;
namespace WorkstarsSDKExamples
{
public class Program
{
static void Main(string[] args)
{
// your connection details
string subDomain = "yourcompany"; // enter your subDomain here, it is the first part of the URL after https://
string apiKey = "111122223333444455556666"; //enter your apiKey here, this is found within the admin portal
// initiate service
WorkstarsService service = new WorkstarsService(subDomain, apiKey);
// call Test service
WorkstarsResult test = service.Test();
if (test.Success)
{
// write the response to the console
Console.WriteLine(test.Message);
}
else
{
// write the error code and error message to the console
Console.WriteLine(test.ErrorCode + " - " + test.Error);
}
// this just keeps the console open to view the results
Console.Read();
}
}
}
Validate an employee feed file
This example uses the ValidateEmployeeFileSchema function which downloads the employee XSD schema from the API and validates it locally. It should only be used for development purposes to ensure your employee XML file is formatted correctly, contains the required fields and content, etc.
using System;
using WorkstarsSDK.Models.Results;
using WorkstarsSDK.Services;
namespace WorkstarsSDKExamples
{
public class Program
{
static void Main(string[] args)
{
// your connection details
string subDomain = "yourcompany"; // enter your subDomain here, it is the first part of the URL after https://
string apiKey = "111122223333444455556666"; //enter your apiKey here, this is found within the admin portal
// initiate service
WorkstarsService service = new WorkstarsService(subDomain, apiKey);
// validate the file at the specific path (using the xsd schema from the API)
WorkstarsResult result = service.ValidateEmployeeFileSchema(@"C:\WorkstarsApi\employees.xml");
if (result.Success)
{
// print the success confirmation message to the console
Console.WriteLine("Validation Success");
Console.WriteLine(result.Message);
}
else
{
// print the error message to the console
Console.WriteLine("Validation Failed");
Console.WriteLine(result.ErrorCode + " - " + result.Error);
}
// this just keeps the console open to view the results
Console.Read();
}
}
}
Upload an employee feed file
This example uses the UploadEmployeeFile function which starts by downloading the employee XSD schema from the API and uses it to validate the file locally. If successful, it will then upload the file to the API for processing. It should only be used in your production environment and you should ensure all errors are handled and logged for further investigation.
If you need to test your file, you can use the ValidateEmployeeFileSchema function which only validates locally and doesnt submit the file to our API.
using System;
using WorkstarsSDK.Models.Results;
using WorkstarsSDK.Services;
namespace WorkstarsSDKExamples
{
public class Program
{
static void Main(string[] args)
{
// your connection details
string subDomain = "yourcompany"; // enter your subDomain here, it is the first part of the URL after https://
string apiKey = "111122223333444455556666"; //enter your apiKey here, this is found within the admin portal
// initiate service
WorkstarsService service = new WorkstarsService(subDomain, apiKey);
// validate and upload the file at the specified path
WorkstarsResult result = service.UploadEmployeeFile(@"C:\WorkstarsApi\employees.xml");
if (result.Success)
{
// print the success confirmation message to the console
Console.WriteLine("Success");
Console.WriteLine(result.Message);
}
else
{
// print the error message to the console
Console.WriteLine("Failure");
Console.WriteLine(result.ErrorCode + " - " + result.Error);
}
// this just keeps the console open to view the results
Console.Read();
}
}
}
Validate a position feed file
This example uses the ValidatePositionFileSchema function which downloads the position XSD schema from the API and validates it locally. It should only be used for development purposes to ensure your positions XML file is formatted correctly, contains the required fields and content, etc.
using System;
using WorkstarsSDK.Models.Results;
using WorkstarsSDK.Services;
namespace WorkstarsSDKExamples
{
public class Program
{
static void Main(string[] args)
{
// your connection details
string subDomain = "yourcompany"; // enter your subDomain here, it is the first part of the URL after https://
string apiKey = "111122223333444455556666"; //enter your apiKey here, this is found within the admin portal
// initiate service
WorkstarsService service = new WorkstarsService(subDomain, apiKey);
// validate the file at the specific path (using the xsd schema from the API)
WorkstarsResult result = service.ValidatePositionFileSchema(@"C:\WorkstarsApi\positions.xml");
if (result.Success)
{
// print the success confirmation message to the console
Console.WriteLine("Validation Success");
Console.WriteLine(result.Message);
}
else
{
// print the error message to the console
Console.WriteLine("Validation Failed");
Console.WriteLine(result.ErrorCode + " - " + result.Error);
}
// this just keeps the console open to view the results
Console.Read();
}
}
}
Upload a position feed file
This example uses the UploadPositionFile function which starts by downloading the position XSD schema from the API and uses it to validate the file locally. If successful, it will then upload the file to the API for processing. It should only be used in your production environment and you should ensure all errors are handled and logged for further investigation.
If you need to test your file, you can use the “ValidatePositionFileSchema” function which only validates locally and doesn't submit the file to our API.
using System;
using WorkstarsSDK.Models.Results;
using WorkstarsSDK.Services;
namespace WorkstarsSDKExamples
{
public class Program
{
static void Main(string[] args)
{
// your connection details
string subDomain = "yourcompany"; // enter your subDomain here, it is the first part of the URL after https://
string apiKey = "111122223333444455556666"; //enter your apiKey here, this is found within the admin portal
// initiate service
WorkstarsService service = new WorkstarsService(subDomain, apiKey);
// validate and upload the file at the specified path
WorkstarsResult result = service.UploadPositionFile(@"C:\WorkstarsApi\positions.xml");
if (result.Success)
{
// print the success confirmation message to the console
Console.WriteLine("Success");
Console.WriteLine(result.Message);
}
else
{
// print the error message to the console
Console.WriteLine("Failure");
Console.WriteLine(result.ErrorCode + " - " + result.Error);
}
// this just keeps the console open to view the results
Console.Read();
}
}
}
Recommendations
To help deal with any support issues we highly recommend that when an error occurs you log the ErrorCode and Error message into the event log. Below is an example:
using System;
using System.Diagnostics;
using WorkstarsSDK.Services;
using WorkstarsSDK.Models.Results;
namespace WorkstarsSDKExamples
{
public class Program
{
static void Main(string[] args)
{
// your connection details
string subDomain = "yourcompany"; // enter your subDomain here, it is the first part of the URL after https://
string apiKey = "111122223333444455556666"; //enter your apiKey here, this is found within the admin portal
// initiate service
WorkstarsService service = new WorkstarsService(subDomain, apiKey);
// call Test service
WorkstarsResult test = service.Test();
if (test.Success)
{
// print the success confirmation message to the console
Console.WriteLine(test.Message);
}
else
{
// Display an appropriate message to the user
Console.WriteLine("Sorry an error has occured please contact your IT team for further assistance.");
// log error into system application log
string sSource = "Workstars SDK";
string sLog = "Application";
if (!EventLog.SourceExists(sSource))
{
EventLog.CreateEventSource(sSource, sLog);
}
EventLog.WriteEntry(sSource, test.Error, EventLogEntryType.Error, test.ErrorCode);
}
// this just keeps the console open to view the results
Console.Read();
}
}
}
Comments (0 comments)