Web Services API Guide: Time Management Web Services

Export APIs

Introduction

With UKG's UKG Pro Web Services, you can leverage your UKG ProTime 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.

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.

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 (http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html)
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.

Property Type Description
Id Integer Access Group ID
Description String Access Group Name

Employee Object

The Time Management Employee object includes the following properties.

Property Type Description
Id Integer ID Number
EmpId String Employee Number
CardNum Integer Badge Number
SupId String Supervisor User ID
SupName String Supervisor Name
FirstName String First Name
LastName String Last Name
Active String Status
Email String Email Address
BirthDate String Birth Date
HireDate String Hire Date
PayMethod Integer Pay Method Value
PayType Integer Pay Type Value
HoliRule Integer Holiday Rule Value
PayCate String Pay Category Value
PayGroupId Integer Pay Group ID
LocationId Integer Location ID
JobId Integer Job ID
ProjectId Integer Project ID
OrgLevel1Id Integer Org Level 1 ID
OrgLevel2Id Integer Org Level 2 ID
OrgLevel3Id Integer Org Level 3 ID
OrgLevel4Id Integer Org Level 4 ID
PayPolicyId Integer Pay Policy ID
ShiftId Integer Shift Rule ID
AccessGroupId Integer Access Group ID

Job Object

The Time Management Job object includes the following properties.

Property Type Description
Id Integer Job ID
Name String Job Name
Description String Job Description

Location Object

The Time Management Location object includes the following properties.

Property Type Description
Id Integer Location ID
Name String Location Name
Description String Location Description

OrgLevel1 Object

The Time Management OrgLevel1 object includes the following properties.

Property Type Description
Id Integer OrgLevel1 ID
Name String OrgLevel1 Name
Description String OrgLevel1 Description

OrgLevel2 Object

The Time Management OrgLevel2 object includes the following properties.

Property Type Description
Id Integer OrgLevel2 ID
Name String OrgLevel2 Name
Description String OrgLevel2 Description

OrgLevel3 Object

The Time Management OrgLevel3 object includes the following properties.

Property Type Description
Id Integer OrgLevel3 ID
Name String OrgLevel3 Name
Description String OrgLevel3 Description

OrgLevel4 Object

The Time Management OrgLevel4 object includes the following properties.

Property Type Description
Id Integer OrgLevel4 ID
Name String OrgLevel4 Name
Description String OrgLevel4 Description

Paycode Object

The Time Management Paycode object includes the following properties.

Property Type Description
Id Integer Paycode ID
Code String Paycode Express Code
Description String Paycode Description

PayGroup Object

The Time Management PayGroup object includes the following properties.

Property Type Description
Id Integer PayGroup ID
Name String PayGroup Name
Description String PayGroup Description

PayMatrix Object

The Time Management PayMatrix object includes the following properties.

Property Type Description
Id Integer ID Number
EmployeeID Integer Employee ID
WorkDate String Work Date
PaycodeId Integer Paycode ID
PayIdent String Pay Matrix ID Type
Hours Decimal Hours
PayAmount Decimal Dollars
TimeId Integer ID of Time Table

Project Object

The Time Management Project object includes the following properties.

Property Type Description
Id Integer Project ID
Name String Project Name
Description String Project Description

Reason Object

The Time Management Reason object includes the following properties.

Property Type Description
Id Integer Reason Code ID
Code String Reason Code
Description Reason Code Name

Shift Object

The Time Management Shift object includes the following properties.

Property Type Description
Id Integer Shift ID
ShiftNum Decimal Shift Number
Description String Shift Description
ShiftType Decimal Shift Type
ShiftCyc Decimal Shift Cycle
DaysCycle Decimal Cycle Days
CycleRef String Cycle Reference Date
DayStart String Flexible Shift Day Start
DayEnd String Flexible Shift Day End
LunchMet Decimal Meal Deduction Method
AutoLunch Boolean Automatic Meal Deduction
OpenLunch Decimal Considered A Meal Start
Lunch1Hr Decimal Meal 1 Work Over Hours
Lunch2Hr Decimal Meal 2 Work Over Hours
Lunch3Hr Decimal Meal 3 Work Over Hours
Lunch4Hr Decimal Meal 4 Work Over Hours
Lunch1Ded Decimal Meal 1 Deduct In Minutes
Lunch2Ded Decimal Meal 2 Deduct In Minutes
Lunch3Ded Decimal Meal 3 Deduct In Minutes
Lunch4Ded Decimal Meal 4 Deduct In Minutes
BreakWin Decimal Apply Paid Breaks
NIBonus Boolean No Meal Punch Bonus
NIBonusMn Decimal No Meal Punch Bonus Minutes
NIMustWork Decimal No Meal Punch Bonus Must Work Over
BrkMethod Decimal Apply Paid Breaks
BrkPayMin Decimal Considered A Break When Within Minutes
BrkLimit Decimal Paid Break Up To Minutes
MealPayMin Decimal Allow Pay Reimbursement Up To Minutes
EndLunch Decimal Considered A Meal End
SchedMeal Boolean Always Use Scheduled Meals
DedWindow Boolean Absolute Deduction Window
CreateMealOut Boolean Create A Minimum Meal Deduction
CreateMealOutHours Decimal Create A Minimum Meal Deduction Hours
AbsDedWin Boolean Absolute Deduction Window
DynWkOnly Boolean Based On Working Hours
NoSplit Boolean No Not Split Punch
HasReimAfter Boolean Daily Limit Up To
ReimAfter Decimal Daily Limit Up To Minutes
MealOut Integer Do Not Split Based On

ShiftDet Object

The Time Management ShiftDet object includes the following properties.

Property Type Description
Id Integer Shift Detail ID
ShiftNum Decimal Shift Number From Shift Table
DayList Decimal Day Number
DayDesc String Day Description
WorkDay Boolean Workday
DayStart String Fixed Shift Day Start
DayEnd String Fixed Shift Day End
Start String Fixed Shift Start Time
End String Fixed Shift End Time
Lunch Decimal Shift Period Meal Amount

ShiftLvl Object

The Time Management ShiftLvl object includes the following properties.

Property Type Description
Id Integer Shift Level ID
ShiftNum Decimal Shift Number From Shift Table
Level String Dynamic Shift Level
Start String Dynamic Shift Start Time
End String Dynamic Shift End Time
Lunch Decimal Dynamic Shift Meal Deduction
DLinkDow String Dynamic Shift Day Of Week

Time Object

The Time Management Time object includes the following properties.

Property Type Description
Id Integer ID Number
EmpId String Employee Number
WorkDate String Work Date
PaycodeId Integer Paycode ID
PaycodeExp String Paycode Express Code
InOrg String In Original
OutOrg String Out Original
In String In Time
Out String Out Time
InRounded String In Time Rounded
OutRounded String Out Time Rounded
InExp String In Express Code
OutExp String Out Express Code
ShiftExp String Shift Rule
SchHrs Decimal Scheduled Hours
RegHr Decimal Regular Hours
Overt1 Decimal OT-1 Hours
Overt2 Decimal OT-2 Hours
Overt3 Decimal OT-3 Hours
Overt4 Decimal OT-4 Hours
Overt5 Decimal OT-5 Hours
RegPay Decimal Regular Dollars
Ot1Pay Decimal OT-1 Dollars
Ot2Pay Decimal OT-2 Dollars
Ot3Pay Decimal OT-3 Dollars
Ot4Pay Decimal OT-4 Dollars
Ot5Pay Decimal OT-5 Dollars
WeekReg Decimal Weekly Regular Hours
WeekOt1 Decimal Weekly OT-1 Hours
WeekOt2 Decimal Weekly OT-2 Hours
WeekOt3 Decimal Weekly OT-3 Hours
WeekOt4 Decimal Weekly OT-4 Hours
WeekOt5 Decimal Weekly OT-5 Hours
ReasonId Integer Reason Code ID
PaygroupId Integer Pay Group ID
LocationId Integer Location ID
JobId Integer Job ID
ProjectId Integer Project ID
OrgLevel1Id Integer Org Level 1 ID
OrgLevel2Id Integer Org Level 2 ID
OrgLevel3Id Integer Org Level 3 ID
OrgLevel4Id Integer Org Level 4 ID
PeriodTh Decimal Period Hours
SiteIn String Site In
SiteOut String Site Out
QuanGood Decimal Quantity Good
QuanScrap Decimal Quantity Scrap
BegSched String Begin Schedule
EndSched String End Schedule
Status Integer Approval ID
AdjustmentDate String Adjustment Date

Schedule Object

The Time Management Schedule object includes the following properties.

Property Type Description
Id Integer Schedule ID
EmployeeID Integer Employee ID
WorkDate String Schedule Date
PaycodeId Integer Paycode Number
SchDate String Date Entered/Date Approved
SchBy Integer Who Approved
SchStart Integer Schedule Start Time
SchEnd Integer Schedule End Time
Hours Double Hours
MealDed Integer Meal Deduction In Minutes
PaygroupId Integer Pay Group
LocationId Integer Location
JobId Integer Job
ProjectId Integer Project
OrgLevel1Id Integer Org Level 1
OrgLevel2Id Integer Org Level 2
OrgLevel3Id Integer Org Level 3
OrgLevel4Id Integer Org Level 4
Status Integer Status of Request
Note String Employee Note
Comment String Supervisor Note
ScheduleRequestId Integer

ScheduleRequest Object

The Time Management ScheduleRequest object includes the following properties.

Property Type Description
Id Integer Schedule Request ID
Description String Scheduler Request Description
Start String From Date
End String To Date
PaycodeId Integer Paycode
Submitted String Date Submitted
Days Integer Number of Days Requested
Notes String Note
EmployeeId Integer Employee ID

Timesheet Object

The Time Management Timesheet object includes the following properties.

Property Type Description
Id Integer Timesheet ID
EmployeeId Integer Employee ID
Starts String Period Start Date
Ends String Period End Date
MissPunch Integer Missed Punch Count
Tardy Integer Tardy Count
SchHr Double Scheduled Hours
RegHr Double Regular Hours
Ot1 Double OT-1 Hours
Ot2 Double OT-2 Hours
Ot3 Double OT-3 Hours
Ot4 Double OT-4 Hours
Ot5 Double OT-5 Hours
PayAmt Double Dollars
Submit Boolean Submitted
Approve Boolean Approved
SysUpdate String Timestamp Of Update
EarlyIn Integer Early In Count
GraceIn Integer Grace In Count
EarlyOut Integer Early Out Count
LateOut Integer Late Out Count
LongMeal Integer Long Meal Count
ShortMeal Integer Short Meal Count
LongBreak Integer Long Break Count
Short Break Integer Short Break Count
Absences Integer Absent Count
DayApprove String ApprovedDays
Status Integer Timesheet Status
AutoMeal Integer Auto Meal Deduction Count
EarlyOutG Integer Early Out Grace Count
NoMeal Integer No Meal Deduction Count
Overtime Double Overtime Count
ShortWkDay Integer Short Work Day Count
AppPunch Double Unapproved Punch Count
AuthOt Double Unauthorized Overtime Count
PaidBrk Integer Unpaid Break Count
MlPremCnt Integer Meal Premium Count
MlPremWav Integer Meal Premium Waived Count
BkPremCnt Integer Break Premium Count
BkPremWav Integer Break 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:

  • Obtain a Time Management Web Service Account username and password.
  • Enter a support request to obtain the URL and to have user accounts created and passwords generated for access.
  • Add a reference to Newtonsoft.Json (Json.NET http://www.newtonsoft.com/json) in your C# project.

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 and 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;
            }
        }

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 decimal? OpenLunch { get; set; }
            public decimal? Lunch1Hr { get; set; }
            public decimal? Lunch2Hr { get; set; }
            public decimal? Lunch3Hr { get; set; }
            public decimal? Lunch4Hr { get; set; }
            public decimal? Lunch1Ded { get; set; }
            public decimal? Lunch2Ded { get; set; }
            public decimal? Lunch3Ded { get; set; }
            public decimal? Lunch4Ded { get; set; }
            public decimal? BreakWin { get; set; }
            public bool? NlBonus { get; set; }
            public decimal? NlBonusMn { get; set; }
            public decimal? NlMustWork { get; set; }
            public decimal? Brkmethod { get; set; }
            public decimal? BrkPayMin { get; set; }
            public decimal? BrkLimit { get; set; }
            public decimal? MealPyMin { get; set; }
            public decimal? EndLunch { get; set; }
            public bool? SchedMeal { get; set; }
            public bool? DedWindow { get; set; }
            public bool? CreateMealOut { get; set; }
            public decimal? CreateMealOutHours { get; set; }
            public bool? AbsDedWin { get; set; }
            public bool? DynWkOnly { get; set; }
            public bool? NoSplit { get; set; }
            public bool? HasReimAfter { get; set; }
            public decimal? ReimAfter { get; set; }
            public int? MealOut { get; set; }
        }

        public class ShiftDet
        {
            public int Id { get; set; }
            public decimal? ShiftNum { get; set; }
            public decimal? DayList { get; set; }
            public string DayDesc { get; set; }
            public bool? WorkDay { get; set; }
            public string DayStart { get; set; }
            public string DayEnd { get; set; }
            public string Start { get; set; }
            public string End { get; set; }
            public decimal? Lunch { get; set; }
        }

        public class ShiftLvl
        {
            public int Id { get; set; }
            public decimal? ShiftNum { get; set; }
            public string Level { get; set; }
            public string Start { get; set; }
            public string End { get; set; }
            public decimal? Lunch { get; set; }
            public string DLinkDow { get; set; }
        }
                                         
        public class Time
        {
            public int Id { get; set; }
            public string EmpId { get; set; }
            public DateTime? WorkDate { get; set; }
            public int? PaycodeId { get; set; }
            public string PaycodeExp { get; set; }
            public DateTime? InOrg { get; set; }
            public DateTime? OutOrg { get; set; }
            public DateTime? In { get; set; }
            public DateTime? Out { get; set; }
            public DateTime? InRounded { get; set; }
            public DateTime? OutRounded { get; set; }
            public string InExp { get; set; }
            public string OutExp { get; set; }
            public string ShiftExp { get; set; }
            public decimal? SchHrs { 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 decimal? RegPay { get; set; }
            public decimal? Ot1Pay { get; set; }
            public decimal? Ot2Pay { get; set; }
            public decimal? Ot3Pay { get; set; }
            public decimal? Ot4Pay { get; set; }
            public decimal? Ot5Pay { get; set; }
            public decimal? WeekReg { get; set; }
            public decimal? WeekOt1 { get; set; }
            public decimal? WeekOt2 { get; set; }
            public decimal? WeekOt3 { get; set; }
            public decimal? WeekOt4 { get; set; }
            public decimal? WeekOt5 { get; set; }
            public int? ReasonId { 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? PeriodTh { get; set; }
            public string SiteIn { get; set; }
            public string SiteOut { get; set; }
            public decimal? QuanGood { get; set; }
            public decimal? QuanScrap { get; set; }
            public string BegSched { get; set; }
            public string EndSched { get; set; }
            public int? Status { get; set; }
            public string AdjustmentDate { get; set; }
        }

        public class Timesheet
        {
            public int Id { get; set; }
            public int? EmployeeId { get; set; }
            public DateTime? Starts { get; set; }
            public DateTime? Ends { get; set; }
            public int? MissPunch { get; set; }
            public int? Tardy { get; set; }
            public double? SchHr { get; set; }
            public double? RegHr { get; set; }
            public double? Ot1 { get; set; }
            public double? Ot2 { get; set; }
            public double? Ot3 { get; set; }
            public double? Ot4 { get; set; }
            public double? Ot5 { get; set; }
            public double? PayAmt { get; set; }
            public bool? Submit { get; set; }
            public bool? Approve { get; set; }
            public DateTime? SysUpdate { get; set; }
            public int? EarlyIn { get; set; }
            public int? GraceIn { get; set; }
            public int? EarlyOut { get; set; }
            public int? LateOut { get; set; }
            public int? LongMeal { get; set; }
            public int? ShortMeal { get; set; }
            public int? LongBreak { get; set; }
            public int? ShortBreak { get; set; }
            public int? Absences { get; set; }
            public string DayApprove { get; set; }
            public int? Status { get; set; }
            public int? AutoMeal { get; set; }
            public int? EarlyOutG { get; set; }
            public int? NoMeal { get; set; }
            public double? Overtime { get; set; }
            public int? ShortWkDay { get; set; }
            public double? AppPunch { get; set; }
            public double? AuthOt { get; set; }
            public int? PaidBrk { get; set; }
            public int? MlPremCnt { get; set; }
            public int? MlPremWav { get; set; }
            public int? BkPremCnt { get; set; }
            public int? BkPremWav { get; set; }
        }
    }
}

After creating these classes, the client can be used as follows:

var credentials = new OdataClientCredentials
            {
                Username = "yourusername",
                Password = "yourpassword",
                Url = new Uri("http://youruri/api"),
            };

            var client = new OdataClient(credentials);
            var accessGroup = client.CallService<AccessGroup>();
            var employees = client.CallService<Employee>();
            var jobs = client.CallService<Job>();
            var locations = client.CallService<Location>();
           var org1Levels = client.CallService<OrgLevel1>();
            var org2Levels = client.CallService<OrgLevel2>();
            var org3Levels = client.CallService<OrgLevel3>();
            var org4Levels = client.CallService<OrgLevel4>();
            var paycodes = client.CallService<Paycode>();
            var paymatrices = client.CallService<PayMatrix>();
            var projects = client.CallService<Project>();
            var reasons = client.CallService<Reason>();
            var schedules = client.CallService<Schedule>();
            var scheduleRequests = client.CallService<ScheduleRequest>();
            var shifts = client.CallService<Shift>();
            var shiftDetails = client.CallService<ShiftDet>();
            var shiftLevels = client.CallService<ShiftLvl>();
            var time = client.CallService<Time>();
            var timesheets = client.CallService<Timesheet>();

            // Call service with ODATA compliant filter
            // Gets time records with WorkDates between 3/4/2012 and 3/20/2012
            // See http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html for more info
            var filteredTimes = client.CallService<Time>("$filter=WorkDate ge 2012-03-04 and WorkDate le 2012-03-20");
        }

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 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)
SSL Support Required

ImportEmpGroupAccessData Object

The Time Management ImportEmpGroupAccessData object includes the following properties.

Property Type Description
EmployeeID String Employee Number in Time Management
GroupInfo

List<GroupInfo>

 List of Group Infos

GroupInfo Object

The Time Management GroupInfo object includes the following properties.

Property Type Description
GroupNumber String Group Number
GroupValue String Group Code
Description String Group 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:

  • Enter a support request to obtain the URL and auth GUID.
  • Add a reference to Newtonsoft.Json (Json.NET http://www.newtonsoft.com/json) in your C# project.

Request JSON

Here is an example request.

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 Code Description
1 Unhandled exception
5 Either EmployeeId or ExternalEmployeeId is required
6 Request 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 and 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>()
            groupInfo.add(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>
    }

    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

The Schedule API enables you to programmatically import schedule data from a third-party system into Time Management.

This section 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)
SSL Support Required

Schedule Object

The Time Management Schedule object includes the following properties.

Property Type Description
Date String Schedule Date
EmployeeID String Employee Number in Time Management
ExternalEmployeeId String Employee ID from the third-party system
Starts String

Start time for the record; must be paired with end time

HH:MM am/pm

24HH:MM (for example, 09:30 am and 5:30 pm)

Ends String

End time for the record; must be paired with start time

HH:MM am/pm

24HH:MM (for example, 09:30 AM and 5:30 PM)
Hours String Hours
Org1 String Org Level 1
Org2 String Org Level 2
Org3 String Org Level 3
Org4 String Org Level 4
Org5 String Org Level 5
Org6 String Org Level 6
Org7 String Org Level 7
Org8 String Org Level 8
MealFrom String

Start time for the meal

HH:MM am/pm

24HH:MM
MealTo String

End time for the meal

HH:MM am/pm

24HH:MM
MealMinutes String Total time scheduled for employee break (for example, 30 minutes)
PaycodeId String

Pay code ID associated with the record

Note: The Import process applies the employee default value if the Pay Code field is blank.
PaycodeCode String Four character value assigned to the pay code

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:

  • Enter a support request to obtain the URL and auth GUID.
  • Add a reference to Newtonsoft.Json (Json.NET http://www.newtonsoft.com/json) in your C# project.

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 Code Description
1 Unhandled exception
5 Either EmployeeId or ExternalEmployeeId is required
5 Date is required
6 Request 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 schedules from a console application into Time Management.

You can copy the entire contents to a C# console application and 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 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:

  • Enter a support request to obtain the URL and auth GUID.
  • Add a reference to Newtonsoft.Json (Json.NET http://www.newtonsoft.com/json) in your C# project.

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": "UTM02",
            "LocationId": "FL",
            "JobId": "BARBACK",
            "ProjectId": "PROJ",
            "OrgLevel1Id": "ORGLV1",
            "OrgLevel2Id": "ORGLV2",
            "OrgLevel3Id": "ORGLV3",
            "OrgLevel4Id": "ORGLV4",
            "QuanGood": 800.25,
            "QuanScrap": "",
            "RegPay": "",
            "ReasonId": "",
            "Note": "This is an example note"
        },
        {
            "CardNum": 8798,
            "WorkDate": "12/18/2019",
            "In": "10:37",
            "Out": "14:57",
            "PaycodeId": 0,
            "RegHr": 8,
            "Overt1": 1.75,
            "Overt2": "",
            "Overt3": "",
            "Overt4": "",
            "Overt5": "",
            "PaygroupId": "UTM02",
            "LocationId": "FL",
            "JobId": "BARBACK",
            "ProjectId": "PROJ",
            "OrgLevel1Id": "ORGLV1",
            "OrgLevel2Id": "ORGLV2",
            "OrgLevel3Id": "ORGLV3",
            "OrgLevel4Id": "ORGLV4",
            "QuanGood": 800.25,
            "QuanScrap": "",
            "RegPay": "",
            "ReasonId": “”
        }
    ]
}

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 Code Description
0 Success
1 Unhandled exception

The response object will have a Results object that contains a ResultCount which will always be 0, a PageNumber which will always be 0, and a TotalPages which will always be 0.

The Data property will be an array of 1 that contains an object with the following:
  • RecordsImported - Contains the number of successfully imported time records.
  • RecordsFailed - Contains the number of failed time records.
  • Failures, if there are any failed records (RecordsFailed > 0) - Contains an array of objects with the failed data and a Reason property.

Here is an example response for a successful import. 

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

Here is an example response for a failed import. 

{
    "StatusCode": 0,
    "StatusDescription": "Success.",
    "Results": {
        "ResultCount": 0,
        "PageNumber": 0,
        "TotalPages": 0,
        "Data": [
            {
                "RecordsImported": 0,
                "RecordsFailed": 2,
                "Failures": [
                    {
                        "Reason": "Data already exists.",
                        "Data": {
                            "Id": null,
                            "EmpSeq": null,
                            "EmpId": "563626270-GCDQM",
                            "CardNum": null,
                            "WorkDate": "12/11/2019",
                            "In": "07:00",
                            "Out": "11:00",
                            "PaycodeId": 0,
                            "RegHr": null,
                            "Overt1": null,
                            "Overt2": null,
                            "Overt3": null,
                            "Overt4": null,
                            "Overt5": null,
                            "PaygroupId": null,
                            "LocationId": null,
                            "JobId": null,
                            "ProjectId": null,
                            "OrgLevel1Id": null,
                            "OrgLevel2Id": null,
                            "OrgLevel3Id": null,
                            "OrgLevel4Id": null,
                            "QuanGood": null,
                            "QuanScrap": null,
                            "RegPay": null,
                            "ReasonId": null,
                            "Note": "from postman"
                        }
                    },
                    {
                        "Reason": "Data already exists.",
                        "Data": {
                            "Id": null,
                            "EmpSeq": null,
                            "EmpId": "563626270-GCDQM",
                            "CardNum": null,
                            "WorkDate": "12/11/2019",
                            "In": "09:00",
                            "Out": "18:00",
                            "PaycodeId": 0,
                            "RegHr": null,
                            "Overt1": null,
                            "Overt2": null,
                            "Overt3": null,
                            "Overt4": null,
                            "Overt5": null,
                            "PaygroupId": null,
                            "LocationId": null,
                            "JobId": null,
                            "ProjectId": null,
                            "OrgLevel1Id": null,
                            "OrgLevel2Id": null,
                            "OrgLevel3Id": null,
                            "OrgLevel4Id": null,
                            "QuanGood": null,
                            "QuanScrap": null,
                            "RegPay": null,
                            "ReasonId": null,
                            "Note": "from postman"
                        }
                    }
                ]
            }
        ]
    }
}

Example Code – C#

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

You can copy the entire contents to a C# console application and 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 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]",
                CardNum = 0, // [CARD NUMBER]
                WorkDate = "[WORK DATE]",
                In = "[IN TIME]",
                Out = "[OUT TIME]",
                PaycodeId = 0, //"[PAYCODE ID]"
                RegHr = 0, //"[REGULAR HOURS]"
                Overt1 = 0, //"[OVERTIME 1 HOURS]"
                Overt2 = 0, //"[OVERTIME 2 HOURS]"
                Overt3 = 0, //"[OVERTIME 3 HOURS]"
                Overt4 = 0, //"[OVERTIME 4 HOURS]"
                Overt5 = 0, //"[OVERTIME 5 HOURS]"
                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]",
                QuanGood = 0, //"[QUANTITY GOOD]"
                QuanScrap = 0, //"[QUANTITY SCRAP]"
                RegPay = 0, //"[REGULAR PAY]"
                ReasonId = "[REASON ID]",
                Note = "[NOTES]"
            });

            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 int? CardNum { 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 string PaygroupId { 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 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<TimeImportResultsData> Data { get; set; }
    }

    public class TimeImportResultsData
    {
        public int RecordsImported { get; set; }
        public int RecordsFailed { get; set; }
        public List<TimeImportFailure> Failures { get; set; }
    }

    public class TimeImportFailure
    {
        public string Reason { get; set; }
        public 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:

  • Enter a support request to obtain the URL and auth GUID.
  • Add a reference to Newtonsoft.Json (Json.NET http://www.newtonsoft.com/json) 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 Code Description
0 Success
1 Unhandled exception

The response object will have a Results object that contains a ResultCount which will always be 0, a PageNumber which will always be 0, and a TotalPages which will always be 0.

The Data property will be an array of 1 that contains an object with the following:
  • RecordsImported - Contains the number of successfully imported time records.
  • RecordsFailed - Contains the number of failed time records.
  • Failures, if there are any failed records (RecordsFailed > 0) - Contains an array of objects with the failed data and a Reason property.

Here is an example response for a successful import. 

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

Here is an 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 and 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<SwipeAndGoImportResonse>(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 SwipeAndGoImportResonse
    {
        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; }
    }
}

© UKG Inc. All rights reserved. For a full list of UKG trademarks, visit www.ukg.com/trademarks. All other trademarks, if any, are the property of their respective owners. No part of this document or its content may be reproduced in any form or by any means or stored in a database or retrieval system without the prior written authorization of UKG Inc. (“UKG”). Information in this document is subject to change without notice. The document and its content are confidential information of UKG and may not be disseminated to any third party. Nothing herein constitutes legal advice, tax advice, or any other advice. All legal or tax questions or concerns should be directed to your legal counsel or tax consultant.

Liability/Disclaimer

UKG makes no representation or warranties with respect to the accuracy or completeness of the document or its content and specifically disclaims any responsibility or representation for other vendors’ software. The terms and conditions of your agreement with us regarding the software or services provided by us, which is the subject of the documentation contained herein, govern this document or content. All company, organization, person, and event references are fictional. Any resemblance to actual companies, organizations, persons, and events is entirely coincidental.

Links to Other Materials: The linked sites and embedded links are not under the control of UKG. We reserve the right to terminate any link or linking program at any time. UKG does not endorse companies or products to which it links. If you decide to access any of the third-party sites linked to the site, you do so entirely at your own risk.