Time Management Web Services

UKG Web Services API Guide

Time Management Web Services

Introduction

With UKG Pro Web Services, you can leverage your UKG Pro Time Management data for solving business application and integration needs. We provide two sets of web services for you to use with Time Management:

  • Export APIs- enables you to extract data from Time Management.
  • Import APIs – enables you to import data into Time Management. (At this time, only schedule data can be imported into Time Management.)

This document describes how to use the Time Management Web Services and is intended for individuals who are familiar with software development processes and Web Services technologies.

Export APIs

UTMOdataServices API

The UTMOdataServices API enables you to programmatically retrieve time-related data from Time Management.

This document describes the methods of the Web service and also provides code examples using Microsoft’s Visual Studio 2010 using C#. The information in the Service Specifications table describes the service requirements.

Service Specifications

  • Protocol: Representational State Transfer (REST)
  • URL Convention: ODATA 4.0 (ODATA 4.0 URL Conventions)
  • SSL Support: Required

Sign Up and Licensing

  • Account Required: Time Management Web Service Account

AccessGroup Object

The Time Management AccessGroup object includes the following properties:

PropertyTypeDescription
IdIntegerAccess Group ID
DescriptionStringAccess Group Name

Employee Object

The Time Management Employee object includes the following properties:

PropertyTypeDescription
IdIntegerID Number
EmpIdStringEmployee Number
CardNumIntegerBadge Number
SupIdStringSupervisor User ID
SupNameStringSupervisor Name
FirstNameStringFirst Name
LastNameStringLast Name
ActiveStringStatus
EmailStringEmail Address
BirthDateStringBirth Date
HireDateStringHire Date
PayMethodIntegerPay Method Value
PayTypeIntegerPay Type Value
HoliRuleIntegerHoliday Rule Value
PayCateStringPay Category Value
PayGroupIdIntegerPay Group ID
LocationIdIntegerLocation ID
JobIdIntegerJob ID
ProjectIdIntegerProject ID
OrgLevel1IdIntegerOrg Level 1 ID
OrgLevel2IdIntegerOrg Level 2 ID
OrgLevel3IdIntegerOrg Level 3 ID
OrgLevel4IdIntegerOrg Level 4 ID
PayPolicyIdIntegerPay Policy ID
ShiftIdIntegerShift Rule ID
AccessGroupIdIntegerAccess Group ID

Job Object

The Time Management Job object includes the following properties:

PropertyTypeDescription
IdIntegerJob ID
NameStringJob Name
DescriptionStringJob Description

Location Object

The Time Management Location object includes the following properties:

PropertyTypeDescription
IdIntegerLocation ID
NameStringLocation Name
DescriptionStringLocation Description

OrgLevel1 Object

The Time Management OrgLevel1 object includes the following properties:

PropertyTypeDescription
IdIntegerOrgLevel1 ID
NameStringOrgLevel1 Name
DescriptionStringOrgLevel1 Description

OrgLevel2 Object

The Time Management OrgLevel2 object includes the following properties:

PropertyTypeDescription
IdIntegerOrgLevel2 ID
NameStringOrgLevel2 Name
DescriptionStringOrgLevel2 Description

OrgLevel3 Object

The Time Management OrgLevel3 object includes the following properties:

PropertyTypeDescription
IdIntegerOrgLevel3 ID
NameStringOrgLevel3 Name
DescriptionStringOrgLevel3 Description

OrgLevel4 Object

The Time Management OrgLevel4 object includes the following properties:

PropertyTypeDescription
IdIntegerOrgLevel4 ID
NameStringOrgLevel4 Name
DescriptionStringOrgLevel4 Description

Paycode Object

The Time Management Paycode object includes the following properties:

PropertyTypeDescription
IdIntegerPaycode ID
CodeStringPaycode Express Code
DescriptionStringPaycode Description

PayGroup Object

The Time Management PayGroup object includes the following properties:

PropertyTypeDescription
IdIntegerPayGroup ID
NameStringPayGroup Name
DescriptionStringPayGroup Description

PayMatrix Object

The Time Management PayMatrix object includes the following properties:

PropertyTypeDescription
IdIntegerID Number
EmployeeIDIntegerEmployee ID
WorkDateStringWork Date
PaycodeIdIntegerPaycode ID
PayIdentStringPay Matrix ID Type
HoursDecimalHours
PayAmountDecimalDollars
TimeIdIntegerID of Time Table

Project Object

The Time Management Project object includes the following properties:

PropertyTypeDescription
IdIntegerProject ID
NameStringProject Name
DescriptionStringProject Description

Reason Object

The Time Management Reason object includes the following properties:

PropertyTypeDescription
IdIntegerReason Code ID
CodeStringReason Code
DescriptionStringReason Code Name

Shift Object

The Time Management Shift object includes the following properties:

PropertyTypeDescription
IdIntegerShift ID
ShiftNumDecimalShift Number
DescriptionStringShift Description
ShiftTypeDecimalShift Type
ShiftCycDecimalShift Cycle
DaysCycleDecimalCycle Days
CycleRefStringCycle Reference Date
DayStartStringFlexible Shift Day Start
DayEndStringFlexible Shift Day End
LunchMetDecimalMeal Deduction Method
AutoLunchBooleanAutomatic Meal Deduction
OpenLunchDecimalConsidered A Meal Start
Lunch1HrDecimalMeal 1 Work Over Hours
Lunch2HrDecimalMeal 2 Work Over Hours
Lunch3HrDecimalMeal 3 Work Over Hours
Lunch4HrDecimalMeal 4 Work Over Hours
Lunch1DedDecimalMeal 1 Deduct In Minutes
Lunch2DedDecimalMeal 2 Deduct In Minutes
Lunch3DedDecimalMeal 3 Deduct In Minutes
Lunch4DedDecimalMeal 4 Deduct In Minutes
BreakWinDecimalApply Paid Breaks
NIBonusBooleanNo Meal Punch Bonus
NIBonusMnDecimalNo Meal Punch Bonus Minutes
NIMustWorkDecimalNo Meal Punch Bonus Must Work Over
BrkMethodDecimalApply Paid Breaks
BrkPayMinDecimalConsidered A Break When Within Minutes
BrkLimitDecimalPaid Break Up To Minutes
MealPayMinDecimalAllow Pay Reimbursement Up To Minutes
EndLunchDecimalConsidered A Meal End
SchedMealBooleanAlways Use Scheduled Meals
DedWindowBooleanAbsolute Deduction Window
CreateMealOutBooleanCreate A Minimum Meal Deduction
CreateMealOutHoursDecimalCreate A Minimum Meal Deduction Hours
AbsDedWinBooleanAbsolute Deduction Window
DynWkOnlyBooleanBased On Working Hours
NoSplitBooleanNo Not Split Punch
HasReimAfterBooleanDaily Limit Up To
ReimAfterDecimalDaily Limit Up To Minutes
MealOutIntegerDo Not Split Based On

ShiftDet Object

The Time Management ShiftDet object includes the following properties:

PropertyTypeDescription
IdIntegerShift Detail ID
ShiftNumDecimalShift Number From Shift Table
DayListDecimalDay Number
DayDescStringDay Description
WorkDayBooleanWorkday
DayStartStringFixed Shift Day Start
DayEndStringFixed Shift Day End
StartStringFixed Shift Start Time
EndStringFixed Shift End Time
LunchDecimalShift Period Meal Amount

ShiftLvl Object

The Time Management ShiftLvl object includes the following properties:

PropertyTypeDescription
IdIntegerShift Level ID
ShiftNumDecimalShift Number From Shift Table
LevelStringDynamic Shift Level
StartStringDynamic Shift Start Time
EndStringDynamic Shift End Time
LunchDecimalDynamic Shift Meal Deduction
DLinkDowStringDynamic Shift Day Of Week

Time Object

The Time Management Time object includes the following properties:

PropertyTypeDescription
IdIntegerID Number
EmpIdStringEmployee Number
WorkDateStringWork Date
PaycodeIdIntegerPaycode ID
PaycodeExpStringPaycode Express Code
InOrgStringIn Original
OutOrgStringOut Original
InStringIn Time
OutStringOut Time
InRoundedStringIn Time Rounded
OutRoundedStringOut Time Rounded
InExpStringIn Express Code
OutExpStringOut Express Code
ShiftExpStringShift Rule
SchHrsDecimalScheduled Hours
RegHrDecimalRegular Hours
Overt1DecimalOT-1 Hours
Overt2DecimalOT-2 Hours
Overt3DecimalOT-3 Hours
Overt4DecimalOT-4 Hours
Overt5DecimalOT-5 Hours
RegPayDecimalRegular Dollars
Ot1PayDecimalOT-1 Dollars
Ot2PayDecimalOT-2 Dollars
Ot3PayDecimalOT-3 Dollars
Ot4PayDecimalOT-4 Dollars
Ot5PayDecimalOT-5 Dollars
WeekRegDecimalWeekly Regular Hours
WeekOt1DecimalWeekly OT-1 Hours
WeekOt2DecimalWeekly OT-2 Hours
WeekOt3DecimalWeekly OT-3 Hours
WeekOt4DecimalWeekly OT-4 Hours
WeekOt5DecimalWeekly OT-5 Hours
ReasonIdIntegerReason Code ID
PaygroupIdIntegerPay Group ID
LocationIdIntegerLocation ID
JobIdIntegerJob ID
ProjectIdIntegerProject ID
OrgLevel1IdIntegerOrg Level 1 ID
OrgLevel2IdIntegerOrg Level 2 ID
OrgLevel3IdIntegerOrg Level 3 ID
OrgLevel4IdIntegerOrg Level 4 ID
PeriodThDecimalPeriod Hours
SiteInStringSite In
SiteOutStringSite Out
QuanGoodDecimalQuantity Good
QuanScrapDecimalQuantity Scrap
BegSchedStringBegin Schedule
EndSchedStringEnd Schedule
StatusIntegerApproval ID
AdjustmentDateStringAdjustment Date

Schedule Object

The Time Management Schedule object includes the following properties:

PropertyTypeDescription
IdIntegerSchedule ID
EmployeeIDIntegerEmployee ID
WorkDateStringSchedule Date
PaycodeIdIntegerPaycode Number
SchDateStringDate Entered/Date Approved
SchByIntegerWho Approved
SchStartIntegerSchedule Start Time
SchEndIntegerSchedule End Time
HoursDoubleHours
MealDedIntegerMeal Deduction In Minutes
PaygroupIdIntegerPay Group
LocationIdIntegerLocation
JobIdIntegerJob
ProjectIdIntegerProject
OrgLevel1IdIntegerOrg Level 1
OrgLevel2IdIntegerOrg Level 2
OrgLevel3IdIntegerOrg Level 3
OrgLevel4IdIntegerOrg Level 4
StatusIntegerStatus of Request
NoteStringEmployee Note
CommentStringSupervisor Note
ScheduleRequestIdInteger

ScheduleRequest Object

The Time Management ScheduleRequest object includes the following properties:

PropertyTypeDescription
IdIntegerSchedule Request ID
DescriptionStringScheduler Request Description
StartStringFrom Date
EndStringTo Date
PaycodeIdIntegerPaycode
SubmittedStringDate Submitted
DaysIntegerNumber of Days Requested
NotesStringNote
EmployeeIdIntegerEmployee ID

Timesheet Object

The Time Management Timesheet object includes the following properties:

PropertyTypeDescription
IdIntegerTimesheet ID
EmployeeIdIntegerEmployee ID
StartsStringPeriod Start Date
EndsStringPeriod End Date
MissPunchIntegerMissed Punch Count
TardyIntegerTardy Count
SchHrDoubleScheduled Hours
RegHrDoubleRegular Hours
Ot1DoubleOT-1 Hours
Ot2DoubleOT-2 Hours
Ot3DoubleOT-3 Hours
Ot4DoubleOT-4 Hours
Ot5DoubleOT-5 Hours
PayAmtDoubleDollars
SubmitBooleanSubmitted
ApproveBooleanApproved
SysUpdateStringTimestamp Of Update
EarlyInIntegerEarly In Count
GraceInIntegerGrace In Count
EarlyOutIntegerEarly Out Count
LateOutIntegerLate Out Count
LongMealIntegerLong Meal Count
ShortMealIntegerShort Meal Count
LongBreakIntegerLong Break Count
ShortBreakIntegerShort Break Count
AbsencesIntegerAbsent Count
DayApproveStringApprovedDays
StatusIntegerTimesheet Status
AutoMealIntegerAuto Meal Deduction Count
EarlyOutGIntegerEarly Out Grace Count
NoMealIntegerNo Meal Deduction Count
OvertimeDoubleOvertime Count
ShortWkDayIntegerShort Work Day Count
AppPunchDoubleUnapproved Punch Count
AuthOtDoubleUnauthorized Overtime Count
PaidBrkIntegerUnpaid Break Count
MlPremCntIntegerMeal Premium Count
MlPremWavIntegerMeal Premium Waived Count
BkPremCntIntegerBreak Premium Count
BkPremWavIntegerBreak Premium Waived Count

UTMOdataServices API Quick Start

This section provides steps for creating a sample application in your development environment to retrieve Time Management information.

Prerequisites

In order to use the UTMOdataServices API, the following prerequisite items must be completed:

  1. Obtain a Time Management Web Service Account username and password.
  2. Enter a support request to obtain the URL and to have user accounts created and passwords generated for access.
  3. Add a reference to Newtonsoft.Json (Json.NET) in your C# project. Newtonsoft.Json

Example Code - C#

The following code is an example of retrieving employee information from your Time Management data in a console application.

You can copy the entire contents to a C# console application and update the following values to have an operating application.

UserName = "YOUR UTM WEB SERVICE ACCOUNT",
Password = "YOUR PASSWORD",

The following are client classes that call the UtmOdataServices API given the provided credentials and URL.

OdataClientCredentials

public class OdataClientCredentials
{
    public string Username { get; set; }
    public string Password { get; set; }
    public Uri Url { get; set; }
}

OdataClient

public class OdataClient
{
    private readonly OdataClientCredentials _credentials;

    public OdataClient(OdataClientCredentials credentials)
    {
        if (credentials == null)
        {
            throw new ArgumentNullException("credentials");
        }

        _credentials = credentials;
    }

    public List<T> CallService<T>()
    {
        return CallService<T>(null);
    }

    public List<T> CallService<T>(string query)
    {
        var data = new List<T>();

        var fullyEscapedUri = _credentials.Url.AbsoluteUri.EndsWith("/")
            ? _credentials.Url
            : new Uri(_credentials.Url + "/");
        var uri = new Uri(fullyEscapedUri, typeof(T).Name);

        if (!string.IsNullOrWhiteSpace(query))
        {
            var uriBuilder = new UriBuilder(uri) { Query = query };
            uri = uriBuilder.Uri;
        }

        var request = WebRequest.Create(uri);
        request.Method = "GET";

        string base64EncodedUsernameAndPassword = string.Format("{0}:{1}", _credentials.Username, _credentials.Password);
        string authHeader = string.Format("Basic {0}", Convert.ToBase64String(Encoding.UTF8.GetBytes(base64EncodedUsernameAndPassword)));
        request.Headers["Authorization"] = authHeader;

        using (var response = request.GetResponse())
        {
            using (var stream = response.GetResponseStream())
            {
                using (var reader = new StreamReader(stream))
                {
                    string json = reader.ReadToEnd();
                    var jsonObj = JsonConvert.DeserializeObject(json) as JObject;
                    var jsonArray = jsonObj["value"] as JArray;

                    foreach (var jsonEmp in jsonArray)
                    {
                        var obj = JsonConvert.DeserializeObject<T>(jsonEmp.ToString());
                        data.Add(obj);
                    }
                }
            }
        }

        return data;
    }
}

Proxy Classes

A proxy class should be made for each object (aka table) available via the UTMOdataServices API. This will be used by the OdataClient to parse the JSON response.

public class AccessGroup
{
    public int Id { get; set; }
    public string Description { get; set; }
}

public class Employee
{
    public int Id { get; set; }
    public string EmpId { get; set; }
    public int? CardNum { get; set; }
    public string SupId { get; set; }
    public string SupName { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Active { get; set; }
    public string Email { get; set; }
    public string BirthDate { get; set; }
    public string HireDate { get; set; }
    public int? PayMethod { get; set; }
    public int? PayType { get; set; }
    public int? HoliRule { get; set; }
    public string PayCate { get; set; }
    public int? PaygroupId { get; set; }
    public int? LocationId { get; set; }
    public int? JobId { get; set; }
    public int? ProjectId { get; set; }
    public int? OrgLevel1Id { get; set; }
    public int? OrgLevel2Id { get; set; }
    public int? OrgLevel3Id { get; set; }
    public int? OrgLevel4Id { get; set; }
    public int? PayPolicyId { get; set; }
    public int? ShiftId { get; set; }
    public int? AccessGroupId { get; set; }
}

public class Job
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
}

public class Location
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
}

public class OrgLevel1
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
}

public class OrgLevel2
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
}

public class OrgLevel3
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
}

public class OrgLevel4
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
}

public class Paycode
{
    public int Id { get; set; }
    public string Code { get; set; }
    public string Description { get; set; }
}

public class Paygroup
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
}

public class PayMatrix
{
    public int Id { get; set; }
    public int? EmployeeId { get; set; }
    public DateTime? WorkDate { get; set; }
    public int? PaycodeId { get; set; }
    public string PayIdent { get; set; }
    public decimal? Hours { get; set; }
    public decimal? PayAmount { get; set; }
    public int? TimeId { get; set; }
}

public class Project
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
}

public class Reason
{
    public int Id { get; set; }
    public string Code { get; set; }
    public string Description { get; set; }
}

public class Schedule
{
    public int Id { get; set; }
    public int? EmployeeId { get; set; }
    public DateTime? WorkDate { get; set; }
    public int? PaycodeId { get; set; }
    public DateTime? SchDate { get; set; }
    public int? SchBy { get; set; }
    public int? SchStart { get; set; }
    public int? SchEnd { get; set; }
    public double? Hours { get; set; }
    public int? MealDed { get; set; }
    public int? PaygroupId { get; set; }
    public int? LocationId { get; set; }
    public int? JobId { get; set; }
    public int? ProjectId { get; set; }
    public int? OrgLevel1Id { get; set; }
    public int? OrgLevel2Id { get; set; }
    public int? OrgLevel3Id { get; set; }
    public int? OrgLevel4Id { get; set; }
    public int? Status { get; set; }
    public string Note { get; set; }
    public string Comment { get; set; }
    public int? ScheduleRequestId { get; set; }
}

public class ScheduleRequest
{
    public int Id { get; set; }
    public string Description { get; set; }
    public DateTime? Start { get; set; }
    public DateTime? End { get; set; }
    public int? PaycodeId { get; set; }
    public DateTime? Submitted { get; set; }
    public int? Days { get; set; }
    public string Notes { get; set; }
    public int? EmployeeId { get; set; }
}

public class Shift
{
    public int Id { get; set; }
    public decimal? ShiftNum { get; set; }
    public string Description { get; set; }
    public decimal? ShiftType { get; set; }
    public decimal? ShiftCyc { get; set; }
    public decimal? DaysCycle { get; set; }
    public string CycleRef { get; set; }
    public string DayStart { get; set; }
    public string DayEnd { get; set; }
    public decimal? LunchMet { get; set; }
    public bool? AutoLunch { get

; set; }
    public string Notes { get; set; }
}

Import APIs

Group Level API

The Group Level API enables you to import only changes rather than a full import.

This section describes the methods of the Web service and provides code examples using Microsoft’s Visual Studio 2010 with C#. The information in the Service Specifications table describes the service requirements.

Service Specifications

  • Protocol: Representational State Transfer (REST)
  • SSL Support: Required

ImportEmpGroupAccessData Object

The Time Management ImportEmpGroupAccessData object includes the following properties:

PropertyTypeDescription
EmployeeIDStringEmployee Number in Time Management
GroupInfoListList of Group Infos

GroupInfo Object

The Time Management GroupInfo object includes the following properties:

PropertyTypeDescription
GroupNumberStringGroup Number
GroupValueStringGroup Code
DescriptionStringGroup Description

Group Level API Quick Start

This section provides steps for creating a sample application in your development environment to import group data into Time Management.

Prerequisites

In order to use the Group Level API, the following prerequisite items must be completed:

  1. Enter a support request to obtain the URL and auth GUID.
  2. Add a reference to Newtonsoft.Json (Json.NET) in your C# project. Newtonsoft.Json

Request

Here is an example request:

{
	"EmployeeGroupAssignmentData": [
		{
			"EmployeeId": "STRING",
			"GroupInfo": [
				{
					"GroupNumber": "STRING",
					"GroupValue": "STRING"
				},
				{
					"GroupNumber": "STRING",
					"GroupValue": "STRING"
				}
			]
		}
	]
}

Example

{
	"EmployeeGroupAssignmentData": [
		{
			"EmployeeId": "000000001-5B8U4",
			"GroupInfo": [
				{
					"GroupNumber": "2",
					"GroupValue": "CA"
				},
				{
					"GroupNumber": "4",
					"GroupValue": "PROJ"
				}
			]
		},
		{
			"EmployeeId": "000000001-PTO15",
			"GroupInfo": [
				{
					"GroupNumber": "2",
					"GroupValue": "CA"
				},
				{
					"GroupNumber": "4",
					"GroupValue": "PROJ"
				}
			]
		}
	]
}

Responses and Error Codes

When a request is successful, the StatusCode returned is "0" and the StatusDescription returned is "Success." If the request is not successful, an error code is received.

Error CodeDescription
1Unhandled exception
5Either EmployeeId or ExternalEmployeeId is required
6Request too large

Here is an example response for a successful import:

{  
   "StatusCode": 0,
   "StatusDescription": "Success.",
   "Results": {  
      "ResultCount": 0,
      "PageNumber": 0,
      "TotalPages": 0,
      "Data": null
   }
}

Example Code – C#

The following is an example of code that can be used to import group access from a console application into Time Management.

You can copy the entire contents to a C# console application, update the following values, and have an operating application.

using System;
using System.Collections.Generic;
using System.IO;
using System.Net;
using System.Text;
using Newtonsoft.Json;

namespace LaborMetricGroupAccessExample
{
    class Program
    {
        private const string Url = "https://[ENVIRONMENTURL]/UtmRestServices/[CLIENTID]/EmployeeGroupAssignment/Update?AuthGUID=[AUTHGUID]";

        static void Main(string[] args)
        {
            var request = new LaborMetricGroupAccessRequest
            {
                EmployeeGroupAssignmentData = new List<EmployeeGroupAssignmentData>()
            };

            var groupInfo = new List<GroupInfo>
            {
                new GroupInfo
                { 
                    GroupNumber = "[Group Number]",
                    GroupValue = "[Group Value]",
                    Description = "[Description]"
                }
            };

            request.EmployeeGroupAssignmentData.Add(
                new EmployeeGroupAssignmentData
                {
                    EmployeeId = "[Employee Id]",
                    GroupInfo = groupInfo
                });

            var json = JsonConvert.SerializeObject(request);

            Post(Url, json);
        }

        public static void Post(string url, string json)
        {
            var encoding = new UTF8Encoding();
            var byteArray = encoding.GetBytes(json);
            var request = (HttpWebRequest) WebRequest.Create(url);
            request.Method = "POST";
            request.ContentLength = byteArray.Length;
            request.ContentType = @"application/json";

            using (var dataStream = request.GetRequestStream())
            {
                dataStream.Write(byteArray, 0, byteArray.Length);
            }

            using (var response = (HttpWebResponse) request.GetResponse())
            {
                var stream = response.GetResponseStream();

                if (stream != null)
                {
                    using (var readStream = new StreamReader(stream, Encoding.UTF8))
                    {
                        var info = readStream.ReadToEnd();
                        var responseObj = JsonConvert.DeserializeObject<EmployeeGroupAssignmentDataResponse>(info);
                        Console.WriteLine(responseObj);
                    }
                }
            }
        }
    }

    public class LaborMetricGroupAccessRequest
    {
        public List<EmployeeGroupAssignmentData> EmployeeGroupAssignmentData { get; set; }
    }

    public class EmployeeGroupAssignmentData
    {
        public string EmployeeId { get; set; }
        public List<GroupInfo> GroupInfo { get; set; }
    }

    public class GroupInfo
    {
        public string GroupNumber { get; set; }
        public string GroupValue { get; set; }
        public string Description { get; set; }
    }

    public class EmployeeGroupAssignmentDataResponse
    {
        public int StatusCode { get; set; }
        public string StatusDescription { get; set; }
        public EmployeeGroupAssignmentDataResults Results { get; set; }
    }

    public class EmployeeGroupAssignmentDataResults
    {
        public int ResultCount { get; set; }
        public int PageNumber { get; set; }
        public int TotalPages { get; set; }
        public object Data { get; set; }
    }
}

Schedule API Quick Start

This section provides steps for creating a sample application in your development environment to import schedule data into Time Management.

Prerequisites

In order to use the Schedule API, the following prerequisites must be completed:

  1. Enter a support request to obtain the URL and auth GUID.
  2. Add a reference to Newtonsoft.Json (Json.NET) in your C# project. Newtonsoft.Json

Request JSON

Here is an example request.

Request:

{  
   "Schedules":[   
      {  
         "Date": "STRING", 
         "EmployeeId": "STRING", 
         "ExternalEmployeeId": "STRING",  
         "Starts": "STRING",
         "Ends": "STRING",
         "Hours": "STRING",
         "Org1": "STRING",
         "Org2": "STRING",
         "Org3": "STRING",
         "Org4": "STRING",
         "Org5": "STRING",
         "Org6": "STRING",
         "Org7": "STRING",
         "Org8": "STRING",
         "MealFrom": "STRING",
         "MealTo": "STRING",
         "MealMinutes": "STRING",
         "PaycodeId": "STRING",
         "PaycodeCode": "STRING"
      }
   ]
}

Example

{  
   "Schedules":[  
      {  
         "Date": "2/6/2017",
         "EmployeeId": "000000001-5B8U4",
         "ExternalEmployeeId": "12345",
         "Starts": "9:00 AM",
         "Ends": "5:30 PM",
         "Hours": "8.5",
         "Org1": "QATESTER",
         "Org2": "QATESTER",
         "Org3": "QATESTER",
         "Org4": "QATESTER",
         "Org5": "QATESTER",
         "Org6": "QATESTER",
         "Org7": "QATESTER",
         "Org8": "QATESTER",
         "MealFrom": "8:00",
         "MealTo": "9:00",
         "MealMinutes": "30",
         "PaycodeId": "1",
         "PaycodeCode": "WRKH"
      }
   ]
}

Responses and Error Codes

When a request is successful, the StatusCode returned is 0 and the StatusDescription returned is Success. If the request is not successful, an error code is received.

Error Codes

Error CodeDescription
1Unhandled exception
5Either EmployeeId or ExternalEmployeeId is required
5Date is required
6Request too large

Example Response for a Successful Import

{  
   "StatusCode": 0,
   "StatusDescription": "Success.",
   "Results":{  
      "ResultCount": 0,
      "PageNumber": 0,
      "TotalPages": 0,
      "Data": null
   }
}

Example Code – C#

The following is an example of code that can be used to import schedules from a console application into Time Management.

You can copy the entire contents to a C# console application and update the following values to have an operating application.

using System;
using System.Collections.Generic;
using System.IO;
using System.Net;
using System.Text;
using Newtonsoft.Json;

namespace ScheduleImportExample
{
    class Program
    {
        private const string Url = "https://[ENVIRONMENTURL]/UtmRestServices/[CLIENTID]/ScheduleImport?AuthGUID=[AUTHGUID]";

        static void Main(string[] args)
        {
            var request = new ScheduleImportRequest
            {
                Schedules = new List<Schedule>()
            };

            request.Schedules.Add(
                new Schedule
                {
                    Date = "[DATE]",
                    EmployeeId = "[EMP ID]",
                    ExternalEmployeeId = "[EXTERNAL EMPLOYEE ID]",
                    Starts = "[START DATE]",
                    Ends = "[END DATE]",
                    Hours = "[HOURS]",        
                    Org1 = "[ORG1]",
                    Org2 = "[ORG2]",
                    Org3 = "[ORG3]",
                    Org4 = "[ORG4]",
                    Org5 = "[ORG5]",
                    Org6 = "[ORG6]",
                    Org7 = "[ORG7]",
                    Org8 = "[ORG8]",
                    MealFrom = "[MEAL FROM TIME]",
                    MealMinutes = "[MEAL MINUTES]",
                    MealTo = "[MEAL TO TIME]",
                    PaycodeCode = "[PAYCODE]",
                    PaycodeId = "[PAYCODE ID]"
                });

            var json = JsonConvert.SerializeObject(request);

            Post(Url, json);
        }

        public static void Post(string url, string json)
        {
            var encoding = new UTF8Encoding();
            var byteArray = encoding.GetBytes(json);
            var request = (HttpWebRequest) WebRequest.Create(url);
            request.Method = "POST";
            request.ContentLength = byteArray.Length;
            request.ContentType = @"application/json";

            using (var dataStream = request.GetRequestStream())
            {
                dataStream.Write(byteArray, 0, byteArray.Length);
            }

            using (var response = (HttpWebResponse) request.GetResponse())
            {
                var stream = response.GetResponseStream();

                if (stream != null)
                {
                    using (var readStream = new StreamReader(stream, Encoding.UTF8))
                    {
                        var info = readStream.ReadToEnd();
                        var responseObj = JsonConvert.DeserializeObject<ScheduleImportResponse>(info);
                        Console.WriteLine(responseObj);
                    }
                }
            }
        }
    }

    public class ScheduleImportRequest
    {
        public List<Schedule> Schedules { get; set; }
    }

    public class Schedule
    {
        public string Date { get; set; }
        public string EmployeeId { get; set; }
        public string ExternalEmployeeId { get; set; }
        public string Starts { get; set; }
        public string Ends { get; set; }
        public string Hours { get; set; }
        public string Org1 { get; set; }
        public string Org2 { get; set; }
        public string Org3 { get; set; }
        public string Org4 { get; set; }
        public string Org5 { get; set; }
        public string Org6 { get; set; }
        public string Org7 { get; set; }
        public string Org8 { get; set; }
        public string MealFrom { get; set; }
        public string MealTo { get; set; }
        public string MealMinutes { get; set; }
        public string PaycodeId { get; set; }
        public string PaycodeCode { get; set; }
    }

    public class ScheduleImportResponse
    {
        public int StatusCode { get; set; }
        public string StatusDescription { get; set; }
        public ScheduleImportResults Results { get; set; }
    }

    public class ScheduleImportResults
    {
        public int ResultCount { get; set; }
        public int PageNumber { get; set; }
        public int TotalPages { get; set; }
        public object Data { get; set; }
    }
}

Time Import API Quick Start

This section provides steps for creating a sample application in your development environment to import time data into Time Management.

Prerequisites

In order to use the Time Import API, the following prerequisites must be completed:

  1. Enter a support request to obtain the URL and auth GUID.
  2. Add a reference to Newtonsoft.Json (Json.NET) in your C# project. Newtonsoft.Json

Request JSON

Here is an example request.

Request:

{
    "TimeImportData": [
        {
          "EmpId": "STRING",
          "CardNum": "INTEGER",
          "WorkDate": "STRING",
          "In": "STRING",
          "Out": "STRING",
          "PaycodeId": "INTEGER",
          "RegHr": "DECIMAL",
          "Overt1": "DECIMAL",
          "Overt2": "DECIMAL",
          "Overt3": "DECIMAL",
          "Overt4": "DECIMAL",
          "Overt5": "DECIMAL",
          "PaygroupId": "INTEGER",
          "LocationId": "INTEGER",
          "JobId": "INTEGER",
          "ProjectId": "INTEGER",
          "OrgLevel1Id": "INTEGER",
          "OrgLevel2Id": "INTEGER",
          "OrgLevel3Id": "INTEGER",
          "OrgLevel4Id": "INTEGER",
          "QuanGood": "DECIMAL",
          "QuanScrap": "DECIMAL",
          "RegPay": "DECIMAL",
          "ReasonId": "STRING",
          "Note": "STRING"
        }
    ]
}

Example

{
    "TimeImportData": [
        {
            "EmpId": "876878799-GCDRX",
            "WorkDate": "12/18/2019",
            "In": "5:37",
            "Out": "10:11",
            "PaycodeId": 0,
            "RegHr": 8,
            "Overt1": 1.75,
            "Overt2": "",
            "Overt3": "",
            "Overt4": "",
            "Overt5": "",
            "PaygroupId": 1,
            "LocationId": 1,
            "JobId": 1,
            "ProjectId": 1,
            "OrgLevel1Id": 1,
            "OrgLevel2Id": 1,
            "OrgLevel3Id": 1,
            "OrgLevel4Id": 1,
            "QuanGood": 1,
            "QuanScrap": 0,
            "RegPay": 0,
            "ReasonId": "",
            "Note": ""
        }
    ]
}

Responses and Error Codes

When a request is successful, the StatusCode returned is 0 and the StatusDescription returned is Success. If the request is not successful, an error code is received.

Error Codes

Error CodeDescription
1Unhandled exception
2EmployeeId required
3WorkDate required
4Invalid Time data format
5Request too large

Example Response for a Successful Import

{  
   "StatusCode": 0,
   "StatusDescription": "Success.",
   "Results":{  
      "ResultCount": 1,
      "PageNumber": 1,
      "TotalPages": 1,
      "Data": [  
         {  
            "EmpId": "876878799-GCDRX",
            "WorkDate": "12/18/2019",
            "In": "5:37",
            "Out": "10:11",
            "PaycodeId": 0,
            "RegHr": 8,
            "Overt1": 1.75,
            "Overt2": "",
            "Overt3": "",
            "Overt4": "",
            "Overt5": "",
            "PaygroupId": 1,
            "LocationId": 1,
            "JobId": 1,
            "ProjectId": 1,
            "OrgLevel1Id": 1,
            "OrgLevel2Id": 1,
            "OrgLevel3Id": 1,
            "OrgLevel4Id": 1,
            "QuanGood": 1,
            "QuanScrap": 0,
            "RegPay": 0,
            "ReasonId": "",
            "Note": ""
         }
      ]
   }
}

Example Code – C#

The following is an example of code that can be used to import time data from a console application into Time Management.

You can copy the entire contents to a C# console application and update the following values to have an operating application.

using System;
using System.Collections.Generic;
using System.IO;
using System.Net;
using System.Text;
using Newtonsoft.Json;

namespace TimeImportExample
{
    class Program
    {
        private const string Url = "https://[ENVIRONMENTURL]/UtmRestServices/[CLIENTID]/TimeImport?AuthGUID=[AUTHGUID]";

        static void Main(string[] args)
        {
            var request = new TimeImportRequest
            {
                TimeImportData = new List<TimeImportData>()
            };

            request.TimeImportData.Add(
                new TimeImportData
                {
                    EmpId = "[EMP ID]",
                    WorkDate = "[WORK DATE]",
                    In = "[IN TIME]",
                    Out = "[OUT TIME]",
                    PaycodeId = 0,
                    RegHr = 0,
                    Overt1 = 0,
                    Overt2 = 0,
                    Overt3 = 0,
                    Overt4 = 0,
                    Overt5 = 0,
                    PaygroupId = 0,
                    LocationId = 0,
                    JobId = 0,
                    ProjectId = 0,
                    OrgLevel1Id = 0,
                    OrgLevel2Id = 0,
                    OrgLevel3Id = 0,
                    OrgLevel4Id = 0,
                    QuanGood = 0,
                    QuanScrap = 0,
                    RegPay = 0,
                    ReasonId = "",
                    Note = ""
                });

            var json = JsonConvert.SerializeObject(request);

            Post(Url, json);
        }

        public static void Post(string url, string json)
        {
            var encoding = new UTF8Encoding();
            var byteArray = encoding.GetBytes(json);
            var request = (HttpWebRequest) WebRequest.Create(url);
            request.Method = "POST";
            request.ContentLength = byteArray.Length;
            request.ContentType = @"application/json";

            using (var dataStream = request.GetRequestStream())
            {
                dataStream.Write(byteArray, 0, byteArray.Length);
            }

            using (var response = (HttpWebResponse) request.GetResponse())
            {
                var stream = response.GetResponseStream();

                if (stream != null)
                {
                    using (var readStream = new StreamReader(stream, Encoding.UTF8))
                    {
                        var info = readStream.ReadToEnd();
                        var responseObj = JsonConvert.DeserializeObject<TimeImportResponse>(info);
                        Console.WriteLine(responseObj);
                    }
                }
            }
        }
    }

    public class TimeImportRequest
    {
        public List<TimeImportData> TimeImportData { get; set; }
    }

    public class TimeImportData
    {
        public string EmpId { get; set; }
        public string WorkDate { get; set; }
        public string In { get; set; }
        public string Out { get; set; }
        public int PaycodeId { get; set; }
        public decimal RegHr { get; set; }
        public decimal Overt1 { get; set; }
        public decimal Overt2 { get; set; }
        public decimal Overt3 { get; set; }
        public decimal Overt4 { get; set; }
        public decimal Overt5 { get; set; }
        public int PaygroupId { get; set; }
        public int LocationId { get; set; }
        public int JobId { get; set; }
        public int ProjectId { get; set; }
        public int OrgLevel1Id { get; set; }
        public int OrgLevel2Id { get; set; }
        public int OrgLevel3Id { get; set; }
        public int OrgLevel4Id { get; set; }
        public decimal QuanGood { get; set; }
        public decimal QuanScrap { get; set; }
        public decimal RegPay { get; set; }
        public string ReasonId { get; set; }
        public string Note { get; set; }
    }

    public class TimeImportResponse
    {
        public int StatusCode { get; set; }
        public string StatusDescription { get; set; }
        public TimeImportResults Results { get; set; }
    }

    public class TimeImportResults
    {
        public int ResultCount { get; set; }
        public int PageNumber { get; set; }
        public int TotalPages { get; set; }
        public List<TimeImportData> Data { get; set; }
    }
}

Swipe and Go Import API Quick Start

This section provides steps for creating a sample application in your development environment to import punch data into Time Management.

Prerequisites

In order to use the Swipe and Go API, the following prerequisites must be completed:

  1. Enter a support request to obtain the URL and auth GUID.
  2. Add a reference to Newtonsoft.Json (Json.NET) in your C# project.

Request JSON

Here is an example request.

Request:

{
    "SwipeAndGoImportData": [
        {
            "EmpId": "STRING",
            "CardNum": "INTEGER",
            "WorkDate": "STRING",
            "Punch": "STRING",
            "PaygroupId": "INTEGER",
            "LocationId": "INTEGER",
            "JobId": "INTEGER",
            "ProjectId": "INTEGER",
            "OrgLevel1Id": "INTEGER",
            "OrgLevel2Id": "INTEGER",
            "OrgLevel3Id": "INTEGER",
            "OrgLevel4Id": "INTEGER",
            "ReasonId": "STRING",
            "Note": "STRING"
        }
    ]
}

Example

{
    "SwipeAndGoImportData": [
        {
            "EmpId": "876878799-GCDRX",
            "WorkDate": "12/10/2019",
            "PaycodeId": 0,
            "Punch": "14:30"
        },
        {
            "EmpId": "876878799-GCDRX",
            "WorkDate": "12/10/2019",
            "PaycodeId": 0,
            "Punch": "15:30"
        },
        {
            "EmpId": "876878799-GCDRX",
            "WorkDate": "12/10/2019",
            "PaycodeId": 0,
            "Punch": "17:30"
        }
    ]
}

Responses and Error Codes

When a request is successful, the StatusCode returned is 0 and the StatusDescription returned is Success. If the request is not successful, an error code is received.

Error Codes

Error CodeDescription
0Success
1Unhandled exception

The response object will have a Results object that contains:

  • ResultCount which will always be 0
  • PageNumber which will always be 0
  • TotalPages which will always be 0

The Data property will be an array of one object containing:

  • RecordsImported - Contains the number of successfully imported time records.
  • RecordsFailed - Contains the number of failed time records.
  • Failures (if there are any failed records) - Contains an array of objects with the failed data and a Reason property.

Example Response for a Successful Import

{
    "StatusCode": 0,
    "StatusDescription": "Success.",
    "Results": {
        "ResultCount": 0,
        "PageNumber": 0,
        "TotalPages": 0,
        "Data": [
            {
                "RecordsImported": 3,
                "RecordsFailed": 0,
                "Failures": []
            }
        ]
    }
}

Example Response for a Failed Import

{
    "StatusCode": 0,
    "StatusDescription": "Success.",
    "Results": {
        "ResultCount": 0,
        "PageNumber": 0,
        "TotalPages": 0,
        "Data": [
            {
                "RecordsImported": 0,
                "RecordsFailed": 1,
                "Failures": [
                    {
                        "Reason": "PaygroupId does not exist.",
                        "Data": {
                            "Id": null,
                            "EmpSeq": null,
                            "EmpId": "876878799-GCDRX",
                            "CardNum": null,
                            "WorkDate": "12/10/2019",
                            "Punch": "14:30",
                            "PaygroupId": "BAD ID",
                            "PaycodeId": 0,
                            "LocationId": null,
                            "JobId": null,
                            "ProjectId": null,
                            "OrgLevel1Id": null,
                            "OrgLevel2Id": null,
                            "OrgLevel3Id": null,
                            "OrgLevel4Id": null,
                            "ReasonId": null,
                            "Note": null
                        }
                    }
                ]
            }
        ]
    }
}

Example Code – C#

The following is an example of code that can be used to import punches from a console application into Time Management.

You can copy the entire contents to a C# console application and update the following values to have an operating application.

using System;
using System.Collections.Generic;
using System.IO;
using System.Net;
using System.Text;
using Newtonsoft.Json;

namespace SwipeAndGoImportExample
{
    class Program
    {
        private const string Url = "https://[ENVIRONMENTURL]/UtmRestServices/[CLIENTID]/SwipeAndGoImport?AuthGUID=[AUTHGUID]";

        static void Main(string[] args)
        {
            var request = new SwipeAndGoImportRequest
            {
                SwipeAndGoImportData = new List<SwipeAndGoImportData>()
            };

            request.SwipeAndGoImportData.Add(
                new SwipeAndGoImportData
                {
                    EmpId = "[EMP ID]",
                    CardNum = 0, // [CARD NUMBER]
                    WorkDate = "[WORK DATE]",
                    Punch = "[PUNCH TIME]",
                    PaycodeId = 0, // "[PAYCODE ID]"
                    PaygroupId = "[PAYGROUP ID]",
                    LocationId = "[LOCATION ID]",
                    JobId = "[JOB ID]",
                    ProjectId = "[PROJECT ID]",
                    OrgLevel1Id = "[ORG LEVEL 1 ID]",
                    OrgLevel2Id = "[ORG LEVEL 2 ID]",
                    OrgLevel3Id = "[ORG LEVEL 3 ID]",
                    OrgLevel4Id = "[ORG LEVEL 4 ID]",
                    ReasonId = "[REASON ID]",
                    Note = "[NOTE]",
                });

            var json = JsonConvert.SerializeObject(request);

            Post(Url, json);
        }

        public static void Post(string url, string json)
        {
            var encoding = new UTF8Encoding();
            var byteArray = encoding.GetBytes(json);
            var request = (HttpWebRequest)WebRequest.Create(url);
            request.Method = "POST";
            request.ContentLength = byteArray.Length;
            request.ContentType = @"application/json";

            using (var dataStream = request.GetRequestStream())
            {
                dataStream.Write(byteArray, 0, byteArray.Length);
            }

            using (var response = (HttpWebResponse)request.GetResponse())
            {
                var stream = response.GetResponseStream();

                if (stream != null)
                {
                    using (var readStream = new StreamReader(stream, Encoding.UTF8))
                    {
                        var info = readStream.ReadToEnd();
                        var responseObj = JsonConvert.DeserializeObject<SwipeAndGoImportResponse>(info);
                        Console.WriteLine(responseObj);
                    }
                }
            }
        }
    }

    public class SwipeAndGoImportRequest
    {
        public List<SwipeAndGoImportData> SwipeAndGoImportData { get; set; }
    }

    public class SwipeAndGoImportData
    {
        public string EmpId { get; set; }
        public int? CardNum { get; set; }
        public string WorkDate { get; set; }
        public string Punch { get; set; }
        public string PaygroupId { get; set; }
        public int? PaycodeId { get; set; }
        public string LocationId { get; set; }
        public string JobId { get; set; }
        public string ProjectId { get; set; }
        public string OrgLevel1Id { get; set; }
        public string OrgLevel2Id { get; set; }
        public string OrgLevel3Id { get; set; }
        public string OrgLevel4Id { get; set; }
        public string ReasonId { get; set; }
        public string Note { get; set; }
    }

    public class SwipeAndGoImportResponse
    {
        public int StatusCode { get; set; }
        public string StatusDescription { get; set; }
        public SwipeAndGoImportResults Results { get; set; }
    }

    public class SwipeAndGoImportResults
    {
        public int ResultCount { get; set; }
        public int PageNumber { get; set; }
        public int TotalPages { get; set; }
        public List<SwipeAndGoImportResultsData> Data { get; set; }
    }

    public class SwipeAndGoImportResultsData
    {
        public int RecordsImported { get; set; }
        public int RecordsFailed { get; set; }
        public List<SwipeAndGoImportFailure> Failures { get; set; }
    }

    public class SwipeAndGoImportFailure
    {
        public string Reason { get; set; }
        public SwipeAndGoImportData Data { get; set; }
    }
}