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:

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	String	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
ShortBreak	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) 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:

Property	Type	Description
`EmployeeID`	String	Employee Number in Time Management
`GroupInfo`	List	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) 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 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, 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:

Enter a support request to obtain the URL and auth GUID.
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 Code	Description
1	Unhandled exception
5	Either EmployeeId or ExternalEmployeeId is required
5	Date is required
6	Request 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:

Enter a support request to obtain the URL and auth GUID.
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 Code	Description
1	Unhandled exception
2	EmployeeId required
3	WorkDate required
4	Invalid Time data format
5	Request 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:

Enter a support request to obtain the URL and auth GUID.
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 Code	Description
0	Success
1	Unhandled 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; }
    }
}