.NET SDK v3.x.x

The Workstars SDK 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

  1. From the .NET “Solution Explorer”, right click on the project where you want to add the nugget package and select Manage NuGet Packages
../_images/vs2017-step1.png
  1. The following screen appears, search for “Workstars” and click Install
../_images/vs2017-step2.png
  1. It’s now ready to use, please 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 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.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();
        }
    }
}