Workforce Central Developer’s Toolkit Reference Guide Timekeeping

®

An alphabetical listing of the XML application programming interface (API) tag definitions that are used by the Workforce Central platform and Workforce Timekeeper.

Kronos Workforce Central Suite Version 6

Document Part Number: 4703971-001 Document Revision: A

The information in this document is subject to change without notice and should not be construed as a commitment by Kronos Incorporated. Kronos Incorporated assumes no responsibility for any errors that may appear in this manual. This document or any part thereof may not be reproduced in any form without the written permission of Kronos Incorporated. All rights reserved. Copyright 2007. Altitude, Altitude Dream, Cambridge Clock, CardSaver, Datakeeper, Datakeeper Central, eForce, Gatekeeper, Gatekeeper Central, Imagekeeper, Jobkeeper Central, Keep.Trac, Kronos, Kronos Touch ID, the Kronos logo, My Genies, PeoplePlanner, PeoplePlanner & Design, Schedule Manager & Design, ShiftLogic, ShopTrac, ShopTrac Pro, StarComm, StarPort, StarSaver, StarTimer, TeleTime, Timekeeper, Timekeeper Central, TimeMaker, Unicru, Visionware, Workforce Accruals, Workforce Central, Workforce Decisions, Workforce Express, Workforce Genie, and Workforce TeleTime are registered trademarks of Kronos Incorporated or a related company. Altitude MPP, Altitude MPPXpress, Altitude Pairing, Altitude PBS, Comm.Mgr, CommLink, DKC/Datalink, eDiagnostics, Experts at Improving the Performance of People and Business, FasTrack, Hireport, HR and Payroll Answerforce, HyperFind, Kronos 4500 Touch ID, Kronos 4500, Kronos 4510, Kronos Acquisition, Kronos e-Central, Kronos KnowledgePass, Kronos TechKnowledgy, KronosWorks, KVC OnDemand, Labor Plus, Momentum Essentials, Momentum Online, Momentum, MPPXpress, Overall Labor Effectiveness, Schedule Assistant, Smart Scheduler, Smart View, Start Quality, Start WIP, Starter Series, StartLabor, Timekeeper Decisions, Timekeeper Web, VisionPlus, Winstar Elite, WIP Plus, Workforce Acquisition, Workforce Activities, Workforce Analytics, Workforce Attendance, Workforce Central Portal, Workforce Connect, Workforce Employee, Workforce HR, Workforce Leave, Workforce Manager, Workforce MobileTime, Workforce Operations Planner, Workforce Payroll, Workforce Record Manager, Workforce Recruiter, Workforce Scheduler with Optimization, Workforce Scheduler, Workforce Smart Scheduler, Workforce Tax Filing, Workforce Timekeeper, and Workforce View are trademarks of Kronos Incorporated or a related company. Mozilla.org is a registered trademark of the Mozilla Foundation. All other trademarks or registered trademarks used herein are the property of their respective owners and are used for identification purposes only. When using and applying the information generated by Kronos products, customers should ensure that they comply with the applicable requirements of federal and state law, such as the Fair Labor Standards Act. Nothing in this Guide shall be construed as an assurance or guaranty that Kronos products comply with any such laws. Published by Kronos Incorporated 297 Billerica Road, Chelmsford, Massachusetts 01824-4119 USA Phone: 978-250-9800, Fax: 978-367-5900 Kronos Incorporated Global Support: 1-800-394-HELP (1-800-394-4357) For links to information about international subsidiaries of Kronos Incorporated, go to http://www.kronos.com Document Revision History Document Revision A Product Version Workforce Central 6.0 Release Date June 2007

Contents

About This Guide Organization of this guide ........................................................................... 20 Abbreviations and terms .............................................................................. 21 Chapter 1: Introduction Using the tag descriptions ........................................................................... 24 Chapter 2: Workforce Timekeeper XML API Tag Definitions AccessAssignment Tag ............................................................................... 32 AccessProfile Tag ........................................................................................ 43 AccrualBalanceSummary Tag ..................................................................... 49 AccrualCode Tag ......................................................................................... 57 AccrualData Tag .......................................................................................... 60 AccrualMove Tag ........................................................................................ 63 AccrualPatternElement Tag ......................................................................... 67 AccrualProfile Tag ...................................................................................... 68 AdHocLaborAccount Tag ........................................................................... 71 APICallList Tag ........................................................................................... 73 APIOutsideDate Tag ................................................................................... 75 APIPSEEngine Tag ..................................................................................... 76 APIPunchRestrictionOverride Tag .............................................................. 78 APISCGEngine Tag .................................................................................... 84 APIStableDateSpans Tag ............................................................................ 86 APIVolumeDataService Tag ....................................................................... 88 AppendShifts Tag ........................................................................................ 90 ApplicationCalendar Tag ............................................................................. 93 ApplicationCalendarAPIFacade Tag ........................................................... 95 ApproveSignoff Tag .................................................................................... 96 Attribute Tag ............................................................................................. 100

Contents

AuditItem Tag ............................................................................................102 AuditTrail Tag ............................................................................................107 AuthenticationType Tag ............................................................................111 BadgeAssignment Tag ...............................................................................113 BaseWageRate Tag ....................................................................................117 Bid Tag .......................................................................................................120 BidGroup Tag ............................................................................................125 BidGroupItem Tag .....................................................................................132 BidNote Tag ...............................................................................................138 BidRequest Tag ..........................................................................................140 BulkAccruals Tag ......................................................................................150 BulkTotals Tag ...........................................................................................153 CalendarProfile Tag ...................................................................................156 CalendarProfileAPIFacade Tag .................................................................162 CallListEmployee Tag ...............................................................................164 CallListOpenShift Tag ...............................................................................165 CancelDeductions Tag ...............................................................................166 CertificationItem Tag .................................................................................169 CheckAdvice Tag .......................................................................................171 CheckAdviceDetailDeductions Tag ...........................................................177 CheckAdviceDetailDirectDeposit Tag ......................................................179 CheckAdviceDetailGrossPay Tag ..............................................................181 CheckAdviceDetailTaxes Tag ...................................................................184 Comment Tag .............................................................................................186 ConnectToSchedule Tag ............................................................................189 ConnectToScheduleItem Tag .....................................................................191 CoverageDetail Tag ...................................................................................195 CoverageSettings Tag ................................................................................196 CoverageSettingsValue Tag .......................................................................202 CoverShiftStatus Tag .................................................................................204 CurrentUser Tag .........................................................................................206 CustomData Tag ........................................................................................210 CustomDate Tag ........................................................................................212 CustomOperator Tag ..................................................................................214

4

Kronos Incorporated

Contents

DataAccessGroup Tag ............................................................................... 215 DataElementAPIFacade Tag ..................................................................... 222 DataSetAPIFacade Tag ............................................................................. 224 DataSource Tag ......................................................................................... 226 DateTotals Tag .......................................................................................... 228 DeductRule Tag ......................................................................................... 230 DelegateAuthorityTask Tag ...................................................................... 232 DelegateProfile Tag ................................................................................... 237 DeviceGroup Tag ...................................................................................... 243 EarnedAccrual Tag .................................................................................... 246 EffectiveWorkload Tag ............................................................................. 250 EligibleJobs Tag ........................................................................................ 254 EmailAddress Tag ..................................................................................... 257 EmployeeGroupAssign Tag ...................................................................... 259 EmployeeGroupItem Tag .......................................................................... 262 EmployeeGroupProfile Tag ....................................................................... 264 EmployeeMessage Tag .............................................................................. 267 EmployeePreferredZone Tag ..................................................................... 271 EmployeeSummary Tag ............................................................................ 274 EmploymentStatus Tag ............................................................................. 276 Error Tag ................................................................................................... 280 ExpectedHours Tag ................................................................................... 284 FailedXMLTransaction Tag ...................................................................... 286 FPAAllocation Tag .................................................................................... 294 FPARule Tag ............................................................................................. 297 FPARuleVersion Tag ................................................................................ 302 FPATrigger Tag ......................................................................................... 306 From Tag ................................................................................................... 311 FunctionAccessProfile Tag ....................................................................... 313 GDAPAssignment Tag .............................................................................. 316 GDAPAssignmentDefaultSwitch Tag ....................................................... 323 GDAPItem Tag .......................................................................................... 325 GenericEmployeeCalendar Tag ................................................................. 327 GenericEmployeeCalendarAPIFacade Tag ............................................... 333

Workforce Central Developers Toolkit Reference Guide—Timekeeping

5

Contents

GenericManagerCalendar Tag ...................................................................335 GenericManagerCalendarAPIFacade Tag .................................................342 GenieColumn Tag ......................................................................................344 GenieRow Tag ...........................................................................................346 GlsegmentDetail Tag .................................................................................348 GroupMembership Tag ..............................................................................351 Headcount Tag ...........................................................................................353 HeadcountPattern Tag ................................................................................355 HistoricalPayCodeEdit Tag ........................................................................357 HistoricalPayCodeMove Tag .....................................................................366 HistoryDetails Tag .....................................................................................375 Holiday Tag ................................................................................................376 HolidayEditHours Tag ...............................................................................378 HolidayEditWages Tag ..............................................................................381 HomeAccount Tag .....................................................................................384 HoursSummary Tag ...................................................................................386 HoursSummaryService Tag .......................................................................388 HPPDItem Tag ...........................................................................................390 HPPDService Tag ......................................................................................393 HPPDSummary Tag ...................................................................................396 HPPDSummaryService Tag .......................................................................399 HyperFindQuery Tag .................................................................................401 HyperFindResult Tag .................................................................................406 ImportBatchStatus Tag ..............................................................................409 JobAssignment Tag ....................................................................................415 JobAssignmentDetails Tag ........................................................................419 Kronos_WFC Tag ......................................................................................424 KTimeZone Tag .........................................................................................426 LaborAccount Tag .....................................................................................429 LaborAccountEntry Tag ............................................................................432 LaborAccountEntryData Tag .....................................................................435 LaborAccountSet Tag ................................................................................437 LaborAccountSetProfile Tag .....................................................................442 LaborLevelDefinition Tag .........................................................................445

6

Kronos Incorporated

Contents

LaborLevelEntry Tag ................................................................................ 449 LaunchHistory Tag .................................................................................... 455 LicenseType Tag ....................................................................................... 460 LightWeightPerson Tag ............................................................................. 464 LocationId Tag .......................................................................................... 466 LocationProfileSettings Tag ...................................................................... 467 LockedDataCorrection Tag ....................................................................... 473 LogonProfile Tag ....................................................................................... 475 ManagerRoleAvailabilityPatternProfile Tag ............................................. 478 ManagerRoleScheduleGroupProfile Tag .................................................. 481 ManagerRoleSchedulePatternProfile Tag ................................................. 484 ManagerRoleShiftCodeProfile Tag ........................................................... 487 MarkForTotalization Tag .......................................................................... 490 Menu Tag ................................................................................................... 493 MenuItem Tag ........................................................................................... 495 MinimunHoursNoModification Tag ......................................................... 498 NameList Tag ............................................................................................ 501 Names Tag ................................................................................................. 503 NavProfile Tag .......................................................................................... 504 NonCancellingPayCodeEdit Tag ............................................................... 510 Note Tag .................................................................................................... 518 OnCall Tag ................................................................................................ 520 OpenShift Tag ........................................................................................... 522 OpenShiftItem Tag .................................................................................... 523 OpenShiftVolunteer Tag ........................................................................... 524 OptOutStatus Tag ...................................................................................... 530 OptOutStatusList Tag ................................................................................ 532 OrgDirect_IndirectPct Tag ........................................................................ 534 OrgJob Tag ................................................................................................ 535 OrgLocation Tag ....................................................................................... 536 OrgLocationsImport Tag ........................................................................... 541 OrgMapIntegration Tag ............................................................................. 543 OrgSet Tag ................................................................................................. 545 OrgSetEntry Tag ........................................................................................ 550

Workforce Central Developers Toolkit Reference Guide—Timekeeping

7

Contents

OrgSetJob Tag ............................................................................................552 OrgWorkAllocationEntry Tag ...................................................................554 OvertimeApproval Tag ..............................................................................556 PasswordHistory Tag .................................................................................561 PatternElement Tag ....................................................................................562 PayCode Tag ..............................................................................................566 PayCodeEdit Tag .......................................................................................570 PayCodeMove Tag .....................................................................................580 PayCodeProfile Tag ...................................................................................589 PayFromSchedule Tag ...............................................................................592 PayFromScheduleStopEvent Tag ..............................................................595 PayRuleProfile Tag ....................................................................................598 PeriodTotals Tag ........................................................................................601 Permission Tag ...........................................................................................603 Person Tag ..................................................................................................605 PersonAccessAssignment Tag ...................................................................614 Personality Tag ..........................................................................................618 PersonalOvertimeAssignment Tag ............................................................623 PersonalOvertimeLimit Tag .......................................................................628 PersonalOvertimeRule Tag ........................................................................630 PersonAuthenticationType Tag ..................................................................632 PersonCertificationAssign Tag ..................................................................634 PersonCertificationItem Tag ......................................................................637 PersonIdentity Tag .....................................................................................640 PersonInformation Tag ..............................................................................645 PersonLicenseType Tag .............................................................................654 PersonShiftTemplateAssignment Tag ........................................................656 PersonSkillAssign Tag ...............................................................................658 PersonSkillItem Tag ...................................................................................661 PostalAddress Tag ......................................................................................663 PreferenceProfile Tag ................................................................................666 PrimaryLaborAccount Tag ........................................................................669 Procedure Tag ............................................................................................674 ProcedureAction Tag .................................................................................679

8

Kronos Incorporated

Contents

ProcedureContext Tag ............................................................................... 681 ProcedureParameter Tag ........................................................................... 683 ProcedureParameterDefinition Tag ........................................................... 685 ProcedureSet Tag ....................................................................................... 687 ProcedureSetItem Tag ............................................................................... 693 Process Tag ................................................................................................ 695 ProcessorToEmployee Tag ........................................................................ 703 ProcessProfile Tag ..................................................................................... 709 ProcessSchedule Tag ................................................................................. 712 ProcessTask Tag ........................................................................................ 716 ProcessTemplate Tag ................................................................................. 725 ProjectingOvertime Tag ............................................................................ 750 Punch Tag .................................................................................................. 752 PunchStatus Tag ........................................................................................ 764 RBSRule Tag ............................................................................................. 768 RBSRuleVersion Tag ................................................................................ 772 ReportProfile Tag ...................................................................................... 777 Request Tag ............................................................................................... 780 RequestToCover Tag ................................................................................. 784 RequestToCoverItem Tag ......................................................................... 790 ResetAccrual Tag ...................................................................................... 792 Response Tag ............................................................................................. 797 RoleProfileKBO Tag ................................................................................. 799 RuleSetEmployeeAssign Tag .................................................................... 804 SchedGenSettings Tag ............................................................................... 807 SchedGenSettingsValue Tag ..................................................................... 813 SchedRule Tag ........................................................................................... 815 SchedRuleContext Tag .............................................................................. 822 SchedRuleOperator Tag ............................................................................ 824 SchedRuleSet Tag ..................................................................................... 826 SchedRuleSortOrder Tag ........................................................................... 832 SchedRuleTopic Tag ................................................................................. 834 SchedRuleValueType Tag ......................................................................... 836 Schedule Tag ............................................................................................. 838

Workforce Central Developers Toolkit Reference Guide—Timekeeping

9

Contents

ScheduleAccrualAmountEdit Tag .............................................................852 ScheduleAccrualPattern Tag ......................................................................856 ScheduleCostPaycode Tag .........................................................................862 ScheduleCostResult Tag ............................................................................864 ScheduleCostSummary Tag .......................................................................866 ScheduleCoverage Tag ..............................................................................868 ScheduleGroup Tag ....................................................................................871 ScheduleGroupProfile Tag .........................................................................876 ScheduleHours Tag ....................................................................................879 ScheduleHoursAccrualViolation Tag ........................................................885 ScheduleHoursDailyStatus Tag .................................................................886 ScheduleHoursException Tag ....................................................................888 ScheduleHoursStatus Tag ..........................................................................889 ScheduleMarkPosted Tag ..........................................................................892 ScheduleOff Tag ........................................................................................894 SchedulePattern Tag ..................................................................................899 SchedulePayCodeEdit Tag .........................................................................906 SchedulePeriod Tag ...................................................................................914 ScheduleRuleOverride Tag ........................................................................918 ScheduleRuleOverrideDetails Tag .............................................................923 ScheduleShift Tag ......................................................................................926 ScheduleShiftSwap Tag .............................................................................932 ScheduleUnavailable Tag ..........................................................................934 ScheduleZone Tag ......................................................................................940 ServerTime Tag ..........................................................................................943 SettingsParamDefinition Tag .....................................................................945 SettingsParamValue Tag ............................................................................948 SettingsType Tag .......................................................................................950 ShiftBuilder Tag .........................................................................................953 ShiftCode Tag ............................................................................................956 ShiftCountSpan Tag ...................................................................................960 ShiftHistory Tag .........................................................................................962 ShiftSegment Tag .......................................................................................966 ShiftStartTimeBand Tag ............................................................................971

10

Kronos Incorporated

Contents

ShiftTemplateAssignment Tag .................................................................. 976 ShiftTemplateItem Tag .............................................................................. 978 ShiftValidation Tag ................................................................................... 980 Signature Tag ............................................................................................. 983 SignatureItem Tag ..................................................................................... 987 SimplePair Tag .......................................................................................... 988 SimpleValue Tag ....................................................................................... 990 StaffingRequirement Tag .......................................................................... 991 StandardShift Tag ...................................................................................... 992 SuiteProduct Tag ....................................................................................... 994 Supervisor Tag ........................................................................................... 997 SwapShiftEmployees Tag ......................................................................... 998 SwapShiftJobs Tag .................................................................................. 1001 SwitchRoleEngine Tag ............................................................................ 1004 SystemSettings Tag ................................................................................. 1007 TelephoneNumber Tag ............................................................................ 1010 TimeEntry Tag ......................................................................................... 1012 TimeFramePeriod Tag ............................................................................. 1015 TimekeepingException Tag ..................................................................... 1018 Timesheet Tag ......................................................................................... 1022 To Tag ..................................................................................................... 1028 TopicParameterDefinition Tag ................................................................ 1030 TopicParameterValue Tag ....................................................................... 1032 Total Tag ................................................................................................. 1033 TotaledScheduledPayCodeEdit Tag ........................................................ 1037 TotaledScheduledPayCodeEditUneditable Tag ...................................... 1040 TotaledScheduledWorkedDuration Tag .................................................. 1044 TotaledSpan Tag ...................................................................................... 1047 TotalSummary Tag .................................................................................. 1049 Transaction Tag ....................................................................................... 1050 TransferEmployee Tag ............................................................................ 1051 TransferJobSeniorityDate Tag ................................................................. 1054 TreeNodeType Tag .................................................................................. 1057 TypeOverride Tag ................................................................................... 1062

Workforce Central Developers Toolkit Reference Guide—Timekeeping

11

Contents

User Tag ...................................................................................................1064 UserAccount Tag .....................................................................................1067 UserAccountLockout Tag ........................................................................1072 UserAccountStatus Tag ............................................................................1074 VacationBid Tag ......................................................................................1078 VolumeDataItem Tag ...............................................................................1085 WageProfile Tag ......................................................................................1086 WeekDay Tag ..........................................................................................1089 WFCGenie Tag ........................................................................................1091 WfcJob Tag ..............................................................................................1095 WorkedDuration Tag ...............................................................................1100 WorkerType Tag ......................................................................................1108 WorkerTypeElement Tag .........................................................................1112 WorkflowAccessAssignment Tag ............................................................1114 WorkflowTemplateCategory Tag ............................................................1118 WorkRule Tag ..........................................................................................1121 WorkRuleProfile Tag ...............................................................................1124 WorkWeek Tag ........................................................................................1127 WorkWeekAssignments Tag ...................................................................1133 WorkWeekDay Tag .................................................................................1136 WSAAccrualCode Tag ............................................................................1140 WSAAccrualDetail Tag ...........................................................................1142 WSAAccrualDetailColumnSet Tag .........................................................1147 WSAAccrualPolicy Tag ...........................................................................1151 WSAAccrualPolicyGrant Tag ..................................................................1161 WSAAccrualPolicyLimit Tag ..................................................................1163 WSAAccrualPolicyPayCode Tag ............................................................1165 WSAAccrualPolicyTakingLimit Tag ......................................................1166 WSAAccrualProfile Tag ..........................................................................1168 WSAAccrualProfilePolicy Tag ................................................................1172 WSAAccrualQualifier Tag ......................................................................1174 WSAAPICombination Tag ......................................................................1177 WSAAPICombinationComponent Tag ....................................................1180 WSAAPICombinationRule Tag ...............................................................1183

12

Kronos Incorporated

Contents

WSAAPICombinationTowardOT Tag .................................................... 1187 WSAAssignmentRule Tag ...................................................................... 1190 WSAAutoBreakPlacement Tag ............................................................... 1196 WSAAvailabilityPatternDAP Tag ........................................................... 1199 WSAAvailabilityPatternProfileItem Tag ................................................ 1202 WSABonusDeductRule Tag .................................................................... 1204 WSABreakRule Tag ................................................................................ 1216 WSABreakTime Tag ............................................................................... 1223 WSACalendarProfile Tag ........................................................................ 1226 WSACallInRule Tag ............................................................................... 1228 WSACfgAccrualCode Tag ...................................................................... 1235 WSACfgContactType Tag ...................................................................... 1239 WSACfgContactTypeList Tag ................................................................ 1242 WSACfgCustomData Tag ....................................................................... 1245 WSACfgCustomDataList Tag ................................................................. 1247 WSACFGDistributionAssignment Tag ................................................... 1250 WSACFGExtProcessorComponent Tag ................................................. 1253 WSACFGOvertimeComponent Tag ....................................................... 1255 WSACFGPaycodeAssignment Tag ......................................................... 1257 WSACFGPaycodeDistribution Tag ........................................................ 1259 WSACFGZoneComponent Tag .............................................................. 1262 WSAColumnDefinition Tag .................................................................... 1264 WSAColumnDefinitionDataType Tag .................................................... 1267 WSAColumnDetail Tag .......................................................................... 1270 WSACombinationRule Tag ..................................................................... 1276 WSACombinedPayCodeRule Tag .......................................................... 1278 WSAComment Tag ................................................................................. 1282 WSACommentType Tag ......................................................................... 1286 WSAContributingPayCodeRule Tag ....................................................... 1288 WSAContributingShiftRule Tag ............................................................. 1291 WSACoreHoursRule Tag ........................................................................ 1296 WSACreditCalculator Tag ...................................................................... 1302 WSACriteriaSet Tag ................................................................................ 1310 WSACustomDate Tag ............................................................................. 1313

Workforce Central Developers Toolkit Reference Guide—Timekeeping

13

Contents

WSACustomDateType Tag .....................................................................1316 WSACustomUrl Tag ................................................................................1318 WSACustomUrlProfile Tag .....................................................................1321 WSADateFinder Tag ................................................................................1325 WSADatePattern Tag ...............................................................................1328 WSADayMonthSpan Tag ........................................................................1332 WSADaysOfWeek Tag ............................................................................1335 WSADetail Tag ........................................................................................1339 WSADetailColumnSet Tag ......................................................................1343 WSADisplayOrder Tag ............................................................................1347 WSADisplayProfile Tag ..........................................................................1350 WSADisplayProfileWorkforceGenieProfile Tag ....................................1363 WSADispOrdOptionalRule Tag ..............................................................1365 WSADPLaborLevelDefinition Tag .........................................................1367 WSADPPayCode Tag ..............................................................................1369 WSADPTimePeriod Tag ..........................................................................1371 WSAEffectivePayRule Tag .....................................................................1373 WSAEffectiveWorkRule Tag ..................................................................1381 WSAEligibilityDeterminer Tag ...............................................................1386 WSAExceptionRule Tag ..........................................................................1391 WSAExceptionType Tag .........................................................................1396 WSAFixedRule Tag .................................................................................1398 WSAFunctionAccessProfile Tag .............................................................1401 WSAGenie Tag ........................................................................................1405 WSAGrant Tag ........................................................................................1408 WSAHoliday Tag .....................................................................................1415 WSAHolidayCreditRule Tag ...................................................................1420 WSAHolidayDate Tag .............................................................................1425 WSAHyperfindQuery Tag .......................................................................1427 WSAInitialGrant Tag ...............................................................................1430 WSAInterval Tag .....................................................................................1432 WSAIntervalRoundRule Tag ...................................................................1434 WSALaborLevel Tag ...............................................................................1438 WSALaborLevelEntry Tag ......................................................................1442

14

Kronos Incorporated

Contents

WSALeaveCaseDetail Tag ...................................................................... 1446 WSALeaveCaseDetailColumnSet Tag .................................................... 1450 WSALimit Tag ........................................................................................ 1454 WSALogonProfile Tag ............................................................................ 1459 WSAMainTab Tag .................................................................................. 1466 WSAMajorityRule Tag ........................................................................... 1468 WSANavbarCategory Tag ....................................................................... 1472 WSAOptionalRule Tag ........................................................................... 1474 WSAOrganizationType Tag .................................................................... 1476 WSAOverridePayCode Tag .................................................................... 1480 WSAOvertimeCombination Tag ............................................................. 1482 WSAOvertimeRule Tag .......................................................................... 1485 WSAPatternTemplateDAP Tag ............................................................... 1492 WSAPatternTemplateProfileItem Tag .................................................... 1495 WSAPayCode Tag ................................................................................... 1497 WSAPayCodeDAP Tag ........................................................................... 1504 WSAPayCodeDistribution Tag ............................................................... 1507 WSAPayCodeProfileItem Tag ................................................................ 1511 WSAPayDistributionAssociation Tag ..................................................... 1513 WSAPayPeriod Tag ................................................................................. 1516 WSAPayRule Tag ................................................................................... 1519 WSAPayRuleHoliday Tag ....................................................................... 1522 WSAPermission Tag ............................................................................... 1524 WSAProbationPeriod Tag ....................................................................... 1527 WSAProbationQualifier Tag ................................................................... 1531 WSAProcessingOrderRule Tag ............................................................... 1534 WSAPunchRoundRule Tag ..................................................................... 1537 WSAQuickFind Tag ................................................................................ 1551 WSAReportDAP Tag .............................................................................. 1555 WSAReportProfileItem Tag .................................................................... 1558 WSARollup Tag ...................................................................................... 1560 WSARollupColumnSet Tag .................................................................... 1564 WSAScheduleAssistant Tag .................................................................... 1568 WSAScheduleAssistantColumnSet Tag .................................................. 1572

Workforce Central Developers Toolkit Reference Guide—Timekeeping

15

Contents

WSAScheduleAssistantTab Tag ..............................................................1576 WSAScheduleDeviationRule Tag ............................................................1578 WSAScheduledHoursType Tag ...............................................................1582 WSAScheduleEditor Tag .........................................................................1585 WSAScheduleEditorColumnSet Tag .......................................................1590 WSAScheduleGroupDAP Tag .................................................................1594 WSAScheduleGroupDetail Tag ...............................................................1598 WSAScheduleGroupDetailColumnSet Tag .............................................1603 WSAScheduleGroupProfileItem Tag ......................................................1608 WSAScheduleGroupRollup Tag ..............................................................1610 WSAScheduleGroupRollupColumnSet Tag ............................................1615 WSASchedulePeriod Tag ........................................................................1620 WSASchedulePlanner Tag .......................................................................1622 WSASchedulePlannerColumnSet Tag .....................................................1627 WSASequencedItem Tag .........................................................................1631 WSASequencerRule Tag .........................................................................1633 WSAShiftGuarantee Tag .........................................................................1636 WSAShiftLength Tag ..............................................................................1641 WSAShiftLengthExclusion Tag ..............................................................1643 WSAShiftTemplateDAP Tag ...................................................................1644 WSAShiftTemplateProfileItem Tag ........................................................1647 WSASignOffRestriction Tag ...................................................................1648 WSASubsequentGrant Tag ......................................................................1652 WSATimePeriod Tag ...............................................................................1654 WSATkTerminalRule Tag .......................................................................1656 WSATreeType Tag ..................................................................................1666 WSAULLE Tag .......................................................................................1669 WSAWageAdjustment Tag ......................................................................1672 WSAWageProfile Tag .............................................................................1675 WSAWageProfileLaborLevelLinkage Tag ..............................................1679 WSAWageProfilePayCode Tag ...............................................................1681 WSAWfgColumnSet Tag ........................................................................1683 WSAWorkforceGenieProfile Tag ............................................................1686 WSAWorkHistoryQualifierRule Tag ......................................................1690

16

Kronos Incorporated

Contents

WSAWorkloadPlannerProfile Tag .......................................................... 1694 WSAWorkRule Tag ................................................................................ 1696 WSAWorkRuleDAP Tag ........................................................................ 1699 WSAWorkRuleGeneral Tag .................................................................... 1702 WSAWorkRulePCDistr Tag ................................................................... 1705 WSAWorkRuleProfileItem Tag .............................................................. 1708 WSAZone Tag ......................................................................................... 1710 WSAZoneCombinationRule Tag ............................................................ 1723 WSAZoneCombinationSpecificationRule Tag ....................................... 1726 WSAZoneCombinationZoneRule Tag .................................................... 1728 WSAZoneRule Tag ................................................................................. 1730 WSAZoneRuleHoliday Tag .................................................................... 1733 WSAZoneRuleLimit Tag ........................................................................ 1735 WTDEmployeeAssignment Tag ............................................................. 1737 WTDGlobal Tag ...................................................................................... 1742 WTDRule Tag ......................................................................................... 1749 WTKEmployee Tag ................................................................................. 1762 Index

Workforce Central Developers Toolkit Reference Guide—Timekeeping

17

Contents

18

Kronos Incorporated

About This Guide

This reference guide defines and describes the Kronos XML API for Workforce Timekeeper. This preface contains the following sections: • • “Organization of this guide” on page 20 “Abbreviations and terms” on page 21

About This Guide

Organization of this guide
This reference guide contains the following information: • • Chapter 1, “Introduction,” on page 23 provides an overview on how to use the reference information. Chapter 2, “Workforce Timekeeper XML API Tag Definitions,” on page 31 contains detailed information about each XML tag.

Users of this guide
This reference guide is for programmers, system integrators, and Web developers who need to understand the Kronos XML interface. Readers should have knowledge of the following software technologies: • • • • Tag-based markup languages such as HTML and XML. Data transfer protocols such as TCP/IP; HTTP and HTTPS; and SOAP. Request-response transactions and sessions. The Workforce Central user interface.

20

Kronos Incorporated

Abbreviations and terms

Abbreviations and terms
The following abbreviations and terms are used in this reference guide:
Abbreviation API DTK HTML HTTP HTTPS RDBMS TCP/IP URL XML Term Application Program Interface Developer’s Toolkit Hypertext Markup Language Hypertext Transfer Protocol Hypertext Transfer Protocol Secure Relational Database Management System Transmission Control Protocol/Internet Protocol Universal Resource Locator Extensible Markup Language

Workforce Central Developers Toolkit Reference Guide—Timekeeping

21

About This Guide

22

Kronos Incorporated

Chapter 1

Introduction

This reference guide is for programmers, system integrators, and Web developers who need to understand the Kronos® Workforce Central® XML interface. Readers should have knowledge of the following software technologies: • • • • Tag-based markup languages such as HTML and XML. Data transfer protocols such as TCP/IP; HTTP and HTTPS; and SOAP. Request-response transactions and sessions. The Workforce Central user interface.

Chapter 1

Introduction

Using the tag descriptions
The XML tags are described using standard formats and conventions, described in this section. XML tag name The XML tag name includes the technical name, or how the tag is referenced in code, and the non-technical name, or how the tag is referenced in the XML Import and Export Programmer Guides and the user interface. Example technical name: CheckAdvice Example non-technical name: Earnings History XML tag description The XML tag description gives an overview of what the XML tag is used for, and specifies whether it is used by another XML tag. The description also includes tag level validations, if they are not standard validations. For example, standard date validation is not mentioned, but if the date must fall during the last week of a month, the information is included. Function access control point The function access control point identifies the functional area that a user must have access to in order to use the XML tags within that functional area. For example, for the Punch tag, the function access control point is API.Timecard. This means that a user must have access to Timecard in order to use this tag. To validate whether a user has the appropriate access rights, complete these steps in Workforce Central Setup. Contact your system administrator if you do not have access to Workforce Central Setup: 1. Click Access Profiles. 2. Click Function Access Profiles from the list on the left. 3. Click the function access profile associated with the user whose access rights you are checking; for example, IS. The Edit Function Access Profile window opens.

24

Kronos Incorporated

Using the tag descriptions

4. Expand the API and API Beans entries to see the function access control points. 5. Find the function access control point you are interested in (for example, Timecard) and verify that it is set to Allowed for the type of operation the user needs to perform. If it is set to Allowed, the user has access rights to all the tags in the reference chapter of this document whose Function Access Control Point is specified as API.Timecard; for example, the Punch tag. Note: In the GUI, the function access control point name may reflect the control point’s association with Java beans. Thus, the GUI may refer to API.Timecard as Timecard Beans. Versions The “introduced” version specifies the Workforce Central version number when the tag was introduced. If the tag was modified since it was introduced, the version when it was last changed is specified. If it has been modified in this release and you are already using this tag, check your XML code to make sure it is up-to-date. If the tag has been marked for deprecation, this information is specified. A deprecated item will be removed from the API in the next major release, or

after one year, whichever date is later.
Syntax This section describes the abstract syntax for the XML tag. XML tag names, action names, action parameters, and property names are case sensitive. Example: Request --> <Request Action = Actions Parameters > Properties </Request> Actions --> "AddComment" | "AddOnly" | "Delete" Parameters --> [ AccrualOverride = Boolean ]

Workforce Central Developers Toolkit Reference Guide—Timekeeping

25

Chapter 1

Introduction

[ allowAdHoc = Boolean ] [ EchoData = Boolean ] Properties --> <PayCodeMove AmountInTimeOrCurrency = String [ CommentText = String ] Date = Date ( EnteredOnDate = Date ) ( EnteredOnTime = Time ) [ FromLaborAccountName = String ] FromPayCodeName = String [ LaborAccountName = String ] [ ManagerName = String ] OrgJobId = String [ OrgJobName = String ] PayCodeName = String > ( <Comments> <Comment>* </Comments> ) <Employee> <CurrentUser> | <PersonIdentity> </Employee> </PayCodeMove> Conventions The syntax conventions are described in the following table.
Syntax Description Variable, which must be replaced by a value in the XML code. Optional elements Example CommentText = String where String tells you to add comments here. [CommentText = String] where [] mean that the CommentText property is not required in the tag. Output only properties (AccrualCodeId = Long) identifies AccrualCodeId as a property that is only used for output.

monospace italic
Brackets [ ]

Parenthesis ()

26

Kronos Incorporated

Using the tag descriptions

Syntax

Description Mutually exclusive options

Example

vertical pipe | asterisk * plus sign +

"AddComment" | "AddOnly" | "Delete"
Choose one of these actions.

Array of zero or more occurrences <Comment>* An array of comments can be specified. Array of one or more occurrences

Parts of a syntax statement The five optional parts of a syntax statement are: • Request—An XML statement can be actionable or non-actionable. If it is actionable, the statement is contained within a Request tag. If it is not actionable, it must be used within an actionable tag. Actions—If the syntax statement contains actions, an Actions part identifies all the actions supported by the XML tag. Parameters—If any actions use parameters, a Parameters part identifies them. Properties—The properties part of the syntax statement identifies all properties that are available for a tag, including required and optional properties. Contained API tags—If the syntax of the primary XML tag requires another XML tag, which is not assigned to any property within the primary tag, a container API tag is used to specify a placeholder for the other tag.

• • •

Action descriptions The action description includes the following information: • The action name includes the technical name, or how the action is referenced in code; and the non-technical name, or how the action is referenced in the XML Import and Export Programmer Guides and the user interface.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

27

Chapter 1

Introduction

• • • • • • •

The description tells what the action does, including validation rules. The return value type identifies whether the action returns any data, and if so, the data type of the returned value. The required properties identifies all properties that must be specified when this action is used. The optional properties identifies the properties that can optionally be specified for the action. The access control point name identifies the type of access available for the tag. The Action Parameters table specifies the names and descriptions of all parameters associated with an action. Not all actions have action parameters. The “introduced” version specifies the Workforce Central version number when the action was introduced. If the action was modified since it was introduced, the version when it was last changed is specified. If it has been modified in this release and you are already using this action, check your XML code to make sure it is up-to-date. If the action has been marked for deprecation, this information is specified. A deprecated item will be removed from the API in the next major release, or

after one year, whichever date is later.
Property descriptions The property description describes all of the properties specified for an XML tag. • The property name includes the technical name, or how the property is referenced in code; and the non-technical name, or how the property is referenced in the XML Import and Export Programmer Guides and the user interface. The description describes each property, including validation rules. Allowed Values identifies a predefined set of allowable values for the property. The Default Value item identifies a default value, where appropriate. The Contributes to Uniqueness item identifies properties that are required as part of the unique identification of an instance of a tag.

• • • •

28

Kronos Incorporated

Using the tag descriptions

Groups of Mutually Exclusive Properties specifies if any of the properties in a tag are mutually exclusive. For example, in the EarnedAccruals tag, you can specify the AmountInTime or the AmountInCurrency property, but not both. The “introduced” version specifies the Workforce Central version number when the property was introduced. If the property was modified since it was introduced, the version when it was last changed is specified. If it has been modified in this release and you are already using this property, check your XML code to make sure it is up-to-date. If the property has been marked for deprecation, this information is specified. A deprecated item will be removed from the API in the next major release,

or after one year, whichever date is later.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

29

Chapter 1

Introduction

30

Kronos Incorporated

Chapter 2

Workforce Timekeeper XML API Tag Definitions

This chapter lists, in alphabetic order, the XML API Tag descriptions

Chapter 2

Workforce Timekeeper XML API Tag Definitions

AccessAssignment Tag Access Rights
The AccessAssignment tag enables you to specify access rights for a person. Access rights can also be displayed and edited online in the People Editor. The user of this tag must have access rights to view or edit the specified data. Used by: PersonInformation Dependency: Access to this information is controlled through the Role View access control point. The user must have view or add access rights to retrieve or modify the information in this tag. Function Access Control Point: API.Person Introduced in v4; last changed in v5.2

Syntax
Properties→ <AccessAssignment [AvailabilityPatternName = String] [TransferEmployeeFlag = Boolean] [DelegateProfileName = String] [PreferenceProfileName = String] [ManagerAccessSetName = String] [AccessProfileName = String] [ProfessionalTransferSetName = String] [ManagerTransferSetName = String] [SchedulePatternName = String] [ManagerPayCodeName = String] [ManagerViewPayCodeName = String] [ProfessionalPayCodeName = String] [ReportName = String] [GroupScheduleName = String] [ShiftCodeName = String] [TimeEntryTypeName = String] [ProfessionalWorkRuleName = String] [ManagerWorkRuleName = String] > </AccessAssignment>

32

Kronos Incorporated

AccessAssignment Tag

Property Descriptions
AccessProfileName

Function access profile
The name of the person's function access profile. The function access profile contains a set of permissions and restrictions that determine which components users can access and the types of functions they can perform. For information about function access profiles and related concepts, see the online help. The following predefined data values are available: • • • • • • &DEFAULT &OTHER_MANAGER &PAYROLL_MANAGER &IS &TIMESTAMP_EMPLOYEE &WORKFORCE_EMPLOYEE

Type: String Optional Maximum length: 50 characters Default value: Specified in the Access Profile Editor in Timekeeping Setup Introduced in v4; last changed in v5.1 AvailabilityPatternName

Availability template profile
The name of the availability template profile that an individual can use when in a manager's role. An availability template is a series of availability settings for a recurring time period that a manager can assign to multiple employees and reuse as needed. An availability template profile is a group of availability templates. Type: String Optional Maximum length: 30 characters

Workforce Central Developers Toolkit Reference Guide—Timekeeping

33

Chapter 2

Workforce Timekeeper XML API Tag Definitions

You can find values in the Timekeeping user interface. Default value: The Empty Data Access Profile Introduced in v5.0; last changed in v5.1 DelegateProfileName

Delegate profile name
Delegate Profile contains the list of people to whom the user with that profile may delegate his/her authority. Type: String Optional Sample values: Empty Profile Default value: &EMPTY Introduced in v5.2 GroupScheduleName

Schedule group profile
Contains the name of a manager's schedule group profile. A schedule group is a set of employees who work the same shifts, and the schedule group profile is a set of schedule groups. The following predefined data values are available: • • &ALL_SCHEDULE_PATTERNS and &EMPTY_PROFILE for all schedules &ALL_GROUP_SCHEDULES and &EMPTY for all group schedules

Type: String Optional Maximum length: 50 characters Dependency: Only specify for a person who has a manager's license Default value: The Empty Data Access Profile

34

Kronos Incorporated

AccessAssignment Tag

Introduced in v5.0; last changed in v5.1 ManagerAccessSetName

Employee group profile
The name of the labor level set that is the manager's employee group when an individual is in a manager role. This gives the manager access to the records of those individuals whose primary accounts are in that labor level set. The following predefined data values are available: • • &ALL_LABOR_ACCOUNTS &EMPTY

Type: String Optional Maximum length: 30 characters Must have a labor account set type of Employee Groups (Manager) or All Sets (Both Manager and Transfer) Introduced in v4; last changed in v5.1 ManagerPayCodeName

Pay codes Edit profile - manager
The name of the pay code profile that applies to an individual when in a manager role. A pay code profile identifies those pay codes that the manager can select for editing. The following predefined data values are available: • • &ALL_PAY_CODES &EMPTY

Type: String Optional Maximum length: 50 characters Dependency: Only specify for a person who has a manager's license. Introduced in v4; last changed in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

35

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ManagerTransferSetName

Labor level transfer set - manager
The name of the labor level transfer set that applies to an individual when in a manager role. A labor level transfer set is a group of labor level entries that a manager or employee can use to transfer time or money. The following predefined data values are available: • • • Type: String Optional Maximum length: 30 characters Must be identified as a labor account set and have a Type of Employee Groups (Manager) or All Sets (Both Manager and Transfer) Dependency: Only specify for a person who has a manager's license. Introduced in v4; last changed in v5.1 ManagerViewPayCodeName &ALL_LABOR_ACCOUNTS &EMPTY

Pay codes View profile - manager
The name of the pay code profile that applies to an individual when in a manager role. A pay code profile identifies those pay codes that the manager can select for viewing. The following predefined data values are available: • • &ALL_PAY_CODES &EMPTY

Type: String Optional Maximum length: 50 characters Dependency: Only specify for a person who has a manager's license.

36

Kronos Incorporated

AccessAssignment Tag

Introduced in v5.2 ManagerWorkRuleName

Work rule profile - manager
The name of the work rule profile that applies to an individual in a manager role. A work rule profile is a set of rules that determines how employee hours accrue (for example, details about how punches round, what types of overtime can be earned, which pay codes hold what type of hours, and policies for meals and breaks). The following predefined data values are available: • • &ALL_WORK_RULES &EMPTY

Type: String Optional Maximum length: 30 characters Dependency: Only specify for a person who has a manager's license. Introduced in v4; last changed in v5.1 PreferenceProfileName

Display profile
The name of the display profile for the person. The display profile identifies the information that is displayed to a user; for example, which items appear on the navigation bar, or how time is displayed in the interface. Type: String Optional Maximum length: 30 characters Default value: &DEFAULT_PREFERENCE Enumerated value: &DEFAULT_PREFERENCE, &SUPER_USER_PREFERENCE, Monday Manager, Tuesday Manager, Friday Manager, Timekeeper, Scheduler, Professional Employees

Workforce Central Developers Toolkit Reference Guide—Timekeeping

37

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v4; last changed in v5.0 ProfessionalPayCodeName

Pay codes profile - employee
The name of the pay code profile that applies to an individual when in an employee role. A pay code profile identifies those pay codes that the employee can select. The following predefined data values are available: • • &ALL_PAY_CODES &EMPTY

Type: String Optional Maximum length: 30 characters Dependency: Only specify for an employee who has a user account user. Introduced in v4; last changed in v5.1 ProfessionalTransferSetName

Labor level transfer set - employee
The name of the labor level transfer set that applies to an individual when in an he name of the labor level transfer set that applies to an individual when in an employee role. A labor level transfer set is a group of labor level entries that a manager or employee can use to transfer time or money. The following predefined data values are available: • • &ALL_LABOR_ACCOUNTS &EMPTY

Type: String Optional Maximum length: 30 characters Dependency: The specified person must have a Type of Employee Groups (Manager) or All Sets (Both Manager and Transfer)

38

Kronos Incorporated

AccessAssignment Tag

Dependency: Only specify for an employee who has a user account. Introduced in v4; last changed in v5.1 ProfessionalWorkRuleName

Work rule profile - employee
The name of the work rule profile that applies to an individual in an employee role. A work rule profile is a set of rules that determines how employee hours accrue (for example, details about how punches round, what types of overtime can be earned, which pay codes hold what type of hours, and policies for meals and breaks). The following predefined data values are available: • • &ALL_WORK_RULES &EMPTY

Type: String Optional Maximum length: 30 characters Dependency: Only specify for an employee who has a user account user. Introduced in v4; last changed in v5.1 ReportName

Reports profile
Contains the name of the report profile that applies to an individual when in a manager role. A reports profile defines which reports the manager can generate or view. The following predefined data values are available: • • &ALL_REPORTS &EMPTY

Type: String Optional Maximum length: 30 characters

Workforce Central Developers Toolkit Reference Guide—Timekeeping

39

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Dependency: Only specify for a person who has a manager license. Introduced in v4; last changed in v5.1 SchedulePatternName

Pattern template profile
Contains the name of a manager's pattern template profile. Pattern templates contain a series of shifts that managers can assign to multiple employees. This pattern template profile identifies those pattern templates that the individual can select when in a manager's role. The following predefined data values are available: • • &ALL_SCHEDULE_PATTERNS &EMPTY

Type: String Optional Maximum length: 50 characters Dependency: Only specify for a person who has a manager license. You can find values in Setup Application. Default value: The Empty Data Access Profile Introduced in v5.0; last changed in v5.1 ShiftCodeName

Shift template profile
The name of the shift template profile that an individual can use when in a manager's role. A shift template is a shift with all its segments that a manager can assign to multiple employees and reuse as needed, and a shift template profile is a group of shift templates. The following predefined data values are available: • • &ALL_SHIFT_CODES &EMPTY_PROFILE

Type: String

40

Kronos Incorporated

AccessAssignment Tag

Optional Maximum length: 50 characters Dependency: Only specify for a person who has a manager license Default value: The Empty Data Access Profile. Introduced in v5.0; last changed in v5.1 TimeEntryTypeName

Time entry method
Indicates the method that the person uses for entering time. Specify one of the following numbers to represent the data value: • • • • 1 for Timestamp 2 for Timestamp and Hourly View 3 for Hourly View 4 for Project View

Type: String Optional Maximum length: 1 character Enumerated value: 1, 2, 3, 4 Introduced in v4; last changed in v5.1 TransferEmployeeFlag

Can see transferred employees
Indicates whether the user can view data for employees who have transferred into work labor accounts that match the primary accounts to which the user has access. TransferEmployeeFlag can have the following values: • • False, if the user cannot see employees who have transferred in True, if the user can see employees who have transferred in

Type: Boolean

Workforce Central Developers Toolkit Reference Guide—Timekeeping

41

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Enumerated value: True, False Introduced in v4

42

Kronos Incorporated

AccessProfile Tag

AccessProfile Tag Access Profile
The AccessProfile tag provides information about access controls. Use it to check a specific access control prior to attempting to perform an action, such as edit. Access profiles are created in Setup and are assigned to people in the online People Editor. The tag provides the following types of information: • • • Access Control Points identify the types of access that can be made available; for example, whether access can be made available for HomeLaborAccount. Actions identify what a user can do with data; for example, edit. Suite Products identify components of the system that can be made available; for example, DCM.

Function Access Control Point: API.AccessProfile Introduced in v4; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "IsPermitted" | "Load" | "LoadAllAccessControlPointNames" | "LoadAllActionNames" | "LoadAllowedPermissions" | "LoadAllSuiteProductNames" Parameters→ IsPermitted→ AccessControlPointName = String ActionName = String [PersonNumber = String]

Workforce Central Developers Toolkit Reference Guide—Timekeeping

43

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SuiteProductName = String Properties→ <AccessProfile AccessProfileName = String (Description = String) > (<Permission> <Permission>* </Permission>) (<SimpleValue> <SimpleValue>* </SimpleValue>) </AccessProfile>

Action Descriptions
IsPermitted Returns a value that denotes whether the specified combination of person, access control point, action, and suite product has access rights. Returns either True or False Return Value Type: SimpleValue tag Access Control Point Name: View Introduced in v4

44

Kronos Incorporated

AccessProfile Tag

Action Parameters Parameter Name Description Additional information

AccessControlPointNam The name of the access control point. Introduced in v4 e Required This name must be listed in the Access Control Point table. Otherwise, the system returns False. ActionName The name of the action. Required This name must be identified in the names in the Permission Type table. Otherwise, the system returns False. The person number used to determine whose access profile to use. Optional The person number to check the access against. It must be the access profile of this person that the permission is checked against. Default value: The currently logged on user. The suite product being checked. Required This name must be listed in the Suite Product table. Otherwise, the system returns False. Introduced in v4

PersonNumber

Introduced in v4

SuiteProductName

Introduced in v4

Load Returns the access profile name and description for the specified access profile. If the access profile name is specified, it must exist in the system. If the access profile name is not specified, the default access profile is used. Return Value Type: AccessProfile tag Optional Properties: AccessProfileName Access Control Point Name: View

Workforce Central Developers Toolkit Reference Guide—Timekeeping

45

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v4; last changed in v5.0 LoadAllAccessControlPointNames Returns all access control points. Return Value Type: Zero or more SimpleValue tags Access Control Point Name: View Introduced in v4 LoadAllActionNames Returns all action names. Return Value Type: Zero or more SimpleValue tags Access Control Point Name: View Introduced in v4 LoadAllowedPermissions Returns all permissions allowed for the specified access profile. Either the specified AccessProfileName or the default AccessProfile must exist. Return Value Type: Zero or more Permission tags Required Properties: None Access Control Point Name: View Introduced in v4 LoadAllSuiteProductNames Returns all suite product names. Return Value Type: Zero or more SimpleValue tags Required Properties: None Access Control Point Name: View Introduced in v4

Property Descriptions
AccessProfileName

Access profile name

46

Kronos Incorporated

AccessProfile Tag

The name of the person's function access profile. The function access profile determines the components that users can access and the types of functions that users can perform, based on their assigned roles. For example, access profiles for Managers can include permission to edit schedules and timecards. The same profile can be assigned to a group of similar users, such as managers in the same department. The system administrator creates the access profiles in Setup. Refer to the System Administrator's GuideTimekeeping for an explanation of the roles. The following predefined data values are available: • • • • • • &OTHER_MANAGER &PAYROLL_MANAGER &IS &TIMESTAMP_EMPLOYEE &WORKFORCE_EMPLOYEE &DEFAULT

Type: String Optional, Key Maximum length: 50 characters Default value: As specified in the Access Profile editor of the Setup Introduced in v4; last changed in v5.0 Description

Description
Describes the access profile. Type: String Output Only Maximum length: 250 characters Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

47

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Permission

Permission
The permissions for the specified access profile are returned in this property. You do not need to specify this property in the request. Type: Zero or more Permission tags Output only Returned in the response only. Not part of the AccessProfile tag. Introduced in v5.2 SimpleValue

Simple value
Information for this property is returned in the response; you do not specify this property in the request. Type: Zero or more SimpleValue tags Output only SimpleValue object is in the response. Not part of the request or the AccessProfile bean Introduced in v5.2

48

Kronos Incorporated

AccrualBalanceSummary Tag

AccrualBalanceSummary Tag Accrual Balance for a Person
The AccrualBalanceSummary tag returns data about an accrual balance for one person. Used by: AccrualData, EmployeeSummary Function Access Control Point: API.Accruals Introduced in v4; last changed in v5.1

Syntax
Properties→ <AccrualBalanceSummary (AccrualCodeId = Long) (AccrualCodeName = String) (HoursPerDay = TimeDuration) (ProbationaryBalanceInCurrency = Currency) (ProbationaryBalanceInTime = TimeDuration) (ProjectedBalanceInCurrency = Currency) (ProjectedBalanceInTime = TimeDuration) (ProjectedDate = Date) (ProjectedGrantAmountInCurrency = Currency) (ProjectedGrantAmountInTime = TimeDuration) (ProjectedProbationaryBalanceInCurrency = Currency) (ProjectedProbationaryBalanceInTime = TimeDuration) (ProjectedTakingAmountInCurrency = Currency) (ProjectedTakingAmountInTime = TimeDuration) (ProjectedVestedBalanceInCurrency = Currency) (ProjectedVestedBalanceInTime = TimeDuration) (AccrualType = Long) (EncumberedBalanceInCurrency = Currency) (VestedBalanceInCurrency = Currency) (EncumberedBalanceInTime = TimeDuration) (VestedBalanceInTime = TimeDuration) > </AccrualBalanceSummary>

Property Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

49

Chapter 2

Workforce Timekeeper XML API Tag Definitions

AccrualCodeId

Accrual code Id
A unique identifier for the accrual code. Type: Long Output Only Introduced in v4 AccrualCodeName

Accrual code name
A named account containing the category in which time or money accrues, such as sick, personal, or vacation. Type: String Output Only Sample values: Vacation, Sick Introduced in v4; last changed in v5.1 AccrualType

Type of accrual
The type identifier displayed for an accrual: 1 for hours, 2 for days, 3 for currency. Type: Long Output Only Enumerated value: 1, 2, 3 Introduced in v4 EncumberedBalanceInCurrency

Vested balance, in currency
Amount of money vested, minus any future scheduled takings.

50

Kronos Incorporated

AccrualBalanceSummary Tag

Type: Currency Output Only Contains a value if the accrual is a monetary type Introduced in v4 EncumberedBalanceInTime

Vested balance, in time
Amount of time vested, minus any future scheduled takings. Type: TimeDuration Output Only Contains a value if the accrual is a time type Introduced in v4 HoursPerDay

Hours per day
Number of hours in an accrual day. Type: TimeDuration Output Only Introduced in v4; last changed in v5.1 ProbationaryBalanceInCurrency

Probationary balance, in currency
Amount of money earned, but not taken because the employee is within the probation period. A probationary amount is one that cannot be taken or paid out. A balance that is given to a person for a probationary period can be transferred as a vested amount once the person has worked through the probationary period. Type: Currency Output Only Contains a value if the accrual is a monetary type Introduced in v4; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

51

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ProbationaryBalanceInTime

Probationary balance, in time
Amount of time earned, but not taken because the employee is within the probation period. A probationary amount is one that cannot be taken or paid out. A balance that is given to a person for a probationary period can be transferred as a vested amount once the person has worked through the probationary period. Type: TimeDuration Output Only Contains a value if the accrual is a time type Introduced in v4; last changed in v5.1 ProjectedBalanceInCurrency

Projected balance, in currency
The current balance minus all projected takings and plus all projected credits up through the furthest projected taking date. This balance includes any scheduled resets. Type: Currency Output Only Contains a value if the accrual type is currency Introduced in v4; last changed in v5.1; deprecated in v5.0 ProjectedBalanceInTime

Projected balance, in time
The current balance minus all projected takings and plus all projected credits up through the furthest projected taking date. This balance includes any scheduled resets. Type: TimeDuration Output Only Contains a value if the accrual type represents a time Introduced in v4; last changed in v5.1; deprecated in v5.0

52

Kronos Incorporated

AccrualBalanceSummary Tag

ProjectedDate

Projected date
The date used in determining the projected balance. Type: Date Output Only Introduced in v4; last changed in v5.1 ProjectedGrantAmountInCurrency

Projected grant amount, in currency
The amount of money scheduled for future grants between the selected date and the furthest projected grant date. Type: Currency Output Only Contains a value if the accrual is a monetary type Introduced in v4; last changed in v5.1 ProjectedGrantAmountInTime

Projected grant amount, in time
The amount of time scheduled for future grants between the selected date and the furthest projected grant date. Type: TimeDuration Output Only Contains a value if the accrual is a time type Introduced in v4; last changed in v5.1 ProjectedProbationaryBalanceInCurrency

Projected probationary balance, in currency
The projected probationary balance expressed as an amount of money. A probationary amount is one that cannot be taken or paid out. A balance that is

Workforce Central Developers Toolkit Reference Guide—Timekeeping

53

Chapter 2

Workforce Timekeeper XML API Tag Definitions

given to a person for a probationary period can be transferred as a vested amount once the person has worked through the probationary period. Type: Currency Output only Introduced in v5.0; last changed in v5.1 ProjectedProbationaryBalanceInTime

Projected probationary balance, in time
The projected probationary balance expressed as an amount of time. A probationary amount is one that cannot be taken or paid out. A balance that is given to a person for a probationary period can be transferred as a vested amount once the person has worked through the probationary period. Type: TimeDuration Output only Introduced in v5.0; last changed in v5.1 ProjectedTakingAmountInCurrency

Projected taking amount, in currency
The amount of money that the employee is scheduled to take between the selected date and the furthest projected taking date. Type: Currency Output Only Contains a value if the accrual is a monetary type Introduced in v4; last changed in v5.1 ProjectedTakingAmountInTime

Projected taking amount, in time
The amount of time that the employee is scheduled to take between the selected date and the furthest projected taking date. Type: TimeDuration

54

Kronos Incorporated

AccrualBalanceSummary Tag

Output Only Contains a value if the accrual is a time type Introduced in v4; last changed in v5.1 ProjectedVestedBalanceInCurrency

Projected vested balance, in currency
The current vested balance of money minus all projected takings and plus all projected vested credits up through the furthest projected taking date. This balance includes any scheduled resets. Type: Currency Output only Introduced in v5.0; last changed in v5.1 ProjectedVestedBalanceInTime

Projected vested balance, in time
The current vested balance of time minus all projected takings and plus all projected vested credits up through the furthest projected taking date. This balance includes any scheduled resets. Type: TimeDuration Output only Introduced in v5.0; last changed in v5.1 VestedBalanceInCurrency

Vested balance, in currency
The amount of money that is vested in the employee's account. A vested amount is one that can be taken or paid out. Type: Currency Output Only Contains a value if the accrual is a monetary type Introduced in v4; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

55

Chapter 2

Workforce Timekeeper XML API Tag Definitions

VestedBalanceInTime

Vested balance, in time
The amount of time that is vested in the employee's account. A vested amount is one that can be taken or paid out. Type: TimeDuration Output Only Contains a value if the accrual is a time type Introduced in v4; last changed in v5.1

56

Kronos Incorporated

AccrualCode Tag

AccrualCode Tag Accrual Code
The AccrualCode tag defines details about an accrual code. Accrual codes identify categories of time or money that employees earn, such as vacation, sick time, and bonus. Amounts can be hours, days, or money. Function Access Control Point: API.Accruals Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadAllAccrualCodes" Parameters→ None Properties→ <AccrualCode (Abbreviation = String) (AccrualCodeName = String) (DisplayType = String) (HoursPerDay = TimeDuration) > </AccrualCode>

Action Descriptions
LoadAllAccrualCodes Returns information for all accrual codes Return Value Type: Zero or more AccrualCode tags Access Control Point Name: View

Workforce Central Developers Toolkit Reference Guide—Timekeeping

57

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v4; last changed in v5.1

Property Descriptions
Abbreviation

Abbreviation
The abbreviation of the accrual code, which can be up to three characters. This abbreviation may appear on selected reports. Type: String Output Only Introduced in v4 AccrualCodeName

Accrual code name
Name of an account that identifies a category of time or money that employees earn. Type: String Output Only Sample values: Vacation, Sick Introduced in v4; last changed in v5.1 DisplayType

Display type
The type of accrual code, which can be money, hours, or days. Type: String Output Only Enumerated value: Hours, Days, Currency Introduced in v4

58

Kronos Incorporated

AccrualCode Tag

HoursPerDay

Number of hours in accrual day
The number of hours per day that constitutes a day of this accrual code. This value is used to convert hours to days. Type: TimeDuration Output Only Contains no value when the DisplayType is Currency Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

59

Chapter 2

Workforce Timekeeper XML API Tag Definitions

AccrualData Tag Accrual Data for Employee
The AccrualData tag gets accrual balance information for the specified employee on the specified date. Used by: EmployeeSummary Function Access Control Point: API.Accruals Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" Parameters→ None Properties→ <AccrualData BalanceDate = Date > (<AccrualBalances> <AccrualBalanceSummary>* </AccrualBalances>) <Employee> <CurrentUser> | <PersonIdentity> </Employee> </AccrualData>

Action Descriptions
Load Returns one summary for each accrual code for the specified employee and date.

60

Kronos Incorporated

AccrualData Tag

Only returns one employee Return Value Type: AccrualData tag Required Properties: Employee, BalanceDate Access Control Point Name: View Introduced in v4

Property Descriptions
AccrualBalances

The balance amounts in all accrual codes for the specified employee
One or more sets of accrual summaries that represent all accrual codes found for the employee at the specified date. Type: Zero or more AccrualBalanceSummary tags Output Only Introduced in v4; last changed in v5.1 BalanceDate

The date specified for the accrual balances being retrieved. Balance date is required.
The date specified for the accrual balances. The vested balance is as of this date. Type: Date Required, Key Introduced in v4; last changed in v5.1 Employee

The employee whose accrual data is being retrieved. Employee is required.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

61

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The employee whose accrual data is being retrieved. Employee is required and must be an existing and active employee, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Required Key Must uniquely identify an existing and active employee. Introduced in v4

62

Kronos Incorporated

AccrualMove Tag

AccrualMove Tag Accrual Move
The AccrualMove tag moves an accrued amount from one accrual code to another. For example, depending on your company's policies and the user's access rights, a user might be able to move an employee's accrued sick time to the employee's vacation time. Dependency: All rules related to applying an accrual move apply to this tag and its actions. Function Access Control Point: API.Accruals Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Update" Parameters→ None Properties→ <AccrualMove AmountInCurrency = Currency AmountInTime = TimeDuration GivingEmployeeAccrualCodeName = String TakingEmployeeAccrualCodeName = String Date = Date > <GivingEmployee> <CurrentUser> | <PersonIdentity> </GivingEmployee> <TakingEmployee> <CurrentUser> | <PersonIdentity> </TakingEmployee>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

63

Chapter 2

Workforce Timekeeper XML API Tag Definitions

</AccrualMove>

Action Descriptions
Update Moves an accrual amount from one employee accrual code to another. The amount of the accrual is also required. Specify either an AmountInCurrency or an AmountInTime. Return Value Type: None Required Properties: GivingEmployeeAccrualCodeName, TakingEmployeeAccrualCodeName, Date, GivingEmployee, TakingEmployee Access Control Point Name: Edit Introduced in v4

Property Descriptions
AmountInCurrency

Amount of accrual, in currency
An accrual amount expressed as money. Type: Currency Maximum length: 30 characters Introduced in v4; last changed in v5.1 AmountInTime

Amount of pay code, in time
A pay code amount, expressed as time. Type: TimeDuration The accrual amount that should be assigned to the employee if the accrual code is an hour or daily accrual code. Introduced in v4; last changed in v5.1

64

Kronos Incorporated

AccrualMove Tag

Date

Effective date
The date when the accrual move takes effect. Type: Date Required Introduced in v4; last changed in v5.1 GivingEmployee

Employee who is giving
One employee, as specified in a PersonIdentity or CurrentUser tag, from whom the accrual will be deducted. Type: Either CurrentUser or PersonIdentity tag Required Key Must uniquely identify an existing and active employee Introduced in v4 GivingEmployeeAccrualCodeName

Accrual code the accrual is moved from
Accrual code (such as sick or vacation) that you want to move to another accrual code. Type: String Required Maximum length: 50 characters You can find values in the Workforce Timekeeper Setup Application. Use a value that is assigned to the employee, as specified in the accrual profile. Introduced in v4; last changed in v5.1 TakingEmployee

Employee who is taking

Workforce Central Developers Toolkit Reference Guide—Timekeeping

65

Chapter 2

Workforce Timekeeper XML API Tag Definitions

One employee, as specified in a PersonIdentity or CurrentUser tag, to whom the accrual will be assigned. This employee can be the same as the GivingEmployee, or it can be a different employee. Type: Either CurrentUser or PersonIdentity tag Required Key Must uniquely identify an existing and active employee Introduced in v4; last changed in v5.1 TakingEmployeeAccrualCodeName

Accrual code the accrual is moved to
Accrual code (such as sick or vacation) to which you want to move an accrued amount. Type: String Required Maximum length: 50 characters You can find values in the Workforce Timekeeper Setup Application. Use a value that is assigned to the employee, as specified in the accrual profile. Introduced in v4; last changed in v5.1

Groups of Mutually Exclusive Properties
Amount The accrual code determines whether AmountInCurrency and AmountInTime must be specified Required Group includes: AmountInCurrency, AmountInTime

66

Kronos Incorporated

AccrualPatternElement Tag

AccrualPatternElement Tag Accrual Pattern Element
The AccrualPatternElement tag represents a schedule day allocated to a specific accrual code. Used by: ScheduleAccrualPattern Function Access Control Point: API.Schedule Introduced in v4; last changed in v6.0

Syntax
Properties→ <AccrualPatternElement DayNumber = Integer > </AccrualPatternElement>

Property Descriptions
DayNumber

Day number in the pattern
Specifies the day of the pattern. Type: Integer Required Must be greater than zero Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

67

Chapter 2

Workforce Timekeeper XML API Tag Definitions

AccrualProfile Tag Accrual Profile
The AccrualProfile tag provides information about the accrual profile assigned to a group of employees. The accrual profile defines a set of accrual rules that apply to the employees to which the accrual profile is assigned. For example, one profile can be assigned to all full-time employees and another can be assigned to all parttime employees. Function Access Control Point: API.Accruals Introduced in v4; last changed in v4.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllAccrualProfiles" | "LoadById" Parameters→ None Properties→ <AccrualProfile [AccrualProfileName = String] [AccrualProfileId = Integer] > </AccrualProfile>

Action Descriptions
Load Returns an accrual profile.

68

Kronos Incorporated

AccrualProfile Tag

Name should be valid Return Value Type: AccrualProfile tag Required Properties: AccrualProfileName Access Control Point Name: View Introduced in v4 LoadAllAccrualProfiles Returns all accrual profiles in the system. Return Value Type: Zero or more AccrualProfile tags Access Control Point Name: View Introduced in v4 LoadById Returns an accrual profile, based on the specified AccrualProfileId. Return Value Type: AccrualProfile tag Required Properties: AccrualProfileID Access Control Point Name: View Introduced in v4

Property Descriptions
AccrualProfileId

Accrual profile Id
A unique identifier for the accrual profile. Type: Integer Optional Introduced in v4 AccrualProfileName

Accrual profile

Workforce Central Developers Toolkit Reference Guide—Timekeeping

69

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The accrual profile to be used for a person or group. Accrual profiles are based on your company's accrual rules and policies that apply to similar groups of employees. The rules determine how employees accrue their time or money, or both. When an employee uses accrued time or money, specified amounts are deducted from the balance. When an employee receives or earns time or money, specified amounts are credited to the balances. Type: String Optional Maximum length: 50 characters You can find values in the Setup Application. Sample values: VAC and Sick Only Introduced in v4

70

Kronos Incorporated

AdHocLaborAccount Tag

AdHocLaborAccount Tag Ad Hoc Labor Account
The AdHocLaborAccount tag enables the creation of an ad hoc labor level account. An ad hoc labor level account can be created only if it does not already exist, and if at least one of the labor level entries needs to be created. Function Access Control Point: API.LaborLevel Introduced in v4; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "CreateAdHoc" Parameters→ None Properties→ <AdHocLaborAccount FieldDefinitionName = String LaborAccountName = String > </AdHocLaborAccount>

Action Descriptions
CreateAdHoc Adds an ad hoc labor account Return Value Type: None Required Properties: LaborAccountName

Workforce Central Developers Toolkit Reference Guide—Timekeeping

71

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: Edit Introduced in v4

Property Descriptions
FieldDefinitionName

Field definition name
Activity form substep's field definition name. Type: String Required Must match an existing field definition name Introduced in v5.0 LaborAccountName

Labor account
Name of the labor level account to be created ad hoc. Enter data for labor accounts in the same format as they appear in the database. For example, if you have a seven-level labor account, specify a value for each labor level: 101/202/303/404/504/603/702. Do not specify labor levels that are not changing. If any of the labor levels are the same as the employee°Øs primary labor account, you can enter @H for those labor levels instead of entering the labor entry names. Type: String Required Maximum length: 356 characters The user and labor level account must allow ad hoc access Introduced in v4

72

Kronos Incorporated

APICallList Tag

APICallList Tag Call List
This tag provides managers, supervisors, or staffing specialists, a call list to find employees that are qualified and available to fill an open shift. Function Access Control Point: Relief Management Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveCallList" Parameters→ RetrieveCallList→ EndDate = Date ProcedureSetName = String StartDate = Date

Action Descriptions
RetrieveCallList Retrieves the list of open shifts and matching employees for each open shift. Return Value Type: Zero or more APICallList tags Access Control Point Name: View Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

73

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Parameters Parameter Name EndDate ProcedureSetName StartDate Description The end date of the scheduling period. Required The name of the script to execute. Required The start date of the scheduling period. Required Additional information Introduced in v6.0 Introduced in v6.0 Introduced in v6.0

74

Kronos Incorporated

APIOutsideDate Tag

APIOutsideDate Tag Outside of work week date
This tag specifies whether hours outside of the work week are excluded when validating weekly employee schedule rules. Function Access Control Point: Scheduling Introduced in v6.0; last changed in v6.0

Syntax
Properties→ <APIOutsideDate OutsideDate = Date > </APIOutsideDate>

Property Descriptions
OutsideDate

A date outside of work week
Specify a date outside of the work week. Hours scheduled on this day are not counted in the weekly scheduling rule limits. Type: Date Required Standard date validation applies Sample values: <OutsideDate> 04/26/2006</OutsideDate> Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

75

Chapter 2

Workforce Timekeeper XML API Tag Definitions

APIPSEEngine Tag Run Priority Scheduling Engine
This tag runs the Priority Scheduling Engine (PSE) with a set of parameters, including procedure set name, start date, and end date. Function Access Control Point: API.Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Run" Parameters→ Run→ EndDate = Date ProcedureSetName = String StartDate = Date

Action Descriptions
Run This action runs the PSE with the given parameters. Return Value Type: None Access Control Point Name: Edit Introduced in v6.0

76

Kronos Incorporated

APIPSEEngine Tag

Action Parameters Parameter Name EndDate ProcedureSetName StartDate Description The end date of the scheduling period. Required The name of the script to execute. Required The start date of the scheduling period. Required Additional information Introduced in v6.0 Introduced in v6.0 Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

77

Chapter 2

Workforce Timekeeper XML API Tag Definitions

APIPunchRestrictionOverride Tag Override Punch Restriction
This tag lets you override punch restrictions for Timestamp employees. Function Access Control Point: API.Timecard Introduced in v6.0; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveForUpdate" | "Update" Parameters→ None Properties→ <APIPunchRestrictionOverride [EarlyInOverrideFlag = Boolean] [EarlyOutRestrictionFlag = Boolean] [ExpirationDateTime = DateTime] [LateInRestrictionFlag = Boolean] [LateOutRestrictionFlag = Boolean] [MinimumBreakRestrictionFlag = Boolean] PersonNumber = String [StartBreakRestrictionFlag = Boolean] [UnscheduledPunchRestrictionFlag = Boolean] > </APIPunchRestrictionOverride>

Action Descriptions

78

Kronos Incorporated

APIPunchRestrictionOverride Tag

RetrieveForUpdate Retrieves the punch restriction override information (if any is present in the DB) for a given employee. Person Number should represent the employee id of an existing employee. Return Value Type: APIPunchRestrictionOverride tag Required Properties: PersonNumber Access Control Point Name: View Introduced in v6.0 Update Updates or adds a punch restriction override record to the database for the specified employee. Person number must be specified and must represent the employee id of an existing employee. Return Value Type: None Required Properties: PersonNumber Access Control Point Name: Edit Introduced in v6.0

Property Descriptions
EarlyInOverrideFlag

Early In Override
Specify whether to override the duration of time before the scheduled shift starts when the employee can punch in. Type: Boolean Optional Must be either "true" or "false". Sample values: true

Workforce Central Developers Toolkit Reference Guide—Timekeeping

79

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Default value: false Introduced in v6.0 EarlyOutRestrictionFlag

Early Out Restriction Override
Specify whether to override the amount of time before the scheduled end of a shift when employees cannot punch out. Type: Boolean Optional Must be either "true" or "false". Sample values: true Default value: false Introduced in v6.0 ExpirationDateTime

Expiration Date and Time
Specify the expiration date and time for the override. Type: DateTime Optional Must be able to be converted to a valid date and time (KDateTime) Sample values: 1/25/2007 10:37AM Default value: Currentdate and time plus 24 hours. Introduced in v6.0 LateInRestrictionFlag

Late In Restriction Override

80

Kronos Incorporated

APIPunchRestrictionOverride Tag

Specify whether to override the amount of time after a scheduled shift starts before an employees punch is rejected. Type: Boolean Optional Must be either "true" or "false". Sample values: true Default value: false Introduced in v6.0 LateOutRestrictionFlag

Late Out Restriction Override
Specify whether to override the amount of time after the scheduled end of a shift when employees can punch out. Type: Boolean Optional Must be either "true" or "false". Sample values: true Default value: false Introduced in v6.0 MinimumBreakRestrictionFlag

Minimum Break Restriction Override
Specify whether to override the punch restriction on the minimum amount of time allowed for a meal break. Type: Boolean Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

81

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Must be either "true" or "false". Sample values: true Default value: false Introduced in v6.0 PersonNumber

Person Number
Specify the person's identification number for whom the punch restriction override will apply. Type: String Required Must be specified and should represent the employee id of an existing employee previously added to the system. Sample values: "242" or "JSMITH" Introduced in v6.0 StartBreakRestrictionFlag

Start Break Restriction Override
Specify whether to override the amount of time before the start of a scheduled shift when an employee punch is rejected. Type: Boolean Optional Must be either "true" or "false". Sample values: true

82

Kronos Incorporated

APIPunchRestrictionOverride Tag

Default value: false Introduced in v6.0 UnscheduledPunchRestrictionFlag

Unscheduled Punch Restriction Override
Specify whether to override the timestamp or device rule to reject in-punches from employees who do not have a scheduled shift. Type: Boolean Optional Must be either "true" or "false". Sample values: true Default value: false Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

83

Chapter 2

Workforce Timekeeper XML API Tag Definitions

APISCGEngine Tag Run Schedule Generator
Runs the Schedule Generator engine with a set of parameters: start date and end date. Function Access Control Point: Schedule Generator Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "run" Parameters→ run→ EndDate = Date OptionSetName = String StartDate = Date

Action Descriptions
run Runs the Schedule Generator engine. Return Value Type: None Access Control Point Name: Edit Introduced in v6.0

84

Kronos Incorporated

APISCGEngine Tag

Action Parameters Parameter Name EndDate OptionSetName Description The end date. Required Represents the schedule generator location settings name. Required The start date. Required Additional information Introduced in v6.0 Introduced in v6.0

StartDate

Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

85

Chapter 2

Workforce Timekeeper XML API Tag Definitions

APIStableDateSpans Tag Stable date spans
This tag lists all the stable date spans for a given list of locations. Function Access Control Point: Schedule Planner Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" Parameters→ None Properties→ <APIStableDateSpans QueryDateSpan = String > [<Locations> <LocationItem>* </Locations>] </APIStableDateSpans>

Action Descriptions
Retrieve Retrieve the stable date span list. Return Value Type: APIStableDateSpans tag Required Properties: QueryDateSpan Optional Properties: Locations

86

Kronos Incorporated

APIStableDateSpans Tag

Access Control Point Name: View Introduced in v6.0

Property Descriptions
Locations

Locations related to stable date span
Represents a list of locations. Type: Zero or more LocationItem tags Optional Sample values: <Locations> <LocationItem Location="Organization/Hospitals/Hosp A/Floor 1"/> </Locations> Introduced in v6.0; last changed in v6.0 QueryDateSpan

A stable date span
Represents a date span. Type: String Required Sample values: <QueryDateSpan> 04/23/2006 - 04/29/2006</ QueryDateSpan> Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

87

Chapter 2

Workforce Timekeeper XML API Tag Definitions

APIVolumeDataService Tag Volume data service
This tag returns all the volume items for a list of locations and a range of dates. Function Access Control Point: Schedule Planner Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" Parameters→ None Properties→ <APIVolumeDataService QueryDateSpan = String > [<Locations> <LocationItem>* </Locations>] </APIVolumeDataService>

Action Descriptions
Retrieve Retrieves all the Volume Items for the given date period and for the given list of locations. Return Value Type: Zero or more VolumeDataItem tags Required Properties: QueryDateSpan Optional Properties: Locations

88

Kronos Incorporated

APIVolumeDataService Tag

Access Control Point Name: View Introduced in v6.0

Property Descriptions
Locations

Locations
Specify a list of locations, such as hospital, floor, or department. Type: Zero or more LocationItem tags Optional Sample values: <Locations> <LocationItem Location="Organization/Hospitals/Hosp A/Floor 1/ER"/> <LocationItem Location="Organization/Hospitals/Hosp A/Floor 1/Pediatrics"/> </Locations> Introduced in v6.0 QueryDateSpan

Date span of volume data
Specify a date span to query. Type: String Required Sample values: <QueryDateSpan> 04/11/2006 - 04/12/2006</ QueryDateSpan> Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

89

Chapter 2

Workforce Timekeeper XML API Tag Definitions

AppendShifts Tag Append shifts
The AppendShifts tag adds time to the beginning or end of a given shift. Function Access Control Point: API.Schedule Introduced in v5.1; last changed in v5.1

Syntax
Properties→ <AppendShifts AppendDurationAmount = TimeDuration AppendToBeginOrEnd = Boolean EffectiveDate = Date [LaborAccountName = String] [OrgJobPath = String] [WorkRuleName = String] > </AppendShifts>

Property Descriptions
AppendDurationAmount

Amount of time to be appended
AppendDurationAmount Type: TimeDuration Required Introduced in v5.1; last changed in v5.1 AppendToBeginOrEnd

Append to the beginning?
AppendToBeginOrEnd property. Type: Boolean

90

Kronos Incorporated

AppendShifts Tag

Required Introduced in v5.1 EffectiveDate

Effective date
EffectiveDate property Type: Date Required Introduced in v5.1 LaborAccountName

Labor account
LaborAccountName property. Type: String Optional Introduced in v5.1 OrgJobPath

Organizational job path
OrgJobPath property. Type: String Optional Introduced in v5.1 WorkRuleName

Work rule
WorkRuleName property. Type: String Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

91

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.1; last changed in v5.1

92

Kronos Incorporated

ApplicationCalendar Tag

ApplicationCalendar Tag Calendar for Application View
The tag creates an application calendar for a specific application, such as timekeeping or scheduling. The application calendar can be used by calendar profiles. Function Access Control Point: Calendar framework Introduced in v5.2; last changed in v5.2

Syntax
Properties→ <ApplicationCalendar ViewType = Integer MonthWidth = Integer ApplicationName = String DataSetName = String > </ApplicationCalendar>

Property Descriptions
ApplicationName

The name of application
The name of an existing application such as timekeeping or scheduling that is associated with the calendar profile. Type: String Required Introduced in v5.1; last changed in v5.1 DataSetName

The name of the calendar data set
The name of the calendar data set to be used in this calendar profile. The calendar data set is created by the DataSet tag.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

93

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: String Required Introduced in v5.1; last changed in v5.1 MonthWidth

Default width of months in multiple months view
The default width of months in multiple months display. Even if you select one week or one month as the default time period for the calendar width, you might want to choose a default number of months, to accommodate individual users who change their calendar view to multiple months. Type: Integer Required Introduced in v5.1; last changed in v5.1 ViewType

Default view type
The default time period display for the calendar. Use 1 for weekly view, 2 for monthly view, or 3 for multiple months view. (You select the number of months in a multiple month view using the MonthWidth property.) Type: Integer Required Sample values: 1 2 3 Enumerated value: 1,2,3 Introduced in v5.1; last changed in v5.1

94

Kronos Incorporated

ApplicationCalendarAPIFacade Tag

ApplicationCalendarAPIFacade Tag Facade for Application Calendar
This tag is the public interface to the ApplicationCalendar. ApplicationCalendars can only be modified by CalendarProfiles. Function Access Control Point: Calendar Framework Introduced in v5.2

Syntax None

Workforce Central Developers Toolkit Reference Guide—Timekeeping

95

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ApproveSignoff Tag Approve Timecard
The ApproveSignoff tag enables the user to manage the approval and signoff aspects of a timecard. Function Access Control Point: API.Timecard Introduced in v4

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Approve" | "PeriodIsApproved" | "PeriodIsSignedOff" | "RemoveApproval" | "RemoveOthersApproval" | "RemoveSignOff" | "SignOff" Parameters→ None Properties→ <ApproveSignoff [DataSource = String] [UserName = String] > <Employee> <CurrentUser> | <PersonIdentity> </Employee> [<Period> <TimeFramePeriod> </Period>] </ApproveSignoff>

96

Kronos Incorporated

ApproveSignoff Tag

Action Descriptions
Approve Approves the specified employee's timesheet. Return Value Type: None Required Properties: Employee, Period Access Control Point Name: Edit Introduced in v4 PeriodIsApproved Returns a True or False, depending on whether the specified employee's timesheet is approved. Return Value Type: SimpleValue tag Required Properties: Employee, Period Access Control Point Name: View Introduced in v4 PeriodIsSignedOff Returns True or False, depending on whether the specified employee's timesheet is signed off. Return Value Type: SimpleValue tag Required Properties: Employee, Period Access Control Point Name: View Introduced in v4 RemoveApproval Removes the approval from the employee. Return Value Type: None Required Properties: Employee Access Control Point Name: Edit Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

97

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RemoveOthersApproval Removes an approval that was added by someone other than the current user. Return Value Type: None Required Properties: Employee, Period, UserName, DataSource Access Control Point Name: Edit Introduced in v4 RemoveSignOff Removes the latest signoff for the employee. Return Value Type: None Required Properties: Employee Access Control Point Name: Edit Introduced in v4 SignOff Adds a sign off to the specified employee's timesheet. Return Value Type: None Required Properties: Employee Access Control Point Name: Edit Introduced in v4

Property Descriptions
DataSource

Data source
The data source that identifies the user who performed a timecard approval. This value is only relevant for the RemoveOthersApproval action. Type: String Optional Maximum length: 10 characters

98

Kronos Incorporated

ApproveSignoff Tag

Introduced in v4 Employee

Employee
One employee whose time is to be approved or signed off, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Required Key Must uniquely identify an existing and active employee Introduced in v4 Period

Time period
For all actions except Signoff, this is the timeframe to which the action applies. It is ignored for the Signoff action. Type: TimeFramePeriod tag Optional Introduced in v4 UserName

User name
The user name used for the approval. Used in the PeriodIsApproved action. Type: String Optional Maximum length: 70 characters Default value: The logged on user Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

99

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Attribute Tag Attribute for process or task
The Attribute tag identifies an attributes for either a process or a task. Used by: Process, ProcessTask Function Access Control Point: com.kronos.wfc.business.workflow.Kattribute Introduced in v5.1; last changed in v5.1

Syntax
Properties→ <Attribute Name = String Value = String > </Attribute>

Property Descriptions
Name

Attribute name
Name of the attribute. Each attribute must contain both a name and a value. Type: String Required Key Maximum length: 255 characters Sample values: HRAdministrator Introduced in v5.1 Value

Attribute value

100

Kronos Incorporated

Attribute Tag

The value for the attribute. Each attribute must contain both a name and a value. Type: String Required Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

101

Chapter 2

Workforce Timekeeper XML API Tag Definitions

AuditItem Tag Audit Item
This tag provides audit information that results from making a change to an audited data item. Function Access Control Point: Audit Introduced in v6.0; last changed in v6.0

Syntax
Properties→ <AuditItem (AfterImage = String) (AssociatedId = Long) (AssociatedName = String) (AuditAction = String) (AuditBeginDtm = DateTime) (AuditEndDtm = DateTime) (AuditType = String) (BeforeImage = String) (EnteredOnDtm = DateTime) (PersonNumber = String) > (<AuditItemChildren> <AuditItem>* </AuditItemChildren>) (<DataSource> <DataSource> </DataSource>) </AuditItem>

Property Descriptions
AfterImage

After image
The value of the audited information after the change. Type: String

102

Kronos Incorporated

AuditItem Tag

Output only Introduced in v6.0 AssociatedId

Associated ID
The database ID of the employee whose information was changed. Type: Long Output only Introduced in v6.0 AssociatedName

Associated name
The name of the database table that has changed. Type: String Output only Introduced in v6.0 AuditAction

Audit action
The user action that caused the change, such as create, modify, or delete. Always one of the values in the database table AUDITACTION, column AUDITACTIONNM. Type: String Output only Sample values: CREATE or MODIFY or DELETE Introduced in v6.0 AuditBeginDtm

Audit begin date time

Workforce Central Developers Toolkit Reference Guide—Timekeeping

103

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The date and time that the audited action began. Type: DateTime Output only Introduced in v6.0 AuditEndDtm

Audit end date time
The date and time that the audited action finished. Type: DateTime Output only Introduced in v6.0 AuditItemChildren

Audit item children
The audited changes that logically belong to this audit item. Audit item children can also have their own children. You can change many person attributes, such as the primary job and the job transfer set, simultaneously. These changes would be children of a parent audit item. One change that affects multiple database tables is also represented as a parent/child audit item relationship. Type: Zero or more AuditItem tags Output only Introduced in v6.0 AuditType

Audit type
The general functional area where the change occurred. This information is derived from the AUDITTYPEdatabase table in the column labelled AUDITTYPENM. Type: String Output only

104

Kronos Incorporated

AuditItem Tag

Sample values: Person Access Assignment Introduced in v6.0 BeforeImage or Schedule Validation Rules

Before image
The value of the audited information prior to the change. The value is blank if the change is a creation. Type: String Output only Introduced in v6.0 DataSource

Data source
The user name and machine responsible for the audited change. Type: DataSource tag Output only Introduced in v6.0 EnteredOnDtm

Entered on date time
The date and time that the audit information itself (not the change being audited) was saved to the database. Type: DateTime Output only Introduced in v6.0 PersonNumber

Person number

Workforce Central Developers Toolkit Reference Guide—Timekeeping

105

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The employee identification number of the person whose information was changed. Type: String Output only Introduced in v6.0

106

Kronos Incorporated

AuditTrail Tag

AuditTrail Tag Audit Trail
This tag provides information collected from the database about audited items. Function Access Control Point: Audit Introduced in v6.0; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveAuditTrail" Parameters→ None Properties→ <AuditTrail DateSpan = DateSpan DateTimeSpan = DateTimeSpan [AuditType = String] [PersonNumber = String] [UserName = String] > (<AuditItems> <AuditItem>* </AuditItems>) </AuditTrail>

Action Descriptions
RetrieveAuditTrail Retrieves an AuditTrail element whose AuditItems reflect the date span, date time span, audit type, user name, and person number specified.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

107

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Return Value Type: AuditTrail tag Required Properties: DateSpan, DateTimeSpan Optional Properties: AuditType, UserName, PersonNumber Access Control Point Name: View Introduced in v6.0

Property Descriptions
DateSpan

Date Span
The dates used to query requested audits. Audits occuring on these dates will be retrieved from the database. Type: DateSpan Introduced in v6.0 DateTimeSpan

Date time span
The date and times on which audits occurred. Audits made in this range will be retrieved from the database. If this date time span is used, the times must be entered. If you want just a day, use the DateSpan property. Type: DateTimeSpan Introduced in v6.0 AuditItems

Audit items
The list of heirarchical audit item information retrieved from the database. Type: Zero or more AuditItem tags Output only Introduced in v6.0

108

Kronos Incorporated

AuditTrail Tag

AuditType

Audit type
The general functional area where the change occurred. This information is derived from the AUDITTYPEdatabase table in the column labelled AUDITTYPENM. Type: String Optional Introduced in v6.0 PersonNumber

Person number
The employee identification number of the person whose information was changed. Type: String Optional Introduced in v6.0 UserName

User Name
The user name of the person making the changes. The audit items that are retrieved from the database will consist of information changed by this user. Type: String Optional Introduced in v6.0

Groups of Mutually Exclusive Properties
DateSpanOrDateTimeSpan Either the DateSpan or the DateTimeSpan, but not both. Required

Workforce Central Developers Toolkit Reference Guide—Timekeeping

109

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Group includes: DateSpan, DateTimeSpan

110

Kronos Incorporated

AuthenticationType Tag

AuthenticationType Tag Authentication Type
The AuthenticationType tag retrieves all AuthenticationType objects. Function Access Control Point: API.People Introduced in v5.1; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveAll" Parameters→ None Properties→ <AuthenticationType (AuthTypeName = String) > </AuthenticationType>

Action Descriptions
RetrieveAll Retrieves all AuthenticationType objects from the database. None Return Value Type: Zero or more AuthenticationType tags Access Control Point Name: View Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

111

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Property Descriptions
AuthTypeName

Authentication type
Name of the authentication type. Type: String Output only Introduced in v5.1

112

Kronos Incorporated

BadgeAssignment Tag

BadgeAssignment Tag Badge Assignment
The BadgeAssignment tag assigns a badge number to an employee. Used by: PersonInformation Function Access Control Point: API.Person Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadBadgeAssignments" Parameters→ None Properties→ <BadgeAssignment BadgeNumber = String EffectiveDate = DateTime [ExpirationDate = DateTime] > <Identity> <CurrentUser> | <PersonIdentity> </Identity> [<Period> <TimeFramePeriod> </Period>] </BadgeAssignment>

Action Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

113

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LoadBadgeAssignments Assigns a badge number to a person for a specified time period. If no time period is specified, the time period begins with the current date and time and continues indefinitely. An empty tag (with only the Identity and Period properties) results when no data for the person or period is found. The person must exist and the user must have access to that person. Return Value Type: Zero or more BadgeAssignment tags Required Properties: Identity Optional Properties: Period Access Control Point Name: View Introduced in v5.0; last changed in v5.1

Property Descriptions
BadgeNumber

Badge number
The badge number that you want to assign to the employee. The system can be configured to allow multiple badges for employees using the global.BadgeAssignment.allowsOverlap property. For information, see the System Settings information in online help. If an employee is assigned multiple badge numbers, each badge number and associated information is added in a separate request. If an employee is assigned multiple badge numbers and you want to remove one of the badge numbers, first remove all existing badge numbers and then reassign the badge number that you want to keep. Type: String Required Maximum length: 25 characters Must be unique for the specified date span. Validation is done after a person is associated with a badge, using the PersonInformation tag. Introduced in v4; last changed in v5.1

114

Kronos Incorporated

BadgeAssignment Tag

EffectiveDate

Effective date and time
The date and time when the badge number assignment becomes effective. If this is blank, the current date and time are used. Type: DateTime Required Must occur before the expiration date Default value: If only the date is specified, the time defaults to 12:00am; that is, midnight. Introduced in v4; last changed in v5.1 ExpirationDate

Expiration date and time
The date and time when the badge number assignment expires. If this is blank, the badge number assignment continues indefinitely. Type: DateTime Optional Must occur after the effective date If only the date is specified, the time defaults to 12:00am; that is, midnight. Default value: January 1, 3000 Introduced in v4; last changed in v5.1 Identity

Identity
The person to whom the badge number is assigned, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Optional Key Must uniquely identify a person.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

115

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.0; last changed in v5.1 Period

Time period
The time span that is associated with the badge assignments. Type: TimeFramePeriod tag Optional The specified identity is used when the time frame requires an association with a person. Used for the LoadBadgeAssignments action. Default value: From the current date until January 1, 3000 Introduced in v5.0

116

Kronos Incorporated

BaseWageRate Tag

BaseWageRate Tag Base Wage Rate
The BaseWageRate tag is used to modify the hourly rate of an employee, effective as of a specific date or to view the wage rate history within a specified timeframe. Function Access Control Point: API.Person Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadBaseWageRateHistory" Parameters→ None Properties→ <BaseWageRate EffectiveDate = Date (ExpirationDate = Date) HourlyRate = Currency (Period = DateSpan) > <Identity> <CurrentUser> | <PersonIdentity> </Identity> </BaseWageRate>

Action Descriptions
LoadBaseWageRateHistory This action loads the wage rate history for a person. If no time period is specified, the entire history is loaded, beginning with the rate that is from the start of time to

Workforce Central Developers Toolkit Reference Guide—Timekeeping

117

Chapter 2

Workforce Timekeeper XML API Tag Definitions

end of time including any future rates. If a time period is specified, the rates that are in effect as of the start and end dates will be loaded. Return Value Type: (***undefined***): BaseWageRateEdit Required Properties: Identity Access Control Point Name: View Introduced in v5.2; last changed in v5.2

Property Descriptions
EffectiveDate

Effective date
The effective date determines when the new rate will be applied. Type: Date Required Sample values: 11/23/2005 Default value: today Introduced in v5.2 ExpirationDate

Expiration date
This property is returned when the base wage rate history is loaded. It indicates the day on which a wage rate expires. Type: Date Output only The value must represent a date. Sample values: 12/02/2005

118

Kronos Incorporated

BaseWageRate Tag

Default value: today Introduced in v5.2 HourlyRate

Hourly rate
The hourly rate represents the new value of an employee's hourly wage. It will go into effect on the effective date. Type: Currency Required Sample values: 10.15 Introduced in v5.2 Identity

Identity
This property identifies the employee when the LoadBaseWageRateHistory action is used. Type: Either CurrentUser or PersonIdentity tag Optional Key Introduced in v5.2 Period

Period
The time period that is optionally used with the LoadBaseWageRateHistory action in order to limit the timeframe of the base wage rate history. Type: DateSpan Output only Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

119

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Bid Tag Bid
This is an abstract bid bean that describes the generic bid which the employee submits, once the manager sends on a bid request. The validate method validates the contents of the bean. When it returns normally, the bean is believed to be valid for posting to the database. For Action BidGroupItem AddBids, the vacation bid BidGroupItemId property should match the BidGroupItem BidGroupItemId property. Function Access Control Point: API.Bid Introduced in v5.0a; last changed in v5.0a

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "ApplyBidNotes" | "DeleteBidNotes" Parameters→ None Properties→ <Bid BidId = Long BidGroupItemId = Long Priority = Integer (Status = String) > [<BidNotes> <BidNote>* </BidNotes>] </Bid>

120

Kronos Incorporated

Bid Tag

Action Descriptions
ApplyBidNotes Applies the specified bid notes to the bid specified by the bid id. Existing bid notes are deleted and the specified ones are inserted. For the ApplyBidNotes Action, the BidId property and the BidNotes property MUST be defined. Return Value Type: None Required Properties: BidId, BidNotes Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0a DeleteBidNotes Deletes all bid notes associated with the bid represented by this bid bean. For the DeleteBidNotes Action, the BidId property MUST be defined. Return Value Type: None Required Properties: BidId Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0a

Property Descriptions
BidGroupItemId

Bid group item Id
Id of the bid group item that this bid belongs to. Type: Long Required Key If the property is defined for an Action, the BidGroupItemId cannot be null. The BidGroupItemId MUST be defined for the VacationBid element in the BidGroupItem BidList for adding bids.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

121

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Sample values: <VacationBid BidGroupItemId="3" Priority="5" StartDate="04/01/2004 00:00:00" EndDate="05/01/2004 11:48:56" HoursPerDay="288000" CreateOpenShift="false"> </VacationBid> Introduced in v5.0; last changed in v5.0a BidId

Bid Id
Unique identifier for this bid. Type: Long Required Key If defined for an Action, the BidId property cannot be null. The BidId property MUST NOT be specified for the BidGroupItem AddBids Action. The BidId property MUST be defined for the ApplyBidNotes, DeleteBidNotes, BidGroupItem RemoveBids Actions. Introduced in v5.0; last changed in v5.0a BidNotes

Bid notes
List of BidNotes to add a specific bid. Type: Zero or more BidNote tags Optional If defined for an Action, the BidNotes property cannot be null. The contents of the BidNotes list cannot be null. The BidNotes property MUST contain one or more BidNote elements. The BidNotes property MUST be specified for the ApplyBidBNotes Action. Sample values: <VacationBid Id="501"> <BidNotes>

122

Kronos Incorporated

Bid Tag

<BidNote Sequence="1" Text="For vacation bid with Id=501"> </BidNote> </BidNotes> </VacationBid> Introduced in v5.0; last changed in v5.0a Priority

Bid priority
Bid priority. Also known as rank. Type: Integer Required If the Priority property is defined for an action, the Priority property cannot be null. The Priority cannot be less than 1. Sample values: <VacationBid BidGroupItemId="3" Priority="1" StartDate="04/01/2004 00:00:00" EndDate="05/01/2004 11:48:56" HoursPerDay="288000" CreateOpenShift="false"> </VacationBid> Introduced in v5.0; last changed in v5.0a Status

Bid status
The status of the bid, which may be 1 of 3 states: Submitted, Approved, Rejected. Type: String Output only The BidStatus property cannot be defined for any BidGroupItem, Bid, or Vacation Bid Action. Sample values: Submitted - 0, Approved - 1, Rejected - 2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

123

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Default value: Submitted, 0 Enumerated value: Submitted - 0, Approved - 1, Rejected - 2 Introduced in v5.0; last changed in v5.0a

124

Kronos Incorporated

BidGroup Tag

BidGroup Tag Bid Group
This tag identifies the bidding group where one or more employees may belong to. The validate method validates the contents of the bean. When this method returns normally, the bean is believed to be valid for posting to the database. Function Access Control Point: API.BidGroup Introduced in v5.0a; last changed in v5.0a

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "Delete" | "Load" | "LoadByBidRequest" | "Update" | "UpdateOnly" Parameters→ None Properties→ <BidGroup [Description = String] BidGroupId = Long Name = String BidRequestId = Long CloseDate = DateTime [NotificationText = String] OpenDate = DateTime ShiftOverride = Boolean >

Workforce Central Developers Toolkit Reference Guide—Timekeeping

125

Chapter 2

Workforce Timekeeper XML API Tag Definitions

</BidGroup>

Action Descriptions
AddOnly Adds a new bid group. For the AddOnly Action, the BidRequestId property, the Name property, the OpenDate property, the CloseDate property, and the ShiftOverride property MUST be specified and valid values. The BidGroupId MUST NOT be specified for the AddOnly Action. Return Value Type: BidGroup tag Required Properties: BidRequestId, Name, OpenDate, CloseDate, ShiftOverride Optional Properties: NotificationText Access Control Point Name: Edit Introduced in v5.0a; last changed in v5.0a Delete Deletes a bid group. For the Delete Action, the BidGroupId MUST be specified and set to a valid BidGroupId value. Return Value Type: None Required Properties: BidGroupId Access Control Point Name: Edit Introduced in v5.0a; last changed in v5.0a Load Loads bid group given the specific BidGroupID. For the Load Action, the BidGroupId MUST be specified and set to a valid BidGroupId value. Return Value Type: BidGroup tag Required Properties: BidGroupId Access Control Point Name: View

126

Kronos Incorporated

BidGroup Tag

Introduced in v5.0a; last changed in v5.0a LoadByBidRequest Loads all bid groups for a given bid request. For the LoadByBidRequest Action, the BidRequestId property MUST be specified and set to a valid id for a BidRequest. Return Value Type: Zero or more BidGroup tags Required Properties: BidRequestId Access Control Point Name: View Introduced in v5.0a; last changed in v5.0a Update Updates or inserts a bid group depending respectively on whether a bid group having the specified BidGroupId, already exists or not. When the update implies addition of a new bid group, the BidGroupId, if any, if specified, is ignored. For Update Action, the BidGroupId property, the BidRequestId property, the OpenDate property, and the CloseDate property all MUST be specified for the Update Action. Return Value Type: None Required Properties: BidGroupId, BidRequestId, OpenDate, CloseDate Optional Properties: ShiftOverride, NotificationText Access Control Point Name: Edit Introduced in v5.0a; last changed in v5.0a UpdateOnly Updates a bid group given its BidGroupId. For the UpdateOnly Action, the BidRequestId MUST NOT be specified. The BidGroupId property MUST be specified, and the BidGroupId specified MUST be a valid id for a Bid Group. Return Value Type: None Required Properties: BidGroupId Optional Properties: Name, Description, OpenDate, CloseDate, ShiftOverride, NotificationText

Workforce Central Developers Toolkit Reference Guide—Timekeeping

127

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: Edit Introduced in v5.0a; last changed in v5.0a

Property Descriptions
BidGroupId

Bid Group Id
Identifies a unique bid group. Type: Long Required Key If defined for an Action, the BidGroupId cannot be null. The BidGroupId MUST be equal to or greater than 1. The BidGroupId MUST NOT be defined for AddOnly Action. The BidGroupId MUST be defined for Delete, Load, Update, and UpdateOnly Actions. Introduced in v5.0a; last changed in v5.0a BidRequestId

Bid Request Id
Identifies the parent bid request. Type: Long Required Key If defined for an Action, the BidRequestId cannot be null. If the BidRequestId property is defined for an Action, it MUST be a valid id for a specific Bid Request. The BidRequestId MUST be defined for AddOnly, LoadByBidRequest, and Update Actions. Introduced in v5.0a; last changed in v5.0a CloseDate

Close Date
Date on which bidding closes. Type: DateTime

128

Kronos Incorporated

BidGroup Tag

Required If defined for an Action, the CloseDate property cannot be null. The CloseDate property must be defined for AddOnly and Update Actions. Sample values: "04/20/2004 11:48:56" Introduced in v5.0a; last changed in v5.0a Description

Bid Group Description
Description for bid group. Type: String Optional If defined for an Action, the Description property cannot be null. Introduced in v5.0a; last changed in v5.0a Name

Bid Group Name
Name for bid group. Type: String Required If defined for an Action, the Name property cannot be null. The Name value MUST be less than or equal to 250 characters. The Name property MUST be specified for the AddOnly Action. Introduced in v5.0a; last changed in v5.0a NotificationText

Notification Text
Text of the notification sent when the parent bid request is sent to the bidding participants.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

129

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: String Optional If defined for an Action, the NotificationText property cannot be null. The NotificationText property MUST be less than or equal to 4000 characters in length. Introduced in v5.0a; last changed in v5.0a OpenDate

Open Date
Date on which bidding opens. Type: DateTime Required If defined for an Action, OpenDate property cannot be null. The OpenDate property MUST be specified for the AddOnly and Update Actions. Sample values: "04/20/2004 00:00:00" Introduced in v5.0a; last changed in v5.0a ShiftOverride

Shift Override
Whether to override shifts when posting to schedule. Type: Boolean Required If defined for an Action, the ShiftOverride property cannot be null. The ShiftOverride property MUST be defined for the AddOnly Action. Sample values: "true" OR "false" Default value: "false"

130

Kronos Incorporated

BidGroup Tag

Introduced in v5.0a; last changed in v5.0a

Workforce Central Developers Toolkit Reference Guide—Timekeeping

131

Chapter 2

Workforce Timekeeper XML API Tag Definitions

BidGroupItem Tag Bid Group Item
The BidGroupItem tag assigns one or more person(s) into a specific bid group. Each person is identified by a specific person id and each bid group is identified by a specific bid group id. The BidSubmissionStatus may not be specified for any action. All Actions are validated. The validate method validates the contents of the bean. When the validation method returns normally, the bean is believed to be valid for posting to the database. Function Access Control Point: API.BidGroupItem Introduced in v5.0a; last changed in v5.0a

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddBids" | "AddOnly" | "Delete" | "Load" | "LoadByBidGroupAndPerson" | "RemoveBids" Parameters→ None Properties→ <BidGroupItem BidGroupId = Long BidGroupItemId = Long (BidSubmissionStatus = String)

132

Kronos Incorporated

BidGroupItem Tag

[BidReceived = DateTime] [LastSubmitted = DateTime] PersonId = Long > [<BidList> <VacationBid>* </BidList>] </BidGroupItem>

Action Descriptions
AddBids Adds bids to an existing bid group item given the BidGroupItemId. For the AddBids Action, the BidGroupItemId property and the BidList property MUST be specified. Return Value Type: BidGroupItem tag Required Properties: BidGroupItemId Optional Properties: BidGroupId, PersonId, LastSubmitted, BidReceived Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0a AddOnly Adds a new bid group item. For AddOnly Action, the BidGroupItemId and the BidSubmissionStatus should not be specified. The BidGroupId and PersonId should be valid id values and specified for the AddOnly Action. Return Value Type: BidGroupItem tag Required Properties: BidGroupId, PersonId Optional Properties: LastSubmitted, BidReceived Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0a Delete Deletes a bid group item given its BidGroupItemId.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

133

Chapter 2

Workforce Timekeeper XML API Tag Definitions

For the Delete Action, the BidGroupItemId MUST be specified. Return Value Type: None Required Properties: BidGroupItemId Optional Properties: BidGroupId, PersonId, LastSubmitted, BidReceived Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0a Load Loads the specific bid group item given its BidGroupItemId. For the Load Action, the BidGroupItemId must be specified. Return Value Type: BidGroupItem tag Required Properties: BidGroupItemId Optional Properties: BidGroupId, PersonId, LastSubmitted, BidReceived Access Control Point Name: View Introduced in v5.0; last changed in v5.0a LoadByBidGroupAndPerson Retrieves the specific bid group item given the BidGroupId and PersonId. For the LoadByBidGroupAndPerson Action, the BidGroupId and PersonId property must be specified. Return Value Type: BidGroupItem tag Required Properties: BidGroupId, PersonId Optional Properties: BidGroupItemId, LastSubmitted, BidReceived Access Control Point Name: View Introduced in v5.0; last changed in v5.0a RemoveBids Remove bids from a bid group item specified by the BidGroupItemId. For the RemoveBids Action, the BidGroupItemId property and the BidList property MUST be specified. Return Value Type: BidGroupItem tag

134

Kronos Incorporated

BidGroupItem Tag

Required Properties: BidGroupItemId Optional Properties: BidGroupId, PersonId, LastSubmitted, BidReceived Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0a

Property Descriptions
BidGroupId

Bid Group Id
The id value for a specific bidding group. The BidGroupId is the id of the bid group this bid group item belongs to. Type: Long Required Key If defined for an Action, the BidGroupId MUST not be null. The BidGroupId MUST be a valid id value which is able to retrieve a specific BidGroup bean. The BidGroupId MUST be specified for AddOnly and LoadByBidGroupAndPerson Actions. Introduced in v5.0; last changed in v5.0 BidGroupItemId

Bid Group Item Id
The specific id value for each bid group item. The BidGroupItemId identifies a unique bid group item. Type: Long Required Key If defined for an Action, BidGroupItemId cannot be null. The BidGroupItemId property MUST not be defined for AddOnly Action, but MUST be defined for Delete, Load, AddBids, and RemoveBids Actions. The BidGroupItemId cannot be less than 1. Introduced in v5.0; last changed in v5.0a

Workforce Central Developers Toolkit Reference Guide—Timekeeping

135

Chapter 2

Workforce Timekeeper XML API Tag Definitions

BidList

Bid List
List of Bids to add to the bid group item. Type: Zero or more VacationBid tags Optional If defined for AddBids or RemoveBids Actions, the BidList cannot contain null values. The BidList property may only be defined for the AddBids and RemoveBids Actions. Introduced in v5.0; last changed in v5.0 BidReceived

Date Bid Received
The date on which the bid request was last received by the employee. If null, the bid request associated with this bid group item was not received by the employee. Type: DateTime Optional If defined for an Action, the BidReceived property cannot be null. Sample values: "04/20/2004 11:48:56" Introduced in v5.0; last changed in v5.0 BidSubmissionStatus

Bid Submission Status
The bidding submission status value: Not Submitted, Submitted, or Declined To Submit. Type: String Output only

136

Kronos Incorporated

BidGroupItem Tag

The BidSubmissionStatus can only have values for Not Submitted, Submitted, or Declined To Submit. The BidSubmissionStatus cannot be defined for AddOnly Action. Default value: Not Submitted Enumerated value: 1 - Not Submitted, 2 - Submitted, 3 - Declined To Submit Introduced in v5.0; last changed in v5.0a LastSubmitted

Date Last Submitted
The date on which the bids associated with this bid group item were last submitted. If null, the bid associated with this bid group item has not been submitted. Type: DateTime Optional If defined for an Action, the LastSubmitted property cannot be null. Sample values: "04/20/2004 00:00:00" Introduced in v5.0; last changed in v5.0 PersonId

Person Id
The specific id value of person. The PersonId is the id of the person this bid group item belongs to. Type: Long Required Key If defined for an Action, the PersonId cannot be null. The PersonId cannot be less than 1. The PersonId MUST be defined for AddOnly and LoadByBidGroupAndPerson Actions. Introduced in v5.0; last changed in v5.0a

Workforce Central Developers Toolkit Reference Guide—Timekeeping

137

Chapter 2

Workforce Timekeeper XML API Tag Definitions

BidNote Tag Bid Note
These are the bid notes associated with a specified bid. The validate method validates the contents of the bean. When it returns normally, the bean is believed to be valid for posting to the database. Function Access Control Point: API.BidNote Introduced in v5.0a; last changed in v5.0a

Syntax
Properties→ <BidNote Text = String Sequence = Integer > </BidNote>

Property Descriptions
Sequence

Sequence Number
Sequence number for a bid note in the set of bid notes for a given bid. Type: Integer Required If defined for a BidNote, the Sequence property cannot be null. The Sequence property MUST be defined for a BidNote within BidNotes list when running the Bid or VacationBid ApplyBidNotes Action. The Sequence value cannot be less than 1. Sample values: <BidNotes> <BidNote Sequence="1" Text="This text is for vacation bid with Id=501"> </BidNote> </BidNotes>

138

Kronos Incorporated

BidNote Tag

Introduced in v5.0; last changed in v5.0a Text

Bid Note Text
Text for the bid note. Type: String Required If defined for a BidNote, the Text property cannot be null. The Text MUST be a string value less than or equal to 255 characters. The Text property MUST be defined for a BidNote. Introduced in v5.0; last changed in v5.0a

Workforce Central Developers Toolkit Reference Guide—Timekeeping

139

Chapter 2

Workforce Timekeeper XML API Tag Definitions

BidRequest Tag Bid Request
The Bid Request tag can be used to submits a bidding request. Typically, the manager will send out or submit a bidding request to his or her employees, so that the employees may be able to submit bids for specific vacation time. The validate method validates the contents of the bean. Function Access Control Point: API.BidRequest Introduced in v5.0a; last changed in v5.0a

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "Delete" | "Load" | "LoadByManager" | "PostToSchedule" | "SendToParticipants" | "Update" | "UpdateOnly" Parameters→ None Properties→ <BidRequest [PeriodStartDate = DateTime] [Description = String] BidRequestId = Long [Name = String] Type = String GroupScheduleProfileName = String

140

Kronos Incorporated

BidRequest Tag

[MaxBids = Integer] [NotificationDate = DateTime] [PeriodEndDate = DateTime] SchedulePatternProfileName = String ShfitCodeProfileName = String (Status = String) VacationPayCodeName = String > <Manager> <PersonIdentity> </Manager> </BidRequest>

Action Descriptions
AddOnly Adds a bid request. For the AddOnly Action, the Manager Property, the PeriodStartDate Property, the PeriodEndDate Property, the Name Property, and the Type Property, and the specific pay code profile name based on the Type property MUST be specified. Return Value Type: BidRequest tag Required Properties: Manager, PeriodStartDate, PeriodEndDate, Name, Type, Either VacationPayCodeName, ShiftCodeProfileName, SchedulePatternProfileName, GroupScheduleProfileName Optional Properties: Description, NotificationDate Access Control Point Name: Edit Introduced in v5.0a; last changed in v5.0a Delete Deletes a bid request given the BidRequestId. For the Delete Action, the BidRequestId property MUST be specified. Return Value Type: None Required Properties: BidRequestId Access Control Point Name: Edit Introduced in v5.0a; last changed in v5.0a

Workforce Central Developers Toolkit Reference Guide—Timekeeping

141

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Load Retrieves a bid request given the BidRequestId. Properties other than the BidRequestId property, if specified, are ignored. For the Load Action, the BidRequestId property MUST be specified. Return Value Type: BidRequest tag Required Properties: BidRequestId Access Control Point Name: View Introduced in v5.0a; last changed in v5.0a LoadByManager Retrieves a list of bid requests corresponding to the specified Manager. Properties other than the Manager property, if specified, will be ignored. For the LoadByManager Action, the Manager property MUST be specified. Return Value Type: Zero or more BidRequest tags Required Properties: Manager Access Control Point Name: View Introduced in v5.0a; last changed in v5.0a PostToSchedule Posts the bid request for the specified BidRequestId to schedule. Properties other than the BidRequestId property, if specified, are ignored. For the PostToSchedule Action, the BidRequestId property MUST be specified. Return Value Type: None Required Properties: BidRequestId Access Control Point Name: Edit Introduced in v5.0a; last changed in v5.0a SendToParticipants Posts the bid request for the specified BidRequestId to schedule. Properties other than the BidRequestId, if specified, are ignored. For the SendToParticipants Action, the BidRequestId property MUST be specified.

142

Kronos Incorporated

BidRequest Tag

Return Value Type: None Required Properties: BidRequestId Access Control Point Name: Edit Introduced in v5.0a; last changed in v5.0a Update Updates or inserts a bid request depending respectively on whether a bid request having the specified BidRequestId, already exists or not. When the update implies addition of a new bid request, the BidRequestId, if any is specified, is ignored. For the Update Action, you must specify the following properties: Manager, PeriodStartDate, PeriodEndDate, Name, MaxBids, Type, based on Type specify either VacationPayCodeName, ShiftCodeProfileName, SchedulePatternProfileName, GroupScheduleProfileName. Return Value Type: None Required Properties: BidRequestId, Manager, PeriodStartDate, PeriodEndDate, Name, MaxBids, Type, Either VacationPayCodeName, ShiftCodeProfileName, SchedulePatternProfileName, or GroupScheduleProfileName Optional Properties: Description, NotificationDate Access Control Point Name: Edit Introduced in v5.0a; last changed in v5.0a UpdateOnly Updates the bid request given the BidRequestId. For the UpdateOnly Action, the BidRequestId property MUST be specified. If you specify the Type property, based on Type specified you MUST specify either VacationPayCodeName, ShiftCodeProfileName, SchedulePatternProfileName, or GroupScheduleProfileName. Return Value Type: None Required Properties: BidRequestId Optional Properties: Manager, PeriodStartDate, PeriodEndDate, Name, Description, MaxBids, NotificationDate, Type and Either VacationPayCodeName, ShiftCodeProfileName, SchedulePatternProfileName, GroupScheduleProfileName

Workforce Central Developers Toolkit Reference Guide—Timekeeping

143

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: Edit Introduced in v5.0a; last changed in v5.0a

Property Descriptions
BidRequestId

Bid Request Id
Identifies a unique bid request. Type: Long Required Key If defined for an Action, the BidRequestId property cannot be null. The BidRequestId property MUST be greater than or equal to 1. The BidRequestId property MUST be specified for every BidRequest Action, except LoadByManager & AddOnly Action. Introduced in v5.0a; last changed in v5.0a Description

Bid Request Description
Description for bid request. Type: String Optional If defined for an Action, the Description property cannot be null. The Description property MUST be less than or equal to 255 characters in length. Introduced in v5.0a; last changed in v5.0a GroupScheduleProfileName

Group Schedule Profile Name
Name of Access Profile that governs the set of Group Schedules from which bidding participants can choose. Applies only to bidding type 'Shift By Group Schedule'. Type: String

144

Kronos Incorporated

BidRequest Tag

Required Key If defined for an Action, the GroupScheduleProfileName cannot be null. If the Type property is set to the shift by group schedule bidding type, then the GroupScheduleProfileName MUST be defined, and the VacationPayCodeName and other 2 Profile Names NOT. Introduced in v5.0a; last changed in v5.0a Manager

Bid Request Owner
Owner of bid request. Type: PersonIdentity tag Required Key If defined for an Action, the Manager property cannot be null. The PersonIdentity tag must be specified in the Manager property. The Manager property MUST be specified for the AddOnly and the LoadByManager Actions. Sample values: <Manager> <PersonIdentity PersonNumber="207"> </PersonIdentity> </Manager> Introduced in v5.0a; last changed in v5.0a MaxBids

Max Bids
Maximum number of bids allowed. Type: Integer Optional If the property is defined for an Action, the MaxBids property cannot be null. The MaxBids property MUST be greater than or equal to 1. The MaxBids property MUST be specified for the AddOnly Action. Introduced in v5.0a; last changed in v5.0a

Workforce Central Developers Toolkit Reference Guide—Timekeeping

145

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Name

Bid Request Name
Name for the bid request. Type: String Optional If defined for an Action, the Name property cannot be null. The Name property MUST be less than or equal to 30 characters. The Name property MUST be specified for the AddOnly Action. Introduced in v5.0a; last changed in v5.0a NotificationDate

Notification Date
Date on which notification about this bid request was last sent to bidding participants. Type: DateTime Optional If defined for an Action, the Notification cannot be null. Sample values: "04/20/2004 11:48:56" Introduced in v5.0a; last changed in v5.0a PeriodEndDate

Period End Date
Bid End Date for target bidding period. Type: DateTime Optional If defined for an Action, the PeriodEndDate cannot be null. The PeriodEndDate MUST be specified for the AddOnly Action.

146

Kronos Incorporated

BidRequest Tag

Sample values: "04/20/2004 11:48:56" Introduced in v5.0a; last changed in v5.0a PeriodStartDate

Bid Period Start Date
Start Date for the target bidding period. Type: DateTime Optional If defined for an Action, the PeriodStartDate cannot be null. The PeriodStartDate property MUST be specified for the AddOnly Action. Sample values: "04/20/2004 00:00:00" Introduced in v5.0a; last changed in v5.0a SchedulePatternProfileName

Schedule Pattern Profile Name
Name of Access Profile that governs the set of Schedule Patterns from which bidding participants can choose. Applies only to bidding type 'Shift By Pattern'. Type: String Required Key If defined for an Action, the SchedulePatternProfileName cannot be null. If the Type property is set to the shift by pattern bidding type, then the SchedulePatternProfileName MUST be defined, and the VacationPayCodeName and other 2 Profile Names NOT. Introduced in v5.0a; last changed in v5.0a ShfitCodeProfileName

Shift Code Profile Name

Workforce Central Developers Toolkit Reference Guide—Timekeeping

147

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Name of Access Profile that governs the set of Shift Codes from which bidding participants can choose. Applies only to bidding type 'Shift By Day'. Type: String Required Key If defined for an Action, the ShiftCodeProfileName cannot be null. If the Type property is set to the shift by day bidding type, then only the ShiftCodeProfileName MUST be specified, the VacationPayCodeName and other 2 Profile Name properties MUST NOT. Introduced in v5.0a; last changed in v5.0a Status

Status
Status for bid request. Type: String Output only The Status property MUST NOT be defined or specified for any BidRequest Action. Default value: 0 - Not Ready Enumerated value: 0 - Not Ready, 1 - Ready, 2 - Done, 3 - Posted Introduced in v5.0a; last changed in v5.0a Type

Bid Type
Identifies the bidding type. Type: String Required Key If defined for an Action, the Type property cannot be null. The Type property can only be 1 of 4 Bidding Types - Vacation, Shift By Day, Shift By Pattern, or Shift By Group Schedule. The Type property MUST be specified for the AddOnly Action.

148

Kronos Incorporated

BidRequest Tag

Introduced in v5.0a; last changed in v5.0a VacationPayCodeName

Vacation Pay Code Name
Name of Pay Code to use for vacation. Applies only for bidding type 'Vacation'. Type: String Required Key If defined for an Action, the VacationPayCodeName cannot be null. If the Type property is set to the vacation bidding type, then only the VacationPayCodeName MUST be specified, the other 3 ProfileName properties MUST NOT be defined. Introduced in v5.0a; last changed in v5.0a

Workforce Central Developers Toolkit Reference Guide—Timekeeping

149

Chapter 2

Workforce Timekeeper XML API Tag Definitions

BulkAccruals Tag Set of Accruals for Employees
The BulkAccruals tag identifies a set of accruals for one or more employees during a specified time period. Function Access Control Point: API.BulkSummary Introduced in v4; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadAccruals" Parameters→ None Properties→ <BulkAccruals AccrualCodeNames = String > (<EmployeeSummary> <EmployeeSummary> </EmployeeSummary>) <Employees> <PersonIdentity> </Employees> <Period> <TimeFramePeriod> </Period> </BulkAccruals>

Action Descriptions

150

Kronos Incorporated

BulkAccruals Tag

LoadAccruals Returns detailed data about the specified set of accruals. This action uses the EmployeeSummary tag, which in turn uses the AccrualBalanceSummary tag to list details about the specified accruals. Return Value Type: Zero or more EmployeeSummary tags Required Properties: Employees, AccrualCodeNames, Period Access Control Point Name: View Introduced in v4

Property Descriptions
AccrualCodeNames

Accrual code names
A comma-separated list of accrual code names. The accrual codes are created in Timekeeper and must be assigned to the employee before you can import data against them. Type: String Required Maximum length: Limited by your system environment settings You can find values in the Setup Application. Sample values: Vacation, Sick Introduced in v4 Employees

Employees
One or more people, as specified in a PersonIdentity tag, for whom accruals are requested. Type: PersonIdentity tag

Workforce Central Developers Toolkit Reference Guide—Timekeeping

151

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required Introduced in v4 EmployeeSummary

Employee Summary
The Employee Summary contains either accruals or totals for an employee along with PersonNumber. Type: EmployeeSummary tag Output only Introduced in v5.2 Period

Time period
Two timeframes are supported: • • 1 or Current_Pay_Period 13 or Today

Type: TimeFramePeriod tag Required Enumerated value: 1, 13 Introduced in v4; last changed in v5.0

152

Kronos Incorporated

BulkTotals Tag

BulkTotals Tag Bulk Totals
The BulkTotals tag identifies a list of employees, a list of pay code names, and a time period. Function Access Control Point: API.BulkSummary Introduced in v4; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadPayCodeTotals" Parameters→ None Properties→ <BulkTotals PayCodeNames = String > (<EmployeeSummary> <EmployeeSummary> </EmployeeSummary>) <Employees> <PersonIdentity> </Employees> <Period> <TimeFramePeriod> </Period> </BulkTotals>

Action Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

153

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LoadPayCodeTotals Returns totals for a given list of employees in their respective current pay periods. Return Value Type: Zero or more EmployeeSummary tags Required Properties: Employees, PayCodeNames, Period Access Control Point Name: View Introduced in v4

Property Descriptions
Employees

Employees
One or more people, as specified in a PersonIdentity tag, for whom totals are requested. Type: PersonIdentity tag Required Introduced in v4 EmployeeSummary

Employee Summary
The Employee Summary contains either accruals or totals for an employee along with PersonNumber. Type: EmployeeSummary tag Output only Introduced in v5.2; last changed in v5.2 PayCodeNames

Pay codes
A comma-separated list of pay code names Type: String Required

154

Kronos Incorporated

BulkTotals Tag

Introduced in v4 Period

Time period
Two timeframes are supported: • • 1 or Current_Pay_Period 13 or Today

Type: TimeFramePeriod tag Required Default value: 1, 13 Introduced in v4; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

155

Chapter 2

Workforce Timekeeper XML API Tag Definitions

CalendarProfile Tag Calendar Profile
This tag creates a calendar profile. Calendar profiles are the basis for the calendars that are displayed for managers or employees. A calendar profile includes one or more generic calendars, or it can include a calendar data set associated with a specific application such as timekeeping or scheduling. Function Access Control Point: Calendar framework Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Add" | "AddOnly" | "Delete" | "RetrieveAll" | "RetrieveAllByName" | "RetrieveAllByNameAndActive" | "RetrieveById" | "RetrieveByName" | "Update" Parameters→ None Properties→ <CalendarProfile Name = String [Description = String] [GenericEmployeeCalendarNames = String list] [GenericManagerCalendarNames = String list] [Active = Boolean] > [<ApplicationCalendars>

156

Kronos Incorporated

CalendarProfile Tag

<ApplicationCalendar>* </ApplicationCalendars>] </CalendarProfile>

Action Descriptions
Add Creates or modifies a calendar profile. If a calendar profile exists with the same name, it is modified. If no calendar profile with that name exists, a new one is created. Return Value Type: None Required Properties: Name, Description, Active Optional Properties: GenericEmployeeCalendarNames, GenericManagerCalendarNames, ApplicationCalendars Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 AddOnly Adds a calendar profile. If a calendar profile exists with the same name, the operation will fail. Return Value Type: None Required Properties: Name, Description, Active Optional Properties: GenericEmployeeCalendarNames, GenericManagerCalendarNames, ApplicationCalendars Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 Delete Deletes an existing calendar profile. The operation will fail if the calendar profile doesn't exist. Return Value Type: None Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

157

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RetrieveAll Returns all calendar profiles. Return Value Type: Zero or more CalendarProfile tags Access Control Point Name: View Introduced in v5.1; last changed in v5.1 RetrieveAllByName Searches for calendar profiles by name and returns a list of calendar profiles. Return Value Type: Zero or more CalendarProfile tags Required Properties: Name Access Control Point Name: View Introduced in v5.1; last changed in v5.1 RetrieveAllByNameAndActive Searches for calendar profiles by name and active, and returns a list of calendar profiles. Return Value Type: Zero or more CalendarProfile tags Required Properties: Name, Active Access Control Point Name: View Introduced in v5.1; last changed in v5.1 RetrieveById Returns the specified calendar profile. The operation will fail if the calendar profile doesn't exist. Return Value Type: CalendarProfile tag Access Control Point Name: View Introduced in v5.1; last changed in v5.1 RetrieveByName Returns the specified calendar profile. The operation will fail if the calendar profile doesn't exist. Return Value Type: CalendarProfile tag Required Properties: Name

158

Kronos Incorporated

CalendarProfile Tag

Access Control Point Name: View Introduced in v5.1; last changed in v5.1 Update Updates an existing calendar profile. If the calendar profile doesn't exist, it will be added. Return Value Type: None Required Properties: Name Optional Properties: NewName, Description, Active, GenericEmployeeCalendarNames, GenericManagerCalendarNames, ApplicationCalendars Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1

Property Descriptions
Active

Is the calendar profile active?
True if the calendar profile is active, false if it is inactive. Type: Boolean Optional Sample values: True False Enumerated value: True, False Introduced in v5.1; last changed in v5.1 ApplicationCalendars

Application calendars
The list of the application calendars in a calendar profile.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

159

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: Zero or more ApplicationCalendar tags Optional Introduced in v5.1; last changed in v5.1 Description

Description
The description of a calendar profile. Type: String Optional Introduced in v5.1; last changed in v5.1 GenericEmployeeCalendarNames

Generic employee calendar names
The names of the generic employee calendars in a calendar profile. Type: String list Optional Introduced in v5.1; last changed in v5.1 GenericManagerCalendarNames

Generic manager calendar Ids
The names of the generic manager calendars in a calendar profile. Type: String list Optional Introduced in v5.1; last changed in v5.1 Name

Calendar profile name
The unique name of a calendar profile. Type: String

160

Kronos Incorporated

CalendarProfile Tag

Required Key Introduced in v5.1; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

161

Chapter 2

Workforce Timekeeper XML API Tag Definitions

CalendarProfileAPIFacade Tag Calendar Profile
This tag is the basis for the calendars that are displayed for managers or employees. A calendar profile typically includes one or more generic calendars, but you can also create a calendar profile that does not include any generic calendar. Function Access Control Point: Calendar Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveAllNames" | "RetrieveForUpdate" | "Update" Parameters→ None Properties→ <CalendarProfileAPIFacade Name = String > </CalendarProfileAPIFacade>

Action Descriptions
RetrieveAllNames Retrieves all names of calendar profiles. Return Value Type: Zero or more NameList tags Access Control Point Name: View

162

Kronos Incorporated

CalendarProfileAPIFacade Tag

Introduced in v5.2 RetrieveForUpdate Retrieves the calendar profile corresponding to the specified name. Return Value Type: CalendarProfileAPIFacade tag Required Properties: Name Access Control Point Name: View Introduced in v5.2 Update Updates the calendar profile Return Value Type: None Required Properties: Name Access Control Point Name: Edit Introduced in v5.2

Property Descriptions
Name

Name
The calendar profile name. Type: String Required Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

163

Chapter 2

Workforce Timekeeper XML API Tag Definitions

CallListEmployee Tag Employee on Call List
This tag provides a list of employees that are qualified and available to fill an open shift. Function Access Control Point: Relief Management Introduced in v6.0

Syntax None

164

Kronos Incorporated

CallListOpenShift Tag

CallListOpenShift Tag Open Shift from Call List
This tag provides a list of open shifts that a qualified and available employee can fill. Function Access Control Point: Relief Management Introduced in v6.0

Syntax None

Workforce Central Developers Toolkit Reference Guide—Timekeeping

165

Chapter 2

Workforce Timekeeper XML API Tag Definitions

CancelDeductions Tag Cancel Deductions
The CancelDeductions tag denotes a request from Data Collection Manager (DCM) to cancel all deductions for a specified date and time. You can use the Update action to locate the nearest shift overlapping or prior to the given date and time, as long as it is within a twenty-four-hour period. If found, the shift will be flagged as if its auto-deductions are canceled. This action is comparable to flagging a punch in the Timecard editor and canceling all deductions. Function Access Control Point: API.Timecard Introduced in v4; last changed in v5.0a

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Update" Parameters→ None Properties→ <CancelDeductions Date = Date [ManagerName = String] Time = Time > <Employee> <CurrentUser> | <PersonIdentity> </Employee> </CancelDeductions>

166

Kronos Incorporated

CancelDeductions Tag

Action Descriptions
Update Flags the indicated shift so that automatic deductions are not applied to the totals for that shift. Return Value Type: None Required Properties: Employee, Date, Time Access Control Point Name: Edit Introduced in v4

Property Descriptions
Date

Date of cancellation
The date of the cancellation. Type: Date Required Introduced in v4 Employee

Employee
One employee whose deductions are being canceled, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Required Must uniquely identify an existing and active employee Introduced in v4 ManagerName

Manager name
The name used to replace the user name in audit.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

167

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: String Optional Maximum length: 70 characters Introduced in v5.0a Time

Time of cancellation
The time of the cancellation. The Time and Date form a timestamp. If a shift overlaps the 23:59 preceding this timestamp, auto-deductions will be canceled for that shift. Otherwise, the cancellation has no effect. Type: Time Required Introduced in v4

168

Kronos Incorporated

CertificationItem Tag

CertificationItem Tag Certification Item
The CertificationItem tag defines an item in the certification. Used by: PersonCertificationAssign Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.0

Syntax
Properties→ <CertificationItem [Abbreviation = String] Name = String [IsActive = Boolean] > </CertificationItem>

Property Descriptions
Abbreviation

Abbreviation for the certification item
Abbreviation for the certification Type: String Optional Maximum length: 5 characters Introduced in v5.0 IsActive

Is the rule type active?
If True, the specified rule type is active. Type: Boolean

Workforce Central Developers Toolkit Reference Guide—Timekeeping

169

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Enumerated value: True, False Introduced in v5.0 Name

Certification item name
The unique name of the certification item Type: String Required Maximum length: 40 characters Introduced in v5.0

170

Kronos Incorporated

CheckAdvice Tag

CheckAdvice Tag Earnings History
The CheckAdvice tag provides earnings history information for the specified employee. Function Access Control Point: API.PayrollAddOns Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" Parameters→ None Properties→ <CheckAdvice CheckNumber = String CheckDate = Date EndDate = Date [GrossPay = String] PaymentType = String NetPay = String StartDate = Date [Taxes = String] [TotalHours = String] [Deductions = String] > [<DirectDepositList> <CheckAdviceDetailDirectDeposit>* </DirectDepositList>] <Employee> <CurrentUser> | <PersonIdentity> </Employee>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

171

Chapter 2

Workforce Timekeeper XML API Tag Definitions

[<DeductionsList> <CheckAdviceDetailDeductions>* </DeductionsList>] [<GrossPayList> <CheckAdviceDetailGrossPay>* </GrossPayList>] [<TaxesList> <CheckAdviceDetailTaxes>* </TaxesList>] </CheckAdvice>

Action Descriptions
AddOnly Adds a pay stub to the database. If one already exists with the same key, it is overwritten by the new one. Dates must be valid dates Return Value Type: None Required Properties: Employee, CheckNumber, CheckDate, NetPay, StartDate, EndDate, PaymentType Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0

Property Descriptions
CheckDate

Date of check
Payment date Type: Date Required Introduced in v5.0; last changed in v5.0 CheckNumber

Check number

172

Kronos Incorporated

CheckAdvice Tag

The check number for this transaction Type: String Required Key Maximum length: 50 characters Introduced in v5.0; last changed in v5.0 Deductions

Total of all deductions
The total amount of deductions that applied to the payment Type: String Optional Maximum length: 50 characters Introduced in v5.0; last changed in v5.0 DeductionsList

List of deductions
One or more deductions that were applied to the payment. Type: Zero or more CheckAdviceDetailDeductions tags Optional If there are any values in DeductionsList, then Deductions must be specified. Introduced in v5.0; last changed in v5.0 DirectDepositList

Direct deposit details
Details about the direct deposit of the check Type: Zero or more CheckAdviceDetailDirectDeposit tags Optional Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

173

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Employee

Employee
One employee, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Required Must uniquely identify an existing and active employee Introduced in v5.0; last changed in v5.0 EndDate

End date of pay period
The end date for the pay period for which the check is drawn Type: Date Required Introduced in v5.0; last changed in v5.0 GrossPay

Gross pay
The amount of the check before adjustments are made Type: String Optional Maximum length: 50 characters Introduced in v5.0; last changed in v5.0 GrossPayList

List of gross pay details
Details about the gross payment for the check. May not be specified if GrossPay property is not specified. Type: Zero or more CheckAdviceDetailGrossPay tags Optional

174

Kronos Incorporated

CheckAdvice Tag

Introduced in v5.0; last changed in v5.0 NetPay

Net pay
The gross pay with adjustments, such as deductions and taxes, applied Type: String Required Maximum length: 50 characters Introduced in v5.0; last changed in v5.0 PaymentType

Method of payment
The method of payment Type: String Required Maximum length: 50 characters Sample values: Direct Deposit, Check Introduced in v5.0; last changed in v5.0 StartDate

Start date of pay period
The start of the pay period for which the check is drawn Type: Date Required Introduced in v5.0; last changed in v5.0 Taxes

Taxes

Workforce Central Developers Toolkit Reference Guide—Timekeeping

175

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Total amount of taxes for items identified as detail taxes that is deducted from the gross payment Type: String Optional Maximum length: 50 characters Introduced in v5.0; last changed in v5.0 TaxesList

List of taxes
Details about the taxes applied to the check. Dependency: May not be specified if the Taxes property is not specified. Type: Zero or more CheckAdviceDetailTaxes tags Optional Introduced in v5.0; last changed in v5.0 TotalHours

Total hours
The total number of hours for which the employee is being paid Type: String Optional Maximum length: 50 characters Introduced in v5.0; last changed in v5.0

176

Kronos Incorporated

CheckAdviceDetailDeductions Tag

CheckAdviceDetailDeductions Tag Earnings History - Deduction
The CheckAdviceDetailDeductions tag describes a deduction in the employee's earnings history. Used by: CheckAdvice Function Access Control Point: API.PayrollAddOns Introduced in v5.0; last changed in v5.0

Syntax
Properties→ <CheckAdviceDetailDeductions Amount = String Description = String EmployeePaid = String AmountYTD = String EmployeePaidYTD = String > </CheckAdviceDetailDeductions>

Property Descriptions
Amount

Amount of deduction
Amount of the specified deduction Type: String Required Introduced in v5.0; last changed in v5.0 AmountYTD

Year to date total
A cumulative year to date amount for this deduction

Workforce Central Developers Toolkit Reference Guide—Timekeeping

177

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: String Required Introduced in v5.0; last changed in v5.0 Description

Description
An explanation of the deduction Type: String Required Introduced in v5.0; last changed in v5.0 EmployeePaid

Portion paid by employee
The portion of the deduction that is paid by the employee Type: String Required Introduced in v5.0; last changed in v5.0 EmployeePaidYTD

Year to date total paid by employee
The year to date portion of the deduction that is paid by the employee Type: String Required Introduced in v5.0; last changed in v5.0

178

Kronos Incorporated

CheckAdviceDetailDirectDeposit Tag

CheckAdviceDetailDirectDeposit Tag Earnings History - Direct Deposit
The CheckAdviceDetailDirectDeposit tag describes details about a direct deposit. Used by: CheckAdvice Function Access Control Point: API.PayrollAddOns Introduced in v5.0; last changed in v5.1

Syntax
Properties→ <CheckAdviceDetailDirectDeposit AccountNumber = String Amount = String Description = String RoutingNumber = String > </CheckAdviceDetailDirectDeposit>

Property Descriptions
AccountNumber

Account number
The account number to which the direct deposit is posted. Type: String Required Introduced in v5.0; last changed in v5.1 Amount

Amount of deposit
Amount of the direct deposit Type: String Required

Workforce Central Developers Toolkit Reference Guide—Timekeeping

179

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.0; last changed in v5.0 Description

Description
An explanation of the item listed for the direct deposit Type: String Required Introduced in v5.0; last changed in v5.0 RoutingNumber

Routing number
The routing number of the bank to which the direct deposit is posted. Type: String Required Introduced in v5.0; last changed in v5.1

180

Kronos Incorporated

CheckAdviceDetailGrossPay Tag

CheckAdviceDetailGrossPay Tag Earnings History - Gross Pay
The CheckAdviceDetailGrossPay tag identifies a gross pay detail. Used by: CheckAdvice Function Access Control Point: API.PayrollAddOns Introduced in v5.0; last changed in v5.0

Syntax
Properties→ <CheckAdviceDetailGrossPay Amount = String Date = Date Description = String Hours = String Rate = String AmountYTD = String > </CheckAdviceDetailGrossPay>

Property Descriptions
Amount

Amount of gross pay
Gross pay amount Type: String Required Introduced in v5.0; last changed in v5.0 AmountYTD

Year to date total
Gross year to date pay amount

Workforce Central Developers Toolkit Reference Guide—Timekeeping

181

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: String Required Introduced in v5.0; last changed in v5.0 Date

Date of check
Date of the check Type: Date Required Introduced in v5.0; last changed in v5.0 Description

Description
The explanation that the specified amount is the gross pay Type: String Required Introduced in v5.0; last changed in v5.0 Hours

Hours paid
Number of hours for which payment is made Type: String Required Must match an existing field definition name Introduced in v5.0; last changed in v5.0 Rate

Pay rate
Rate at which payment was made

182

Kronos Incorporated

CheckAdviceDetailGrossPay Tag

Type: String Required Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

183

Chapter 2

Workforce Timekeeper XML API Tag Definitions

CheckAdviceDetailTaxes Tag Earnings History - Taxes
The CheckAdviceDetailTaxes tag describes details about a tax that is part of the employee's earnings history. Used by: CheckAdvice Function Access Control Point: API.PayrollAddOns Introduced in v5.0; last changed in v5.0

Syntax
Properties→ <CheckAdviceDetailTaxes Amount = String Description = String TaxableWages = String TaxesYTD = String > </CheckAdviceDetailTaxes>

Property Descriptions
Amount

Amount of tax
Amount of the specified tax Type: String Required Introduced in v5.0; last changed in v5.0 Description

Description
An explanation of the specified tax Type: String

184

Kronos Incorporated

CheckAdviceDetailTaxes Tag

Required Introduced in v5.0; last changed in v5.0 TaxableWages

Taxable wages
Wages for which taxes are paid Type: String Required Introduced in v5.0; last changed in v5.0 TaxesYTD

Year to date total for taxes
The cumulative year to date taxes for this taxable item reported with this check Type: String Required Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

185

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Comment Tag Comment
The Comment tag denotes additional text assigned to a punch, pay code edit, or other timekeeping tags. The Comment and WSAComment tags refer to the same database object. Function Access Control Point: API.Audit Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadActiveComments" | "LoadCommentCategories" Parameters→ None Properties→ <Comment [CommentCategory = String] (CommentText = String) > [<Notes> <Note>* </Notes>] </Comment>

Action Descriptions
LoadActiveComments Returns a list of active comments. Return Value Type: Zero or more Comment tags

186

Kronos Incorporated

Comment Tag

Access Control Point Name: View Introduced in v4 LoadCommentCategories Returns a list of comment beans with CommentCategory properties set to all categories available in the system. Return Value Type: Zero or more Comment tags Access Control Point Name: View Introduced in v5.1

Property Descriptions
CommentCategory

Comment category
Specify the comment category name string. Only the comments for the given category will be loaded. If unspecified, all active comments will be loaded. If the name is invalid, an empty result will be return (no error). Type: String Optional None Sample values: SHIFTS Default value: null Introduced in v5.0 CommentText

Comment text
A comment that can be attached to another record. Comments can be returned for a specified category or for all categories. Type: String

Workforce Central Developers Toolkit Reference Guide—Timekeeping

187

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Output Only Maximum length: 254 characters Introduced in v4 Notes

Comment Notes
The list of notes for the comment Type: Zero or more Note tags Optional Introduced in v6.0

188

Kronos Incorporated

ConnectToSchedule Tag

ConnectToSchedule Tag Schedule Import
The ConnectToSchedule tag imports an employee's scheduled shifts from another application into the scheduler. Function Access Control Point: API.Schedule Introduced in v5.1; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Update" Parameters→ None Properties→ <ConnectToSchedule <ConnectToScheduleItems> <ConnectToScheduleItem>* </ConnectToScheduleItems> </ConnectToSchedule>

Action Descriptions
Update Adds the specified items into schedule period Return Value Type: None Required Properties: ConnectToScheduleItems Access Control Point Name: Edit

Workforce Central Developers Toolkit Reference Guide—Timekeeping

189

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.1

Property Descriptions
ConnectToScheduleItems

Schedule items to import
One or more ConnectToScheduleItem tags. Taken together, these items define the values that form a shift. Type: Zero or more ConnectToScheduleItem tags Required Introduced in v5.1

190

Kronos Incorporated

ConnectToScheduleItem Tag

ConnectToScheduleItem Tag Schedule Import Items
This tag contains schedule import elements that are used by another application to import shifts into the Scheduler. Function Access Control Point: API.Schedule Introduced in v5.1; last changed in v6.0

Syntax
Properties→ <ConnectToScheduleItem [CommentText = String] [StartDate = Date] EmployeeId = String [LaborAccountName = String] [OrgJobPath = String] RequestCode = Integer [Duration = TimeDuration] [StartTime = Time] [WorkRuleName = String] > [<Notes> <Note>* </Notes>] </ConnectToScheduleItem>

Property Descriptions
CommentText

Comment
A comment about the shift Type: String Optional Maximum length: 255 characters

Workforce Central Developers Toolkit Reference Guide—Timekeeping

191

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.1 Duration

Time duration of shift
The duration of the shift Type: TimeDuration Optional Introduced in v5.1 EmployeeId

Employee Id
The unique employee id Type: String Required Key Must identify an existing and active employee Introduced in v5.1 LaborAccountName

Labor account
The labor account for the schedule shift being imported Type: String Optional LaborAccountName and OrgJobPath are mutually exclusive. Introduced in v5.1 Notes

Comment Notes
The list of notes for the comment to be created from comment text Type: Zero or more Note tags

192

Kronos Incorporated

ConnectToScheduleItem Tag

Optional Introduced in v6.0 OrgJobPath

Location of job in the organization
The fully qualified path name for an organizational job Type: String Optional OrgJobPath and LaborAccountName are mutually exclusive. Introduced in v5.1 RequestCode

RequestCode
A code that represents a request, where: DELETE_CODE = 10; BEGIN_SHIFT_CODE = 11; INSERT_BREAK_CODE = 12; INSERT_TRANSFER_CODE = 13; END_SHIFT_CODE = 14; OFF_DAY_CODE = 15; DELETE_SHIFT_CODE = 16; INSERT_OFF_DAY_CODE_COMMENT = 17; INSERT_SHIFT_CODE_COMMENT = 21; OFF_SHIFT_CODE = 41; INSERT_OFF_SHIFT_CODE_COMMENT = 42. Type: Integer Required Enumerated value: 10, 11, 12, 13, 14, 15, 16, 17, 21, 41, 42 Introduced in v5.1; last changed in v5.1 StartDate

Date when a shift starts
The date when a shift starts Type: Date Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

193

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.1 StartTime

Time when a shift starts
Time when a shift starts Type: Time Optional Introduced in v5.1 WorkRuleName

Work rule name
Name of the work rule Type: String Optional Introduced in v5.1

194

Kronos Incorporated

CoverageDetail Tag

CoverageDetail Tag Coverage Detail
This tag returns the daily coverage (required/scheduled) for the location and date range selected for every job in locations and for every time span. Function Access Control Point: Schedule Planner Introduced in v6.0

Syntax None

Workforce Central Developers Toolkit Reference Guide—Timekeeping

195

Chapter 2

Workforce Timekeeper XML API Tag Definitions

CoverageSettings Tag Coverage settings
This tag determines how to calculate coverage measures and how to present them. A coverage setting may be associated to each location type in the organizational map. Function Access Control Point: Location Settings Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Add" | "AddOnly" | "Delete" | "DeleteOnly" | "Retrieve" | "RetrieveAll" | "RetrieveAllForUpdate" | "RetrieveAllNames" | "RetrieveForUpdate" | "Update" | "UpdateOnly" Parameters→ None Properties→ <CoverageSettings SettingsName = String [Description = String] > [<SettingsParamValues> <SettingsParamValue>*

196

Kronos Incorporated

CoverageSettings Tag

</SettingsParamValues>] [<OrgPaths> <SimpleValue>* </OrgPaths>] </CoverageSettings>

Action Descriptions
Add Add a coverage type setting object into the system. If it already exists an update is performed. Return Value Type: None Required Properties: SettingsName Optional Properties: Description, SettingsParamValues, OrgPaths Access Control Point Name: Edit Introduced in v6.0 AddOnly Add a coverage type setting object into the system. If it already exists an error is thrown. Return Value Type: None Required Properties: SettingsName Optional Properties: Description, SettingsParamValues, OrgPaths Access Control Point Name: Edit Introduced in v6.0 Delete Delete a coverage type settings object. If the object doesn't exist, no exception will be thrown. Return Value Type: None Required Properties: SettingsName Access Control Point Name: Edit Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

197

Chapter 2

Workforce Timekeeper XML API Tag Definitions

DeleteOnly Delete a coverage type settings object. If doesn't exist an exception is thrown. Return Value Type: None Required Properties: SettingsName Access Control Point Name: View Introduced in v6.0 Retrieve Return the coverage type setting object by name. Return Value Type: (***undefined***): CoverageSetting Required Properties: SettingsName Access Control Point Name: View Introduced in v6.0 RetrieveAll Return all the coverage type setting objects. Return Value Type: Zero or more CoverageSettings tags Access Control Point Name: View Introduced in v6.0 RetrieveAllForUpdate Return a list of coverage type setting objects. This action is used for future updates. Return Value Type: Zero or more CoverageSettings tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Return the coverage type setting name objects. Return Value Type: (***undefined***): KBusinessObjectNameList Access Control Point Name: View Introduced in v6.0

198

Kronos Incorporated

CoverageSettings Tag

RetrieveForUpdate Return the coverage type setting object. This action is used for future updates. Return Value Type: CoverageSettings tag Required Properties: SettingsName Access Control Point Name: View Introduced in v6.0 Update Update the coverage type setting object.If it does not exist an add is performed. Return Value Type: None Required Properties: SettingsName Optional Properties: Description, SettingsParamValues, OrgPaths Access Control Point Name: Edit Introduced in v6.0 UpdateOnly Update a coverage type setting object. If it does not exist an error is thrown. Return Value Type: None Required Properties: SettingsName Optional Properties: Description, SettingsParamValues, OrgPaths Access Control Point Name: Edit Introduced in v6.0

Property Descriptions
Description

Coverage settings object description
Specify a description for the coverage settings. Type: String Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

199

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Sample values: <CoverageSettings SettingsName="coverage setting 3" Description="sample setting"> Introduced in v6.0; last changed in v6.0 OrgPaths

Location paths
Specify the list of associated organizational location type paths. Type: Zero or more SimpleValue tags Optional Must be existing locations on current date, and must be accessible to user. Sample values: <OrgPaths> <SimpleValue Value="Organization/Hospitals/Hosp A/ Floor 1" /> </OrgPaths> Introduced in v6.0; last changed in v6.0 SettingsName

Coverage settings name
Specify the coverage settings name. Type: String Required Key Sample values: <CoverageSettings SettingsName="coverage setting 3" Description="sample setting"> Introduced in v6.0; last changed in v6.0

200

Kronos Incorporated

CoverageSettings Tag

SettingsParamValues

Coverage settings parameter values
Specify the coverage settings parameter values. Type: Zero or more SettingsParamValue tags Optional Sample values: <SettingsParamValues> <SettingsParamValue Name="PARAM" Value="Test"/> </SettingsParamValues> Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

201

Chapter 2

Workforce Timekeeper XML API Tag Definitions

CoverageSettingsValue Tag Value of coverage setting parameter
This tag provides the coverage setting parameter associated with the organization path given in the request. Function Access Control Point: Location Settings Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveValue" Parameters→ RetrieveValue→ orgPath = String paramDefinitionName = String Properties→ <CoverageSettingsValue (Value = String) > </CoverageSettingsValue>

Action Descriptions
RetrieveValue Return a coverage setting value object. Return Value Type: CoverageSettingsValue tag Access Control Point Name: View Introduced in v6.0

202

Kronos Incorporated

CoverageSettingsValue Tag

Action Parameters Parameter Name orgPath Description Path of the location from which to find the setting and its parameter value. Required The name of parameter definition for which the value is requested. Required Must be an existing sched gen parameter defintion Additional information Introduced in v6.0

paramDefinitionName

Introduced in v6.0

Property Descriptions
Value

Parameter value
value of the parameter specified in the request, read from the setting matching the location specified in the request. Type: String Output only Sample values: <Response Status="Success" OrgPath="Organization/ Hospitals/Hosp A/Floor 3" Action="RetrieveValue" ParamDefinitionName="PERFECTCOVERAGE_CELL_COLOR"> <CoverageSettingsValue Value="FFFFFF"/> </Response> Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

203

Chapter 2

Workforce Timekeeper XML API Tag Definitions

CoverShiftStatus Tag Cover Shift Status
This tag represents result of daily status. Function Access Control Point: API.Schedule Introduced in v5.1; last changed in v5.1

Syntax
Properties→ <CoverShiftStatus (Date = Date) (IsShiftExists = Boolean) (IsShiftCovered = Boolean) > (<RequestToCoverItems> <RequestToCoverItem>* </RequestToCoverItems>) </CoverShiftStatus>

Property Descriptions
Date

Date
The date of the daily status. Type: Date Output only Introduced in v5.1 IsShiftCovered

Is the shift covered?
This property holds the result of whether the shift has been covered. Type: Boolean

204

Kronos Incorporated

CoverShiftStatus Tag

Output only Introduced in v5.1; last changed in v5.1 IsShiftExists

Does the shift exist?
This property holds the result of whether is the shift existing. Type: Boolean Output only Introduced in v5.1; last changed in v5.1 RequestToCoverItems

Date and time span of the shift
This property contains a set of shift's date time span information. Type: Zero or more RequestToCoverItem tags Output only Introduced in v5.1; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

205

Chapter 2

Workforce Timekeeper XML API Tag Definitions

CurrentUser Tag Currently Logged On User
The CurrentUser tag identifies the currently logged on user. This is a special instance of the PersonIdentity tag. It can be used wherever a PersonIdentity is allowed and CurrentUser is appropriate. However, if you specify CurrentUser, do not specify any property. When you specify the CurrentUser tag, the properties are all provided by the system. CurrentUser always represents the person making the request. Function Access Control Point: API.Common Introduced in v4; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadIdentities" Parameters→ None Properties→ <CurrentUser BadgeNumber = String EmployeeKey = Long PersonKey = Long PersonNumber = String UserKey = Long </CurrentUser>

Action Descriptions

206

Kronos Incorporated

CurrentUser Tag

LoadIdentities Returns current user information for the logged on user. Return Value Type: CurrentUser tag Required Properties: None Access Control Point Name: View Introduced in v4

Property Descriptions
BadgeNumber

Badge number
Contains an employee badge number that is assigned to the employee. The system can be configured to allow multiple badges for employees. Specify whether to allow multiple badge assignments in System Configuration System Settings Global Values global.BadgeAssignment.allowsOverlap = Yes. If an employee is assigned multiple badge numbers, each badge number and associated information is added in a separate request. If you want to remove a badge number, remove all existing badge numbers. Then reassign the valid number that you want to keep. Type: String Maximum length: 25 characters Must be unique for the specified date span. Validation is done after a person is associated with a badge, using the PersonInformation tag. Introduced in v4 EmployeeKey

Employee database key
The employee database key for the current user

Workforce Central Developers Toolkit Reference Guide—Timekeeping

207

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: Long Maximum value = 2,147,488, 848 Must identify only one person Introduced in v4; last changed in v5.0 PersonKey

Person database key
The person database key for the current user Type: Long Maximum value = 2,147,488, 848 Must identify only one person Introduced in v4; last changed in v5.0 PersonNumber

Person number
Person number of the specified person Type: String Maximum length: 15 characters Introduced in v4 UserKey

User database key
The database key for the current user Type: Long Maximum value = 2,147,488, 848 Must identify only one person Introduced in v4; last changed in v5.0

Groups of Mutually Exclusive Properties

208

Kronos Incorporated

CurrentUser Tag

Identifier A single value that identifies the current user Required Group includes: BadgeNumber, EmployeeKey, PersonKey, PersonNumber, UserKey

Workforce Central Developers Toolkit Reference Guide—Timekeeping

209

Chapter 2

Workforce Timekeeper XML API Tag Definitions

CustomData Tag Custom Data
The CustomData tag lets you specify information for individuals, such as a social security number or an alternate name. This function is the same as the Additional Information workspace in the People Editor. Function Access Control Point: API.Person Introduced in v4; last changed in v5.1

Syntax
Properties→ <CustomData Text = String CustomDataTypeName = String > </CustomData>

Property Descriptions
CustomDataTypeName

Type of custom data
The customer-defined label for custom string types. You must define the custom data type first using the Setup Application. Then you can use this property to specify custom strings. Type: String Required Key Maximum length: 30 characters Values for CustomDataTypeName are added to the system through the Setup Application. A maximum of ten custom strings can be included for a person. Sample values:

210

Kronos Incorporated

CustomData Tag

seniority number, mother's maiden name, Social Security Number Introduced in v4 Text

Text
The text of the custom string Type: String Required Maximum length: 80 characters Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

211

Chapter 2

Workforce Timekeeper XML API Tag Definitions

CustomDate Tag Custom Date
The CustomDate tag denotes Date type information for a site-specified Date category that can be assigned to a person. Used by: PersonInformation Function Access Control Point: API.Person Introduced in v4; last changed in v5.0

Syntax
Properties→ <CustomDate Date = Date CustomDateTypeName = String > </CustomDate>

Property Descriptions
CustomDateTypeName

Date name
Contains the name of a person-specific date for an employee Type: String Required Key Maximum length: 50 characters You can find values in the Workforce Timekeeper user interface. Sample values: 401K Enrollment Date Introduced in v4

212

Kronos Incorporated

CustomDate Tag

Date

Date
Specifies a custom date field to be used by the Person tag. Type: Date Required Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

213

Chapter 2

Workforce Timekeeper XML API Tag Definitions

CustomOperator Tag Sorting and Mathcing Rule Custom Operator
Gives access to sorting or matching rule's custom operator item objects of the Priority Scheduling Engine. Function Access Control Point: API.Priority Scheduling Engine Introduced in v6.0

Syntax
Properties→ <CustomOperator OperatorName = String Value = String > </CustomOperator>

Property Descriptions
OperatorName

Custom operator name
Represents the name of a sorting or matching rule custom operator. Type: String Required Key Introduced in v6.0 Value

Custom operator value
Represents the value of a sorting or matching rule custom operator. Type: String Required Introduced in v6.0

214

Kronos Incorporated

DataAccessGroup Tag

DataAccessGroup Tag DataAccessGroup
This tag specifies the schedule group that users who are assigned a specific data access profile can access and assign. Function Access Control Point: Regional Configuration Introduced in v6.0; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddGDAPItem" | "AddOnly" | "Delete" | "DeleteAllGDAPItem" | "DeleteGDAPItem" | "Duplicate" | "GetGDAPItemTypeList" | "Retrieve" | "RetrieveAll" | "RetrieveAllForUpdate" | "RetrieveAllNames" | "RetrieveForUpdate" | "Update" | "UpdateOnly" Parameters→ Retrieve→ AllowItemList [GDAPItemType RetrieveAll→ AllowItemList [GDAPItemType UpdateOnly→

= Boolean = String] = Boolean = String]

Workforce Central Developers Toolkit Reference Guide—Timekeeping

215

Chapter 2

Workforce Timekeeper XML API Tag Definitions

[NewName = String] Properties→ <DataAccessGroup Name = String [Description = String] > <GDAPItemList> <GDAPItem>* </GDAPItemList> </DataAccessGroup>

Action Descriptions
AddGDAPItem Add GDAPItemList to the existing GDAP The Retrieve method is the factory Action. Check whether GDAPItemList is empty Return Value Type: None Required Properties: Name, GDAPItemList Access Control Point Name: Edit Introduced in v6.0 AddOnly Create a new GDAP and Assign it the current User Check whether the Name property already in the Database Return Value Type: None Required Properties: Name Optional Properties: Description,GDAPItemList Access Control Point Name: Edit Introduced in v6.0 Delete Delete the GDAP and any associated GDAP Items Return Value Type: None

216

Kronos Incorporated

DataAccessGroup Tag

Required Properties: Name Access Control Point Name: Edit Introduced in v6.0 DeleteAllGDAPItem Delete all the GDAPItems that associated with this GDAP Return Value Type: None Required Properties: Name Access Control Point Name: Edit Introduced in v6.0 DeleteGDAPItem Delete the GDAP Items in the GDAPItemList Return Value Type: None Required Properties: Name,GDAPItemList Access Control Point Name: Edit Introduced in v6.0 Duplicate The name of an existing Generic Data Access Profile that will be duplicated. The Name should be the name of an existing Generic Data Access Profile. Return Value Type: None Required Properties: Name Access Control Point Name: Edit Introduced in v6.0 GetGDAPItemTypeList Return the dataAccessgroup object with an ArrayList of DAGEntity type it contains. Valid Generic Data Access group Profile Name is in user's context Return Value Type: DataAccessGroup tag Required Properties: Name

Workforce Central Developers Toolkit Reference Guide—Timekeeping

217

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: Edit Introduced in v6.0; last changed in v6.0 Retrieve Get GDAP with all asociate GDAP items if the GDAPItemType=True and GDAPItemType is not specified Check whether the GDAP Name is in User's context Return Value Type: DataAccessGroup tag Required Properties: Name Access Control Point Name: Edit Introduced in v6.0; last changed in v6.0
Action Parameters Parameter Name AllowItemList Description set AllowItemList=TRUE to get GDAPItems showed in the response Required Default value: False What kind of GDAPItemType you want to retrieve Optional Default value: False Additional information Introduced in v6.0; last changed in v6.0

GDAPItemType

Introduced in v6.0

RetrieveAll Retrieves a list of Data Access Groups Return Value Type: Collection Access Control Point Name: View Introduced in v6.0

218

Kronos Incorporated

DataAccessGroup Tag

Action Parameters Parameter Name AllowItemList Description set AllowItemList = true to indicate that you want the GDAP items showed in the response Required Default value: False What kind of GDAPItemType you want to retrieve Optional Default value: FALSE Additional information Introduced in v6.0; last changed in v6.0

GDAPItemType

Introduced in v6.0

RetrieveAllForUpdate Returns all Generic Data Access Profile for updating. Return Value Type: Zero or more DataAccessGroup tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Returns a list of the names of all Generic Data Access Profile in user's GDAP context Return Value Type: Zero or more NameList tags Access Control Point Name: View Introduced in v6.0; last changed in v6.0 RetrieveForUpdate Returns the specified Generic Data Access Profile for updating. Return Value Type: DataAccessGroup tag Required Properties: Name Access Control Point Name: View Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

219

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Update Update the specified Generic Data Access Profile. The specified Generic Data Access Profile must in database. Return Value Type: None Required Properties: Name Access Control Point Name: Edit Introduced in v6.0 UpdateOnly Update the GDAP with Description or change the GDAP with the NewName Return Value Type: None Required Properties: Name Optional Properties: NewName, Description Access Control Point Name: Edit Introduced in v6.0; last changed in v6.0
Action Parameters Parameter Name NewName Description DataAccessGroup Name . The new name should be unique. Optional The new name should be unique. Additional information Introduced in v6.0; last changed in v6.0

Property Descriptions
Description

Description of the Data Access Group
Specity the description of the Data Access Group. Type: String Optional

220

Kronos Incorporated

DataAccessGroup Tag

Default value: NULL Introduced in v6.0 GDAPItemList

List of GDAP Items
Specify the list of generic data access profiles. Type: Zero or more GDAPItem tags Required This list cannot be empty. Introduced in v6.0; last changed in v6.0 Name

Data Access Group Name
Specify a unique name for the Data Access Group. The name is also used by Retrievel, AddOnly, Delete, UpdateOnly, DeleteGDAPItem, DeleteAllGDAPItem, and GetGDAPItemTypeList. Type: String Required The Name must be unique Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

221

Chapter 2

Workforce Timekeeper XML API Tag Definitions

DataElementAPIFacade Tag Calendar Data Element Facade
Creates or modifies Data Elements using the SDM API. Function Access Control Point: API.CALENDAR_VIEWS_SETUP Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveAllNames" | "RetrieveForUpdate" | "Update" Parameters→ None Properties→ <DataElementAPIFacade Name = String > </DataElementAPIFacade>

Action Descriptions
RetrieveAllNames Retrieves All Names Return Value Type: Zero or more NameList tags Access Control Point Name: View Introduced in v5.2

222

Kronos Incorporated

DataElementAPIFacade Tag

RetrieveForUpdate Retrieve for update through SDM Return Value Type: DataElementAPIFacade tag Required Properties: Name Access Control Point Name: View Introduced in v5.2 Update Updates using SDM Return Value Type: None Required Properties: Name Access Control Point Name: Edit Introduced in v5.2

Property Descriptions
Name

Name
Name Type: String Required Key Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

223

Chapter 2

Workforce Timekeeper XML API Tag Definitions

DataSetAPIFacade Tag Calendar setup data
Creates or modifies setup data for a calendar view. Function Access Control Point: API.CALENDAR_VIEWS_SETUP Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveAllNames" | "RetrieveForUpdate" | "Update" Parameters→ None Properties→ <DataSetAPIFacade Name = String > </DataSetAPIFacade>

Action Descriptions
RetrieveAllNames Retrieves All names of Calendar Data Set objects. Return Value Type: Zero or more NameList tags Access Control Point Name: View Introduced in v5.2

224

Kronos Incorporated

DataSetAPIFacade Tag

RetrieveForUpdate Retrieves the Calendar Data Set object corresponding to the name. Return Value Type: DataSetAPIFacade tag Required Properties: Name Access Control Point Name: View Introduced in v5.2 Update Updates the Calendar data Set object corresponding to the name. Return Value Type: None Required Properties: Name Access Control Point Name: Edit Introduced in v5.2

Property Descriptions
Name

Name of calendar view
Name of the calendar view to be created or changed. Type: String Required Key Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

225

Chapter 2

Workforce Timekeeper XML API Tag Definitions

DataSource Tag Data Source
The DataSource tag identifies the location and meaning of a Timesheet item. Function Access Control Point: API.Audit Introduced in v4

Syntax
Properties→ <DataSource (ClientName = String) (FunctionalAreaCode = Integer) (ServerName = String) (UserName = String) > </DataSource>

Property Descriptions
ClientName

Client name
Name that specifies the client's identity Type: String Output Only Introduced in v4 FunctionalAreaCode

Code number of functional area
Code that specifies the function change being performed Type: Integer Output Only Introduced in v4

226

Kronos Incorporated

DataSource Tag

ServerName

Server name
Name representing the server Type: String Output Only Introduced in v4 UserName

User name
Name of the logged on user Type: String Output Only Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

227

Chapter 2

Workforce Timekeeper XML API Tag Definitions

DateTotals Tag Totals for a Date
The DateTotals tag returns a summary of totals for a particular date. Used by: Timesheet Function Access Control Point: API.Timecard Introduced in v4

Syntax
Properties→ <DateTotals (Date = Date) > (<Totals> <TotalSummary> </Totals>) </DateTotals>

Property Descriptions
Date

Date to which the totals apply
The date on which totals apply Type: Date Output only Introduced in v4 Totals

Set of Totals
A list of totals for this date, broken out by labor account and pay code Type: TotalSummary tag Output only

228

Kronos Incorporated

DateTotals Tag

Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

229

Chapter 2

Workforce Timekeeper XML API Tag Definitions

DeductRule Tag Deduct Rule
The DeductRule tag provides information about deduct rules. The DeductRule and WSABonusDeductRule tags refer to the same database object. Function Access Control Point: API.Rules Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadAllDeductRules" Parameters→ None Properties→ <DeductRule (DeductRuleName = String) > </DeductRule>

Action Descriptions
LoadAllDeductRules Returns all deduct rules in the system. Return Value Type: Zero or more DeductRule tags Access Control Point Name: View Introduced in v5.0; last changed in v5.0

Property Descriptions

230

Kronos Incorporated

DeductRule Tag

DeductRuleName

Deduct rule name
Name of the deduct rule Type: String Output only Maximum length: 50 characters Must be unique Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

231

Chapter 2

Workforce Timekeeper XML API Tag Definitions

DelegateAuthorityTask Tag DelegateAuthorityTask
DelegateAuthorityTask describes a delegation task that was requested and accepted by a delegate (proxy manager). A delegate can have delegation tasks from more than one delegator (manager). Use this tag to retrieve a delegate's delegation tasks. Function Access Control Point: API.DelegateAuthority Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveByProxyMgrPersonNumber" Parameters→ RetrieveByProxyMgrPersonNumber→ PersonNumber = String Properties→ <DelegateAuthorityTask (TaskString = String) (EndDate = Date) (TaskId = Long) (RoleProfileId = Long) (RoleName = String) (MgrName = String) (ProxyMgrName = String) (ProxyMgrId = String) ProxyMgrNumber = String (MgrId = String) (StartDate = Date) > </DelegateAuthorityTask>

232

Kronos Incorporated

DelegateAuthorityTask Tag

Action Descriptions
RetrieveByProxyMgrPersonNumber This action takes parameter PersonNumber of a delegate (the proxy manager). It retrieves a list of delegation tasks for the delegate. PersonNumber parameter is always required. This PersonNumber is the person number for the delegate (the proxy manager). Return Value Type: Zero or more DelegateAuthorityTask tags Required Properties: PersonNumber Access Control Point Name: View Introduced in v5.2; last changed in v5.2
Action Parameters Parameter Name PersonNumber Description The person number for the delegate (the proxy manager). Required This parameter is always required for the action. Additional information Introduced in v5.2

Property Descriptions
EndDate

End date of a delegate task
End date of a delegate task. Type: Date Output only Introduced in v5.2; last changed in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

233

Chapter 2

Workforce Timekeeper XML API Tag Definitions

MgrId

Proxy manager ID
Proxy manager's person ID. Type: String Output only Introduced in v5.2; last changed in v5.2 MgrName

Name of a manager
Manager's name. Type: String Output only Introduced in v5.2; last changed in v5.2 ProxyMgrId

Person ID of a proxy manager
Proxy manager's person ID. Type: String Output only Introduced in v5.2; last changed in v5.2 ProxyMgrName

Name of proxy manager
Proxy Manager's full name. Type: String Output only Introduced in v5.2; last changed in v5.2

234

Kronos Incorporated

DelegateAuthorityTask Tag

ProxyMgrNumber

Person number of a proxy manager
Proxy manager's person number. Type: String Required Key Introduced in v5.2; last changed in v5.2 RoleName

Name of a delegate role profile
Delegate role profile name. Type: String Output only Introduced in v5.2; last changed in v5.2 RoleProfileId

Id of a delegate role profile
Delegate role profile ID. Type: Long Output only Introduced in v5.2; last changed in v5.2 StartDate

Start date of a delegate task
Start Date of a delegate task. Type: Date Output only Introduced in v5.2; last changed in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

235

Chapter 2

Workforce Timekeeper XML API Tag Definitions

TaskId

ID of a delegate task
Delegate task ID. Type: Long Output only Introduced in v5.2; last changed in v5.2 TaskString

Description of a task
Task string. Type: String Output only Introduced in v5.2; last changed in v5.2

236

Kronos Incorporated

DelegateProfile Tag

DelegateProfile Tag Delegate Profile
View, list, create, delete, duplicate and update a delegate profile. Function Access Control Point: API.DelegateProfile Introduced in v5.2; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "Delete" | "Duplicate" | "Retrieve" | "RetrieveAll" | "UpdateEntryList" | "UpdateOnly" Parameters→ Duplicate→ Name = String UpdateEntryList→ [NewName = String] UpdateOnly→ [NewName = String] Properties→ <DelegateProfile Name = String [Description = String] > <Delegates> <LightWeightPerson>* </Delegates> </DelegateProfile>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

237

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Descriptions
AddOnly A manager license is required to Add a new delegate profile. The name of the delegate profile must be unique and not exceed 50 characters. The list of delegates is required and is defined as a LightWeightPerson bean List. The length of the name should not exceed 50. The length of the description should not exceed 250. Delegates is defined as list of LightWeightPerson bean List.The list of delegates is required. They need to have manager license. Return Value Type: None Required Properties: Name, Delegates Optional Properties: Description Access Control Point Name: View Introduced in v5.2; last changed in v5.2 Delete The name of an existing delegate profile. The name of an existing delegate profile. Return Value Type: None Required Properties: Name Access Control Point Name: View Introduced in v5.2 Duplicate The name of an existing delegate profile that will be duplicated. The Name should be the name of an existing delegate profile. Return Value Type: None Access Control Point Name: View Introduced in v5.2; last changed in v5.2

238

Kronos Incorporated

DelegateProfile Tag

Action Parameters Parameter Name Name Description The Name should be the name of an existing delegate profile. Required The Name should be the name of an existing delegate profile. Additional information Introduced in v5.2

Retrieve Specify the name of the delegate profile to be retrieved; the name should not exceed 50 characters. The length of the name should not exceed 50. Return Value Type: (***undefined***): Required Properties: Name Access Control Point Name: View Introduced in v5.2; last changed in v5.2 RetrieveAll No special validation No special validation Return Value Type: (***undefined***): Access Control Point Name: View Introduced in v5.2 UpdateEntryList This action should add a list of delegates but not delete the existing deletes. This is the difference between the UpdateEntryList and UpdateOnly. Parameter NewName is used when rename a delegate profile. The length of Name should not exceed 50. The length of Description should not exceed 250. Delegates is defined as list of LightWeightPerson bean List. The list is required. Return Value Type: None

Workforce Central Developers Toolkit Reference Guide—Timekeeping

239

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required Properties: Name, Delegates Optional Properties: NewName, Description Access Control Point Name: Edit Introduced in v6.0; last changed in v6.0
Action Parameters Parameter Name NewName Description The name for the delegete profile should be unique. Optional The name for the delegete profile should be unique. Additional information Introduced in v6.0

UpdateOnly Parameter NewName is used when rename a delegate profile. The length of Name should not exceed 50. The length of Description should not exceed 250. Delegates is defined as list of LightWeightPerson bean List. The list is required. Parameter NewName is used when rename a delegate profile. The length of Name should not exceed 50. The length of Description should not exceed 250. Delegates is defined as list of LightWeightPerson bean List. The list is required. Return Value Type: None Required Properties: Name,Delegates Optional Properties: NewName, Description Access Control Point Name: View Introduced in v5.2; last changed in v5.2

240

Kronos Incorporated

DelegateProfile Tag

Action Parameters Parameter Name NewName Description The new name should be unique. Optional The new name should be unique. Additional information Introduced in v5.2

Property Descriptions
Delegates

List of available delegates
The names of the people who are the available delegates. Type: Zero or more LightWeightPerson tags Required This list can't be empty. Introduced in v5.2 Description

Description of delegate profile
The description of the delegate profile; it can be any text you want. Type: String Optional The size can't exceed 250 characters. Introduced in v5.2 Name

Delegate profile name
Specify the name of an existing delegate profile; or when creating a new delegate profile using the AddOnly action, specify a unique name. The name must not exceed 50 characters. Type: String

Workforce Central Developers Toolkit Reference Guide—Timekeeping

241

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required The name of delegate profile. The length should not exceed 50. If it is used for AddOnly, the name needs to be unique. Introduced in v5.2

242

Kronos Incorporated

DeviceGroup Tag

DeviceGroup Tag Device Group
The DeviceGroup tag represents all of the data collection devices that an employee can access. Function Access Control Point: API.Employee Introduced in v4

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllDeviceGroups" | "LoadById" Parameters→ None Properties→ <DeviceGroup [DeviceGroupId = Integer] [DeviceGroupName = String] > </DeviceGroup>

Action Descriptions
Load Returns information about the specified device group, based on DeviceGroupName. Return Value Type: DeviceGroup tag Required Properties: DeviceGroupName

Workforce Central Developers Toolkit Reference Guide—Timekeeping

243

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: View Introduced in v4 LoadAllDeviceGroups Returns all device groups in the system. Return Value Type: Zero or more DeviceGroup tags Access Control Point Name: View Introduced in v4 LoadById Returns information about a device group, based on DeviceGroupId. Return Value Type: DeviceGroup tag Required Properties: DeviceGroupId Optional Properties: DeviceGroupId Access Control Point Name: View Introduced in v4

Property Descriptions
DeviceGroupId

Device group ID
A unique identifier for a device group Type: Integer Optional Introduced in v4 DeviceGroupName

Group of devices that the employee can use
The name of the group of devices that the employee is authorized to use Type: String Optional

244

Kronos Incorporated

DeviceGroup Tag

Maximum length: 50 characters You can find values in the Workforce Timekeeper Setup Application. Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

245

Chapter 2

Workforce Timekeeper XML API Tag Definitions

EarnedAccrual Tag Earned Accrual
The Earned Accrual tag adds or subtracts an amount of time or money for a specified accrual code and employee. If you want to replace the current balance (rather than add or subtract a specific amount), use the ResetAccrual tag. All rules associated with adding earned accruals apply to the EarnedAccrual tag and associated actions. Function Access Control Point: API.Accruals Introduced in v5.1; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Update" Parameters→ None Properties→ <EarnedAccrual AmountInCurrency = Currency AmountInTime = TimeDuration AmountInTimeOrCurrency = String AccrualCodeName = String Date = Date > <Employee> <CurrentUser> | <PersonIdentity> </Employee> </EarnedAccrual>

246

Kronos Incorporated

EarnedAccrual Tag

Action Descriptions
Update Updates an accrual amount for a specified employee. If the accrual code does not exist for the employee, this action adds it. The type of the accrual code determines the amount that can be specified: either a time duration, or a currency. The format of the accrual amount must match the type of the accrual code. Return Value Type: None Required Properties: AccrualCodeName, Date, Employee, One member of the AccrualAmount group Access Control Point Name: Edit Introduced in v4; last changed in v5.0

Property Descriptions
AmountInCurrency

Amount of accrual, in currency
The amount of money to be added to the current balance for the specified accrual code and employee. Use a negative number to decrement the current balance. Type: Currency Maximum length: 30 characters AmountInCurrency belongs to the AccrualAmount group. To specify a currency value, use either the AmountInCurrency or the AmountInTimeOrCurrency property. Introduced in v4; last changed in v5.1 AmountInTime

Amount of accrual, in time
The amount of time to be added to the current balance for the specified accrual code and employee. Use a negative value to decrement the current balance.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

247

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: TimeDuration Maximum length: 30 characters AmountInTime belongs to the AccrualAmount group. To specify a time value, use either the AmountInTime or the AmountInTimeOrCurrency property. Introduced in v4; last changed in v5.1 AmountInTimeOrCurrency

Amount of accrual, in time or currency
The amount to be added or decremented to the current balance for a specified accrual code and employee. This value can be formatted either as a time value or a currency, depending on the format needed for the specified accrual code. Type: String AmountInTimeOrCurrency belongs to the AccrualAmount group. Only one member of the group can be used. Introduced in v5.0; last changed in v5.1 AccrualCodeName

Accrual code name
The name of an accrual code that exists and is assigned to the specified employee. Type: String Required Maximum length: 50 characters You can find values in the Workforce Timekeeper Setup Application. Sample values: Vacation, Sick Introduced in v4; last changed in v5.1 Date

Date

248

Kronos Incorporated

EarnedAccrual Tag

The date to which the accrual transaction applies Type: Date Required Introduced in v4 Employee

Employee
One employee, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Required Key Must uniquely identify an existing and active employee Introduced in v4

Groups of Mutually Exclusive Properties
AccrualAmount Accrual amount must be specified either in terms of time or money. AmountInTimeOrCurrency is recommended, but you can use the other properties instead. Required Group includes: AmountInCurrency, AmountInTime, AmountInTimeOrCurrency

Workforce Central Developers Toolkit Reference Guide—Timekeeping

249

Chapter 2

Workforce Timekeeper XML API Tag Definitions

EffectiveWorkload Tag Workload type
The EffectiveWorkload tag defines a workload type. Used by: WorkloadPlan Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.2

Syntax
Properties→ <EffectiveWorkload (AnchorDate = Date) (EffectiveDate = Date) (ExpirationDate = Date) OrgJobPath = String [PatternDurationType = String] (WorkloadType = String) WorkloadPatternType = String WorkloadPlanType = String > <HeadcountPatterns> <HeadcountPattern>* </HeadcountPatterns> </EffectiveWorkload>

Property Descriptions
AnchorDate

Base start date of workload pattern
Specifies the date on which the workload pattern is scheduled to start Type: Date Output only Introduced in v5.0

250

Kronos Incorporated

EffectiveWorkload Tag

EffectiveDate

Effective start date in workload pattern
The effective start date within the workload pattern Type: Date Output only Introduced in v5.0 ExpirationDate

End date for workload pattern
The end date for the workload pattern Type: Date Output only Introduced in v5.0 HeadcountPatterns

Daily staffing patterns
One or more instances of staffing data patterns Type: Zero or more HeadcountPattern tags Required Introduced in v5.0 OrgJobPath

Location of job in the organization
The fully qualified path name for an organizational job Type: String Required Maximum length: 1000 characters

Workforce Central Developers Toolkit Reference Guide—Timekeeping

251

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The LocationOrgNodePath in the WorkloadPlan tag, which represents the fully qualified path name for the organization node on the organization tree, must be the parent of the OrgJobPath. Sample values: If the LocationOrgNodePath path is A/B/C, then the OrgJobPath is A/B/C/D. Introduced in v5.0 PatternDurationType

Pattern duration type (weekly, daily)
The workload duration Dependency: PatternDurationType is required, and can be Weekly or Daily if the value of WorkloadPlanType is Regular. You must specify Weekly to import the normal Baseline and Adjusted patterns that appear in the Pattern Tab of the Workload Planner user interface. Dependency: PatternDurationType is optional if the WorkloadPlanType is Holiday, but if specified, it must be specified as "Daily" Type: String Optional Enumerated value: Weekly, Daily Introduced in v5.0 WorkloadPatternType

Type of workload pattern
The type of workload pattern Type: String Required Sample values: Baseline, Adjusted

252

Kronos Incorporated

EffectiveWorkload Tag

Introduced in v5.0 WorkloadPlanType

Type of workload plan
The type of workload plan Dependency: If WorkloadPlanType is specified as Holiday, then PatternDurationType must be specified as Daily and DayOfWeek in the Headcount tag must be specified as Anyday. Dependency: If WorkloadPlanType is specified as Regular, PatternDurationType must be specified as Weekly to import the normal Baseline and Adjusted patterns that appear in the Pattern Tab of the Workload Planner user interface. Dependency: If WorkloadPlanType is specified as Regular and PatternDurationType is specified as Daily, then they are available from the Workload Planner user interface on the Calendar tab. Type: String Required Enumerated value: Regular, Holiday Introduced in v5.0 WorkloadType

Type of workload
Type of workload Type: String Output only This value is system-generated. Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

253

Chapter 2

Workforce Timekeeper XML API Tag Definitions

EligibleJobs Tag EligibleJobs
This tag will get all open shifts for a specified date range. Function Access Control Point: API.Schedule Introduced in v5.1; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadAll" Parameters→ None Properties→ <EligibleJobs [EndDate = Date] StartDate = Date > <Employee> <PersonIdentity> </Employee> (<LocationItems> <LocationItem>* </LocationItems>) </EligibleJobs>

Action Descriptions
LoadAll The LoadAll action gets all open shifts in the employee's transfer set for the specified date range.

254

Kronos Incorporated

EligibleJobs Tag

The specified employee must be an active employee. Return Value Type: Zero or more LocationItem tags Required Properties: Employee, StartDate Optional Properties: EndDate Access Control Point Name: View Introduced in v5.1; last changed in v5.1

Property Descriptions
Employee

Employee
This property represents the employee who requests the action. Type: PersonIdentity tag Required Key It must be an active employee. Introduced in v5.1 EndDate

End Date
EndDate is the ending date of query date span. Instead of using KDateSpan, the start date & end date is more a convenience way for process manager. Type: Date Optional It must be a valid end date for property StartDate. Introduced in v5.1; last changed in v5.1 LocationItems

Location Items

Workforce Central Developers Toolkit Reference Guide—Timekeeping

255

Chapter 2

Workforce Timekeeper XML API Tag Definitions

A list of location items. Type: Zero or more LocationItem tags Output only Introduced in v5.2 StartDate

Start Date
StartDate is the beginning date of query date span. Instead of using KDateSpan, the start date & end date is more a convenience way for process manager. Type: Date Required It must be a valid date. Introduced in v5.1; last changed in v5.1

256

Kronos Incorporated

EmailAddress Tag

EmailAddress Tag Email Address
The EmailAddress tag specifies an e-mail address of the given e-mail address type. Used by: PersonInformation Function Access Control Point: API.Person Introduced in v4; last changed in v5.0

Syntax
Properties→ <EmailAddress Address = String ContactTypeName = String > </EmailAddress>

Property Descriptions
Address

Email address for employee
The employee's electronic mail address Type: String Required Maximum length: 50 characters Introduced in v4 ContactTypeName

Type of contact
The name of the contact category Type: String

Workforce Central Developers Toolkit Reference Guide—Timekeeping

257

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required Key Maximum length: 30 characters Introduced in v4

258

Kronos Incorporated

EmployeeGroupAssign Tag

EmployeeGroupAssign Tag Employee group assignments
The EmployeeGroupAssign tag is used to assign a list of employees to one or more schedule groups. Function Access Control Point: API.Schedule Introduced in v5.1; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "Update" Parameters→ None Properties→ <EmployeeGroupAssign (PersonNumber = Integer) > <Employees> <CurrentUser> | <PersonIdentity> </Employees> <EmployeeGroupItems> <EmployeeGroupItem>* </EmployeeGroupItems> </EmployeeGroupAssign>

Action Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

259

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Load Load action loads employee's group assignment information. PeriodDateSpan is an optional tag. If it hasn't been defined, load employee's group assignment information; start from today to "forever". Person Number shouldn't be null Return Value Type: String Required Properties: PersonNumber Optional Properties: Period,TimeFramePeriod, PeriodDateSpan Access Control Point Name: View Introduced in v5.1; last changed in v5.1 Update Update action assigns a list of employees to one or more groups of a certain date range. EmployeeGroupItems shouldn't be null Return Value Type: String Required Properties: EmployeeGroupItems, Employees Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1

Property Descriptions
EmployeeGroupItems

List of EmployeeGroupItem tags
A list of EmployeeGroupItem tags. Type: Zero or more EmployeeGroupItem tags Required Introduced in v5.1; last changed in v5.2 Employees

Employees

260

Kronos Incorporated

EmployeeGroupAssign Tag

A list of schedule employees Type: Either CurrentUser or PersonIdentity tag Required Introduced in v5.1; last changed in v5.1 PersonNumber

Person number
PersonNumber is a required property for load action only. Type: Integer Output only Introduced in v5.1; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

261

Chapter 2

Workforce Timekeeper XML API Tag Definitions

EmployeeGroupItem Tag Employee Group Item
The EmployeeGroupItem tag contains information about the employee's group assignment. Function Access Control Point: API.Schedule Introduced in v5.1; last changed in v6.0

Syntax
Properties→ <EmployeeGroupItem ExpirationDate = Time EndDate = Time EffectiveDate = Time Name = String > </EmployeeGroupItem>

Property Descriptions
ExpirationDate

Expiration date of employee assignment
The expiration date which employee will be disassociated from a schedule group. If this is not present, it will default to the end of time. Type: Time Introduced in v5.1; last changed in v6.0; deprecated in v6.0. The expiration date is not used in the UI so it should not be exposed in the API. The end date should be used instead. EndDate

The end date of the employee assignment.
The end date is used to determine the last day an employee belongs to a schedule group. If this is not present, it will default to the end of time.

262

Kronos Incorporated

EmployeeGroupItem Tag

Type: Time Introduced in v6.0; last changed in v6.0 EffectiveDate

Effective date of assignment
The effective date on which an employee will be assigned to a schedule group. Type: Time Required Introduced in v5.1; last changed in v5.2 Name

Name of the employee group
The name of the group Type: String Required Introduced in v5.1; last changed in v5.2

Groups of Mutually Exclusive Properties
EndAndExpirationDate Only one of these should be specified. The preference is end date since expiration date is deprecated. Optional Group includes: ExpirationDate, EndDate

Workforce Central Developers Toolkit Reference Guide—Timekeeping

263

Chapter 2

Workforce Timekeeper XML API Tag Definitions

EmployeeGroupProfile Tag Group Profile for Employee Assignment
The employee group is a collection of labor level entries assigned to a manager that defines the employee information to which the manager has access. A manager who is assigning a new employee to an employee group can only grant the new employee the labor level sets in his or her own employee group or a subset of that group. The manager cannot assign groups that are outside of his or her employee group. Function Access Control Point: API.Employee Introduced in v4

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllEmployeeGroupProfiles" | "LoadById" Parameters→ None Properties→ <EmployeeGroupProfile [EmployeeGroupProfileId = Integer] [EmployeeGroupProfileName = String] > </EmployeeGroupProfile>

Action Descriptions

264

Kronos Incorporated

EmployeeGroupProfile Tag

Load Returns the specified employee group profile, based on EmployeeGroupProfileName. Return Value Type: EmployeeGroupProfile tag Required Properties: EmployeeGroupProfileName Access Control Point Name: View Introduced in v4 LoadAllEmployeeGroupProfiles Returns all employee group profiles in the system. Return Value Type: Zero or more EmployeeGroupProfile tags Access Control Point Name: View Introduced in v4 LoadById Returns the specified employee group profile, based on EmployeeGroupProfileId. Return Value Type: EmployeeGroupProfile tag Required Properties: EmployeeGroupProfileId Access Control Point Name: View Introduced in v4

Property Descriptions
EmployeeGroupProfileId

Employee group profile ID
A unique identifier for the employee group profile Type: Integer Optional Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

265

Chapter 2

Workforce Timekeeper XML API Tag Definitions

EmployeeGroupProfileName

Employee group profile name
Name of the employee group profile Type: String Optional Introduced in v4

266

Kronos Incorporated

EmployeeMessage Tag

EmployeeMessage Tag Employee Message
The EmployeeMessage tag is used to send messages to employees, view messages or delete messages. The bean does the validation Function Access Control Point: API.Messaging Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Delete" | "Load" | "LoadAllMessages" | "Send" Parameters→ None Properties→ <EmployeeMessage MessageSubject = String TypeId = String > <Recipients> <HyperFindQuery> | <To> </Recipients> <Sender> <From> </Sender> </EmployeeMessage>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

267

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Descriptions
Delete validation done in the bean validation done in the bean Return Value Type: None Required Properties: MessageId,Sender Access Control Point Name: Edit Introduced in v5.2 Load validation done in the bean validation done in the bean Return Value Type: Zero or more EmployeeMessage tags Required Properties: Sender Access Control Point Name: View Introduced in v5.2 LoadAllMessages bean does the validation bean does the validation Return Value Type: (***undefined***): APIBeanList Required Properties: Identity Access Control Point Name: View Introduced in v5.2; last changed in v5.2 Send validation done in the bean validation done in the bean Return Value Type: None Required Properties: TypeId,Sender,Recipients,MessageSubject

268

Kronos Incorporated

EmployeeMessage Tag

Optional Properties: MessageBody,MessageId Access Control Point Name: Edit Introduced in v5.2; last changed in v5.2

Property Descriptions
MessageSubject

Message Subject
Message subject Type: String Required Validation done in the bean Introduced in v5.2 Recipients

Recipients
The recipients can be either a <hyperfindquery bean or a <to bean Type: Either HyperFindQuery or To tag Required validation done in the bean Introduced in v5.2 Sender

Sender
Validation done in the bean Type: From tag Required

Workforce Central Developers Toolkit Reference Guide—Timekeeping

269

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Validation done in the bean Introduced in v5.2 TypeId

Message Type ID
The acceptable values are 1, 2 or 3. Type: String Required The acceptable values are 1, 2 or 3. Sample values: 1, 2 or 3 Introduced in v5.2

270

Kronos Incorporated

EmployeePreferredZone Tag

EmployeePreferredZone Tag Preferred schedule zone assignment for the employee
This tag assigns a preferred schedule zone for an employee. Function Access Control Point: API.Schedule Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Delete" | "Load" | "Update" Parameters→ None Properties→ <EmployeePreferredZone [PreferredZone = String] PersonNumber = Integer [PreferredZoneSet = String] > </EmployeePreferredZone>

Action Descriptions
Delete This will delete the preferred zone assignment for the person whose personNumber matches the one supplied. Return Value Type: None Required Properties: PersonNumber

Workforce Central Developers Toolkit Reference Guide—Timekeeping

271

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: Edit Introduced in v5.2 Load This is the person number of the employee whose preferred zone you would like to retrieve. Return Value Type: EmployeePreferredZone tag Required Properties: PersonNumber Access Control Point Name: View Introduced in v5.2 Update This will set the preferred zone for the person supplied. It will be set to the zone in the zone set which has been passed in via the PreferredZone and PreferredZoneSet attributes. Return Value Type: None Required Properties: PersonNumber, PreferredZoneSet, PreferredZone Access Control Point Name: Edit Introduced in v5.2

Property Descriptions
PersonNumber

Person number
The person number of the employee that you are assigning or deleting the preferred zone for. Type: Integer Required Introduced in v5.2; last changed in v5.2 PreferredZone

Name of preferred schedule zone

272

Kronos Incorporated

EmployeePreferredZone Tag

The name of the zone that is being assigned to an employee Type: String Optional Introduced in v5.2; last changed in v5.2 PreferredZoneSet

Schedule Zone Set that contains the preferred zone
The name of the zone set that contains the zone that is being assigned or deleted Type: String Optional Introduced in v5.2; last changed in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

273

Chapter 2

Workforce Timekeeper XML API Tag Definitions

EmployeeSummary Tag Employee Summary
The EmployeeSummary tag contains either accruals or totals for an employee. Used by: BulkAccruals, BulkTotals Function Access Control Point: API.Accruals Introduced in v4

Syntax
Properties→ <EmployeeSummary (<Accruals> <AccrualBalanceSummary>* </Accruals>) (<Employee> <PersonIdentity> </Employee>) (<Totals> <Total>* </Totals>) </EmployeeSummary>

Property Descriptions
Accruals

Accruals
One or more accruals for the specified employee, as requested by the BulkAccruals tag. Type: Zero or more AccrualBalanceSummary tags Output Only Introduced in v4

274

Kronos Incorporated

EmployeeSummary Tag

Employee

Employee
One employee, as specified in a PersonIdentity tag, for whom the accruals or totals are returned. Type: PersonIdentity tag Output Only Must uniquely identify an existing and active employee Introduced in v4 Totals

Totals
A list of totals for the specified employee, as requested by the BulkTotals tag. The Total tag contains the minimum information, PayCodeId, PayCodeName, and AmountInTime or AmountInCurrency. Type: Zero or more Total tags Output Only Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

275

Chapter 2

Workforce Timekeeper XML API Tag Definitions

EmploymentStatus Tag Employment Status
This tag sets the employment status of a person identified in the PersonInformation tag for the specified time frame. The employment status can be Active, Inactive, or Terminated. For more information, see the online help. Used by: PersonInformation Function Access Control Point: API.Person Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadEmploymentStatuses" Parameters→ None Properties→ <EmploymentStatus [EffectiveDate = Date] EmploymentStatusName = String [ExpirationDate = Date] > <Identity> <CurrentUser> | <PersonIdentity> </Identity> [<Period> <TimeFramePeriod> </Period>] </EmploymentStatus>

Action Descriptions

276

Kronos Incorporated

EmploymentStatus Tag

LoadEmploymentStatuses Returns information associated with the employment status for one person over the specified period of time. If the period of time is not specified, the current date through January 1, 3000 is used. The information returned for the Identity and Period properties is added to the first tag in the resulting list. If no data for the person is found, the value returned consists of just the Identity and Period properties. The person must exist and the user must have access to that person. Return Value Type: Zero or more EmploymentStatus tags Required Properties: Identity Optional Properties: Period Access Control Point Name: View Introduced in v5.0; last changed in v5.0

Property Descriptions
EffectiveDate

Effective date
The beginning date of the employment status that this tag sets. Type: Date Optional Must occur before the expiration date Default value: The date of the import Introduced in v4; last changed in v5.1 EmploymentStatusName

Employment status name
Indicates the current status of the employee.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

277

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Values can be: • • • • 0 for not applicable 1 for an active employee 2 for an inactive employee 3 for a terminated employee

Type: String Required Maximum length: 1 character Enumerated value: 0, 1, 2, 3 Introduced in v4 ExpirationDate

Expiration date
The date when the employment status specified by this tag ends. Type: Date Optional Must occur after the effective date. Default value: January 1, 3000 Introduced in v4; last changed in v5.1 Identity

Identity
One person, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Optional Key Must uniquely identify a person. Introduced in v5.0

278

Kronos Incorporated

EmploymentStatus Tag

Period

Time period
The time span that is associated with an employment status Type: TimeFramePeriod tag Optional The specified identity shall be used when the time frame requires an association with a person. Used for the LoadEmploymentStatuses action Default value: From the current date until January 1, 3000 Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

279

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Error Tag Error
An Error tag represents a processing, validation, or persistence error that occurred while processing the XML or executing an action Function Access Control Point: API.Common Introduced in v4; last changed in v5.0

Syntax
Properties→ <Error [ActionName = String] [PropertyType = String] [ParameterType = String] ErrorCode = Integer Message = String [ErrorData = Collection] [ParameterName = String] [PropertyName = String] [BeanName = String] [PropertyValue = String] [ParameterValue = String] > [<DetailErrors> <Error>* </DetailErrors>] </Error>

Property Descriptions
ActionName

Action being used when error occurred
Identifies the action in which the error occurred Type: String Optional

280

Kronos Incorporated

Error Tag

Introduced in v4 BeanName

Tag being used when error occurred
The external name of the tag in which the error occurred Type: String Optional Introduced in v4 DetailErrors

Error Details
A list of other errors that may have caused the primary error Type: Zero or more Error tags Optional Introduced in v4 ErrorCode

Error code
A unique code that identifies the error Type: Integer Required Introduced in v4 ErrorData

Other data related to the error
Other data about the error. Each entry is of the form name=value. Type: Collection Optional Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

281

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Message

Error message
An error message that describes the error Type: String Required Introduced in v4 ParameterName

Parameter being used when error occurred
The name of the parameter in which the error occurred Type: String Optional Introduced in v4 ParameterType

Data type of the parameter being used when the error occurred
The data type of the parameter in which the error occurred Type: String Optional Introduced in v4 ParameterValue

Value of the parameter when the error occurred
The value of the parameter in which the error occurred Type: String Optional Introduced in v4

282

Kronos Incorporated

Error Tag

PropertyName

Property being used when the error occurred
The name of the property in which the error occurred Type: String Optional Introduced in v4 PropertyType

Data type of property being used when the error occurred
The data type of the property in which the error occurred Type: String Optional Introduced in v4 PropertyValue

Value of property when the error occurred
The value of the property in which the error occurred Type: String Optional Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

283

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ExpectedHours Tag Hours an Employee Is Expected to Work
The ExpectedHours tag contains the number of hours that the employee is expected to work each day. Used by: PersonInformation Function Access Control Point: API.Person Introduced in v4; last changed in v5.0

Syntax
Properties→ <ExpectedHours Quantity = TimeDuration TimePeriodTypeName = String > </ExpectedHours>

Property Descriptions
Quantity

Number of hours
The number of hours the employee is expected to work for the time span identified in TimePeriodTypeName. Type: TimeDuration Required Maximum length: 6 characters The value can be an integer or a decimal amount, such as 8, 8.0 or 8.5. Do not use colons, for example, 8:00 to separate hours and minutes. Introduced in v4; last changed in v5.0 TimePeriodTypeName

Time span associated with number of hours

284

Kronos Incorporated

ExpectedHours Tag

The span of time associated with the number of hours reported in Quantity. Type: String Required Key Maximum length: 10 characters Enumerated value: Daily, Weekly, Monthly, Annually, Pay Period, Schedule Period Introduced in v4; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

285

Chapter 2

Workforce Timekeeper XML API Tag Definitions

FailedXMLTransaction Tag Failed XML Transaction
The FailedXMLTransaction tag provides information about an XML transaction that has failed an attempt to process an XML request. It is used to retrieve or modify failed XML transaction information. Note: This tag provides information for the Transaction Assistant. Function Access Control Point: API.FailedXMLTransaction Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "Delete" | "Load" Parameters→ None Properties→ <FailedXMLTransaction BatchStatId = Long [XMLRequestBodyText = String] [ErrorText = String] [SourceDetails = String] [XMLRequestEndDate = Date] [XMLRequestEndTime = Time] [ErrorCode = Integer] [XMLRequestHeaderText = String] [SourceName = String] [APIBeanName = String] [PropertyName = String]

286

Kronos Incorporated

FailedXMLTransaction Tag

[ErrorRecordNumber = Integer] [XMLRequestBeginDate = Date] [XMLRequestBeginTime = Time] [TransactionType = String] [PropertyValue = String] > </FailedXMLTransaction>

Action Descriptions
AddOnly Adds a failed XML transaction error record to the database. Does not replace an existing failed transaction Return Value Type: None Required Properties: SourceName, BatchStatId, XMLRequestEndDate, XMLRequestEndTime, TransactionType, XMLRequestHeaderText, XMLRequestBodyText Access Control Point Name: Edit Introduced in v5.0 Delete Removes the failed transaction record with matching property values from the database. SourceName or TransactionType must be specified. Return Value Type: None Required Properties: XMLRequestEndDate, XMLRequestEndTime Access Control Point Name: Edit Introduced in v5.0 Load Returns all failed transactions for the specified SourceName and TransactionType. You must specify at least one of these properties with the Load action; if you do not, an error is returned. Return Value Type: Zero or more FailedXMLTransaction tags Optional Properties: SourceName, TransactionType Access Control Point Name: Edit

Workforce Central Developers Toolkit Reference Guide—Timekeeping

287

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.0

Property Descriptions
APIBeanName

Name of failed XML tag
The API tag name for the failed XML transaction request Type: String Optional Maximum length: 100 characters Introduced in v5.0 BatchStatId

Batch status ID
The unique numeric value of an instance of a batch that contains a failed transaction. The batch status Id is the value in the Import Batch Status tag that was generated when the batch was created. Type: Long Optional Key Maximum length: 10 characters Introduced in v5.0 ErrorCode

Error code
A identification for the error that was returned Type: Integer Optional Introduced in v5.0

288

Kronos Incorporated

FailedXMLTransaction Tag

ErrorRecordNumber

Record number for error
The unique number that is generated for the error Type: Integer Optional Introduced in v5.0 ErrorText

Description of error
A description of the error that was returned Type: String Optional Maximum length: 250 characters Introduced in v5.0 PropertyName

Property that caused the error
The name of the property within the XMLRequestBody that caused the error Type: String Optional Maximum length: 10 characters Introduced in v5.0 PropertyValue

Value of property that caused the error
The value of the property in the XMLRequestBody that caused the error Type: String Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

289

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Maximum length: 2000 characters Introduced in v5.0 SourceDetails

Details about the application
The source details including additional information about source Type: String Optional Maximum length: 250 characters Introduced in v5.0 SourceName

Name of application submitting the import
The name of the source system submitting an XML import Type: String Optional Maximum length: 30 characters Sample values: Connect, NameOfAThird PartyApplication, DCM Introduced in v5.0 TransactionType

Transaction (import content) type
The XML Import transaction type for the failed transaction. If the type is "XML" the XMLRequestBodyText is examined to determine the transaction type. Type: String Optional Must be a valid import type

290

Kronos Incorporated

FailedXMLTransaction Tag

Sample values: Accrual Dates, Accruals, Activities, Activities People, Availability Templates, Certifications, Customers, Labor Level Entries, Labor Level Sets, Organizational Maps, Pay Code Edits, People, Punches, Results, Schedule Assistant Criteria, Schedule Rules, Schedules, Skills, Staffing, Workforce Activities, Workforce Scheduler Introduced in v5.0 XMLRequestBeginDate

Start date of XML request
The date when the XML request was started Type: Date Optional Introduced in v5.0 XMLRequestBeginTime

Start time of XML request
The time when the XML request was started Type: Time Optional Introduced in v5.0 XMLRequestBodyText

Body of the XML request
Details for the failed XML request Type: String Optional Maximum length: 2000 characters

Workforce Central Developers Toolkit Reference Guide—Timekeeping

291

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Replace all special characters with the descriptive special HTML characters, as shown: " = &quot; & = &amp; < = &lt; = &gt; ' = &apos; Sample values: &lt; Request Action=&quot; AddOnly&quot;&gt; &lt; Punch Date=&quot; 08/23/03&quot; Time=&quot;9:00AM&quot; KronosTimeZone=&quot;13011&quot; DayLightSavingsFlag=&quot; True&quot;&gt; &lt;Employee&gt; &lt; PersonIdentity BadgeNumber=&quot; 28&quot; /&gt; &lt; /Employee&gt; &lt; /Punch&gt; &lt; /Request&gt; Introduced in v5.0 XMLRequestEndDate

End date of XML request
The end date of the request failure Type: Date Optional Introduced in v5.0 XMLRequestEndTime

End time of XML request
The end time of the request failure. Type: Time Optional Value must parse to a valid time according to current user's preferences. Introduced in v5.0 XMLRequestHeaderText

Header of the XML request
The XML request header for the failed XML request

292

Kronos Incorporated

FailedXMLTransaction Tag

Type: String Optional Maximum length: 1000 characters Replace all special characters with the special HTML characters, as shown: " = &quot; & = &amp; < = &lt; = &gt; ' = &apos; Sample values: &lt; ?xml version=&quot; 1.0&quot; ?&gt; &lt;Kronos_WFC version=&quot; 1.0&quot; &gt; Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

293

Chapter 2

Workforce Timekeeper XML API Tag Definitions

FPAAllocation Tag Percent Allocation Rule Allocation
Defines the labor account and how wages are allocated to that labor account. Function Access Control Point: API.TimeKeeping Introduced in v5.2; last changed in v5.2

Syntax
Properties→ <FPAAllocation [LaborAccountName = String] Percentage = Double [WageAdjustmentAmount = Double] [WageAdjustmentType = Integer] > </FPAAllocation>

Property Descriptions
LaborAccountName

Labor Account Name
The labor account that will be allocated the specified percent of the pay. Type: String Optional Must be a valid labor account. If AdHoc is enabled and validation for a labor level is turned off, then labor level entries may be created by adhoc. Sample values: LaborAccountName="101//303//504//701" Introduced in v5.2 Percentage

Percentage

294

Kronos Incorporated

FPAAllocation Tag

The percentage of the total wage that will be allocated to the specified labor account. All allocations for a trigger must add up to 100. Type: Double Required Must be between 0 and 100. Sample values: Percentage="100" Introduced in v5.2 WageAdjustmentAmount

Wage Adjustment Amount
Specifies the amount that the base wage will be adjusted by. Type: Double Optional Sample values: WageAdjustmentAmount="5.00" Introduced in v5.2 WageAdjustmentType

Wage Adjustment Type
Specifies how the base wage will be adjusted after the allocation rule is applied: 0 - none; 1 - addition; 2 - flat; 3 - multiply. Type: Integer Optional Must be between 0 and 3 Sample values: WageAdjustmentType="1"

Workforce Central Developers Toolkit Reference Guide—Timekeeping

295

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.2

296

Kronos Incorporated

FPARule Tag

FPARule Tag Percent Allocation Rule
This tag provides the create, read, update, and delete operations used for managing percent allocation rules. Use the ProcessorToEmployee tag to assign a percent allocation rule to an employee. Function Access Control Point: API.TimeKeeping Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Delete" | "Retrieve" | "RetrieveAll" | "RetrieveAllNames" | "RetrieveByName" | "RetrieveForUpdate" | "Update" Parameters→ None Properties→ <FPARule Name = String > <FPARuleVersions> <FPARuleVersion>* </FPARuleVersions> </FPARule>

Action Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

297

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Delete Deletes an FPARule name must not be null and should be between 1 and 30 characters Return Value Type: None Required Properties: name Access Control Point Name: Edit Introduced in v5.2 Retrieve The name of the rule to be retrieved name must not be null and must be between 1 and 30 characters in length Return Value Type: FPARule tag Required Properties: name Access Control Point Name: View Introduced in v5.2 RetrieveAll Returns all FPA rules in the system Return Value Type: Zero or more FPARule tags Access Control Point Name: View Introduced in v5.2 RetrieveAllNames Returns the names of all FPARules in the system Return Value Type: Zero or more NameList tags Access Control Point Name: View Introduced in v5.2; last changed in v5.2 RetrieveByName Returns a FPARule for a given name name must not be null and between 1 and 30 characters Return Value Type: FPARule tag

298

Kronos Incorporated

FPARule Tag

Required Properties: name Access Control Point Name: View Introduced in v5.2 RetrieveForUpdate Returns a FPARule for use in an Update request name must not be null and should be between 1 and 30 characters Return Value Type: FPARule tag Required Properties: name Access Control Point Name: View Introduced in v5.2 Update This action will update (insert,update) a FPARule. It uses the factory method RetrieveByName to retrieve an existing rule if it exists. The FPARuleVersion is a list of FPARuleVersion API Tags. See the FPARuleVersion Tag for more information. name must not be null and between 1 and 30 characters Return Value Type: None Required Properties: name Optional Properties: FPARuleVersions Access Control Point Name: Edit Introduced in v5.2

Property Descriptions
FPARuleVersions

Percent Allocation Revisions
The list of revisions (FPARuleVersion) of a FPA Rule Type: Zero or more FPARuleVersion tags Required

Workforce Central Developers Toolkit Reference Guide—Timekeeping

299

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Sample values: <FPARuleVersions> <FPARuleVersion EndEffectiveDate="01/01/3000" StartEffectiveDate="01/01/1753" Description="BOT EOT"> <Triggers> <FPATrigger LaborAccountPattern="//////701" SequenceNumber="1"> <PayCodes> <SimpleValue value="All Regular"/> <SimpleValue value="Regular"/> </PayCodes> <Allocations> <FPAAllocation LaborAccountName="101//303// 504//701" WageAdjustmentType="1" Percentage="50" WageAdjustmentAmount="5.00" /> <FPAAllocation LaborAccountName="101//303// 504//702" WageAdjustmentType="2" Percentage="50" WageAdjustmentAmount="12.00" /> </Allocations> </FPATrigger> <FPATrigger JobCode="Line 1/QCE" JobCodeEffectiveDate="11/15/2005" SequenceNumber="1"> <PayCodes> <SimpleValue value="Regular"/> </PayCodes> <Allocations> <FPAAllocation LaborAccountName="101//303// 504//701" WageAdjustmentType="1" Percentage="50" WageAdjustmentAmount="5.00" /> <FPAAllocation LaborAccountName="101//303// 504//702" WageAdjustmentType="2" Percentage="50" WageAdjustmentAmount="12.00" /> </Allocations> </FPATrigger> </Triggers> </FPARuleVersion> </FPARuleVersions> Introduced in v5.2

300

Kronos Incorporated

FPARule Tag

Name

Percent Allocation Rule Name
The name of the rule Type: String Required Key Must not be null and between 1 and 30 characters Sample values: <FPARule Name="SDM Rule"> Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

301

Chapter 2

Workforce Timekeeper XML API Tag Definitions

FPARuleVersion Tag Percent Allocation Rule Revision
Represents a revision of a FPARule Function Access Control Point: API.TimeKeeping Introduced in v5.2; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddVersionToRule" Parameters→ AddVersionToRule→ ruleName = String Properties→ <FPARuleVersion [Description = String] EndEffectiveDate = Date StartEffectiveDate = Date > [<Triggers> <FPATrigger>* </Triggers>] </FPARuleVersion>

Action Descriptions
AddVersionToRule Adds a new FPA Version to a rule Return Value Type: None

302

Kronos Incorporated

FPARuleVersion Tag

Required Properties: StartEffectiveDate Optional Properties: Description Triggers Access Control Point Name: Edit Introduced in v6.0
Action Parameters Parameter Name ruleName Description Name of the urle to add this version to Required Additional information Introduced in v6.0

Property Descriptions
Description

Description
Simple description to describe the revision Type: String Optional Sample values: Description="Initial Version" Introduced in v5.2 EndEffectiveDate

End Effective Date
The end date of this revision Type: Date Required Must not be null and be a valid date Sample values:

Workforce Central Developers Toolkit Reference Guide—Timekeeping

303

Chapter 2

Workforce Timekeeper XML API Tag Definitions

EndEffectiveDate="01/01/3000" Introduced in v5.2 StartEffectiveDate

Start Effective Date
The date that this revision begins Type: Date Required Must not be null and be a valid date Sample values: StartEffectiveDate="01/01/1753" Introduced in v5.2 Triggers

Triggers
Triggers on a version are used to compare against a total. If the trigger matches then the total is allocated accordingly to the allocations specified for the total. Type: Zero or more FPATrigger tags Optional Sample values: <Triggers> <FPATrigger LaborAccountPattern="//////701" SequenceNumber="1"> <PayCodes> <SimpleValue value="All Regular"/> <SimpleValue value="Regular"/> </PayCodes> <Allocations> <FPAAllocation LaborAccountName="101//303// 504//701" WageAdjustmentType="1" Percentage="50" WageAdjustmentAmount="5.00" />

304

Kronos Incorporated

FPARuleVersion Tag

<FPAAllocation LaborAccountName="101//303// 504//702" WageAdjustmentType="2" Percentage="50" WageAdjustmentAmount="12.00" /> </Allocations> </FPATrigger> <FPATrigger JobCode="Line 1/QCE" JobCodeEffectiveDate="11/15/2005" SequenceNumber="1"> <PayCodes> <SimpleValue value="Regular"/> </PayCodes> <Allocations> <FPAAllocation LaborAccountName="101//303// 504//701" WageAdjustmentType="1" Percentage="50" WageAdjustmentAmount="5.00" /> <FPAAllocation LaborAccountName="101//303// 504//702" WageAdjustmentType="2" Percentage="50" WageAdjustmentAmount="12.00" /> </Allocations> </FPATrigger> </Triggers> Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

305

Chapter 2

Workforce Timekeeper XML API Tag Definitions

FPATrigger Tag Percent Allocation Rule Trigger
Represents a trigger that is used to determine if a total should be split and allocated Function Access Control Point: API.TimeKeeping Introduced in v5.2; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddTriggerToRule" Parameters→ AddTriggerToRule→ ruleName = String versionStartDate = Date Properties→ <FPATrigger [JobCode = String] [JobCodeEffectiveDate = Date] LaborAccountPattern = String SequenceNumber = Long > [<Allocations> <FPAAllocation>* </Allocations>] [<PayCodes> <SimpleValue>* </PayCodes>] </FPATrigger>

Action Descriptions

306

Kronos Incorporated

FPATrigger Tag

AddTriggerToRule Adds a new trigger to a rule Return Value Type: None Required Properties: SequenceNumber LaborAccountPattern Allocations Optional Properties: JobCode JobCodeEffectiveDate Access Control Point Name: Edit Introduced in v6.0
Action Parameters Parameter Name ruleName versionStartDate Description name of the rule to add this trigger to Required The start date of this version. Required Validate the date format. Additional information Introduced in v6.0 Introduced in v6.0

Property Descriptions
Allocations

Allocations
Specifies how much of a total should be allocated, to where, and at what wage rate, once the trigger is matched against the original total. Type: Zero or more FPAAllocation tags Optional If allocations are specified then their total percentage must equal to 100 Sample values: <Allocations> <FPAAllocation LaborAccountName="101//303// 504//701" WageAdjustmentType="1" Percentage="50" WageAdjustmentAmount="5.00" />

Workforce Central Developers Toolkit Reference Guide—Timekeeping

307

Chapter 2

Workforce Timekeeper XML API Tag Definitions

<FPAAllocation LaborAccountName="101//303// 504//702" WageAdjustmentType="2" Percentage="50" WageAdjustmentAmount="12.00" /> </Allocations> Introduced in v5.2 JobCode

Job Code
The Job that is compared against the trigger when determining if a trigger matches the total. Used in combination with the labor account pattern and paycodes Type: String Optional The Job Code Path entered must exist and be qualified enough that there is only one match. Entering in a Job such as just "QCE" will fail as there are numerous QCE jobs at different locations (Line) Sample values: JobCode="Line 1/QCE" Introduced in v5.2 JobCodeEffectiveDate

Job Code Effective Date
The effective date of the job chosen. Type: Date Optional Must be a valid date. If not provided then the current date is used. Sample values: JobCodeEffectiveDate="11/15/2005" Introduced in v5.2

308

Kronos Incorporated

FPATrigger Tag

LaborAccountPattern

Labor Account Pattern
The labor account that will be used to compare against a total. If this and any other trigger attributes match then the trigger is applied to the total (split) Type: String Required Must be in a valid labor account format containing the correct number of labor levels, use the correct wild card characters (*,?). If a full labor level entries are validated to exist Sample values: LaborAccountPattern="//////701" Introduced in v5.2 PayCodes

Pay Codes
Part of the trigger and when defined used when comparing against a total. If there are paycodes defined on the trigger then the total must also use one of those paycodes in order to match. Type: Zero or more SimpleValue tags Optional Sample values: <PayCodes> <SimpleValue value="Regular"/> </PayCodes> Introduced in v5.2; last changed in v5.2 SequenceNumber

Sequence Number

Workforce Central Developers Toolkit Reference Guide—Timekeeping

309

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Each trigger is given a sequence number to determine in which order they are compared against the total. Each trigger should have a unique sequence number. Type: Long Required Must be a valid long Sample values: SequenceNumber="1" Introduced in v5.2

310

Kronos Incorporated

From Tag

From Tag The Kmail sender
Sender of Kmail. This tag appears as a child of the Sender tag of the EmployeeMessage tag. Validation done in the FromBean Function Access Control Point: API.Messaging Introduced in v5.2; last changed in v5.2

Syntax
Properties→ <From Address = String [PersonNumber = String] [PersonKey = String] > </From>

Property Descriptions
Address

Email address
email address Type: String Required Validation done in the bean Introduced in v5.2 PersonKey

Person key
Person Key Type: String

Workforce Central Developers Toolkit Reference Guide—Timekeeping

311

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional validation done in the bean Introduced in v5.2 PersonNumber

Person id
Person id Type: String Optional validation done in the bean Introduced in v5.2

312

Kronos Incorporated

FunctionAccessProfile Tag

FunctionAccessProfile Tag Function Access Profile
Returns a list of function access profiles. A function access profile determines the components that users can access and the functions that users can perform within the system. For example, the function access profile for a manager can include permission to edit schedules and timecards. The FunctionAccessProfile and WSAFunctionAccessProfile tags refer to the same database object. Function Access Control Point: API.Employee Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllFunctionAccessProfiles" | "LoadById" Parameters→ None Properties→ <FunctionAccessProfile [FunctionAccessProfileId = Integer] [FunctionAccessProfileName = String] > </FunctionAccessProfile>

Action Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

313

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Load Returns a function access profile, based on FunctionAccessProfileName. Return Value Type: FunctionAccessProfile tag Required Properties: FunctionAccessProfileName Access Control Point Name: View Introduced in v4 LoadAllFunctionAccessProfiles Returns all function access profiles in the system. Return Value Type: Zero or more FunctionAccessProfile tags Access Control Point Name: View Introduced in v4 LoadById Returns a function access profile, based on FunctionAccessProfileId. ID must be valid Return Value Type: FunctionAccessProfile tag Required Properties: FunctionAccessProfileId Access Control Point Name: View Introduced in v4

Property Descriptions
FunctionAccessProfileId

Function access profile ID
Uniquely identifies the function access profile in the database Type: Integer Optional Introduced in v4

314

Kronos Incorporated

FunctionAccessProfile Tag

FunctionAccessProfileName

Function access profile name
The name of the person's function access profile. The function access profile determines the timekeeping components that users can access and the types of functions that users can perform within timekeeping, based on their assigned roles. For example, access profiles for Managers can include permission to edit schedules and timecards. The same profile can be assigned to a group of similar users, such as managers in the same department. The system administrator creates the access profiles. Refer to the timekeeping System Administrator's Guide for an explanation of the roles. The following predefined data values are provided: • • • • IS Payroll Manager Time Stamp Employee Workforce Employee

Type: String Optional Maximum length: 50 characters Default value: Default Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

315

Chapter 2

Workforce Timekeeper XML API Tag Definitions

GDAPAssignment Tag Generic Data Access Profile Assignment
This tag lets users associate a generic data access profile with a person. Function Access Control Point: Regional Configuration Introduced in v6.0; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "Delete" | "ExpireNow" | "Load" | "RetrieveByGDAPName" | "RetrieveByPersonId" | "RetrieveByPersonIdAndRole" | "Update" | "UpdateOnly" Parameters→ None Properties→ <GDAPAssignment DefaultSwitch = Boolean [EffectiveDate = Date] [ExpirationDate = Date] GDAPName = String [OriginalEffectiveDate = Date] [OriginalExpirationDate = Date] Role = String > <Identity> <PersonIdentity>

316

Kronos Incorporated

GDAPAssignment Tag

</Identity> </GDAPAssignment>

Action Descriptions
AddOnly Creates a new GDAP assignment object to associate a Person with a GDAP. At least one GDAP Assignment must be the default for the user; if this is the first one, it MUST be set to true. If multiple assignments are made with the default switch set to true, only the last one in will be the default. Return Value Type: None Required Properties: Identity, GDAPName, EffectiveDate, ExpirationDate, Role, DefaultSwitch Access Control Point Name: Edit Introduced in v6.0 Delete Finds an existing GDAP assignment based on the GDAPName and either the EffectiveDate, the ExpirationDate, or both, and removes that GDAP assignment. Either EffectiveDate or ExpirationDate or both must be present or an error will be thrown. Return Value Type: None Required Properties: Identity, GDAPName, EffectiveDate and/or ExpirationDate Access Control Point Name: Edit Introduced in v6.0 ExpireNow Expires matching GDAP assignment object at current date/time. GDAP Assignment for this employee must exist with the other matching properties. Return Value Type: None Required Properties: Identity, GDAPName, EffectiveDate, Role Access Control Point Name: Edit

Workforce Central Developers Toolkit Reference Guide—Timekeeping

317

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v6.0 Load Returns a list of GDAPs assigned to the person given in the Identity. If the given person has no GDAP assignments, the list will be empty. If the person does not exist an error will be thrown. Return Value Type: Zero or more GDAPAssignment tags Required Properties: Identity Access Control Point Name: View Introduced in v6.0 RetrieveByGDAPName Returns an object of type DataAccessGroupAssignmentSet containing all DataAccessGroupAssignment objects for this GDAP. If no GDAP assignments can be found for the given GDAPName an error will be thrown. Return Value Type: Collection list Required Properties: GDAPName Access Control Point Name: View Introduced in v6.0 RetrieveByPersonId Returns a list of GDAPs assigned to the person given in the Identity. If the given person has no GDAP assignments, the list will be empty. If the person does not exist an error will be thrown. Return Value Type: Collection list Required Properties: Identity Access Control Point Name: View Introduced in v6.0 RetrieveByPersonIdAndRole Retrieves a list of GDAP objects for the person specified in the Identity property, and of the type (Manager, Employee) given in the Role property. If Role is not specified, this action will effectively be the same as the RetrieveByPersonId

318

Kronos Incorporated

GDAPAssignment Tag

action. If the person does not have any GDAP assignments, an empty list will be returned. If the person does not exist, an error will be thrown. Return Value Type: Collection list Required Properties: Identity Optional Properties: Role Access Control Point Name: View Introduced in v6.0 Update Updates an existing GDAP assignment. At least one GDAP Assignment must be the default for the user; if this is the first one, it MUST be set to true. If multiple assignments are made with the default switch set to true, only the last one in will be the default. Return Value Type: None Required Properties: Identity, GDAPName, Role, EffectiveDate, ExpirationDate, DefaultSwitch, OriginalEffectiveDate, OriginalExpirationDate Access Control Point Name: Edit Introduced in v6.0 UpdateOnly Updates an existing GDAP assignment object. At least one GDAP Assignment must be the default for the user; if this is the first one, it MUST be set to true. If multiple assignments are made with the default switch set to true, only the last one in will be the default. Return Value Type: None Required Properties: Identity, GDAPName, Role, EffectiveDate, ExpirationDate, DefaultSwitch, OriginalEffectiveDate, OriginalExpirationDate Access Control Point Name: Edit Introduced in v6.0

Property Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

319

Chapter 2

Workforce Timekeeper XML API Tag Definitions

DefaultSwitch

Default Switch
Indicates whether the generic data access profile assignment should be used as the person's default profile. Type: Boolean Required Should be either "true" or "false". Sample values: true Default value: false Introduced in v6.0 EffectiveDate

Effective Date
Specify the effective date of the generic data access profile. Type: Date Optional Introduced in v6.0 ExpirationDate

Expiration Date
Specify the expiration date of the generic data access profile. Type: Date Optional Introduced in v6.0 GDAPName

Generic Data Access Profile Name

320

Kronos Incorporated

GDAPAssignment Tag

Specify the name of the generic data access profile to be assigned. Type: String Required Introduced in v6.0 Identity

Identity
Specify the identity of the person who will be assigned the generic data access profile. Type: PersonIdentity tag Required Introduced in v6.0 OriginalEffectiveDate

OriginalEffective Date
Specify the original effective date of the generic data access profile, which you can use later for updates. Type: Date Optional Introduced in v6.0; last changed in v6.0 OriginalExpirationDate

OriginalExpiration Date
Specify the original expiration date of the generic data access profile, which you can use later for updates. Type: Date Optional Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

321

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Role

Role (Manager, Employee)
Specify either "MANAGER_ROLE" or "EMPLOYEE_ROLE" for the role. Type: String Required Must be either "MANAGER_ROLE" or "EMPLOYEE_ROLE" Introduced in v6.0

322

Kronos Incorporated

GDAPAssignmentDefaultSwitch Tag

GDAPAssignmentDefaultSwitch Tag General Data Access Profile Assignment Default
This tag lets you assign users to a default generic data access profile that contains selected data. Function Access Control Point: Regional Configuration Introduced in v6.0; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Update" Parameters→ None Properties→ <GDAPAssignmentDefaultSwitch GDAPName = String Role = String > </GDAPAssignmentDefaultSwitch>

Action Descriptions
Update Changes the default Generic Data Access Profile for the logged on user. Must have Role and GDAP name Return Value Type: GDAPAssignmentDefaultSwitch tag Required Properties: GDAP Name, Role Access Control Point Name: Edit

Workforce Central Developers Toolkit Reference Guide—Timekeeping

323

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v6.0

Property Descriptions
GDAPName

Generic Data Access Profile name
Specify the name of the default generic data access profile for the user that has signed into the application. Type: String Required Introduced in v6.0 Role

Role
Specify the role of the default generic data access profile assignment. Type: String Required Must be either "MANAGER_ROLE" or "EMPLOYEE_ROLE" Introduced in v6.0

324

Kronos Incorporated

GDAPItem Tag

GDAPItem Tag Generic Data Access Profile Item
This tag lets you add generic data access profile items, such as Pay Codes, to the Data Access Group. Function Access Control Point: Regional Configuration Introduced in v6.0; last changed in v6.0

Syntax
Properties→ <GDAPItem Name = String Type = String > </GDAPItem>

Property Descriptions
Name

Name
Specify the name of genric data access profile. Use a name that is meaningful for your configuration. Type: String Required The name property cannot be empty. Introduced in v6.0 Type

Type
Specify the type of generic data access profile, for example, Pay Codes. Type: String

Workforce Central Developers Toolkit Reference Guide—Timekeeping

325

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required The Type property cannot be empty. Introduced in v6.0

326

Kronos Incorporated

GenericEmployeeCalendar Tag

GenericEmployeeCalendar Tag Default calendar view for employees
The tag for a generic calendar view in a calendar profile used by employees. A generic calendar is based on a single calendar data set. It includes a default time period and other attributes that define the calendar display. The generic calendars that are available, either from the default installation or that you create, are the basis for calendar profiles that are assigned directly to individuals. Each generic calendar is specific to either managers or to employees. This tag applies to generic calendars for employees. Function Access Control Point: Calendar framework Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Add" | "AddOnly" | "Delete" | "RetrieveAll" | "RetrieveAllByName" | "RetrieveAllByNameAndActive" | "RetrieveById" | "RetrieveByName" | "Update" Parameters→ None Properties→ <GenericEmployeeCalendar [TimePeriodId = Integer]

Workforce Central Developers Toolkit Reference Guide—Timekeeping

327

Chapter 2

Workforce Timekeeper XML API Tag Definitions

[MonthWidth = Integer] [ViewType = Integer] [Description = String] [Active = Boolean] Name = String DataSetName = String [DisplayName = String] > </GenericEmployeeCalendar>

Action Descriptions
Add Adds a generic employee calendar, if the calendar with the same name exists, it will be updated. Return Value Type: None Required Properties: Name, Description, active, dataSetName, displayName, viewType, monthWidth, timePeriodId Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 AddOnly Adds a generic employee calendar, the operation will fail if a calendar with the same name exists. Return Value Type: None Required Properties: Name, Description, active, dataSetName, displayName, viewType, monthWidth, timePeriodId Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 Delete Deletes a generic employee calendar. The operation will fail if the calendar doesn't exist. Return Value Type: None Access Control Point Name: Edit

328

Kronos Incorporated

GenericEmployeeCalendar Tag

Introduced in v5.1; last changed in v5.1 RetrieveAll Returns all the generic employee calendars. Return Value Type: Zero or more GenericEmployeeCalendar tags Access Control Point Name: View Introduced in v5.1; last changed in v5.1 RetrieveAllByName Searches for generic employee calendars by name. Return Value Type: Zero or more GenericEmployeeCalendar tags Required Properties: Name Access Control Point Name: View Introduced in v5.1; last changed in v5.1 RetrieveAllByNameAndActive Searches for generic employee calendars by name and active. Return Value Type: Zero or more GenericEmployeeCalendar tags Required Properties: Name, Active Access Control Point Name: View Introduced in v5.1; last changed in v5.1 RetrieveById Returns the specified employee generic calendar. The operation will fail if the calendar doesn't exist. Return Value Type: GenericEmployeeCalendar tag Access Control Point Name: View Introduced in v5.1; last changed in v5.1 RetrieveByName Returns the specified generic employee calendar. The operation will fail if the calendar doesn't exist. Return Value Type: GenericEmployeeCalendar tag

Workforce Central Developers Toolkit Reference Guide—Timekeeping

329

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required Properties: Name Access Control Point Name: View Introduced in v5.1; last changed in v5.1 Update Updates a generic employee calendar. If the calendar doesn't exist, it will be added. Return Value Type: None Required Properties: name Optional Properties: newName, Description, active, dataSetId, displayName, viewType, monthWidth, timePeriodId Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1

Property Descriptions
Active

Is the employee calendar active?
True if the default employee calendar view is active; false if it is not. Type: Boolean Optional Sample values: True Enumerated value: True, False Introduced in v5.1; last changed in v5.1 DataSetName

Name of the base calendar data set
The name of the calendar data set that is the basis for the generic calendar. Each default calendar view is based on a single calendar data set.

330

Kronos Incorporated

GenericEmployeeCalendar Tag

Type: String Required Introduced in v5.1; last changed in v5.1 Description

Description of the default calendar view
The description of the default calendar view for employees. Type: String Optional Introduced in v5.1; last changed in v5.1 DisplayName

Name to display in the user interface
The display name of the default employee calendar view. Type: String Optional Introduced in v5.1; last changed in v5.1 MonthWidth

Default number of months to display
The default width of months in multiple months display. Even if you select one week or one month as the default time period for the calendar width, you might want to choose a default number of months, to accommodate individual users who change their calendar view to multiple months. Type: Integer Optional Introduced in v5.1; last changed in v5.1 Name

Name of default calendar view

Workforce Central Developers Toolkit Reference Guide—Timekeeping

331

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The unique name of the default view to use for the employee calendar. Type: String Required Key Introduced in v5.1; last changed in v5.1 TimePeriodId

Default date range to display
The date range that the calendar will initially display. If you use a relative range of dates, you must also enter time periods that are before and after the current date; the resulting calendar display will include the relative dates that you specify. Type: Integer Optional Introduced in v5.1; last changed in v5.1 ViewType

Default time period to display
The default time period display for the calendar. Use 1 for weekly view; 2 for monthly view; or 3 for multiple months view. To select the number of months in a multiple month view, use the MonthWidth property. Type: Integer Optional Enumerated value: 1,2,3 Introduced in v5.1; last changed in v5.1

332

Kronos Incorporated

GenericEmployeeCalendarAPIFacade Tag

GenericEmployeeCalendarAPIFacade Tag Change the default employee calendar view
Creates or modifies the default employee calendar view using Setup Data Manager. Function Access Control Point: API.CALENDAR_VIEWS_SETUP Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveAllNames" | "RetrieveForUpdate" | "Update" Parameters→ None Properties→ <GenericEmployeeCalendarAPIFacade Name = String > </GenericEmployeeCalendarAPIFacade>

Action Descriptions
RetrieveAllNames Retrieves all names of Generic Employee Calendars. Return Value Type: Zero or more NameList tags Access Control Point Name: View Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

333

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RetrieveForUpdate Retrieves the Generic Employee calendar corresponding to the name. Return Value Type: GenericEmployeeCalendarAPIFacade tag Required Properties: Name Access Control Point Name: View Introduced in v5.2 Update Updates the Generic Employee calendar corresponding to name. Return Value Type: None Required Properties: Name Access Control Point Name: Edit Introduced in v5.2

Property Descriptions
Name

Default employee calendar view name
Name of the default employee calendar view to create or modify. Type: String Required Key Introduced in v5.2

334

Kronos Incorporated

GenericManagerCalendar Tag

GenericManagerCalendar Tag Generic Manager Calendar
The tag for a generic calendar view in a calendar profile used by managers. A generic calendar is based on a single calendar data set. It includes a default HyperFind query, a default time period, and other attributes that define the calendar display. The generic calendars that are available, either from the default installation or that you create, are the basis for calendar profiles that are assigned directly to individuals. Each generic calendar is specific to either managers or to employees. This tag applies to generic calendars for managers. Function Access Control Point: Calendar framework Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Add" | "AddOnly" | "Delete" | "RetrieveAll" | "RetrieveAllByName" | "RetrieveAllByNameAndActive" | "RetrieveById" | "RetrieveByName" | "Update" Parameters→ None Properties→ <GenericManagerCalendar

Workforce Central Developers Toolkit Reference Guide—Timekeeping

335

Chapter 2

Workforce Timekeeper XML API Tag Definitions

[NavBarCategoryId = Long] DataSetName = Long [Description = String] Name = String [HyperFindQueryId = Long] [Active = Boolean] [DisplayName = String] [TimePeriodId = Integer] [ViewType = Integer] [MonthWidth = Integer] > </GenericManagerCalendar>

Action Descriptions
Add Adds a generic manager calendar, if a calendar with the same name exists, it will be updated. Return Value Type: None Required Properties: name, Description, active, dataSetName, displayName, viewType, monthWidth, timePeriodId, hperFindQueryId, navBarCategoryId Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 AddOnly Adds a generic manager calendar, the operation will fail if a calendar with the same name exists. Return Value Type: None Required Properties: name, Description, active, dataSetName, displayName, viewType, monthWidth, timePeriodId, hperFindQueryId, navBarCategoryId Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 Delete Deletes a generic manager calendar. The operation will fail if the calendar doesn't exist.

336

Kronos Incorporated

GenericManagerCalendar Tag

Return Value Type: None Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 RetrieveAll Returns all the generic manager calendars. Return Value Type: Zero or more GenericManagerCalendar tags Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 RetrieveAllByName Searches for generic manager calendars by name. Return Value Type: Zero or more GenericManagerCalendar tags Required Properties: Name Access Control Point Name: View Introduced in v5.1; last changed in v5.1 RetrieveAllByNameAndActive Searches for generic manager calendars by name and active. Return Value Type: Zero or more GenericManagerCalendar tags Required Properties: Name, Active Access Control Point Name: View Introduced in v5.1; last changed in v5.1 RetrieveById Returns the specified generic manager calendar. The operation will fail if the calendar doesn't exist. Return Value Type: GenericManagerCalendar tag Access Control Point Name: View Introduced in v5.1; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

337

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RetrieveByName Returns the specified generic manager calendar. The operation will fail if the calendar doesn't exist. Return Value Type: GenericManagerCalendar tag Required Properties: Name Access Control Point Name: View Introduced in v5.1; last changed in v5.1 Update Updates a generic manager calendar. If the calendar doesn't exist, it will be added. Return Value Type: None Required Properties: name Optional Properties: newName, Description, active, dataSetId, displayName, viewType, monthWidth, timePeriodId, hperFindQueryId, navBarCategoryId Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1

Property Descriptions
Active

Is the generic manager calendar active?
True if a generic manager calendar is active, false if it's not. Type: Boolean Optional Sample values: True Enumerated value: True, False Introduced in v5.1; last changed in v5.1

338

Kronos Incorporated

GenericManagerCalendar Tag

DataSetName

Data Set Name
The name of the calendar data set that is the basis for the generic calendar. Each generic calendar is based on one and only one calendar data set. Type: Long Required Introduced in v5.1; last changed in v5.1 Description

Description
The description of a generic manager calendar. Type: String Optional Introduced in v5.1; last changed in v5.1 DisplayName

Name to display in the user interface
The display name of the generic manager calendar. Type: String Optional Introduced in v5.1; last changed in v5.1 HyperFindQueryId

HyperFind Query Id
The name of the default HyperFind query that this generic calendar will use. Note that the default HyperFind query is available only on generic calendars for managers, and not on generic calendars for employees. Type: Long Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

339

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.1; last changed in v5.1 MonthWidth

Width of Month
The default width of months in multiple months display. Even if you select one week or one month as the default time period for the calendar width, you might want to choose a default number of months, to accommodate individual users who change their calendar view to multiple months. Type: Integer Optional Introduced in v5.1; last changed in v5.1 Name

Generic Manager Calendar Name
The unique name of a generic manager calendar. Type: String Required Key Introduced in v5.1; last changed in v5.1 NavBarCategoryId

Category Id of the assigned navigation bar
The navigation bar category for this generic calendar (for example, Timekeeping, Scheduling, and so on). Note that the navigation bar category is available only on generic calendars for managers, and not on generic calendars for employees. Type: Long Optional Introduced in v5.1; last changed in v5.1 TimePeriodId

Time Period Id

340

Kronos Incorporated

GenericManagerCalendar Tag

The date range that the calendar will initially display. If you use a relative range of dates, you must also enter time periods that are before and after the current date; the resulting calendar display will include the relative dates that you specify. Type: Integer Optional Introduced in v5.1; last changed in v5.1 ViewType

View Type
The default time period display for the calendar. Use 1 for weekly view, 2 for monthly view, or 3 for multiple months view. (You select the number of months in a multiple month view using the MonthWidth property.) Type: Integer Optional Enumerated value: 1,2,3 Introduced in v5.1; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

341

Chapter 2

Workforce Timekeeper XML API Tag Definitions

GenericManagerCalendarAPIFacade Tag Generic Manager Calendar Facade
Creates or modifies Generic Manager Calendar using the SDM API. Function Access Control Point: API.CALENDAR_VIEWS_SETUP Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveAllNames" | "RetrieveForUpdate" Parameters→ None Properties→ <GenericManagerCalendarAPIFacade Name = String > </GenericManagerCalendarAPIFacade>

Action Descriptions
RetrieveAllNames Retrieves all names of Generic Manager calendars. Return Value Type: Zero or more NameList tags Access Control Point Name: View Introduced in v5.2

342

Kronos Incorporated

GenericManagerCalendarAPIFacade Tag

RetrieveForUpdate Retrieves the Generic manager calendar corresponding to the name for update using the SDM API. Return Value Type: GenericManagerCalendarAPIFacade tag Required Properties: Name Access Control Point Name: View Introduced in v5.2

Property Descriptions
Name

Name
Name Type: String Required Key Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

343

Chapter 2

Workforce Timekeeper XML API Tag Definitions

GenieColumn Tag Column Definition
The GenieColumn tag contains metadata. Function Access Control Point: API.Genie Introduced in v5.2; last changed in v5.2

Syntax
Properties→ <GenieColumn ColumnNumber = Integer ExitNum = Integer Label = String Product = String Width = Integer > </GenieColumn>

Property Descriptions
ColumnNumber

Column Number
The position of the column, which can be found in Display Preferences Setup. Type: Integer Required Introduced in v5.2 ExitNum

Exit Number
The extension number. Product and ExitNum makes an unique key to identify a column data type Type: Integer

344

Kronos Incorporated

GenieColumn Tag

Required Introduced in v5.2 Label

Label
The column label, which can be found in Display Preferences Setup. Type: String Required Introduced in v5.2; last changed in v5.2 Product

Product
The name of the product that this column belongs to. Type: String Required Introduced in v5.2 Width

Width
The column width in pixels, which can be found in Display Preferences Setup. Type: Integer Required Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

345

Chapter 2

Workforce Timekeeper XML API Tag Definitions

GenieRow Tag Row Definition
The GenieRow tag contains data for a row. Function Access Control Point: API.Genie Introduced in v5.2; last changed in v5.2

Syntax
Properties→ <GenieRow ColumnN = String RowKey = Integer > </GenieRow>

Property Descriptions
ColumnN

Column referenced in a row
The data for column N in this row. Column N is described by a GenieColumn tag. Type: String Required Introduced in v5.2; last changed in v5.2 RowKey

Row Key
The value of this attribute depends on what is loaded: Detail, QuickFind or Schedule Group Detail: person key • • Roll-Up: labor account name Schedule Roll-Up: schedule group name

Type: Integer

346

Kronos Incorporated

GenieRow Tag

Required Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

347

Chapter 2

Workforce Timekeeper XML API Tag Definitions

GlsegmentDetail Tag GlSegment Detail
The GLSegmentDetail tag describes the labor level segment information when two or more location types map to the same labor level. Function Access Control Point: Organizational Maps Introduced in v6.0; last changed in v6.0

Syntax
Properties→ <GlsegmentDetail [AllowNewLLEntries = Boolean] [endSeparatorCharacter = String] [FillCharacter = String] [FillPosition = String] [LaborLevelName = String] [SegmentLength = Integer] [SegmentNumber = Integer] > </GlsegmentDetail>

Property Descriptions
AllowNewLLEntries

Allow New labor Level Entry
Specify whether you can create new labor level entries as part of creating new locations for this location type. Specify either yes or no. Type: Boolean Optional Introduced in v6.0 endSeparatorCharacter

End Separator Character

348

Kronos Incorporated

GlsegmentDetail Tag

Specify the character used to separate segments of a labor level entry. Type: String Optional the length is 1 Introduced in v6.0 FillCharacter

Filled Character
Specify the character used to complete a labor level entry when an organizational job does not contain all the location types that are associated with a segmented labor level. Type: String Optional the length is 1 Introduced in v6.0 FillPosition

Filled Position
Specify the position to insert a fill character when a segment of the labor level entry does not meet the segment length criteria. Type: String Optional either "Trailing" or "Leading" Introduced in v6.0; last changed in v6.0 LaborLevelName

Labor level definition name
Specify the name of labor level to which the location type maps. Type: String Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

349

Chapter 2

Workforce Timekeeper XML API Tag Definitions

must be exist in the system Introduced in v6.0 SegmentLength

Segment Length
Specify the number of characters in the labor level segment to which the location type maps. Type: Integer Optional Introduced in v6.0 SegmentNumber

Segment Number
Specify the part of a labor level entry to which the location type maps. Type: Integer Optional Introduced in v6.0; last changed in v6.0

350

Kronos Incorporated

GroupMembership Tag

GroupMembership Tag Group Membership
The GroupMembership tag identifies employees who belong to a group during a specified time period. Used by: ScheduleGroup Function Access Control Point: API.Schedule Introduced in v4; last changed in v6.0

Syntax
Properties→ <GroupMembership EffectiveDateSpan = DateSpan > <Employee> <CurrentUser> | <PersonIdentity> </Employee> </GroupMembership>

Property Descriptions
EffectiveDateSpan

Span of time when employee is member of group
The period of time when the specified employee belongs to the group Type: DateSpan Required Introduced in v4 Employee

Employee
One employee who belongs to the group, as specified in a PersonIdentity or CurrentUser tag.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

351

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: Either CurrentUser or PersonIdentity tag Required Must uniquely identify an existing and active employee Introduced in v4

352

Kronos Incorporated

Headcount Tag

Headcount Tag Daily Staffing Data
The Headcount tag defines the staffing data for a given day of the week in the date range. Used by: HeadcountPattern Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.1

Syntax
Properties→ <Headcount DayOfWeek = String NumberOfStaffs = Integer > </Headcount>

Property Descriptions
DayOfWeek

Day of the week
Represents each day of the week Dependency: Values that can be specified for this property depend on the value of the PatternDurationType property in the EffectiveWorkload tag as follows: If the value of PatternDurationType property is "Daily", the value of this property must be "Anyday" If the value of PatternDurationType property is "Weekly", seven Headcount tags must be created. Each one must identify a different day of the week. Type: String Required The value "Anyday" can only be used for holiday or daily workload patterns

Workforce Central Developers Toolkit Reference Guide—Timekeeping

353

Chapter 2

Workforce Timekeeper XML API Tag Definitions

You must use the English name for the day, even if your application server is configured to use a different national language. Enumerated value: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Anyday Introduced in v5.0; last changed in v5.1 NumberOfStaffs

Number of staff required
The total number of staff required for a given day of the week Type: Integer Required Introduced in v5.0

354

Kronos Incorporated

HeadcountPattern Tag

HeadcountPattern Tag Daily Staffing Pattern
The HeadcountPattern tag defines the staffing data pattern for each day of the week in the workload. Used by: EffectiveWorkload Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.2

Syntax
Properties→ <HeadcountPattern WorkloadSpanName = String > <Headcounts> <Headcount>* </Headcounts> </HeadcountPattern>

Property Descriptions
Headcounts

Staffing data for pattern
Staffing data for specific days of the week. Dependency: The number of items in this list depends on the value of the PatternDurationType property in the EffectiveWorkload tag. - If the value of PatternDurationType is "Daily", then this list must contain one item. - If the value of PatternDurationType is "Weekly", then this list must contain seven items. Type: Zero or more Headcount tags Required

Workforce Central Developers Toolkit Reference Guide—Timekeeping

355

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.0; last changed in v5.2 WorkloadSpanName

Workload span
The workload span for the staffing data. Type: String Required Must match an existing shift name or zone name that is assigned to the location. Introduced in v5.0

356

Kronos Incorporated

HistoricalPayCodeEdit Tag

HistoricalPayCodeEdit Tag Historical Pay Code Edit
The HistoricalPayCodeEdit tag makes a pay code edit in a signed-off or locked pay period. You can make historical edits only to pay code amounts. Function Access Control Point: API.Timecard Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddComment" | "AddOnly" | "Delete" Parameters→ AddOnly→ [AccrualOverride = Boolean] [allowAdHoc = Boolean] [EchoData = Boolean] Properties→ <HistoricalPayCodeEdit [ImpactsAccrualsFlag = Boolean] AmountInTimeOrCurrency = String [CommentText = String] (EnteredOnDate = Date) HistoricalDate = Date Date = Date [PaidFlag = Boolean] [LaborAccountName = String] PayCodeName = String (EnteredOnTime = Time) [WorkRuleName = String] >

Workforce Central Developers Toolkit Reference Guide—Timekeeping

357

Chapter 2

Workforce Timekeeper XML API Tag Definitions

[<Notes> <Note>* </Notes>] (<Comments> <Comment>* </Comments>) <Employee> <CurrentUser> | <PersonIdentity> </Employee> </HistoricalPayCodeEdit>

Action Descriptions
AddComment Adds a comment to the set of comments associated with the existing historical pay code edit. Acceptable values can be found in the Setup Application. Return Value Type: None Required Properties: AmountInTimeOrCurrency, CommentText, Date, HistoricalDate, Employee, PayCodeName Access Control Point Name: Edit Introduced in v4 AddOnly Adds a new historical pay code edit for the specified employee. There is no limit to the number of historical pay code edits that an employee can have. Return Value Type: HistoricalPayCodeEdit tag Required Properties: AmountInTimeOrCurrency, Date, HistoricalDate, Employee, PayCodeName Access Control Point Name: Edit Introduced in v4

358

Kronos Incorporated

HistoricalPayCodeEdit Tag

Action Parameters Parameter Name AccrualOverride Description If the action results in an accrual warning, the warning is overridden when AccrualOverride = True. Optional Default value: False Specifies whether an ad hoc labor level is allowed. Optional Default value: False If True, the Response includes a copy of this tag. Optional Default value: False Additional information Introduced in v4

allowAdHoc

Introduced in v5.0; last changed in v5.0; deprecated in v5.0. Not used Introduced in v4

EchoData

Delete Marks for deletion all historical pay code edits for this employee, matching the given date, time, and labor account. At least one historical pay code edit must exist for the specified employee whose required properties match the supplied properties. Return Value Type: None Required Properties: AmountInTimeOrCurrency, Date, HistoricalDate, Employee, PayCodeName Access Control Point Name: Edit Introduced in v4

Property Descriptions
AmountInTimeOrCurrency

Amount of pay code, in time or currency
A value that can represent money or time, depending on the PayCodeName.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

359

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The value is a monetary amount if PayCodeName is a money type or time if PayCodeName is a time type. Type: String Required, Key Maximum of 30 characters. Introduced in v4; last changed in v5.1 Comments

Comments
The set of comments currently associated with this timekeeping item. Type: Zero or more Comment tags Output only Introduced in v4 CommentText

Comment text
Text that is attached to the pay code amount or totaled amount. Note: A comment entered as part of a historical amount is not used as part of the criteria when an import delete is issued for the same historical amount. Type: String Optional Maximum length: 254 characters Must exactly match an applicable comment that already exists. The string matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application. Introduced in v4 Date

Effective date of the edit
The date on which the pay code edit becomes effective.

360

Kronos Incorporated

HistoricalPayCodeEdit Tag

Type: Date Required, Key Introduced in v4 Employee

Employee
One employee for whom the edit applies, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Required, Key Must uniquely identify an existing and active employee Introduced in v4 EnteredOnDate

Date on which the user performed the edit
The server date on which this edit was added to the database. Type: Date Output only Introduced in v4 EnteredOnTime

Time at which the user performed the edit
The server time at which this edit was added to the database. Type: Time Output only Introduced in v4 HistoricalDate

Date to which the edit applies
The date to which the historical edit is applied.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

361

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: Date Required, Key The specified date must be within a locked pay period. Introduced in v4 ImpactsAccrualsFlag

Accrual balance adjusted based on historical amount?
Determines whether the accrual balances should be adjusted based on the historical amount. Its value is: • • False if the employee's accrual balances should not be adjusted based upon the historical amount entered True if the employee's accrual balances should be adjusted based upon the historical amount entered

Type: Boolean Optional Default value: False Enumerated value: True, False Introduced in v4 LaborAccountName

Labor account
The name of the labor account of the employee whose pay code amount or totaled amount is being edited. It is required when the pay code edit, historical edit, or totaled amount being deleted or commented, contained an explicit value. This property need not be specified if the pay code amount or totaled amount applies to the employee's primary account. It is required if you are deleting or adding a comment to a pay code edit that contains an explicit LaborAccountName value. Enter data for labor accounts in the same format as they appear in the database. For example, if you have a seven-level labor account, specify a value for each labor level, using the following format: 101/202/303/404/504/603/702.

362

Kronos Incorporated

HistoricalPayCodeEdit Tag

Do not specify labor levels that are not changing. For example, you can enter the value 101//303////, indicating that only the first and third labor level entries are different. If any of the labor levels are the same as the employee's primary labor account, you can enter @H for those labor levels instead of entering the labor entry names. Type: String Optional Maximum length: 356 characters. Default value: Primary account for the employee Introduced in v4; last changed in v5.0 Notes

Comment Note
The list of notes for the comment to be created from comment text Type: Zero or more Note tags Optional Introduced in v6.0 PaidFlag

Included in totals for the employee?
Determines whether the historical amount is tracked and included in the employee's totals. Value can be: • • False means that the amount supplied is tracked, but is not included in the employee's totals for the current pay period. True means that the amount supplied is tracked and included in the employee's totals for the current pay period.

Type: Boolean Optional Default value: False

Workforce Central Developers Toolkit Reference Guide—Timekeeping

363

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Enumerated value: True, False Introduced in v4; last changed in v5.1 PayCodeName

Pay code
Identifies the name of the pay code that is being applied to an amount associated with a historical amount. A pay code represents an amount in time or currency. It can represent one of the following units: • The hours accumulated during a pay period. A pay code that holds hours can contain worked hours (such as regular, overtime, or second shift) or unworked hours (such as vacation, sick, or personal). Money earned by employees during a pay period. For example, if hours are allocated for J.D. Smith, who worked 8 regular and 4 overtime hours for a total of 12 hours, there will be two pay code edit entries: An entry with 8 regular hours An entry with 4 overtime hours

• •

• •

Type: String Required, Key Maximum length: 50 characters Introduced in v4 WorkRuleName

Work rule
DEPRECATED. Name of the work rule. A work rule applies specific payroll rules to shifts that determine how employee hours accrue. The following predefined data values are provided: • • &ALL_WORK_RULES &EMPTY

364

Kronos Incorporated

HistoricalPayCodeEdit Tag

Type: String Optional Maximum length: 50 characters You can find values in Setup. Introduced in v4; deprecated in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

365

Chapter 2

Workforce Timekeeper XML API Tag Definitions

HistoricalPayCodeMove Tag Historical Pay Code Move
The HistoricalPayCodeMove tag moves historical amounts of time or money for an individual employee or for a group of employees. When you move historical amounts from one pay code to another, the historical date must be in a signed-off or locked pay period. Function Access Control Point: API.Timecard Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddComment" | "AddOnly" | "Delete" Parameters→ AddOnly→ [AccrualOverride = Boolean] [allowAdHoc = Boolean] [EchoData = Boolean] Properties→ <HistoricalPayCodeMove AmountInTimeOrCurrency = String [ImpactsAccrualsFlag = Boolean] [CommentText = String] (EnteredOnDate = Date) Date = Date HistoricalDate = Date [LaborAccountName = String] FromLaborAccountName = String PayCodeName = String

366

Kronos Incorporated

HistoricalPayCodeMove Tag

FromPayCodeName = String (EnteredOnTime = Time) [WorkRuleName = String] > [<Notes> <Note>* </Notes>] (<Comments> <Comment>* </Comments>) <Employee> <CurrentUser> | <PersonIdentity> </Employee> </HistoricalPayCodeMove>

Action Descriptions
AddComment Adds a comment to the set of comments associated with this historical pay code move. Return Value Type: None Required Properties: AmountInTimeOrCurrency, CommentText, Date, FromLaborAccountName, FromPayCodeName, HistoricalDate, Employee, PayCodeName Access Control Point Name: Edit Introduced in v4 AddOnly Adds a new historical pay code edit with the specified properties for this employee. There is no limit to the number of historical pay code edits that you can add for an employee. Return Value Type: HistoricalPayCodeMove tag Required Properties: AmountInTimeOrCurrency, Date, FromLaborAccountName, FromPayCodeName, HistoricalDate, Employee, PayCodeName Access Control Point Name: Edit Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

367

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Parameters Parameter Name AccrualOverride Description If the action results in an accrual warning, the warning is overridden when AccrualOverride = True. Optional Default value: False Specifies whether an ad hoc labor level is allowed. Optional Default value: False If True, the Response includes a copy of this tag. Optional Default value: False Additional information Introduced in v4

allowAdHoc

Introduced in v5.0; last changed in v5.0; deprecated in v5.0. Not used Introduced in v4

EchoData

Delete Marks all historical pay code edits for an employee that match a set of specified requirements for deletion. Return Value Type: None Required Properties: AmountInTimeOrCurrency, Date, FromLaborAccountName, FromPayCodeName, HistoricalDate, Employee, PayCodeName Access Control Point Name: Edit Introduced in v4

Property Descriptions
AmountInTimeOrCurrency

Amount of pay code, in time or currency
Amount of pay code, expressed as a time duration or a currency. Type: String Required, Key

368

Kronos Incorporated

HistoricalPayCodeMove Tag

Maximum length: 30 characters Whether the value is expressed as a time duration or a currency depends on the pay code. Both PayCodeName and FromPayCodeName must identify pay codes that are of the same payment type; either time or currency. Introduced in v4 Comments

Comments
The set of comments currently returned with this timekeeping item. Type: Zero or more Comment tags Output Only Introduced in v4 CommentText

Comment text
A comment that you can add with this edit Type: String Optional Maximum length: 254 characters Must match exactly an applicable comment that already exists in the database. The string matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application. Introduced in v4 Date

Effective date of the edit
The date on which the edit is applied to correct an event that occurred on the HistoricalDate. Type: Date

Workforce Central Developers Toolkit Reference Guide—Timekeeping

369

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required, Key Introduced in v4 Employee

Employee
The employee for whom the edit applies, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Required, Key Must uniquely identify an existing and active employee Introduced in v4; last changed in v5.1 EnteredOnDate

Date on which the user performed the edit
The server date on which this edit was added to the database. Type: Date Output Only Introduced in v4 EnteredOnTime

Time at which the user performed the edit
The server time at which this edit was added to the database. Type: Time Output Only Introduced in v4 FromLaborAccountName

Labor account that the amount is moved from
If moving time from one labor account to another, the labor account from which the amount is to be moved.

370

Kronos Incorporated

HistoricalPayCodeMove Tag

Type: String Optional, Key Maximum length: 356 characters Ad hoc creation of labor level entries is not supported; the labor level entries must exist. Default value: Primary account for the employee Introduced in v4; last changed in v5.1 FromPayCodeName

Pay code that the amount is moved from
If moving an amount from one pay code to another, the pay code from which the amount is to be moved. Type: String Required, Key Maximum length: 50 characters Both PayCodeName and FromPayCodeName must be associated with the same type of payment; either time or currency. Introduced in v4; last changed in v5.1 HistoricalDate

Historical date to which the edit applies
The past date which this edit is correcting. It can be at or prior to the employee's current signoff timestamp. Type: Date Required, Key Introduced in v4 ImpactsAccrualsFlag

Check edit against accrual balance?

Workforce Central Developers Toolkit Reference Guide—Timekeeping

371

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Indicates whether this edit should be checked against the employee's accrual balances Determines whether the accrual balances should be adjusted based on the historical amount Its value is: • • 0 if the employee's accrual balances should not be adjusted based upon the historical amount entered 1 if the employee's accrual balances should be adjusted based upon the historical amount entered

Type: Boolean Optional Enumerated value: True, False Introduced in v4 LaborAccountName

Labor account
If moving time from one labor account to another, the name of the labor account to which a pay code amount or totaled amount is being applied. LaborAccountName is optional when adding a pay code edit, historical edit, or totaled amount. It is required when the pay code edit, historical edit, or totaled amount being deleted or commented contained an explicit value. This property need not be specified if the pay code amount or totaled amount applies to the employee°Øs primary account. Enter data for labor accounts in the same format as they appear in the timekeeping database. If you have a seven-level labor account, specify a value for each labor level, using the following format: 101/202/303/404/504/603/702 Do not specify labor levels that are not changing. If any of the labor levels are the same as the employee°Øs primary labor account, you can enter @H for those labor levels instead of entering the labor entry names. Type: String Optional

372

Kronos Incorporated

HistoricalPayCodeMove Tag

Maximum length: 356 characters Default value: Primary account for the employee Introduced in v4; last changed in v5.1 Notes

Comment Notes
The list of notes for the comment to be created from comment text Type: Zero or more Note tags Optional Introduced in v6.0 PayCodeName

Pay code
If moving an amount from one pay code to another, the pay code to which the amount is to be moved. Type: String Required, Key Maximum length: 50 characters Both PayCodeName and FromPayCodeName must be associated with the same type of payment; either time or currency. Introduced in v4; last changed in v5.1 WorkRuleName

Work rule
Name of the work rule The following predefined data values are provided: • • &ALL_WORK_RULES &EMPTY

Type: String

Workforce Central Developers Toolkit Reference Guide—Timekeeping

373

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Maximum length: 50 characters You can find values in Setup. Introduced in v4; deprecated in v5.0

374

Kronos Incorporated

HistoryDetails Tag

HistoryDetails Tag History Details
Details of an action in the launch of the PSE. Function Access Control Point: Priority Scheduling Engine Introduced in v6.0

Syntax None

Workforce Central Developers Toolkit Reference Guide—Timekeeping

375

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Holiday Tag Holiday
The Holiday tag denotes a predefined holiday period. The Holiday and WSAHoliday tags refer to the same database object. Function Access Control Point: API.Schedule Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllHolidaysInSpan" Parameters→ None Properties→ <Holiday DateTimeSpan = DateTimeSpan [Name = String] > </Holiday>

Action Descriptions
Load Returns the named holiday for the specified time span. Return Value Type: Holiday tag Required Properties: Name, DateTimeSpan Access Control Point Name: View

376

Kronos Incorporated

Holiday Tag

Introduced in v4; last changed in v5.1 LoadAllHolidaysInSpan Returns all holidays that are effective within the specified date span. Return Value Type: Zero or more Holiday tags Required Properties: DateTimeSpan Access Control Point Name: View Introduced in v4

Property Descriptions
DateTimeSpan

Date and time span
Specifies the date and time span of the holiday Type: DateTimeSpan Required Introduced in v4 Name

Holiday
The name of the holiday Type: String Optional Introduced in v4; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

377

Chapter 2

Workforce Timekeeper XML API Tag Definitions

HolidayEditHours Tag Holiday Edit Hours
The HolidayEditHours tag is generated by the Callable Totalizer as a timesheet item for a Holiday credit if the Holiday Credit Rule is identified as one of the three credit types: fixed number of hours, hours from schedule, or average shift length. Function Access Control Point: API.Timecard Introduced in v4

Syntax
Properties→ <HolidayEditHours (AmountInTimeOrCurrency = String) (Date = Date) (HolidayName = String) (IsCurrencyFlag = Boolean) (PayCodeName = String) > </HolidayEditHours>

Property Descriptions
AmountInTimeOrCurrency

Amount of pay code, in time or currency
Amount of pay code amount, expressed as a time duration or a currency Type: String Output Only Should always be TimeDuration for this tag Introduced in v4 Date

Date to which the edit applies
The date on which the edit is credited

378

Kronos Incorporated

HolidayEditHours Tag

Type: Date Output Only Sample values: 8:00 Vacation on 4/2/2001 Introduced in v4 HolidayName

Holiday
The name of the holiday Type: String Output Only Introduced in v4 IsCurrencyFlag

Is the pay code in currency?
False indicates that the pay code represents a monetary item Type: Boolean Output Only Must always be False Enumerated value: False Introduced in v4 PayCodeName

Pay code
The pay code to be credited with the amount Type: String Output Only Enumerated value: Holiday

Workforce Central Developers Toolkit Reference Guide—Timekeeping

379

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v4

380

Kronos Incorporated

HolidayEditWages Tag

HolidayEditWages Tag Holiday Edit Wages
The HolidayEditWages tag is generated by the Callable Totalizer as a timesheet item for a Holiday credit if the Holiday Credit Rule is identified as one of the three credit types: fixed wages, percent of wages, or average wages. Function Access Control Point: API.Timecard Introduced in v4

Syntax
Properties→ <HolidayEditWages (AmountInTimeOrCurrency = String) (Date = Date) (HolidayName = String) (IsCurrencyFlag = Boolean) (PayCodeName = String) > </HolidayEditWages>

Property Descriptions
AmountInTimeOrCurrency

Amount of pay code, in time or currency
Amount of pay code, expressed as a time duration or a currency Type: String Output Only Should always be Currency for this tag Introduced in v4 Date

Date to which the edit applies
The date on which the edit is credited

Workforce Central Developers Toolkit Reference Guide—Timekeeping

381

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: Date Output Only Sample values: 8:00 Vacation on 4/2/2001 Introduced in v4 HolidayName

Holiday
The name of the holiday Type: String Output Only Introduced in v4 IsCurrencyFlag

Is the pay code in currency?
False indicates that the pay code represents a monetary item. Type: Boolean Output Only Must always be True Enumerated value: True Introduced in v4 PayCodeName

Pay code
The pay code to be credited with the amount Type: String Output Only Enumerated value: Holiday

382

Kronos Incorporated

HolidayEditWages Tag

Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

383

Chapter 2

Workforce Timekeeper XML API Tag Definitions

HomeAccount Tag Home Account
The HomeAccount tag denotes the labor account assigned for the specified time frame. Used by: PersonInformation Function Access Control Point: API.Person Introduced in v4; last changed in v5.0

Syntax
Properties→ <HomeAccount EffectiveDate = Date [ExpirationDate = Date] LaborAccountName = String > </HomeAccount>

Property Descriptions
EffectiveDate

Effective date
The date when the home labor account status becomes effective Type: Date Required Must occur before the expiration date Introduced in v4; last changed in v5.0; deprecated in v5.0. Use this property in the PrimaryLaborAccount tag instead. ExpirationDate

Expiration date
The date when the home labor account expires

384

Kronos Incorporated

HomeAccount Tag

Type: Date Optional Must occur after the effective date Default value: January 1, 3000 Introduced in v4; last changed in v5.0; deprecated in v5.0. Use this property in the PrimaryLaborAccount tag instead. LaborAccountName

Primary labor account
This is the name of the primary labor account of the employee whose pay code amount or totaled amount is being edited. LaborAccountName is optional when adding a pay code edit, historical edit, or totaled amount. It is required when the pay code edit, historical edit, or totaled amount being deleted or commented contains an explicit value. This property need not be specified if the pay code amount or totaled amount applies to the employee's primary account. Enter data for labor accounts in the same format as they appear in the timekeeping database. If you have a seven-level labor account, specify a value for each labor level, using the following format: 101/202/303/404/504/603/702 Do not specify labor levels that are not changing. If any of the labor levels are the same as the employee°Øs primary labor account, you can enter @H for those labor levels instead of entering the labor entry names. Type: String Required Key Maximum length: 356 characters Introduced in v4; last changed in v5.0; deprecated in v5.0. Use this property in the PrimaryLaborAccount tag instead.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

385

Chapter 2

Workforce Timekeeper XML API Tag Definitions

HoursSummary Tag Hours summary for a location
This tag contains the summary of the hours for a specific location. Function Access Control Point: Schedule Planner Introduced in v6.0

Syntax
Properties→ <HoursSummary Amount = String OrgPath = String SummaryType = String ValueType = String > </HoursSummary>

Property Descriptions
Amount

Amount
Specify the amount of hours. Type: String Required Sample values: 42.5000 Introduced in v6.0 OrgPath

Organizational Path
Specify the organizational node path.

386

Kronos Incorporated

HoursSummary Tag

Type: String Required Sample values: Organization/Hospitals/Hosp A/Floor 1/ER Introduced in v6.0 SummaryType

Summary Type
Specify the hours summary for a location type. Type: String Required Sample values: Location Introduced in v6.0 ValueType

Value Type
Specify the hours summary value type. Type: String Required Sample values: GrandSum Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

387

Chapter 2

Workforce Timekeeper XML API Tag Definitions

HoursSummaryService Tag Hours summary items for a location
This service returns all the summary items for a list of locations. Each summary item hold the sum (in hours) of the durations of all ProductiveShifts and PayCodes in the schedule container associated with the specified locations and date range. Function Access Control Point: Schedule Planner Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" Parameters→ None Properties→ <HoursSummaryService QueryDateSpan = String > [<Locations> <LocationItem>* </Locations>] </HoursSummaryService>

Action Descriptions
Retrieve Retrieves all the Summary Items for the given date period and for the given list of locations. Return Value Type: Zero or more HoursSummary tags

388

Kronos Incorporated

HoursSummaryService Tag

Required Properties: QueryDateSpan Optional Properties: Locations Access Control Point Name: View Introduced in v6.0

Property Descriptions
Locations

Locations for hours summary
Represents a list of locations. Type: Zero or more LocationItem tags Optional Sample values: <Locations> <LocationItem Location="Organization/Hospitals/Hosp A/Floor 1/ER"/> <LocationItem Location="Organization/Hospitals/Hosp A/Floor 1/Pediatrics"/> </Locations> Introduced in v6.0 QueryDateSpan

Date range for hours summary
Represents a date span. Type: String Required Sample values: <QueryDateSpan> 11/1/2005 - 11/5/2005</QueryDateSpan> Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

389

Chapter 2

Workforce Timekeeper XML API Tag Definitions

HPPDItem Tag HPPD item
The HPPDItem tag contains information about HPPD data. Function Access Control Point: API.Schedule Introduced in v5.2; last changed in v6.0

Syntax
Properties→ <HPPDItem [DataTypeName = String] [Contribute = String] EffectiveDate = Date [ValueTypeName = String] [Amount = String] OrgPath = String > </HPPDItem>

Property Descriptions
Amount

Hours, or float number
Amount of either hours or float number. Type: String Optional For action update, it has to be a number. Introduced in v5.2; last changed in v5.2 Contribute

Direct, indirect, or total
Contribute is one of the following: Direct, Indirect or Total.

390

Kronos Incorporated

HPPDItem Tag

Type: String Optional For action update, it must be one of the follows: Direct, Indirect. Introduced in v5.2; last changed in v5.2 DataTypeName

Budgeted, Actual, Scheduled, or Variance
DataTypeName is one of the following: Budgeted, Actual, Scheduled or Variance. Type: String Optional It must be either Budgeted or Actual in action Update. Introduced in v5.2; last changed in v6.0 EffectiveDate

Effective date of HPPD assignment
The effective date of a hppd assignment. Type: Date Optional Key Introduced in v5.2; last changed in v5.2 OrgPath

Location in organizational map
The Location in the organization tree. Type: String Optional Key It must be a valid location path. Introduced in v5.2; last changed in v5.2 ValueTypeName

HPPD, Hours, or Volume

Workforce Central Developers Toolkit Reference Guide—Timekeeping

391

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ValueTypeName holds the one of the following values: HPPD, Hours, or Volume. Type: String Optional It must be "HPPD" for action update. Introduced in v5.2; last changed in v5.2

392

Kronos Incorporated

HPPDService Tag

HPPDService Tag HPPD Service
The HPPDService tag updates or retrieves HPPD values by a giving location and date. Function Access Control Point: API.Schedule Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" | "RetrieveForUpdate" | "Update" Parameters→ None Properties→ <HPPDService [QueryDateSpan = DateSpan] OrgPath = String > [<Items> <HPPDItem>* </Items>] </HPPDService>

Action Descriptions
Retrieve This action retrieves a list of hppd data for a specified location and date range. Return Value Type: Zero or more HPPDItem tags

Workforce Central Developers Toolkit Reference Guide—Timekeeping

393

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required Properties: OrgPath, QueryDateSpan Access Control Point Name: View Introduced in v5.2; last changed in v5.2 RetrieveForUpdate This action retrieves HPPD data stored in the database and ready for update. Return Value Type: Zero or more HPPDItem tags Required Properties: OrgPath, QueryDateSpan Access Control Point Name: View Introduced in v5.2; last changed in v5.2 Update This action will either insert or update a list of HPPD items onto a database table. Return Value Type: None Required Properties: Items Access Control Point Name: Edit Introduced in v5.2

Property Descriptions
Items

HPPD items
A list of HPPD items. Type: Zero or more HPPDItem tags Optional Introduced in v5.2 OrgPath

Org node path
Location in the organization tree. Type: String

394

Kronos Incorporated

HPPDService Tag

Optional Key Introduced in v5.2; last changed in v5.2 QueryDateSpan

Date span
This property represents a date span for query the hppd values. Type: DateSpan Optional Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

395

Chapter 2

Workforce Timekeeper XML API Tag Definitions

HPPDSummary Tag Hours/Volume Summary
This tag provides hours per per patient day (HPPD) summary data for various levels of your organization. Function Access Control Point: API.Schedule Introduced in v6.0; last changed in v6.0

Syntax
Properties→ <HPPDSummary Amount = String Contribute = String DataTypeName = String OrgPath = String ValueType = String > </HPPDSummary>

Property Descriptions
Amount

Amount
Specify the hours per patient day summary amount value. Type: String Required Sample values: 12.50 Introduced in v6.0 Contribute

Contribute

396

Kronos Incorporated

HPPDSummary Tag

Specify the hours per patient day summary contribution value, which can be direct, indirect or total. Type: String Required Sample values: Direct Introduced in v6.0 DataTypeName

Data Type Name
Specify the hours per patient day summary data type, which can be budgeted, target or actual. Type: String Required Sample values: Budgeted Introduced in v6.0 OrgPath

Organizational map path
Represents the organizational map path for the hours per patient day summary information. Type: String Required Sample values: Organization/Hospitals/Hosp A/Floor 1/ER Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

397

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ValueType

Value Type
Represents the hppd summary value type, which can be hours, volume or hppd. Type: String Required Sample values: Hours Introduced in v6.0

398

Kronos Incorporated

HPPDSummaryService Tag

HPPDSummaryService Tag HPPD Summary Service
This service returns all the hppd summary items for a list of locations. Each summary item hold the sum of hppd infos associated with the specified locations and date range. Function Access Control Point: API.Schedule Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" Parameters→ None Properties→ <HPPDSummaryService QueryDateSpan = DateSpan > [<Locations> <LocationItem>* </Locations>] </HPPDSummaryService>

Action Descriptions
Retrieve Returns the hppd summary data for the specified date span and list of locations. If no location is specified, the home locations will be used. Return Value Type: Zero or more HPPDSummary tags

Workforce Central Developers Toolkit Reference Guide—Timekeeping

399

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required Properties: QueryDateSpan Optional Properties: Locations Access Control Point Name: View Introduced in v6.0

Property Descriptions
Locations

Locations
Represents the locations for the hppd summary data to be retrieved. Type: Zero or more LocationItem tags Optional Sample values: Organization/Hospitals/Hosp A/Floor 1/ER Introduced in v6.0 QueryDateSpan

Query Date Span
Represents the date span for the hppd summary to retrieve. Type: DateSpan Required Sample values: 11/01/2005 - 11/05/2005 Introduced in v6.0

400

Kronos Incorporated

HyperFindQuery Tag

HyperFindQuery Tag Query
The HyperFindQuery tag specifies a HyperFind query that is used to return one or more people as well as other data. Used by: PersonIdentity Function Access Control Point: API.Hyperfind Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "GetQueryCount" | "LoadAllQueries" | "RunQuery" Parameters→ None Properties→ <HyperFindQuery [QueryPersonOrEmployee = String] (Description = String) HyperFindQueryName = String [QueryIncludeWTKEmployeeFlag = Boolean] [QueryIncludePersonFlag = Boolean] [QueryIncludeUserFlag = Boolean] [QueryDateSpan = DateSpan] VisibilityCode = String > </HyperFindQuery>

Action Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

401

Chapter 2

Workforce Timekeeper XML API Tag Definitions

GetQueryCount Returns the number of people that can be returned by the HyperFind query. Return Value Type: SimpleValue tag Required Properties: HyperFindQueryName, VisibilityCode, QueryDateSpan, QueryPersonOrEmployee Access Control Point Name: View Introduced in v4 LoadAllQueries Returns a list of all HyperFind queries. Return Value Type: Zero or more HyperFindQuery tags Required Properties: VisibilityCode Access Control Point Name: View Introduced in v4 RunQuery Returns a list of people and associated information for the specified HyperFind query. Return Value Type: Zero or more HyperFindResult tags Required Properties: HyperFindQueryName, VisibilityCode, QueryDateSpan, QueryPersonOrEmployee Access Control Point Name: View Introduced in v4

Property Descriptions
Description

Description of query
Describes the HyperFind query Type: String Output Only

402

Kronos Incorporated

HyperFindQuery Tag

Introduced in v4; last changed in v5.0 HyperFindQueryName

HyperFind query name
Specifies the name of the HyperFind query. The query name and its visibility code form a unique key to the HyperFind query. Type: String Optional Key The names of HyperFind queries can be found in the Workforce Central user interface. Introduced in v4 QueryDateSpan

Span of dates for the query
The span of dates when the query is valid. Specifies the date span used to determine access to and active status of the people returned in the result. Type: DateSpan Optional Introduced in v4; last changed in v5.1 QueryIncludePersonFlag

Include person data?
Indicates whether to include information from the Person tag in the result Type: Boolean Optional Default value: False Enumerated value: True, False Introduced in v4; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

403

Chapter 2

Workforce Timekeeper XML API Tag Definitions

QueryIncludeUserFlag

Include user account data?
Indicates whether to include information from the UserAccount tag in the result Type: Boolean Optional Default value: False Enumerated value: True, False Introduced in v4; last changed in v5.0 QueryIncludeWTKEmployeeFlag

Include employee data?
Indicates whether to include information from the WTKEmployee tag in the result Type: Boolean Optional Default value: False Enumerated value: True, False Introduced in v4; last changed in v5.0 QueryPersonOrEmployee

Category (person, employee, job assignment) for query
The type of person being requested in the query Type: String Optional Enumerated value: Person, Employee, Job Assignment Introduced in v4; last changed in v5.0 VisibilityCode

Visibility (public, private)

404

Kronos Incorporated

HyperFindQuery Tag

The visibility of the HyperFindQuery: public or private. Private queries are visible only to the query owner; public queries are available to any user whose access profile allows it. The query name and its visibility form a unique key to the HyperFind query. Use Private when referring to a personal HyperFind query. Type: String Required Key Note: For a Personal HyperFind, use the value Private. Enumerated value: Public, Private Introduced in v4; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

405

Chapter 2

Workforce Timekeeper XML API Tag Definitions

HyperFindResult Tag Result of Query
The HyperFindResult tag returns the result of running a HyperFind query. Used by: HyperFindQuery Function Access Control Point: API.Hyperfind Introduced in v4; last changed in v5.1

Syntax
Properties→ <HyperFindResult (FullName = String) (PersonNumber = String) > (<WTKEmployeeData> <WTKEmployee> </WTKEmployeeData>) (<PersonData> <Person> </PersonData>) (<UserAccountData> <UserAccount> </UserAccountData>) </HyperFindResult>

Property Descriptions
FullName

Full name
Name of the resulting person Type: String Output Only Maximum length: 64 characters Introduced in v4

406

Kronos Incorporated

HyperFindResult Tag

PersonData

Person data
Information about the resulting person Type: Person tag Output Only Dependency: Only contains a value when the QueryIncludePersonFlag property in the HyperFindQuery is True Introduced in v4 PersonNumber

Person number
Person number of the specified person Type: String Output Only Introduced in v4 UserAccountData

User account data
The User Account tag for the resulting person Type: UserAccount tag Output Only Dependency: Only contains a value when the QueryIncludeUserAccountFlag property in the HyperFindQuery is True Introduced in v4 WTKEmployeeData

Employee data
WTKEmployee tag for the resulting person Type: WTKEmployee tag

Workforce Central Developers Toolkit Reference Guide—Timekeeping

407

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Output Only Contains a value when the QueryIncludeWTKEmployeeFlag property in the HyperFindQuery is True Introduced in v4

408

Kronos Incorporated

ImportBatchStatus Tag

ImportBatchStatus Tag Status of Import Batch
The Import Batch Status tag represents an import batch's details. This tag is used to add, modify, or retrieve import batch name and batch statistics information. Function Access Control Point: API.ImportBatchStatus Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "LoadAllBatchNames" | "Update" Parameters→ None Properties→ <ImportBatchStatus (BatchDescription = String) [BatchName = String] BatchStatId = Long [ErrorText = String] (BatchType = String) [SuccessRecordCount = Integer] [FailedRecordCount = Integer] [BatchProcessStatus = String] [TotalRecordCount = Integer] [TransactionType = String] > </ImportBatchStatus>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

409

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Descriptions
AddOnly Adds a new batch status record, including the batch status identification. If a record already exists in ImportBatch with the same name but of type Table, the AddOnly action fails. Return Value Type: ImportBatchStatus tag Required Properties: BatchName Access Control Point Name: Edit Introduced in v5.0 LoadAllBatchNames Returns all batch name information in the database. The response status is Failure if the request finds no records. Return Value Type: Zero or more ImportBatchStatus tags Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0 Update Adds a new batch status record or updates an existing one. The BatchProcessStatus must exist in the ImportProcStat table and the TransactionType must exist in the ImportCntntType table. Otherwise, the tag returns a status of Failure. Return Value Type: None Required Properties: BatchStatId, TransactionType, BatchProcessStatus Optional Properties: ErrorText, TotalRecordCount, SuccessRecordCount, FailedRecordCount Access Control Point Name: Edit Introduced in v5.0

Property Descriptions

410

Kronos Incorporated

ImportBatchStatus Tag

BatchDescription

Batch description
The BatchDescription contains the same value as BatchName. Type: String Output only Maximum length: 30 characters Introduced in v5.0 BatchName

Batch name
A user defined Import Batch name. Type: String Optional Maximum length: 30 characters Batch Name must uniquely identify an Import Batch. Existing batch names can be found in the user interface. Required: For an AddOnly action Introduced in v5.0 BatchProcessStatus

Status of batch process
The status of the batch import process Type: String Optional Maximum length: 30 characters Must be one of the identified values Enumerated value: IN PROCESS, COMPLETE, INTERRUPTED BY USER, TERMINATED

Workforce Central Developers Toolkit Reference Guide—Timekeeping

411

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.0 BatchStatId

Batch status ID
The unique numeric value of an instance of a batch which has been run, or is in the process of running. Type: Long Optional Key You can find values in the Workforce Timekeeper user interface. Introduced in v5.0 BatchType

Import type (table or XML)
The type of batch import Type: String Output only Enumerated value: Table Import, XML Import Introduced in v5.0 ErrorText

Description of error
The error text for the batch Type: String Optional Maximum length: 250 characters Sample values: Normal Completion Introduced in v5.0

412

Kronos Incorporated

ImportBatchStatus Tag

FailedRecordCount

Number of records processed unsuccessfully
The total number of records that were not successfully processed in the batch. The client can provide the total record count at the beginning of the batch; then provide this information and the success count at the conclusion. Otherwise, the system can update these values for each record. Type: Integer Optional Introduced in v5.0 SuccessRecordCount

Number of records processed successfully
Indicates the total number of records that were successfully processed in the batch. The user can provide the total record count at the beginning of the batch as well as the success and failure counts, or the system can update for each record. Type: Integer Optional Introduced in v5.0 TotalRecordCount

Total number of records in batch
The total number of records that were expected to be added in the batch. The user can provide this information at the beginning of the batch and provide the success/ failure count at the conclusion or it can update for each record. Type: Integer Optional Introduced in v5.0 TransactionType

Transaction type

Workforce Central Developers Toolkit Reference Guide—Timekeeping

413

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The type of transaction Type: String Optional If more than one transaction type is being imported in the batch, transaction type is set to XML. Sample values: Accrual Dates, Accruals, Activities, Activities People, Availability Templates, Certifications, Customers, Labor Level Entries, Labor Level Sets, Organizational Maps, Pay Code Edits, People, Punches, Result", Schedule Assistant Criteria, Schedule Rules, Schedules, Skills, Staffing, Workforce Activities, Workforce Scheduler, XML Introduced in v5.0; last changed in v5.0

414

Kronos Incorporated

JobAssignment Tag

JobAssignment Tag Job Assignment
The JobAssignment tag specifies information about a person's job assignment. It is used to import data. Used by: Personality Function Access Control Point: API.Person Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" Parameters→ None Properties→ <JobAssignment (HasPersonalOvertimeFlag = Boolean) [ScheduleGroupName = String] > <Identity> <CurrentUser> | <PersonIdentity> </Identity> [<JobAssignmentDetailsData> <JobAssignmentDetails> </JobAssignmentDetailsData>] [<PersonalOvertimeAssignments> <PersonalOvertimeAssignment>* </PersonalOvertimeAssignments>] [<PrimaryLaborAccounts> <PrimaryLaborAccount>* </PrimaryLaborAccounts>]

Workforce Central Developers Toolkit Reference Guide—Timekeeping

415

Chapter 2

Workforce Timekeeper XML API Tag Definitions

[<Period> <TimeFramePeriod> </Period>] </JobAssignment>

Action Descriptions
Load Returns all information associated with the job and overtime assignments for the specified person and period. Return Value Type: JobAssignment tag Required Properties: Identity Optional Properties: Period Access Control Point Name: View Introduced in v5.0

Property Descriptions
HasPersonalOvertimeFlag

Is there personal overtime?
Indicates whether personal overtime assignments are associated with that person Type: Boolean Output only Enumerated value: True, False Introduced in v5.0; last changed in v5.0 Identity

Identity
One employee, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Optional Key

416

Kronos Incorporated

JobAssignment Tag

Must uniquely identify a person. Introduced in v5.0 JobAssignmentDetailsData

Job assignment details
General job, employee, and scheduling information that is associated with this job assignment Type: JobAssignmentDetails tag Optional Introduced in v5.0; last changed in v5.0 Period

Time period
The specified time frame Type: TimeFramePeriod tag Optional Must evaluate to a span of time. Identity is used when the time frame requires association with a person. Used for the Load action. Default value: From the current date until January 1, 3000 Introduced in v5.0 PersonalOvertimeAssignments

Personal overtime assignments
One or more rules that override the person's assigned overtime rule; that is, specify one or more Overriding Personal Rules. Type: Zero or more PersonalOvertimeAssignment tags Optional Each tag in the list must be a Personal Overtime Assignment tag Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

417

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PrimaryLaborAccounts

Primary labor accounts
One or more Primary Labor Accounts Type: Zero or more PrimaryLaborAccount tags Optional Maximum length: 356 characters This property consists of one or more labor levels, separated by slash (/). Each labor level has a maximum length of 50 characters. At least one primary labor account must be specified for a new person. Introduced in v5.0; last changed in v5.0 ScheduleGroupName

Schedule group assignment
The name of the schedule group to which the person is currently assigned Type: String Optional Maximum length: 30 characters You can find values in the Workforce Timekeeper user interface. Introduced in v5.0

418

Kronos Incorporated

JobAssignmentDetails Tag

JobAssignmentDetails Tag Job Assignment Details
The JobAssignmentDetails tag specifies certain job, employee, and schedule information for a person. Used by: JobAssignment Function Access Control Point: API.Person Introduced in v5.0; last changed in v5.2

Syntax
Properties→ <JobAssignmentDetails [BaseWageHourly = Currency] [BaseWageEffectiveDate = Date] [DeviceGroupName = String] [PayRuleName = String] [SupervisorName = String] [SeniorityRankDate = Date] [SupervisorPersonNumber = String] [TimeZoneName = String] [WageProfileName = String] [WorkerTypeName = String] > </JobAssignmentDetails>

Property Descriptions
BaseWageEffectiveDate

Base wage effective date
This property indicates when the specified base wage rate should take effect. Type: Date Optional The string entered must represent a date. Sample values:

Workforce Central Developers Toolkit Reference Guide—Timekeeping

419

Chapter 2

Workforce Timekeeper XML API Tag Definitions

12/02/2005 Default value: today Introduced in v5.2 BaseWageHourly

Base hourly wage
The base wage is the employee°Øs hourly wage without any premium values (overtime, shift differential, and so on). Type: Currency Optional Maximum length: 15 characters If specified, this value must be greater than or equal to 0.0. Introduced in v5.0; last changed in v5.2 DeviceGroupName

Device group
The Device Group represents all of the data collection devices that the employee can access. Type: String Optional Maximum length: 50 characters You can find values in the Workforce Timekeeper Setup Application. Introduced in v5.0; last changed in v5.1 PayRuleName

Pay rule
The name of the pay rule that is assigned to the employee. A pay rule contains general payroll rules such as type of pay period (for example, weekly). A complete pay rule controls such items as the pay period length, the day divide, when punches link to schedules, when data collection devices accept and reject

420

Kronos Incorporated

JobAssignmentDetails Tag

punches, which holidays give holiday credits, and the order that hour types are processed. Type: String Optional Maximum length: 50 characters Required: For a new Workforce Timekeeper Employee or Timekeeper Employee that tracks their time in Workforce Central. You can find values in the Workforce Timekeeper Setup Application. Introduced in v5.0; last changed in v5.1 SeniorityRankDate

Seniority date
The date when the individual became qualified to work the job or was assigned to the job. Type: Date Optional Introduced in v5.0; last changed in v5.1 SupervisorName

Reports to
The name of a person's manager Type: String Optional Maximum length: 64 characters Specify the managers name as last name, first name, middle initial. It must match the name of an existing manager Sample values: Example: Smith, John B

Workforce Central Developers Toolkit Reference Guide—Timekeeping

421

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.0; last changed in v5.0 SupervisorPersonNumber

Supervisor person number
This property can be used to uniquely identify a manager or combine with SupervisorName. Type: String Optional Must uniquely identify an existing and active manager Sample values: A person ID, Sample SupervisorPersonNumber="213" Introduced in v5.2; last changed in v5.2 TimeZoneName

Time zone
Either the ID, a five-digit value that describes how the local time for a region relates to Greenwich mean time (GMT), or the exact name of the time zone in which the person works. Type: String Optional Maximum length: 30 characters Required: When a value is also specified for DeviceGroupName For a list of values, see "Time Zone Definitions" in Appendix B in the Workforce Timekeeper DTK Reference Guide. Default value: Default time zone Introduced in v5.0 WageProfileName

Wage profile

422

Kronos Incorporated

JobAssignmentDetails Tag

The name of the person's wage profile. The Wage Profile allows an employee to have multiple wage rates. Type: String Optional Maximum length: 50 characters Introduced in v5.0; last changed in v5.1 WorkerTypeName

Worker type
The worker type identifies the category of worker (for example, full-time, parttime, or other types that your site might define). Type: String Optional Maximum length: 50 characters Introduced in v5.0; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

423

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Kronos_WFC Tag Session Container
The Kronos_WFC tag is a container for all XML session information sent to and from a client application. This tag is required to identify the context and version for the application server. It can contain any combination of XML API tags defined in the XML API. All tags specified in the request Kronos_WFC tags are echoed in the response. The Kronos_WFC tag must appear prior to the first request in an XML session with the version tag identifying the XML version. The response will also contain this tag which shall include the version, WFCVersion, and TimeStamp tags. Function Access Control Point: API.XML Introduced in v4; last changed in v5.0

Syntax
Properties→ <Kronos_WFC [TimeStamp = String] Version = String (WFCVersion = String) > </Kronos_WFC>

Property Descriptions
TimeStamp

Time stamp
The timestamp can refer to the request or the response. This value is ignored by the API XML, but can be used for documenting request times. For a response, it is set to the execution time. Type: String Optional Introduced in v4

424

Kronos Incorporated

Kronos_WFC Tag

Version

Version of XML API
The XML API version Type: String Required The value is validated against the versions supported by the XML server. Introduced in v4 WFCVersion

Version of core timekeeping product
The core timekeeping version on the server that the session was run on Type: String Output Only Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

425

Chapter 2

Workforce Timekeeper XML API Tag Definitions

KTimeZone Tag Time Zone
The KTimeZone tag provides information about the time zones in the timekeeping system. Function Access Control Point: API.Employee Introduced in v4

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllKTimeZones" | "LoadById" Parameters→ None Properties→ <KTimeZone [KTimeZoneId = Integer] [KTimeZoneName = String] > </KTimeZone>

Action Descriptions
Load Returns time zone information, based on KTimeZoneName. Name should be valid Return Value Type: KTimeZone tag Required Properties: KTimeZoneName

426

Kronos Incorporated

KTimeZone Tag

Access Control Point Name: View Introduced in v4 LoadAllKTimeZones Returns a list of all time zones in the system. Return Value Type: Zero or more KTimeZone tags Required Properties: None Access Control Point Name: View Introduced in v4 LoadById Returns time zone information, based on KTimeZoneId. ID should be valid Return Value Type: KTimeZone tag Required Properties: KTimeZoneId Access Control Point Name: View Introduced in v4

Property Descriptions
KTimeZoneId

Time zone ID
Uniquely identifies the time zone in the database Type: Integer Optional Sample values: 13011 Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

427

Chapter 2

Workforce Timekeeper XML API Tag Definitions

KTimeZoneName

Time zone name
Identifies the time zone by name, for example, Eastern Type: String Optional Sample values: (GMT -05:00) Eastern Time Introduced in v4

428

Kronos Incorporated

LaborAccount Tag

LaborAccount Tag Labor Account
The LaborAccount tag identifies the labor level entries in a labor level account. Used by: PunchStatus Function Access Control Point: API.LaborLevel Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "Update" | "UpdateAndLoad" Parameters→ None Properties→ <LaborAccount [Description = String] LaborAccountName = String > [<LaborLevelEntries> <LaborLevelEntry>* </LaborLevelEntries>] </LaborAccount>

Action Descriptions
Load Returns labor account information for the specified labor account

Workforce Central Developers Toolkit Reference Guide—Timekeeping

429

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Return Value Type: LaborAccount tag Optional Properties: LaborAccountName, LaborAccountId Access Control Point Name: View Introduced in v4; last changed in v6.0 Update Adds a new labor account or updates an existing one Return Value Type: None Required Properties: LaborAccountName Access Control Point Name: Edit Introduced in v4 UpdateAndLoad Adds a new labor account, or updates an existing one. Returns labor account information for the specified labor account. Return Value Type: LaborAccount tag Required Properties: None Optional Properties: LaborAccountName, LaborAccountId Access Control Point Name: Edit Introduced in v4

Property Descriptions
Description

Description of labor account
Describes the labor account Type: String Optional Must contain only legal description characters Introduced in v4; last changed in v6.0

430

Kronos Incorporated

LaborAccount Tag

LaborAccountName

Labor account
The name of the labor account. Enter data for labor accounts in the same format as they appear in the timekeeping database. If you have a seven-level labor account, specify a value for each labor level, using the following format: 101/202/303/404/504/603/702 Do not specify labor levels that are not changing. Type: String Required Key Maximum length: 356 characters Each component in the name must correspond to the name and sort order position of an existing labor level entry. The name must contain only legal naming characters. Introduced in v4 LaborLevelEntries

Set of labor level entries
One labor level entry is specified for each labor level in the specified labor account. Type: Zero or more LaborLevelEntry tags Optional Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

431

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LaborAccountEntry Tag Labor Account Entry
The LaborAccountEntry tag identifies one or more labor level entries that need to be added, removed, or replaced in the labor account set. The order of precedence is: • • • Replace Add Remove

Function Access Control Point: API.DataAccess Introduced in v4; last changed in v5.0

Syntax
Properties→ <LaborAccountEntry [AddEntries = String] [RemoveEntries = String] [ReplaceEntries = String] LaborLevelDefinitionName = String > </LaborAccountEntry>

Property Descriptions
AddEntries

Labor level entries added to the labor account set
A semicolon-delimited list of labor level entries that need to be added to the labor account set for this labor level. Entries can contain wildcards. Type: String Optional Maximum length: 146 characters

432

Kronos Incorporated

LaborAccountEntry Tag

Each semicolon-delimited entry is validated against the labor level definitions length requirements, and checked for invalid characters. Except for wildcards, all labor level entries must exist. Introduced in v4; last changed in v5.0 LaborLevelDefinitionName

Labor level to which the entry belongs
The name of the labor level to which this labor level entry belongs Type: String Required Key Maximum length: 50 characters Introduced in v4 RemoveEntries

Labor level entries removed from the labor account set
The semicolon-delimited list of labor level entries to be removed from the labor account set for this labor level. Entries can contain wildcards. Type: String Optional Maximum length: 146 characters Each semicolon-delimited entry is validated against the labor level definitions length requirements, and checked for invalid characters. Except for wildcards, all labor level entry must exist. Introduced in v4; last changed in v5.0 ReplaceEntries

Labor level entries that replace the labor account set
A semicolon-delimited list of labor level entries that should replace existing entries in the labor account set for this labor level. Entries can contain wildcards. Type: String

Workforce Central Developers Toolkit Reference Guide—Timekeeping

433

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Maximum length: 146 characters Each semicolon-delimited entry is validated against the labor level definitions length requirements, and checked for invalid characters. Except for wildcards, all labor level entry must exist. Introduced in v4; last changed in v5.0

434

Kronos Incorporated

LaborAccountEntryData Tag

LaborAccountEntryData Tag Entry Data for a Labor Account
The LaborAccountEntryData tag describes the labor account entry data in a labor account set. Function Access Control Point: API.DataAccess Introduced in v5.0; last changed in v5.0

Syntax
Properties→ <LaborAccountEntryData (Descriptions = String) (Adhoc = Boolean) (LaborLevelDefinitionName = String) (Entries = String) > </LaborAccountEntryData>

Property Descriptions
Adhoc

Is ad hoc allowed?
True or False, based on whether ad hoc is allowed Type: Boolean Output only Enumerated value: True, False Introduced in v5.0 Descriptions

Description of labor account set
Describes the labor account set Type: String

Workforce Central Developers Toolkit Reference Guide—Timekeeping

435

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Output only Introduced in v5.0 Entries

Labor level entries
The labor level entries Type: String Output only Introduced in v5.0 LaborLevelDefinitionName

Labor level definition
The name of the labor level definition Type: String Output only Introduced in v5.0; last changed in v5.0

436

Kronos Incorporated

LaborAccountSet Tag

LaborAccountSet Tag Labor Account Set
The LaborAccountSet tag describes the set of labor levels that comprise a labor account. This set is used by the access package to determine if a user can access a person or the specified Labor Level. Function Access Control Point: API.DataAccess Introduced in v4; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "Load" | "LoadLaborAccountData" | "LoadLaborAccountUpdatedData" | "Update" | "UpdateOnly" Parameters→ None Properties→ <LaborAccountSet LaborAccountSetKey = String LaborAccountSetName = String [NewName = String] [Description = String] [LaborAccountSetTypeName = String] [UpdatedDate = String] > [<EntryList> <LaborAccountEntry>*

Workforce Central Developers Toolkit Reference Guide—Timekeeping

437

Chapter 2

Workforce Timekeeper XML API Tag Definitions

</EntryList>] </LaborAccountSet>

Action Descriptions
AddOnly Adds a new labor account set Return Value Type: None Required Properties: LaborAccountSetName, LaborAccountSetTypeName Access Control Point Name: Edit Introduced in v4 Load Returns information for the specified labor account set name Return Value Type: LaborAccountSet tag Required Properties: LaborAccountSetName Access Control Point Name: View Introduced in v4 LoadLaborAccountData Returns all labor account set data for the specified labor account set key. Return Value Type: Zero or more LaborAccountSet tags Required Properties: LaborAccountSetKey Access Control Point Name: View Introduced in v5.0; last changed in v5.0 LoadLaborAccountUpdatedData Returns a list of labor entries for the specified labor account set key that have been updated or modified since the given reference date. Return Value Type: LaborAccountSet tag Required Properties: LaborAccountSetKey, UpdatedDate Access Control Point Name: View

438

Kronos Incorporated

LaborAccountSet Tag

Introduced in v5.1; last changed in v5.2 Update Adds a new labor account set or updates an existing one Return Value Type: None Required Properties: LaborAccountSetName. If adding a new labor account set, LaborAccountSetTypeName is required. Access Control Point Name: Edit Introduced in v4 UpdateOnly Updates an existing labor account set Return Value Type: None Required Properties: LaborAccountSetName Access Control Point Name: Edit Introduced in v4

Property Descriptions
Description

Summary of the labor level set
A brief summary of the labor level set Type: String Optional Maximum length: 250 characters Introduced in v4 EntryList

List of entries in the labor account set
Specifies the list of labor level account entries in the labor account set Type: Zero or more LaborAccountEntry tags

Workforce Central Developers Toolkit Reference Guide—Timekeeping

439

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Each labor level account entry in the list is validated individually. Introduced in v4 LaborAccountSetKey

Key for the labor account set
The database key for the labor account set Type: String Optional Key Maximum length: 10 characters Introduced in v5.0; last changed in v5.0 LaborAccountSetName

Labor account set name
The name of the labor level set Type: String Required Key Maximum length: 30 characters Introduced in v4 LaborAccountSetTypeName

Type of labor account set
Identifies the type of the labor level set. LaborAccountSetTypeName can have the following values: 1-Indicates the entry of a labor level set that can be used in any user role. 2-Indicates the entry of a labor level set that is used exclusively for employee group labor level sets. 3-Indicates entry of a labor level set that is used exclusively for labor level transfer sets.

440

Kronos Incorporated

LaborAccountSet Tag

For values 1 and 2, there must be at least one entry in each level in the labor level set. For example, if the labor level set consists of seven labor levels, then there must be at least one entry in each level. For value 3, there must be at least one entry in the labor level set, which can be in any labor level. For example, if the labor level set consists of seven labor levels, then at least one of those seven must include at least one entry. Type: String Optional Maximum length: 1 character Enumerated value: 1, 2, 3 Introduced in v4 NewName

New name of labor account set
The name to replace the existing name of a labor level set. Type: String Optional Maximum length: 30 characters Use the value @ to indicate that the existing name of the labor level set should be retained. Required: For an update of a labor level set. Introduced in v4; last changed in v5.0 UpdatedDate

Updated Date
The date when the entries of the specified labor account set are updated Type: String Optional Introduced in v5.1; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

441

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LaborAccountSetProfile Tag Set Profile for a Labor Account
The LaborAccountSetProfile tag provides information about valid labor account set profiles. A labor account set profile specifies the labor level sets a manager or employee can use when defining a labor account for transfer. To prevent access to labor level transfer sets, select the empty profile. Function Access Control Point: API.Employee Introduced in v4

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllLaborAccountSetProfiles" | "LoadById" Parameters→ None Properties→ <LaborAccountSetProfile [LaborAccountSetProfileId = Integer] [LaborAccountSetProfileName = String] > </LaborAccountSetProfile>

Action Descriptions
Load Returns a labor account set profile, based on LaborAccountSetProfileName. Name should be valid

442

Kronos Incorporated

LaborAccountSetProfile Tag

Return Value Type: LaborAccountSetProfile tag Required Properties: LaborAccountSetProfileName Access Control Point Name: View Introduced in v4 LoadAllLaborAccountSetProfiles Returns all labor account set profiles in the system. Return Value Type: Zero or more LaborAccountSetProfile tags Required Properties: None Access Control Point Name: View Introduced in v4 LoadById Returns a labor account set profile, based on LaborAccountSetProfileID. ID must be valid Return Value Type: LaborAccountSetProfile tag Required Properties: LaborAccountSetProfileID Access Control Point Name: View Introduced in v4

Property Descriptions
LaborAccountSetProfileId

Id of set profile for labor account
Uniquely identifies the labor account set profile in the database Type: Integer Optional Introduced in v4 LaborAccountSetProfileName

Set profile for labor account

Workforce Central Developers Toolkit Reference Guide—Timekeeping

443

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The name for the common set of labor accounts that a group of users can access; for example, F Snow Employees. Type: String Optional Maximum length: 30 characters Sample values: All Labor Account Introduced in v4

444

Kronos Incorporated

LaborLevelDefinition Tag

LaborLevelDefinition Tag Labor Level Definition
The LaborLevelDefinition tag describes the hierarchical labor levels that define a job structure. The LaborLevelDefinition and WSALaborLevel tags refer to the same database object. Function Access Control Point: API.LaborLevel Introduced in v4

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "GetNumberOfLaborLevels" | "LoadAllDefinitions" Parameters→ None Properties→ <LaborLevelDefinition (AddAtTerminalFlag = Boolean) (LaborLevelDefinitionName = String) (MaxNameLength = Integer) (MinNameLength = Integer) (OverrideFlag = Boolean) (SortOrder = Integer) (ShortName = String) > </LaborLevelDefinition>

Action Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

445

Chapter 2

Workforce Timekeeper XML API Tag Definitions

GetNumberOfLaborLevels Returns a count of labor level definitions Return Value Type: SimpleValue tag Access Control Point Name: View Introduced in v4 LoadAllDefinitions Returns all labor level definition names Return Value Type: Zero or more LaborLevelDefinition tags Access Control Point Name: View Introduced in v4

Property Descriptions
AddAtTerminalFlag

Add labor level at a data collection device?
Specifies whether this labor level can be added at a Data Collection Manager (DCM) device Type: Boolean Output Only Enumerated value: True, False Introduced in v4 LaborLevelDefinitionName

Labor level definition
The name of the labor level definition Type: String Output Only You can find values in the Workforce Timekeeper Setup Application Introduced in v4

446

Kronos Incorporated

LaborLevelDefinition Tag

MaxNameLength

Maximum length of name
Maximum length of a labor level entry name Type: Integer Output Only Introduced in v4 MinNameLength

Minimum length of name
Minimum length of a labor level entry name Type: Integer Output Only Introduced in v4 OverrideFlag

Override rules for name length?
Indicates whether the user is allowed to define a labor level entry name that does not conform to the minimum or maximum length rules Type: Boolean Output Only Enumerated value: True, False Introduced in v4 ShortName

Short name for labor level definition
Short name of the labor level definition Type: String Output Only Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

447

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SortOrder

Position of this labor level in labor account
A number representing the position of this definition in the labor account Type: Integer Output Only Must be between 1 and the number of labor levels in the system Introduced in v4

448

Kronos Incorporated

LaborLevelEntry Tag

LaborLevelEntry Tag Labor Level Entry
The LaborLevelEntry tag describes one labor level. Labor level entries usually contain an entry name and description. This tag is used by LaborAccount. The LaborLevelEntry and WSALaborLevelEntry tags refer to the same database object. The NewName property can only be specified to update an existing LaborLevelEntry, using the Update or UpdateOnly action. The LaborLevelEntryName can be the name or the description when locating an existing labor level entry using the Load, Update, or UpdateOnly action. Function Access Control Point: API.LaborLevel Introduced in v4; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "GetCountByLaborLevelWithFilter" | "GetCountsByLaborLevel" | "Load" | "LoadByWildcard" | "Update" | "UpdateOnly" Parameters→ GetCountByLaborLevelWithFilter→ LaborLevelDefinitionName = String Wildcard = String LoadByWildcard→ LaborLevelDefinitionName = String WildCard = String

Workforce Central Developers Toolkit Reference Guide—Timekeeping

449

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Properties→ <LaborLevelEntry [Description = String] [InactiveFlag = Boolean] LaborLevelDefinitionName = String LaborLevelEntryName = String NewName = String > </LaborLevelEntry>

Action Descriptions
AddOnly Adds a new labor level entry Return Value Type: None Required Properties: LaborLevelEntryName, LaborLevelDefinitionName Access Control Point Name: Edit Introduced in v4 GetCountByLaborLevelWithFilter Returns the number of visible labor level entries for the specified level Return Value Type: SimpleValue tag Access Control Point Name: View Introduced in v4
Action Parameters Parameter Name Description Additional information Introduced in v5.1 Introduced in v4.0 Required

LaborLevelDefinitionNa The name of labor level definition me Required Wildcard

GetCountsByLaborLevel Returns the number of labor level entries for each labor level in the system

450

Kronos Incorporated

LaborLevelEntry Tag

Return Value Type: Zero or more SimpleValue tags Access Control Point Name: View Introduced in v4 Load Returns the specified labor level entry Return Value Type: LaborLevelEntry tag Required Properties: LaborLevelEntryName, LaborLevelDefinitionName Access Control Point Name: View Introduced in v4 LoadByWildcard Returns the labor level entries that match the wildcard name or description pattern for the specified labor level definition Return Value Type: Zero or more LaborLevelEntry tags Required Properties: None Access Control Point Name: View Introduced in v4
Action Parameters Parameter Name Description Additional information Introduced in v4 Introduced in v4

LaborLevelDefinitionNa The name of the labor level definition me Required WildCard The pattern with which to search the description field Required

Update Adds a new labor level entry or updates an existing one Return Value Type: None Required Properties: LaborLevelEntryName, LaborLevelDefinitionName

Workforce Central Developers Toolkit Reference Guide—Timekeeping

451

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: Edit Introduced in v4 UpdateOnly Updates an existing labor level entry Return Value Type: None Required Properties: LaborLevelEntryName, LaborLevelDefinitionName Access Control Point Name: Edit Introduced in v4

Property Descriptions
Description

Description
Contains text that describes the labor level entry specified in LaborLevelEntryName. It is ignored when you inactivate or reactivate a labor level entry. Type: String Optional Maximum length: 250 characters Introduced in v4 InactiveFlag

Is the Labor Level Entry inactive?
Indicates whether the labor level entry is active. If True, the labor level entry is no longer valid for this labor level. Type: Boolean Optional Enumerated value: True, False Introduced in v4

452

Kronos Incorporated

LaborLevelEntry Tag

LaborLevelDefinitionName

Name of the Labor Level
Identifies the labor level for which a labor level entry can be specified. For example, if the LaborLevelDefinitionName is Job, a LaborLevelEntryName might be 401 and have a corresponding Description value of Assembly. The value of this input property can be either the name or the ID of the labor level. If a labor level definition with a matching name is not found, a labor level definition with a matching ID is looked for. Type: String Optional Key Maximum length: 50 characters Introduced in v4; last changed in v5.2 LaborLevelEntryName

Name of the Labor Level Entry
The LaborLevelEntryName identifies the name of the labor level entry. LaborLevelEntryName works in conjunction with LaborLevelDefinitionName, which identifies the labor level that the labor level entry is a member of. The text that describes the LaborLevelEntryName is entered in the Description column. Although defined as a string, LaborLevelEntryName typically contains a number, not text. Example: The Precision Auto factory uses the labor account format with the following labor levels: /Company/Division/Department/Job The employees perform a variety of work, so the Job labor level has multiple entries that represent the jobs that are performed. In this example, each job has a different LaborLevelEntryName, as follows: • LaborLevelEntryName 401 has a corresponding Description value of Assembly

Workforce Central Developers Toolkit Reference Guide—Timekeeping

453

Chapter 2

Workforce Timekeeper XML API Tag Definitions

• • •

LaborLevelEntryName 402 has a corresponding Description value of Welding LaborLevelEntryName 403 has a corresponding Description value of Painting LaborLevelEntryName 404 has a corresponding Description value of Inspection

Type: String Optional Key Maximum length: 50 characters Introduced in v4; last changed in v5.0 NewName

New Name for an Existing Labor Level Entry
Identifies the new name of an existing labor level entry. NewName is required only when you update a labor level entry. If the labor level entry name is not changing, you can enter @H to indicate that the labor level entry name should retain its original value. Type: String Optional Key Maximum length: 50 characters Introduced in v4

454

Kronos Incorporated

LaunchHistory Tag

LaunchHistory Tag PSE Launch History
History of the Priority Scheduling Engine (PSE) launch. Function Access Control Point: Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveAll" | "RetrieveByDate" | "RetrieveByDatePerson" | "RetrieveByPerson" | "RetrieveByProcedureSet" | "RetrieveByProcedureSetUserAccountName" | "RetrieveByUser" Parameters→ RetrieveByDate→ Date = Date RetrieveByDatePerson→ Date = Date Person = String RetrieveByPerson→ Person = String RetrieveByProcedureSet→ ProcedureSet = String RetrieveByProcedureSetUserAccountName→ ProcedureSet = String UserName = String RetrieveByUser→ UserName = String

Workforce Central Developers Toolkit Reference Guide—Timekeeping

455

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Descriptions
RetrieveAll Retrieve all existing LaunchHistory. No properties are required. Return Value Type: Zero or more LaunchHistory tags Access Control Point Name: View Introduced in v6.0 RetrieveByDate Retrieve all the launch history for a specific date. Will throw an exception if the date string is invalid Return Value Type: Zero or more LaunchHistory tags Access Control Point Name: View Introduced in v6.0
Action Parameters Parameter Name Date Description String for the date. Required Additional information Introduced in v6.0; last changed in v6.0

RetrieveByDatePerson Retrieve all the launch history for a specific employee on a date. Return Value Type: Zero or more LaunchHistory tags Access Control Point Name: View Introduced in v6.0

456

Kronos Incorporated

LaunchHistory Tag

Action Parameters Parameter Name Date Person Description String for the date. Required The name of the person employee. Required Additional information Introduced in v6.0; last changed in v6.0 Introduced in v6.0; last changed in v6.0

RetrieveByPerson Retrieve all the launch history for a specific employee. Return Value Type: Zero or more LaunchHistory tags Access Control Point Name: View Introduced in v6.0
Action Parameters Parameter Name Person Description The name of the employee. Required Additional information Introduced in v6.0; last changed in v6.0

RetrieveByProcedureSet Retrieve an existing LaunchHistory, based on the procedure set name. The procedure set name property must be provided or a validation exception will be thrown. Return Value Type: Zero or more LaunchHistory tags Access Control Point Name: View Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

457

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Parameters Parameter Name ProcedureSet Description The name of the procedure. Required Additional information Introduced in v6.0; last changed in v6.0

RetrieveByProcedureSetUserAccountName Retrieve an existing LaunchHistory, based on the procedure set name and the user name. The procedure set name and username property must be provided or a validation exception will be thrown. Return Value Type: Zero or more LaunchHistory tags Access Control Point Name: View Introduced in v6.0
Action Parameters Parameter Name ProcedureSet UserName Description The name of the procedure set. Required The name of the user. Required Additional information Introduced in v6.0; last changed in v6.0 Introduced in v6.0; last changed in v6.0

RetrieveByUser Retrieve all the launch history for a specific user. Return Value Type: Zero or more LaunchHistory tags Access Control Point Name: View Introduced in v6.0

458

Kronos Incorporated

LaunchHistory Tag

Action Parameters Parameter Name UserName Description The user name of the LaunchHistory to retrieve. Required Additional information Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

459

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LicenseType Tag License Type
The LicenseType tag identifies the available licenses within the system. This tag contains category and count information for the specified license. The license must already be defined. The license need not be assignable or active to obtain its information. Function Access Control Point: API.Person Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAssignable" Parameters→ None Properties→ <LicenseType (CategoryName = String) LicenseTypeName = String (LimitCount = Integer) (InUseCount = Integer) (AvailableCount = Integer) > </LicenseType>

Action Descriptions

460

Kronos Incorporated

LicenseType Tag

Load Returns the category and count information associated with the specified license type. The license type name must be specified and identify an existing license within the system. Return Value Type: LicenseType tag Required Properties: LicenseTypeName Access Control Point Name: View Introduced in v5.0 LoadAssignable Returns all assignable licenses that are active and have a limit count greater than zero. Return Value Type: Zero or more LicenseType tags Required Properties: None Access Control Point Name: View Introduced in v5.0

Property Descriptions
AvailableCount

Number of unassigned licenses
The number of licenses still available to assign Type: Integer Output only Introduced in v5.0 CategoryName

License type
The name of the license category Type: String

Workforce Central Developers Toolkit Reference Guide—Timekeeping

461

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Output only Enumerated value: Product, Interactive Introduced in v5.0 InUseCount

Number of assigned licenses
The number of licenses currently in use Type: Integer Output only Introduced in v5.0 LicenseTypeName

License type name
The name or the Id of the license type. There are a number of valid licenses, but not all are assignable to employees The following license types can be assigned to employees: • • • • • • • 1 or Workforce_Timekeeper_Employee 2 or Workforce_Professional_ Employee 3 or Workforce_Manager 5 or Workforce_Activities 9 or Workforce_Scheduler 10 or Workforce_Attendance_Employee 12 or Workforce_Leave_Employee

Type: String Optional Key Maximum length: 2 characters Specify @ to make no change to the existing license type. Enumerated value: @, 1, 2, 3, 5, 9, 10, 12

462

Kronos Incorporated

LicenseType Tag

Introduced in v5.0; last changed in v5.0 LimitCount

Maximum number of licenses allowed
The total number of licenses allowed Type: Integer Output only Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

463

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LightWeightPerson Tag Available delegate
The LightWeight Person tag displays a person's name and number. Function Access Control Point: API.DelegateProfile Introduced in v5.2; last changed in v5.2

Syntax
Properties→ <LightWeightPerson (Name = String) PersonNumber = String > </LightWeightPerson>

Property Descriptions
Name

Person Name
This is output only. Type: String Output only This is output only. Introduced in v5.2 PersonNumber

Person Number
The PersonNumber of existing person. Type: String Required The PersonNumber of existing person.

464

Kronos Incorporated

LightWeightPerson Tag

Introduced in v5.2; last changed in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

465

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LocationId Tag Location Id of Node
The LocationId tag identifies the location of a node in the Organizational Map. Used by: ScheduleZoneSet, StandardShiftSet Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.0

Syntax
Properties→ <LocationId NodeId = String > </LocationId>

Property Descriptions
NodeId

Node ID
An existing node in the Organizational Map Type: String Required You can find values in the Workforce Timekeeper user interface. Introduced in v5.0

466

Kronos Incorporated

LocationProfileSettings Tag

LocationProfileSettings Tag Location Profiles
Used to assign procedure sets to locations. Function Access Control Point: Location Settings Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Add" | "AddOnly" | "Delete" | "DeleteOnly" | "Retrieve" | "RetrieveAll" | "RetrieveAllForUpdate" | "RetrieveAllNames" | "RetrieveForUpdate" | "Update" | "UpdateOnly" Parameters→ None Properties→ <LocationProfileSettings [Description = String] SettingsName = String > <OrgPaths> <SimpleValue>* </OrgPaths> <SettingsParamValues> <SettingsParamValue>*

Workforce Central Developers Toolkit Reference Guide—Timekeeping

467

Chapter 2

Workforce Timekeeper XML API Tag Definitions

</SettingsParamValues> </LocationProfileSettings>

Action Descriptions
Add Adds a pse settings object into the system. If the object already exists, an update will be performed. Return Value Type: None Required Properties: SettingsName, SettingsParamValues, OrgPaths Optional Properties: description Access Control Point Name: Edit Introduced in v6.0 AddOnly Adds a pse settings object into the system. If an object with the same name exists, an exception is thrown. Return Value Type: None Required Properties: SettingsName, SettingsParamValues, OrgPaths Optional Properties: Description Access Control Point Name: Edit Introduced in v6.0 Delete Deletes a pse settings object from the system. If the object doesn't exists, no exception is thrown. Return Value Type: None Required Properties: SettingsName Access Control Point Name: Edit Introduced in v6.0

468

Kronos Incorporated

LocationProfileSettings Tag

DeleteOnly Deletes a pse settings object from the system. If the object doesn't exist, an exception is thrown. Return Value Type: None Required Properties: SettingsName Access Control Point Name: Edit Introduced in v6.0 Retrieve Returns the pse setting object by name. Return Value Type: (***undefined***): PSESettings Required Properties: SettingsName Access Control Point Name: View Introduced in v6.0 RetrieveAll Returns all the pse settings objects. Return Value Type: (***undefined***): PSESettings Access Control Point Name: View Introduced in v6.0 RetrieveAllForUpdate Returns all pse settings objects. The ouput will be used as input by the update method by the SDM. Return Value Type: (***undefined***): PSESettings Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Returns all pse settings objects names. Return Value Type: String list Access Control Point Name: View

Workforce Central Developers Toolkit Reference Guide—Timekeeping

469

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v6.0 RetrieveForUpdate Returns a pse settings object. The output of this method will be used as input for update method by the SDM. Return Value Type: (***undefined***): PSESettings Required Properties: SettingsName Access Control Point Name: View Introduced in v6.0 Update Updates a pse settings object into the system. If the obejct doesn't exists, an exception is thrown. Return Value Type: None Required Properties: SettingsName, SettingsParamValues, OrgPaths Optional Properties: Description Access Control Point Name: Edit Introduced in v6.0 UpdateOnly Updates a pse settings objects into the system. If the object doesn't exists, an exception is thrown. Return Value Type: None Required Properties: SettingsName, SettingsParamValues, OrgPaths Optional Properties: Description Access Control Point Name: Edit Introduced in v6.0

Property Descriptions
Description

Description

470

Kronos Incorporated

LocationProfileSettings Tag

The pse settings object's description. Type: String Optional Sample values: <Description> This is a description</Description> Introduced in v6.0 OrgPaths

Organizational Nodes Paths
The pse settings object's organizational nodes assignment. Type: Zero or more SimpleValue tags Required Sample values: <OrgPaths> <SimpleValue Value="Organization/Hospitals/Hosp A/ Floor 1" /> </OrgPaths> Introduced in v6.0 SettingsName

Settings Name
The pse settings object name. Type: String Required Key Sample values: <SettingsName> PSESettingsName</SettingsName> Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

471

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SettingsParamValues

Settings Parameters Values
The pse settings object's parameters values. Type: Zero or more SettingsParamValue tags Required Sample values: <SettingsParamValues> <SettingsParamValue Name="PROCEDURE_SETS" Value="Assign Only;Unassign Only"/> </SettingsParamValues> Introduced in v6.0

472

Kronos Incorporated

LockedDataCorrection Tag

LockedDataCorrection Tag Adjust Signed-off Timesheet
The LockedDataCorrection tag describes a timesheet item generated by the Callable Totalizer that represents a totalizer-generated adjustment credited to the current pay period. The purpose of this edit is to make an adjustment to time in a signed-off period. Such an adjustment can be needed, for example, when an employee punches across a day divide and the signoff date happens to occur on that day divide. If the work rule specifies that hours count to the scheduled start day, then the "out" punch must be credited to the period prior to the signoff. However, no punches or other timekeeping events are permitted in the database prior to the signoff. Therefore, a LockedDataCorrection is issued by the totalizer, crediting some hours to the current pay period and noting the nature of this correction. Used by: Timesheet Function Access Control Point: API.Timecard Introduced in v4; last changed in v5.0

Syntax
Properties→ <LockedDataCorrection (Date = Date) > (<Employee> <CurrentUser> | <PersonIdentity> </Employee>) (<Totals> <Total>* </Totals>) </LockedDataCorrection>

Property Descriptions
Date

Date

Workforce Central Developers Toolkit Reference Guide—Timekeeping

473

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The date on which the edit is credited Type: Date Output Only Sample values: 8:00 Vacation on 4/2/2001 Introduced in v4 Employee

Employee
One employee, as specified in a PersonIdentity or CurrentUser tag, to whom the amount is credited. Type: Either CurrentUser or PersonIdentity tag Output Only Must uniquely identify an existing and active employee Introduced in v4 Totals

Totals
The totals constituting the correction Type: Zero or more Total tags Output Only Introduced in v4

474

Kronos Incorporated

LogonProfile Tag

LogonProfile Tag Logon Profile
The LogonProfile tag provides information about valid logon profiles that are defined within the system. A logon profile defines the settings for a user's password and restrictions. The LogonProfile and WSALogonProfile tags are used by the same database object. Function Access Control Point: API.Employee Introduced in v4; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllLogonProfiles" | "LoadById" Parameters→ None Properties→ <LogonProfile [LogonProfileId = Integer] [LogonProfileName = String] > </LogonProfile>

Action Descriptions
Load Returns information for the specified logon profile, based on LogonProfileName. Only logon profiles with a database key of -1 or greater will be returned.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

475

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Return Value Type: LogonProfile tag Required Properties: LogonProfileName Access Control Point Name: View Introduced in v4; last changed in v5.0 LoadAllLogonProfiles Returns all assignable logon profiles in the system. Only logon profiles with a database key of -1 or greater shall be returned. Return Value Type: Zero or more LogonProfile tags Required Properties: None Access Control Point Name: View Introduced in v4; last changed in v5.0 LoadById Returns information for the specified logon profile, based on LogonProfileId. Only logon profiles with a database key of -1 or greater shall be returned. Return Value Type: LogonProfile tag Required Properties: LogonProfileId Access Control Point Name: View Introduced in v4; last changed in v5.0

Property Descriptions
LogonProfileId

Logon profile Id
Uniquely identifies the logon profile in the database Type: Integer Optional Introduced in v4

476

Kronos Incorporated

LogonProfile Tag

LogonProfileName

Logon profile name
The Logon Profile column contains the name of the user's logon profile. The logon profile provides rules for password behavior or provides rules for automatic logout and lockout behavior. The following predefined data values are available: • • • • &DEFAULT_LOGON &SUPER_USER_LOGON &XMLUSER_LOGON &IMPORT_LOGON_PROFILE

Type: String Optional Maximum length: 50 characters Sample values: MobileTime Logon Default value: &DEFAULT_LOGON Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

477

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ManagerRoleAvailabilityPatternProfile Tag Availability Pattern Profile for Managers
The ManagerRoleAvailabilityPatternProfile tag contains a valid, existing availability pattern Profile. Function Access Control Point: API.Profile Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAll" Parameters→ None Properties→ <ManagerRoleAvailabilityPatternProfile AvailabilityPatternProfileName = String (Description = String) (IsAllowAll = Boolean) > </ManagerRoleAvailabilityPatternProfile>

Action Descriptions
Load Load the AvailabilityPattern profile from the database. This property cannot be null and has to be valid. Return Value Type: ManagerRoleAvailabilityPatternProfile tag Required Properties: AvailabilityPatternProfileName

478

Kronos Incorporated

ManagerRoleAvailabilityPatternProfile Tag

Access Control Point Name: View Introduced in v5.0 LoadAll Load all of the AvailabilityPattern profiles in the database. Return Value Type: Zero or more ManagerRoleAvailabilityPatternProfile tags Access Control Point Name: View Introduced in v5.0; last changed in v5.0

Property Descriptions
AvailabilityPatternProfileName

Availability pattern profile name
The AvailabilityPatternProfile Name. Type: String Optional Key Required: For a Load action Introduced in v5.0 Description

Description
Description of the profile Type: String Output only Maximum length: 250 characters Introduced in v5.0 IsAllowAll

Does profile contain all permissions?
Indicates whether the profile contains all permissions.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

479

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: Boolean Output only Enumerated value: True, False Introduced in v5.0; last changed in v5.0

480

Kronos Incorporated

ManagerRoleScheduleGroupProfile Tag

ManagerRoleScheduleGroupProfile Tag Schedule Group Profile for Managers
The ManagerRoleScheduleGroupProfile tag contains a valid Schedule Group Profile defined in timekeeping. Function Access Control Point: API.Profile Introduced in v5.0; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAll" Parameters→ None Properties→ <ManagerRoleScheduleGroupProfile (Description = String) (IsAllowAll = Boolean) ScheduleGroupProfileName = String > </ManagerRoleScheduleGroupProfile>

Action Descriptions
Load Load the Schedule Group Profile from the database. The ScheduleGroupProfileName property cannot be null and must be valid. Return Value Type: ManagerRoleScheduleGroupProfile tag Required Properties: ScheduleGroupProfileName

Workforce Central Developers Toolkit Reference Guide—Timekeeping

481

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: View Introduced in v5.0; last changed in v5.1 LoadAll Load all of the Schedule Group Profiles in the database. Return Value Type: Zero or more ManagerRoleScheduleGroupProfile tags Access Control Point Name: View Introduced in v5.0; last changed in v5.1

Property Descriptions
Description

Description
Description of the profile. Type: String Output only Introduced in v5.0 IsAllowAll

Does profile contain all permissions?
Indicates whether the profile contains all permissions Type: Boolean Output only Enumerated value: True, False Introduced in v5.0; last changed in v5.0 ScheduleGroupProfileName

Schedule group profile name
The name of a Manager's schedule group profile. This schedule group profile identifies those schedule groups that the person can select.

482

Kronos Incorporated

ManagerRoleScheduleGroupProfile Tag

The following predefined data values are available: • • &ALL_SCHEDULE_PATTERNS &EMPTY

Type: String Optional Key Maximum length: 50 characters Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

483

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ManagerRoleSchedulePatternProfile Tag Schedule Pattern Profile for Managers
The ManagerRoleSchedulePatternProfile tag contains a valid SchedulePattern Profiles defined in Timekeeping. Function Access Control Point: API.Profile Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAll" Parameters→ None Properties→ <ManagerRoleSchedulePatternProfile (Description = String) (IsAllowAll = Boolean) SchedulePatternProfileName = String > </ManagerRoleSchedulePatternProfile>

Action Descriptions
Load Load the SchedulePattern profile from the database. The SchedulePatternProfileName property cannot be null and has to be valid. Return Value Type: ManagerRoleSchedulePatternProfile tag Required Properties: SchedulePatternProfileName

484

Kronos Incorporated

ManagerRoleSchedulePatternProfile Tag

Access Control Point Name: View Introduced in v5.0 LoadAll Load all of the SchedulePattern profiles in the database. Return Value Type: Zero or more ManagerRoleSchedulePatternProfile tags Access Control Point Name: View Introduced in v5.0; last changed in v5.0

Property Descriptions
Description

Description
Description of the profile Required: For a load action Type: String Output only Maximum length: 30 characters Introduced in v5.0 IsAllowAll

Does profile contain all permissions?
Indicates whether the profile contains all permissions Type: Boolean Output only Enumerated value: True, False Introduced in v5.0; last changed in v5.0 SchedulePatternProfileName

Schedule pattern profile name

Workforce Central Developers Toolkit Reference Guide—Timekeeping

485

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The name of SchedulePatternProfile Type: String Optional Key Maximum length: 250 characters Introduced in v5.0

486

Kronos Incorporated

ManagerRoleShiftCodeProfile Tag

ManagerRoleShiftCodeProfile Tag Shift Code Profile for Managers
The ManagerRoleShiftCodeProfile displays a valid shift code profile that already exists. Function Access Control Point: API.Profile Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAll" Parameters→ None Properties→ <ManagerRoleShiftCodeProfile (Description = String) (IsAllowAll = Boolean) ShiftCodeProfileName = String > </ManagerRoleShiftCodeProfile>

Action Descriptions
Load Load the ShiftCode profile from the database. The ShiftCodeProfileName property cannot be null and has to be valid. Return Value Type: ManagerRoleShiftCodeProfile tag Required Properties: ShiftCodeProfileName

Workforce Central Developers Toolkit Reference Guide—Timekeeping

487

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: View Introduced in v5.0 LoadAll Load all of the ShiftCode profiles in the database. Return Value Type: Zero or more ManagerRoleShiftCodeProfile tags Access Control Point Name: View Introduced in v5.0; last changed in v5.0

Property Descriptions
Description

Description
Description of the profile Type: String Output only Introduced in v5.0 IsAllowAll

Does profile contain all permissions?
Indicates whether the profile contains all permissions Type: Boolean Output only Enumerated value: True, False Introduced in v5.0; last changed in v5.0 ShiftCodeProfileName

Shift code profile name
Name of the shift code profile Required: For a load action

488

Kronos Incorporated

ManagerRoleShiftCodeProfile Tag

Type: String Optional Key Maximum value: 30 characters Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

489

Chapter 2

Workforce Timekeeper XML API Tag Definitions

MarkForTotalization Tag Mark for Totalization
The MarkForTotalization tag identifies employee information that has changed and must be recomputed. Function Access Control Point: API.Timecard Introduced in v4; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Update" Parameters→ None Properties→ <MarkForTotalization [RuleChangedFlag = Boolean] [ScheduleChangedFlag = Boolean] > <Employee> <CurrentUser> | <PersonIdentity> </Employee> </MarkForTotalization>

Action Descriptions
Update Updates the specified flag or flags for the employee. Return Value Type: None Required Properties: Employee

490

Kronos Incorporated

MarkForTotalization Tag

Optional Properties: RuleChangeFlag, ScheduleChangedFlag Access Control Point Name: Edit Introduced in v4

Property Descriptions
Employee

Employee
One employee, as specified in a PersonIdentity or CurrentUser tag, to be marked for totalization Type: Either CurrentUser or PersonIdentity tag Required Key Must uniquely identify an existing and active employee Introduced in v4 RuleChangedFlag

Totalize if the pay rule changes?
Initiates a totalization for the employee as if the employee's pay rule has changed Type: Boolean Optional Default value: False Enumerated value: True, False Introduced in v4 ScheduleChangedFlag

Totalize if the schedule changes?
Initiates a totalization for the employee as if the employee's schedule has changed Type: Boolean Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

491

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Default value: False Enumerated value: True, False Introduced in v4; last changed in v5.0

492

Kronos Incorporated

Menu Tag

Menu Tag Menu
The Menu tag identifies the list of menu items for one user. If no user is specified, the default value is the logged-on user. Function Access Control Point: API.Menu Introduced in v4

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" Parameters→ None Properties→ <Menu (<MenuItems> <MenuItem>* </MenuItems>) <User> <CurrentUser> | <PersonIdentity> </User> </Menu>

Action Descriptions
Load Returns a list of menu items for the specified user or the currently logged-on user. Return Value Type: Menu tag

Workforce Central Developers Toolkit Reference Guide—Timekeeping

493

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: View Introduced in v4

Property Descriptions
MenuItems

Menu items
A list of menu items for the user Type: Zero or more MenuItem tags Output Only Introduced in v4 User

User
One person, as specified in a PersonIdentity or CurrentUser tag, to whom the menu is assigned Type: Either CurrentUser or PersonIdentity tag Optional Key Default value: Logged on user Introduced in v4

494

Kronos Incorporated

MenuItem Tag

MenuItem Tag Menu Item
The MenuItem tag denotes one entry in a Menu tag. You can use this tag to display a menu item and follow its links. Used by: Menu Function Access Control Point: API.Menu Introduced in v4

Syntax
Properties→ <MenuItem (AccessControlPointName = String) (Depth = Integer) (ExternalFlag = Boolean) (Label = String) (MenuItemName = String) (URL = String) > </MenuItem>

Property Descriptions
AccessControlPointName

Access control point name
A control, such as access to the HyperFind function, that determines how a user can interact with a product feature Type: String Output Only Introduced in v4 Depth

Depth of item within menu

Workforce Central Developers Toolkit Reference Guide—Timekeeping

495

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Depth of this item in the menu Type: Integer Output Only Must be greater than or equal to 0 Introduced in v4 ExternalFlag

Is this an external menu link?
Indicates whether this menu item points to a link that is part of the application. If it points to an external link, the value is True. Type: Boolean Output Only Enumerated value: True, False Introduced in v4 Label

Label shown in menu
The label used when displaying this menu item Type: String Output Only Introduced in v4 MenuItemName

Menu item
Name of the menu item Type: String Output Only Introduced in v4

496

Kronos Incorporated

MenuItem Tag

URL

URL for menu item
The URL of the menu item Type: String Output Only Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

497

Chapter 2

Workforce Timekeeper XML API Tag Definitions

MinimunHoursNoModification Tag Minimum allowable hours before a swap shift
In order to swap a shift, you must make your request before the shift start time. The minimum number of hours in advance of the shift is determined according to organizational rules. For example, if the minimum number of hours is 72, your request must be made at least 72 hours before the start time of the shift. The MinimunHoursNoModification tag is used to determine whether a swap shift is requested at an acceptable time. Function Access Control Point: API.Schedule Introduced in v5.1Beta; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" Parameters→ None Properties→ <MinimunHoursNoModification (MinimunHoursRequired = Time) (IsBeyondMinimunHours = Boolean) QueryDate = Date StartTime = Time > </MinimunHoursNoModification>

Action Descriptions

498

Kronos Incorporated

MinimunHoursNoModification Tag

Load This action determines whether the request is made at an acceptable time. Return Value Type: MinimunHoursNoModification tag Required Properties: QueryDate, StartTime Access Control Point Name: View Introduced in v5.1Beta

Property Descriptions
IsBeyondMinimunHours

Is request submitted on time?
This value is true if your request has been submitted on time; false if is has not. Type: Boolean Output only Enumerated value: true, false Introduced in v5.0a MinimunHoursRequired

Hours required before the request
The minimum number of hours before a shift that a swap can be accepted Type: Time Output only Sample values: 72.00 Introduced in v5.0a QueryDate

Start date
The date when the request is submitted

Workforce Central Developers Toolkit Reference Guide—Timekeeping

499

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: Date Required Introduced in v5.1Beta StartTime

Start time
The time of day when the shift begins Type: Time Required Introduced in v5.1Beta

500

Kronos Incorporated

NameList Tag

NameList Tag Name List
The NameList tag returns one or more items that are specified in a specific request. Function Access Control Point: API.Common Introduced in v5.1; last changed in v5.1

Syntax
Properties→ <NameList (PropertyName = String) > (<Names> </Names>) </NameList>

Property Descriptions
Names

Names
One or more names of the entities in the DB as instances of "SimpleValue" or "SimplePair" Type: Either tag Output only Introduced in v5.1 PropertyName

Property Name
This whole object represents the collection of names of all of the instances of a particular type of business object within the target DB. This attribute holds the

Workforce Central Developers Toolkit Reference Guide—Timekeeping

501

Chapter 2

Workforce Timekeeper XML API Tag Definitions

name of the attribute which is used with one of the names within this collection to retrieve a particular instance of this Business Object class from the database. Type: String Output only Introduced in v5.1

502

Kronos Incorporated

Names Tag

Names Tag Names of Rules
List of user-understandable names of all rules (i.e business entities). Function Access Control Point: API.Common Introduced in v5.1; last changed in v5.1

Syntax
Properties→ <Names (<SimpleValues> <SimpleValue>* </SimpleValues>) </Names>

Property Descriptions
SimpleValues

Set of rule names
List of names returned as simple values. Type: Zero or more SimpleValue tags Output only Introduced in v5.1; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

503

Chapter 2

Workforce Timekeeper XML API Tag Definitions

NavProfile Tag Navigation Profile
This tag enables you to specify what parts of the system users can see and access. Standard named entity validation. Function Access Control Point: API.DISPLAY_PROFILES Introduced in v6.0; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Delete" | "Retrieve" | "RetrieveAll" | "RetrieveAllNames" | "RetrieveForUpdate" | "RetrieveForUpdateFactory" | "Update" Parameters→ None Properties→ <NavProfile [Active = String] [HomePagePath = String] [Description = String] Name = String [Type = String] [RootNodePath = String] [LegacyHomePage = String] > </NavProfile>

504

Kronos Incorporated

NavProfile Tag

Action Descriptions
Delete Deletes the named NavProfile. Return Value Type: None Required Properties: Name Access Control Point Name: Edit Introduced in v6.0 Retrieve Retrieves the NavProfile item Return Value Type: NavProfile tag Required Properties: Name Access Control Point Name: View Introduced in v6.0; last changed in v6.0 RetrieveAll Retrieves all the NavProfiles in the system. Return Value Type: Zero or more NavProfile tags Required Properties: None Access Control Point Name: View Introduced in v6.0; last changed in v6.0 RetrieveAllNames Retrieves the names of all the NavProfiles in the system. Required method for Setup Data Manager. Return Value Type: String list Required Properties: None Access Control Point Name: View Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

505

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RetrieveForUpdate Retrieves the named NavProfile for update. Method required for Setup Data Manager. Return Value Type: NavProfile tag Required Properties: Name Access Control Point Name: Edit Introduced in v6.0 RetrieveForUpdateFactory Retrieves the named NavProfile for updating. Return Value Type: NavProfile tag Required Properties: Name Access Control Point Name: Edit Introduced in v6.0 Update Updates the profile or inserts a new NavProfile if it doesn't exist. Return Value Type: None Optional Properties: Name, Type, Active, LegacyHomePage, Description, RootNodePath, HomePagePath Access Control Point Name: Edit Introduced in v6.0; last changed in v6.0

Property Descriptions
Active

Active or Inactive Navigation Profile
Specify whether the navigation profile is active or not active. Type: String Optional Sample values:

506

Kronos Incorporated

NavProfile Tag

true Default value: true Enumerated value: true, false Introduced in v6.0; last changed in v6.0 Description

NavProfile Description
Specify an optional descriptiion of the navigation profile. Type: String Optional Sample values: This is a NavProfile for Managers Introduced in v6.0 HomePagePath

Home page path
Specify an optional path to the user's home page. Type: String Optional Introduced in v6.0 LegacyHomePage

UsersHomePage'
Specify the page to load for advanced users when they log on. Type: String Optional Sample values: /QUICKFIND

Workforce Central Developers Toolkit Reference Guide—Timekeeping

507

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v6.0 Name

Navigation Profile Name
Specify the name of the navigation profile. Type: String Required Normal WFC character validation for Srings. Sample values: Manager Navigation Introduced in v6.0; last changed in v6.0 RootNodePath

Root node path
Specify an optional root node in the menu structure for this profile. Type: String Optional Introduced in v6.0 Type

Navigation Profile Type
Specify the types of Navigation Profiles. The choices are Basic for the default home page, and Advanced to select another home page. Type: String Optional Sample values: Basic

508

Kronos Incorporated

NavProfile Tag

Default value: Basic Enumerated value: Advanced, Basic Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

509

Chapter 2

Workforce Timekeeper XML API Tag Definitions

NonCancellingPayCodeEdit Tag Non-Canceling Pay Code Edit
The NonCancellingPayCodeEdit tag adds or subtracts an amount to an existing pay code edit. If you want to override a scheduled pay code edit with a specified amount, use the PayCodeEdit tag. Function Access Control Point: API.Timecard Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddComment" | "AddOnly" | "Delete" Parameters→ AddOnly→ [AccrualOverride = Boolean] [allowAdHoc = Boolean] [EchoData = Boolean] Properties→ <NonCancellingPayCodeEdit AmountInTimeOrCurrency = String ScheduleAmountType = String OrgJobId = String OrgJobName = String [CommentText = String] (EnteredOnDate = Date) Date = Date (IsCurrencyFlag = Boolean)

510

Kronos Incorporated

NonCancellingPayCodeEdit Tag

LaborAccountName = String [ManagerName = String] [OverrideAccrualDays = Double] PayCodeName = String [StartTime = Time] (EnteredOnTime = Time) > [<Notes> <Note>* </Notes>] (<Comments> <Comment>* </Comments>) <Employee> <CurrentUser> | <PersonIdentity> </Employee> </NonCancellingPayCodeEdit>

Action Descriptions
AddComment Adds a comment to each pay code edit associated with the specified employee. The CommentText must exactly match an entry in the Comment table. Return Value Type: None Required Properties: AmountInTimeOrCurrency, CommentText, Date, Employee, PayCodeName Access Control Point Name: Edit Introduced in v4 AddOnly Adds a new pay code edit with the specified properties. Return Value Type: PayCodeEdit tag Required Properties: AmountInTimeOrCurrency, Date, Employee, PayCodeName Access Control Point Name: Edit Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

511

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Parameters Parameter Name AccrualOverride Description If the action results in an accrual warning, the warning is overridden when AccrualOverride=True. Optional Default value: False Specifies whether an ad hoc labor level is allowed. Optional Default value: False If True, the Response includes a copy of this tag. Optional Default value: False Additional information Introduced in v4

allowAdHoc

Introduced in v5.0; last changed in v5.0; deprecated in v5.0. Not used Introduced in v4

EchoData

Delete Marks for deletion all pay code edits for the employee with matching properties. Return Value Type: None Required Properties: AmountInTimeOrCurrency, Date, Employee, PayCodeName Access Control Point Name: Edit Introduced in v4

Property Descriptions
AmountInTimeOrCurrency

Amount of pay code, in time or currency
Amount to be added or subtracted from an existing pay code, expressed as a time duration or money. To subtract an amount, use a negative number. Type: String Maximum length: 30 characters

512

Kronos Incorporated

NonCancellingPayCodeEdit Tag

Whether the value is expressed as a time duration or a currency depends on the pay code. Introduced in v4; last changed in v5.1 ScheduleAmountType

Amount, based on the employee schedule
Amount, based on the employee schedule Type: String Introduced in v6.0 OrgJobId

ID of job in organization
ID of job in organization Type: String Introduced in v6.0 OrgJobName

Job in the organization
Job in the organization Type: String Introduced in v6.0 Comments

Comments
The set of comments currently returned with this timekeeping item Type: Zero or more Comment tags Output Only Introduced in v4 CommentText

Comment text

Workforce Central Developers Toolkit Reference Guide—Timekeeping

513

Chapter 2

Workforce Timekeeper XML API Tag Definitions

A comment Type: String Optional Maximum length: 254 characters The comment must match exactly an applicable comment that already exists in the database. The string matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application. Introduced in v4; last changed in v5.0 Date

Date to which the edit applies
The date to which the edit applies Type: Date Required, Key Sample values: 4/2/2000 Introduced in v4 Employee

Employee
One employee to be credited with the amount, as specified in a PersonIdentity or CurrentUser tag Type: Either CurrentUser or PersonIdentity tag Required, Key Must uniquely identify an existing and active employee Introduced in v4 EnteredOnDate

Date of the edit

514

Kronos Incorporated

NonCancellingPayCodeEdit Tag

The server date on which the edit is added to the database Type: Date Output Only Introduced in v4 EnteredOnTime

Time of the edit
The server time at which the edit is added to the database Type: Time Output Only Introduced in v4 IsCurrencyFlag

Is the pay code in currency?
True if the pay code represents a monetary item. False if it represents an hourly pay code. Type: Boolean Output Only Enumerated value: True, False Introduced in v4 LaborAccountName

Labor account
The name of the labor account. LaborAccountName is required when the pay code edit, historical edit, or totaled amount being deleted or commented contained an explicit value. It need not be specified if the pay code amount or totaled amount applies to the employee's primary account. Enter data for labor accounts in the same format as they appear in the timekeeping database. For example, if you have a seven-level labor account, specify a value for each labor level, using the following format: 101/202/303/404/504/603/702.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

515

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Do not specify labor levels that are not changing. If any of the labor levels are the same as the employee's primary labor account, you can enter @H for those labor levels instead of entering the labor entry names. Type: String Optional, Key Maximum length: 356 characters Default value: Primary account for the employee Introduced in v4; last changed in v5.0 ManagerName

Manager name
Manager Name Type: String Optional Introduced in v6.0 Notes

Comment Notes
Comment Notes Type: Zero or more Note tags Optional Introduced in v6.0 OverrideAccrualDays

Override Accrual Days
Override Accrual Days Type: Double Optional Introduced in v6.0

516

Kronos Incorporated

NonCancellingPayCodeEdit Tag

PayCodeName

Pay code
The pay code to be edited. Type: String Required, Key Must be associated with an hourly or monetary pay code edit Introduced in v4; last changed in v5.1 StartTime

Start Time
Start Time Type: Time Optional Introduced in v6.0

Groups of Mutually Exclusive Properties
Amount in Time Amount value Required Group includes: AmountInTimeOrCurrency, ScheduleAmountType OrgJob Organization Job Optional Group includes: OrgJobId, OrgJobName

Workforce Central Developers Toolkit Reference Guide—Timekeeping

517

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Note Tag Note
This tag lets you add text notes to comments on a time sheet or schedule item. Function Access Control Point: API.Common Introduced in v6.0; last changed in v6.0

Syntax
Properties→ <Note Text = String [Timestamp = DateTime] > [<DataSource> <DataSource> </DataSource>] </Note>

Property Descriptions
DataSource

Data Source
Specify the person who created the note. Type: DataSource tag Optional Introduced in v6.0 Text

Note Text
Specify the text of the note. Type: String Required

518

Kronos Incorporated

Note Tag

Introduced in v6.0 Timestamp

Note Timestamp
Specify the time when you created the note. Type: DateTime Optional Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

519

Chapter 2

Workforce Timekeeper XML API Tag Definitions

OnCall Tag On Call
The OnCall tag describes a timesheet item generated by the Callable Totalizer. This read-only pay code edit corresponds to the amount of time in the scheduled shift if the scheduled shift's work rule has been configured as a "Callin" work rule. The scheduled shift may be a work rule transfer. Used by: Timesheet Function Access Control Point: API.Timecard Introduced in v4; last changed in v5.0

Syntax
Properties→ <OnCall (AmountInTime = TimeDuration) (Date = Date) (LaborAccountName = String) > (<Employee> <CurrentUser> | <PersonIdentity> </Employee>) </OnCall>

Property Descriptions
AmountInTime

Amount of pay code, in time
Amount of pay code amount, expressed as a time duration Type: TimeDuration Output Only Introduced in v4 Date

Date

520

Kronos Incorporated

OnCall Tag

The date on which the edit is credited Type: Date Output Only Sample values: 4/2/2001 Introduced in v4 Employee

Employee
One employee, as specified in a PersonIdentity or CurrentUser tag, to be credited with the amount. Type: Either CurrentUser or PersonIdentity tag Output Only Must uniquely identify an existing and active employee Introduced in v4 LaborAccountName

Labor account
The labor account associated with the edit. If not specified in the PayCodeEdit tag, the employee's primary account is used. Type: String Output Only Maximum length:356 characters Introduced in v4; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

521

Chapter 2

Workforce Timekeeper XML API Tag Definitions

OpenShift Tag Open shift
An open shift. Function Access Control Point: Schedule Planner Introduced in v6.0

Syntax None

522

Kronos Incorporated

OpenShiftItem Tag

OpenShiftItem Tag Open shift details
This tag only contains an open shift's date time span information. none Function Access Control Point: API.Schedule Introduced in v5.1; last changed in v5.2

Syntax
Properties→ <OpenShiftItem (DATE_TIME_SPAN = DateTimeSpan) > </OpenShiftItem>

Property Descriptions
DATE_TIME_SPAN

Date-time span of the open shift
This property contains an open shift's date time span. Type: DateTimeSpan Output only Must be a valid date time span. Introduced in v5.1; last changed in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

523

Chapter 2

Workforce Timekeeper XML API Tag Definitions

OpenShiftVolunteer Tag Open Shift Volunteer
This tag assigns a Workforce Scheduler licensed employee to an open shift. Function Access Control Point: API.Schedule Introduced in v5.1; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AssignOpenShiftVolunteer" | "GetOpenShiftsForJob" Parameters→ None Properties→ <OpenShiftVolunteer [IsCheckRules = Boolean] [PartialEndDate = Date] [PartialEndTime = Time] QueryDateTimeSpan = DateTimeSpan OrgJobPath = String [QueryDate = Date] [IsSaveData = Boolean] [PartialStartDate = Date] [PartialStartTime = Time] > <Employee> <PersonIdentity> </Employee> (<OpenShiftItems> <OpenShiftItem>* </OpenShiftItems>) (<RuleViolations>

524

Kronos Incorporated

OpenShiftVolunteer Tag

<RuleViolation>* </RuleViolations>) </OpenShiftVolunteer>

Action Descriptions
AssignOpenShiftVolunteer This action will assign a person to an open shift. The specified open shift must be a valid open shift. The specified employee must be an active employee. Return Value Type: Zero or more RuleViolation tags Required Properties: QueryDateTimeSpan,OrgJobPath,Employee Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 GetOpenShiftsForJob This action will load all open shifts for a specified job within a specified date range. OrgJobPath must be a valid organization job path and QueryDate must be a valid date. Return Value Type: Zero or more OpenShiftItem tags Required Properties: QueryDate, OrgJobPath Access Control Point Name: View Introduced in v5.1; last changed in v5.1

Property Descriptions
Employee

Employee
This property represents the employee who requests the action to cover an open shift. Type: PersonIdentity tag

Workforce Central Developers Toolkit Reference Guide—Timekeeping

525

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required Key It must be an active employee. Introduced in v5.1; last changed in v5.1 IsCheckRules

Check validation rules?
This property indicates whether schedule validation rules will be checked. Type: Boolean Optional none Introduced in v5.1; last changed in v5.1 IsSaveData

Save change data?
This property indicates whether the changes made will be persisted to the database. Type: Boolean Optional none Introduced in v5.1; last changed in v5.1 OpenShiftItems

Open Shift Items
This property contains a list of an open shift's date time span information. Type: Zero or more OpenShiftItem tags Output only none Introduced in v5.1; last changed in v5.1

526

Kronos Incorporated

OpenShiftVolunteer Tag

OrgJobPath

Organizational job path
This property represents an organization job for an open shift Type: String Optional Key The specified jon must be a valid job Introduced in v5.1; last changed in v5.1 PartialEndDate

End date of replacement shift
This property represents the end date of a shift to replace a specified open shift. Type: Date Optional Must be a valid date. Introduced in v5.1; last changed in v5.1 PartialEndTime

End time of replacement shift
This property represents the end time of a shift to replace a specified open shift. Type: Time Optional Must be a valid time. Introduced in v5.1; last changed in v5.1 PartialStartDate

Start date of replacement shift
This property represents the start date of a shift to replace a specified open shift. Type: Date

Workforce Central Developers Toolkit Reference Guide—Timekeeping

527

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Must be a valid date. Introduced in v5.1; last changed in v5.1 PartialStartTime

Start time of replacement shift
This property represents the start time of a shift to replace a specified open shift. Type: Time Optional Must be a valid time. Introduced in v5.1; last changed in v5.1 QueryDate

Query date
This property is used to query for open shifts in the specified date. Type: Date Optional Must be a valid date. Introduced in v5.1; last changed in v5.1 QueryDateTimeSpan

Open shift date and time span
This property represents an existing an open shift date time span. Type: DateTimeSpan Optional Key It must be a valid date time span for an existing open shift. Introduced in v5.1; last changed in v5.1 RuleViolations

Rule violations

528

Kronos Incorporated

OpenShiftVolunteer Tag

This is a set of rule violations that was generated by the tag. Type: Zero or more RuleViolation tags Output only none Introduced in v5.1; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

529

Chapter 2

Workforce Timekeeper XML API Tag Definitions

OptOutStatus Tag Working Time Directive Opt Out Status
This tag shows an employee's opt in/out status for the Working Time Directive. The Working Time Directive feature lets you plan, monitor, and track the amount of time that employees are required to work. It also lets you ensure that employees have appropriate rest periods. A working time directive rule should be assigned only to those employees who have working time limits. For more information, see the online help. See parent WTDEmployeeAssignment. Function Access Control Point: Working Time Directive Introduced in v5.1; last changed in v5.1

Syntax
Properties→ <OptOutStatus [EffectiveDate = DateTime] [ExpirationDate = DateTime] [In = Boolean] WtdEmployeeAssgnmntId = Long > </OptOutStatus>

Property Descriptions
EffectiveDate

Effective Date
The date on which this status is effective. Type: DateTime Optional Introduced in v5.1

530

Kronos Incorporated

OptOutStatus Tag

ExpirationDate

Expiration Date
The date on which this status expires. Not used. Type: DateTime Optional Introduced in v5.1 In

Opt Out/In Status
Indicates if the status is an opt in or out. Type: Boolean Optional Sample values: True Introduced in v5.1 WtdEmployeeAssgnmntId

WTD Employee Assignment Id
Set on object insert. No need to set. Type: Long Required Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

531

Chapter 2

Workforce Timekeeper XML API Tag Definitions

OptOutStatusList Tag Working Time Directive Opt Out Status List
Extended from EffectiveDatedList it represents all of an employee's opt in/out status for a Working Time Directive Rule. See parent WTDEmployeeAssignment. Function Access Control Point: Working Time Directive Introduced in v5.1; last changed in v5.1

Syntax
Properties→ <OptOutStatusList [WtdAssignmentId = Long] > [<OptOutStatuses> <OptOutStatus>* </OptOutStatuses>] </OptOutStatusList>

Property Descriptions
OptOutStatuses

Opt Out Statuses
The list of opt in/out statuses for an employee Type: Zero or more OptOutStatus tags Optional Introduced in v5.1 WtdAssignmentId

WTD Assignment Id
Set on insertion into WTDEmployeeAssignment. Not necessary to set. Type: Long

532

Kronos Incorporated

OptOutStatusList Tag

Optional Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

533

Chapter 2

Workforce Timekeeper XML API Tag Definitions

OrgDirect_IndirectPct Tag ApiOrgDirect_IndirectPct
Api that takes the OrgIds and EffectiveDate and returns an ApiOrgDirect_IndirectPctBean that contains the entered data and the Direct and InDirect percentages. The action is load That the OrgIds and EffectiveDate are set as input properties and that the return object contains the OrgIds, EffectiveDate, Direct percentage and InDirect percentage values Function Access Control Point: API.OrgMap Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "load" Parameters→ None

Action Descriptions
load Gets the Direct and InDirect Pct Return Value Type: (***undefined***): ApiOrgDirect_IndirectPct Required Properties: OrgIds EffectiveDate Access Control Point Name: Edit Introduced in v5.2; last changed in v5.2

534

Kronos Incorporated

OrgJob Tag

OrgJob Tag Organizational Job
An organizational job is a job plus a location in the organizational map. An organizational job is represented by an organizational path name. Function Access Control Point: API.RetailSchedules Introduced in v5.1Beta; last changed in v5.2

Syntax
Properties→ <OrgJob [FullPath = String] (NodeId = Long) > </OrgJob>

Property Descriptions
FullPath

Full path for organizational job
The full path for the task group organizational job Type: String Optional Introduced in v5.1Beta; last changed in v5.2 NodeId

Organizational node id
The id for the organizational node Type: Long Output only Introduced in v5.1Beta

Workforce Central Developers Toolkit Reference Guide—Timekeeping

535

Chapter 2

Workforce Timekeeper XML API Tag Definitions

OrgLocation Tag Location of Node in Organization
The OrgLocation tag describes a node in an organizational map (or tree). An organizational map is a hierarchical representation of an organization that represents where employees work, where they might be scheduled (locations), and the jobs they perform at those locations. Used by: OrgLocationsImport The node must be unique under the parent node. Function Access Control Point: API.Tree Introduced in v5.0; last changed in v5.2

Syntax
Properties→ <OrgLocation [Description = String] [EndEffectiveDate = Date] [StartEffectiveDate = Date] [Seasonal = Boolean] [LLEntryName = String] ParentLocationNum = Long [LocationType = String] LocationNum = Long [LocationName = String] > [<OrgWorkAllocationEntryList> <OrgWorkAllocationEntry>* </OrgWorkAllocationEntryList>] </OrgLocation>

Property Descriptions
Description

Description
Describes the node.

536

Kronos Incorporated

OrgLocation Tag

Type: String Optional You can find values in the Workforce Timekeeper Setup Application. Sample values: Registered Nurse Introduced in v5.0 EndEffectiveDate

Effective end date
The date when the node ceases to be effective. Required: If an organizational location is being added. Optional: If an organizational location is being updated. Type: Date Optional The effective date must be within the range of effective dates for the parent node. A change in an effective date for a parent node automatically changes the appropriate child node's effective date. Default value: 1/1/3000 Introduced in v5.0; last changed in v5.0 LLEntryName

Labor level entry
The labor level name of the node. Type: String Optional Maximum length: 50 characters Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

537

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LocationName

Node in the organization
The name of the node. Type: String Optional You can find values in the Workforce Timekeeper user interface. Required: If you are adding a new node Introduced in v5.0 LocationNum

Node Id
A unique identifier for the node. Type: Long Required Key Maximum length: 12 Introduced in v5.0 LocationType

Location type
The category of the node in the organization. Type: String Optional You can find values in the Workforce Timekeeper user interface. Required: If you add a new node, you must specify an already existing LocationType. Sample values: Facility, Job, Division

538

Kronos Incorporated

OrgLocation Tag

Introduced in v5.0 OrgWorkAllocationEntryList

Fixed percent allocation rules
A list of fixed percent allocation rules that apply to the jobs in this location. Type: Zero or more OrgWorkAllocationEntry tags Optional Introduced in v5.2 ParentLocationNum

Location of parent node
The unique identifier of the parent node to which this node is associated. Type: Long Required Maximum length: 12 characters Must be an integer The ParentLocationNum must exist in the organizational tree. Required: When adding a new location or job Introduced in v5.0; last changed in v5.0 Seasonal

Is the location seasonal?
Boolean value that, when True, indicates that the job or location is not active for the full year. Type: Boolean Optional true or false Sample values: true, false

Workforce Central Developers Toolkit Reference Guide—Timekeeping

539

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.1 StartEffectiveDate

Effective start date
The date when the node becomes effective. Required: If an organizational location is being added. Optional: If an organizational location is being updated. Type: Date Optional The effective date must be within the range of effective dates for the parent node. A change in an effective date for a parent node automatically changes the appropriate child node's effective date. Default value: 1/1/3000 Introduced in v5.0; last changed in v5.0

540

Kronos Incorporated

OrgLocationsImport Tag

OrgLocationsImport Tag Nodes in Organizational Map
The OrgLocationsImport tag is used to import one or more nodes in the organizational map (or tree). A node can be modified, moved to a different parent node, or added. Function Access Control Point: API.Tree Introduced in v5.0; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Update" Parameters→ None Properties→ <OrgLocationsImport ChangeDate = Date > <OrgLocations> <OrgLocation>* </OrgLocations> </OrgLocationsImport>

Action Descriptions
Update Imports one or more organizational tree nodes. If a specified node already exists, it is updated. If it does not exist, it is added.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

541

Chapter 2

Workforce Timekeeper XML API Tag Definitions

If you are adding a node, you must specify existing LocationType and LocationName properties in the OrgLocation tag. Return Value Type: None Required Properties: ChangeDate, OrgLocations Access Control Point Name: Edit Introduced in v5.0

Property Descriptions
ChangeDate

Date of import
The date when the specified nodes are imported Type: Date Required Introduced in v5.0 OrgLocations

Organization locations
One or more organization locations Type: Zero or more OrgLocation tags Required Introduced in v5.0

542

Kronos Incorporated

OrgMapIntegration Tag

OrgMapIntegration Tag Organizational map
Use this tag to access the organizational map. Function Access Control Point: API.OrgMap Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadJobLocations" | "RetrieveAll" | "RetrievePartial" Parameters→ None

Action Descriptions
LoadJobLocations Retrieve Home Location data which can be either retrieved from the database or calculated in memory Return Value Type: Zero or more OrgMapIntegration tags Required Properties: None Access Control Point Name: View Introduced in v5.2 RetrieveAll Validation done in the KBO

Workforce Central Developers Toolkit Reference Guide—Timekeeping

543

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Validation done in the KBO Return Value Type: (***undefined***): OrgNodeIntegration Required Properties: Kdate Access Control Point Name: View Introduced in v5.2 RetrievePartial validation done in the KBO validation done in the KBO Return Value Type: (***undefined***): OrgNodeIntegration Required Properties: Date, OrgPath, Depth Access Control Point Name: View Introduced in v5.2

544

Kronos Incorporated

OrgSet Tag

OrgSet Tag Organizational Set
The OrgSet tag describes the attributes of an organizational set. An organizational set is a group of organizational jobs combined into a single entity for group edits and other management tasks. Organizational sets contain one or more organizational groups or job transfer sets, beginning with the manager's personal root. This tag identifies the area of the organizational map that a user can access. It also retrieves a list of organizational sets of a particular type, such as job transfer sets. Function Access Control Point: API.DataAccess Introduced in v5.0; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "Load" | "Update" | "UpdateEntryList" | "UpdateOnly" Parameters→ None Properties→ <OrgSet [Description = String] OrgSetName = String [OrgSetTypeName = String] [Name = String] (OrgSetId = Long) > [<EntryList>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

545

Chapter 2

Workforce Timekeeper XML API Tag Definitions

<OrgSetEntry>* </EntryList>] (<OrgSetJobList> <OrgSetJob>* </OrgSetJobList>) </OrgSet>

Action Descriptions
AddOnly Adds a new organizational set. Return Value Type: None Required Properties: OrgSetName,OrgSetTypeName, EntryList, Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0 Load Returns information for all organization sets. When type is not specified, orgsetids and effectiveDate are required when type is "orgJobs". Return Value Type: Zero or more OrgSet tags Required Properties: orgsetName Optional Properties: TYPE, orgsetids, effectiveDate, fullPath Access Control Point Name: View Introduced in v5.0; last changed in v6.0 Update Adds a new organizational set or updates an existing one. When adding a new organizational set, Description, orgSetTypeName and EntryList are required. Return Value Type: None Required Properties: orgsetName Optional Properties: Description, OrgSetTypeName, EntryList Access Control Point Name: Edit Introduced in v5.0

546

Kronos Incorporated

OrgSet Tag

UpdateEntryList Updates all jobs in the organizational set. Return Value Type: None Required Properties: OrgSetName, EntryList Invalid Properties: Description, OrgSetTypeName Access Control Point Name: Edit Introduced in v6.0 UpdateOnly Updates information for an existing organization set. Return Value Type: None Required Properties: OrgSetName Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0

Property Descriptions
Description

Description
Describes the organization set, which consists of locations and jobs. Type: String Optional You can find values in the Workforce Timekeeper user interface. Introduced in v5.0 EntryList

All jobs in the set
This list contains all of the jobs in the set. Type: Zero or more OrgSetEntry tags Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

547

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.0; last changed in v5.0 Name

New name of job set
A unique name used to rename the organization job set Type: String Optional Introduced in v5.0; last changed in v6.0 OrgSetId

Primary identifier for job set
The primary identifier for the organization job set Type: Long Output only Maximum length: 10 characters An integer value Introduced in v5.0; last changed in v5.0 OrgSetJobList

Jobs in set
One or more jobs in the organization job set Type: Zero or more OrgSetJob tags Output only Introduced in v5.0; last changed in v5.0 OrgSetName

Job set name
The name of the organizational set for the selected action. Type: String

548

Kronos Incorporated

OrgSet Tag

Required Key Introduced in v5.0; last changed in v5.1 OrgSetTypeName

Job set type
Type of the organization job set Type: String Optional Maximum length: 30 characters Enumerated value: All Organizational Sets, Organizational Groups, Job Transfer Sets Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

549

Chapter 2

Workforce Timekeeper XML API Tag Definitions

OrgSetEntry Tag Jobs in Set
Use the OrgSetEntry tag to add or replace organizational jobs in an organizational set. Used by: OrgSet Function Access Control Point: API.DataAccess Introduced in v5.0; last changed in v6.0

Syntax
Properties→ <OrgSetEntry EffectiveDate = Date (OrgId = Long) [AddEntries = String] [Name = String] [ReplaceEntries = String] > </OrgSetEntry>

Property Descriptions
AddEntries

Locations for new jobs
A semicolon-delimited list of full pathnames for jobs. The jobs you list will be added to the organizational set. Type: String Optional Introduced in v5.0; last changed in v5.1 EffectiveDate

Effective date
The date when the specified jobs become effective

550

Kronos Incorporated

OrgSetEntry Tag

Type: Date Required Introduced in v5.0; last changed in v5.0 Name

Name of the job set entry
Name of the job set entry. Type: String Optional Introduced in v6.0; last changed in v6.0 OrgId

ID for job set entry
A unique identifier for the organization set entry Type: Long Output only Introduced in v5.0; last changed in v5.0 ReplaceEntries

Replacement jobs in set
A semicolon-delimited list of full pathnames for jobs. The jobs you list will replace existing jobs in the organizational set. Type: String Optional Introduced in v5.0; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

551

Chapter 2

Workforce Timekeeper XML API Tag Definitions

OrgSetJob Tag Job in Organizational Job Set
The OrgSetJob tag describes a job that is defined in the organizational set. Used by: Org Set Function Access Control Point: API.DataAccess Introduced in v5.0; last changed in v5.0

Syntax
Properties→ <OrgSetJob (OrgJobId = String) (OrgJobName = String) > </OrgSetJob>

Property Descriptions
OrgJobId

Job Id
A unique identifier for a job in the organization Type: String Output only You must have Functional Access for Job Transfers. A node with this Id must exist in the organizational structure. Introduced in v5.0; last changed in v5.0 OrgJobName

Job name
The full path of the job in the organization

552

Kronos Incorporated

OrgSetJob Tag

Note: OrgJobName string matching is case-sensitive on a server that connects to an Oracle database. Type: String Output only Maximum length: 1000 characters You must have Functional Access for Job Transfers. A node with this Id must exist in the organizational structure. Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

553

Chapter 2

Workforce Timekeeper XML API Tag Definitions

OrgWorkAllocationEntry Tag Labor percentages for organizational map jobs
Use this tag to add or change the percentage for both direct labor and indirect labor for a job that is part of an organization map. Used by: OrgLocation Function Access Control Point: Organizational Maps Introduced in v5.1; last changed in v5.2

Syntax
Properties→ <OrgWorkAllocationEntry OrgWorkPct = Integer OrgWorkTypeName = String > </OrgWorkAllocationEntry>

Property Descriptions
OrgWorkPct

Percentage of work in a job of an organization map
Specify a percentage value for the type of work, either Direct Labor or Indirect Labor, in an organizational map job. The percentages for both Direct Labor and Indirect Labor must add up to 100 percent. Type: Integer Required between 0 and 100 Introduced in v5.2 OrgWorkTypeName

Type of work in the job of an organizational map

554

Kronos Incorporated

OrgWorkAllocationEntry Tag

Specify the type of work, Direct Labor or Indirect Labor, to assign a percentage value to. Type: String Required Sample values: "Direct work" or "Indirect work" Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

555

Chapter 2

Workforce Timekeeper XML API Tag Definitions

OvertimeApproval Tag Overtime Approval
The OvertimeApproval tag lets an individual approve overtime for an employee on one specified day. Use either the ApproveAll, ApproveSome, or ApproveNone action to approve the appropriate amount of overtime. Function Access Control Point: API.Timecard Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddComment" | "ApproveAll" | "ApproveNone" | "ApproveSome" Parameters→ None Properties→ <OvertimeApproval [AmountInTime = TimeDuration] [CommentText = String] Date = Date (EnteredOnDate = Date) (EnteredOnTime = Time) > (<Comments> <Comment>* </Comments>) <Employee> <CurrentUser> | <PersonIdentity>

556

Kronos Incorporated

OvertimeApproval Tag

</Employee> </OvertimeApproval>

Action Descriptions
AddComment Adds a comment along with the action taken. Return Value Type: None Required Properties: Employee, Date, CommentText, AmountInTime Access Control Point Name: Edit Introduced in v4 ApproveAll Approve all overtime for the specified day. Return Value Type: None Required Properties: Employee, Date Access Control Point Name: Edit Introduced in v4; last changed in v5.1 ApproveNone Does not approve any overtime requested or submitted for the specified day. Return Value Type: None Required Properties: Employee, Date Access Control Point Name: Edit Introduced in v4; last changed in v5.1 ApproveSome Approve only a portion of the overtime hours that the employee submitted or requested. Return Value Type: None Required Properties: Employee, Date, AmountInTime Access Control Point Name: Edit

Workforce Central Developers Toolkit Reference Guide—Timekeeping

557

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v4; last changed in v5.1

Property Descriptions
AmountInTime

Amount of approved overtime
This property is meaningful only when you use the ApproveSome action. Enter the number of hours to be approved. When used with the AddComments action, All or None can be specified, if appropriate. Type: TimeDuration Optional Must not be negative Introduced in v4; last changed in v5.1 Comments

Comments
The set of comments currently returned with this timekeeping item Type: Zero or more Comment tags Output Only Introduced in v4 CommentText

Comment text
A comment Type: String Optional Maximum length: 254 characters The comment must match exactly an applicable comment that already exists in the database. The string matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application.

558

Kronos Incorporated

OvertimeApproval Tag

Introduced in v4 Date

Date of overtime
The date for which the overtime hours are being approved Type: Date Required Key Introduced in v4 Employee

Employee
One employee for whom overtime hours are to be approved, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Required Key Must uniquely identify an existing and active employee Introduced in v4 EnteredOnDate

Date of the edit
The server date on which the edit is added to the database Type: Date Output Only Introduced in v4 EnteredOnTime

Time of the edit
The server time on which the edit is added to the database Type: Time Output Only

Workforce Central Developers Toolkit Reference Guide—Timekeeping

559

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v4

560

Kronos Incorporated

PasswordHistory Tag

PasswordHistory Tag Password History
The PasswordHistory tag returns an encrypted password for the specified date. Used by: User Function Access Control Point: API.Person Introduced in v4; last changed in v5.1

Syntax
Properties→ <PasswordHistory (EffectiveDateTime = DateTime) (Password = Password) > </PasswordHistory>

Property Descriptions
EffectiveDateTime

Effective date and time
The date and time when the password becomes effective Type: DateTime Output Only Introduced in v4 Password

Password
Encrypted password of the user account Type: Password Output Only Introduced in v4; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

561

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PatternElement Tag Schedule Pattern Element
The PatternElement tag describes a part of the schedule pattern that represents an employee's schedule for a day. Used by: SchedulePattern Function Access Control Point: API.Schedule Introduced in v4; last changed in v6.0

Syntax
Properties→ <PatternElement AmountInCurrency = Currency AmountInTime = TimeDuration PayCodeName = String ShiftCodeName = String (CommentText = String) DayNumber = Integer [DisplayTime = Time] > (<Comments> <Comment>* </Comments>) </PatternElement>

Property Descriptions
PayCodeName

Pay code for the day
The pay code allocated to that day. PayCodeName and ShiftCodeName are mutually exclusive; one is required. Type: String A pay code can require either AmountInCurrency or AmountInTime. Must be a valid pay code.

562

Kronos Incorporated

PatternElement Tag

Introduced in v4 ShiftCodeName

Shift code for the day
The shift code allocated to the specified day. PayCodeName and ShiftCodeName are mutually exclusive; one is required. Type: String You can find values in the Workforce Timekeeper user interface. Introduced in v4 AmountInCurrency

Amount of pay code, in currency
An amount expressed as a currency Only used if PayCodeName is specified and represents a monetary item. Type: Currency Must be greater than zero Introduced in v4 AmountInTime

Amount of pay code, in time
A pay code amount, expressed as a time duration Dependency: Only used if PayCodeName is specified and represents an hourly pay code. Type: TimeDuration Must be greater than zero Introduced in v4 Comments

Comments
User comments

Workforce Central Developers Toolkit Reference Guide—Timekeeping

563

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: Zero or more Comment tags Output only Introduced in v5.0 CommentText

Comment text
A text string that is returned Type: String Output only Maximum length: 254 characters Introduced in v5.0 DayNumber

Day number in the pattern
Specifies the day of the pattern Type: Integer Required Must be greater than zero Introduced in v4 DisplayTime

Time to display in the user interface
The time displayed in the user interface Type: Time Optional DisplayTime is required if a PayCodeName is specified Introduced in v4

Groups of Mutually Exclusive Properties

564

Kronos Incorporated

PatternElement Tag

AccrualAmount AccrualAmount Optional Group includes: AmountInCurrency, AmountInTime PatternElementCode A Schedule Pattern element is either a Shift or PayCode Required Group includes: PayCodeName, ShiftCodeName

Workforce Central Developers Toolkit Reference Guide—Timekeeping

565

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PayCode Tag Pay Code
The PayCode tag provides information about a pay code. You can use this tag to determine whether a user has permission to assign the pay code to himself/herself or to other employees. The PayCode and WSAPayCode tags refer to the same database object. Function Access Control Point: API.Timecard Introduced in v4; last changed in v4.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadAllPayCodes" Parameters→ None Properties→ <PayCode (ManagerAccessFlag = Boolean) (IsVisibleFlag = Boolean) (ProfessionalAccessFlag = Boolean) (ExcuseAbsenceFlag = Boolean) (IsCombinedFlag = Boolean) (IsCurrencyFlag = Boolean) (DisplayOrder = Integer) (PayCodeName = String) > </PayCode>

Action Descriptions

566

Kronos Incorporated

PayCode Tag

LoadAllPayCodes Returns a list of all pay codes. Return Value Type: Zero or more PayCode tags Required Properties: None Access Control Point Name: View Introduced in v4

Property Descriptions
DisplayOrder

Order to display pay codes in the user interface
If another tag returns a list of PayCode tags, this specifies the sort order of this tag in the list. Type: Integer Output Only Introduced in v4 ExcuseAbsenceFlag

Can credited amounts excuse an absence?
Indicates whether amounts credited to this pay code can excuse an absence Type: Boolean Output Only Enumerated value: True, False Introduced in v4 IsCombinedFlag

Is the pay code combined?
Indicates whether the pay code is combined Type: Boolean

Workforce Central Developers Toolkit Reference Guide—Timekeeping

567

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Output Only Enumerated value: True, False Introduced in v4 IsCurrencyFlag

Is the pay code in currency?
True if the pay code represents a monetary item. False if it represents an hourly pay code. Type: Boolean Output Only Enumerated value: True, False Introduced in v4 IsVisibleFlag

Can a user see the pay code?
Indicates whether the pay code is visible to the end user Type: Boolean Output Only Enumerated value: True, False Introduced in v4 ManagerAccessFlag

Can a manager access the pay code?
Indicates whether the pay code is accessible for manager functions Type: Boolean Output Only Enumerated value: True, False Introduced in v4

568

Kronos Incorporated

PayCode Tag

PayCodeName

Pay code
Name of the pay code Type: String Output Only Introduced in v4 ProfessionalAccessFlag

Can an employee access the pay code?
Indicates whether the pay code is accessible for professional functions Type: Boolean Output Only Enumerated value: True, False Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

569

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PayCodeEdit Tag Pay Code Edit
The PayCode Edit tag identifies a positive or negative amount that replaces a scheduled pay code edit. To add a value rather than replace one, use the NonCancellingPayCodeEdit tag. Function Access Control Point: API.Timecard Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddComment" | "AddOnly" | "Delete" Parameters→ AddOnly→ [AccrualOverride = Boolean] [allowAdHoc = Boolean] [EchoData = Boolean] Properties→ <PayCodeEdit ScheduleAmountType = String AmountInTimeOrCurrency = String OrgJobId = String OrgJobName = String [CommentText = String] (EnteredOnDate = Date) Date = Date (IsCurrencyFlag = Boolean) LaborAccountName = String [ManagerName = String]

570

Kronos Incorporated

PayCodeEdit Tag

[OverrideAccrualDays = Double] PayCodeName = String [StartTime = Time] (EnteredOnTime = Time) > [<Notes> <Note>* </Notes>] (<Comments> <Comment>* </Comments>) <Employee> <CurrentUser> | <PersonIdentity> </Employee> </PayCodeEdit>

Action Descriptions
AddComment Adds a comment to each pay code edit associated with the specified employee. Depending on the type of edit, you may need to specify LaborAccountName. Return Value Type: None Required Properties: AmountInTimeOrCurrency, CommentText, Date, Employee, PayCodeName Access Control Point Name: Edit Introduced in v4 AddOnly Adds a new pay code edit with the specified properties. Return Value Type: PayCodeEdit tag Required Properties: AmountInTimeOrCurrency, Date, Employee, PayCodeName Access Control Point Name: Edit Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

571

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Parameters Parameter Name AccrualOverride Description If the action results in an accrual warning, the warning is overridden when AccrualOverride=True. Optional Default value: False Specifies whether an ad hoc labor level is allowed. Optional Default value: False If True, the Response includes a copy of this tag. Optional Default value: False Additional information Introduced in v4

allowAdHoc

Introduced in v5.0; last changed in v5.0; deprecated in v5.0. Not used Introduced in v4

EchoData

Delete Marks for deletion all pay code edits for the employee with matching properties. Return Value Type: None Required Properties: AmountInTimeOrCurrency, Date, Employee, PayCodeName Access Control Point Name: Edit Introduced in v4

Property Descriptions
ScheduleAmountType

Amount, based on the employee schedule
ScheduleAmountType can be used instead of AmountInTimeCurrency to specify an amount based on the employee's schedule. The amount of time actually saved for the pay code edit will be calculated by the totalizer based on the employee's schedule for the specified day, or zero if there is no schedule for the day.

572

Kronos Incorporated

PayCodeEdit Tag

If ScheduleAmountType is calculated, the value is based on the number of hours that the employee is scheduled to work that day and whether the amount is a full day or half day amount. If specified, it must be one of the following: • • 1 to calculate the amount as a full-day scheduled amount. 2 to calculate the amount as a half-day scheduled amount

Type: String Maximum length: 1 character Enumerated value: 1 , 2 Introduced in v4.3; last changed in v5.0 AmountInTimeOrCurrency

Amount, in time or currency
The value associated with the corresponding pay code amount or totaled amount. This property is required for all request codes. Enter the value as follows: • • If PayCodeName holds money, specify an amount of money. If PayCodeName holds time, specify a duration of time.

Type: String Maximum length: 30 characters Introduced in v4; last changed in v5.0 OrgJobId

ID of job in organization
A unique identifier for a job in the organization Type: String Default value: Null Introduced in v5.0 OrgJobName

Job in the organization

Workforce Central Developers Toolkit Reference Guide—Timekeeping

573

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The name of the organizational job path for the employee whose pay code amount or totaled amount is being edited. It is optional when you add a pay code, historical edit, or totaled amount. It is not used if the punch applies to the employee's primary organizational job. Enter data for OrgJobName in the same format as it appears in the database. Note: OrgJobName string matching is case-sensitive on a server that connects to an Oracle database. Type: String Maximum length: 1000 characters You must have Functional Access for Job Transfers. A node with this Id must exist in the organizational structure. Default value: Null Introduced in v5.0 Comments

Comments
The set of comments currently returned with this timekeeping item Type: Zero or more Comment tags Output Only Introduced in v4 CommentText

Comment text
A text string that is attached to the pay code amount or totaled amount. CommentText is required when you add a comment. It is optional when adding a pay code edit, historical edit, or totaled amount. Type: String Optional Maximum length: 254 characters

574

Kronos Incorporated

PayCodeEdit Tag

Must match exactly an applicable comment that already exists in the database. The string matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application. Introduced in v4 Date

Date to which the edit applies
The date on which the current pay code edit becomes effective. Type: Date Required, Key Sample values: 8:00 Vacation on 4/2/2001 Introduced in v4 Employee

Employee
One employee, as specified in a PersonIdentity or CurrentUser tag, to be credited with the amount. Type: Either CurrentUser or PersonIdentity tag Required, Key Must uniquely identify an existing and active employee Introduced in v4; last changed in v5.0 EnteredOnDate

Date of the edit
The date on which the edit is added to the database Type: Date Output Only Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

575

Chapter 2

Workforce Timekeeper XML API Tag Definitions

EnteredOnTime

Time of the edit
The time at which the edit is added to the database Type: Time Output Only Introduced in v4 IsCurrencyFlag

Is the amount in currency or time?
True if the pay code represents a monetary item. False if it represents an hourly pay code. Type: Boolean Output Only Enumerated value: True, False Introduced in v4 LaborAccountName

Labor account
This is the name of the labor account of the employee whose pay code amount or totaled amount is being edited. LaborAccountName is optional when adding a pay code edit, historical edit, or totaled amount. It is required when the pay code edit, historical edit, or totaled amount being deleted or commented contained an explicit value. It need not be specified if the pay code amount or totaled amount applies to the employee's primary account. Enter data for labor accounts in the same format as they appear in the timekeeping database. If you have a seven-level labor account, specify a value for each labor level, using the following format: 101/202/303/404/504/603/702. Do not specify labor levels that are not changing. If any of the labor levels are the same as the employee's primary labor account, you can enter @H for those labor levels instead of entering the labor entry names.

576

Kronos Incorporated

PayCodeEdit Tag

Type: String Optional, Key Maximum length: 356 characters Default value: Primary account for the employee Introduced in v4; last changed in v5.0 ManagerName

Manager name
The name that replaces the user name in audit. Type: String Optional Maximum length: 70 characters Introduced in v5.0a Notes

Comment Notes
The list of notes for the comment to be created from comment text Type: Zero or more Note tags Optional Introduced in v6.0 OverrideAccrualDays

Override Accrual Days
A decimal number used to override the calculations made when determining the number of days (or fraction of a day) to be accrued as a result of this pay code edit. If specified, this value trumps all other calculated values. Note that this value must not be specified if the value of the PayCodeName attribute refers to a pay code of "money" type. Only used in the "AddOnly" action. Type: Double Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

577

Chapter 2

Workforce Timekeeper XML API Tag Definitions

A decimal number between 0 and 1 (inclusive) with, at most, 2 digits after the decimal point. Do not specify this attribute if the value of the PayCodeName attribute refers to a pay code of "money" type. Only used in the "AddOnly" action. Introduced in v6.0 PayCodeName

Pay code
Identifies the name of the pay code that is being applied to an amount associated with a pay code or to a historical amount. This is always required when importing a pay code edit or a historical edit. A pay code represents an amount in time or currency. It can represent one of the following units: • The hours accumulated during a pay period. A pay code that holds hours can contain worked hours (such as regular, overtime, or second shift) or unworked hours (such as vacation, sick, or personal). Money earned by employees during a pay period. For example, to allocate hours for J.D. Smith, who worked 8 regular and 4 overtime hours for a total of 12 hours, create two pay code edit entries: An entry with 8 regular hours An entry with 4 overtime hours

• • • •

Type: String Required, Key Maximum length: 50 characters Introduced in v4 StartTime

Start Time
StartTime is an optional field and should not be specified when: (1) PayCode is of "money" type or (2) The ScheduleAmountType value is specified. This is only applicable to the "AddOnly" action Type: Time

578

Kronos Incorporated

PayCodeEdit Tag

Optional The value must be able to be converted to a KTime object. If the specified PayCode is of a "money" type or if the ScheduleAmountType value is specified, then StartTime should simply not be specified. This is only applicable to the "AddOnly" action. Sample values: 1pm or 1:00pm or 13:00 Introduced in v6.0

Groups of Mutually Exclusive Properties
Amount in Time Properties that specify the amount of time to be assigned to a specified pay code Required Group includes: ScheduleAmountType, AmountInTimeOrCurrency OrgJob Organization Job Name or ID: If ID exists, Name is ignored. Optional Group includes: OrgJobId, OrgJobName

Workforce Central Developers Toolkit Reference Guide—Timekeeping

579

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PayCodeMove Tag Pay Code Move
The PayCodeMove tag moves an amount of time or money to from one pay code or labor account to another. Function Access Control Point: API.Timecard Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddComment" | "AddOnly" | "Delete" Parameters→ AddOnly→ [AccrualOverride = Boolean] [allowAdHoc = Boolean] [EchoData = Boolean] Properties→ <PayCodeMove OrgJobId = String OrgJobName = String AmountInTimeOrCurrency = String [CommentText = String] Date = Date (EnteredOnDate = Date) [LaborAccountName = String] FromLaborAccountName = String [ManagerName = String] PayCodeName = String FromPayCodeName = String

580

Kronos Incorporated

PayCodeMove Tag

(EnteredOnTime = Time) > [<Notes> <Note>* </Notes>] (<Comments> <Comment>* </Comments>) <Employee> <CurrentUser> | <PersonIdentity> </Employee> </PayCodeMove>

Action Descriptions
AddComment Adds a comment to the set of comments associated with the pay code move item. Return Value Type: None Required Properties: AmountInTimeOrCurrency, CommentText, Date, FromLaborAccountName, FromPayCodeName, PayCodeName Access Control Point Name: Edit Introduced in v4 AddOnly Adds a new pay code move item with the specified properties. Return Value Type: PayCodeMove tag Required Properties: AmountInTimeOrCurrency, Date, FromLaborAccountName, FromPayCodeName, PayCodeName Access Control Point Name: Edit Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

581

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Parameters Parameter Name AccrualOverride Description If the action results in an accrual warning, the warning is overridden when AccrualOverride=True. Optional Default value: False Specifies whether an ad hoc labor level is allowed. Optional Default value: False If True, the Response includes a copy of this tag Optional Default value: False Additional information Introduced in v4

allowAdHoc

Introduced in v5.0; last changed in v5.0; deprecated in v5.0. Not used Introduced in v4

EchoData

Delete Marks for deletion an existing pay code move item. Return Value Type: None Required Properties: AmountInTimeOrCurrency, Date, FromLaborAccountName, FromPayCodeName, PayCodeName Access Control Point Name: Edit Introduced in v4

Property Descriptions
OrgJobId

ID of job in organization
A unique identifier for a job in the organization Type: String Default value: Null

582

Kronos Incorporated

PayCodeMove Tag

Introduced in v5.0 OrgJobName

Job in the organization
The name of the organizational job path for the employee If specified, enter data for OrgJobName in the same format as it appears in the database. Note: OrgJobName string matching is case-sensitive on a server that connects to an Oracle database. Type: String Maximum length: 1000 characters You must have Functional Access for Job Transfers. A node with this Id must exist in the organizational structure. Default value: null Introduced in v5.0 AmountInTimeOrCurrency

Amount of pay code, in time or currency
Amount of pay code, expressed as a time duration or currency. Type: String Required, Key Maximum length: 30 characters Whether the value is expressed as a time duration or a currency depends on the pay code. Introduced in v4; last changed in v5.0 Comments

Comments
The set of comments currently returned with this timekeeping item Type: Zero or more Comment tags

Workforce Central Developers Toolkit Reference Guide—Timekeeping

583

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Output Only Introduced in v4 CommentText

Comment text
A comment Type: String Optional Maximum length: 254 characters Must match exactly an applicable comment that already exists in the database. The string matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application. Introduced in v4 Date

Date
The date on which the move is to be credited; for example, move 8:00 from pay code A to pay code B, effective on 4/1/2001 Type: Date Required, Key Introduced in v4 Employee

Employee
One employee whose pay codes are to be adjusted, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Required, Key Must uniquely identify an existing and active employee Introduced in v4

584

Kronos Incorporated

PayCodeMove Tag

EnteredOnDate

Date of the edit
The server date on which the move is entered in the database Type: Date Output Only Introduced in v4 EnteredOnTime

Time of the edit
The server time at which the move is entered in the database Type: Time Output Only Introduced in v4 FromLaborAccountName

Labor account that the amount is moved from
This is the name of the labor account of the employee from which a pay code amount or totaled amount is being moved. LaborAccountName is optional when adding a pay code edit, historical edit, or totaled amount. It is required when the pay code edit, historical edit, or totaled amount being deleted or commented contained an explicit value. This property need not be specified if the pay code amount or totaled amount applies to the employee's primary account. Enter data for labor accounts in the same format as they appear in the timekeeping database. If you have a seven-level labor account, specify a value for each labor level, using the following format: 101/202/303/404/504/603/702. Do not specify labor levels that are not changing. If any of the labor levels are the same as the employee's primary labor account, you can enter @H for those labor levels instead of entering the labor entry name. Type: String Optional, Key

Workforce Central Developers Toolkit Reference Guide—Timekeeping

585

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Maximum length: 356 characters Default value: Primary account for the employee Introduced in v4; last changed in v5.0 FromPayCodeName

Pay code that the amount is moved from
The pay code from which the amount is to be moved Type: String Required, Key Maximum length: 50 characters Introduced in v4 LaborAccountName

Labor account
This is the name of the labor account of the employee for whom a pay code amount or totaled amount is being applied. LaborAccountName is optional when adding a pay code edit, historical edit, or totaled amount. It is required when the pay code edit, historical edit, or totaled amount being deleted or commented contained an explicit value. This property need not be specified if the pay code amount or totaled amount applies to the employee's primary account. Enter data for labor accounts in the same format as they appear in the timekeeping database. If you have a seven-level labor account, specify a value for each labor level, using the following format: 101/202/303/404/504/603/702. Do not specify labor levels that are not changing. If any of the labor levels are the same as the employee's primary labor account, you can enter @H for those labor levels instead of entering the labor entry names. Type: String Optional Maximum length: 356 characters Default value: Primary account for the employee

586

Kronos Incorporated

PayCodeMove Tag

Introduced in v4; last changed in v5.0 ManagerName

Manager Name
The name to replace the user name in audit. Type: String Optional Maximum length: 70 characters Introduced in v5.0a Notes

Comment Notes
The list of notes for the comment to be created from comment text Type: Zero or more Note tags Optional Introduced in v6.0 PayCodeName

Pay code
The pay code to be credited with the moved amount Type: String Required, Key Maximum length: 50 characters Introduced in v4

Groups of Mutually Exclusive Properties
OrgJob Organization Job ID or Name: If ID exists, Name is ignored. Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

587

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Group includes: OrgJobId, OrgJobName

588

Kronos Incorporated

PayCodeProfile Tag

PayCodeProfile Tag Pay Code Profile
The PayCodeProfile tag returns information about valid PayCode profiles defined within the timekeeping system. A Pay Code is a category that the timekeeping system uses to organize time and money. Time pay codes accrue hours, while money pay codes accrue money. Note: To assign a pay code profile to a person, use the ManagerPayCodeName or ProfessionalPayCodeName property in the AccessAssignment tag. Function Access Control Point: API.Employee Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllPayCodeProfiles" | "LoadById" | "LoadPayCodesForProfileName" Parameters→ None Properties→ <PayCodeProfile [PayCodeProfileId = Integer] [PayCodeProfileName = String] > </PayCodeProfile>

Action Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

589

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Load Returns a pay code profile, based on PayCodeProfileName. Name should be valid Return Value Type: PayCodeProfile tag Required Properties: PayCodeProfileName Access Control Point Name: View Introduced in v4 LoadAllPayCodeProfiles Returns a list of all pay code profiles in the system. Return Value Type: Zero or more PayCodeProfile tags Required Properties: None Access Control Point Name: View Introduced in v4 LoadById Returns a pay code profile, based on PayCodeProfileId. ID must be valid Return Value Type: PayCodeProfile tag Required Properties: PayCodeProfileId Access Control Point Name: View Introduced in v4 LoadPayCodesForProfileName Returns all paycodes associated with the given profile name, based on PayCodeProfileName. Validates that the name is associated with a valid profile name. Return Value Type: Zero or more PayCode tags Required Properties: PayCodeProfileName Access Control Point Name: View Introduced in v5.1

590

Kronos Incorporated

PayCodeProfile Tag

Property Descriptions
PayCodeProfileId

Id of Pay code profile
Uniquely identifies the pay code data access profile in the database Type: Integer Optional Introduced in v4 PayCodeProfileName

Pay code profile name
The name for the common set of pay codes that can be accessed by a group of users, for example, All Pay Codes. Type: String Optional Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

591

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PayFromSchedule Tag Pay from Schedule
The PayFromSchedule tag identifies a period of time during which an employee can be paid from a predefined schedule. When the tag is used, the employee's timecard is populated with punches and pay code edits, based on the person's work schedule. Function Access Control Point: API.Timecard Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "Delete" Parameters→ None Properties→ <PayFromSchedule [CommentText = String] EndDate = Date StartDate = Date > <Employee> <PersonIdentity> </Employee> </PayFromSchedule>

Action Descriptions

592

Kronos Incorporated

PayFromSchedule Tag

AddOnly Adds a record to the timesheet that identifies an employee and a time period when pay is based on a schedule. The employee must exist. Return Value Type: None Required Properties: Employee, StartDate, EndDate Access Control Point Name: Edit Introduced in v4 Delete Marks all existing pay from schedule items for deletion for the specified employee and time span. Return Value Type: None Required Properties: Employee, StartDate, EndDate Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0

Property Descriptions
CommentText

Comment text
A comment Type: String Optional Maximum length: 254 characters Must match exactly an applicable comment that already exists in the database. The string matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application. Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

593

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Employee

Employee
One employee who is paid from a schedule, as specified in a PersonIdentity tag. Type: PersonIdentity tag Required Must uniquely identify an existing and active employee Introduced in v4 EndDate

End date
The end date of the schedule period Type: Date Required Introduced in v4 StartDate

Start date
The start date of the schedule period Type: Date Required Introduced in v4

594

Kronos Incorporated

PayFromScheduleStopEvent Tag

PayFromScheduleStopEvent Tag Stop Payment from Schedule
The PayFromScheduleStopEvent tag stops a Pay from Schedule payment from being posted for a specific date (for example, when an employee is absent). Function Access Control Point: API.Timecard Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "Delete" Parameters→ None Properties→ <PayFromScheduleStopEvent [CommentText = String] Date = Date > <Employee> <PersonIdentity> </Employee> </PayFromScheduleStopEvent>

Action Descriptions
AddOnly Adds a record to the timesheet to stop an employee from being paid according to the schedule when he or she is absent. Only one entry can exist for the given employee and date.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

595

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Return Value Type: None Required Properties: Employee, Date Access Control Point Name: Edit Introduced in v4 Delete Marks the record to stop an employee from being paid according to the schedule for deletion. The employee must exist Return Value Type: None Required Properties: Employee, Date Access Control Point Name: Edit Introduced in v5.0

Property Descriptions
CommentText

Comment text
A comment Type: String Optional Maximum length: 254 characters Must match exactly an applicable comment that already exists in the database. The string matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application. Introduced in v4 Date

Date of event

596

Kronos Incorporated

PayFromScheduleStopEvent Tag

The date when the event occurred employee that caused payment to be stopped. An example of such an event is an absence. Type: Date Required Introduced in v4 Employee

Employee
One employee, as specified in a PersonIdentity tag, who is paid from schedule and was absent. Type: PersonIdentity tag Required Must uniquely identify an existing and active employee Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

597

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PayRuleProfile Tag Pay Rule Profile
The PayRuleProfile tag provides information about existing pay rules. A pay rule contains general payroll rules, such as type of pay period (for example, weekly). A complete pay rule controls such items as the pay period length, the day divide, when punches are linked to schedules, when data collection devices accept and reject punches, which holidays give holiday credits, and the order in which hour types are processed. Function Access Control Point: API.Employee Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllPayRuleProfiles" | "LoadById" Parameters→ None Properties→ <PayRuleProfile [PayRuleProfileId = Integer] [PayRuleProfileName = String] > </PayRuleProfile>

Action Descriptions

598

Kronos Incorporated

PayRuleProfile Tag

Load Returns a pay rule profile, based on PayRuleProfileName. Return Value Type: PayRuleProfile tag Required Properties: PayRuleProfileName Access Control Point Name: View Introduced in v4 LoadAllPayRuleProfiles Returns a list of all pay rule profiles in the system. Return Value Type: Zero or more PayRuleProfile tags Required Properties: None Access Control Point Name: View Introduced in v4 LoadById Returns a pay rule profile, based on PayRuleProfileId. Return Value Type: PayRuleProfile tag Required Properties: PayRuleProfileId Access Control Point Name: View Introduced in v4

Property Descriptions
PayRuleProfileId

ID of pay rule profile
Uniquely identifies the pay rule in the system Type: Integer Optional Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

599

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PayRuleProfileName

Pay rule profile
The name for the common set of general payroll rules that apply to a group of employees Type: String Optional Sample values: Full Time Introduced in v4

600

Kronos Incorporated

PeriodTotals Tag

PeriodTotals Tag Period Totals
The PeriodTotals tag contains a summary of all hours and currency earned during a range of days, disbursed by labor account and pay code. The amount associated with each labor account and pay code pair is returned in a Total tag. Used by: Timesheet Function Access Control Point: API.Timecard Introduced in v4

Syntax
Properties→ <PeriodTotals (PeriodDateSpan = DateSpan) > (<Totals> <TotalSummary> </Totals>) </PeriodTotals>

Property Descriptions
PeriodDateSpan

Span of dates
The start and end dates separated by a dash for the specified period; that is, the period for which the totals apply. Type: DateSpan Output Only Sample values: 04/03/2001-04/09/2001 Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

601

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Totals

Totals
A list of totals for this date, broken out by labor account and pay code Type: TotalSummary tag Output Only The combination of pay code and labor account must be unique. Introduced in v4

602

Kronos Incorporated

Permission Tag

Permission Tag Permission
The Permission tag denotes an action and its associated access control point. This tag has no actions, but is accessed through the GetAllowedPermissions action of the AccessProfile tag. Function Access Control Point: API.AccessProfile Introduced in v4; last changed in v5.0

Syntax
Properties→ <Permission (AccessControlPointName = String) (ActionName = String) (SuiteProductName = String) (ScopeName = String) > </Permission>

Property Descriptions
AccessControlPointName

Access control point name
A control, such as access to the HyperFind function, that determines how a user can interact with a product feature Type: String Output Only Introduced in v4 ActionName

Action name
Action for which the permission has been granted: add, edit, delete, or view.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

603

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: String Output Only Introduced in v4 ScopeName

Scope of action
Scope that is associated with the action and permission type. Type: String Output Only Introduced in v4 SuiteProductName

Product name
Individual product that is protected by this access control point. Type: String Output Only Enumerated value: WFA, WFP, WTK, WAC, WFE, WFS, DCM, WRM, WMT, PLATFORM_SERVICES, EVENT_MGR, BGP, NOTIFICATION, REPORTS_ENGINE, WHR, WPR, WCT, TID, TA, M8M Introduced in v4

604

Kronos Incorporated

Person Tag

Person Tag Name and Employment Data
The Person tag defines name and employment information for an employee. Used by: HyperFindResult, PersonInformation Because several properties are required to define an employee, property validations are not done until the data is updated in the system. Function Access Control Point: API.Person Introduced in v4; last changed in v6.0

Syntax
Properties→ <Person [AccrualProfileName = String] [BaseWageHourly = Currency] [BirthDate = Date] (ManagerSignoffThruDateTime = Date) (PayrollLockoutThruDateTime = Date) [FirstName = String] (FullName = String) [HireDate = Date] [FingerRequiredFlag = Boolean] [LastName = String] [MiddleInitial = String] [FullTimePercentage = Long] [PersonNumber = String] [PhoneticFullName = String] [EmployeeStandardHours = Double] [FullTimeStandardHours = Double] [RomanizedFullName = String] [ShortName = String] > </Person>

Property Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

605

Chapter 2

Workforce Timekeeper XML API Tag Definitions

AccrualProfileName

Accrual profile
The accrual profile to be used for a person or group. An accrual profile can contain one or more accrual rules. Accrual profiles are assigned to similar groups of employees. For example, all full-time employees might have the same accrual profile. Type: String Optional Maximum length: 50 characters You can find values in the Workforce Timekeeper Setup Application. Sample values: VAC and Sick Only Introduced in v5.0; last changed in v5.1 BaseWageHourly

Base hourly wage
The base wage is the employee's hourly wage without any premium values (overtime, shift differential, and so on). Type: Currency Optional Maximum length: 15 characters If specified, this value must be greater than or equal to 0.0. Default value: 0.00 Introduced in v4; last changed in v5.2; deprecated in v5.0. Use this property in the BaseWageRateEntry tag instead BirthDate

Birth date
The person's date of birth

606

Kronos Incorporated

Person Tag

Type: Date Optional Must occur before the hire date when the hire date is also specified Introduced in v4 EmployeeStandardHours

Ratio - employee hours
The EmployeeStandardHours and FullTimeStandardHours properties define the full-time equivalency for a part-time employee, defining the equivalency as a ratio of the employee's scheduled hours to the hours in a standard work week. Full-time equivalency is used to determine the rate at which benefits accrue for an employee who is not scheduled to work a full standard work week. For example, suppose this employee is scheduled to work 30 hours, and a fulltime employee works 40 hours per week. You would enter a value of 30 for EmployeeStandardHours and a value of 40 for FullTimeStandardHours. You can alternatively specify the employee's full-time equivalency as the percentage of full-time hours that the employee is scheduled to work. To do this, use the FullTimePercentage property. If you enter a value for FullTimePercentage, do NOT enter a value for EmployeeStandardHours or FullTimeStandardHours. Type: Double Optional Maximum length: 15 characters EmployeeStandardHours must be greater than or equal to 0.0. If both EmployeeStandardHours and FullTimePercentage are specified, FullTimePercentage takes precedence. Introduced in v4; last changed in v5.1 FingerRequiredFlag

Is finger scan identification required?

Workforce Central Developers Toolkit Reference Guide—Timekeeping

607

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Indicates when a finger scan (biometric) entry is required for the person Type: Boolean Optional Default value: False Enumerated value: True, False Introduced in v5.0; last changed in v5.0 FirstName

First name
The person's first name. Type: String Optional Maximum length: 30 characters Introduced in v4 FullName

Full name
Name of the person. This name is usually listed in the browser. Type: String Output Only Maximum length: 64 characters This property is derived from other properties in the person tag. Introduced in v4 FullTimePercentage

Percentage of full-time hours
FullTimePercentage sets the full-time equivalency for a part-time employee, defining the equivalency as the percentage of full-time hours that the employee is scheduled to work. The full-time equivalency is used to determine the rate at

608

Kronos Incorporated

Person Tag

which benefits accrue for an employee who is not scheduled to work a full standard work week. For example, suppose this employee is scheduled to work 20 hours, and a fulltime employee works 40 hours per week. The full-time percentage for this person is therefore 50%. To use this property for a part-time employee, use an integer value between 1 and 100. You can alternatively specify the employee's full-time equivalency as a ratio of scheduled hours to standard hours. To do this, use the EmployeeStandardHours and FullTimeStandardHours properties. If you enter a value for EmployeeStandardHours and FullTimeStandardHours, do NOT enter a value for FullTimePercentage. Type: Long Optional Maximum length: 15 characters, including decimals It must be between 0 and 100. Default value: 100.0 Introduced in v4; last changed in v5.1 FullTimeStandardHours

Ratio - full time status
The EmployeeStandardHours and FullTimeStandardHours properties define the full-time equivalency for a part-time employee, defining the equivalency as a ratio of the employee's scheduled hours to the hours in a standard work week. Full-time equivalency is used to determine the rate at which benefits accrue for an employee who is not scheduled to work a full standard work week.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

609

Chapter 2

Workforce Timekeeper XML API Tag Definitions

For example, suppose this employee is scheduled to work 30 hours, and a fulltime employee works 40 hours per week. You would enter a value of 30 for EmployeeStandardHours and a value of 40 for FullTimeStandardHours. You can alternatively specify the employee's full-time equivalency as the percentage of full-time hours that the employee is scheduled to work. To do this, use the FullTimePercentage property. If you enter a value for FullTimePercentage, do NOT enter a value for EmployeeStandardHours or FullTimeStandardHours. Type: Double Optional Maximum length: 15 characters, including decimals This value is specified as part of the Employee to FullTime Standard Hours ratio. It must be greater than 0.0. Introduced in v4; last changed in v5.1 HireDate

Hire date
The date on which the person was hired. Type: Date Optional If you provide a value, it must be later than the birth date. Required: When adding a new employee. Default value: The date when the record for the new hire is imported. Introduced in v4; last changed in v5.0 LastName

Last name
The person's last name. A value for this column is required when adding a new person. Type: String

610

Kronos Incorporated

Person Tag

Optional Maximum length: 30 characters Introduced in v4 ManagerSignoffThruDateTime

Date of last manager signoff
Date of the last manager signoff Type: Date Output only Introduced in v5.0; last changed in v5.0 MiddleInitial

Middle initial
The person's middle initial Type: String Optional Maximum length: 1 character Introduced in v4 PayrollLockoutThruDateTime

Date of last payroll lockout
Date of the last payroll lockout Type: Date Output only Introduced in v5.0; last changed in v5.0 PersonNumber

Person number
Person number of the specified person. This property is used to set, change, or display the Person Number assignment.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

611

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: String Optional Maximum length: 15 characters This number must be unique regardless of whether the person is active, inactive, or terminated. Required: When creating a new person Introduced in v4; last changed in v5.0 PhoneticFullName

Phonetic Full Name
The Phonetic version of the person's full name. Type: String Optional Maximum length: 64 characters Introduced in v6.0 RomanizedFullName

Romanized Full Name
The Romanized version of the person's full name. Type: String Optional Maximum length: 64 characters Introduced in v6.0 ShortName

Short name for person
The name by which the person wants to be known. Type: String Optional

612

Kronos Incorporated

Person Tag

Maximum length: 20 characters Default value: The first 20 characters of the first name. Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

613

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PersonAccessAssignment Tag Access Assignment Data
The PersonAccessAssignment tag specifies an access assignment that is in effect for an employee as of the effective date. Used by: PersonInformation Function Access Control Point: API.Person Introduced in v5.0; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadPersonAccessAssignments" Parameters→ None Properties→ <PersonAccessAssignment [EffectiveDate = Date] [ExpirationDate = Date] [ProfessionalTransferOrganizationSetName = String] [ManagerTransferOrganizationSetName = String] [ManagerAccessOrganizationSetName = String] > <Identity> <CurrentUser> | <PersonIdentity> </Identity> [<Period> <TimeFramePeriod> </Period>] </PersonAccessAssignment>

614

Kronos Incorporated

PersonAccessAssignment Tag

Action Descriptions
LoadPersonAccessAssignments Returns information associated with person access assignments over the specified time period. If the period is not specified, the current date through January 1, 3000 is used. The Identity and Period information associated with the request are added to the item in the returned list. If there are no data for the person and time period, one list item is returned containing only the Identity and Period properties. The person must exist within the system and the user must have access to that person. Return Value Type: Zero or more PersonAccessAssignment tags Required Properties: Identity Optional Properties: Period Access Control Point Name: View Introduced in v5.0

Property Descriptions
EffectiveDate

Date when access becomes effective
The date the access assignment becomes effective for the person Type: Date Optional Must occur before the expiration date Default value: The current system date Introduced in v5.0 ExpirationDate

Expiration date for access
The date the person's access assignment expires

Workforce Central Developers Toolkit Reference Guide—Timekeeping

615

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: Date Optional Must occur after the effective date Default value: January 1, 3000 Introduced in v5.0 Identity

Identity
One person, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Optional Key Must uniquely identify a person. Introduced in v5.0 ManagerAccessOrganizationSetName

Organizational group
An organizational group that a manager can use. Type: String Optional Maximum length: 30 characters Default value: The Empty Organization Set Enumerated value: All Organizational Sets, Organizational Groups Introduced in v5.0; last changed in v5.0 ManagerTransferOrganizationSetName

Job transfer set - manager
A job transfer set that a manager can use. Type: String Optional

616

Kronos Incorporated

PersonAccessAssignment Tag

Maximum length: 30 characters Default value: The Empty Organization Set Enumerated value: All Organizational Sets, Job Transfer Sets Introduced in v5.0; last changed in v5.1 Period

Time period
The span of time associated with the person access assignments Type: TimeFramePeriod tag Optional Used for the LoadPersonAccessAssignments action Default value: From the current date until January 1, 3000 Introduced in v5.0 ProfessionalTransferOrganizationSetName

Job transfer set - employee
A job transfer set that an employee can use. Type: String Optional Maximum length: 30 characters Default value: The Empty Organization Set Enumerated value: All Organizational Sets, Job Transfer Sets Introduced in v5.0; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

617

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Personality Tag Personality Data
Use the Personality tag to add a new person to the system, delete an existing person from the system, or modify certain information about an existing person. Function Access Control Point: API.Person Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "Delete" | "DeleteOnly" | "Load" | "Update" | "UpdateOnly" Parameters→ None Properties→ <Personality [<WTKEmployeeData> <WTKEmployee> </WTKEmployeeData>] [<GDAPAssignments> <GDAPAssignment>* </GDAPAssignments>] <Identity> <CurrentUser> | <PersonIdentity> </Identity> [<JobAssignmentData> <JobAssignment>

618

Kronos Incorporated

Personality Tag

</JobAssignmentData>] [<PersonInformationData> <PersonInformation> </PersonInformationData>] [<Period> <TimeFramePeriod> </Period>] [<UserData> <User> </UserData>] </Personality>

Action Descriptions
AddOnly Adds a new person to the system. Return Value Type: None Required Properties: PersonInformationData Invalid Properties: Identity Access Control Point Name: Edit Introduced in v4 Delete Marks a person for deletion. Return Value Type: None Required Properties: Identity Access Control Point Name: Edit Introduced in v5.0 DeleteOnly Marks a person for deletion. Return Value Type: None Required Properties: Identity Access Control Point Name: Edit

Workforce Central Developers Toolkit Reference Guide—Timekeeping

619

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v4; last changed in v5.0; deprecated in v5.0 Load Returns a person's demographic, user, and employee information. Return Value Type: Personality tag Required Properties: Identity Access Control Point Name: View Introduced in v4 Update Adds information for a new person or updates an existing one. Return Value Type: None Required Properties: If Identity is not specified, PersonInformationData is required, and a new person is added. If Identity is specified, the record is updated or added, depending on whether it already exists. Access Control Point Name: Edit Introduced in v4 UpdateOnly Updates an existing person. Return Value Type: None Required Properties: Identity Access Control Point Name: Edit Introduced in v4

Property Descriptions
GDAPAssignments

Generic Data Access Profile Assignment List
Generic Data Access Profile Assignments for the person. Type: Zero or more GDAPAssignment tags Optional

620

Kronos Incorporated

Personality Tag

Introduced in v6.0 Identity

Identity
One person, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Optional Key Introduced in v4 JobAssignmentData

Job assignment data
The job assignment information for the person Type: JobAssignment tag Optional Introduced in v5.0 Period

Time period
A span of time that may or may not be associated with a person Type: TimeFramePeriod tag Optional Used for narrowing the effective date of the request Default value: From the current date until January 1, 3000 Introduced in v5.0; last changed in v5.0 PersonInformationData

Person data
The person information of the person Type: PersonInformation tag

Workforce Central Developers Toolkit Reference Guide—Timekeeping

621

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Required: When creating a new person Introduced in v4; last changed in v5.1 UserData

User data
The user information for the person Type: User tag Optional Introduced in v4 WTKEmployeeData

Employee data
Specifies the WTKEmployee information for the person Type: WTKEmployee tag Optional Introduced in v4; last changed in v5.0; deprecated in v5.0. Use the properties in the Person and JobAssignmentDetails tags.

622

Kronos Incorporated

PersonalOvertimeAssignment Tag

PersonalOvertimeAssignment Tag Overtime Assignment for a Person
The PersonalOvertimeAssignment tag specifies an overtime assignment within a range of dates for a person. It is used for importing data into the system. Function Access Control Point: API.Person Introduced in v5.0; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" Parameters→ None Properties→ <PersonalOvertimeAssignment [StopOvertimeFlag = Boolean] [EffectiveDate = Date] [ExpirationDate = Date] OvertimeLevel = Long OvertimeTypeName = String > <Identity> <CurrentUser> | <PersonIdentity> </Identity> [<PersonalOvertimeRuleData> <PersonalOvertimeRule> </PersonalOvertimeRuleData>] <Period> <TimeFramePeriod> </Period> </PersonalOvertimeAssignment>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

623

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Descriptions
Load Returns all personal overtime assignments for the specified person within the specified time period. If the period is not specified, the current date through January 1, 3000 is used. The Identity and Period information associated with the request are added to the item in the resulting list. If no data are found for the person and time period, the first item on the list contains only the Identity and Period properties. The person must exist within the system. Return Value Type: Zero or more PersonalOvertimeAssignment tags Required Properties: Identity Optional Properties: Period Access Control Point Name: View Introduced in v5.0

Property Descriptions
EffectiveDate

Effective date
The date when the personal overtime assignment becomes effective Type: Date Optional Must occur before the expiration date Default value: Current system date Introduced in v5.0 ExpirationDate

Expiration date
The date when the personal overtime assignment expires

624

Kronos Incorporated

PersonalOvertimeAssignment Tag

Type: Date Optional Must occur after the effective date Default value: January 1, 3000 Introduced in v5.0 Identity

Identity
One employee, as specified in a PersonIdentity or CurrentUser tag Type: Either CurrentUser or PersonIdentity tag Optional Key Must uniquely identify an existing and active employee. Only used for the Load action Introduced in v5.0 OvertimeLevel

Overtime level
The numeric position of the overtime rule within the sequence of rules. Type: Long Required Key Maximum length: 2 characters The value must be an integer greater than zero. Introduced in v5.0 OvertimeTypeName

Overtime type
The reset interval for the rule Type: String Required Key

Workforce Central Developers Toolkit Reference Guide—Timekeeping

625

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Maximum length: 30 characters Introduced in v5.0 Period

Time period
The specified time frame Type: TimeFramePeriod tag Optional Key Must evaluate to a span of time. Identity is used when the time frame requires association with a person. Used for the Load action Default value: January 1, 3000 Introduced in v5.0 PersonalOvertimeRuleData

Personal overtime rule
The personal overtime rule associated with the personal overtime assignment An overtime establishes the limits and reset methods for accumulating overtime hours. Type: PersonalOvertimeRule tag Optional Introduced in v5.0; last changed in v5.1 StopOvertimeFlag

Associate with job assignment?
Indicates whether this personal overtime assignment shall be associated with the job during the time span Type: Boolean Optional Enumerated value: True, False

626

Kronos Incorporated

PersonalOvertimeAssignment Tag

Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

627

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PersonalOvertimeLimit Tag Overtime Limit for a Person
The PersonalOvertimeLimit tag identifies personal overtime values that are assigned to a personal overtime rule. Used by: PersonalOvertimeRule Function Access Control Point: API.Person Introduced in v5.0; last changed in v5.0

Syntax
Properties→ <PersonalOvertimeLimit [MinimumAmount = TimeDuration] [Amount = TimeDuration] PersonalOvertimeAmountTypeName = String > </PersonalOvertimeLimit>

Property Descriptions
Amount

Time worked before overtime accrues
The amount of time before the overtime begins to accrue. This overrides the amount in the limit rule. Type: TimeDuration Optional Default value: null Introduced in v5.0; last changed in v5.0 MinimumAmount

Overtime worked before overtime rate starts

628

Kronos Incorporated

PersonalOvertimeLimit Tag

The amount of overtime time that must be worked before the overtime rate is applied Type: TimeDuration Optional Default value: null Introduced in v5.0 PersonalOvertimeAmountTypeName

Type of overtime amount
The type that is associated with the amounts. Type: String Required Key Maximum length: 30 characters Enumerated value: &DAILY, &WEEKLY, &PAYPERIOD, &BI_WEEKLY, &RANGE_OF_TIME, &SHIFT, &24HOUR_RULE, &NUMBER_OF_DAYS Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

629

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PersonalOvertimeRule Tag Overtime Rule for a Person
The PersonalOvertimeRule tag provides the amount information associated with a personal overtime assignment. An overtime rule establishes the limits and reset methods for accumulating overtime hours. When employees reach overtime goals within specified time periods, they start to earn overtime hours. There is always one personal overtime rule for each personal overtime assignment. Used by: PersonalOvertimeAssignment Function Access Control Point: API.Person Introduced in v5.0; last changed in v5.1

Syntax
Properties→ <PersonalOvertimeRule (PersonalOvertimeRuleDisplayName = String) [UseScheduleFlag = Boolean] > [<PersonalOvertimeLimits> <PersonalOvertimeLimit>* </PersonalOvertimeLimits>] </PersonalOvertimeRule>

Property Descriptions
PersonalOvertimeLimits

Personal overtime limits
The list of Personal Overtime Limit tags that are associated with the personal overtime rule Type: Zero or more PersonalOvertimeLimit tags Optional Introduced in v5.0

630

Kronos Incorporated

PersonalOvertimeRule Tag

PersonalOvertimeRuleDisplayName

Personal overtime rule
The name of a personal overtime rule used for an external user Type: String Output only Introduced in v5.0 UseScheduleFlag

Use schedule to determine overtime?
When true, the personal overtime rule uses the days in the schedule to determine when overtime is allowed. Type: Boolean Optional Enumerated value: True, False Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

631

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PersonAuthenticationType Tag Authentication Type
The PersonAuthenticationType tag contains information about an authentication type relative to a specific person. There is a finite set of authentication types recognized by the system and each person is either considered active or inactive with respect to each of them. A person should be active with a single authentication type at any given time. For the ActiveFlag property data is expected to be either boolean true or false. For the AuthenticationTypeName property data is expected to be one of the following types recognized by the system: Kronos, NT, LDAP, KRONOS_CUSTOM. Function Access Control Point: API.Person Introduced in v5.1; last changed in v5.1

Syntax
Properties→ <PersonAuthenticationType ActiveFlag = Boolean AuthenticationTypeName = String > </PersonAuthenticationType>

Property Descriptions
ActiveFlag

Is this auth type active for this person?
Indicates whether or not the specified Authentication Type is active or inactive with respect to the person. True means that this person will be authenticated in the manner specified in AuthenticationTypeName when they attempt to log on to the system. Type: Boolean

632

Kronos Incorporated

PersonAuthenticationType Tag

Required Sample values: true or false Introduced in v5.1 AuthenticationTypeName

Name or ID of Authentication Type
The name or id of the AuthenticationType being activated or inactivated for this person. Type: String Required Sample values: Kronos, NT, LDAP, KRONOS_CUSTOM or 1,2,3,4 Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

633

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PersonCertificationAssign Tag Certifications Assigned to Employees
The PersonCertificationAssign tag assigns one or more certifications to one or more employees. Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadAll" | "LoadCertificationAssignments" | "Update" Parameters→ None Properties→ <PersonCertificationAssign [PersonNumber = String] > [<PersonCertificationItems> <PersonCertificationItem>* </PersonCertificationItems>] [<Employees> <PersonIdentity>* </Employees>] [<Period> <TimeFramePeriod> </Period>] </PersonCertificationAssign>

Action Descriptions

634

Kronos Incorporated

PersonCertificationAssign Tag

LoadAll Returns all certification assignments for an employee. Return Value Type: PersonCertificationAssign tag Required Properties: PersonNumber Access Control Point Name: View Introduced in v5.0; last changed in v5.0 LoadCertificationAssignments Returns certification assignments for an employee for the specified timeframe. If Period is not specified, this action returns all assignments from the current date to January 1, 3000 Return Value Type: PersonCertificationAssign tag Required Properties: PersonNumber Optional Properties: Period Access Control Point Name: View Introduced in v5.0; last changed in v5.0 Update Assigns certifications to one or more employees. Return Value Type: None Required Properties: PersonCertificationItems, Employees Access Control Point Name: Edit Introduced in v5.0

Property Descriptions
Employees

Employees
One or more employees, as specified in one or more PersonIdentity tags, for whom the certification is assigned. Type: Zero or more PersonIdentity tags

Workforce Central Developers Toolkit Reference Guide—Timekeeping

635

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Each employee must have a WFS license. Introduced in v5.0 Period

Time period
The time span when the assignment is in effect. Type: TimeFramePeriod tag Optional Introduced in v5.0; last changed in v5.0 PersonCertificationItems

Certification items
The certification items that are assigned to the employees specified in Employees. Type: Zero or more PersonCertificationItem tags Optional Introduced in v5.0 PersonNumber

Person number
The person number of the person about whom information is returned Type: String Optional Maximum length: 15 characters Introduced in v5.0

636

Kronos Incorporated

PersonCertificationItem Tag

PersonCertificationItem Tag Certification Assigned to Employees
The PersonCertificationItem tag identifies a certification that can be assigned to one or more people. Used by: PersonCertificationAssign Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.0

Syntax
Properties→ <PersonCertificationItem Name = String [CertificationNumber = String] EffectiveDate = Date ExpirationDate = Date [OldCertificationNumber = String] [OldEffectiveDate = Date] [OldExpirationDate = Date] > </PersonCertificationItem>

Property Descriptions
CertificationNumber

Certification number
Certification number Type: String Optional Maximum length: 12 characters Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

637

Chapter 2

Workforce Timekeeper XML API Tag Definitions

EffectiveDate

Effective date
The date when the certification assignment becomes effective for the employee previously specified Type: Date Required Introduced in v5.0; last changed in v5.0 ExpirationDate

Expiration date
The date when the assignment of this certification to the previously specified employee expires Type: Date Required Introduced in v5.0; last changed in v5.0 Name

Certification name
The unique name of a legal certification Type: String Required Maximum length: 40 characters You can find values in the Workforce Timekeeper user interface. Introduced in v5.0; last changed in v5.0 OldCertificationNumber

Old certification number
The old certification number is the number that was previously assigned to a person.

638

Kronos Incorporated

PersonCertificationItem Tag

Dependency: If any one of OldCertificationNumber, OldEffectiveDate, or OldExpirationDate is specified, the other two must also be specified. To update a certification number, you must specify the certification number and these three properties. Type: String Optional Maximum length: 12 characters Introduced in v5.0; last changed in v5.0 OldEffectiveDate

Old effective date
The old effective date is the one that was previously specified for a person certification assignment. Dependency: If any one of OldCertificationNumber, OldEffectiveDate, or OldExpirationDate is specified, the other two must also be specified. Type: Date Optional Introduced in v5.0; last changed in v5.0 OldExpirationDate

Old expiration date
The old expiration date is the one that was previously specified for a person certification assignment. Dependency: If any one of OldCertificationNumber, OldEffectiveDate, or OldExpirationDate is specified, the other two must also be specified. Type: Date Optional Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

639

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PersonIdentity Tag Person Identity Data
The PersonIdentity tag identifies one or more people. It is used by many import transactions. Function Access Control Point: API.Common Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadIdentities" Parameters→ None Properties→ <PersonIdentity BadgeNumber = String EmployeeKey = Long PersonKey = Long <PersonIdentityList> <CurrentUser> | <PersonIdentity> </PersonIdentityList> PersonNumber = String UserKey = Long [<FilterQueryName> <HyperFindQuery> </FilterQueryName>] </PersonIdentity>

Action Descriptions

640

Kronos Incorporated

PersonIdentity Tag

LoadIdentities Returns the person number, badge number, and database keys for the specified person. The user must specify exactly one of BadgeNumber, PersonNumber, PersonKey, EmployeeKey, or UserKey. Return Value Type: PersonIdentity tag Required Properties: PersonNumber Optional Properties: None Access Control Point Name: View Introduced in v4; last changed in v5.1

Property Descriptions
BadgeNumber

Badge number
Contains an employee badge number that is assigned to the employee. The system can be configured to allow multiple badges for employees. Specify whether to allow multiple badge assignments in System Configuration -> System Settings -> Global Values -> global.BadgeAssignment.allowsOverlap = Yes If an employee is assigned multiple badge numbers, each badge number and associated information is added in a separate request. If you want to remove a badge number, remove all existing badge numbers. Then reassign the valid number that you want to keep. A member of the Identifier group. If you are importing data from another system, this may be a convenient identifier to use. Type: String Maximum length: 25 characters Must be unique for the specified date span. Validation is done after a person is associated with a badge, using the PersonInformation tag. The effective date is the date of the server Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

641

Chapter 2

Workforce Timekeeper XML API Tag Definitions

EmployeeKey

Employee database key
The internal database key that identifies the employee. As an internal number, it is not likely to be widely used for functions such as import transactions. Type: Long Maximum value = 2,147,488, 848 Must identify just one person A member of the Identifier group Introduced in v4; last changed in v5.0 PersonKey

Person database key
The internal database key that identifies the person. As an internal number, it is not likely to be widely used for functions such as import transactions. Type: Long Maximum value = 2,147,488, 848 Must identify just one person A member of the Identifier group Introduced in v4; last changed in v5.0 PersonIdentityList

Person identity list
One or more PersonIdentity and CurrentUser tags Type: Either CurrentUser or PersonIdentity tag Each person in the list is validated separately. PersonIdentityList is a member of the Identifier group. However, you may not use it if you are importing data. Introduced in v4

642

Kronos Incorporated

PersonIdentity Tag

PersonNumber

Person number
The person's identification number. A member of the Identifier group. If you are importing data from another system, this may be a convenient identifier to use. Type: String Maximum length: 15 characters Non-numeric values are permitted. Introduced in v4; last changed in v5.0 UserKey

User database key
The internal database key that identifies the user. As an internal number, it is not likely to be widely used for functions such as import transactions. Type: Long Maximum value = 2,147,488, 848 Must identify just one person A member of the Identifier group Introduced in v4; last changed in v5.0 FilterQueryName

Query name
Specifies the name of an existing query that identifies one or more people. Information is returned in the HyperFindResult tag. Note: When importing person-related information that involves making changes to an inactive or terminated employee's status or information, specify the name of a hyperfind query that includes all employees. Type: HyperFindQuery tag Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

643

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The default value, All Home, only returns Active employees. Default value: All Home Introduced in v5.0; last changed in v5.0

Groups of Mutually Exclusive Properties
Identifier Only one member of the Identifier group can be specified. Identifier and FilterQueryName are mutually exclusive. Outstanding: Identifier usage constraint is specified as Required. But Identifier and FilterQueryName are mutually exclusive. Therefore, Identifier should not be Required. Required Group includes: BadgeNumber, EmployeeKey, PersonKey, PersonIdentityList, PersonNumber, UserKey

644

Kronos Incorporated

PersonInformation Tag

PersonInformation Tag Person Information and Data
The PersonInformation tag contains demographic, employment, and system information. Used by: Personality See the following tags for validation rules: • • • • • • • • • • • • • • • • AccessAssignment BadgeAssignment CustomData CustomDate EmailAddress EmploymentStatus ExpectedHours HomeAccount PersonIdentity Person PersonAccessAssignment PersonLicenseType PostalAddress Supervisor TelephoneNumber UserAccountStatus

Function Access Control Point: API.Person Introduced in v4; last changed in v5.1

Syntax
Request→

Workforce Central Developers Toolkit Reference Guide—Timekeeping

645

Chapter 2

Workforce Timekeeper XML API Tag Definitions

<Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllBadgeAssignments" | "LoadAllEmploymentStatus" | "LoadAllHomeAccounts" | "LoadAllUserAccountStatus" Parameters→ None Properties→ <PersonInformation [<PersonAccessAssignments> <PersonAccessAssignment>* </PersonAccessAssignments>] [<AccessAssignmentData> <AccessAssignment> </AccessAssignmentData>] [<CustomDataList> <CustomData>* </CustomDataList>] [<PersonAuthenticationTypes> <PersonAuthenticationType>* </PersonAuthenticationTypes>] [<BadgeAssignments> <BadgeAssignment>* </BadgeAssignments>] [<EMailAddresses> <EmailAddress>* </EMailAddresses>] [<EmploymentStatusList> <EmploymentStatus>* </EmploymentStatusList>] <Identity> <CurrentUser> | <PersonIdentity> </Identity> [<HomeAccounts> <HomeAccount>* </HomeAccounts>]

646

Kronos Incorporated

PersonInformation Tag

[<PersonData> <Person> </PersonData>] [<CustomDates> <CustomDate>* </CustomDates>] [<PostalAddresses> <PostalAddress>* </PostalAddresses>] [<ExpectedHoursList> <ExpectedHours>* </ExpectedHoursList>] [<PersonLicenseTypes> <PersonLicenseType>* </PersonLicenseTypes>] [<SupervisorData> <Supervisor> </SupervisorData>] [<TelephoneNumbers> <TelephoneNumber>* </TelephoneNumbers>] [<UserAccountStatusList> <UserAccountStatus>* </UserAccountStatusList>] </PersonInformation>

Action Descriptions
Load Returns all demographic, employment, and system information for the specified person. Return Value Type: PersonInformation tag Required Properties: Identity Access Control Point Name: View Introduced in v4 LoadAllBadgeAssignments Returns all badge assignments for the specified person. Return Value Type: Zero or more BadgeAssignment tags

Workforce Central Developers Toolkit Reference Guide—Timekeeping

647

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required Properties: Identity Access Control Point Name: View Introduced in v4; last changed in v5.0; deprecated in v5.0 LoadAllEmploymentStatus Returns all employment statuses for the specified person. Return Value Type: Zero or more EmploymentStatus tags Required Properties: Identity Access Control Point Name: View Introduced in v4; last changed in v5.0; deprecated in v5.0 LoadAllHomeAccounts Returns all home accounts for the specified person. The home account shall be the derived account (resulting from the combination of the Primary Job and Primary Labor Account) for the specified time frame. Return Value Type: Zero or more HomeAccount tags Required Properties: Identity Access Control Point Name: View Introduced in v4; last changed in v5.0; deprecated in v5.0 LoadAllUserAccountStatus Returns all user account statuses for the specified person. Return Value Type: Zero or more UserAccountStatus tags Required Properties: Identity Access Control Point Name: View Introduced in v4; last changed in v5.0; deprecated in v5.0

Property Descriptions
AccessAssignmentData

Access rights
A set of access rights and preferences

648

Kronos Incorporated

PersonInformation Tag

Type: AccessAssignment tag Optional Introduced in v4 BadgeAssignments

Badge assignments
One or more badge numbers and associated time frames Type: Zero or more BadgeAssignment tags Optional Introduced in v4 CustomDataList

Additional information
One or more sets of information for site-specified data categories Type: Zero or more CustomData tags Optional Introduced in v4 CustomDates

Person dates
One or more sets of date type information for site-specified date categories that can be assigned to a person Type: Zero or more CustomDate tags Optional Introduced in v4 EMailAddresses

E-mail addresses
Specifies the person's e-mail address. Type: Zero or more EmailAddress tags

Workforce Central Developers Toolkit Reference Guide—Timekeeping

649

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Introduced in v4; last changed in v5.1 EmploymentStatusList

Employment statuses
The employment statuses for the specified time frames Type: Zero or more EmploymentStatus tags Optional Introduced in v4 ExpectedHoursList

Standard hours
The number of hours for the specified time period types Type: Zero or more ExpectedHours tags Optional Introduced in v4 HomeAccounts

Labor accounts
Specifies labor accounts assigned for the specified time frames. When specified within and AddOnly, Update, or UpdateOnly action, the values within this tag represent the labor accounts assigned to the person over the specified time frame. When resulting from the Load action, the home account shall be the derived account (resulting from the combination of the Primary Job and Primary Labor Account) for the specified time frame. Type: Zero or more HomeAccount tags Optional Introduced in v4; last changed in v5.0; deprecated in v5.0. Use the PrimaryLaborAccount tag to assign labor accounts.

650

Kronos Incorporated

PersonInformation Tag

Identity

Identity
One person, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Required Key Must uniquely identify an existing and active employee Introduced in v4 PersonAccessAssignments

Access assignment dates
The access assignments for the person for the specified time frames Type: Zero or more PersonAccessAssignment tags Optional Introduced in v5.0 PersonAuthenticationTypes

Authentication Types
The list of one or more authentication types, and the status (either active or inactive) for each type, for the current person. Only one authentication type should be active at a given time for each person. The authentication types include the following: Kronos, NT, LDAP, KRONOS_CUSTOM. Type: Zero or more PersonAuthenticationType tags Optional Default value: Kronos Introduced in v5.1 PersonData

Person data
Basic name and employment information for a person

Workforce Central Developers Toolkit Reference Guide—Timekeeping

651

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: Person tag Optional Required: When creating a new person Introduced in v4 PersonLicenseTypes

Status of licenses
The licenses for a specific person. Type: Zero or more PersonLicenseType tags Optional Introduced in v4; last changed in v5.1 PostalAddresses

Postal addresses
Postal addresses for the specified address types Type: Zero or more PostalAddress tags Optional Introduced in v4 SupervisorData

Supervisor data
The person who is logically defined as this person's supervisor Type: Supervisor tag Optional Introduced in v4; last changed in v5.0; deprecated in v5.0. Use the JobAssignmentDetails tag to assign a supervisor. TelephoneNumbers

Telephone numbers
The telephone numbers for the given telephone number types

652

Kronos Incorporated

PersonInformation Tag

Type: Zero or more TelephoneNumber tags Optional Introduced in v4 UserAccountStatusList

User account statuses
The user account statuses for the specified time frames Type: Zero or more UserAccountStatus tags Optional Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

653

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PersonLicenseType Tag License that is Assigned to a Person
The PersonLicenseType tag contains information about the license assigned to a person. Used by: PersonInformation Function Access Control Point: API.Person Introduced in v4; last changed in v5.0

Syntax
Properties→ <PersonLicenseType ActiveFlag = Boolean LicenseTypeName = String > </PersonLicenseType>

Property Descriptions
ActiveFlag

Is the license active?
Specifies the state of the license. True if the license is active for the person. Type: Boolean Required Enumerated value: True, False Introduced in v4 LicenseTypeName

Type of license
The name or the Id of the license type. There are nine valid licenses, but not all are assignable to employees

654

Kronos Incorporated

PersonLicenseType Tag

The following license types can be assigned to employees: • • • • • 1 or Workforce_Timekeeper_Employee 2 or Workforce_Professional_ Employee 3 or Workforce_Manager 5 or Workforce_Activities 9 or Workforce_Scheduler

Type: String Required Key Maximum length: 2 characters Specify @ to make no change to the existing license type. Enumerated value: @, 1, 2, 3, 5, 9 Introduced in v4; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

655

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PersonShiftTemplateAssignment Tag Shift Template Profile Assigned to Person
The PersonShiftTemplateAssignment tag associates a shift template profile with a person. Function Access Control Point: API.Schedule Introduced in v5.1Beta; last changed in v5.0a

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "Update" Parameters→ None Properties→ <PersonShiftTemplateAssignment ShiftTemplateProfileName = String > <Employee> <PersonIdentity> </Employee> </PersonShiftTemplateAssignment>

Action Descriptions
Load Returns the name of the shift template for the specified employee. Return Value Type: PersonShiftTemplateAssignment tag Required Properties: Employee

656

Kronos Incorporated

PersonShiftTemplateAssignment Tag

Access Control Point Name: View Introduced in v5.1Beta Update Assigns a specified shift template to a specified employee. Taken together, the shift template and employee must be unique in the system. Return Value Type: None Required Properties: Employee, ShiftTemplateProfileName Access Control Point Name: Edit Introduced in v5.1Beta

Property Descriptions
Employee

Employee
One employee, as specified in a PersonIdentity tag Type: PersonIdentity tag Required Key Must uniquely identify an existing and active employee Introduced in v5.1Beta; last changed in v5.0a ShiftTemplateProfileName

Shift template profile name
The name of a shift code profile name Type: String Optional Key Introduced in v5.1Beta

Workforce Central Developers Toolkit Reference Guide—Timekeeping

657

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PersonSkillAssign Tag Skills Assigned to Employees
The PersonSkillAssign tag assigns one or more skills to one or more employees for a specific period of time. Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadAll" | "LoadSkillAssignments" | "Update" Parameters→ None Properties→ <PersonSkillAssign [PersonNumber = String] > [<Employees> <PersonIdentity>* </Employees>] [<PersonSkillItems> <PersonSkillItem>* </PersonSkillItems>] [<Period> <TimeFramePeriod> </Period>] </PersonSkillAssign>

Action Descriptions

658

Kronos Incorporated

PersonSkillAssign Tag

LoadAll Returns all skill assignments for an employee. Return Value Type: PersonSkillAssign tag Required Properties: PersonNumber Access Control Point Name: View Introduced in v5.0; last changed in v5.0 LoadSkillAssignments Returns skill assignments for an employee for the specified timeframe. Return Value Type: PersonSkillAssign tag Required Properties: PersonNumber Access Control Point Name: View Introduced in v5.0; last changed in v5.0 Update Assigns skills to one or more employees. Return Value Type: None Required Properties: PersonSkillItems, Employees Access Control Point Name: Edit Introduced in v5.0

Property Descriptions
Employees

Employees
One or more people, as specified in one or more PersonIdentity tags. The skills that are specified in PersonSkillItems are assigned to this list of people. Type: Zero or more PersonIdentity tags Optional Each employee must have a WFS license. Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

659

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Period

Time period
The span of time during which the skill assignments are in effect for the specified employees. Type: TimeFramePeriod tag Optional Introduced in v5.0 PersonNumber

Person number
The person number of a person about whom information is returned. Type: String Optional Maximum length: 15 characters Introduced in v5.0 PersonSkillItems

Skill items assigned to employees
The skill items that are assigned to the employees specified in Employees. Type: Zero or more PersonSkillItem tags Optional Introduced in v5.0

660

Kronos Incorporated

PersonSkillItem Tag

PersonSkillItem Tag Skill that can be assigned
The PersonSkillItem tag contains a skill that can be assigned to one or more employees. Used by: PersonSkillAssign Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.2

Syntax
Properties→ <PersonSkillItem [EffectiveDate = Date] (ExpirationDate = Date) [IsActive = Boolean] Name = String > </PersonSkillItem>

Property Descriptions
EffectiveDate

Effective date
The date when the skill becomes available for assignment Type: Date Optional Introduced in v5.0 ExpirationDate

Expiration date
The date when the skill will no longer be available for assignment Type: Date

Workforce Central Developers Toolkit Reference Guide—Timekeeping

661

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Output only Introduced in v5.0; last changed in v5.0 IsActive

Is the skill active?
Specifies whether the skill is active Type: Boolean Optional Enumerated value: True, False Introduced in v5.0 Name

Skill name
The name of a skill Type: String Required Maximum length: 40 characters You can see the list of existing skills in the user interface. Introduced in v5.0; last changed in v5.0

662

Kronos Incorporated

PostalAddress Tag

PostalAddress Tag Postal Address
The PostalAddress tag specifies address elements for a specified address type. Used by: PersonInformation Function Access Control Point: API.Person Introduced in v4; last changed in v5.0

Syntax
Properties→ <PostalAddress ContactTypeName = String [City = String] [Country = String] [State = String] [Street = String] [PostalCode = String] > </PostalAddress>

Property Descriptions
City

City
The city or town portion of the person's address Type: String Optional Maximum length: 25 characters Introduced in v4 ContactTypeName

Category of the contact

Workforce Central Developers Toolkit Reference Guide—Timekeeping

663

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The name of the contact category Type: String Required Key Maximum length: 30 characters Introduced in v4 Country

Country
The country portion of the person's address Type: String Optional Maximum length: 25 characters Introduced in v4 PostalCode

Zip code
The postal code portion of the person's address Type: String Optional Maximum length: 25 characters Introduced in v4 State

State/Province
The state or province of the person's address Type: String Optional Maximum length: 25 characters Introduced in v4; last changed in v5.0

664

Kronos Incorporated

PostalAddress Tag

Street

Street
The numerical and street name portion of the person's address Type: String Optional Maximum length: 100 characters Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

665

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PreferenceProfile Tag Display Profile
The PreferenceProfile tag provides information about valid Preference Profiles defined within the timekeeping system. The display profile determines the information that the system displays to a user (for example, the HyperFinds that appear on the navigation bar). Function Access Control Point: API.Employee Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllPreferenceProfiles" | "LoadById" Parameters→ None Properties→ <PreferenceProfile PreferenceProfileName = String [PreferenceProfileId = Integer] > </PreferenceProfile>

Action Descriptions
Load Returns a preference profile, based on PreferenceProfileName. Name should be valid

666

Kronos Incorporated

PreferenceProfile Tag

Return Value Type: PreferenceProfile tag Required Properties: PreferenceProfileName Access Control Point Name: View Introduced in v4; last changed in v5.1 LoadAllPreferenceProfiles Returns all preference profiles in the system. Return Value Type: Zero or more PreferenceProfile tags Required Properties: None Access Control Point Name: View Introduced in v4 LoadById Returns a preference profile, based on PreferenceProfileId. Return Value Type: PreferenceProfile tag Required Properties: PreferenceProfileId Access Control Point Name: View Introduced in v4

Property Descriptions
PreferenceProfileId

Id of display profile
Uniquely identifies the preference profile in the database Type: Integer Optional Introduced in v4 PreferenceProfileName

Display profile name

Workforce Central Developers Toolkit Reference Guide—Timekeeping

667

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The name for the common set of display preferences applying to a group of users. For example, Tuesday Manager. It includes the time formats and the display profile for managers. Type: String Required Introduced in v4

668

Kronos Incorporated

PrimaryLaborAccount Tag

PrimaryLaborAccount Tag Primary Labor Account
The PrimaryLaborAccount tag identifies the labor account and primary organization job for a person's job assignment within a range of dates. If organizational maps are in use, the primary account is comprised of a primary job and a primary labor account. For those whose organizations do not use jobs, the primary account is comprised solely of a primary labor account. Used by: JobAssignment Function Access Control Point: API.Person Introduced in v5.0; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadPrimaryLaborAccounts" Parameters→ None Properties→ <PrimaryLaborAccount [EffectiveDate = Date] [ExpirationDate = Date] [LaborAccountName = String] [OrganizationPath = String] > <Identity> <CurrentUser> | <PersonIdentity> </Identity> [<Period> <TimeFramePeriod>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

669

Chapter 2

Workforce Timekeeper XML API Tag Definitions

</Period>] </PrimaryLaborAccount>

Action Descriptions
LoadPrimaryLaborAccounts Loads information associated with the primary labor account for a specified person over a specified period. If the period is not specified, the current date through January 1, 3000 is used. The Identity and Period information associated with the request is added to the item in the list. If no data is found, just the Identity and Period properties are returned. Return Value Type: Zero or more PrimaryLaborAccount tags Required Properties: Identity Optional Properties: Period Access Control Point Name: View Introduced in v5.0; last changed in v5.0

Property Descriptions
EffectiveDate

Effective date
The date when the primary labor account becomes effective Type: Date Optional Must occur before the expiration date Default value: Current date Introduced in v5.0 ExpirationDate

Expiration date

670

Kronos Incorporated

PrimaryLaborAccount Tag

The date when the primary labor account expires Type: Date Optional Must occur after the effective date Default value: January 1, 3000 Introduced in v5.0 Identity

Identity
One person, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Optional Key Must uniquely identify a person Introduced in v5.0; last changed in v5.0 LaborAccountName

Labor account
The name of the employee's primary labor account. Type: String Optional Maximum length: 356 characters Required for an employee's primary labor account name. You can find values in the Workforce Timekeeper user interface. Sample values: The following is an example of a primary account name (depending on how labor levels and accounts are defined in your system): 112/222/332/401/501/601/701. You can use shorthand for the primary labor account in any labor account entry if you are also importing an organizational path.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

671

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.0 OrganizationPath

Primary job in the organization
The primary job information. Dependency: This value is required only to import a Scheduling Employee. Enter values in the same format as they appear in the database. String matching is case-sensitive on a server that connects to an Oracle database. Note: The labor level entries within a labor account cannot overlap with the organization-derived account. For example, in the labor account: 101//////701, the entry 101 overlaps with Organization in the organization-derived account Organization/Hospitals/Hosp A/Floor 1/ER/RN2. The combining of an imported labor account and an organizational job pathderived account must result in a fully qualified labor account. For example, the labor account /////// and organization-derived account Organization/Hospitals/ Hosp A/Floor 1/ER/RN2 cannot result in a fully qualified labor account, because the organization-derived account has only six labor level entries, not seven labor level entries. Type: String Optional Maximum length: 1000 characters When shorthand notation is used, the person's current primary account must have a primary organization assigned. Required: For any person who has a scheduler license Introduced in v5.0 Period

Time period
The period of time associated with the primary account Type: TimeFramePeriod tag

672

Kronos Incorporated

PrimaryLaborAccount Tag

Optional Identity is used if a person is required in association with the time frame. Used for the LoadPrimaryLaborAccounts action Default value: From the current date until January 1, 3000 Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

673

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Procedure Tag Procedure
A procedure represents a PSE engine process. Function Access Control Point: Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Add" | "AddOnly" | "Delete" | "DeleteOnly" | "Retrieve" | "RetrieveAll" | "RetrieveAllForUpdate" | "RetrieveAllNames" | "RetrieveForUpdate" | "Update" | "UpdateOnly" Parameters→ None Properties→ <Procedure [ContextName = String] [Description = String] ProcedureName = String > </Procedure>

Action Descriptions

674

Kronos Incorporated

Procedure Tag

Add Inserts one Procedure object in the database . If it's already there a rule with the same name nothing happens. Return Value Type: None Required Properties: ProcedureName, ContextName Access Control Point Name: Edit Introduced in v6.0 AddOnly Inserts one Procedure object in the database . If it's already there an error is thrown. Return Value Type: None Required Properties: ProcedureName, ContextName Access Control Point Name: Edit Introduced in v6.0 Delete Deletes the Procedure object from the database that has the same name as the one specified in the ProcedureName. If it's not there nothing happens. Return Value Type: None Required Properties: ProcedureName Access Control Point Name: Edit Introduced in v6.0 DeleteOnly Deletes the Procedure object from the database that has the same name as the one specified in the ProcedureName. If it's not there an error is thrown. Return Value Type: None Required Properties: ProcedureName Access Control Point Name: Edit Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

675

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Retrieve Retrieves the Procedure object that has the same name as the one specified in the ProcedureName. Return Value Type: Procedure tag Required Properties: ProcedureName Access Control Point Name: View Introduced in v6.0 RetrieveAll Retrieves all the Procedure objects. Return Value Type: Zero or more Procedure tags Access Control Point Name: View Introduced in v6.0 RetrieveAllForUpdate Retrieves all the Procedure objects. Return Value Type: Zero or more Procedure tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Retrieves all the names for all Procedure objects. Return Value Type: String list Access Control Point Name: View Introduced in v6.0 RetrieveForUpdate Retrieves the Procedure object that has the same name as the one specified in the ProcedureName. Return Value Type: Procedure tag Required Properties: ProcedureName Access Control Point Name: View

676

Kronos Incorporated

Procedure Tag

Introduced in v6.0 Update Updates one Procedure object in the database . If it's not there it's inserted, if it's there it's updated. Return Value Type: None Required Properties: ProcedureName Access Control Point Name: Edit Introduced in v6.0 UpdateOnly Updates one Procedure object in the database . If it's not there an error is thrown. Return Value Type: None Required Properties: ProcedureName Access Control Point Name: Edit Introduced in v6.0

Property Descriptions
ContextName

Context name
The name of the context. Type: String Optional Introduced in v6.0 Description

Description
It's the description of the rule set. It must not have more then 255 characters and must not contain invalid characters also. Type: String

Workforce Central Developers Toolkit Reference Guide—Timekeeping

677

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Introduced in v6.0 ProcedureName

Procedure name
Defines the name of the Procedure object. Type: String Required Introduced in v6.0

678

Kronos Incorporated

ProcedureAction Tag

ProcedureAction Tag Procedure Action
Procedure actions define legal actions for the pse engine. Function Access Control Point: Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" | "RetrieveAll" Parameters→ None Properties→ <ProcedureAction ProcedureActionName = String > </ProcedureAction>

Action Descriptions
Retrieve Retrieves the ProcedureAction object that has the same name as the one specified in the ProcedureActionName. Return Value Type: ProcedureAction tag Required Properties: ProcedureActionName Access Control Point Name: View Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

679

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RetrieveAll Retrieves all the ProcedureAction objects. Return Value Type: Zero or more ProcedureAction tags Access Control Point Name: View Introduced in v6.0

Property Descriptions
ProcedureActionName

Procedure action name
The name of the ProcedureAction object. Type: String Required Key Introduced in v6.0

680

Kronos Incorporated

ProcedureContext Tag

ProcedureContext Tag Procedure Context
Defines the context of a Procedure. Function Access Control Point: Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" | "RetrieveAll" | "RetrieveAllNames" Parameters→ None Properties→ <ProcedureContext ProcedureContextName = String > </ProcedureContext>

Action Descriptions
Retrieve Retrieves the ProcedureContext object that has the same name as the one specified in the ProcedureContextName. Return Value Type: ProcedureContext tag Required Properties: ProcedureContextName Access Control Point Name: View

Workforce Central Developers Toolkit Reference Guide—Timekeeping

681

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v6.0 RetrieveAll Retrieves all the ProcedureContext objects. Return Value Type: Zero or more ProcedureContext tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Retrieves all the names for all ProcedureContext objects. Return Value Type: String list Access Control Point Name: View Introduced in v6.0

Property Descriptions
ProcedureContextName

Procedure context name
The name of the ProcedureContext. Type: String Required Key Introduced in v6.0

682

Kronos Incorporated

ProcedureParameter Tag

ProcedureParameter Tag Procedure Parameter
A generic procedure parameter. Function Access Control Point: Priority Scheduling Engine Introduced in v6.0

Syntax
Properties→ <ProcedureParameter ParameterValue = String ProcedureParameterName = String ProcedureParameterDefinitionName = String > </ProcedureParameter>

Property Descriptions
ParameterValue

Parameter value
Defines the value of this ProcedureParameter object. Type: String Required Key Introduced in v6.0 ProcedureParameterDefinitionName

Procedure parameter definition name
Defines the name of the ProcedureParameterDefinition object associated to this ProcedureParameter object. Type: String Required Key Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

683

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ProcedureParameterName

Procedure Parameter Name
Represents the procedure parameter name. Type: String Required Key Introduced in v6.0

684

Kronos Incorporated

ProcedureParameterDefinition Tag

ProcedureParameterDefinition Tag Procedure Parameter Definition
Defines a Procedure parameter. Function Access Control Point: Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" | "RetrieveAll" | "RetrieveAllNames" Parameters→ None Properties→ <ProcedureParameterDefinition ProcedureParameterName = String > </ProcedureParameterDefinition>

Action Descriptions
Retrieve Retrieves the ProcedureParameterDefinition object that has the same name as the one specified in the ProcedureParameterName. Return Value Type: ProcedureParameterDefinition tag Required Properties: ProcedureParameterName Access Control Point Name: View

Workforce Central Developers Toolkit Reference Guide—Timekeeping

685

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v6.0; last changed in v6.0 RetrieveAll Retrieves all the sorting and matching ProcedureParameterDefinition objects. Return Value Type: Zero or more ProcedureParameterDefinition tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Retrieves all the names for all ProcedureParameterDefinition objects. Return Value Type: String list Access Control Point Name: View Introduced in v6.0

Property Descriptions
ProcedureParameterName

Procedure parameter name
The name of the Procedure's parameter. Type: String Required Key Introduced in v6.0

686

Kronos Incorporated

ProcedureSet Tag

ProcedureSet Tag Procedure Set
Represents a set of ProceduresSetItem objects. Each item ProceduresSetItem has a procedure and a set of ProcedureParam objects that holds all the parameters that are needed to run the given procedure. Function Access Control Point: Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Add" | "AddOnly" | "Delete" | "DeleteOnly" | "Retrieve" | "RetrieveAll" | "RetrieveAllForUpdate" | "RetrieveAllNames" | "RetrieveForUpdate" | "Update" | "UpdateOnly" Parameters→ None Properties→ <ProcedureSet ContextName = String [Description = String] ProcedureSetName = String > [<ProcedureSetItems> <ProcedureSetItem>*

Workforce Central Developers Toolkit Reference Guide—Timekeeping

687

Chapter 2

Workforce Timekeeper XML API Tag Definitions

</ProcedureSetItems>] </ProcedureSet>

Action Descriptions
Add Inserts one ProcedureSet object in the database. If it's already there a Procedure with the same name nothing happens. Return Value Type: None Required Properties: ProcedureSetName, ContextName Optional Properties: Description Access Control Point Name: Edit Introduced in v6.0 AddOnly Inserts one ProcedureSet object in the database . If it's already there an error is thrown. Return Value Type: None Required Properties: ProcedureSetName, ContextName Access Control Point Name: Edit Introduced in v6.0 Delete Deletes the ProcedureSet object from the database that has the same name as the one specified in the ProcedureSetName. If it's not there nothing happens. Return Value Type: None Required Properties: ProcedureSetName Access Control Point Name: Edit Introduced in v6.0 DeleteOnly Deletes the ProcedureSet object from the database that has the same name as the one specified in the ProcedureSetName. If it's not there an error is thrown.

688

Kronos Incorporated

ProcedureSet Tag

Return Value Type: None Required Properties: ProcedureSetName Access Control Point Name: Edit Introduced in v6.0 Retrieve Retrieves the ProcedureSet object that has the same name as the one specified in the ProcedureSetName. Return Value Type: ProcedureSet tag Required Properties: ProcedureSetName Access Control Point Name: View Introduced in v6.0 RetrieveAll Retrieves all the ProcedureSet objects. Return Value Type: Zero or more ProcedureSet tags Access Control Point Name: View Introduced in v6.0 RetrieveAllForUpdate Retrieves all the ProcedureSet objects. Return Value Type: Zero or more ProcedureSet tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Retrieves all the names for all ProcedureSet objects. Return Value Type: String list Access Control Point Name: View Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

689

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RetrieveForUpdate Retrieves the ProcedureSet object that has the same name as the one specified in the ProcedureSetName. Return Value Type: ProcedureSet tag Required Properties: ProcedureSetName Access Control Point Name: View Introduced in v6.0 Update Updates one ProcedureSet object in the database. If it's not there it's inserted, if it's there it's updated. Return Value Type: None Required Properties: ProcedureSetName, ContextName Optional Properties: Description Access Control Point Name: Edit Introduced in v6.0 UpdateOnly Updates one ProcedureSet object in the database . If it's not there an error is thrown. Return Value Type: None Required Properties: ProcedureSetName, ContextName Optional Properties: Description Access Control Point Name: Edit Introduced in v6.0

Property Descriptions
ContextName

Context Name
Represents the procedure set context name.

690

Kronos Incorporated

ProcedureSet Tag

Type: String Required Sample values: PSE_CONTEXT Introduced in v6.0 Description

Description of rule set
Description of the rule set. Cannot exceed 255 characters and cannot contain invalid characters. Type: String Optional Introduced in v6.0 ProcedureSetItems

Procedure Set Items
Represents the list of procedure set items. Type: Zero or more ProcedureSetItem tags Optional Sample values: <ProcedureSetItems> <ProcedureSetItem ProcedureName = "Procedure2" GenerateAudit="False"> <ProcedureParameters> <ProcedureParameter ProcedureParameterDefinitionName = "SORTING_EMPLOYEES_RULE_SET" ParameterValue="Rule Set NB 4" /> <ProcedureParameter ProcedureParameterDefinitionName = "SORTING_SHIFTS_RULE_SET" ParameterValue="Rule Set NB 3" />

Workforce Central Developers Toolkit Reference Guide—Timekeeping

691

Chapter 2

Workforce Timekeeper XML API Tag Definitions

</ProcedureParameters> </ProcedureSetItem> </ProcedureSetItems Introduced in v6.0 ProcedureSetName

Procedure set name
The name of the ProcedureSet. Type: String Required Key Introduced in v6.0

692

Kronos Incorporated

ProcedureSetItem Tag

ProcedureSetItem Tag Procedure Set Item
Makes the link between a Procedure and a ProcedureSet. Function Access Control Point: Priority Scheduling Engine Introduced in v6.0

Syntax
Properties→ <ProcedureSetItem GenerateAudit = Boolean ProcedureName = String > [<ProcedureParameters> <ProcedureParameter>* </ProcedureParameters>] </ProcedureSetItem>

Property Descriptions
GenerateAudit

Generate audit
The audit trail flag. The value of this can be only "True" or "False". Type: Boolean Required Key Introduced in v6.0 ProcedureName

Procedure name
The name of the Procedure associated to this ProcedureSetItem. Type: String Required Key

Workforce Central Developers Toolkit Reference Guide—Timekeeping

693

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v6.0 ProcedureParameters

Procedure Parameters
The list of procedure parameters, which is composed of a procedure parameter definition and the value associated. Type: Zero or more ProcedureParameter tags Optional Sample values: <ProcedureParameters> <ProcedureParameter ProcedureParameterDefinitionName = "SORTING_EMPLOYEES_RULE_SET" ParameterValue="Rule Set NB 4" /> <ProcedureParameter ProcedureParameterDefinitionName = "SORTING_SHIFTS_RULE_SET" ParameterValue="Rule Set NB 3" /> </ProcedureParameters> Introduced in v6.0

694

Kronos Incorporated

Process Tag

Process Tag Process
The Process tag specifies a process that resulted from a specific process template. Function Access Control Point: com.kronows.wf.business.workflow.Kprocess Introduced in v5.1; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Add" | "AddWithWebForm" | "DeleteOnly" | "Retrieve" | "UpdateOnly" Parameters→ Add→ ResourceId = String AddWithWebForm→ ResourceId = String Properties→ <Process AdminTemplateId = Integer ProcessStateCode = Integer ProcessId = Integer ProcessName = String ProcessState = String [KProcessUniqueKey = String] > [<ProcessAttributes> <Attribute>* </ProcessAttributes>] </Process>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

695

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Descriptions
Add This action initiates or starts a process and supports the initialization of process attributes. It does not add new process attributes, but can initialize existing process attribute values. Any process attribute that has an attribute type of "Object" or "java.lang.Object" cannot be updated or initialized. The ResourceID is equivalent to the WTKPersonNumber or PersonId value. The ResourceId must match the timekeeping person number, and it is important to note that trailing blanks are significant and should not be included. AdminTemplateId must be greater than 0. ResourceId must be greater than 1 character and less than or equal to 30 characters. Return Value Type: Process tag Required Properties: One of AdminTemplateId or KProcessUniqueKey is required. ResourceId is a required action parameter. Optional Properties: ProcessAttributes Access Control Point Name: Edit Introduced in v5.1

696

Kronos Incorporated

Process Tag

Action Parameters Parameter Name ResourceId Description The ResourceId is a required action parameter for the Add action. It is the identifier of the resource or equivalent to the PersonNumber or PersonId of the person who will be initiating the process. The ResourceID is equivalent to the WTK Person Number or Person Id value. The ResourceId must match the WFC person number, and it is important to note that trailing blanks are significant and should not be included. Required Minimum length: 1 character Maximum length: 30 characters Additional information Introduced in v5.1

AddWithWebForm This action initiates or starts a process and supports the initialization of the process attributes. This action initiates a process that contains a web form, supports the initialization of process attributes, and returns the first task which contains the web form. New process attributes cannot be added through this action, but existing process attribute values can be initialized. Any process attribute that has an attribute type of "Object" or "java.lang.Object" cannot be updated or initialized. The ResourceID is equivalent to the WTKPersonNumber or PersonId value. The ResourceId must match the timekeeping person number, and it is important to note that trailing blanks are significant and should not be included. AdminTemplateId must be greater than 0. ResourceId must be greater than 1 character and less than or equal to 30 characters. Return Value Type: ProcessTask tag Required Properties: One of AdminTemplateId or KProcessUniqueKey is required. ResourceId is a required action parameter.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

697

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Properties: ProcessAttributes Access Control Point Name: Edit Introduced in v5.1
Action Parameters Parameter Name ResourceId Description The ResourceId is the required action paramter for the AddWithWebForm action. It is the id of the resource or equivalent to the person's number or person id who will be initiating the process. The ResourceID is equivalent to the WTK Person Number or Person Id value. The ResourceId must match the WFC person number, and it is important to note that trailing blanks are significant and should not be included. Required Minimum length: 1 character Maximum length: 30 characters Additional information Introduced in v5.1

DeleteOnly The DeleteOnly method deletes a single process specified by the process id. The ProcessId must be greater than 0. Return Value Type: None Required Properties: ProcessId Access Control Point Name: Edit Introduced in v5.1 Retrieve This action returns a specific process. The ProcessId must be greater than 0. Return Value Type: Process tag

698

Kronos Incorporated

Process Tag

Required Properties: ProcessId Access Control Point Name: View Introduced in v5.1 UpdateOnly This action updates a process by updating the process state and the process attributes. This action does not add new process attributes, but can update existing ones. The process state can be updated from an aborted state to active state. The process state can be updated from a ready state to a passive state. The process state can be updated from an active state to passive state or to an abort state. The process state can be updated from an abort state to a passive state. Any process attribute that has an attribute type of "Object" or "java.lang.Object" cannot be updated or initialized. The ProcessId must be greater than 0. The ProcessStateCode can be 1 to update a process state to active, 3 to update process state to abort state, and 4 to update a process state to passive or a canceled state. Return Value Type: Process tag Required Properties: ProcessId Optional Properties: ProcessStateCode, ProcessAttributes Access Control Point Name: Edit Introduced in v5.1

Property Descriptions
AdminTemplateId

Administrator Template Id
The identifier for the process template from which the process was created, used for administration purposes. Type: Integer Required The AdminTemplateId is a required property on the Process. The AdminTemplateId must not be null and must be greater than 0. The

Workforce Central Developers Toolkit Reference Guide—Timekeeping

699

Chapter 2

Workforce Timekeeper XML API Tag Definitions

AdminTemplateId is an optional property on the Process Add and AddWithWebForm actions. Introduced in v5.1 KProcessUniqueKey

Process unique key
The exposed private_PMUniqueKey that can be used to instantiate or start a process. Type: String Optional KProcessUniqueKey must be 1 or more characters long. Sample values: 95c73c96947cdca4:52fecf:101437b4fc1:-7ffd Introduced in v5.1 ProcessAttributes

Process attributes
One or more process attributes. Each process attribute contains a name and a value. Type: Zero or more Attribute tags Optional Each Attribute within a Process Attributes list must contain a Name property and Value property pair. The Name must be greater than 1 character. The Name has maximum length of 255 characters. Sample values: <ProcessAttributes> <Attribute Name="HRAdministrator" Value="207"> </ Attribute> </ProcessAttributes>

700

Kronos Incorporated

Process Tag

Introduced in v5.1 ProcessId

Process identifier
The identifier of the process or the instantiated process template Type: Integer Required Key Must be greater than 0. Introduced in v5.1 ProcessName

Process name
The name of the process Type: String Required Maximum length: 50 characters Minimum length: Must be greater than 1 character Sample values: EmployeeAward Introduced in v5.1 ProcessState

Process state
The state of the process Type: String Required ProcessState is a required property on the Process. The ProcessState must not be null and must be one of the valid process states. The ProcessState is an optional property on the Process UpdateOnly action.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

701

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Sample values: "Ready","Active","Done","Abort","Passive" Introduced in v5.1 ProcessStateCode

Process State Code
The integer value for the process state. Type: Integer Required The ProcessState Code can only be values 0, 1, 2, 3, 4. Sample values: 0 for Ready process state, 1 for Active process state, 2 for Done process state, 3 for Abort process state, 4 for Passive process state Introduced in v5.1

702

Kronos Incorporated

ProcessorToEmployee Tag

ProcessorToEmployee Tag Assign processor rule to an employee
Assign rules defined by an extension processor, such as the fixed percent allocation and rest between shift processors, to an employee. This assignment is effective dated. Function Access Control Point: Totalizer.Extensibility Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Add" | "AddOnly" | "Delete" | "Retrieve" | "RetrieveAll" | "RetrieveByPerson" | "RetrieveByPersonAndEffectiveDate" | "RetrieveByProcessor" | "RetrieveForUpdate" | "Update" | "UpdateOnly" Parameters→ None Properties→ <ProcessorToEmployee [EffectiveDate = Date] [ExpirationDate = Date] Processor = String > <Person> <PersonIdentity>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

703

Chapter 2

Workforce Timekeeper XML API Tag Definitions

</Person> </ProcessorToEmployee>

Action Descriptions
Add Adds a new association of an extension processor to an employee, or updates an existing one. Return Value Type: None Required Properties: Processor, Person Optional Properties: EffectiveDate, ExpirationDate, NewProcessor, NewEffectiveDate Access Control Point Name: Edit Introduced in v5.2 AddOnly Adds a new association of an extension processor to an employee. Return Value Type: None Required Properties: Processor, Person Optional Properties: EffectiveDate, ExpirationDate Access Control Point Name: Edit Introduced in v5.2 Delete Deletes an association of an extension processor to an employee. If the effective date is not specified, deletes the association that is in effect at start of time (01/01/ 1753). Return Value Type: None Required Properties: Processor, Person Optional Properties: EffectiveDate Access Control Point Name: Edit Introduced in v5.2

704

Kronos Incorporated

ProcessorToEmployee Tag

Retrieve Retrieves a ProcessorToEmployee association. If an effective date is not specified, retrieves the association in effect at start of time (01/01/1753). Return Value Type: ProcessorToEmployee tag Required Properties: Processor, Person Optional Properties: EffectiveDate Access Control Point Name: View Introduced in v5.2 RetrieveAll Retrieves a list of all of the ProcessorToEmployee associations. Return Value Type: Zero or more ProcessorToEmployee tags Access Control Point Name: View Introduced in v5.2 RetrieveByPerson Retrieves the list of ProcessorToEmployee associations for a given employee. Person must be a valid PersonIdentity. Return Value Type: Zero or more ProcessorToEmployee tags Required Properties: Person Access Control Point Name: View Introduced in v5.2 RetrieveByPersonAndEffectiveDate Retrieve the list of ProcessorToEmployee associations for the given person that are in effect on the given effective date. Person must be a valid PersonIdentity, and EffectiveDate must be a valid date. Return Value Type: Zero or more ProcessorToEmployee tags Required Properties: Person, EffectiveDate Access Control Point Name: View Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

705

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RetrieveByProcessor Retrieves the list of ProcessorToEmployee associations for a given extension processor. Must specify a valid Processor name. Return Value Type: Zero or more ProcessorToEmployee tags Required Properties: Processor Access Control Point Name: View Introduced in v5.2 RetrieveForUpdate Retrieves a ProcessorToEmployee association for update. If the effective date is not specified, retrieves the association in effect at start of time (01/01/1753). Return Value Type: ProcessorToEmployee tag Required Properties: Processor, Person Optional Properties: EffectiveDate Access Control Point Name: View Introduced in v5.2 Update Updates an existing association of an extension processor to an employee, or add one if it does not exist. Return Value Type: None Required Properties: Processor, Person Optional Properties: EffectiveDate, ExpirationDate, NewProcessor, NewEffectiveDate Access Control Point Name: Edit Introduced in v5.2 UpdateOnly Updates an existing association of an extension processor to an employee. Return Value Type: None Required Properties: Processor, Person

706

Kronos Incorporated

ProcessorToEmployee Tag

Optional Properties: EffectiveDate, ExpirationDate, NewProcessor, NewEffectiveDate Access Control Point Name: Edit Introduced in v5.2

Property Descriptions
EffectiveDate

Effective date
The effective date of the association of an extension processor and an employee. Type: Date Optional Must be a valid date. Default value: 01/01/1753 (start of time) Introduced in v5.2 ExpirationDate

Expiration date
The expiration date of an association of an extension processor and an employee. Type: Date Optional Must be a valid date. Default value: 01/01/3000 (forever) Introduced in v5.2 Person

Person
The PersonIdentity of the employee to be associated with an extension processor. Type: PersonIdentity tag

Workforce Central Developers Toolkit Reference Guide—Timekeeping

707

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required Key Must be a valid PersonIdentity. Introduced in v5.2 Processor

Processor
The name of an extension processor to associate with an employee. Type: String Required Key Must be a valid extension processor name. Introduced in v5.2

708

Kronos Incorporated

ProcessProfile Tag

ProcessProfile Tag Process Profile
The ProcessProfile tag loads the specific information for one or more process profiles. For the Load Action, the ProcessProfileName MUST be specified. For the LoadById Action, the ProcessProfileId property MUST be specified. Function Access Control Point: API.WorkflowProfile Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllProcessProfiles" | "LoadById" Parameters→ None Properties→ <ProcessProfile ProcessProfileId = Long [ProcessProfileName = String] > </ProcessProfile>

Action Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

709

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Load Loads the process profile from the database given the ProcessProfileName property. An example of the ProcessProfileName may be "All Process Templates". The ProcessProfileName must already exist in the database, prior to calling the Load action. Return Value Type: (***undefined***): WorkflowProfile Required Properties: ProcessProfileName Access Control Point Name: View Introduced in v5.0; last changed in v5.0 LoadAllProcessProfiles Loads all process profiles in the database, returning a list of APIWorkflowProfileBeans. Return Value Type: (***undefined***): WorkflowProfile Required Properties: None Access Control Point Name: View Introduced in v5.0; last changed in v5.0 LoadById Loads the Process Profile from the database given the ProcessProfileId property. The ProcessProfileId which uniquely identifies a process profile must already exist in the database, prior to calling the LoadById action. Return Value Type: (***undefined***): WorkflowProfile Required Properties: ProcessProfileId Access Control Point Name: View Introduced in v5.0; last changed in v5.0

Property Descriptions
ProcessProfileId

Process Profile Id

710

Kronos Incorporated

ProcessProfile Tag

The Id of a specific process profile, which identifies a unique process profile. Type: Long Required Key Introduced in v5.0; last changed in v5.0 ProcessProfileName

Process Profile name
The Name of the Process Profile. The ProcessProfileName property MUST be specified for the Load action. Type: String Optional For the Load action, the ProcessProfileName property MUST be specified. The ProcessProfileName must already exist in the database, prior to calling the Load action. Sample values: ProcessProfileName="All Process Templates" Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

711

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ProcessSchedule Tag Process Schedule
The ProcessSchedule tag is used to modify an existing employee schedule in addition to what is already scheduled. With the ProcessSchedule tag, you can swap shifts between employees or assign a new employee to cover a scheduled shift for another employee. Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "CoverShift" | "SwapShifts" Parameters→ None Properties→ <ProcessSchedule [SaveData = Boolean] QueryDateSpan = DateSpan [CheckRules = Boolean] > <Employees> <CurrentUser> | <PersonIdentity> </Employees> [<ScheduleItems> <ScheduleAccrualAmountEdit> | <ScheduleOff> | <SchedulePayCodeEdit> | <ScheduleShift> | <ScheduleShiftSwap> | <ScheduleUnavailable> </ScheduleItems>] </ProcessSchedule>

712

Kronos Incorporated

ProcessSchedule Tag

Action Descriptions
CoverShift Assign an employee to cover a shift for another employee, as specified by a ScheduleShiftSwap tag in the ScheduleItems property. The Employees list must contain exactly two employees. These must be the same employees as those identified in the ScheduleShiftSwap tag. The ScheduleItems list must contain exactly two shifts. Return Value Type: Zero or more RuleViolation tags Required Properties: Employees, QueryDateSpan, ScheduleItems Optional Properties: SaveData, CheckRules Access Control Point Name: Edit Introduced in v5.0; last changed in v5.1 SwapShifts Swap the employee assignments for the two specified shifts, as identified by ScheduleShiftSwap tags in the ScheduleItems property. The Employees list must contain exactly two employees. These must be the same employees as those identified in the ScheduleShiftSwap tag. The ScheduleItems list must contain exactly two shifts. Return Value Type: Zero or more RuleViolation tags Required Properties: Employees, QueryDateSpan, ScheduleItems Optional Properties: SaveData, CheckRules Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0

Property Descriptions
CheckRules

Validate modified schedule?

Workforce Central Developers Toolkit Reference Guide—Timekeeping

713

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Indicates whether schedule validation will take place on the modified schedule from an action Type: Boolean Optional SaveData and CheckRules cannot both be false. If CheckRules is True, any rule violations from employees or jobs that are affected by the action are returned by the action. If it is False, then null is returned. Default value: False Introduced in v5.0 Employees

Employees
One or more employees for whom the action will be processed, as specified in one or more PersonIdentity or CurrentUser tags. Type: Either CurrentUser or PersonIdentity tag Required Key Introduced in v5.0 QueryDateSpan

Span of dates
The span of dates that are used Type: DateSpan Required Key The span must fully encompass the dates of any shift that is specified in ScheduleItems. Introduced in v5.0 SaveData

Save the modified schedule?
SaveData indicates whether the schedule, modified by an action, will be saved.

714

Kronos Incorporated

ProcessSchedule Tag

Type: Boolean Optional SaveData and CheckRules cannot both be false. If SaveData is True, any rule violations from employees or jobs that are affected by the action are returned by the action. If it is False, then null is returned. Default value: True Introduced in v5.0 ScheduleItems

Scheduled shifts
The ScheduleItems property contains the shifts that will be processed by actions in the ProcessSchedule tag. Each one represents a shift that would appear in the schedule editor or the schedule planner. Each item in this list must be a ScheduleShiftSwap tag. Type: Either ScheduleAccrualAmountEdit, ScheduleOff, SchedulePayCodeEdit, ScheduleShift, ScheduleShiftSwap or ScheduleUnavailable tag Optional Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

715

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ProcessTask Tag Process Task
The ProcessTask tag relates a task within a process or workflow. A process task has state and attribute values that can be retrieved and updated. Function Access Control Point: com.kronos.wfc.business.workflow.KProcessTask Introduced in v5.1; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" | "RetrieveAllByProcessId" | "RetrieveAllByResourceId" | "UpdateOnly" Parameters→ RetrieveAllByResourceId→ [CategoryName = String] Properties→ <ProcessTask EndDate = Date [Locations = String] [PrevLocations = String] ProcessId = Integer [ProcessName = String] [ResourceId = String] [ResourceName = String] StartDate = Date [TaskURL = String] TaskId = Integer TaskName = String

716

Kronos Incorporated

ProcessTask Tag

TaskState = String TaskStateCode = Integer > [<TaskAttributes> <Attribute>* </TaskAttributes>] </ProcessTask>

Action Descriptions
Retrieve The Retrieve action returns the ProcessTask specified by the TaskId. Return Value Type: ProcessTask tag Required Properties: TaskId Access Control Point Name: View Introduced in v5.0a RetrieveAllByProcessId This action returns a list of tasks for a given process. By specifying the ProcessId, TaskStateCode, and ResourceId, you can retrieve a list of tasks by process id, or by process id and task state, or by process id, task state and resource id, or by process id and resource id. The ResourceID is equivalent to the WTKPersonNumber or PersonId value. The ResourceId must match the timekeeping person number, and it is important to note that trailing blanks are significant and should not be included. Return Value Type: Zero or more ProcessTask tags Required Properties: ProcessId Optional Properties: TaskStateCode, ResourceId Access Control Point Name: View Introduced in v5.1 RetrieveAllByResourceId This action returns a list of tasks for a given process. By specifying the ResourceId, TaskStateCode, CategoryName, you can retrieve a list of process tasks by resource, or by resource id and task state, or by resource id, task state, and category name, or by resource id and by category name. If you specify an active

Workforce Central Developers Toolkit Reference Guide—Timekeeping

717

Chapter 2

Workforce Timekeeper XML API Tag Definitions

task state with a TaskStateCode of 1, a list of all active tasks that are assigned to the specified resource for all processes is returned. If you specify a CategoryName and a specific ResourceId, a list of all tasks assigned to that resource and also correspond to a process template that belong to the specified category will be returned. If you specify a TaskStateCode of 1, a CategoryName, and a ResourceId, a list of all active tasks assigned to the specified resource that correspond to a process template that belongs to the specified CategoryName are returned. The ResourceID is equivalent to the WTKPersonNumber or PersonId value. The ResourceId must match the timekeeping person number, and it is important to note that trailing blanks are significant and should not be included. Return Value Type: Zero or more ProcessTask tags Required Properties: ResourceId Optional Properties: CategoryName - optional action parameter, TaskStateCode optional property Access Control Point Name: View Introduced in v5.1
Action Parameters Parameter Name CategoryName Description The CategoryName is an optional action parameter to the RetrieveByResourceId action. Optional If specified for the action, the CategoryName must not be null and must be greater than 1 character and less than or equal to 50 characters in length. Additional information Introduced in v5.1

UpdateOnly This action updates a specific task within a process by updating the task state and task attributes. You cannot add any new task attributes. However, process task attribute values can be updated. Any task attribute that has an attribute type of "Object" or "java.lang.Object" cannot be updated or initialized.

718

Kronos Incorporated

ProcessTask Tag

Return Value Type: ProcessTask tag Required Properties: TaskId Optional Properties: TaskStateCode, TaskAttributes Access Control Point Name: Edit Introduced in v5.1

Property Descriptions
EndDate

End date
The date on which the process task ends Type: Date Required EndDate is a required property on the ProcessTask. The EndDate must not be null and must be a valid Date. Introduced in v5.1 Locations

List of active tasks
A comma separated list of active tasks that indicate where you are in the process. Type: String Optional Locations is an optional property on the ProcessTask. Introduced in v5.1 PrevLocations

List of resources assigned to previous tasks
A comma separated list of resources assigned to one or more previous tasks. If a resource name is not available, you can specify the resource identifier instead. If

Workforce Central Developers Toolkit Reference Guide—Timekeeping

719

Chapter 2

Workforce Timekeeper XML API Tag Definitions

the previous tasks have no assigned resources, an empty string is returned. This can occur with synch tasks. Type: String Optional Introduced in v5.1 ProcessId

Process identifier
The identifier of the process to which this process task belongs. Type: Integer Required Must be greater than zero. Introduced in v5.1 ProcessName

Process name
The name of the process to which this process task belongs. Type: String Optional Maximum length: 50 characters and MinimumLength: 1 character Sample values: EmployeeAward Introduced in v5.1 ResourceId

Resource or person Id who owns the task
The identifier of the resource or person who owns the process task. The ResourceID is equivalent to the WTKPerson Number or PersonId value. The

720

Kronos Incorporated

ProcessTask Tag

ResourceId must match the timekeeping person number, and it is important to note that trailing blanks are significant and should not be included. Type: String Optional Maximum length: 30 characters Introduced in v5.1 ResourceName

Resource or person who owns the task
The name of the resource or person who owns the process task Type: String Optional Maximum length: 64 characters Minimum length: 1 character Sample values: Fryman, Christy Introduced in v5.1 StartDate

Start date
The date the process task starts Type: Date Required StartDate is a required property on the ProcessTask. The StartDate must not be null and must be a valid Date. Introduced in v5.1 TaskAttributes

Task attributes

Workforce Central Developers Toolkit Reference Guide—Timekeeping

721

Chapter 2

Workforce Timekeeper XML API Tag Definitions

One or more Attribute tags that identify who belongs to the process task. Each TaskAttribute has a name and value pair. Type: Zero or more Attribute tags Optional TaskAttributes list is an optional property on the ProcessTask and an optional property on ProcessTask UpdateOnly action. For each task attribute specified, the task attribute Name cannot be null and must be 1 char and <= 255 chars in length. Sample values: <TaskAttributes> <Attribute Name="roleAttribute" Value="${employee}.manager> </Attribute> </TaskAttributes> Introduced in v5.1 TaskId

Task identifier
The identifier of the process task. Type: Integer Required Key Must be greater than zero. Introduced in v5.1 TaskName

Task name
The name of the process task Type: String Required

722

Kronos Incorporated

ProcessTask Tag

The TaskName is a required property on the ProcessTask. The TaskName must not be null and must be greater than 1 character and less than 50 characters in length. Sample values: Approval Form Introduced in v5.1 TaskState

Task state
The state of the process task Type: String Required If specified, the TaskState must be one of the valid task states. Sample values: "Ready","Active","Complete","Failed","Passive" Introduced in v5.1 TaskStateCode

Task state code
The integer value representing the Process Task state. Type: Integer Required 0 for Ready task state, 1 for Active task state, 2 for Complete task state, 3 for Failed task state, 4 for Passive task state Enumerated value: 0, 1, 2, 3, 4 Introduced in v5.1 TaskURL

Task URL

Workforce Central Developers Toolkit Reference Guide—Timekeeping

723

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The url of the web task in a process Type: String Optional Introduced in v5.1

724

Kronos Incorporated

ProcessTemplate Tag

ProcessTemplate Tag Process Template
The ProcessTemplate tag represents the template for a process. A process template can belong to one or more categories. A process template can be used to create a process. Function Access Control Point: com.kronos.wfc.business.workflow.KProcessTemplate Introduced in v5.1; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Add" | "DeleteOnly" | "Retrieve" | "RetrieveAll" | "RetrieveAllByCategory" | "RetrieveAllByResourceId" | "RetrieveAllForEmployee" | "RetrieveAllForManager" | "RetrieveByDisplayName" | "RetrieveByUniqueKey" | "UpdateOnly" Parameters→ RetrieveAllByCategory→ [IncludeTemplateData = Boolean] RetrieveAllByResourceId→ GetHiddenActions = Boolean [IncludeTemplateData = Boolean] ResourceId = String RetrieveAllForEmployee→ [CategoryName = String]

Workforce Central Developers Toolkit Reference Guide—Timekeeping

725

Chapter 2

Workforce Timekeeper XML API Tag Definitions

GetHiddenActions = Boolean [IncludeTemplateData = Boolean] RetrieveAllForManager→ [CategoryName = String] GetHiddenActions = Boolean [IncludeTemplateData = Boolean] ResourceId = String RetrieveByDisplayName→ [IncludeTemplateData = Boolean] RetrieveByUniqueKey→ [IncludeTemplateData = Boolean] UpdateOnly→ [IncludeTemplateData = Boolean] Properties→ <ProcessTemplate AdminTemplateId = Long [KProcessUniqueKey = String] [CommentText = String] EffectiveDate = DateTime ExpirationDate = DateTime ActiveSwitch = Integer ActionListSwitch = Integer (LastDeployed = DateTime) [MaxPoolSize = Integer] [UsedBy = String] [CategoryNames = String] DisplayName = String TemplateData = String TemplateId = Long AdminTemplateName = String Version = Integer > </ProcessTemplate>

Action Descriptions
Add This action adds a new Process Template using the specified TemplateData. Return Value Type: ProcessTemplate tag Required Properties: DisplayName, EffectiveDate, ExpirationDate, TemplateData

726

Kronos Incorporated

ProcessTemplate Tag

Optional Properties: ActiveSwitch, ActionListSwitch, CommentText, MaxPoolSize, CategoryNames Access Control Point Name: Edit Introduced in v5.1 DeleteOnly This action deletes a process template specified by the AdminTemplateId. Return Value Type: None Required Properties: AdminTemplateId Access Control Point Name: Edit Introduced in v5.1 Retrieve This action returns the process template for the specified template identifier. The AdminTemplateId must be greater than 0. Return Value Type: ProcessTemplate tag Required Properties: AdminTemplateId Access Control Point Name: View Introduced in v5.1 RetrieveAll The RetrieveAll method retrieves a list of all process templates regardless of which person or resource id they belong to or which category they belong to. This method retrieves a list of all process templates. By default, the Filter action parameters is set to "ALL" and the IncludeTemplateData action parameter is set to "false". If the IncludeTemplateData action parameter is set to "true", the TemplateData property will be displayed for each process template returned in the XML Response. If the IncludeTemplateData action parameter is set to "false", the TemplateData property will not be displayed for each process template returned in the XML Response. If the IncludeTemplateData action parameter is not specified at all for this action, by default the IncludeTemplateData action parameter is set to "false", and the TemplateData property will not be displayed for each returned process template.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

727

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Filter action parameter can only be: "ALL", "ACTIVE", "INACTIVE" and the IncludeTemplateData action parameter can only be "true" or "false" Return Value Type: Zero or more ProcessTemplate tags Optional Properties: Filter, IncludeTemplateData Access Control Point Name: View Introduced in v5.1 RetrieveAllByCategory This action returns one or more process templates for the specified category. This action has an action parameter, IncludeTemplateData. If IncludeTemplateData action parameter is specified as "true", TemplateData property is returned for each process template. By default, the IncludeTemplateData action parameter is set to "false". If the IncludeTemplateData action parameter is not specified, the IncludeTemplateData is set to "false", and the TemplateData property will not be displayed for each ProcessTemplate returned. Return Value Type: Zero or more ProcessTemplate tags Required Properties: CategoryName Optional Properties: IncludeTemplateData Access Control Point Name: View Introduced in v5.1

728

Kronos Incorporated

ProcessTemplate Tag

Action Parameters Parameter Name IncludeTemplateData Description The IncludeTempateData specifies whether information that is returned should include TemplateData. If the IncludeTemplateData action parameter is set to "true", TemplateData is returned for each process template. If you do not specify the IncludeTemplateData as action parameter, the IncludeTemplateData by default is set to "false", and the TemplateData property will not be displayed in each process template returned. Optional IncludeTemplateData is an optional action parameter on the RetrieveAllByCategory action. It can only be set to "true" or "false". Default value: "false" Additional information Introduced in v5.1

RetrieveAllByResourceId This method returns a combined list of all the process templates that a specific manager and employee can instantiate. This method gets a list of all actions from the Employee and Manager Action lists, for the specified resource. The GetHiddenActions parameter can be set to "true" or "false". If the GetHiddenActions is set to "true", the process templates who's ActionListSwitch is set to 0, will be returned along with those who's values is 1. If the GetHiddenActions action parameter is set to "false", only process templates with an ActionListSwitch set to 1 will be returned. The IncludeTemplateData action parameter may be "true" or "false". If the IncludeTemplateData action parameter is set to "true", the TemplateData property will be displayed for every process template returned in the XML Response. If the IncludeTemplateData action parameter is set to "false", the TemplateData property will not be displayed within each process template returned within the XML Response. By default, the

Workforce Central Developers Toolkit Reference Guide—Timekeeping

729

Chapter 2

Workforce Timekeeper XML API Tag Definitions

IncludeTemplateData action parameter is set to "false". If you do not specify the IncludeTemplateData action parameter, the value for IncludeTemplateData will be set to "false". Therefore, the TemplateData property will not be displayed for each returned process template. The ResourceID is equivalent to the WTKPersonNumber or PersonId value. The ResourceId must match the timekeeping person number, and it is important to note that trailing blanks are significant and should not be included. The ResourceId, IncludeTemplateData are required parameters. The ResourceId must be 1 char & <= 30 chars in length. The GetHiddenActions action parameter and the IncludeTemplateData action parameter can only be set to either "true" or "false". Return Value Type: Zero or more ProcessTemplate tags Required Properties: ResourceId, GetHiddenActions Optional Properties: IncludeTemplateData Access Control Point Name: View Introduced in v5.1

730

Kronos Incorporated

ProcessTemplate Tag

Action Parameters Parameter Name GetHiddenActions Description The GetHiddenActions action parameter is a required action parameter on the RetrieveAllByResourceId action. The GetHiddenActions action parameter can either be "true" or "false". If the GetHiddenActions action parameter is set to "true", all the process templates that have the ActionListSwitch set to 0 will be returned along with those who's value is 1. This implies all of the process templates that are "Hidden" from the Actions list, will be returned along those which are visible on the Actions list. Required GetHiddenActions is a required action parameter on the RetrieveAllByResourceId action. It can either be set to "true" or "false". Default value: "false" Additional information Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

731

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Parameter Name IncludeTemplateData

Description The IncludeTempateData specifies whether information that is returned should include TemplateData. If the IncludeTemplateData action parameter is set to "true", TemplateData is returned for each process template. If the IncludeTemplateData action parameter is set to "false", TemplateData is returned for each process template. If you do not specify the IncludeTemplateData action parameter, the default value for IncludeTemplateData is set to "false". Therefore, the TemplateData property will not be displayed for each returned process template. Optional IncludeTemplateData is an optional action parameter on RetrieveAllByResourceId action. It must be set to either "true" or "false". Default value: "false"

Additional information Introduced in v5.1

732

Kronos Incorporated

ProcessTemplate Tag

Parameter Name ResourceId

Description The ResourceId is a required action parameter on the RetrieveAllByResourceId action. It represents the id of the resource, manager or employee who will be initiating the process. The ResourceID is equivalent to the WTK Person Number or Person Id value. The ResourceId must match the WFC person number, and it is important to note that trailing blanks are significant and should not be included. Required ResourceId is a required action parameter on the RetrieveAllByResourceId action. The ResourceId must be greater than 1 character and less than or equal to 30 characters in length.

Additional information Introduced in v5.1

RetrieveAllForEmployee This method returns a list of process templates that employees can instantiate. If you do not specify the CategoryName, you will retrieve all process templates, that a manager, specified by resourceId, can instantiate. If you specify a CategoryName, you will get all process templates that belong to specific category, specified by the given category name, that the specified manager can instantiate. If the GetHiddenActions is set to "true", the process templates who's ActionListSwitch is set to 0, will be returned along with those who's values is 1. The IncludeTemplateData action parameter may be "true" or "false". If the IncludeTemplateData action parameter is set to "true", the TemplateData property will be displayed for every process template returned in the XML Response. If the IncludeTemplateData action parameter is set to "false", the TemplateData property will not be displayed within each process template returned within the XML Response. By default, the IncludeTemplateData action parameter is set to "false". If you do not specify the IncludeTemplateData action parameter, the

Workforce Central Developers Toolkit Reference Guide—Timekeeping

733

Chapter 2

Workforce Timekeeper XML API Tag Definitions

IncludeTemplateData will be set to "false" by default, and the TemplateData property will not be displayed for each returned process template. GetHiddenActions, IncludeTemplateData are required parameters. GetHiddenActions can only be "true" or "false". Return Value Type: Zero or more ProcessTemplate tags Required Properties: GetHiddenActions Optional Properties: CategoryName, IncludeTemplateData Access Control Point Name: View Introduced in v5.1; last changed in v6.0

734

Kronos Incorporated

ProcessTemplate Tag

Action Parameters Parameter Name CategoryName Description The CategoryName is an optional action parameter on the RetrieveAllForEmployee action. It represents the name of the category which one or more process template belongs to. Optional CategoryName is an optional action parameter on the RetrieveAllForEmployee action. It must be greater than 1 character and less than or equal to 50 characters in length. The GetHiddenActions action parameter is a required action parameter on the RetrieveAllForEmployee action. The GetHiddenActions action parameter can either be "true" or "false". If the GetHiddenActions action parameter is set to "true", all the process templates that have the ActionListSwitch set to 0 will be returned along with those who's value is 1. This implies all of the process templates that are "Hidden" from the Actions list, will be returned along those which are visible on the Actions list. Required GetHiddenActions is a required action parameter on the RetrieveAllForEmployee action. It can either be set to "true" or "false". Default value: "false" Additional information Introduced in v5.1

GetHiddenActions

Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

735

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Parameter Name IncludeTemplateData

Description The IncludeTempateData specifies whether information that is returned should include TemplateData. If the IncludeTemplateData action parameter is set to "true", TemplateData is returned for each process template.If the IncludeTemplateData action parameter is set to "false", TemplateData is not returned for each process template. If you do not specify the IncludeTemplateData action parameter, by default the IncludeTemplateData value is set to "false". Therefore, the TemplateData property will not be displayed for each returned process template. Optional IncludeTemplateData is a required action parameter on RetrieveAllForEmployee action. It must be set to either "true" or "false". Default value: "false"

Additional information Introduced in v5.1

RetrieveAllForManager This method returns a list of process templates that managers can instantiate. The CategoryName is an optional action parameter. If you do not specify the CategoryName, you will retrieve all process templates, that a manager, specified by resourceId, can instantiate. If you specify a CategoryName, you will get all process templates that belong to specific category, specified by the given category name, that the specified manager can instantiate. If the GetHiddenActions is set to "true", the process templates who's ActionListSwitch is set to 0, will be returned along with those who's values is 1. The IncludeTemplateData action parameter may be "true" or "false". If the IncludeTemplateData action parameter is set to "true", the TemplateData property will be displayed for every process template returned in the XML Response. If the IncludeTemplateData is set to "false", the TemplateData property will not be displayed within each process template

736

Kronos Incorporated

ProcessTemplate Tag

returned within the XML Response. By default, the IncludeTemplateData action parameter is set to "false". If the IncludeTemplateData action parameter is not specified, the default value is set to "false", therefore the TemplateData property will not be displayed for each returned process template. The ResourceID is equivalent to the WTKPersonNumber or PersonId value. The ResourceId must match the timekeeping person number, and it is important to note that trailing blanks are significant and should not be included. The ResourceId, GetHiddenActions are required parameters. The ResourceId must be 1 char & <= 30 chars in length. CategoryName, if given, must be 1 char & <= 50 chars in length. GetHiddenActions can only be "true" or "false". Return Value Type: Zero or more ProcessTemplate tags Required Properties: ResourceId, GetHiddenActions Optional Properties: CategoryName, IncludeTemplateData Access Control Point Name: View Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

737

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Parameters Parameter Name CategoryName Description The CategoryName is an optional action parameter on RetrieveAllForManager. It represents the name of the category which one or more process template belongs to. Optional CategoryName is an optional action parameter on the RetrieveAllForManager action. If specified on the action, it must be greater than 1 character and less than or equal to 50 characters in length. The GetHiddenActions action parameter is a required action parameter on the RetrieveAllForManager action. The GetHiddenActions action parameter can either be "true" or "false". If the GetHiddenActions action parameter is set to "true", all the process templates that have the ActionListSwitch set to 0 will be returned along with those who's value is 1. This implies all of the process templates that are "Hidden" from the Actions list, will be returned along those which are visible on the Actions list. Required GetHiddenActions is a required action parameter on the RetrieveAllForManager action. It must be set to either "true" or "false". Default value: "false" Additional information Introduced in v5.1

GetHiddenActions

Introduced in v5.1

738

Kronos Incorporated

ProcessTemplate Tag

Parameter Name IncludeTemplateData

Description The IncludeTempateData specifies whether information that is returned should include TemplateData. If the IncludeTemplateData action parameter is set to "true", TemplateData is returned for each process template. Optional IncludeTemplateData is an optional action parameter on the RetrieveAllForManager action. It can only be set to "true" or "false". Default value: "false" The ResourceId is a required action parameter on the RetrieveAllForManager action. It represents the id of the resource or manager who will be initiating the process. The ResourceID is equivalent to the WTK Person Number or Person Id value. The ResourceId must match the WFC person number, and it is important to note that trailing blanks are significant and should not be included. Required ResourceId is a required action parameter on the RetrieveAllForManager action. The ResourceId must be greater than 1 character and less than or equal to 30 characters in length.

Additional information Introduced in v5.1

ResourceId

Introduced in v5.1

RetrieveByDisplayName This method returns a process template by specifying the process template display name. The RetrieveByDisplayName action takes one required action parameter called IncludeTemplateData, which can either be set to "true" or "false". If the

Workforce Central Developers Toolkit Reference Guide—Timekeeping

739

Chapter 2

Workforce Timekeeper XML API Tag Definitions

IncludeTemplateData action parameter is set to "true", the TemplateData property will be displayed within the XML Response of the returned process template. If the IncludeTemplateData action parameter is set to "false", the TemplateData property will not be displayed within the returned process template as part of the XML Response. By default, the IncludeTemplateData action parameter is set to "false". If you do not specify the IncludeTemplateData action parameter, the IncludeTemplateData is set to "false" and the TemplateData property will not be displayed for each returned process template. The DisplayName is a required property and must be greater than 1 character and <= 50 characters in length. The IncludeTemplateData is an optional action parameter to RetrieveByDisplayName action. It can only be either "true" or "false" value. Return Value Type: ProcessTemplate tag Required Properties: DisplayName Optional Properties: IncludeTemplateData Access Control Point Name: View Introduced in v5.1

740

Kronos Incorporated

ProcessTemplate Tag

Action Parameters Parameter Name IncludeTemplateData Description The IncludeTemplateData action parameter specifies whether information that is returned should include TemplateData property. If the IncludeTemplateData action parameter is set to "true", TemplateData property is returned for each process template. If you do not specify the IncludeTemplateData as action parameter, the IncludeTemplateData by default is set to "false", and the TemplateData property will not be displayed in the returned process template. Optional IncludeTemplateData is an optional action parameter on the RetrieveByDisplayName action. It can only be set to "true" or "false". Default value: "false" Additional information Introduced in v5.1

RetrieveByUniqueKey This method returns a process template by specifying the KProcessUniqueKey. The action RetrieveByUniqueKey takes one action parameter called IncludeTemplateData, which can either be set to "true" or "false". If the IncludeTemplateData action parameter is set to "true", the TemplateData property will be displayed within the returned process template within the XML Response. If the IncludeTemplateData action parameter is set to "false", the TemplateData property will not be displayed within the returned process template in the returned XML Response. By default, the IncludeTemplateData action parameter is set to "false". If you do not specify the IncludeTemplateData action parameter, the IncludeTemplateData is set to "false" and the TemplateData property will not be displayed for each process template returned. The KProcessUniqueKey is a required property and must be

Workforce Central Developers Toolkit Reference Guide—Timekeeping

741

Chapter 2

Workforce Timekeeper XML API Tag Definitions

1 character and <= 255 characters in length. The IncludeTemplateData is an optional action parameter to RetrieveByUniqueKey action. It can only be either "true" or "false" value. Return Value Type: ProcessTemplate tag Required Properties: KProcessUniqueKey Optional Properties: IncludeTemplateData Access Control Point Name: View Introduced in v5.1
Action Parameters Parameter Name IncludeTemplateData Description The IncludeTempateData specifies whether information that is returned should include TemplateData. If the IncludeTemplateData action parameter is set to "true", TemplateData is returned for each process template. If you do not specify the IncludeTemplateData as action parameter, the IncludeTemplateData by default is set to "false", and the TemplateData property will not be displayed in the process template returned. Optional IncludeTemplateData is an optional action parameter on the RetrieveByUniqueKey action. It can only be set to "true" or "false". Default value: "false" Additional information Introduced in v5.1

UpdateOnly This method updates a process template. The following ProcessTemplate properties cannot be updated through this method: the TemplateId, AdminTemplateId, AdminTemplateName, Version, UsedBy,

742

Kronos Incorporated

ProcessTemplate Tag

KProcessUniqueKey, and TemplateData properties. All other properties of the ProcessTemplate can be updated. This method will allow updates to a process template by assigning a process template to categories. If the CategoryName does not exist, the process template will not be assigned to that category. The category name will not be added to the ProcessTemplate categoryNames list. The UpdateOnly action takes one action parameter called IncludeTemplateData. The IncludeTemplateData action parameter can only be "true" or "false" value. If the IncludeTemplateData action parameter is set to "true", the TemplateData property will be displayed within the process template within the returned XML Response. If the IncludeTemplateData action parameter is set to "false", the TemplateData property will not be displayed within the process template in the returned XML Response. By default, the IncludeTemplateData action parameter is set to "false". If you do not specify the IncludeTemplateData action parameter, the IncludeTemplateData value is set to "false", and the TemplateData property will not be displayed in the returned process template. The AdminTemplateId is a required property. The AdminTemplateId must be greater than 0. The IncludeTemplateData is an optional action parameter. It can only be "true" or "false" value. Return Value Type: ProcessTemplate tag Required Properties: AdminTemplateId Optional Properties: DisplayName, ActiveSwitch, EffectiveDate, ExpirationDate, ActionListSwitch, CommentText, MaxPoolSize, CategoryNames, IncludeTemplateData Access Control Point Name: Edit Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

743

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Parameters Parameter Name IncludeTemplateData Description The IncludeTempateData specifies whether information that is returned should include TemplateData. If the IncludeTemplateData action parameter is set to "true", TemplateData is returned for each process template. If you do not specify the IncludeTemplateData as action parameter, the IncludeTemplateData by default is set to "false", and the TemplateData property will not be displayed in the process template returned. Optional IncludeTemplateData is an optional action parameter on the UpdateOnly action. It must be set to either "true" or "false". Default value: "false" Additional information Introduced in v5.1

Property Descriptions
ActionListSwitch

Is the process visible in the action list?
The ActionListSwitch indicates whether this process is visible in the action list. Type: Integer Required Introduced in v5.1 ActiveSwitch

Is the process active?
The ActiveSwitch indicates whether this process is active.

744

Kronos Incorporated

ProcessTemplate Tag

Type: Integer Required Enumerated value: 0, 1 Introduced in v5.1 AdminTemplateId

Administrator Template Id
The template id used in the Process Manager Process Designer application and in the Process Administrator, used for administrative purposes. Corresponds to the DWEWORKFLOWID column in the WPMWORKFLOW table. Type: Long Required Key Must be greater than zero Sample values: 2101 Introduced in v5.1; last changed in v5.1 AdminTemplateName

Template name
The AdminTemplateName is the name used in the Process Manager Process Designer application and in the Process Administrator, used for administration purposes. Type: String Required Maximum length: 60 characters Sample values: Employee_Award.template Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

745

Chapter 2

Workforce Timekeeper XML API Tag Definitions

CategoryNames

Set of categories
A comma separated list of categories that this process template belongs to. Type: String Optional Maximum length for each CategoryName: 50 characters Introduced in v5.1 CommentText

Comment text
The CommentText is a comment on a process. Type: String Optional Maximum length: 255 characters Introduced in v5.1 DisplayName

Template Display Name
The name or the display name of the process template. Type: String Required Maximum length: 50 characters Sample values: EmployeeAward Introduced in v5.1 EffectiveDate

Effective date

746

Kronos Incorporated

ProcessTemplate Tag

The effective date of this process. Type: DateTime Required Must be a valid KDateTime. Sample values: 12/01/2004 00:00:00 Introduced in v5.1 ExpirationDate

Expiration date
The expiration date of this process. Type: DateTime Required Must be a valid KDateTime Sample values: 01/01/3000 00:00:00 Introduced in v5.1 KProcessUniqueKey

App. Unique Key
The exposed unique ID for the template, the private Unique Key. This ID is created when you create a new process template in the Process Designer. You can use this value to start a process. Type: String Optional Maximum length: 255 characters Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

747

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LastDeployed

Last Deployed Date/Time
A timestamp indicating the date and time at which the template was deployed. Type: DateTime Output only Introduced in v5.2; last changed in v5.2 MaxPoolSize

Max processes in pool
The maximum number of processes that can be in a pool. Type: Integer Optional Must be equal to or greater than zero. The MaxPoolSize cannot be greater than the WFC System Settings Business Automation value for "wba.processengine.server.maxpoolsize". Introduced in v5.1 TemplateData

Template XML
A based-64 encoded string that represents the process template XML. Type: String Required Maximum length: 1 character Introduced in v5.1 TemplateId

Template identifier
The identifier of the process template. Corresponds to the WPMWORKFLOWID column in the WPMWORKFLOW table.

748

Kronos Incorporated

ProcessTemplate Tag

Type: Long Required Key Must be greater than zero Introduced in v5.1 UsedBy

Process profiles that use the template
A comma-separated list of process profiles that use this process template. Type: String Optional Maximum length: 255 characters Introduced in v5.1 Version

Version for optimistic locking
The version number used for optimistic locking. Type: Integer Required Must be greater than zero Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

749

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ProjectingOvertime Tag Projected overtime
This tag provides a projected overtime calculation for a date span for specified locations. Function Access Control Point: Schedule Planner Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" Parameters→ None Properties→ <ProjectingOvertime QueryDateSpan = String > [<Locations> <LocationItem>* </Locations>] </ProjectingOvertime>

Action Descriptions
Load Returns the projecting overtime data. Return Value Type: ProjectingOvertime tag Required Properties: QueryDateSpan Optional Properties: Locations

750

Kronos Incorporated

ProjectingOvertime Tag

Access Control Point Name: View Introduced in v6.0

Property Descriptions
Locations

Locations for overtime projection
Represents a list of locations. Type: Zero or more LocationItem tags Optional Sample values: <Locations> <LocationItem Location="Organization/Hospitals/Hosp A/Floor 1"/> </Locations> Introduced in v6.0; last changed in v6.0 QueryDateSpan

Date span for overtime projection
Represents a date span. Type: String Required Sample values: <QueryDateSpan> 04/23/2006 - 04/29/2006</ QueryDateSpan> Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

751

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Punch Tag Punch
The Punch tag adds a punch or a comment, deletes a punch, or removes the work rule transfer from an existing punch. Function Access Control Point: API.Timecard Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddComment" | "AddOnly" | "AddOnlyWithRestrictions" | "Delete" | "RemoveWorkRule" Parameters→ AddOnly→ [AccrualOverride = Boolean] [allowAdHoc = Boolean] [EchoData = Boolean] AddOnlyWithRestrictions→ [AccrualOverride = Boolean] [EchoData = Boolean] RemoveWorkRule→ [EchoData = Boolean] Properties→ <Punch OrgJobId = String OrgJobName = String [CommentText = String] Date = Date

752

Kronos Incorporated

Punch Tag

(EnteredOnDate = Date) [CancelDeductRuleName = String] [DaylightSavingsFlag = Boolean] [LaborAccountName = String] [ManagerName = String] Time = Time (EnteredOnTime = Time) [KronosTimeZone = String] [OverrideTypeName = String] [WorkRuleName = String] > [<Notes> <Note>* </Notes>] (<Comments> <Comment>* </Comments>) <Employee> <CurrentUser> | <PersonIdentity> </Employee> </Punch>

Action Descriptions
AddComment Adds a comment to an existing punch. Depending on the type of punch, you may need to specify one of the following properties: • • • • LaborAccountName WorkRuleName OverrideTypeName KronosTimeZone

Return Value Type: None Required Properties: CommentText, Date, Employee, Time Access Control Point Name: Edit Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

753

Chapter 2

Workforce Timekeeper XML API Tag Definitions

AddOnly Adds a new punch for an employee. If no date or time are specified, this action uses a timestamp; a new punch is created with the current system date and time, with the time adjusted for the employee's default time zone. If one of date or time is specified, the other must also be specified. An employee can have at most one punch for a given date and time. A punch cannot be added if the date and time precedes or exactly equals the employee's Manager Signoff Date. Return Value Type: Punch tag Required Properties: Employee Optional Properties: Date, Time Access Control Point Name: Edit Introduced in v4

754

Kronos Incorporated

Punch Tag

Action Parameters Parameter Name AccrualOverride Description If the action results in an accrual warning, the warning is overridden when AccrualOverride=True. Optional Default value: False Specifies whether an ad hoc labor level is allowed. Optional Default value: False If True, the Response includes a copy of the tag. Optional Default value: False Additional information Introduced in v4

allowAdHoc

Introduced in v5.0; last changed in v5.0; deprecated in v5.0. Not used Introduced in v4

EchoData

AddOnlyWithRestrictions Adds a new punch for an employee. If no date or time are specified, this action uses a timestamp; a new punch is created with the current system date and time, with the time adjusted for the employee's default time zone. If one of date or time is specified, the other must also be specified. An employee can have at most one punch for a given date and time. A punch cannot be added if the date and time precedes or exactly equals the employee's Manager Signoff Date. If no date/time specified, punch restriction rule will apply Return Value Type: Punch tag Required Properties: Employee Optional Properties: Date, Time Access Control Point Name: Edit Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

755

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Parameters Parameter Name AccrualOverride Description If the action results in an accrual warning, the warning is overridden when AccrualOverride=True. Optional Default value: false If True, the Response includes a copy of the tag. Optional Default value: false Additional information Introduced in v6.0; last changed in v6.0

EchoData

Introduced in v6.0; last changed in v6.0

Delete Marks an existing punch for deletion. Return Value Type: None Required Properties: Date, Employee, Time Access Control Point Name: Edit Introduced in v4 RemoveWorkRule Removes the work rule transfer from an existing punch. Return Value Type: Punch tag Required Properties: Date, Employee, Time Access Control Point Name: Edit Introduced in v4

756

Kronos Incorporated

Punch Tag

Action Parameters Parameter Name EchoData Description If True, the Response includes a copy of this tag. Optional Default value: False Additional information Introduced in v4

Property Descriptions
OrgJobId

ID of job in organization
A unique identifier for a job in the organization Type: String You must have Functional Access for Job Transfers. A node with this Id must exist in the organizational structure Default value: Null Introduced in v5.0 OrgJobName

Job in the organization
The primary organizational job information for the employee. You can optionally specify OrgJobName or OrgJobId. You can leave this column blank if the punch applies to the employee's primary organizational job. Enter data for OrgJobName in the same format as it appears in the database. The OrgJobName string matching is case-sensitive on a server that connects to an Oracle database. Type: String Maximum length: 1000 characters You must have Functional Access for Job Transfers. A node with this Id must exist in the organizational structure

Workforce Central Developers Toolkit Reference Guide—Timekeeping

757

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Default value: Null Introduced in v5.0 CancelDeductRuleName

Deduct rule for cancellation override
Specifies the deduct rule to be used Type: String Optional Cancel deduction rules can be found in the user interface. Either select one of these, or type 'All' to cancel all deductions for the day. Introduced in v4 Comments

Comments
The set of comments that are returned with this timekeeping item Type: Zero or more Comment tags Output Only Introduced in v4 CommentText

Comment text
Use comment text to provide details about the punch. It contains a comment string that is attached to the punch. Type: String Optional Maximum length: 254 characters Must match exactly an applicable comment that already exists in the database. The string matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application.

758

Kronos Incorporated

Punch Tag

Introduced in v4 Date

Date of punch
Date contains one of the following entries: • • • The date of a punch that is being added or deleted The date of a punch for which you are adding a comment The date of a punch for which the work rule is being cleared

Type: Date Optional Key Dependency: If Date is specified, Time must also be specified. Introduced in v4; last changed in v5.0 DaylightSavingsFlag

Is daylight-saving time in effect?
True if daylight saving time is in effect for the specified time zone. Type: Boolean Optional Ignored if the time zone does not support Daylight Savings Time Default value: False Enumerated value: True, False Introduced in v4 Employee

Employee
One employee for whom the punch is credited, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Required, Key

Workforce Central Developers Toolkit Reference Guide—Timekeeping

759

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Must uniquely identify an existing and active employee Introduced in v4; last changed in v5.0 EnteredOnDate

Date of the edit
The server date on which the edit is added to the database Type: Date Output Only Introduced in v4 EnteredOnTime

Time of the edit
The server time at which the edit is added to the database Type: Time Output Only Introduced in v4 KronosTimeZone

Time zone
The time zone used for the punch. Specify either the name of the time zone or the five-digit KronosTimeZone. If the KronosTimeZone was specified when a punch was added, it must also be used to perform another action such as delete, clear, or add a comment. Type: String Optional Maximum length: 30 characters For a list of values, see "Time Zone Definitions" in Appendix B in the Timekeeping DTK Reference Guide. Sample values: 13011, Eastern

760

Kronos Incorporated

Punch Tag

Default value: Time zone at the employees server Introduced in v4 LaborAccountName

Labor account name
The name of the labor account that is associated with the punch. This is optional when adding a punch. It need not be specified if the punch applies to the employee's primary account. To specify a labor account name, enter it in the same format as it appears in the database. For example, if you have a seven-level labor account in the Timekeeping configuration, specify a value for each labor level, using the following format: 101/202/303/404/504/603/702. You can omit any labor levels that are not changing; for example, you can enter the value 101//303////, indicating that only the first and third labor level entries are different. If any of the labor levels should be the same as the employee's primary labor account, specify @H for those labor levels. If your Timekeeping system is set up to allow you to create ad hoc labor level entries when adding a punch, you can create the ad hoc entries when specifying the labor account. Type: String Optional Maximum length: 356 characters. You can find values in the Timekeeping user interface. Introduced in v4 ManagerName

Manager name
The name to replace the user name in audit. Type: String Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

761

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Maximum length: 70 characters Introduced in v5.0a Notes

Comment Notes
The list of notes for the comment to be created from comment text Type: Zero or more Note tags Optional Introduced in v6.0 OverrideTypeName

Type of override
The type of override Type: String Optional Maximum length: 30 characters Enumerated value: In Punch, Out Punch, New Shift, or an associated Break Rule name as defined in the Workforce Timekeeper Setup Introduced in v4 Time

Time
Time contains one of the following items: • • • The time when the punch is added or deleted The time when you are adding a comment for the punch The time of the punch for which the work rule is being cleared

Type: Time Optional Key

762

Kronos Incorporated

Punch Tag

The combination of Date and Time must be unique for all non-deleted punches for an employee. Dependency: If Date is specified, Time must also be specified. Introduced in v4 WorkRuleName

Work rule
This is the work rule associated with the punch. A work rule applies a different set of pay rules to the employee's time. The application of these rules determines how employee hours are calculated. Dependency: Enter this value only when a work rule other than the employee's usual work rule is to be used. The following predefined data values are provided: • • &ALL_WORK_RULES &EMPTY

Type: String Optional Maximum length: 50 characters You can find values in Timekeeping Setup. Sample values: Salaried, Part Time Introduced in v4

Groups of Mutually Exclusive Properties
OrgJob Organization Job ID or Name: If ID is supplied, Name is ignored. Optional Group includes: OrgJobId, OrgJobName

Workforce Central Developers Toolkit Reference Guide—Timekeeping

763

Chapter 2

Workforce Timekeeper XML API Tag Definitions

PunchStatus Tag Punch Status
The PunchStatus tag checks the employee's punch in/punch out status. It returns punch-in time and labor account transfer, if the employee has punched in. Function Access Control Point: API.Timecard Introduced in v5.0; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "CheckStatus" Parameters→ None Properties→ <PunchStatus [Time = DateTime] [DaylightSavingsFlag = Boolean] [KronosTimeZone = Integer] > <Employee> <PersonIdentity> </Employee> (<LaborAccountName> <LaborAccount> </LaborAccountName>) </PunchStatus>

Action Descriptions

764

Kronos Incorporated

PunchStatus Tag

CheckStatus Returns the status (In or Out) of the punch. Return Value Type: PunchStatus tag Required Properties: Employee Access Control Point Name: View Introduced in v5.0; last changed in v5.1

Property Descriptions
DaylightSavingsFlag

Is daylight-saving time in effect?
Whether daylight saving time is in effect for the specified date and time. When returning within status, it is the daylight saving time associated with the punch. Type: Boolean Optional Default value: False Enumerated value: True, False Introduced in v5.0 Employee

Employee
One employee, as specified in a PersonIdentity tag. Type: PersonIdentity tag Required Must uniquely identify an existing and active employee Introduced in v5.0 KronosTimeZone

Time zone

Workforce Central Developers Toolkit Reference Guide—Timekeeping

765

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The timezone associated with the date and time. When returning within status, it is the timezone of the punch. Type: Integer Optional For a list of values, see "Time Zone Definitions" in Appendix B in the Timekeeping DTK Reference Guide. Sample values: 13011 Default value: The application server timezone Introduced in v5.0; last changed in v5.0 LaborAccountName

Labor account
If the punch status is in, returns the current labor account transfer Type: LaborAccount tag Output only Maximum length:356 characters Introduced in v5.0 Time

Date and time of punch
The date and time of a punch. When returned by the system, it contains the time of the punch. Type: DateTime Optional Sample values: 06/17/2003 10:00AM Default value: Current time

766

Kronos Incorporated

PunchStatus Tag

Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

767

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RBSRule Tag Rest Between Shifts Rule
Rest Between Shifts Function Access Control Point: API.Timekeeping Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Delete" | "Retrieve" | "RetrieveAll" | "RetrieveAllNames" | "RetrieveByName" | "RetrieveForUpdate" | "Update" Parameters→ None Properties→ <RBSRule Name = String > [<RBSRuleVersions> <RBSRuleVersion>* </RBSRuleVersions>] </RBSRule>

Action Descriptions
Delete Delete the named RBS Rule

768

Kronos Incorporated

RBSRule Tag

Rule cannot be deleted if linked to a work rule. Return Value Type: None Required Properties: Name Access Control Point Name: Edit Introduced in v5.2 Retrieve Returns the RBS Rule with the given name. Return Value Type: RBSRule tag Required Properties: Name Access Control Point Name: View Introduced in v5.2 RetrieveAll Retrieve all RBS rules. Return Value Type: Zero or more RBSRule tags Access Control Point Name: View Introduced in v5.2 RetrieveAllNames Returns the names of all RBS Rules defined in the system. Return Value Type: Zero or more NameList tags Access Control Point Name: View Introduced in v5.2 RetrieveByName Retrieve named RBS rule. Return Value Type: RBSRule tag Required Properties: Name Access Control Point Name: View Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

769

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RetrieveForUpdate Retrieve RBSRule For Update. Name length should be between 1 to 30. Return Value Type: RBSRule tag Required Properties: Name Access Control Point Name: Edit Introduced in v5.2 Update Updates the RBS Rule with the given name. If the rule does not exist, then it will be created. Return Value Type: None Required Properties: Name Optional Properties: RBSRuleVersions Access Control Point Name: Edit Introduced in v5.2

Property Descriptions
Name

Rule Name
The name of the RBS Rule Type: String Required Key Rule name has to comply with the general rules for the WFC rule names. The rule name has to be at least one character long. Introduced in v5.2 RBSRuleVersions

RBS Rule Data Versions in the RBS Rule

770

Kronos Incorporated

RBSRule Tag

The data versions of the RBS Rule Type: Zero or more RBSRuleVersion tags Optional Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

771

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RBSRuleVersion Tag RBS Rule Data Version
The Data Version of the RBS Rule Function Access Control Point: API.Timekeeping Introduced in v5.2; last changed in v5.2

Syntax
Properties→ <RBSRuleVersion ApplyPremiumToEntireShift = Boolean IsRestIntervalContinuous = Boolean [MaxRestPremiumDuration = TimeDuration] [MinRestPremiumDuration = TimeDuration] [MinShiftLengthDuration = TimeDuration] [Description = String] RuleName = String RequiredRestDuration = TimeDuration LookbackDuration = TimeDuration OutPunchOption = Integer InPunchOption = Integer UnscheduledShiftIsRest = Boolean > </RBSRuleVersion>

Property Descriptions
ApplyPremiumToEntireShift

Apply Premium To Entire Shift
A flag specifying whether to apply RBS premium to the entire shift. If set to false - the premium is applied to the amount of denied rest. If the duration of denied rest is greater than the duration of a shift, the premium is applied to the duration of a shift. If this flag is set to true, RBS premium is applied to the whole duration of a shift. Type: Boolean

772

Kronos Incorporated

RBSRuleVersion Tag

Required Default value: false Introduced in v5.2 Description

RBS Rule Data Version Description
The description of the RBS Rule Data Version Type: String Optional Introduced in v5.2 InPunchOption

Shift Start
The option specifying whether to consider a shift's start at Rounded Punch, Actual Punch or Scheduled Punch time stamp.The allowable values are 0 - for Rounded Punch, 1 - for Actual Punch, 2 - for Scheduled Punch Type: Integer Required Introduced in v5.2 IsRestIntervalContinuous

Continuous Rest Interval
This flag specifies if the rest between shifts is required to be continuous in order foe the employee to qualify for the Rest Between Shifts premium. If it is set to true, the rest is required to be continuous, if it is set to false, the rest is not required to be continuous, all rest intervals within a lookback window will be considered. Type: Boolean Required Default value: false Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

773

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LookbackDuration

Rest Interval Window
The duration of the lookback window from the start of a shift in which the rest intervals are counted to determine whether the shift qualifies for the Rest Between Shift premium. Type: TimeDuration Required Default value: 0:00 Introduced in v5.2 MaxRestPremiumDuration

Maximum Rest Premium
The maximum duration of the Rest Between Shifts premium Type: TimeDuration Optional Introduced in v5.2 MinRestPremiumDuration

Minimum Rest Premium
The duration of the Minimum RBS Rest Premium Type: TimeDuration Optional Introduced in v5.2 MinShiftLengthDuration

Minimum Shift Length
The minimum duration of a shift to qualify for the Rest Between Shifts premium Type: TimeDuration Optional

774

Kronos Incorporated

RBSRuleVersion Tag

Introduced in v5.2 OutPunchOption

Shift End
The option specifying whether to consider shift's end at Rounded Punch, Actual Punch or Scheduled Punch time stamp.The allowable values are 0 - for Rounded Punch, 1 - for Actual Punch, 2 - for Scheduled Punch Type: Integer Required Introduced in v5.2 RequiredRestDuration

Required Rest
The duration of the required rest between shifts Type: TimeDuration Required Should be less than the duration of the LookbackDuration Introduced in v5.2 RuleName

RBS Rule Name
The name of the RBS Rule, that this data belongs to Type: String Required See validation for the RBSRule Name Introduced in v5.2 UnscheduledShiftIsRest

Unscheduled Shifts Count As Rest

Workforce Central Developers Toolkit Reference Guide—Timekeeping

775

Chapter 2

Workforce Timekeeper XML API Tag Definitions

A flag specifying whether unscheduled shifts count as rest or as work. If true unscheduled shifts count as rest, if false - unscheduled shifts count as work Type: Boolean Required Default value: false Introduced in v5.2

776

Kronos Incorporated

ReportProfile Tag

ReportProfile Tag Report Profile
The ReportProfile tag shows the report profile assigned to a manager. A Report Profile defines which reports the Manager can view or run. Function Access Control Point: API.Employee Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllReportProfiles" | "LoadById" Parameters→ None Properties→ <ReportProfile [ReportProfileId = Integer] [ReportProfileName = String] > </ReportProfile>

Action Descriptions
Load Returns a report profile, based on ReportProfileName. Name should be valid Return Value Type: ReportProfile tag Required Properties: ReportProfileName

Workforce Central Developers Toolkit Reference Guide—Timekeeping

777

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: View Introduced in v4 LoadAllReportProfiles Returns a list of all report profiles in the system. Return Value Type: Zero or more ReportProfile tags Required Properties: None Access Control Point Name: View Introduced in v4 LoadById Returns a report profile, based on ReportProfileId. ID must be valid Return Value Type: ReportProfile tag Required Properties: ReportProfileId Access Control Point Name: View Introduced in v4

Property Descriptions
ReportProfileId

Id of report profile
Uniquely identifies the report data access profile in the database Type: Integer Optional Introduced in v4 ReportProfileName

Report profile name
The name for the common set of reports that a group of users can access. For example, IS Reports.

778

Kronos Incorporated

ReportProfile Tag

Type: String Optional Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

779

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Request Tag Request
The Request tag is a container for other XML tags. If an XML tag is actionable, it is contained in a Request tag. If it is not actionable, a Request tag must not be specified. Note: There are contained API tags listed in the syntax that are not part of the platform or timekeeping. These tags are in add-on products such as Activities or Scheduling. Function Access Control Point: API.XML Introduced in v4; last changed in v5.1

Syntax
Properties→ <Request Action = String [OnError = String] [DataSource = String] [Password = Password] [ProcessAsManager = Boolean] [Sequence = String] [Object = String] [FailureURL = String] [SuccessURL = String] [UserName = String] > </Request>

Property Descriptions
Action

Action for the request
The action to apply to the contained tags Type: String

780

Kronos Incorporated

Request Tag

Required Action must be supported by all contained tags Introduced in v4 DataSource

Data source (application) submitting the request
Instantiates a DataSource in the thread state, creating it in the database if necessary Type: String Optional Introduced in v4 FailureURL

URL to display for a failed response
A URL used to redirect a failed response Type: String Optional Introduced in v4 Object

Tag specified as an object of the Request
Object name of the contained tag Type: String Optional Required: When specifying System for Logon, Logoff, or Ping Required: When the contained object is omitted Introduced in v4 OnError

Action to take after error (continue or stop)

Workforce Central Developers Toolkit Reference Guide—Timekeeping

781

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Indicates whether to continue or stop after an error is encountered Type: String Optional Enumerated value: Continue, Stop Introduced in v4 Password

Password
Logon password Type: Password Optional Required: For logon Action Introduced in v4; last changed in v5.0 ProcessAsManager

Process requests using Manager role
Specifies whether to process the XML APIs within the request using the Manager's role: • • True - process using Manager's role False - process using Employee role.

Type: Boolean Optional Sample values: true Default value: false Introduced in v5.1; last changed in v5.1 Sequence

Sequence

782

Kronos Incorporated

Request Tag

A user-supplied sequence string that is returned in the corresponding Response tag Type: String Optional Maximum length: There is no maximum length other than what your operating system can accommodate. Introduced in v4 SuccessURL

URL to display for a successful response
A URL used to redirect a successful response Type: String Optional Introduced in v4 UserName

User name
The logon user id Type: String Optional Required: For logon Action Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

783

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RequestToCover Tag Request to cover another shift
This tag will provide all the needed actions to assign a shift to an employee to cover another shift. Function Access Control Point: API.Schedule Introduced in v5.1; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AssignCoverShift" | "LoadEligibleEmployees" | "LoadShifts" Parameters→ None Properties→ <RequestToCover [IsCheckRules = Boolean] [QueryDate = Date] (IsShiftExists = Boolean) [PartialEndDate = Date] [PartialEndTime = Time] [IsSaveData = Boolean] [QueryDateTimeSpan = DateTimeSpan] [PartialStartDate = Date] [PartialStartTime = Time] > (<RequestToCoverItems> <RequestToCoverItem>* </RequestToCoverItems>) (<RequestToCoverStatus> <CoverShiftStatus>

784

Kronos Incorporated

RequestToCover Tag

</RequestToCoverStatus>) <Employee> <Personality> </Employee> (<RuleViolations> <RuleViolation>* </RuleViolations>) <Employees> <PersonIdentity>* </Employees> </RequestToCover>

Action Descriptions
AssignCoverShift AssignCoverShift assigns a shift to an employee to cover another shift. Return Value Type: Zero or more RuleViolation tags Required Properties: QueryDateTimeSpan, Employees Optional Properties: PartialStartDate,PartialEndDate,PartialStartTime,PartialEndTime,IsSaveData,IsC heckRules Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 LoadEligibleEmployees LoadEligibleEmployees returns eligible employees who can work for the specified shift. Return Value Type: RequestToCover tag Required Properties: QueryDateTimeSpan, Employee Access Control Point Name: View Introduced in v5.1; last changed in v5.1 LoadShifts The LoadShifts action will load all shifts for the specified employee and a query date.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

785

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Return Value Type: RequestToCover tag Required Properties: QueryDate,Employee Access Control Point Name: View Introduced in v5.1; last changed in v5.1

Property Descriptions
Employee

Requesting employee
The employee who requests his/her shift to be covered. Type: Personality tag Optional Key It must be an active employee. Introduced in v5.1; last changed in v5.2 Employees

Two employees (requesting and covering)
This property represents 2 employees for whom one's shift is to be covered by the other one. Type: Zero or more PersonIdentity tags Optional Key The size must be 2. Introduced in v5.1; last changed in v5.2 IsCheckRules

Check rules?
This property indicates whether schedule rule validation should be checked. Type: Boolean Optional

786

Kronos Incorporated

RequestToCover Tag

Introduced in v5.1; last changed in v5.1 IsSaveData

Save changes?
This property indicates whether the changes made by an action will be persisted to the database. Type: Boolean Optional Introduced in v5.1; last changed in v5.1 IsShiftExists

Does the shift exist?
This property holds the result of whether is the shift existing. Type: Boolean Output only Introduced in v5.1; last changed in v5.1 PartialEndDate

End date of replacement shift
The end date of a shift which will override partial or full schedule of the open shift. Type: Date Optional Introduced in v5.1; last changed in v5.1 PartialEndTime

End time of replacement shift
The end time of a shift which will override partial or full schedule of the open shift. Type: Time

Workforce Central Developers Toolkit Reference Guide—Timekeeping

787

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Introduced in v5.1; last changed in v5.1 PartialStartDate

Start date of replacement shift
The beginning date of a shift which will override partial or full schedule of the open shift. Type: Date Optional Introduced in v5.1; last changed in v5.1 PartialStartTime

Start time of replacement shift
The beginning time of a shift which will override partial or full schedule of the open shift. Type: Time Optional Introduced in v5.1; last changed in v5.1 QueryDate

Date to query
The date to query for a specified employee's shifts. Type: Date Optional It must be a valid date. Introduced in v5.1; last changed in v5.2 QueryDateTimeSpan

Schedule date and time span

788

Kronos Incorporated

RequestToCover Tag

This property represents the start date and time and end date and time of a schedule. Type: DateTimeSpan Optional It must be a valid date time span. Introduced in v5.1; last changed in v5.1 RequestToCoverItems

Date and time span
This property contains a shift's date time span information. Type: Zero or more RequestToCoverItem tags Output only Introduced in v5.1; last changed in v5.1 RequestToCoverStatus

Request To Cover Status
This property is the status of the result. Type: CoverShiftStatus tag Output only Introduced in v5.1; last changed in v5.1 RuleViolations

Rule violations generated
RuleViolations is the set of rule violations that was generated by the tag. Type: Zero or more RuleViolation tags Output only Introduced in v5.1; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

789

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RequestToCoverItem Tag Request To Cover Item
This tag represents the result of execution of the OpenShifts tag. Function Access Control Point: API.Schedule Introduced in v5.1; last changed in v5.1

Syntax
Properties→ <RequestToCoverItem (DateTimeSpan = DateTimeSpan) > (<OrgJobPaths> <LocationItem>* </OrgJobPaths>) </RequestToCoverItem>

Property Descriptions
DateTimeSpan

Date and time span
This property represents a date and time span of a valid shift. Type: DateTimeSpan Output only none Introduced in v5.1; last changed in v5.1 OrgJobPaths

Organization job paths
This property represents a set of valid organization jobs. Type: Zero or more LocationItem tags Output only

790

Kronos Incorporated

RequestToCoverItem Tag

none Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

791

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ResetAccrual Tag Accrual Reset
The ResetAccrual tag specifies values to use when resetting amounts for a specified accrual code and employee. The accrual code determines whether an AmountInTime or AmountInCurrency must be specified. Function Access Control Point: API.Accruals Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Update" Parameters→ None Properties→ <ResetAccrual AmountInCurrency = Currency AmountInTime = TimeDuration AmountInTimeOrCurrency = String ProbationAmountInCurrency = Currency ProbationAmountInTime = TimeDuration AccrualCodeName = String Date = Date > <Employee> <CurrentUser> | <PersonIdentity> </Employee> </ResetAccrual>

792

Kronos Incorporated

ResetAccrual Tag

Action Descriptions
Update Resets an accrual amount for the specified accrual code. The accrual code is used to determine the amount types, time duration, or currency. Updates information for one employee Either AmountInTime or AmountInCurrency must be specified. Return Value Type: None Required Properties: AccrualCodeName, Date, Employee Access Control Point Name: Edit Introduced in v4

Property Descriptions
AmountInCurrency

Amount of accrual, in currency
The new monetary value for the employee's accrual balance Type: Currency Maximum length: 30 characters Default value: 0.00 Introduced in v4 AmountInTime

Amount of accrual, in time
The new time span value for the employee's accrual balance Type: TimeDuration Maximum length: 30 characters Default value: 0.0 or 0:0 Introduced in v4; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

793

Chapter 2

Workforce Timekeeper XML API Tag Definitions

AmountInTimeOrCurrency

Amount of accrual, in time or currency
The amount to be added or decremented to the current balance for a specified accrual code and employee. This value can be formatted either as a time value or a currency, depending on the format needed for the specified accrual code. Type: String AmountInTimeOrCurrency belongs to the AccrualAmount group. Only one member of the group can be used. Introduced in v5.1; last changed in v5.1 ProbationAmountInCurrency

Probationary amount, in currency
The amount, expressed as a currency, in which accrual balances are earned but cannot be taken or paid. This property is optional when resetting an accrual balance. If you do not specify a value for ProbationaryAmountInCurrency or ProbationaryAmountInTime, then the probation amount defaults to zero. Dependency: If you specify a value for this property, you must also have a value in AmountInCurrency. Type: Currency Maximum length: 15 characters Introduced in v4 ProbationAmountInTime

Probationary amount, in time
The amount, expressed as a time duration, in which accrual balances are earned but cannot be taken or paid. This property is optional when resetting an accrual balance. If you do not specify a value for ProbationaryAmountInCurrency or ProbationaryAmountInTime, then the probation amount defaults to zero. Dependency: If you specify a value for this property, you must also have a value in AmountInTime. Type: TimeDuration

794

Kronos Incorporated

ResetAccrual Tag

Maximum length: 15 characters Introduced in v4 AccrualCodeName

Accrual code name
The accrual code associated with the transaction. Type: String Required Maximum length: 50 characters The accrual code must be created in Workforce Timekeeper Setup Application and assigned to the employee before you can import data against it. Sample values: Vacation, Sick Introduced in v4 Date

Date
The date when the accrual transaction is effective Type: Date Required Introduced in v4 Employee

Employee
One employee, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Required Key Must uniquely identify an existing and active employee

Workforce Central Developers Toolkit Reference Guide—Timekeeping

795

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v4

Groups of Mutually Exclusive Properties
Amount/Currency Mutually Exclusive group for AmountInTimeOrCurrency, AmountInTime and AmountInCurrency Required Group includes: AmountInCurrency, AmountInTime, AmountInTimeOrCurrency Probation Amount/Currency Mutually Exclusive group for Probation AmountInCurrency and Probation AmountInTime Optional Group includes: ProbationAmountInCurrency, ProbationAmountInTime

796

Kronos Incorporated

Response Tag

Response Tag Response
The Response tag is a container for all response information that is sent back to the client application. A Response tag corresponds to a Request tag, which can contain any number of XML API tags. All XML API tags specified in the request are echoed in the response, unless the EchoData action parameter is specified as False for the tag. Note: EchoData can not be specified for all XML API tags. Function Access Control Point: API.XML Introduced in v4; last changed in v5.0

Syntax
Properties→ <Response (Message = String) (Sequence = String) (Status = String) (TransactionSequence = String) > </Response>

Property Descriptions
Message

Message if request fails
This message is generated if a failure occurs and explains the reason for the failure Type: String Output Only Introduced in v4 Sequence

Sequence specified in request

Workforce Central Developers Toolkit Reference Guide—Timekeeping

797

Chapter 2

Workforce Timekeeper XML API Tag Definitions

A user-supplied sequence string returned in the corresponding Response tag Type: String Output Only Introduced in v4 Status

Status of response
The status resulting from the corresponding Request Type: String Output Only Enumerated value: Success, Failure Introduced in v4 TransactionSequence

Transaction sequence specified in transaction
A user-supplied sequence string specified in the Transaction tag and returned in the Response tags for every Request in the transaction Type: String Output Only Introduced in v4

798

Kronos Incorporated

RoleProfileKBO Tag

RoleProfileKBO Tag Role Profile API
The tag allows user to view, list, update, create, duplicate and delete role profile. Function Access Control Point: API.DelegateAuthority.RoleProfile Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "Delete" | "Duplicate" | "Retrieve" | "RetrieveAll" | "RetrieveAllNames" | "RetrieveForUpdate" | "RetrieveRoleProfiles" | "Update" | "UpdateOnly" Parameters→ Update→ [NewName = String] UpdateOnly→ [NewName = String] Properties→ <RoleProfileKBO [AccessProfileName = String] [Description = String] [PreferenceProfileName = String] [Name = String] > </RoleProfileKBO>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

799

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Descriptions
AddOnly Adds the role profile with the given [Name] to the database. Return Value Type: None Required Properties: Name,AccessProfileName,PreferenceProfileName Optional Properties: Description Access Control Point Name: Edit Introduced in v5.2; last changed in v5.2 Delete Deletes the role profile by name Return Value Type: None Required Properties: Name Access Control Point Name: Edit Introduced in v5.2; last changed in v5.2 Duplicate Creates a duplicate of the existing role profile with the name "copy of [Name]" Return Value Type: None Required Properties: Name Access Control Point Name: Edit Introduced in v5.2; last changed in v5.2 Retrieve The length of the name should not exceed 50. The length of the name should not exceed 50. Return Value Type: (***undefined***): Required Properties: Name Access Control Point Name: View

800

Kronos Incorporated

RoleProfileKBO Tag

Introduced in v5.2 RetrieveAll Retrieves all the available RoleProfile objects. Return Value Type: Zero or more RoleProfileKBO tags Access Control Point Name: View Introduced in v5.2 RetrieveAllNames Return the collection of names of RoleProfile objects required for Setup Data Manager. Return Value Type: Collection list Access Control Point Name: View Introduced in v5.2 RetrieveForUpdate Returns a single instance of RoleProfileKBO which can be used for Update by SDM. Return Value Type: RoleProfileKBO tag Required Properties: Name Access Control Point Name: View Introduced in v5.2 RetrieveRoleProfiles Retrieves list of all profiles in the database Return Value Type: (***undefined***): Access Control Point Name: View Introduced in v5.2 Update This method will update if the RoleProfile object exists with the given name otherwise creates a new a object. Return Value Type: None Required Properties: Name

Workforce Central Developers Toolkit Reference Guide—Timekeeping

801

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Properties: Description Access Control Point Name: Edit Introduced in v5.2; last changed in v5.2
Action Parameters Parameter Name NewName Description RoleProfile will be created with the given NewName if it doesn't exist already. Optional Additional information Introduced in v5.2

UpdateOnly Updates the role profile info in the delegaterole table name should not exceed 50 chars Return Value Type: None Required Properties: Name Optional Properties: Description, AccessProfileName, PreferenceProfileName Access Control Point Name: Edit Introduced in v5.2; last changed in v5.2
Action Parameters Parameter Name NewName Description The new name of the RoleProfile that will be updated as the given New Name parameter. Optional Additional information Introduced in v5.2

Property Descriptions
AccessProfileName

Access Profile Name

802

Kronos Incorporated

RoleProfileKBO Tag

The function Access Profile Name that will be included as part of the Role Profile. Type: String Optional Introduced in v5.2 Description

Description
Role Profile Description Type: String Optional Introduced in v5.2 Name

Role Profile Name
Name of the Role Profile that will be retrieved. Type: String Optional Introduced in v5.2 PreferenceProfileName

Display Profile Name
The Display Profile Name that will be included as part of the Role Profile. Type: String Optional Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

803

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RuleSetEmployeeAssign Tag Rule Sets Assigned to Employees
The RuleSetEmployeeAssign tag assigns one or more rule sets to one or more employees. Function Access Control Point: API.RuleEvaluation Introduced in v5.0; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "Update" Parameters→ None Properties→ <RuleSetEmployeeAssign [PersonNumber = String] > <Employees> <PersonIdentity>* </Employees> <EmployeeRuleSetItems> <EmployeeRuleSetItem>* </EmployeeRuleSetItems> </RuleSetEmployeeAssign>

Action Descriptions
Load Returns the rule set assignments for an employee

804

Kronos Incorporated

RuleSetEmployeeAssign Tag

Required Properties: PersonNumber Access Control Point Name: View Introduced in v5.0 Update Assigns rule sets to one or more employees. Return Value Type: None Required Properties: EmployeeRuleSetItems, Employees Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0

Property Descriptions
EmployeeRuleSetItems

Rules in the rule set
The rule sets that are assigned to the specified employees Type: Zero or more EmployeeRuleSetItem tags Required Introduced in v5.0 Employees

Employees
One or more employees for whom the rule set is assigned, as specified in one or more PersonIdentity tags. Type: Zero or more PersonIdentity tags Required Each employee specified must have a WFS license. Introduced in v5.0; last changed in v5.0 PersonNumber

Person number

Workforce Central Developers Toolkit Reference Guide—Timekeeping

805

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Person number of the person about whom information is returned Type: String Optional Maximum length: 15 characters This person must have WFS license. Introduced in v5.0; last changed in v5.0

806

Kronos Incorporated

SchedGenSettings Tag

SchedGenSettings Tag Schedule Generator settings
Used to configure schedule generator engine run options. Function Access Control Point: Location Settings Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Add" | "AddOnly" | "Delete" | "DeleteOnly" | "Retrieve" | "RetrieveAll" | "RetrieveAllForUpdate" | "RetrieveAllNames" | "RetrieveForUpdate" | "Update" | "UpdateOnly" Parameters→ None Properties→ <SchedGenSettings [Description = String] SettingsName = String > [<OrgPaths> <SimpleValue>* </OrgPaths>] [<SettingsParamValues> <SettingsParamValue>*

Workforce Central Developers Toolkit Reference Guide—Timekeeping

807

Chapter 2

Workforce Timekeeper XML API Tag Definitions

</SettingsParamValues>] </SchedGenSettings>

Action Descriptions
Add Add a schedule generator settings object into the system. If it already exists an update is performed. Return Value Type: None Required Properties: SettingsName Optional Properties: Description, SettingsParamValues, OrgPaths Access Control Point Name: Edit Introduced in v6.0 AddOnly Add a new schedule generator settings object into the system. If it already exists an error is thrown. Return Value Type: None Required Properties: SettingsName Optional Properties: Description, SettingsParamValues, OrgPaths Access Control Point Name: Edit Introduced in v6.0 Delete Delete a schedule generator settings object. If the object doesn't exist, no exception is thrown. Return Value Type: None Required Properties: SettingsName Access Control Point Name: Edit Introduced in v6.0

808

Kronos Incorporated

SchedGenSettings Tag

DeleteOnly Delete a schedule generator settings object with the specified name. If the object doesn't exist, an error is thrown. Return Value Type: None Required Properties: SettingsName Access Control Point Name: Edit Introduced in v6.0 Retrieve Return the schedule generator settings object with the specified name. Return Value Type: SchedGenSettings tag Required Properties: SettingsName Access Control Point Name: View Introduced in v6.0 RetrieveAll Return all the schedule generator settings objects. Return Value Type: Zero or more SchedGenSettings tags Access Control Point Name: View Introduced in v6.0 RetrieveAllForUpdate Return a list of schedule generator settings objects. This action is used for future updates. Return Value Type: Zero or more SchedGenSettings tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Return a schedule generator settings names list. Return Value Type: (***undefined***): KBusinessObjectNameList Access Control Point Name: View

Workforce Central Developers Toolkit Reference Guide—Timekeeping

809

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v6.0 RetrieveForUpdate Return the schedule generator settings object with the specified name. This action is used for future updates. Return Value Type: SchedGenSettings tag Required Properties: SettingsName Access Control Point Name: View Introduced in v6.0 Update Update the schedule generator settings object. If it does not exist an add is performed. Return Value Type: None Required Properties: SettingsName Optional Properties: Description, SettingsParamValues, OrgPaths Access Control Point Name: Edit Introduced in v6.0 UpdateOnly Update a schedule generator settings object. If it does not exist an error is thrown. Return Value Type: None Required Properties: SettingsName Optional Properties: Description, SettingsParamValues, OrgPaths Access Control Point Name: Edit Introduced in v6.0

Property Descriptions
Description

Description of Schedule Generator setting
Represents the schedule generation settings object's description.

810

Kronos Incorporated

SchedGenSettings Tag

Type: String Optional Sample values: <Description> This is a description.</Description> Introduced in v6.0; last changed in v6.0 OrgPaths

Location path
Represents the organizational nodes associated to a schedule generator settings object. Type: Zero or more SimpleValue tags Optional Path must be valid on this date. Path must be acessible to logged-on user. Sample values: <OrgPaths> <SimpleValue Value="Organization/Hospitals/Hosp A/ Floor 1" /> </OrgPaths> Introduced in v6.0; last changed in v6.0 SettingsName

Name of Schedule Generator setting
Represents the schedule generation setting's name. Type: String Required Key Sample values: <SettingsName> ThisIsAName</SettingsName> Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

811

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SettingsParamValues

Settings objectsparametersvalues'
Represents the schedule generator settings object's parameters values. Type: Zero or more SettingsParamValue tags Optional Parameter names must be SchedGenSettings type parameters. Sample values: <SettingsParamValues> <SettingsParamValue Name="PARAM" Value="test"/> </SettingsParamValues> Introduced in v6.0; last changed in v6.0

812

Kronos Incorporated

SchedGenSettingsValue Tag

SchedGenSettingsValue Tag Value of Schedule Generator settings
Retrieves all the schedule generation settings associated with the organization paths given in the request. Function Access Control Point: Location Settings Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveSettings" Parameters→ None Properties→ <SchedGenSettingsValue (<Settings> <SchedGenSettings> </Settings>) <OrgPaths> <SimpleValue>* </OrgPaths> </SchedGenSettingsValue>

Action Descriptions
RetrieveSettings Return the list of schedule generator settings objects associated to the orgpaths specified. Return Value Type: SchedGenSettingsValue tag

Workforce Central Developers Toolkit Reference Guide—Timekeeping

813

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required Properties: OrgPaths Access Control Point Name: View Introduced in v6.0

Property Descriptions
OrgPaths

Organizational location path
list of locations for which setting values should be retrieved. This property is input only. Type: Zero or more SimpleValue tags Required Sample values: <OrgPaths> <SimpleValue Value="Organization/Hospitals/ Hosp A/Floor 3" /> <SimpleValue Value="Organization/Hospitals/ Hosp A/Floor 2" /> </OrgPaths> Introduced in v6.0; last changed in v6.0 Settings

Associated SchedGenSettings
list of schedGenSettings associated to one of the locations specified in the request (orgPaths property). Type: SchedGenSettings tag Output only Sample values: see SchedGenSettings Introduced in v6.0; last changed in v6.0

814

Kronos Incorporated

SchedRule Tag

SchedRule Tag Sorting and Matching Rule
Gives access to sorting or matching rules used by the Priority Scheduling Engine (PSE). Function Access Control Point: API.Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Add" | "AddOnly" | "Delete" | "DeleteOnly" | "Retrieve" | "RetrieveAll" | "RetrieveAllNames" | "RetrieveForUpdate" | "RetrievesAllForUpdate" | "Update" | "UpdateOnly" Parameters→ None Properties→ <SchedRule ContextName = String [Description = String] RuleName = String SortOrderName = String TopicName = String > [<CustomOperators>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

815

Chapter 2

Workforce Timekeeper XML API Tag Definitions

<CustomOperator>* </CustomOperators>] [<TopicParameterValues> <TopicParameterValue>* </TopicParameterValues>] </SchedRule>

Action Descriptions
Add Adds a sorting or matching rule object into the system. If it is already there a rule with the same name nothing happens. Return Value Type: None Required Properties: RuleName, ContextName, TopicName, SortOrderName Optional Properties: Description, TopicParameterValues, CustomOperators Access Control Point Name: Edit Introduced in v6.0 AddOnly Adds a sorting or matching rule object into the system . If it is already there an error is thrown. Return Value Type: None Required Properties: RuleName, ContextName, TopicName, SortOrderName Optional Properties: Description, TopicParameterValues, CustomOperators Access Control Point Name: Edit Introduced in v6.0 Delete Deletes the sorting or matching rule object that has the same name as the one specified in the RuleName. If it's not there nothing happens. Return Value Type: None Required Properties: RuleName Access Control Point Name: Edit

816

Kronos Incorporated

SchedRule Tag

Introduced in v6.0 DeleteOnly Deletes the sorting or matching rule object that has the same name as the one specified in the RuleName. If it's not there an error is thrown. Return Value Type: None Required Properties: RuleName Access Control Point Name: Edit Introduced in v6.0 Retrieve Retrieves the sorting or matching rule object by name. Return Value Type: SchedRule tag Required Properties: RuleName Access Control Point Name: View Introduced in v6.0 RetrieveAll Retrieves all sorting or matching rule objects. Return Value Type: Zero or more SchedRule tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Retrieves all sorting or matching rule objects names. Return Value Type: String list Access Control Point Name: View Introduced in v6.0 RetrieveForUpdate Retrieves the sorting or matching rule object specified by name for future updates. Return Value Type: SchedRule tag Required Properties: RuleName

Workforce Central Developers Toolkit Reference Guide—Timekeeping

817

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: View Introduced in v6.0 RetrievesAllForUpdate Retrieves all sorting or matching rule objects to be used in future updates. Return Value Type: Zero or more SchedRule tags Access Control Point Name: View Introduced in v6.0 Update Updates a sorting or matching rule object into the system. If the rule iis not there, it is added, else it is updated. Return Value Type: None Required Properties: RuleName Optional Properties: ContextName, TopicName, SortOrderName, Description, TopicParameterValues, CustomOperators Access Control Point Name: Edit Introduced in v6.0 UpdateOnly Updates a sorting or matching rule object into the system. If it is not there an error is thrown. Return Value Type: None Required Properties: RuleName Optional Properties: ContextName, TopicName, SortOrderName, Description, TopicParameterValues, CustomOperators Access Control Point Name: Edit Introduced in v6.0

Property Descriptions
ContextName

Rule Context Name

818

Kronos Incorporated

SchedRule Tag

The name of the context. Type: String Required Sample values: SORTING_SHIFTS Introduced in v6.0 CustomOperators

Rule Custom Operators
This tag allows the user to assign custom operators to a rule. Type: Zero or more CustomOperator tags Optional Sample values: <CustomOperators> <CustomOperator OperatorName="EQUAL_TO" Value="RN" /> <CustomOperator OperatorName="EQUAL_TO" Value="RN2" /> </CustomOperators> Introduced in v6.0 Description

Rule Description
It's the description of the rule. It must not have more then 255 characters and must not contain invalid characters also. Type: String Optional Sample values: <Description> This is a description</Description>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

819

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v6.0 RuleName

Rule Name
The name of the rule. Type: String Required Key Sample values: <RuleName> test Rule</RuleName> Introduced in v6.0 SortOrderName

Rule Sort Order Name
The sort order used within this rule. Type: String Required Sample values: ASCENDING Introduced in v6.0 TopicName

Rule Topic Name
The name of the topic of this rule. Type: String Required Sample values: SHIFT_END_TIME

820

Kronos Incorporated

SchedRule Tag

Introduced in v6.0 TopicParameterValues

Rule Topic Parameter Values
This tag allows the user to assign some TopicParameterValues to one rule. Type: Zero or more TopicParameterValue tags Optional Sample values: <TopicParameterValues> <TopicParameterValue TopicParameterName="PRIMARY_JOB" Value="true" /> <TopicParameterValue TopicParameterName="TRANSFER_SET" Value="true" /> </TopicParameterValues> Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

821

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SchedRuleContext Tag Sorting and Matching Rule Context
Gives access to sorting or matching rule's context used in Priority Scheduling Engine . It is a gold data. Function Access Control Point: API.Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" | "RetrieveAll" | "RetrieveAllNames" Parameters→ None Properties→ <SchedRuleContext ContextName = String > </SchedRuleContext>

Action Descriptions
Retrieve Retrieves a sorting or mathcing rule's context object by name. Return Value Type: SchedRuleContext tag Required Properties: ContextName Access Control Point Name: View

822

Kronos Incorporated

SchedRuleContext Tag

Introduced in v6.0 RetrieveAll Retrieves all sorting or mathcing rule's context objects from the database. Return Value Type: Zero or more SchedRuleContext tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Retrieves the names of all sorting or matching rule's context objects. Return Value Type: String list Access Control Point Name: View Introduced in v6.0

Property Descriptions
ContextName

Context Name
The name of the context to retrieve. Type: String Required Key Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

823

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SchedRuleOperator Tag Sorting and Matching Rule Operator
Gives access to sorting or matching rules's operators used in Priority Scheduleing Engine. It is a gold data. Function Access Control Point: API.Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" | "RetrieveAll" | "RetrieveAllNames" Parameters→ None Properties→ <SchedRuleOperator OperatorName = String > </SchedRuleOperator>

Action Descriptions
Retrieve Retrieves the sorting or matching rule's operator object by name. Return Value Type: SchedRuleOperator tag Required Properties: OperatorName Access Control Point Name: View

824

Kronos Incorporated

SchedRuleOperator Tag

Introduced in v6.0 RetrieveAll Retrieves all sorting or matching rule's operator objects. Return Value Type: Zero or more SchedRuleOperator tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Retrieves all sorting or matching rule's operator objects names. Return Value Type: String list Access Control Point Name: View Introduced in v6.0

Property Descriptions
OperatorName

Operator Name
Represents the sorting and matching rule operator name. Type: String Required Key Sample values: EQUAL Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

825

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SchedRuleSet Tag Sorting and Matching Rule Set
Gives access to sorting or matching rule sets used by the Priority Scheduling Engine. Function Access Control Point: Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Add" | "AddOnly" | "Delete" | "DeleteOnly" | "Retrieve" | "RetrieveAll" | "RetrieveAllNames" | "RetrieveForUpdate" | "RetrievesAllForUpdate" | "Update" | "UpdateOnly" Parameters→ None Properties→ <SchedRuleSet ContextName = String [Description = String] RuleSetName = String > [<SchedRules> <SchedRule>* </SchedRules>]

826

Kronos Incorporated

SchedRuleSet Tag

</SchedRuleSet>

Action Descriptions
Add Adds a sorting or matching rule set object into the system. If already exists nothing happens. Return Value Type: None Required Properties: RuleSetName, ContextName Optional Properties: Description Access Control Point Name: Edit Introduced in v6.0 AddOnly Adds a sorting or matching rule set object into the system. If already exists an error is thrown. Return Value Type: None Required Properties: RuleSetName, ContextName Optional Properties: Description Access Control Point Name: Edit Introduced in v6.0 Delete Deletes a sorting or matching rule set object from the system. If already exists nothing happens. Return Value Type: None Required Properties: RuleSetName Access Control Point Name: Edit Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

827

Chapter 2

Workforce Timekeeper XML API Tag Definitions

DeleteOnly Deletes a sorting or matching rule set object from the system that has the same name as the one specified in the RuleSetName. If doesn't exists an error is thrown. Return Value Type: None Required Properties: RuleSetname Access Control Point Name: Edit Introduced in v6.0 Retrieve Retrieves a sorting or matching rule set object by name. Return Value Type: SchedRuleSet tag Required Properties: RuleSetName Access Control Point Name: View Introduced in v6.0 RetrieveAll Retrieves all sorting or matching rule set objects. Return Value Type: Zero or more SchedRuleSet tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Retrieves all sorting or matching rule set objects names. Return Value Type: String list Access Control Point Name: View Introduced in v6.0 RetrieveForUpdate Retrieves sorting or matching rule set object that has the same name as the one specified in the RuleSetName parameter. This object will be used in future updates. Return Value Type: SchedRuleSet tag Required Properties: RuleSetName

828

Kronos Incorporated

SchedRuleSet Tag

Access Control Point Name: View Introduced in v6.0 RetrievesAllForUpdate Retrieves all sorting and matching rule set objects. Return Value Type: Zero or more SchedRuleSet tags Access Control Point Name: View Introduced in v6.0 Update Updates a sorting or matching rule set object into the system. If doesn't exists it will be updated. Return Value Type: None Required Properties: RuleSetName Access Control Point Name: Edit Introduced in v6.0 UpdateOnly Updates a sorting or matching rule set object into the system. If doesn't exists an error is thrown. Return Value Type: None Required Properties: RuleSetName Access Control Point Name: Edit Introduced in v6.0

Property Descriptions
ContextName

Rule Set Context Name
The name of the context used in the rule set. Type: String Required

Workforce Central Developers Toolkit Reference Guide—Timekeeping

829

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Sample values: <ContextName> SORTING_SHIFTS</ContextName> Introduced in v6.0 Description

Rule Set Description
Description of the rule set. Cannot exceed 255 characters and cannot contain invalid characters. Type: String Optional Sample values: <Description> This is a description</Description> Introduced in v6.0 RuleSetName

Rule Set Name
The name of the rule set. Type: String Required Key Sample values: <RuleSetName> Test Rule Set</RuleSetName> Introduced in v6.0 SchedRules

Sort and Match Rules
Represents the list of sorting and matching rules. Type: Zero or more SchedRule tags

830

Kronos Incorporated

SchedRuleSet Tag

Optional Sample values: <SchedRules> <SchedRule RuleName=°±Shift Start Time Rule°± Description=°±This will sort shifts based on their start time.°± TopicName=°±SHIFT_START_TIME°± ContextName=°±SORTING_SHIFTS°± SortOrderName=°±ASCENDING°± /> </ SchedRules > Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

831

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SchedRuleSortOrder Tag Sorting and Matching Rule Sort Order
Gives access to sorting or matching rule's sort orders used in Priority Scheduling Engine. It is a gold data. Function Access Control Point: API.Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" | "RetrieveAll" | "RetrieveAllNames" Parameters→ None Properties→ <SchedRuleSortOrder SortOrderName = String > </SchedRuleSortOrder>

Action Descriptions
Retrieve Retrieves the sorting or matching rule's sort order object by the specified name. Return Value Type: SchedRuleSortOrder tag Required Properties: SortOrderName Access Control Point Name: View

832

Kronos Incorporated

SchedRuleSortOrder Tag

Introduced in v6.0 RetrieveAll Retrieves all sorting or matching rule's sort order objects. Return Value Type: Zero or more SchedRuleSortOrder tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Retrieves all sorting or matching rule's sort order objects names. Return Value Type: String list Access Control Point Name: View Introduced in v6.0

Property Descriptions
SortOrderName

Sort Order Name
Represents the sorting and matching rules sort order name. Type: String Required Key Sample values: ASCENDING Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

833

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SchedRuleTopic Tag Sorting and Matching Rule Topic
Gives access to sorting or matching rule's topics used in Priority Scheduleing Engine. It is a gold data. Function Access Control Point: API.Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" | "RetrieveAll" | "RetrieveAllNames" Parameters→ None Properties→ <SchedRuleTopic TopicName = String > </SchedRuleTopic>

Action Descriptions
Retrieve Retrieves the sorting or matching rule's topic object by name. Return Value Type: SchedRuleTopic tag Required Properties: TopicName Access Control Point Name: View

834

Kronos Incorporated

SchedRuleTopic Tag

Introduced in v6.0 RetrieveAll Retrieves all sorting or matching rule's topic objects. Return Value Type: Zero or more SchedRuleTopic tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Retrieves all sorting or matching rule's topic objects names. Return Value Type: String list Access Control Point Name: View Introduced in v6.0

Property Descriptions
TopicName

Topic Name
Represents the sorting and matching rule's topic name. Type: String Required Key Sample values: EMPLOYEE_HIRE_DATE Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

835

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SchedRuleValueType Tag Sorting and Matching Rule Value Type
Gives access to sorting or matching rule's value type used in Priority Scheduling Engine. It is a gold data. Function Access Control Point: API.Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" | "RetrieveAll" | "RetrieveAllNames" Parameters→ None Properties→ <SchedRuleValueType ValueTypeName = String > </SchedRuleValueType>

Action Descriptions
Retrieve Retrieves the sorting or matching rule's value type object by the given name. Return Value Type: SchedRuleValueType tag Required Properties: ValueTypeName Access Control Point Name: View

836

Kronos Incorporated

SchedRuleValueType Tag

Introduced in v6.0 RetrieveAll Retrieves all sorting or matching rule's value type objects. Return Value Type: Zero or more SchedRuleValueType tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Retrieves all sorting or matching rule's value type objects names. Return Value Type: String list Access Control Point Name: View Introduced in v6.0

Property Descriptions
ValueTypeName

Valiue Type Name
Represents the sorting and matching rules value type name. Type: String Required Key Sample values: BooleanValueType Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

837

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Schedule Tag Schedule
The Schedule tag contains information about all schedule activities for one employee or group. Function Access Control Point: API.Schedule Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddScheduleItems" | "AddShiftRemovingOverlaps" | "AppendShift" | "AssignBreaks" | "AssignOpenShift" | "CheckRuleViolations" | "Delete" | "DeletePatterns" | "EditScheduleItems" | "Load" | "LockDays" | "LockShifts" | "RemoveScheduleItems" | "RemoveSpecifiedScheduleItems" | "ReplaceShift" | "TransferEmployees" | "UnLockDays" | "UnlockShifts" | "Update" Parameters→ None

838

Kronos Incorporated

Schedule Tag

Properties→ <Schedule [IsForeverPattern = Boolean] [IsOpenShift = Boolean] [OrgJobPath = String] [SaveData = Boolean] QueryDateSpan = DateSpan [CheckRules = Boolean] > [<AppendShifts> <AppendShifts>* </AppendShifts>] <Employees> <CurrentUser> | <PersonIdentity> </Employees> [<OpenShiftItems> <ScheduleShiftSwap>* </OpenShiftItems>] [<PartialShiftItems> <ScheduleShiftSwap>* </PartialShiftItems>] [<ScheduleItems> <ScheduleAccrualAmountEdit> | <ScheduleOff> | <SchedulePayCodeEdit> | <ScheduleShift> | <ScheduleShiftSwap> | <ScheduleUnavailable> </ScheduleItems>] [<Locations> <LocationItem>* </Locations>] [<OrgJobPaths> <LocationItem>* </OrgJobPaths>] [<ScheduleCostSummaries> <ScheduleCostSummary>* </ScheduleCostSummaries>] <ScheduleGroups> <ScheduleGroup>* </ScheduleGroups> [<SchedulePatterns> <SchedulePattern>* </SchedulePatterns>] [<TransferEmployees> <TransferEmployee>* </TransferEmployees>] </Schedule>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

839

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Descriptions
AddScheduleItems Adds the specified items into the schedule for the identified people and time period Return Value Type: None Required Properties: ScheduleItems, QueryDateSpan Access Control Point Name: Edit Introduced in v4 AddShiftRemovingOverlaps Adds the specified shift item for an employee, and removes any existing shift item that overlaps within the time span QueryDateSpan must identify just one day. Employees must specify just one employee. ScheduleItems must contain just one ScheduleShift tag. Return Value Type: Zero or more RuleViolation tags Required Properties: QueryDateSpan, Employees, ScheduleItems Optional Properties: SaveData, CheckRules Access Control Point Name: Edit Introduced in v5.0 AppendShift Appends shift for specified employees. At lease one of the optional properties must be present. Return Value Type: None Required Properties: AppendShifts, QueryDateSpan Optional Properties: Employees, ScheduleGroups Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1

840

Kronos Incorporated

Schedule Tag

AssignBreaks Assigns breaks, based on the break placement rules, to the shift identified by the query date span and employee The query date span and each employee, taken together, must identify an existing shift Return Value Type: None Required Properties: QueryDateSpan, Employees Access Control Point Name: Edit Introduced in v5.0a AssignOpenShift Assigns an open shift to a person QueryDateSpan must identify exactly one day. Employees must specify exactly one employee. OpenShiftItems must contain exactly one ScheduleShiftSwap. Return Value Type: Zero or more RuleViolation tags Required Properties: QueryDateSpan, Employees, OrgJobPath, OpenShiftItems Optional Properties: SaveData, CheckRules Access Control Point Name: Edit Introduced in v5.0; last changed in v5.1 CheckRuleViolations Returns all rule violations that exist in the current schedule for the specified employees and/or jobs. At least one of the optional properties must be present. Return Value Type: Zero or more RuleViolation tags Required Properties: QueryDateSpan Optional Properties: Employees, OrgJobPath, OrgJobPaths Access Control Point Name: View Introduced in v5.0; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

841

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Delete Marks all schedule items for deletion from the identified schedule period. At least one of the optional properties must be present. Return Value Type: None Required Properties: QueryDateSpan Optional Properties: Employees, ScheduleGroups Access Control Point Name: Edit Introduced in v4; last changed in v5.1 DeletePatterns Marks an existing accrual pattern for deletion from an employee or a group. At least one of the optional properties must be present. The existing pattern anchor time must be within the query date span. Return Value Type: None Required Properties: QueryDateSpan Optional Properties: Employees, ScheduleGroups Access Control Point Name: Edit Introduced in v4; last changed in v5.1 EditScheduleItems Modifies one or more existing schedule items. At least one of the optional properties must be present. Return Value Type: None Required Properties: ScheduleItems, QueryDateSpan Optional Properties: Employees, ScheduleGroups Access Control Point Name: Edit Introduced in v5.0; last changed in v5.1 Load Returns all schedule items and patterns for the specified people and time period. Any item that is not currently active returns a value of True for the IsDeleted property. At least one of the optional properties must be present.

842

Kronos Incorporated

Schedule Tag

Return Value Type: Schedule tag Required Properties: QueryDateSpan Optional Properties: Employees, ScheduleGroups, IsOpenShift, OrgJobPath Access Control Point Name: View Introduced in v4; last changed in v6.0 LockDays Locks the days for specified employees. At least one of the optional properties must be present. Return Value Type: None Required Properties: QueryDateSpan Optional Properties: Employees, ScheduleGroups Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 LockShifts Lock schedule shifts for the following conditions: QueryDateSpan and one or more Locations QueryDateSpan and one or more OrgJobPaths QueryDateSpan and one or more Employees QueryDateSpan spanning 1 day, one employee Optional fields contain following logic: one of: Locations, OrgJobPaths, Employees or QueryDateSpan and one employee, and one ScheduleItem ScheduleItems must identify one Shift and one Employee. QueryDateSpan must represent a single day.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

843

Chapter 2

Workforce Timekeeper XML API Tag Definitions

If Locations, OrgJobPath, or Employees is specified, QueryDateSpan must also be specified. Return Value Type: None Required Properties: QueryDateSpan Optional Properties: Locations, OrgJobPaths, Employees, ScheduleItems Access Control Point Name: Edit Introduced in v5.0; last changed in v5.1 RemoveScheduleItems Removes the specified items for the specified identified time period Return Value Type: None Required Properties: ScheduleItems, QueryDateSpan Access Control Point Name: Edit Introduced in v4 RemoveSpecifiedScheduleItems Removes the specified items for the specified identified time period Return Value Type: None Required Properties: ScheduleItems, QueryDateSpan Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 ReplaceShift Replace shift for specified employees. At least one of the optional properties must be present. Note: to avoid an override of the <StartDate value, keep the <StartDayNumber and <EndDayNumber values to 1 when performing a replaceshifts action. Return Value Type: None Required Properties: QueryDateSpan Optional Properties: Employees, ScheduleGroups

844

Kronos Incorporated

Schedule Tag

Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 TransferEmployees Transfers employees to other jobs. At least one of the optional properties must be present. Return Value Type: None Required Properties: TransferEmployees, QueryDateSpan Optional Properties: Employees, ScheduleGroups Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 UnLockDays UnLockDays for the specified employees. At least one of the optional properties must be present. Return Value Type: None Required Properties: QueryDateSpan Optional Properties: Employee, ScheduleGroups Access Control Point Name: Edit Introduced in v5.1; last changed in v5.1 UnlockShifts Locks schedule shifts can be used for the following cases: QueryDateSpan and one or more Locations QueryDateSpan and one or more OrgJobPaths QueryDateSpan and one or more Employees QueryDateSpan spanning 1 day, one employee

Workforce Central Developers Toolkit Reference Guide—Timekeeping

845

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional fields contain following logic: one of: Locations, OrgJobPaths, Employees or QueryDateSpan and one employee, and one ScheduleItem If ScheduleItems is specified, there can only be one, and it must be a Shift. Only one Employee must be specified. QueryDateSpan must represent a single day. If Locations, OrgJobPath, or Employees is specified, QueryDateSpan must also be specified. Return Value Type: None list Required Properties: QueryDateSpan Optional Properties: Locations, OrgJobPaths, Employees, ScheduleItems Access Control Point Name: Edit Introduced in v5.0; last changed in v5.1 Update Replaces the specified items and patterns from the schedule period At least one employee or group must be specified. Return Value Type: None Required Properties: ScheduleItems, QueryDateSpan Access Control Point Name: Edit Introduced in v4

Property Descriptions
AppendShifts

Append shifts
AppendShifts Type: Zero or more AppendShifts tags Optional Introduced in v5.1

846

Kronos Incorporated

Schedule Tag

CheckRules

Validate modified schedule?
Indicates whether schedule validation should be done on the modified schedule Type: Boolean Optional If True, all rule violations from employees or jobs that are affected by the action are returned. If False, null is returned. Dependency: Only one of SaveData and CheckRules can be False. Default value: False Introduced in v5.0 Employees

Employees
One or more employees for whom the schedule is valid, as specified in one or more PersonIdentity or CurrentUser tags. Type: Either CurrentUser or PersonIdentity tag Optional Key Introduced in v4; last changed in v5.0 IsForeverPattern

Extend end date indefinitely?
Indicates whether the pattern end date is January 1, 3000 Type: Boolean Optional Enumerated value: True, False Introduced in v4 IsOpenShift

Is this an open shift?

Workforce Central Developers Toolkit Reference Guide—Timekeeping

847

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Specifies whether the shift is open. If True, the shift is open. Type: Boolean Optional Enumerated value: True, False Introduced in v5.0; last changed in v5.0 Locations

Locations
Locations property is used to load the schedule for a specific locations into the container that gets created. Used for locking/unlocking shifts Type: Zero or more LocationItem tags Optional Introduced in v5.1 OpenShiftItems

Items in open shift
The set of items that define the open shift Type: Zero or more ScheduleShiftSwap tags Optional Only one shift can be specified. Introduced in v5.1 OrgJobPath

Location of job in the organization
The fully qualified organizational job Type: String Optional Maximum length: 1000 characters Only used if the IsOpenShift property is "True"

848

Kronos Incorporated

Schedule Tag

Introduced in v5.0; last changed in v5.0 OrgJobPaths

Organizational jobs
OrgJobPaths specifies a list of OrgJobs. It is similar to multiple OrgJobPath properties. Type: Zero or more LocationItem tags Optional All items in the list must identity organizational jobs. Introduced in v5.0 PartialShiftItems

Items in partial shift
The set of items that define a partial shift. The partial shift is assigned to an open shift. Type: Zero or more ScheduleShiftSwap tags Optional Only one partial shift can be specified. Introduced in v5.1 QueryDateSpan

Span of dates for the schedule
The span of dates when the schedule is valid. If you are creating a pattern and want the pattern to last forever, use IsForeverPattern. Type: DateSpan Required, Key Introduced in v4 SaveData

Save the modified schedule?

Workforce Central Developers Toolkit Reference Guide—Timekeeping

849

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SaveData indicates whether the modified schedule will be saved. Type: Boolean Optional No Save severity rule violations may exist, regardless of the value of IsCheckRules. If any such rules exist, the Request will fail and the violations will be listed. Dependency: Only one of SaveData and CheckRules can be False. Default value: True Introduced in v5.0 ScheduleCostSummaries

Schedule cost summaries
One or more ScheduleCostSummary tags. Type: Zero or more ScheduleCostSummary tags Optional Default value: none Introduced in v5.0a ScheduleGroups

Schedule groups associated with the schedule
One or more groups for whom the schedule is valid Type: Zero or more ScheduleGroup tags Optional Key Introduced in v4; last changed in v6.0 ScheduleItems

Items in schedule
A list of all ScheduleShift, SchedulePayCodeEdit, ScheduleUnavailable, ScheduleOff, ScheduleShiftSwap, and ScheduleAccrualAmountEdit tags that make up the schedule. These items can all be seen in the user interface.

850

Kronos Incorporated

Schedule Tag

Each of them contains an IsDeleted property, which specifies whether the item is active. An inactive item is one that is deleted but remains visible and struck through in the user interface. Any item that is not visible in the user interface, such as a deleted ad hoc shift item, is not included. Type: Either ScheduleAccrualAmountEdit, ScheduleOff, SchedulePayCodeEdit, ScheduleShift, ScheduleShiftSwap or ScheduleUnavailable tag Optional Introduced in v4 SchedulePatterns

Schedule patterns
A list of patterns that are used to generate the schedule Type: Zero or more SchedulePattern tags Optional Introduced in v4 TransferEmployees

Transfer employees
TransferEmployees Type: Zero or more TransferEmployee tags Optional Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

851

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleAccrualAmountEdit Tag Accrual Amount Edit
The ScheduleAccrualAmountEdit tag represents a modification to the accrued balance of an employee or group. Used by: Schedule Function Access Control Point: API.Schedule Introduced in v4; last changed in v6.0

Syntax
Properties→ <ScheduleAccrualAmountEdit AmountInCurrency = Currency AmountInTime = TimeDuration AccrualCodeName = String (IsDeleted = Boolean) [ScheduleGroupName = String] Startdate = Date > [<Employee> <CurrentUser> | <PersonIdentity> </Employee>] </ScheduleAccrualAmountEdit>

Property Descriptions
AmountInCurrency

Amount of accrual, in currency
An accrual amount expressed as a currency Type: Currency Maximum length: 30 characters Introduced in v4

852

Kronos Incorporated

ScheduleAccrualAmountEdit Tag

AmountInTime

Amount of accrual, in time
An accrual amount, expressed in hours or days Type: TimeDuration Maximum length: 30 characters Introduced in v4 AccrualCodeName

Accrual code name
The accrual code associated with the transaction. The accrual code must be created in timekeeping and assigned to the employee before you can import data against it. Type: String Required Maximum length: 50 characters You can find values in the timekeeping Application. Sample values: Vacation, Sick Introduced in v4 Employee

Employee
One employee who is assigned to the shift, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Optional Must uniquely identify an existing and active employee Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

853

Chapter 2

Workforce Timekeeper XML API Tag Definitions

IsDeleted

Is the item inactive?
Indicates whether the item is active. • • If False, the item is active. If True, it is currently inactive.

Type: Boolean Output only Enumerated value: True, False Introduced in v5.0; last changed in v5.0 ScheduleGroupName

Schedule group name
The name of the schedule group to which the person is currently assigned Type: String Optional Maximum length: 30 characters You can find values in the Workforce Timekeeper user interface. Introduced in v4 Startdate

Start date
The start date for this item Type: Date Required Must be within the span of the containing schedule Introduced in v4

Groups of Mutually Exclusive Properties

854

Kronos Incorporated

ScheduleAccrualAmountEdit Tag

AccrualAmount AccrualAmount Required Group includes: AmountInCurrency, AmountInTime

Workforce Central Developers Toolkit Reference Guide—Timekeeping

855

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleAccrualPattern Tag Create or Modify Accrual Pattern
The ScheduleAccrualPattern tag allows you to create or modify an accrual pattern for a given employee or group. Function Access Control Point: API.Schedule Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Delete" | "Update" Parameters→ None Properties→ <ScheduleAccrualPattern AmountInCurrency = Currency AmountInTime = TimeDuration AccrualCodeName = String IsForeverPattern = Boolean (PeriodLengthInDays = Integer) [PeriodLength = Integer] QueryDateSpan = DateSpan [AnchorDate = Date] [PeriodCodeName = String] > <AccrualPatternElements> <AccrualPatternElement>* </AccrualPatternElements> [<Employees> <PersonIdentity> </Employees>]

856

Kronos Incorporated

ScheduleAccrualPattern Tag

[<ScheduleGroups> <ScheduleGroup>* </ScheduleGroups>] </ScheduleAccrualPattern>

Action Descriptions
Delete Marks an existing accrual pattern from an employee or a group for deletion The existing pattern anchor time must be within the query data span. Return Value Type: None Required Properties: AccrualCodeName Access Control Point Name: Edit Introduced in v4 Update Adds a new pattern or updates an existing one for an employee or a group Return Value Type: None Required Properties: AccrualCodeName Access Control Point Name: Edit Introduced in v4

Property Descriptions
AmountInCurrency

Amount of accrual, in currency
An accrual amount expressed as a currency Type: Currency Maximum length: 30 characters Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

857

Chapter 2

Workforce Timekeeper XML API Tag Definitions

AmountInTime

Amount of pay code, in time
A pay code amount, expressed in hours or days Type: TimeDuration Introduced in v4 AccrualCodeName

Accrual code name
A named account containing a specific type of accrual balance Type: String Required Maximum length: 50 characters You can find values in the Workforce Timekeeper Setup Application. Sample values: Vacation, Sick Introduced in v4 AccrualPatternElements

Elements in accrual pattern
One or more elements that comprise the pattern. Each element corresponds to one day in the pattern. Type: Zero or more AccrualPatternElement tags Required Introduced in v4 AnchorDate

Start date for accrual pattern
Specifies the date on which the pattern is scheduled to start

858

Kronos Incorporated

ScheduleAccrualPattern Tag

Type: Date Optional Introduced in v4 Employees

Employees
One or more employees, as specified in a PersonIdentity tag, who are assigned to the accrual. Dependency: At least one of Employees or ScheduleGroups is required. Type: PersonIdentity tag Optional Must uniquely identify an existing and active employee Introduced in v4 IsForeverPattern

Extend end date indefinitely?
Indicates whether the pattern's end date is January 1, 3000 Type: Boolean Required Enumerated value: True, False Introduced in v4 PeriodCodeName

Units of time for accrual period
The unit of time used for the PeriodLength Type: String Optional Maximum length: 30 characters

Workforce Central Developers Toolkit Reference Guide—Timekeeping

859

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Enumerated value: Daily, Weekly, Monthly, Annually, Pay Period, Schedule Period Introduced in v4 PeriodLength

Number of units
The number of units in the availability pattern, as specified by the PeriodCodeName. For example, if the PeriodCodeName is Weeks and PeriodLength is 3, this number specifies three weeks. Type: Integer Optional Introduced in v4 PeriodLengthInDays

Number of days for pattern
The number of days to which the accrual pattern applies Type: Integer Output Only Introduced in v4; last changed in v5.0 QueryDateSpan

Span of dates for schedule
The span of dates when the schedule is valid. If you are creating an accrual pattern and want the pattern to last forever, set IsForeverPattern to True. Type: DateSpan Required Key Introduced in v4 ScheduleGroups

Group assigned to the accrual

860

Kronos Incorporated

ScheduleAccrualPattern Tag

Identifies one or more group who are assigned to the accrual Dependency: At least one of Employees or ScheduleGroups is required. Type: Zero or more ScheduleGroup tags Optional Any group that is specified must exist Introduced in v4

Groups of Mutually Exclusive Properties
AccrualAmount AccrualAmount is either in Currency or in Time depending on AccrualCodeName Required Group includes: AmountInCurrency, AmountInTime

Workforce Central Developers Toolkit Reference Guide—Timekeeping

861

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleCostPaycode Tag Schedule Cost Paycode
This tag contains the hours and wages for a single pay code in the schedule costing table. Function Access Control Point: API.RetailSchedules Introduced in v5.0a; last changed in v5.2

Syntax
Properties→ <ScheduleCostPaycode (Hours = Time) (Label = String) (Wages = Currency) > </ScheduleCostPaycode>

Property Descriptions
Hours

Hours to earn wage
The hours worked to earn the wage. Type: Time Output only Sample values: 41.00 Introduced in v5.0a; last changed in v5.0a Label

Paycode label
A label for the paycode

862

Kronos Incorporated

ScheduleCostPaycode Tag

Type: String Output only none Sample values: Summary Default value: none Introduced in v5.0a; last changed in v5.0a Wages

Wage for paycode and job
The wage for this paycode and job. Type: Currency Output only Sample values: 1,500 Default value: none Introduced in v5.0a; last changed in v5.0a

Workforce Central Developers Toolkit Reference Guide—Timekeeping

863

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleCostResult Tag Schedule Cost Result
This tag contains the result tags for all paycodes under the given job or account. none Function Access Control Point: API.RetailSchedules Introduced in v5.0a; last changed in v5.0a

Syntax
Properties→ <ScheduleCostResult (Label = String) > (<Paycodes> <ScheduleCostPaycode>* </Paycodes>) </ScheduleCostResult>

Property Descriptions
Label

Job or account label
The fully qualified name for the selected job or account label Type: String Output only Sample values: Organization/Manufacturing/Bright Plant/Light Bulbs/ Line 1/ASSM Default value: none Introduced in v5.0a; last changed in v5.0a

864

Kronos Incorporated

ScheduleCostResult Tag

Paycodes

Paycodes for the job or account
One or more ScheduleCostPaycode tags for the job or account Type: Zero or more ScheduleCostPaycode tags Output only Introduced in v5.0a; last changed in v5.0a

Workforce Central Developers Toolkit Reference Guide—Timekeeping

865

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleCostSummary Tag Schedule Cost Summary
The ScheduleCostSummary tag contains information about the schedule cost. Function Access Control Point: API.RetailSchedules Introduced in v5.0; last changed in v5.0a

Syntax
Properties→ <ScheduleCostSummary SummaryType = String Grouping = String [Updated = Boolean] > (<Results> <ScheduleCostResult>* </Results>) </ScheduleCostSummary>

Property Descriptions
Grouping

Job or account?
Specifies whether the results should be indexed by job or by account. Type: String Required Enumerated value: job, account Introduced in v5.0a; last changed in v5.0a Results

Results for a job or account
One or more ScheduleCostResult tags. Each ScheduleCostResult tags represents a job or account.

866

Kronos Incorporated

ScheduleCostSummary Tag

Type: Zero or more ScheduleCostResult tags Output only Introduced in v5.0a; last changed in v5.0a SummaryType

Employee or location?
Specifies whether the output should be based on employee or location Type: String Required Default value: none Enumerated value: employee, location Introduced in v5.0a; last changed in v5.0a Updated

Request an update to schedule cost data?
This property is used to determine whether the system updates schedule cost data. In a request, specify True to request an update. In a response, True means that the data has been updated. Type: Boolean Optional Default value: False Enumerated value: True, False Introduced in v5.0a; last changed in v5.0a

Workforce Central Developers Toolkit Reference Guide—Timekeeping

867

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleCoverage Tag Schedule coverage
Used to retrieve information on Schedule Planner data: open shifts, staffing requirements, coverage details. Function Access Control Point: SchedulePlanner Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveAll" | "RetrieveDetails" | "RetrieveOpenShifts" | "RetrieveSummary" Parameters→ None Properties→ <ScheduleCoverage QueryDateSpan = String > [<Locations> <LocationItem>* </Locations>] </ScheduleCoverage>

Action Descriptions
RetrieveAll This will retrieve data that may be either from the cache or the calculation by the Schedule container for coverage details, staffing requirements and open shifts.

868

Kronos Incorporated

ScheduleCoverage Tag

Return Value Type: ScheduleCoverage tag Required Properties: QueryDateSpan Optional Properties: Locations Access Control Point Name: View Introduced in v6.0 RetrieveDetails This will retrieve data that may be either from the cache or the calculation by the Schedule container for coverage details. Return Value Type: Zero or more CoverageDetail tags Required Properties: QueryDateSpan Optional Properties: Locations Access Control Point Name: View Introduced in v6.0 RetrieveOpenShifts This will retrieve data that may be either from the cache or the calculation by the Schedule container for open shifts. Return Value Type: Zero or more OpenShift tags Required Properties: QueryDateSpan Optional Properties: Locations Access Control Point Name: View Introduced in v6.0 RetrieveSummary This will retrieve data that may be either from the cache or the calculation by the Schedule container for staffing requirements summary. Return Value Type: Zero or more StaffingRequirement tags Required Properties: QueryDateSpan Optional Properties: Locations Access Control Point Name: View

Workforce Central Developers Toolkit Reference Guide—Timekeeping

869

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v6.0

Property Descriptions
Locations

Locations with the requirements
Represents a list of locations. Type: Zero or more LocationItem tags Optional Sample values: <Locations> <LocationItem Location="Organization/Hospitals/Hosp A/Floor 1/ER"/> </Locations> Introduced in v6.0; last changed in v6.0 QueryDateSpan

Date span of requirements
Represents a date span. Type: String Required Sample values: <QueryDateSpan> 12/18/05-12/22/05</QueryDateSpan> Introduced in v6.0; last changed in v6.0

870

Kronos Incorporated

ScheduleGroup Tag

ScheduleGroup Tag Schedule Group
The ScheduleGroup tag identifies employees who are grouped together for scheduling purposes. Each employee's membership in a schedule group varies, depending on the date span. Used by: Schedule, ScheduleAccrualPattern Function Access Control Point: API.Schedule Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddEmployees" | "Delete" | "Load" | "LoadAllGroups" | "RemoveEmployees" | "RemoveEmployeesByDateSpan" | "Update" Parameters→ None Properties→ <ScheduleGroup [QueryDateSpan = DateSpan] [AllowsInheritance = Boolean] [AllowContract = Boolean] [IsOverrideConflict = Boolean] [ScheduleGroupName = String] > [<GroupMemberships> <GroupMembership>*

Workforce Central Developers Toolkit Reference Guide—Timekeeping

871

Chapter 2

Workforce Timekeeper XML API Tag Definitions

</GroupMemberships>] </ScheduleGroup>

Action Descriptions
AddEmployees Adds one or more employees to the existing group for the specified period of time Return Value Type: None Required Properties: ScheduleGroupName, Group Memberships Access Control Point Name: Edit Introduced in v4 Delete Marks a specified group for deletion Return Value Type: None Required Properties: ScheduleGroupName Access Control Point Name: Edit Introduced in v4 Load Returns an employee assignment for the specified group for the date span Return Value Type: ScheduleGroup tag Required Properties: ScheduleGroupName, QueryDateSpan Access Control Point Name: View Introduced in v4 LoadAllGroups Returns all groups in the system Return Value Type: Zero or more ScheduleGroup tags Required Properties: None Access Control Point Name: View Introduced in v4

872

Kronos Incorporated

ScheduleGroup Tag

RemoveEmployees Removes one or more employees from the schedule group for the specified period of time Return Value Type: None Required Properties: ScheduleGroupName, GroupMemberships Access Control Point Name: Edit Introduced in v4 RemoveEmployeesByDateSpan Removes one or more employees from the specified group for the specified date range All of the employees to be removed must be specified in the GroupMembership list. Return Value Type: None Required Properties: GroupMemberships Access Control Point Name: Edit Introduced in v4 Update Modifies the employee list for the specified group and date span Return Value Type: None Required Properties: ScheduleGroupName, QueryDateSpan Access Control Point Name: Edit Introduced in v4

Property Descriptions
AllowContract

Is the group schedule a schedule contract?
Determine if a group schedule is being used as a schedule Contract Type: Boolean

Workforce Central Developers Toolkit Reference Guide—Timekeeping

873

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Default value: false Introduced in v6.0; last changed in v6.0 AllowsInheritance

Does this group allows inheritance?
This flag determines if employees in a Group can inherit shifts from the group schedule Type: Boolean Optional Introduced in v6.0; last changed in v6.0 GroupMemberships

List of group members
One or more employees who are part of the group Type: Zero or more GroupMembership tags Optional Introduced in v4 IsOverrideConflict

Override schedule conflicts?
Indicates whether to override conflicts when adding group members Type: Boolean Optional Default value: False Enumerated value: True, False Introduced in v4; last changed in v5.1 QueryDateSpan

Date span for the schedule

874

Kronos Incorporated

ScheduleGroup Tag

The range of dates when the schedule is valid for the group members Type: DateSpan Optional Introduced in v4 ScheduleGroupName

Schedule group name
The name of the schedule group to which the members of the group are assigned. Type: String Optional Maximum length: 30 characters You can find values in the Workforce Timekeeper user interface. Introduced in v4; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

875

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleGroupProfile Tag Profile for Schedule Group
The ScheduleGroupProfile tag provides information about valid ScheduleGroup profiles defined within the system. A Schedule Group is a set of employees who work the same shift. Function Access Control Point: API.Employee Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "Load" | "LoadAllScheduleGroupProfiles" | "LoadById" Parameters→ None Properties→ <ScheduleGroupProfile [ScheduleGroupId = Integer] [ScheduleGroupName = String] > </ScheduleGroupProfile>

Action Descriptions
Load Returns a schedule group. Name should be valid

876

Kronos Incorporated

ScheduleGroupProfile Tag

Return Value Type: ScheduleGroup tag Access Control Point Name: View Introduced in v4 Load Returns a schedule group, based on ScheduleGroupName. Name should be valid Return Value Type: ScheduleGroupProfile tag Required Properties: ScheduleGroupName Access Control Point Name: View Introduced in v4; last changed in v5.1 LoadAllScheduleGroupProfiles Returns all schedule group profiles in the system. Return Value Type: Zero or more ScheduleGroup tags Required Properties: None Access Control Point Name: View Introduced in v4 LoadById Returns a schedule group, based on ScheduleGroupId. ID must be valid Return Value Type: ScheduleGroup tag Required Properties: ScheduleGroupId Access Control Point Name: View Introduced in v4; last changed in v5.1

Property Descriptions
ScheduleGroupId

Identifier of schedule group

Workforce Central Developers Toolkit Reference Guide—Timekeeping

877

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Uniquely identifies the schedule group in the database Type: Integer Optional Introduced in v4; last changed in v6.0 ScheduleGroupName

Schedule group name
The name of the schedule group to which the person is currently assigned Type: String Optional Maximum length: 30 characters You can find values in the Workforce Timekeeper user interface. Introduced in v4

878

Kronos Incorporated

ScheduleHours Tag

ScheduleHours Tag Schedule Hours
The ScheduleHours tag provides information about a schedule shift for a person, and allows it to be overridden. Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "CancelTimeOff" Parameters→ None Properties→ <ScheduleHours [AmountInTime = TimeDuration] [IsAllDays = Boolean] [IsCreateOpenShift = Boolean] QueryDateSpan = DateSpan [IsOverride = Boolean] PaycodeName = String [IsSaveData = Boolean] [UnavailableDuration = TimeDuration] [DisplayTime = Time] [UnavailableStartTime = Time] [IsCheckRules = Boolean] > <Employee> <PersonIdentity> </Employee> </ScheduleHours>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

879

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Descriptions
AddOnly This action either overrides existing scheduled hours with a pay code edit, or adds the pay code edit to the schedule. Return Value Type: Zero or more RuleViolation tags Required Properties: Employee, QueryDateSpan, PaycodeName Optional Properties: AmountInTime, DisplayTime, IsAllDays,UnavailableDuration, IsCreateOpenShift, IsOverride, IsSaveData, IsCheckRules Access Control Point Name: Edit Introduced in v5.0 CancelTimeOff This action removes the specified pay code edit. Return Value Type: Zero or more ScheduleHoursStatus tags Required Properties: Employee, QueryDateSpan, PaycodeName Access Control Point Name: Edit Introduced in v5.1Beta

Property Descriptions
AmountInTime

Amount of pay code, in time
The amount of the pay code edit, expressed as a time value Type: TimeDuration Optional Must be between 00:00 and 100:00 Dependency: If AmountInTime is used, DisplayTime must also be used.

880

Kronos Incorporated

ScheduleHours Tag

Dependency: If AmountInTime is used, the pay code must be associated with time, rather than currency. Introduced in v5.0 DisplayTime

Time to display in the user interface
The start time of the scheduled pay code edit Type: Time Optional Dependency: If DisplayTime is used, AmountInTime must also be used. Introduced in v5.0 Employee

Employee
One employee, as specified in a PersonIdentity tag Type: PersonIdentity tag Required Key Must uniquely identify an existing and active employee. If the employee has a Workforce_Scheduler_Employee license and specifies True for IsCreateOpenShift, you will be able to create open shifts. Otherwise IsCreateOpenShift will have no effect. Introduced in v5.0 IsAllDays

Apply paycode edit applied to non-scheduled days?
This property identifies how AmountInTime and DisplayTime will be used. If True, a pay code edit is created for non-scheduled days. If False, a pay code edit is not applied to non-scheduled days. Type: Boolean Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

881

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Dependency: If True, AmountInTime and DisplayTime must be specified. Default value: False Introduced in v5.0; last changed in v5.2 IsCheckRules

Validate modified schedule?
Indicates whether schedule validation should be done on the modified schedule Type: Boolean Optional If True, any rule violations for affected employees or jobs will be returned. If False, null is returned. Dependency: Only one of IsSaveData and IsCheckRules can be False. Default value: False Introduced in v5.0 IsCreateOpenShift

Create open shifts?
Specifies whether open shifts should be created Type: Boolean Optional Dependency: If IsCreateOpenShift is True, IsOverride must also be True. Dependency: This property is only available to employees who have Workforce_Scheduler_Employee licenses. Default value: True Introduced in v5.0 IsOverride

Override scheduled hours?
Specifies whether the pay code edit should override the scheduled hours

882

Kronos Incorporated

ScheduleHours Tag

Type: Boolean Optional Dependency: If IsCreateOpenShift is True, IsOverride must also be True. Default value: True Introduced in v5.0 IsSaveData

Save modified schedule?
Indicates whether the modified schedule should be saved Type: Boolean Optional There may be No Save severity rule violations in existence. If so, regardless of the value of IsCheckRules, the Request will fail and the violations will be listed. Dependency: Only one of IsSaveData and IsCheckRules can be False. Default value: True Introduced in v5.0 PaycodeName

Pay code
The pay code that will override or add to the person scheduled hours Type: String Required Maximum length: 50 characters The pay code must be a monetary type. Introduced in v5.0 QueryDateSpan

Date range of schedule
The range of dates for which the schedule is valid

Workforce Central Developers Toolkit Reference Guide—Timekeeping

883

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: DateSpan Required Key Introduced in v5.0 UnavailableDuration

Time range when employee is unavailable
The period of time during a specific day when an employee is unavailable Type: TimeDuration Optional Introduced in v5.0 UnavailableStartTime

Unavailable start time
If this property is specified, its value will be used as this persons unavailable start Time. Type: Time Optional Introduced in v5.1Beta

884

Kronos Incorporated

ScheduleHoursAccrualViolation Tag

ScheduleHoursAccrualViolation Tag Accrual Violations Message
This tag contains a message about an accrual violation. Used by: ScheduleHoursStatus Function Access Control Point: API.Schedule Introduced in v5.1Beta; last changed in v5.2

Syntax
Properties→ <ScheduleHoursAccrualViolation (ViolationMessage = String) > </ScheduleHoursAccrualViolation>

Property Descriptions
ViolationMessage

Violation message
The violation message Type: String Output only Cannot be null. Introduced in v5.1Beta; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

885

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleHoursDailyStatus Tag Daily Status for Schedule Hours
The ScheduleHoursDailyStatus tag returns daily information about schedule hours. Used by: ScheduleHoursStatus Function Access Control Point: API.Schedule Introduced in v5.1Beta; last changed in v5.1Beta

Syntax
Properties→ <ScheduleHoursDailyStatus (Date = Date) (ScheduledShiftExist = Boolean) (IsPayCodeEditCreated = Boolean) > </ScheduleHoursDailyStatus>

Property Descriptions
Date

Date for requested data
The date for which schedule information has been requested Type: Date Output only Introduced in v5.1Beta IsPayCodeEditCreated

Was pay code edit created?
This property returns true if a pay code edited was created; false if one has not. Type: Boolean Output only

886

Kronos Incorporated

ScheduleHoursDailyStatus Tag

Introduced in v5.1Beta ScheduledShiftExist

Does scheduled shift exist?
This property returns true if the specified shift exists; false if it does not. Type: Boolean Output only Introduced in v5.1Beta

Workforce Central Developers Toolkit Reference Guide—Timekeeping

887

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleHoursException Tag Exception Message for Schedule Hours
This tag contains an exception message. Used by: ScheduleHoursStatus Function Access Control Point: API.Schedule Introduced in v5.1Beta; last changed in v5.2

Syntax
Properties→ <ScheduleHoursException (ViolationMessage = String) > </ScheduleHoursException>

Property Descriptions
ViolationMessage

Violation message
This is an output only property; it displays exception messages that will be used by process manager. Type: String Output only Cannot be null. Introduced in v5.1Beta; last changed in v5.1

888

Kronos Incorporated

ScheduleHoursStatus Tag

ScheduleHoursStatus Tag Schedule Hours Status
The ScheduleHoursStatus tag contains all of the messages from the ScheduleHoursAccrualViolation, ScheduleHoursDailyStatus, and ScheduleHoursException tags, as well as violations identified in the RuleViolations tag. Information in this tag is returned by the CancelTimeOff action of the ScheduleHours tag. One ScheduleHoursStatus tag is returned for each date in the QueryDateSpan range that is specified in the ScheduleHours tag. Function Access Control Point: API.Schedule Introduced in v5.1Beta; last changed in v5.1Beta

Syntax
Properties→ <ScheduleHoursStatus (Date = Date) > (<AccrualViolation> <ScheduleHoursAccrualViolation> </AccrualViolation>) (<RuleViolations> <RuleViolation>* </RuleViolations>) (<DailyStatus> <ScheduleHoursDailyStatus>* </DailyStatus>) (<Exception> <ScheduleHoursException> </Exception>) </ScheduleHoursStatus>

Property Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

889

Chapter 2

Workforce Timekeeper XML API Tag Definitions

AccrualViolation

Accrual violation
An accrual violation as shown in the ScheduleHoursAccrualViolation tag Type: ScheduleHoursAccrualViolation tag Output only Introduced in v5.1Beta DailyStatus

Status for daily schedule hours
One or more schedule hours daily status records, as shown in the ScheduleHoursDailyStatus tag. Type: Zero or more ScheduleHoursDailyStatus tags Output only Introduced in v5.1Beta Date

Date
The date for which information is requested Type: Date Output only Introduced in v5.1Beta Exception

Violation for schedule hours
The schedule hours violation message as shown by the ScheduleHoursException tag Type: ScheduleHoursException tag Output only Introduced in v5.1Beta

890

Kronos Incorporated

ScheduleHoursStatus Tag

RuleViolations

Schedule rule violations
The rule violations as shown in the RuleViolations tag Type: Zero or more RuleViolation tags Output only Introduced in v5.1Beta

Workforce Central Developers Toolkit Reference Guide—Timekeeping

891

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleMarkPosted Tag Schedules Marked As Posted
The ScheduleMarkPosted tag enables you to specify a date range and a set of jobs for which all shifts are captured and marked as posted. Note: These shifts can be modified and assigned to employees, but they cannot be deleted. Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Update" Parameters→ None Properties→ <ScheduleMarkPosted OrgJobLocation = String QueryDateSpan = DateSpan > </ScheduleMarkPosted>

Action Descriptions
Update Updates a mark posted period if one exists Return Value Type: None Required Properties: QueryDateSpan, OrgJobLocation

892

Kronos Incorporated

ScheduleMarkPosted Tag

Access Control Point Name: Edit Introduced in v5.0

Property Descriptions
OrgJobLocation

Set of jobs in the organization
A set of jobs for which all shifts will be marked as posted Type: String Required Maximum length: 1000 characters Introduced in v5.0 QueryDateSpan

Span of dates for schedule
The date range when the schedule is valid Type: DateSpan Required Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

893

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleOff Tag Employee On Call
The ScheduleOff tag describes a situation where an employee is on call. The person may or may not actually be called in. Because the person may not come in, a punch may not be recorded. Although the person is not paid for the shift, no exception is generated. Used by: Schedule Dependency: A shift with this segment type must specify a transfer of labor level, work rule, organizational job path, or any combination of these items. Only one ScheduleOff segment can be specified. Function Access Control Point: API.Schedule Introduced in v4; last changed in v6.0

Syntax
Properties→ <ScheduleOff <ShiftSegments> <ShiftSegment>* </ShiftSegments> ShiftCodeName = String [CommentText = String] (IsDeleted = Boolean) [IsOpenShift = Boolean] StartDate = Date [ShiftTypeName = String] > [<Notes> <Note>* </Notes>] (<Comments> <Comment>* </Comments>) [<Employee> <CurrentUser> | <PersonIdentity> </Employee>] </ScheduleOff>

894

Kronos Incorporated

ScheduleOff Tag

Property Descriptions
ShiftSegments

Segments in shift
The set of segments that comprise the shift code schedule Type: Zero or more ShiftSegment tags Introduced in v4; last changed in v5.0 ShiftCodeName

Shift code name
Name of shift code Type: String Maximum length: 50 characters Must identify an existing shift code Introduced in v5.0 Comments

Comments
The set of comments currently returned with this timekeeping item Type: Zero or more Comment tags Output only Introduced in v5.0 CommentText

Comment text
A text string that is attached to the shift, rather than to a shift segment. The comment must be applicable for this category. Type: String Optional Maximum length: 254 characters

Workforce Central Developers Toolkit Reference Guide—Timekeeping

895

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Must match exactly an applicable comment that already exists in the database. The string matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application. Introduced in v5.0; last changed in v5.0 Employee

Employee
One employee who is assigned to the shift, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Optional Must uniquely identify an existing and active employee Introduced in v4 IsDeleted

Is the item inactive?
Indicates whether the item is active. • • If False, the item is active. If True, it is currently inactive.

Type: Boolean Output only Enumerated value: True, False Introduced in v5.0; last changed in v5.0 IsOpenShift

Is this an open shift?
Specifies whether the current Off shift is open. If True, the shift is open. Type: Boolean Optional

896

Kronos Incorporated

ScheduleOff Tag

Default value: False Enumerated value: True, False Introduced in v5.0; last changed in v5.0 Notes

Comment Notes
The list of notes for the comment to be created from comment text Type: Zero or more Note tags Optional Introduced in v6.0 ShiftTypeName

Type of shift
Name of shift type Type: String Optional You can find values in the Workforce Timekeeper user interface. Introduced in v5.0 StartDate

Start date of shift
Contains information that depends on the action you are taking as follows: • If the action is to delete all scheduled shifts, pay codes, and off days that begin on the specified date, it contains the start date of the shift, pay code, or off day being deleted. If the action is to begin importing a new shift, it contains the start date of the shift being imported. If the action is to insert a break in a shift, it contains the start date of the break being imported.

• •

Workforce Central Developers Toolkit Reference Guide—Timekeeping

897

Chapter 2

Workforce Timekeeper XML API Tag Definitions

• • • •

If the action is to insert a transfer in a shift, it contains the start date of the transfer being imported. If the action is to import a new off day, it contains the start date of the off day being imported. If the action is to delete all scheduled shifts and off days that begin on the specified date, it contains the start date of the shift or off day being deleted. If the action is to add an off shift (a shift for an off day on which a person is available to work, if necessary), it contains the start date of the off shift being imported.

Type: Date Required Introduced in v4; last changed in v5.0

Groups of Mutually Exclusive Properties
Shift segment A shift must specify either a ShiftCode or a set of segments, but not both. Required Group includes: ShiftSegments, ShiftCodeName

898

Kronos Incorporated

SchedulePattern Tag

SchedulePattern Tag Schedule Pattern
This tag describes a schedule pattern. Used by: Schedule Function Access Control Point: API.Schedule Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddPatternElements" | "Delete" | "Load" | "LoadAllPatterns" | "LoadTemplatePatterns" | "RetrieveAllForUpdate" | "RetrieveAllNames" | "RetrieveForUpdate" | "Update" Parameters→ None Properties→ <SchedulePattern (EffectiveDateSpan = DateSpan) [Description = String] (Employee = String) [IsTemplateFlag = Boolean] (PeriodLengthInDays = Integer) [PeriodLength = Integer] SchedulePatternName = String (ScheduleGroupName = String)

Workforce Central Developers Toolkit Reference Guide—Timekeeping

899

Chapter 2

Workforce Timekeeper XML API Tag Definitions

[AnchorDate = Date] [PeriodCodeName = String] > [<PatternElements> <PatternElement>* </PatternElements>] </SchedulePattern>

Action Descriptions
AddPatternElements Adds a list of specified pattern elements to an existing pattern or adds a new pattern if one does not already exist If a pattern is added, it must be a template pattern. Return Value Type: None Required Properties: SchedulePatternName Access Control Point Name: Edit Introduced in v4 Delete Marks a pattern for deletion Must be a template pattern Return Value Type: None Required Properties: SchedulePatternName Access Control Point Name: Edit Introduced in v4 Load Returns a single pattern by name Return Value Type: SchedulePattern tag Required Properties: SchedulePatternName Access Control Point Name: View Introduced in v4

900

Kronos Incorporated

SchedulePattern Tag

LoadAllPatterns Returns a list of defined patterns, including templates Return Value Type: Zero or more SchedulePattern tags Required Properties: None Access Control Point Name: View Introduced in v4 LoadTemplatePatterns Returns information about all template patterns Return Value Type: Zero or more SchedulePattern tags Required Properties: None Access Control Point Name: View Introduced in v4 RetrieveAllForUpdate SDM optional action to retrieve all Schedule Patterns. Return Value Type: Zero or more SchedulePattern tags Access Control Point Name: View Introduced in v5.1 RetrieveAllNames SDM required action to retrieve all the names of the Schedule Patterns. Return Value Type: (***undefined***): KBusinessObjectNameList Access Control Point Name: View Introduced in v5.1 RetrieveForUpdate SDM required action to retrieve a Schedule Pattern by name. Return Value Type: SchedulePattern tag Required Properties: SchedulePatternName Access Control Point Name: View Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

901

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Update Adds a new pattern or updates an existing one Must be a template pattern Return Value Type: None Required Properties: SchedulePatternName, AnchorDate, PatternElements, PeriodLength, PeriodCodeName Access Control Point Name: Edit Introduced in v4

Property Descriptions
AnchorDate

Start date for pattern
Specifies the date on which the pattern is scheduled to start Type: Date Optional Introduced in v4 Description

Description of the pattern
Describes the named pattern. A pattern can be associated with an anchor date and assigned to one or more employees or groups of employees. Type: String Optional Introduced in v4; last changed in v5.2 EffectiveDateSpan

Date and time span for the pattern
The span of time that is designated for an instance of the pattern that is starting on a specific anchor date and associated with a specific employee

902

Kronos Incorporated

SchedulePattern Tag

Type: DateSpan Output only Introduced in v5.0 Employee

Employee
The PersonNumber for the specified employee Type: String Output only Must uniquely identify an existing and active employee Introduced in v5.0 IsTemplateFlag

Is the pattern a template?
Indicates whether this pattern is a template Type: Boolean Optional Enumerated value: True, False Introduced in v4 PatternElements

Pattern elements list
Lists the elements that comprise the pattern Type: Zero or more PatternElement tags Optional Introduced in v4; last changed in v5.2 PeriodCodeName

Units of time period (days or weeks)

Workforce Central Developers Toolkit Reference Guide—Timekeeping

903

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The unit of time used for the PeriodLength Type: String Optional Maximum length: 10 characters Enumerated value: Days, Weeks Introduced in v4 PeriodLength

Number of units
The number of units in the availability pattern, as specified by the PeriodCodeName. For example, if the PeriodCodeName is Weeks and PeriodLength is 3, it specifies three weeks. Type: Integer Optional Introduced in v4 PeriodLengthInDays

Number of days for pattern
The number of days to which the pattern applies. This number is formulated by converting the PeriodLength on the basis of the PeriodCodeName. Type: Integer Output Only Introduced in v4 ScheduleGroupName

Schedule group name
The name of the schedule group to which the person is currently assigned Type: String Output only Maximum length: 30 characters

904

Kronos Incorporated

SchedulePattern Tag

You can find values in the Workforce Timekeeper user interface. Introduced in v5.0 SchedulePatternName

Pattern template profile
Defines the name of the schedule pattern template Type: String Required Key Maximum length: 50 characters You can find values in the Workforce Timekeeper user interface. Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

905

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SchedulePayCodeEdit Tag Schedule pay code edit
The SchedulePayCodeEdit tag represents a planned transfer of time or money between labor accounts. Used by: Schedule The ScheduleGroupName and the Employee are mutually exclusive. One must be specified. Function Access Control Point: API.Schedule Introduced in v4; last changed in v6.0

Syntax
Properties→ <SchedulePayCodeEdit AmountInTimeOrCurrency = String AmountInCurrency = Currency AmountInTime = TimeDuration [CommentText = String] (IsDeleted = Boolean) [LaborAccountName = String] [OrgJobPath = String] [IsOverrideAccrual = Boolean] [IsPartialOverride = Boolean] [IsOverride = Boolean] [PayCodeName = String] [StartDate = Date] [UnavailableStartTime = Time] [UnavailableDuration = TimeDuration] DisplayTime = Time > [<Notes> <Note>* </Notes>] (<Comments> <Comment>* </Comments>) [<Employee> <CurrentUser> | <PersonIdentity> </Employee>]

906

Kronos Incorporated

SchedulePayCodeEdit Tag

</SchedulePayCodeEdit>

Property Descriptions
AmountInTimeOrCurrency

Amount of pay code
The amount of the pay code edit, in time or currency, expressed as string, and convert the string to Timeduration or Currency based on amount type of pay code Type: String Introduced in v5.0; last changed in v5.0a AmountInCurrency

Amount of pay code, in currency
The amount of the pay code edit, expressed as currency. Dependency: If AmountInCurrency is specified, the associated PayCodeName must match. Type: Currency Must be between 0 and 999 Introduced in v4 AmountInTime

Amount of pay code, in time
The amount of the pay code edit, expressed as a time value. If AmountInTime is specified, the associated PayCodeName must match. Type: TimeDuration Must be between 00:00 and 100:00 Introduced in v4 Comments

Comments

Workforce Central Developers Toolkit Reference Guide—Timekeeping

907

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The set of comments that are returned with this timekeeping item Type: Zero or more Comment tags Output Only Introduced in v4 CommentText

Comment text
A comment string that is attached to the scheduled pay code edit. Type: String Optional Maximum length: 254 characters Must match exactly an applicable comment that already exists in the database. The string matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application. Introduced in v4; last changed in v5.0 DisplayTime

Time to display in the user interface
The start time of the scheduled pay code edit. Type: Time Required Introduced in v4; last changed in v5.0 Employee

Employee
Either a PersonIdentity or CurrentUser tag. Specifies the employee assigned to the paycode edit. Type: Either CurrentUser or PersonIdentity tag Optional

908

Kronos Incorporated

SchedulePayCodeEdit Tag

Must uniquely identify an existing and active employee. Introduced in v5.0 IsDeleted

Is the item inactive?
Indicates whether the item is active. • • If False, the item is active. If True, it is currently inactive.

Type: Boolean Output only Enumerated value: True, False Introduced in v5.0; last changed in v5.0 IsOverride

Override shift while creating pay code edit?
Indicates whether shifts can be overridden. • • If True, all existing inherited shifts for the specified day are overridden. If False, no override is applied.

Type: Boolean Optional Default value: False Enumerated value: True, False Introduced in v5.0; last changed in v5.0 IsOverrideAccrual

Override shift and allow pay code edit?
Indicates whether an override is acceptable: • • If True, it overrides a warning exception and creates a new pay code edit. f False, it provides a warning message and no pay code edit is added.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

909

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: Boolean Optional Default value: False Enumerated value: True, False Introduced in v5.0 IsPartialOverride

Override shift partially while creating pay code edit?
If IsPartialOverride is True, the shift is partially overridden. Type: Boolean Optional Sample values: True Default value: False Enumerated value: False Introduced in v5.0; last changed in v5.1 LaborAccountName

Labor account
The labor account that is associated with the pay code. Note the following: Do not specify if the scheduled pay code edit applies to the employee's primary account LaborAccountName is required if the scheduled pay code edit applies to a labor account other than the employee's primary account

910

Kronos Incorporated

SchedulePayCodeEdit Tag

If you are adding a comment to a scheduled pay code edit that had an explicit value for LaborAccountName when it was added, you must enter that value. Do not specify if you are deleting a scheduled pay code edit. Enter data for labor accounts in the same format as they appear in timekeeping. If you have a seven-level labor account in the timekeeping configuration, specify a value for each labor level, using the format shown in the following example: 101/202/303/404/504/603/702 You do not have to enter values for any labor levels that are not changing. For example, you can enter 101//303////, indicating that only the first and third labor level entries are different. If any of the labor levels should stay the same as the employee's primary labor account, you can enter @H for those labor levels instead of entering the labor entry names. Type: String Optional Maximum length: 356 characters. Introduced in v4; last changed in v5.1 Notes

Comment notes
The list of notes for the comment to be created from comment text Type: Zero or more Note tags Optional Introduced in v6.0; last changed in v6.0 OrgJobPath

Location of job in the organization

Workforce Central Developers Toolkit Reference Guide—Timekeeping

911

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The organizational job path of the employee whose scheduled pay code edit is being imported. Enter data for OrgJobPath in the same format as it appears in the database. The OrgJobPath string matching is case-sensitive on a server that connects to an Oracle database. @P is a short-hand of employee's primary job. Required: If you are adding a comment to a scheduled pay code edit that had an explicit value for OrgJobPath when it was imported Type: String Optional Maximum length: 1000 characters Dependency: This is required if the scheduled pay code edit applies to an organizational job other than the employee's primary organizational job. Introduced in v5.0; last changed in v5.0 PayCodeName

Pay code
The pay code that is associated with the pay code edit Type: String Optional Maximum length: 50 characters Introduced in v4 StartDate

Start date
The date of the scheduled pay code edit. Type: Date Optional Introduced in v5.0

912

Kronos Incorporated

SchedulePayCodeEdit Tag

UnavailableDuration

Time duration of unavailability
The period of time when an employee is unavailable on a specific day Type: TimeDuration Optional Introduced in v5.0 UnavailableStartTime

Start time for unavailability
The start time for an unavailable duration Type: Time Optional Introduced in v5.0

Groups of Mutually Exclusive Properties
AccrualAmount AccrualAmount is either in Currency or in Time depending on PayCodeName Required Group includes: AmountInTimeOrCurrency, AmountInCurrency, AmountInTime

Workforce Central Developers Toolkit Reference Guide—Timekeeping

913

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SchedulePeriod Tag Schedule Period
The SchedulePeriod tag defines the length of time to be used for the previous, current, and next schedule periods. Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Delete" | "Load" | "LoadAllPeriods" | "RetrieveAllForUpdate" | "RetrieveAllNames" | "RetrieveForUpdate" | "Update" Parameters→ None Properties→ <SchedulePeriod [Description = String] PeriodLength = Integer SchedulePeriodName = String StartDate = Date PeriodCodeName = String > </SchedulePeriod>

Action Descriptions

914

Kronos Incorporated

SchedulePeriod Tag

Delete Marks an existing schedule period for deletion Return Value Type: None Required Properties: SchedulePeriodName Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0 Load Returns all existing schedule period in the database Return Value Type: None Required Properties: SchedulePeriodName Access Control Point Name: View Introduced in v5.0; last changed in v5.0 LoadAllPeriods Load all schedule periods from the database. Return Value Type: Zero or more SchedulePeriod tags Required Properties: None Access Control Point Name: View Introduced in v5.0 RetrieveAllForUpdate SDM optional action to retrieve all Schedule Periods. Return Value Type: Zero or more SchedulePeriod tags Access Control Point Name: View Introduced in v5.1 RetrieveAllNames SDM required action to retrieve all the names of the Schedule Periods. Return Value Type: (***undefined***): KBusinessObjectNameList Access Control Point Name: View Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

915

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RetrieveForUpdate SDM required action to retrieve a Schedule Period by name. Return Value Type: SchedulePeriod tag Required Properties: SchedulePeriodName Access Control Point Name: View Introduced in v5.1 Update Adds a new schedule period or updates an existing one Return Value Type: None Required Properties: PeriodCodeName, PeriodLength, StartDate, SchedulePeriodName Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0

Property Descriptions
Description

Description
Describes the schedule period Type: String Optional Maximum length: 250 characters Introduced in v5.0 PeriodCodeName

Units for time period (days or months)
The unit of time used for the PeriodLength Type: String Required

916

Kronos Incorporated

SchedulePeriod Tag

Default value: Days Enumerated value: Days, Weeks Introduced in v5.0 PeriodLength

Number of units
The number of units in the availability pattern, as specified by the PeriodCodeName. For example, if the PeriodCodeName is Weeks and PeriodLength is 3, it specifies three weeks. Type: Integer Required Introduced in v5.0 SchedulePeriodName

Schedule period name
The name of the schedule period Type: String Required You can find values in the Workforce Timekeeper user interface. Introduced in v5.0 StartDate

Start date (anchor date)
The anchor date for the schedule period Type: Date Required Introduced in v5.0; last changed in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

917

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleRuleOverride Tag Schedule rule override
This tag contains the corressponding actions and properties for schedule rule override Function Access Control Point: API.Schedule Introduced in v6.0; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "Delete" | "Retrieve" | "RetrieveAll" | "Update" Parameters→ None Properties→ <ScheduleRuleOverride (DetailsSummary = String) [EffectiveDate = DateTime] (EmployeeId = Long) [ExpirationDate = DateTime] [Name = String] [PersonNumber = String] [SchedRuleId = Long] > [<ScheduleRuleOverrideDetailsList> <ScheduleRuleOverrideDetails>* </ScheduleRuleOverrideDetailsList>] </ScheduleRuleOverride>

918

Kronos Incorporated

ScheduleRuleOverride Tag

Action Descriptions
AddOnly Adds the schedule rule override Return Value Type: ScheduleRuleOverride tag Required Properties: PersonNumber, SchedRuleId, EffectiveDate, ExpirationDate, ScheduleRuleOverrideDetailsList Access Control Point Name: Edit Introduced in v6.0 Delete Deletes the schedule rule override Return Value Type: None Required Properties: Name Access Control Point Name: Edit Introduced in v6.0 Retrieve Retrieves the ScheduleruleOverride for a specfied name Return Value Type: ScheduleRuleOverride tag Required Properties: Name Access Control Point Name: View Introduced in v6.0 RetrieveAll Retrieves the list of available schedule rule override. Return Value Type: ScheduleRuleOverride tag Required Properties: PersonNumber Access Control Point Name: View Introduced in v6.0 Update Changes to the schedule rule override

Workforce Central Developers Toolkit Reference Guide—Timekeeping

919

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Return Value Type: ScheduleRuleOverride tag Required Properties: Name, ScheduleRuleOverrideDetailsList Access Control Point Name: Edit Introduced in v6.0

Property Descriptions
DetailsSummary

Details summary
Details summary Type: String Output only Introduced in v6.0 EffectiveDate

Effective date
Effective date Type: DateTime Optional Introduced in v6.0 EmployeeId

Employee id
Employee id Type: Long Output only Introduced in v6.0; last changed in v6.0 ExpirationDate

Expiration date

920

Kronos Incorporated

ScheduleRuleOverride Tag

Expiration date Type: DateTime Optional Introduced in v6.0 Name

Name
Name Type: String Optional Introduced in v6.0 PersonNumber

Person number
Person number Type: String Optional Introduced in v6.0 SchedRuleId

Schedule rule id
Schedule rule id Type: Long Optional Introduced in v6.0 ScheduleRuleOverrideDetailsList

Schedule rule override details list
Schedule rule override details list

Workforce Central Developers Toolkit Reference Guide—Timekeeping

921

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: Zero or more ScheduleRuleOverrideDetails tags Optional Introduced in v6.0; last changed in v6.0

922

Kronos Incorporated

ScheduleRuleOverrideDetails Tag

ScheduleRuleOverrideDetails Tag Schedule rule override details
This tag constains the schedule rule override details. Function Access Control Point: API.Schedule Introduced in v6.0; last changed in v6.0

Syntax
Properties→ <ScheduleRuleOverrideDetails ParamQty = Double ParamTypeMMId = Long ParamTypeId = Long (ParamValue = String) ParamValTypeId = Long [WeekDayId = Long] > </ScheduleRuleOverrideDetails>

Property Descriptions
ParamQty

Parameter quantity
Parameter quantity Type: Double Required Introduced in v6.0; last changed in v6.0 ParamTypeId

Parameter type id
Parameter type id Type: Long

Workforce Central Developers Toolkit Reference Guide—Timekeeping

923

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required Introduced in v6.0 ParamTypeMMId

Parameter type MM id
Parameter type MM id Type: Long Required Introduced in v6.0 ParamValTypeId

Parameter value type id
Parameter value type id Type: Long Required Introduced in v6.0; last changed in v6.0 ParamValue

Parameter value
Parameter value Type: String Output only Introduced in v6.0; last changed in v6.0 WeekDayId

Week day id
Week day id Type: Long Optional

924

Kronos Incorporated

ScheduleRuleOverrideDetails Tag

Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

925

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleShift Tag Shift from Schedule
The ScheduleShift tag represents a schedule item that has a contiguous span of time for a single employee or group. Used by: Schedule if you add it to the ScheduleItems property list The ScheduleGroupName and the Employee are mutually exclusive. One must be specified. Function Access Control Point: API.Schedule Introduced in v4; last changed in v6.0

Syntax
Properties→ <ScheduleShift <ShiftSegments> <ShiftSegment>* </ShiftSegments> ShiftCodeName = String [CommentText = String] (IsDeleted = Boolean) [IsOpenShift = Boolean] [OrgJobPath = String] [ScheduleGroupName = String] [ShiftTypeName = String] StartDate = Date > [<Notes> <Note>* </Notes>] (<Comments> <Comment>* </Comments>) [<Employee> <CurrentUser> | <PersonIdentity> </Employee>] </ScheduleShift>

926

Kronos Incorporated

ScheduleShift Tag

Property Descriptions
ShiftSegments

Segments in shift
The set of segments that comprise the shift code schedule Type: Zero or more ShiftSegment tags Introduced in v4 ShiftCodeName

Shift code name
The name of a shift template Type: String Maximum length: 50 characters Must be an existing shift code name You can find values in the Workforce Timekeeper user interface. Introduced in v4 Comments

Comments
The set of comments returned with this shift Type: Zero or more Comment tags Output only Introduced in v5.0 CommentText

Comment text
A text string that is attached to the entire shift, rather than to any shift segment. This string must apply for this category. Type: String Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

927

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Maximum length: 254 characters Must match exactly an applicable comment that already exists in the database. The string matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application. Introduced in v5.0 Employee

Employee
One employee, as specified in a PersonIdentity or CurrentUser tag, who is assigned to the shift. Specify either ScheduleGroupName or Employee, but not both. Type: Either CurrentUser or PersonIdentity tag Optional Must uniquely identify an existing and active employee Introduced in v4 IsDeleted

Is the item inactive?
Indicates whether the item is active. • • If False, the item is active. If True, it is currently inactive.

Type: Boolean Output only Enumerated value: True, False Introduced in v5.0; last changed in v5.0 IsOpenShift

Is this an open shift?
Specifies whether the shift is open. If True, the shift is open. Type: Boolean

928

Kronos Incorporated

ScheduleShift Tag

Optional Enumerated value: True, False Introduced in v5.0; last changed in v5.0 Notes

Comment Notes
The list of notes for the comment to be created from comment text Type: Zero or more Note tags Optional Introduced in v6.0 OrgJobPath

Location of job in the organization
Contains the organizational job path to which the employee is transferring. The OrgJobPath is case-sensitive if your data resides on an Oracle database. Required: When the pay code edits, historical edit, or totaled amount being deleted or commented contained an explicit OrgJobName value Required: When adding a shift that does not apply to the employee's primary organizational job. Dependency: When inserting a transfer within a shift or adding an off shift, you must specify a value for LaborAccountName, WorkRuleName, or OrgJobPath. Type: String Optional Maximum length: 1000 characters Introduced in v5.0; last changed in v5.0 ScheduleGroupName

Schedule group name
The name of the schedule group to which the members of the group are assigned. Specify either ScheduleGroupName or Employee, but not both.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

929

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: String Optional Maximum length: 30 characters You can find values in the Workforce Timekeeper user interface. Introduced in v4 ShiftTypeName

Shift display type
How the shift is displayed Type: String Optional Maximum length: 30 characters Enumerated value: Work Shift, Displayed Unavailable Day, Hide this Shift, Scheduled Pay Code Edit, Hidden Work Shift, Hidden Unavailable Day, Hidden Pay Code Edit, Displayed Off Day, Hidden Off Day, Accrual Amount, Hidden Accrual Amount Introduced in v4; last changed in v5.2 StartDate

Start date of shift
Contains information that depends on the action you are taking as follows: • If the action is to delete all scheduled shifts, pay codes, and off days that begin on the specified date, it contains the start date of the shift, pay code, or off day being deleted. If the action is to begin importing a new shift, it contains the start date of the shift being imported. If the action is to insert a break in a shift, it contains the start date of the break being imported. If the action is to insert a transfer in a shift, it contains the start date of the transfer being imported.

• • •

930

Kronos Incorporated

ScheduleShift Tag

• • •

If the action is to import a new off day, it contains the start date of the off day being imported. If the action is to delete all scheduled shifts and off days that begin on the specified date, it contains the start date of the shift or off day being deleted. If the action is to add an off shift (a shift for an off day on which a person is available to work, if necessary), it contains the start date of the off shift being imported.

Type: Date Required Maximum length: 15 characters Must be within the date span of the containing schedule. Introduced in v4; last changed in v5.0

Groups of Mutually Exclusive Properties
ShiftCodeSegment Either provide ShiftCodeName from shift template or ShiftSegmnets with detailed information for each segment. Required Group includes: ShiftSegments, ShiftCodeName

Workforce Central Developers Toolkit Reference Guide—Timekeeping

931

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleShiftSwap Tag Existing Shift
The ScheduleShiftSwap tag contains an existing shift for actions on schedules that operate on shifts, but do not add new ones. Used by: Process Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.2

Syntax
Properties→ <ScheduleShiftSwap EndDate = Date EndTime = Time StartDate = Date StartTime = Time > <Employee> <CurrentUser> | <PersonIdentity> </Employee> </ScheduleShiftSwap>

Property Descriptions
Employee

Employee
One employee who is assigned to the shift, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Required Must uniquely identify an existing and active employee Introduced in v5.0

932

Kronos Incorporated

ScheduleShiftSwap Tag

EndDate

End date of the shift
End date for shift Type: Date Required Introduced in v5.1; last changed in v5.2 EndTime

End of the shift
The end of the identified shift Type: Time Required Introduced in v5.0 StartDate

Start date for shift
The start date of the identified shift Type: Date Required Introduced in v5.0 StartTime

Start time for shift
The time when the identified shift starts Type: Time Required Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

933

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleUnavailable Tag Unavailable Schedule Period
This tag is a schedule item that describes a schedule period when a person or group is not available for work. Used by: Schedule if you add it to the ScheduleItems property list Function Access Control Point: API.Schedule Introduced in v4; last changed in v6.0

Syntax
Properties→ <ScheduleUnavailable [CommentText = String] EndDate = Date EndTime = Time (IsDeleted = Boolean) (IsLockedFlag = Boolean) [ScheduleGroupName = String] StartDate = Date StartTime = Time > [<Notes> <Note>* </Notes>] (<Comments> <Comment>* </Comments>) [<Employee> <CurrentUser> | <PersonIdentity> </Employee>] </ScheduleUnavailable>

Property Descriptions
Comments

Comments

934

Kronos Incorporated

ScheduleUnavailable Tag

The set of comments currently returned with this unavailable shift Type: Zero or more Comment tags Output only Introduced in v5.0 CommentText

Comment text
A text string that is attached to the shift, rather than to a shift segment. The comment must be applicable for this category. Type: String Optional Maximum length: 254 characters String matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application. Introduced in v5.0 Employee

Employee
One employee, as specified in a PersonIdentity or CurrentUser tag, who is unavailable. Type: Either CurrentUser or PersonIdentity tag Optional Must uniquely identify an existing and active employee Introduced in v4 EndDate

End date of unavailable period
The end date of the unavailable period Type: Date

Workforce Central Developers Toolkit Reference Guide—Timekeeping

935

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required StartDate must be less than or equal to EndDate Introduced in v4 EndTime

End time of unavailable period
The end time associated with the EndDate of the unavailable period Type: Time Required If StartDate is the same as EndDate, then StartTime must be less than EndTime Introduced in v4 IsDeleted

Is the schedule item inactive?
Indicates whether the item is active. - If False, the item is active. - If True, it is currently inactive. An inactive shift is one that has been deleted from an inherited shift item or from a pattern. It displays in the user interface with the text stuck through; it can be restored. This does not apply to an ad hoc shift item, which is deleted. It does not display in the user interface and cannot be restored. Type: Boolean Output only Enumerated value: True, False Introduced in v5.0; last changed in v5.2 IsLockedFlag

Is the schedule item locked?

936

Kronos Incorporated

ScheduleUnavailable Tag

True if the schedule item has been locked. A schedule might be locked because the timecard has been signed off. Type: Boolean Output Only Enumerated value: True, False Introduced in v4; last changed in v5.0 Notes

Comment Notes
The list of notes for the comment to be created from comment text Type: Zero or more Note tags Optional Introduced in v6.0 ScheduleGroupName

Schedule group name
The name of the schedule group to which the person is currently assigned Type: String Optional Maximum length: 30 characters You can find values in the Workforce Timekeeper user interface. Introduced in v4 StartDate

Start date
Contains information that depends on the action you are taking as follows: - If the action is to delete all scheduled shifts, pay codes, and off days that begin on the specified date, it contains the start date of the shift, pay code, or off day being deleted.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

937

Chapter 2

Workforce Timekeeper XML API Tag Definitions

- If the action is to begin importing a new shift, it contains the start date of the shift being imported. - If the action is to insert a break in a shift, it contains the start date of the break being imported. - If the action is to insert a transfer in a shift, it contains the start date of the transfer being imported. - If the action is to import a new off day, it contains the start date of the off day being imported. - If the action is to delete all scheduled shifts and off days that begin on the specified date, it contains the start date of the shift or off day being deleted. - If the action is to add an off shift (a shift for an off day on which a person is available to work, if necessary), it contains the start date of the off shift being imported. Required: If you delete all scheduled shifts, import a shift, insert a break, insert a transfer, import an off day, or import an off shift. Type: Date Required Must be within the date span of the containing schedule. Introduced in v4; last changed in v5.2 StartTime

Start time
Contains information that depends on the action being taken, as follows: - If you begin importing a new shift, it contains the start time of the shift being imported. - If you insert a break in a shift, it contains the start time of the break being imported. - If you insert a transfer in a shift, it contains the start time of the transfer being imported.

938

Kronos Incorporated

ScheduleUnavailable Tag

- If you import a new off day, the start time of the off day being imported. - If you add an off shift (a shift for an off day on which a person is available to work, if necessary), the start time of the off shift being imported. This column is required whenever you import a shift, insert a break in a shift, insert a transfer in a shift, or import an off shift. It is optional when importing an off day. If you do not specify a value, the off day start time defaults to the start of the day. If you specify StartTime, you must have previously specified the UserAccountStatusName in the UserAccountStatus tag. Type: Time Required If StartDate is the same as EndDate, then StartTime must be less than EndTime. Introduced in v4; last changed in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

939

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ScheduleZone Tag Schedule Zone
This tag identifies a period of time during a day for which coverage is measured; for example, the Day schedule zone can be defined as 7 A.M. to 3 P.M. Used by: ScheduleZoneSet Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.2

Syntax
Properties→ <ScheduleZone [ZoneDescription = String] EndTime = Time [NewName = String] ZoneName = String [isDeleted = Boolean] BeginTime = Time > </ScheduleZone>

Property Descriptions
BeginTime

Start time
The starting time for a zone time span Type: Time Required Introduced in v5.0 EndTime

End time
The ending time for a zone time span

940

Kronos Incorporated

ScheduleZone Tag

Type: Time Required Introduced in v5.0 isDeleted

Should the zone be deleted?
Specify if the zone should be deleted or not Type: Boolean Optional Introduced in v5.2; last changed in v5.2 NewName

New zone name
New zone name. Type: String Optional Introduced in v5.2 ZoneDescription

Description of schedule zone
Describes the schedule zone Type: String Optional Maximum length: 250 characters Introduced in v5.0 ZoneName

Schedule zone name
The name of a schedule zone

Workforce Central Developers Toolkit Reference Guide—Timekeeping

941

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: String Required Maximum length: 30 characters You can find values in the Workforce Timekeeper user interface under the Scheduler Setup Workload Setup menu. Sample values: Morning, Evening, 7AM-3PM Introduced in v5.0

942

Kronos Incorporated

ServerTime Tag

ServerTime Tag Server Date and Time
The ServerTime tag represents the date, time, and time zone of the timekeeping server. Function Access Control Point: API.Audit Introduced in v4

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "GetServerTime" Parameters→ None Properties→ <ServerTime (DateTime = DateTime) (KronosTimeZone = String) > </ServerTime>

Action Descriptions
GetServerTime Returns the server's date, time, and timezone. Return Value Type: ServerTime tag Access Control Point Name: View Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

943

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Property Descriptions
DateTime

Date and time at the server
The date and time of the server Type: DateTime Output Only Introduced in v4 KronosTimeZone

Time zone at the server
Time zone at the server Type: String Output Only Maximum length: 30 characters For a list of values, see "Time Zone Definitions" in Appendix B in the Workforce Timekeeper DTK Reference Guide. Introduced in v4

944

Kronos Incorporated

SettingsParamDefinition Tag

SettingsParamDefinition Tag Settings parameters
Represents the parameters of a setting to which a user may configure; for example, the color used to indicate overcoverage in Coverage settings. Function Access Control Point: Location Settings Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" | "RetrieveAll" | "RetrieveAllNames" Parameters→ None Properties→ <SettingsParamDefinition SettingsParameterDefinitionName = String (ValueTypeName = String) > </SettingsParamDefinition>

Action Descriptions
Retrieve Return a parameter definition object given the name. Return Value Type: SettingsParamDefinition tag Required Properties: SettingsParameterDefinitionName Access Control Point Name: View

Workforce Central Developers Toolkit Reference Guide—Timekeeping

945

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v6.0 RetrieveAll Returns all parameter definitions. Return Value Type: Zero or more SettingsParamDefinition tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Return all parameter definitions objects names. Return Value Type: (***undefined***): KBusinessObjectNameList Access Control Point Name: View Introduced in v6.0

Property Descriptions
SettingsParameterDefinitionName

Name of settings parameter
Represents a settings parameter defenition name. Type: String Required Key Sample values: <SettingsParameterDefinitionName> ThisIsAName</ SettingsParameterDefinitionName> Introduced in v6.0; last changed in v6.0 ValueTypeName

Parameter value type
value type expected by this parameter: integer, objectId, date°¦ Type: String Output only

946

Kronos Incorporated

SettingsParamDefinition Tag

Sample values: ValueTypeName="OBJECTID" Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

947

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SettingsParamValue Tag Value of a settings parameter
Represents a settings parameter definition an associated value. Each parameter validates the values differently. Function Access Control Point: Location Settings Introduced in v6.0

Syntax
Properties→ <SettingsParamValue Name = String Value = String > </SettingsParamValue>

Property Descriptions
Name

Name of parameter definition
name of an existing setting parameter definition. Type: String Required Must be an existing parameter definition from SettingsParamValue gold data. Sample values: <SettingsParamValue Value="Admin Assistant;Full Time" Name="WORK_RULES"/> Introduced in v6.0; last changed in v6.0 Value

Parameter value

948

Kronos Incorporated

SettingsParamValue Tag

Value chosen for a parameter definition. Eg: number of decimals = "2". Type: String Required Each parameter class validates the values according to its own rules. Sample values: <SettingsParamValue Value="Admin Assistant;Full Time" Name="WORK_RULES"/> Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

949

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SettingsType Tag Settings Type
Represents the types of settings which are available for user configuration (coverage settings, schedule generation settings, etc). Function Access Control Point: Location Settings (Schedule Setup) Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" | "RetrieveAll" | "RetrieveAllNames" Parameters→ Retrieve→ SettingsTypeName = String Properties→ <SettingsType (Description = String) SettingsTypeName = String > </SettingsType>

Action Descriptions
Retrieve Retrieve a setting type object by name. Return Value Type: SettingsType tag Required Properties: SettingsTypeName

950

Kronos Incorporated

SettingsType Tag

Access Control Point Name: View Introduced in v6.0
Action Parameters Parameter Name SettingsTypeName Description Name of the setting type. Required Additional information Introduced in v6.0

RetrieveAll Retrieves all settings type objects. Return Value Type: Zero or more SettingsType tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Retrieves all settings type objects names. Return Value Type: (***undefined***): KBusinessObjectNameList Access Control Point Name: View Introduced in v6.0

Property Descriptions
Description

Settings type description
Settings type description Type: String Output only Introduced in v6.0 SettingsTypeName

Settings type name

Workforce Central Developers Toolkit Reference Guide—Timekeeping

951

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Representa a settings type object name. Type: String Required Key Sample values: <SettingsTypeName> ThisIsAName</SettingsTypeName> Introduced in v6.0; last changed in v6.0

952

Kronos Incorporated

ShiftBuilder Tag

ShiftBuilder Tag Build employee schedule
The ShiftBuilder tag represents a schedule builder background process that uses an employee's schedule pattern to populate future employee schedules. Function Access Control Point: API.Schedule Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "BuildShifts" | "LoadPopulatedThroughDate" | "PurgeShiftBuilderErrorDetails" | "ResubmitFailedShiftBuilderTasks" Parameters→ None Properties→ <ShiftBuilder (PopulatedThroughDate = Date) [UserName = String] > </ShiftBuilder>

Action Descriptions
BuildShifts Invokes the shift builder process Return Value Type: None Access Control Point Name: Edit

Workforce Central Developers Toolkit Reference Guide—Timekeeping

953

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v4 LoadPopulatedThroughDate To get the PopulatedThroughDate. Return Value Type: None Access Control Point Name: View Introduced in v5.1Beta; last changed in v5.1 PurgeShiftBuilderErrorDetails Purge shift builder error details in the SHIFTBUILDERDTL table, any records older than certain number of days will be purged from the database. Return Value Type: None Access Control Point Name: Edit Introduced in v6.0 ResubmitFailedShiftBuilderTasks Resubmit the failed shift builder entries that are stuck in the SCHEDULEPROC table so they can be retried again. Return Value Type: None Access Control Point Name: Edit Introduced in v6.0

Property Descriptions
PopulatedThroughDate

Date through which the schedule is populated
The populated through date Type: Date Output only none Introduced in v5.1Beta; last changed in v6.0

954

Kronos Incorporated

ShiftBuilder Tag

UserName

User who starts the schedule builder
The name of the user who starts the Schedule Builder Type: String Optional Introduced in v4; last changed in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

955

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ShiftCode Tag Shift
The ShiftCode tag describes a named shift. It can be used for group or individual shifts, or as a template for generating shifts. Function Access Control Point: API.Schedule Introduced in v4; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Delete" | "Load" | "LoadAllShiftCodes" | "RetrieveAllForUpdate" | "RetrieveAllNames" | "RetrieveForUpdate" | "Update" Parameters→ None Properties→ <ShiftCode [Description = String] [Label = String] ShiftCodeName = String > [<ShiftSegments> <ShiftSegment>* </ShiftSegments>] </ShiftCode>

Action Descriptions

956

Kronos Incorporated

ShiftCode Tag

Delete Marks the specified shift code for deletion Return Value Type: None Required Properties: ShiftCodeName Access Control Point Name: Edit Introduced in v4 Load Returns the specified shift code Return Value Type: ShiftCode tag Required Properties: ShiftCodeName Access Control Point Name: View Introduced in v4 LoadAllShiftCodes Returns all user-defined shift codes Return Value Type: Zero or more ShiftCode tags Required Properties: None Access Control Point Name: View Introduced in v4 RetrieveAllForUpdate SDM optional action to retrieve all Shift Codes. Return Value Type: Zero or more ShiftCode tags Access Control Point Name: View Introduced in v5.1 RetrieveAllNames SDM required action to retrieve all the names of the Shift Codes. Return Value Type: (***undefined***): KBusinessObjectNameList Access Control Point Name: View Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

957

Chapter 2

Workforce Timekeeper XML API Tag Definitions

RetrieveForUpdate SDM required action to retrieve a Shift Code by name. Return Value Type: ShiftCode tag Required Properties: ShiftCodeName Access Control Point Name: View Introduced in v5.1 Update Adds a new shift code or updates an existing one Return Value Type: None Required Properties: ShiftCodeName, ShiftSegments Access Control Point Name: Edit Introduced in v4; last changed in v5.0

Property Descriptions
Description

Description of shift code
Describes the shift code Type: String Optional Maximum length: 100 characters Introduced in v4; last changed in v5.2 Label

Label for shift code
The shift code label that displays in the user interface Type: String Optional Maximum length: 30 characters

958

Kronos Incorporated

ShiftCode Tag

Introduced in v4; last changed in v5.2 ShiftCodeName

Shift code name
The shift that can be generated by the system Type: String Required, Key Maximum length: 50 characters Introduced in v4 ShiftSegments

Segments in shift
The set of segments that comprise the specified shift code Type: Zero or more ShiftSegment tags Optional Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

959

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ShiftCountSpan Tag Shift counting exceptions
This tag identifies exceptions to the default counting rules. An exception occurs when a default counting rule is not used for a shift, but the majority rule is used instead. Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.2

Syntax
Properties→ <ShiftCountSpan EndTime = Time BeginTime = Time > </ShiftCountSpan>

Property Descriptions
BeginTime

Start time
The starting time for a shift count span Type: Time Required Introduced in v5.0 EndTime

End time
The ending time for a shift count span Type: Time Required

960

Kronos Incorporated

ShiftCountSpan Tag

Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

961

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ShiftHistory Tag Shift history
The ShiftHistory tag to retrieve a shift's history. Function Access Control Point: API.Schedule Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" Parameters→ None Properties→ <ShiftHistory <Employee> <PersonIdentity> </Employee> OrgJobPath = String (Action = String) (Comment = String) (NewShift = String) (Reason = String) (Info = String) (DateTime = DateTime) DateTimeSpan = DateTimeSpan (UserName = String) > </ShiftHistory>

Action Descriptions

962

Kronos Incorporated

ShiftHistory Tag

Retrieve Retrieve action to retrieve a shift's history. Return Value Type: Zero or more ShiftHistory tags Required Properties: DateTimeSpan, Employee or OrgJobPath but not both. Access Control Point Name: View Introduced in v5.2

Property Descriptions
Employee

Employee
The employee to whom the schedule applies. Type: PersonIdentity tag Employee and OrgJobPath are mutually exclusive. Introduced in v5.2; last changed in v5.2 OrgJobPath

Organizational job
The fully qualified Organization job is used to retrieve the booked-off open shift history. Type: String OrgJobPath and Employee are mutually exclusive. Introduced in v5.2; last changed in v5.2 Action

Action
The shift history action. Type: String Output only

Workforce Central Developers Toolkit Reference Guide—Timekeeping

963

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v5.2; last changed in v5.2 Comment

Comment
The comment of the modification. Type: String Output only Introduced in v5.2; last changed in v5.2 DateTime

Shift modified date and time.
The shift modified date and time. Type: DateTime Output only Introduced in v5.2 DateTimeSpan

Shift span
The fully qualified date time span to define a shift's duration. Type: DateTimeSpan Required Introduced in v5.2 Info

Shift information
The shift information. Type: String Output only Introduced in v5.2; last changed in v5.2

964

Kronos Incorporated

ShiftHistory Tag

NewShift

New shift
Information of the new created shift. Type: String Output only Introduced in v5.2; last changed in v5.2 Reason

Reason
The Book-Off, Book-On or Relief Not Needed reason. Type: String Output only Introduced in v5.2; last changed in v5.2 UserName

User who modified the shift
The user who modified the shift. Type: String Output only Introduced in v5.2; last changed in v5.2

Groups of Mutually Exclusive Properties
Employee Must have either Employee or OrgJobPath but not both Required Group includes: Employee, OrgJobPath

Workforce Central Developers Toolkit Reference Guide—Timekeeping

965

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ShiftSegment Tag Shift Segment
The ShiftSegment tag represents shift-related information for a single time span. Used by: ScheduleOff, ScheduleShift, and ShiftCode Function Access Control Point: API.Schedule Introduced in v4; last changed in v5.2

Syntax
Properties→ <ShiftSegment EndTime = Time [LaborAccountName = String] [OrgJobPath = String] EndDayNumber = Integer StartDayNumber = Integer [SegmentTypeName = String] [StartTime = Time] [WorkRuleName = String] > </ShiftSegment>

Property Descriptions
EndDayNumber

Offset for end day in shift
The day offset of the segment end within its shift Type: Integer Required StartDayNumber must be less than or equal to EndDayNumber Introduced in v4

966

Kronos Incorporated

ShiftSegment Tag

EndTime

End time
The segment end time within its end day Type: Time Required If StartDayNumber is the same as EndDayNumber, then StartTime must be less than EndTime. Introduced in v4 LaborAccountName

Labor account
This is the name of the labor account to charge for this activity. Enter data for labor accounts in the same format as they appear in the timekeeping database. If you have a seven-level labor account, specify a value for each labor level, using the following format: 101/202/303/404/504/603/702 Do not specify labor levels that are not changing. Type: String Optional Maximum length: 356 characters Introduced in v4 OrgJobPath

Location of job in the organization
The organizational job path to which the employee is transferring. OrgJobPath is optional when you import a shift, insert a transfer, import an off day, or import an off shift. When adding a shift, it can be left blank if the shift being added applies to the employee's primary organizational job. When inserting a transfer within a shift or adding an off shift, you must specify a value LaborAccountName, WorkRuleName, or OrgJobPath.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

967

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Enter data for OrgJobPath in the same format as it appears in the database. The OrgJobPath string matching is case-sensitive on a Workforce Central server that connects to an Oracle database. Type: String Optional Maximum length: 1000 characters Introduced in v5.0; last changed in v5.2 SegmentTypeName

Segment type
The type of activity that the segment represents Type: String Optional Maximum length: 30 characters Default value: Regular Enumerated value: Regular, Unavailable, Transfer, Break, Off, Regular PCE, Availability PCE, Accrual Edit Introduced in v4; last changed in v5.2 StartDayNumber

Offset for start day in shift
The day offset of the segment within its shift Type: Integer Required StartDayNumber must be less than or equal to EndDayNumber Introduced in v4 StartTime

Start time
Contains information that depends on the action being taken, as follows:

968

Kronos Incorporated

ShiftSegment Tag

- If you begin importing a new shift, it contains the start time of the shift being imported. - If you insert a break in a shift, it contains the start time of the break being imported. - If you insert a transfer in a shift, it contains the start time of the transfer being imported. - If you import a new off day, the start time of the off day being imported. - If you add an off shift (a shift for an off day on which a person is available to work, if necessary), the start time of the off shift being imported. This column is required whenever you import a shift, insert a break in a shift, insert a transfer in a shift, or import an off shift. It is optional when importing an off day. If you do not specify a value, the off day start time defaults to the start of the day. Type: Time Optional Maximum length: 15 characters If StartDate is the same as EndDate, then StartTime must be less than EndTime. Dependency: If you specify StartTime, you must have previously the UserAccountStatusName in the UserAccountStatus tag. Introduced in v4; last changed in v5.2 WorkRuleName

Work rule
Name of the work rule that describes the activity The following predefined data values are provided: &ALL_WORK_RULES &EMPTY Type: String

Workforce Central Developers Toolkit Reference Guide—Timekeeping

969

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Maximum length: 50 characters You can find values in the Timekeeping Application. Introduced in v4; last changed in v5.2

970

Kronos Incorporated

ShiftStartTimeBand Tag

ShiftStartTimeBand Tag Shift Start Time Band
The ShiftStartTimeBand tag describes a named start time of the shift. Function Access Control Point: API.Schedule Introduced in v5.1; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "addOnly" | "deleteOnly" | "retrieve" | "retrieveAll" | "update" | "updateOnly" Parameters→ None Properties→ <ShiftStartTimeBand [ActiveSwitch = Boolean] Name = String DisplayName = String [NewName = String] StartTime = Time > </ShiftStartTimeBand>

Action Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

971

Chapter 2

Workforce Timekeeper XML API Tag Definitions

addOnly Stores shift start band in the database. Returns an error if object with the same name exists Validate all properties including optional Return Value Type: Boolean Required Properties: Name, DisplayName, StartTime Optional Properties: ActiveFlag Access Control Point Name: Edit Introduced in v5.1 deleteOnly Logically deletes the shift start time band object from the database or returns an error if object does not exists Validate Name property. Return Value Type: Boolean Required Properties: Name Access Control Point Name: Edit Introduced in v5.1 retrieve Retrieves shift start time band object from the database by name Validate the Name property. Return Value Type: ShiftStartTimeBand tag Required Properties: Name Access Control Point Name: View Introduced in v5.1 retrieveAll Retrieves all ShiftStartTimeBand objects from the database Return Value Type: (***undefined***): List of ShiftStartTimeBand Access Control Point Name: View

972

Kronos Incorporated

ShiftStartTimeBand Tag

Introduced in v5.1 update Persists the shift start time band object in the database or updates with new data if object exists. Validate all properties including optional. Return Value Type: Boolean Required Properties: Name Optional Properties: NewName, DisplayName, StartTime, ActiveSwitch Access Control Point Name: Edit Introduced in v5.1 updateOnly Updates the start time band object in the database. Returns an error if object does not exist or the new name is not unique Validate all properties including optional Return Value Type: Boolean Required Properties: Name Optional Properties: NewName, DisplayName, StartTime, ActiveSwitch Access Control Point Name: Edit Introduced in v5.1

Property Descriptions
ActiveSwitch

Is the band active?
The active band flag. Type: Boolean Optional Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

973

Chapter 2

Workforce Timekeeper XML API Tag Definitions

DisplayName

Name to display in the user interface
The shift start time band display name Type: String Required Can not be null and should contain between 1 and 50 characters. Introduced in v5.1; last changed in v5.1 Name

Name of band
The shift start time band name Type: String Required The value can not be null and should contain from 1 to 50 characters. Introduced in v5.1 NewName

New Name
The new name of the shift start time band ( for update action only) Type: String Optional Cannot be null and should contain between 1 and 30 characters. Introduced in v5.1; last changed in v5.2 StartTime

Start Time
The shift start time (required for add, optional for update) Type: Time

974

Kronos Incorporated

ShiftStartTimeBand Tag

Required Can not be null Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

975

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ShiftTemplateAssignment Tag Shift Template Profiles assigned to an employees
The ShiftTemplateAssignment tag consists of one or more shift template profiles for one employee who has been identified in the ShiftTemplateItem. Function Access Control Point: API.Schedule Introduced in v5.1Beta; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAll" | "Update" Parameters→ None Properties→ <ShiftTemplateAssignment <ShiftTemplateItems> <ShiftTemplateItem>* </ShiftTemplateItems> </ShiftTemplateAssignment>

Action Descriptions
Load Returns all shift template profiles for the employee specified in the ShiftTemplateItem tag.

976

Kronos Incorporated

ShiftTemplateAssignment Tag

All ShiftTemplateItem tags that are returned must identify the same existing employee. Return Value Type: ShiftTemplateAssignment tag Required Properties: ShiftTemplateItems Access Control Point Name: View Introduced in v5.1Beta LoadAll Loads all shift template profiles in the system. Return Value Type: Zero or more ShiftTemplateItem tags Required Properties: none Access Control Point Name: View Introduced in v5.1Beta Update Updates a person's shift template profile. Return Value Type: None Required Properties: ShiftTemplateItems Access Control Point Name: Edit Introduced in v5.1Beta

Property Descriptions
ShiftTemplateItems

Shift template items
One or more shift template assignments, as shown in the ShiftTemplateItem tag. Type: Zero or more ShiftTemplateItem tags Required Introduced in v5.1Beta; last changed in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

977

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ShiftTemplateItem Tag Shift Template Item
The ShiftTemplateItem tag defines an element of a shift template profile assignment. Function Access Control Point: API.Schedule Introduced in v5.1Beta; last changed in v5.0a

Syntax
Properties→ <ShiftTemplateItem ShiftTemplateProfileName = String > <Employee> <PersonIdentity> </Employee> </ShiftTemplateItem>

Property Descriptions
Employee

Employee
The employee to whom the shift code template profile is assigned Type: PersonIdentity tag Required Key Must be a unique and existing employee Introduced in v5.1Beta ShiftTemplateProfileName

Shift template profile name
The name of an existing shift code profile Type: String

978

Kronos Incorporated

ShiftTemplateItem Tag

Optional Key Introduced in v5.1Beta

Workforce Central Developers Toolkit Reference Guide—Timekeeping

979

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ShiftValidation Tag Shift Validation
The ShiftValidation tag determines if a shift has been assigned to an identified employee within a specified date and time range. Function Access Control Point: API.Schedule Introduced in v5.1Beta; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" Parameters→ None Properties→ <ShiftValidation (IsShiftExists = Boolean) EndTime = Time QueryDate = Date StartTime = Time > <Employee> <PersonIdentity> </Employee> </ShiftValidation>

Action Descriptions
Load The Load action returns the ShiftValidation tag. The IsShiftExists property will have a value of True if the shift exists.

980

Kronos Incorporated

ShiftValidation Tag

Return Value Type: ShiftValidation tag Required Properties: QueryDate, StartTime, EndTime, Employee Access Control Point Name: View Introduced in v5.1Beta

Property Descriptions
Employee

Employee
One employee, as specified in a PersonIdentity tag Type: PersonIdentity tag Required Key Must uniquely identify an existing and active employee Introduced in v5.1Beta EndTime

Shift end time
The time when the shift ends Type: Time Required Introduced in v5.1Beta; last changed in v5.2 IsShiftExists

Is shift assigned to employee?
Indicates whether a shift as been assigned to the employee for the specified date and time range. A value of true means there is such an assignment. Type: Boolean Output only Introduced in v5.1Beta

Workforce Central Developers Toolkit Reference Guide—Timekeeping

981

Chapter 2

Workforce Timekeeper XML API Tag Definitions

QueryDate

Shift start date
The date when the shift starts Type: Date Required Introduced in v5.1Beta StartTime

Shift start time
The time when the shift begins Type: Time Required Introduced in v5.1Beta; last changed in v5.2

982

Kronos Incorporated

Signature Tag

Signature Tag Signature
Used in a Procedure to hold the prototype of the Procedure Function Access Control Point: Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Add" | "AddOnly" | "Delete" | "DeleteOnly" | "Retrieve" | "RetrieveAll" | "RetrieveAllForUpdate" | "RetrieveAllNames" | "RetrieveForUpdate" | "Update" | "UpdateOnly" Parameters→ None Properties→ <Signature SignatureName = String > </Signature>

Action Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

983

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Add Inserts one Signature object in the database . If it's already there a rule with the same name nothing happens. Return Value Type: None Required Properties: SignatureName Access Control Point Name: Edit Introduced in v6.0 AddOnly Inserts one Signature object in the database . If it's already there an error is thrown. Return Value Type: None Required Properties: SignatureName Access Control Point Name: Edit Introduced in v6.0 Delete Deletes the Signature object from the database that has the same name as the one specified in the SignatureName. If it's not there nothing happens. Return Value Type: None Required Properties: SignatureName Access Control Point Name: Edit Introduced in v6.0 DeleteOnly Deletes the Signature object from the database that has the same name as the one specified in the SignatureName. If it's not there an error is thrown. Return Value Type: None Required Properties: SignatureName Access Control Point Name: Edit Introduced in v6.0

984

Kronos Incorporated

Signature Tag

Retrieve Retrieves the Signature object that has the same name as the one specified in the SignatureName. Return Value Type: Signature tag Required Properties: SignatureName Access Control Point Name: View Introduced in v6.0 RetrieveAll Retrieves all the Signature objects. Return Value Type: Zero or more Signature tags Access Control Point Name: View Introduced in v6.0 RetrieveAllForUpdate Retrieves all the Signature objects. Return Value Type: Zero or more Signature tags Access Control Point Name: View Introduced in v6.0; last changed in v6.0 RetrieveAllNames Retrieves all the names for all Signature objects. Return Value Type: String list Access Control Point Name: View Introduced in v6.0 RetrieveForUpdate Retrieves the Signature object that has the same name as the one specified in the SignatureName. Return Value Type: Signature tag Required Properties: SignatureName Access Control Point Name: View

Workforce Central Developers Toolkit Reference Guide—Timekeeping

985

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v6.0 Update Updates one Signature object in the database . If it's not there it's inserted, if it's there it's updated. Return Value Type: None Required Properties: SignatureName Access Control Point Name: Edit Introduced in v6.0 UpdateOnly Updates one Signature object in the database . If it's not there an error is thrown. Return Value Type: None Required Properties: SignatureName Access Control Point Name: Edit Introduced in v6.0

Property Descriptions
SignatureName

Signature Name
Defines the name property of the Signature object. Type: String Required Key Introduced in v6.0

986

Kronos Incorporated

SignatureItem Tag

SignatureItem Tag Signature Item
This object is the small part of a Signature object. Function Access Control Point: Priority Scheduling Engine Introduced in v6.0

Syntax
Properties→ <SignatureItem ProcedureParameterDefinitionName = String ProcedureParameterName = String > </SignatureItem>

Property Descriptions
ProcedureParameterDefinitionName

Procedure Parameter Definition Name
The name of the procedure parameter definition object of this SignatureItem object. Type: String Required Key Introduced in v6.0 ProcedureParameterName

Procedure Parameter Name
The name of procedure parameter. Type: String Required Key Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

987

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SimplePair Tag Simple Pair
The SimplePair tag contains Key and Value. Function Access Control Point: API.Common Introduced in v5.2; last changed in v5.2

Syntax
Properties→ <SimplePair Key = String Value = String > </SimplePair>

Property Descriptions
Key

Key
A primitive value whose format depends on the action or property that returns it, and can represent an alphanumeric string, an integer, or a boolean type. Type: String Required Default value: String Introduced in v5.2 Value

Value
A primitive value whose format depends on the action or property that returns it, and can represent an alphanumeric string, an integer, or a boolean type. Type: String

988

Kronos Incorporated

SimplePair Tag

Required Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

989

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SimpleValue Tag Simple Value
The SimpleValue tag contains a single primitive value. This tag is used mainly when an action returns a primitive type, such as Integer or String. Function Access Control Point: API.Common Introduced in v4

Syntax
Properties→ <SimpleValue Value = String > </SimpleValue>

Property Descriptions
Value

Value
A primitive value whose format depends on the action or property that returns it, and can represent an alphanumeric string, an integer, or a boolean type. Type: String Required This property represents one value. Introduced in v4

990

Kronos Incorporated

StaffingRequirement Tag

StaffingRequirement Tag Staffing requirement
This tag returns the daily coverage (required/scheduled) for every location and for every time span. Function Access Control Point: Schedule Planner Introduced in v6.0

Syntax None

Workforce Central Developers Toolkit Reference Guide—Timekeeping

991

Chapter 2

Workforce Timekeeper XML API Tag Definitions

StandardShift Tag Standard Shift
The StandardShift tag describes a named time span. Used by: StandardShiftSet Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.0

Syntax
Properties→ <StandardShift [ShiftDescription = String] EndTime = Time ShiftName = String BeginTime = Time > </StandardShift>

Property Descriptions
BeginTime

Start time
The starting time for the shift Type: Time Required Introduced in v5.0 EndTime

End time
The ending time for the shift Type: Time Required

992

Kronos Incorporated

StandardShift Tag

Introduced in v5.0 ShiftDescription

Description
Describes the shift Type: String Optional Maximum length: 250 characters Introduced in v5.0 ShiftName

Shift name
The name of the shift Type: String Required Maximum length: 30 characters You can find values in the Workforce Timekeeper user interface under the Scheduler Setup Workload Setup menu. Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

993

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SuiteProduct Tag Product in Suite
The SuiteProduct tag provides license information about products in the suite. The product that is specified must be defined to the system, but need not be installed. Function Access Control Point: API.Person Introduced in v5.0; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadAll" | "LoadByName" Parameters→ None Properties→ <SuiteProduct (InstalledSw = Boolean) (LicensedSw = Boolean) (IndependentProductSw = Boolean) [SuiteProductName = String] (Version = String) > </SuiteProduct>

Action Descriptions
LoadAll Returns information about all suite products in the system.

994

Kronos Incorporated

SuiteProduct Tag

Return Value Type: Zero or more SuiteProduct tags Access Control Point Name: View Introduced in v5.0; last changed in v5.0 LoadByName Returns information about the requested suite product. Return Value Type: SuiteProduct tag Required Properties: SuiteProductName Access Control Point Name: View Introduced in v5.0; last changed in v5.0

Property Descriptions
IndependentProductSw

Is this a standalone product?
Specifies whether the product is part of the suite or is independent Type: Boolean Output only Enumerated value: True, False Introduced in v5.0; last changed in v5.0 InstalledSw

Is the product installed?
Specifies whether the product is installed Type: Boolean Output only Enumerated value: True, False Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

995

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LicensedSw

Is the product licensed?
Specifies whether the suite is licensed Type: Boolean Output only Enumerated value: True, False Introduced in v5.0; last changed in v5.0 SuiteProductName

Suite product name
The name of the suite product for which information is requested Type: String Optional Introduced in v5.0 Version

Version of suite product
The version of the suite product. Type: String Output only Introduced in v5.0

996

Kronos Incorporated

Supervisor Tag

Supervisor Tag Person Employee Reports To
The Supervisor tag identifies the person who is defined as the supervisor for the containing tag. This name specified in this tag is not related to any system rights. Used by: PersonInformation Function Access Control Point: API.Person Introduced in v4; last changed in v5.1

Syntax None

Workforce Central Developers Toolkit Reference Guide—Timekeeping

997

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SwapShiftEmployees Tag Employees Eligible for Swap Shifts
The SwapShiftEmployees tag contains information about an employee who can swap a shift with another shift. Must be an active employee. The specified shift must be exist. Function Access Control Point: API.Schedule Introduced in v5.1Beta; last changed in v5.1Beta

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadEligibleEmployees" Parameters→ None Properties→ <SwapShiftEmployees EndTime = Time QueryDate = Date StartTime = Time > <Employee> <PersonIdentity> </Employee> </SwapShiftEmployees>

Action Descriptions

998

Kronos Incorporated

SwapShiftEmployees Tag

LoadEligibleEmployees This action returns one or more employees who can swap with the specified shift. Return Value Type: Zero or more Person tags Required Properties: Employee, QueryDate, StartTime, EndTime Access Control Point Name: View Introduced in v5.1Beta

Property Descriptions
Employee

Employee
One employee, as specified in a PersonIdentity tag. Type: PersonIdentity tag Required Must uniquely identify an existing and active employee. If the employee has a Workforce_Scheduler_Employee license and specifies True for IsCreateOpenShift, you will be able to create open shifts. Otherwise IsCreateOpenShift will have no effect. Introduced in v5.1Beta EndTime

Shift end time
The end time for the shift that needs to be swapped Type: Time Required Introduced in v5.1Beta QueryDate

Shift start date
The start date for a shift that can be swapped.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

999

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: Date Required Introduced in v5.1Beta StartTime

Shift start time
Start time for the shift that can be swapped. Type: Time Required Introduced in v5.1Beta

1000

Kronos Incorporated

SwapShiftJobs Tag

SwapShiftJobs Tag Jobs Eligible for Swap Shifts
This tag returns job list for a shift swap. Function Access Control Point: API.Schedule Introduced in v5.1Beta; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadJobs" Parameters→ None Properties→ <SwapShiftJobs EndTime = Time QueryDate = Date StartTime = Time > <Employee> <PersonIdentity> </Employee> (<OrgJobs> <OrgJob>* </OrgJobs>) </SwapShiftJobs>

Action Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1001

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LoadJobs This action returns one or more jobs for the shift within the specified date and time span. Return Value Type: Zero or more OrgJob tags Access Control Point Name: View Introduced in v5.1Beta

Property Descriptions
Employee

Employee
One employee, as specified in a PersonIdentity tag. Type: PersonIdentity tag Required Must uniquely identify an existing and active employee. Introduced in v5.1Beta EndTime

Shift end time
This property is the end time of a shift. Type: Time Required Introduced in v5.1Beta OrgJobs

Organization jobs
This property is a tag list property that represent a list of organization jobs. Type: Zero or more OrgJob tags Output only

1002

Kronos Incorporated

SwapShiftJobs Tag

Introduced in v5.1Beta; last changed in v5.1 QueryDate

Shift start date
This property is the start date of a shift. Type: Date Required Introduced in v5.1Beta StartTime

Shift start time
This property is the start time of a shift Type: Time Required Introduced in v5.1Beta

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1003

Chapter 2

Workforce Timekeeper XML API Tag Definitions

SwitchRoleEngine Tag SwitchRoleEngine
The SwitchRoleEngine tag will switch the role from myself to the delegator role or switch back from the delegator role to myself. Function Access Control Point: API.People Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "SwitchBackToMyself" | "SwitchRole" Parameters→ None Properties→ <SwitchRoleEngine delegatorFullName = String delegatorPersonNum = String roleProfileName = String > </SwitchRoleEngine>

Action Descriptions
SwitchBackToMyself Switch the role back to myself. Return Value Type: None Required Properties: none Access Control Point Name: Edit

1004

Kronos Incorporated

SwitchRoleEngine Tag

Introduced in v5.2 SwitchRole Switch the current user to the identifier with role profile one of the delegator identifier and role profile name cannot be null or empty Return Value Type: None Required Properties: Delegator Identifier, Role Profile Name Access Control Point Name: Edit Introduced in v5.2

Property Descriptions
delegatorFullName

delegator Full Name
The name of the delegator. Specify the name as last name, comma, space, first name, space, middle initial. Type: String Maximum length: 64 characters Introduced in v5.2; last changed in v5.2 delegatorPersonNum

delegator Person Number
The person number of the delegator. Type: String Maximum length: 15 characters Introduced in v5.2; last changed in v5.2 roleProfileName

role Profile Name
The name of the delegation role profile name.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1005

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: String Required Maximum length: 50 characters Introduced in v5.2; last changed in v5.2

Groups of Mutually Exclusive Properties
Delegator Identifier One member or both members of the Identifier group can be specified.. Outstanding: Identifier usage constraint is specified as Required. But only one member of the Identifier group is required. Their values can be none. Required Group includes: delegatorFullName, delegatorPersonNum

1006

Kronos Incorporated

SystemSettings Tag

SystemSettings Tag System Settings
The SystemSettings tag returns the value of system settings on the application server. For a description of system settings, see the online help (System Configuration System Settings). If the requested system settings do not exist, a list of null values is returned. Function Access Control Point: APIBeans.COMMON Introduced in v5.0; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" Parameters→ Load→ KeyNames = String Properties→ <SystemSettings (Key = String) (Value = String) > </SystemSettings>

Action Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1007

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Load Returns system settings that match parameter values. There can be more than one system setting that matches a parameter. For example, a parameter of site.local would return all site.local.* system settings. Return Value Type: Zero or more SystemSettings tags Access Control Point Name: View Introduced in v5.0
Action Parameters Parameter Name KeyNames Description A comma separated list of system setting keys. Each item in the list represents one or more system settings. Required Additional information Introduced in v5.0

Property Descriptions
Key

Key for the system setting
A unique key for a system setting Type: String Output only Sample values: site.locale Introduced in v5.0 Value

Value for the system setting
The value of a requested system setting.

1008

Kronos Incorporated

SystemSettings Tag

Type: String Output only Introduced in v5.0; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1009

Chapter 2

Workforce Timekeeper XML API Tag Definitions

TelephoneNumber Tag Telephone Number
The TelephoneNumber tag defines a person's telephone number. Used by: PersonInformation Function Access Control Point: API.Person Introduced in v4; last changed in v6.0

Syntax
Properties→ <TelephoneNumber PhoneNumber = String ContactTypeName = String > </TelephoneNumber>

Property Descriptions
ContactTypeName

Type of contact
The customer-defined name of the contact category; up to three telephone numbers can be provided. You can define the contact category name using Workforce Central Setup Application. Type: String Required Key Maximum length: 30 characters Values for CustomTypeName can be changed through the Workforce Central Setup Application. Sample values: Home Phone, Work Phone, Mobile Phone

1010

Kronos Incorporated

TelephoneNumber Tag

Introduced in v4; last changed in v6.0 PhoneNumber

Phone number
The telephone number for the specified contact type Type: String Required Maximum length: 35 characters A maximum of three phone numbers can be specified for a person in Workforce Timekeeper. Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1011

Chapter 2

Workforce Timekeeper XML API Tag Definitions

TimeEntry Tag Time Entry
The TimeEntry tag returns information about valid time entries defined within the system. The Time Entry Method determines how employees will see time when entering data. Function Access Control Point: API.Employee Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllTimeEntries" | "LoadById" Parameters→ None Properties→ <TimeEntry [TimeEntryId = Integer] [TimeEntryName = String] > </TimeEntry>

Action Descriptions
Load Returns a time entry, based on TimeEntryName. Name should be valid Return Value Type: TimeEntry tag

1012

Kronos Incorporated

TimeEntry Tag

Required Properties: TimeEntryName Access Control Point Name: View Introduced in v4 LoadAllTimeEntries Returns all time entries in the system. Return Value Type: Zero or more TimeEntry tags Required Properties: None Access Control Point Name: View Introduced in v4 LoadById Returns a time entry, based on TimeEntryID. ID must be valid Return Value Type: TimeEntry tag Required Properties: TimeEntryID Access Control Point Name: View Introduced in v4

Property Descriptions
TimeEntryId

Id of time entry
Uniquely identifies the TimeEntryProfile in the database Type: Integer Optional Introduced in v4 TimeEntryName

Time entry name
The name for the common set of TimeEntries that a group of employees can select

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1013

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: String Optional Enumerated value: Timestamp, Timestamp & Hourly View, Hourly View, Project View Introduced in v4

1014

Kronos Incorporated

TimeFramePeriod Tag

TimeFramePeriod Tag Time Frame for a Period of Time
The TimeFramePeriod tag describes a period of time. Used by: a number of other tags Function Access Control Point: API.Common Introduced in v4; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadAllTimeFrames" | "LoadDateRange" Parameters→ None Properties→ <TimeFramePeriod [TimeFrameDate = Date] [PeriodDateSpan = DateSpan] TimeFrameName = String > </TimeFramePeriod>

Action Descriptions
LoadAllTimeFrames Returns all time frames in the system. Only TimeFrameName is returned Return Value Type: Zero or more TimeFramePeriod tags

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1015

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Required Properties: None Access Control Point Name: View Introduced in v4 LoadDateRange Parameter MAP could have any Parameters like CURRENT_PAY_PERIOD, PREVIOUS_PAY_PERIOD, NEXT_PAY_PERIOD, CURRENT_SCHEDULE_PERIOD, PREVIOUS_SCHEDULE_PERIOD, NEXT_SCHEDULE_PERIOD, WEEK_TO_DATE, LAST_WEEK, YESTERDAY, TODAY, DATE_RANGE, and SPECIFIC_DATE. Return Value Type: (***undefined***): APITimeFramePeriodBean Required Properties: ParameterMap Access Control Point Name: View Introduced in v5.2; last changed in v5.2

Property Descriptions
PeriodDateSpan

Span of dates
The start and end dates, dash separated, for the specified period Type: DateSpan Optional For input, the value is the time span for the period. For output, the value is the time span for the resulting information. Introduced in v4 TimeFrameDate

Reference date
A date for a time span that requires a reference date Type: Date Optional

1016

Kronos Incorporated

TimeFramePeriod Tag

If the value of the TimeFrameName is Specific-Date, this property contains the value of that date. Introduced in v4 TimeFrameName

Time frame name
The name of the time frame Specify one of the following numbers to represent the data value: • • • • • • • • • • • • 0 for Previous_Payperiod 1 for Current_Payperiod 2 for Next_Payperiod 3 for Previous_SchedPeriod 4 for Current_SchedPeriod 5 for Next_SchedPeriod 6 for Week_to_Date 7 for Last_Week 8 for Yesterday 9 for Range_of_Dates 11 for Specific_Date 13 for Today

Type: String Required Maximum length: 1 character Enumerated value: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 13 Introduced in v4; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1017

Chapter 2

Workforce Timekeeper XML API Tag Definitions

TimekeepingException Tag Timekeeping Exception
The TimekeepingException tag describes an exception that occurred as a result of a timekeeping exception rule such as late, early, or missing punch. Used by: TotaledSpan, WorkedDuration Function Access Control Point: API.Timecard Introduced in v4

Syntax
Properties→ <TimekeepingException (MissedOutDateTime = DateTime) (DifferenceToLimit = TimeDuration) (ExceptionTypeName = String) (AssociatedWithInPunchFlag = Boolean) (MinimumNumberOfActiveDays = Integer) (ActualNumberOfActiveDays = Integer) (NumberOfWorkedDays = Integer) (DurationOfException = TimeDuration) > </TimekeepingException>

Property Descriptions
ActualNumberOfActiveDays

Number of active days
Meaningful only for MinimumDaysActive and MinimumDaysEmployed timekeeping exceptions Type: Integer Output Only Introduced in v4

1018

Kronos Incorporated

TimekeepingException Tag

AssociatedWithInPunchFlag

Is the exception associated with an in-punch?
True if the exception is associated with an In punch, False if it is associated with an Out punch Type: Boolean Output Only Enumerated value: True, False Introduced in v4 DifferenceToLimit

Difference between triggering limit and time of event
Specifies the difference between the triggering limit and the time of the event. Meaningful only for timekeeping exceptions identified as Early, Late, VeryEarly, VeryLate, Long, or Short. For example, if there is a Late limit of 0:32, and if the employee punches out at 1:00 past the scheduled end of shift, the DifferentToLimit is 0:28. Type: TimeDuration Output Only Introduced in v4 DurationOfException

Time duration for exception
Specifies the sum of the DifferenceToLimit and the value of the triggering limit. Meaningful only for Early, Late, VeryEarly, VeryLate, Long, and Short timekeeping exceptions. For example, if the late limit is 0:32, and if the employee punches out 1:00 past the scheduled end of shift, the DurationOfException is 1:00. Type: TimeDuration Output Only Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1019

Chapter 2

Workforce Timekeeper XML API Tag Definitions

ExceptionTypeName

Exception type
The name of the exception. Type: String Output Only You can find values in the Workforce Timekeeper user interface. Sample values: Canceled Deduction, Core Hours Violation, Early Introduced in v4 MinimumNumberOfActiveDays

Minimum number of active days
The configured minimum Meaningful only for MinimumDaysActive and MinimumDaysEmployed exceptions. Type: Integer Output Only Introduced in v4 MissedOutDateTime

Date and time of missed out-punch
The computed missed out time. Meaningful only for a MissedOut exception. Type: DateTime Output Only Introduced in v4 NumberOfWorkedDays

Number of worked days

1020

Kronos Incorporated

TimekeepingException Tag

This value is meaningful only for a WorkHistory exception Type: Integer Output Only Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1021

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Timesheet Tag Timesheet
The Timesheet tag represents a set of timekeeping items for an employee and a given period of days. (This is also referred to as a Timecard.) These include punches, edits, and worked durations, and totalization output such as per period summary, per day summaries, and exceptions. Function Access Control Point: API.Timecard Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadDailyTotals" | "LoadPeriodTotals" Parameters→ None Properties→ <Timesheet (TotalsUpToDateFlag = Boolean) (LastTotalizationDateTime = DateTime) (ManagerSignoffDateTime = DateTime) > <Employee> <CurrentUser> | <PersonIdentity> </Employee> (<DailyTotals> <DateTotals>* </DailyTotals>) <Period> <TimeFramePeriod> </Period>

1022

Kronos Incorporated

Timesheet Tag

(<TotaledPayCodeEdits> <HistoricalPayCodeEdit> | <HistoricalPayCodeMove> | <LockedDataCorrection> | <OnCall> | <PayCodeEdit> | <PayCodeMove> | <Punch> </TotaledPayCodeEdits>) (<TotaledWorkedDurations> <WorkedDuration>* </TotaledWorkedDurations>) (<PeriodTotalData> <PeriodTotals> </PeriodTotalData>) (<TotaledSpans> <TotaledSpan>* </TotaledSpans>) (<UntotaledPunches> <Punch>* </UntotaledPunches>) (<UntotaledWorkedDurations> <WorkedDuration>* </UntotaledWorkedDurations>) </Timesheet>

Action Descriptions
Load Returns a timesheet containing everything known about timekeeping events for the specified period and employee. Return Value Type: Timesheet tag Required Properties: Employee, Period Access Control Point Name: View Introduced in v4 LoadDailyTotals Returns a timesheet whose daily totals contain the most recent totalization for the specified period and employee. Return Value Type: Timesheet tag Required Properties: Employee, Period

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1023

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: View Introduced in v4 LoadPeriodTotals Returns a timesheet whose period totals contain totals for the specified period and employee. Return Value Type: Timesheet tag Required Properties: Employee, Period Access Control Point Name: View Introduced in v4

Property Descriptions
DailyTotals

Set of daily totals
A list of DateTotals tags for the number of days in the requested period Type: Zero or more DateTotals tags Output Only Contains the number of days in the requested period. Each item is an instance of DateTotals, and represents a summary total for the specified day. Introduced in v4 Employee

Employee
One employee, as specified in a PersonIdentity or CurrentUser tag, for whom the action is requested. Type: Either CurrentUser or PersonIdentity tag Required Must uniquely identify an existing and active employee Introduced in v4

1024

Kronos Incorporated

Timesheet Tag

LastTotalizationDateTime

Date and time of last totalization
A server timestamp for the most recent totalization Type: DateTime Output Only Introduced in v4 ManagerSignoffDateTime

Date and time of manager signoff
The date and time of the most recent manager signoff. If the employee has not yet been signed off, this property is not returned. Type: DateTime Output Only Introduced in v4 Period

Time period
The time period for the data being retrieved Type: TimeFramePeriod tag Required Introduced in v4 PeriodTotalData

Totals for time period
Totals for the requested period Type: PeriodTotals tag Output Only Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1025

Chapter 2

Workforce Timekeeper XML API Tag Definitions

TotaledPayCodeEdits

Total of pay code edits
One or more pay code edits credited for the requested period. These are specified in the PayCodeEdit, PayCodeMove, HistoricalPayCodeEdit, HistoricalPayCodeMove. LockedDataCorrection, and OnCall tags. Note: The Employee property is omitted from these tags. Type: Either HistoricalPayCodeEdit, HistoricalPayCodeMove, LockedDataCorrection, OnCall, PayCodeEdit, PayCodeMove or Punch tag Output Only Introduced in v4 TotaledSpans

Totals for time spans
A list of TotaledSpan tags credited towards the requested period. Each TotaledSpan must contain one or two Punch tags defining the span, along with any TimekeepingException tags relevant to the span. Note: No Employee tag is returned in the Punch tags, because all of the punches in a timesheet apply to the employee associated with the Timesheet tag. Each Punch includes a list of Comment tags, if the punch is associated with one or more Timekeeping Comments. Type: Zero or more TotaledSpan tags Output Only Introduced in v4 TotaledWorkedDurations

Total of worked durations
A list of WorkedDuration tags credited towards the requested period, each of which can include a list of Comment tags and a list of TimekeepingException tags.

1026

Kronos Incorporated

Timesheet Tag

Note: No Employee tag is returned in the WorkedDuration tags, because all of the worked durations in a given timesheet apply to the employee associated with the timesheet. Type: Zero or more WorkedDuration tags Output Only Introduced in v4 TotalsUpToDateFlag

Are totals up to date?
Indicates whether totals are up to date. This value is True only if no punches or edits have been made since the last totalization. Type: Boolean Output Only Enumerated value: True, False Introduced in v4 UntotaledPunches

Untotaled punches
A list of Punch tags that have not been totalized Type: Zero or more Punch tags Output Only Introduced in v4 UntotaledWorkedDurations

Untotaled worked durations
A list of WorkedDuration tags that have not been totalized Type: Zero or more WorkedDuration tags Output Only Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1027

Chapter 2

Workforce Timekeeper XML API Tag Definitions

To Tag The Kmail recipient
The person to send the kmail to. This tag appears as a child of the Recipients property of the EmployeeMessage tag. validation done in the bean Function Access Control Point: API.Messaging Introduced in v5.2; last changed in v5.2

Syntax
Properties→ <To Address = String [PersonNumber = String] [PersonKey = String] > </To>

Property Descriptions
Address

Kmail address
Email address Type: String Required validation done in the bean Introduced in v5.2 PersonKey

Person key
Person key Type: String

1028

Kronos Incorporated

To Tag

Optional validation done in the bean Introduced in v5.2 PersonNumber

Person ID
person id Type: String Optional validation done in the bean Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1029

Chapter 2

Workforce Timekeeper XML API Tag Definitions

TopicParameterDefinition Tag Sorting and Matching Rule Topic Parameter Definition
Gives access to sorting or matching rule's topic's parameter definitions used in Priority Scheduling Engine. It is a gold data. Function Access Control Point: API.Priority Scheduling Engine Introduced in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Retrieve" | "RetrieveAll" | "RetrieveAllNames" Parameters→ None Properties→ <TopicParameterDefinition TopicParameterName = String > </TopicParameterDefinition>

Action Descriptions
Retrieve Retrieves the sorting or mathcing rule's topic parameter definition object by name. Return Value Type: TopicParameterDefinition tag Required Properties: TopicParameterName

1030

Kronos Incorporated

TopicParameterDefinition Tag

Access Control Point Name: View Introduced in v6.0 RetrieveAll Retrieves all sorting or matching rule's topic parameter definition objects. Return Value Type: Zero or more TopicParameterDefinition tags Access Control Point Name: View Introduced in v6.0 RetrieveAllNames Retrieves all sorting or matching rule's topic parameter definition objects names. Return Value Type: String list Access Control Point Name: View Introduced in v6.0

Property Descriptions
TopicParameterName

Topic Parameter Definition Name
Represents the sorting and matching rule's topic parameter defintion name. Type: String Required Key Sample values: PRIMARY_JOB Introduced in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1031

Chapter 2

Workforce Timekeeper XML API Tag Definitions

TopicParameterValue Tag Sorting and Matching Rule Topic Parameter Value
Gives access to sorting or matching rule's topic parameter values used in Priority Scheduling Engine. Function Access Control Point: API.Priority Scheduling Engine Introduced in v6.0

Syntax
Properties→ <TopicParameterValue TopicParameterName = String Value = String > </TopicParameterValue>

Property Descriptions
TopicParameterName

Topic parameter name
Represents the name of a sorting or matching rule topic parameter. Type: String Required Key Introduced in v6.0 Value

Topic parameter value
Represents the value of a sorting or matching rule topic parameter. Type: String Required Introduced in v6.0

1032

Kronos Incorporated

Total Tag

Total Tag Total
The Total tag describes a total for a PayCode and LaborAccount pair. Used by: EmployeeSummary, TotalSummary Function Access Control Point: API.Timecard Introduced in v4; last changed in v5.0

Syntax
Properties→ <Total (AmountInCurrency = Currency) (AmountInTime = TimeDuration) (LaborAccountDescription = String) (OrgJobDescription = String) (IsCurrencyFlag = Boolean) (LaborAccountName = String) (LaborAccountId = Long) (OrgJobName = String) (OrgJobId = Long) (PayCodeName = String) (PayCodeId = Long) > </Total>

Property Descriptions
AmountInCurrency

Amount of pay code, in currency
A pay code amount, expressed as a currency Type: Currency Output Only Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1033

Chapter 2

Workforce Timekeeper XML API Tag Definitions

AmountInTime

Amount of pay code, in time
Amount of pay code amount, expressed as a time duration Type: TimeDuration Output Only Introduced in v4 IsCurrencyFlag

Is the pay code in currency?
True if the pay code represents a monetary item. False if it represents an hourly pay code. Type: Boolean Output Only Enumerated value: True, False Introduced in v4; last changed in v5.0 LaborAccountDescription

Description of labor account
The description associated with the labor account Type: String Output Only Introduced in v4 LaborAccountId

Labor account ID
A unique identifier for the labor account to which this amount is applied. This is intended for use by support personnel only. It is recommended that you use the labor account name instead. Type: Long

1034

Kronos Incorporated

Total Tag

Output Only Introduced in v4 LaborAccountName

Labor account
Name of the labor account to which this amount is applied Type: String Output Only Maximum length: 356 characters Each component in the name corresponds to the name and sort order position of an existing labor level entry. The name must contain only legal naming characters. Introduced in v4 OrgJobDescription

Description of organizational job
The description of the job in the organization. Type: String Output only Introduced in v5.0 OrgJobId

Organizational job ID
A unique identifier for a job in the organization Type: Long Output only Introduced in v5.0 OrgJobName

Organizational job
The full path of the job in the organization

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1035

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: String Output only Maximum length: 1000 characters Introduced in v5.0 PayCodeId

Pay code ID
The unique identifier of the pay code to which this amount is applied. Intended for use by support personnel only. It is recommended that you use the PayCodeName property instead. Type: Long Output Only Introduced in v4 PayCodeName

Pay code
The pay code to which this amount is applied Type: String Output Only Introduced in v4

1036

Kronos Incorporated

TotaledScheduledPayCodeEdit Tag

TotaledScheduledPayCodeEdit Tag Editable Scheduled Pay Code Edit that is Totaled
The TotaledScheduledPayCodeEdit tag is generated by the Callable Totalizer. It is based on the Scheduled PayCodeEdit tag, and can be edited with the Timecard Editor. For example, you can edit the Timecard Editor to add comments. Function Access Control Point: API.Timecard Introduced in v4; last changed in v5.0

Syntax
Properties→ <TotaledScheduledPayCodeEdit (AmountInTimeOrCurrency = String) (EnteredOnDate = Date) (Date = Date) (IsCurrencyFlag = Boolean) (LaborAccountName = String) (PayCodeName = String) (EnteredOnTime = Time) > (<Comments> <Comment>* </Comments>) </TotaledScheduledPayCodeEdit>

Property Descriptions
AmountInTimeOrCurrency

Amount of pay code, in time or currency
Amount of pay code, expressed as a time duration or a currency. Type: String Output Only Maximum length: 30 characters Must be consistent with the given pay code

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1037

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v4 Comments

Comments
A list of comments currently returned with this timekeeping item Type: Zero or more Comment tags Output Only Introduced in v4 Date

Date to which the edit applies
The date on which the edit is credited Type: Date Output Only Sample values: 8:00 Vacation on 4/2/2001 Introduced in v4 EnteredOnDate

Date of the edit
The server date on which the edit is added to the database Type: Date Output Only Introduced in v4 EnteredOnTime

Time of the edit
The server time at which the edit is added to the database Type: Time

1038

Kronos Incorporated

TotaledScheduledPayCodeEdit Tag

Output Only Introduced in v4 IsCurrencyFlag

Is the pay code in currency?
True if the pay code represents a monetary item. False if it represents an hourly pay code. Type: Boolean Output Only Enumerated value: True, False Introduced in v4 LaborAccountName

Labor account
This is the name of the labor account of the employee whose pay code amount or totaled amount is being edited. Type: String Output Only Maximum length: 356 characters Default value: Primary account for the employee Introduced in v4; last changed in v5.0 PayCodeName

Pay code
The pay code to be credited with the amount Type: String Output Only Must be associated with an hourly or monetary pay code edit Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1039

Chapter 2

Workforce Timekeeper XML API Tag Definitions

TotaledScheduledPayCodeEditUneditable Tag Uneditable Scheduled Pay Code Edit that is Totaled
The TotaledScheduledPayCodeEditUneditable tag is generated by the Callable Totalizer. "Uneditable" means that this pay code edit cannot be edited in a timesheet. For example, you cannot use the timecard editor to add comments. Function Access Control Point: API.Timecard Introduced in v4; last changed in v5.0

Syntax
Properties→ <TotaledScheduledPayCodeEditUneditable (AmountInTimeOrCurrency = String) [CommentText = String] (EnteredOnDate = Date) (Date = Date) (IsCurrencyFlag = Boolean) (LaborAccountName = String) (PayCodeName = String) (EnteredOnTime = Time) > (<Comments> <Comment>* </Comments>) </TotaledScheduledPayCodeEditUneditable>

Property Descriptions
AmountInTimeOrCurrency

Amount of pay code, in time or currency
Amount of pay code, expressed as a time duration or a currency Type: String Output Only Maximum length: 30 characters

1040

Kronos Incorporated

TotaledScheduledPayCodeEditUneditable Tag

An amount expressed as a TimeDuration or Currency depending on the pay code. Must be consistent with the given pay code. Introduced in v4 Comments

Comments
A list of comments currently returned with this timekeeping item Type: Zero or more Comment tags Output Only Introduced in v4 CommentText

Comment text
A comment Type: String Optional Maximum length: 254 characters Must match exactly an applicable comment that already exists in the database. The string matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application. Introduced in v4 Date

Date to which the edit applies
The date on which the edit is credited Type: Date Output Only Sample values: 8:00 Vacation on 4/2/2001

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1041

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v4 EnteredOnDate

Date of the edit
The server date on which the edit is added to the database Type: Date Output Only Introduced in v4 EnteredOnTime

Time of the edit
The server time at which the edit is added to the database Type: Time Output Only Introduced in v4 IsCurrencyFlag

Is the pay code in currency?
False indicates that the pay code represents a monetary item Type: Boolean Output Only Enumerated value: True, False Introduced in v4 LaborAccountName

Labor account
This is the name of the labor account of the employee whose pay code amount or totaled amount is being loaded. A seven-level labor account will appear using the following format: 101/202/303/404/504/603/702. Type: String

1042

Kronos Incorporated

TotaledScheduledPayCodeEditUneditable Tag

Output Only Maximum length: 356 characters Default value: Primary account for the employee Introduced in v4; last changed in v5.0 PayCodeName

Pay code
The pay code to be credited with the amount Type: String Output Only Must be associated with an hourly or monetary pay code edit Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1043

Chapter 2

Workforce Timekeeper XML API Tag Definitions

TotaledScheduledWorkedDuration Tag Amount of Scheduled Work in Shift
The TotaledScheduledWorkedDuration tag represents the amount of worked time that is scheduled for the employee in a single shift of the employee's schedule. This tag is generated by the Callable Totalizer only if the employee is configured as an hourly employee; that is, the Timecard Editor shows the amount of time worked by the employee, rather than punches. This timesheet item is not generated for a non-hourly employee. Function Access Control Point: API.Timecard Introduced in v4

Syntax
Properties→ <TotaledScheduledWorkedDuration (AmountInTime = TimeDuration) (Date = Date) (LaborAccountName = String) (ScheduledLaborAccountName = String) (WorkRuleName = String) > (<Employee> <CurrentUser> | <PersonIdentity> </Employee>) (<Exceptions> <TimekeepingException>* </Exceptions>) </TotaledScheduledWorkedDuration>

Property Descriptions
AmountInTime

Amount of pay code, in time
Amount of pay code amount, expressed as a time duration Type: TimeDuration

1044

Kronos Incorporated

TotaledScheduledWorkedDuration Tag

Output Only Introduced in v4 Date

Date for the scheduled work
The date to be credited with this worked duration Type: Date Output Only Introduced in v4 Employee

Employee
One employee, as specified in a PersonIdentity or CurrentUser tag, to be credited with the time. Type: Either CurrentUser or PersonIdentity tag Output Only Must uniquely identify an existing and active employee Introduced in v4 Exceptions

Timekeeping exceptions
A list of timekeeping exceptions. Dependency: Returned only when the WorkedDuration tag is returned as part of a Timesheet tag, and only if the most recent totalization detects one or more timekeeping exceptions for this WorkedDuration. Type: Zero or more TimekeepingException tags Output Only Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1045

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LaborAccountName

Labor account
The labor account associated with this worked duration. The duration is a transfer to this labor account. Type: String Output Only Maximum length:356 characters Introduced in v4 ScheduledLaborAccountName

Scheduled labor account
The portion of the labor account that is automatically derived from any corresponding scheduled shift Type: String Output Only Introduced in v4 WorkRuleName

Work rule
A work rule associated with this worked duration. The duration is a transfer to this work rule. Type: String Output Only Maximum length: 50 characters Introduced in v4

1046

Kronos Incorporated

TotaledSpan Tag

TotaledSpan Tag Total for Time Span
The TotaledSpan tag is returned as a record of a Timesheet object. All TotaledSpans in a Timesheet apply to the same employee. Used by: Timesheet Function Access Control Point: API.Timecard Introduced in v4

Syntax
Properties→ <TotaledSpan (LaborAccountName = String) > (<Exceptions> <TimekeepingException>* </Exceptions>) (<OutPunch> <Punch> </OutPunch>) (<InPunch> <Punch> </InPunch>) </TotaledSpan>

Property Descriptions
Exceptions

Exceptions associated with the totaled span
A list of all timekeeping exceptions associated, through totalization, with this TotaledSpan. If no exceptions are associated with this totaled span, the property will not be returned. Type: Zero or more TimekeepingException tags Output Only

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1047

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Introduced in v4 InPunch

Punch associated with start of the span
The Punch object associated with the start of this span. When returned within a TotaledSpan, the Punch object does not contain an Employee tag. Type: Punch tag Output Only Introduced in v4 LaborAccountName

Labor account
The name of the labor account for which the span is charged Type: String Output Only Maximum length:356 characters Introduced in v4 OutPunch

Punch associated with end of the span
The Punch tag associated with the end of this span. When returned within a TotaledSpan, the Punch tag does not contain an Employee tag. Type: Punch tag Output Only Introduced in v4

1048

Kronos Incorporated

TotalSummary Tag

TotalSummary Tag Summary of Totals
The TotalSummary tag contains a set of Total tags, each of which records an amount of time and/or currency to be credited to a labor account and pay code. Used by: DateTotals, PeriodTotals Function Access Control Point: API.Timecard Introduced in v4

Syntax
Properties→ <TotalSummary (<Totals> <Total>* </Totals>) </TotalSummary>

Property Descriptions
Totals

Set of Totals
A list of totals, each of which reports an amount of time or currency for a unique combination of labor account and pay code Type: Zero or more Total tags Output only Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1049

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Transaction Tag Transaction
The Transaction tag provides a means to specify atomic actions across multiple Request tags. The Transaction tag can contain only a sequence number and one or more Request tags. A Response with a Status of Failure generated from any Request tag in the transaction causes all requests to roll back. After a failure, processing continues with the next Transaction or Request tag. Function Access Control Point: API.XML Introduced in v4

Syntax
Properties→ <Transaction [TransactionSequence = String] > </Transaction>

Property Descriptions
TransactionSequence

Transaction sequence
A number supplied by the client application that is returned in each Response tag for the Transaction Type: String Optional Introduced in v4

1050

Kronos Incorporated

TransferEmployee Tag

TransferEmployee Tag Transfer Employee
This tag is used to transfer a segment of an employee's shift to a different labour account or work rule. Function Access Control Point: API.Schedule Introduced in v5.1; last changed in v6.0

Syntax
Properties→ <TransferEmployee EffectiveDate = Date [LaborAccountName = String] [OrgJobPath = String] TransferStartTime = Time [WorkRuleName = String] > [<Comments> <Comment> </Comments>] </TransferEmployee>

Property Descriptions
Comments

Comments
Comments Type: Comment tag Optional Introduced in v5.1 EffectiveDate

Effective date

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1051

Chapter 2

Workforce Timekeeper XML API Tag Definitions

EffectiveDate Type: Date Required Introduced in v5.1 LaborAccountName

Labor account name
LaborAccountName Type: String Optional Introduced in v5.1 OrgJobPath

Organization job path
OrgJobPath Type: String Optional Introduced in v5.1 TransferStartTime

Transfer start time
TransferStartTime Type: Time Required Introduced in v5.1 WorkRuleName

Work rule
WorkRuleName

1052

Kronos Incorporated

TransferEmployee Tag

Type: String Optional Introduced in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1053

Chapter 2

Workforce Timekeeper XML API Tag Definitions

TransferJobSeniorityDate Tag Seniority Date
The TransferJobSeniorityDate tag assigns a seniority date for an employee and an organizational job, based on the employee's job transfer set, as of an effective date. Function Access Control Point: API.Schedule Introduced in v5.0; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllJobSeniorityDates" | "Update" Parameters→ None Properties→ <TransferJobSeniorityDate EffectiveDate = Date [LocationOrgNodePath = String] PersonNumber = String [SeniorityDate = Date] > </TransferJobSeniorityDate>

Action Descriptions
Load Retrieves employee seniority information as of an effective date. Return Value Type: Collection

1054

Kronos Incorporated

TransferJobSeniorityDate Tag

Required Properties: PersonNumber, LocationOrgNodePath, EffectiveDate Access Control Point Name: View Introduced in v5.0; last changed in v5.0 LoadAllJobSeniorityDates Retrieves employee's all transfer job sets seniority dates as of an effective date. Return Value Type: Zero or more TransferJobSeniorityDate tags Required Properties: PersonNumber, EffectiveDate Access Control Point Name: View Introduced in v5.1 Update Updates employee seniority information. The LocationOrgNodePath must represent an organizational node. Return Value Type: None Required Properties: PersonNumber, LocationOrgNodePath, EffectiveDate, SeniorityDate Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0

Property Descriptions
EffectiveDate

Effective date
The date when the job transfer set was assigned to the employee Type: Date Required Job Transfer Set with OrgJobs must be defined and exist on the given effective date. Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1055

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LocationOrgNodePath

Full path for node location
The full path for the organizational node location Type: String Optional Maximum length: 1000 Introduced in v5.0; last changed in v5.1 PersonNumber

Person number
Person number of the specified person Type: String Required Key Maximum length: 15 characters A job transfer set with OrgJobs should be defined and exist on the given effective date. The specified person must have a Workforce Scheduler license. Introduced in v5.0; last changed in v5.0 SeniorityDate

Seniority date
The seniority date of a timekeeping employee. This is a factor for a schedule job list, in which each job has a seniority date associated with it. Type: Date Optional Introduced in v5.0; last changed in v5.0

1056

Kronos Incorporated

TreeNodeType Tag

TreeNodeType Tag Organizational Tree Node Type
TheTreeNodeType tag lets you add, delete, or modify a location type for use when adding new locations to an organizational tree. Function Access Control Point: API.Hierarchies Introduced in v6.0; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "addOnly" | "checkForRefrences" | "delete" | "retrieveAllForUpdate" | "retrieveAllNames" | "retrieveForUpdate" | "update" Parameters→ None Properties→ <TreeNodeType [Description = String] Name = String [NewName = String] [TreeTypeName = String] > [<GlsegmentDetail> <GlsegmentDetail> </GlsegmentDetail>] </TreeNodeType>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1057

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Action Descriptions
addOnly Add new tree node type into organizational map Return Value Type: None Required Properties: Name Optional Properties: Description, TreeTypeName, GlsegmentDetail Access Control Point Name: Edit Introduced in v6.0 checkForRefrences Check this tree node type is referenced by any tree node Return Value Type: Boolean Required Properties: Name Optional Properties: TreeTypeName Access Control Point Name: View Introduced in v6.0 delete delete the tree node type from the system if it is not referenced. If there are multiple tree node type mapping to the same labor level definition, and the to be deleted tree node type is in not in the last position of node type list, it can't be delted. Return Value Type: None Required Properties: name Access Control Point Name: Edit Introduced in v6.0 retrieveAllForUpdate Return all tree node type which can be updated Return Value Type: Zero or more TreeNodeType tags Optional Properties: TreeTypeName

1058

Kronos Incorporated

TreeNodeType Tag

Access Control Point Name: View Introduced in v6.0 retrieveAllNames Return all Names Return Value Type: String Optional Properties: TreeTypeName Access Control Point Name: View Introduced in v6.0; last changed in v6.0 retrieveForUpdate Retrun tree node type bean if this tree node type is not referenced by any tree node Return Value Type: TreeNodeType tag Required Properties: Name Optional Properties: TreeTypeName Access Control Point Name: View Introduced in v6.0; last changed in v6.0 update update tree node type Return Value Type: None Required Properties: Name Optional Properties: Description, TreeTypeName, GlsegmentDetail, newName Access Control Point Name: Edit Introduced in v6.0

Property Descriptions
Description

Description of Node type
Specify an optional description of the tree location type.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1059

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: String Optional Maximum length: 250 characters Sample values: description Introduced in v6.0; last changed in v6.0 GlsegmentDetail

Glsegment Detail
Specify the labor level segment information when two or more location types map to the same labor level. Type: GlsegmentDetail tag Optional Introduced in v6.0 Name

Node Type Name
Specify the name of the tree location type. Type: String Required The name must be unique and conform to name property standards. Maximum length: 30 characters Sample values: Division Introduced in v6.0; last changed in v6.0 NewName

Node Type New Name

1060

Kronos Incorporated

TreeNodeType Tag

Specify the new name of the changed location type. Type: String Optional The name must be unique and conform to name property standards. Maximum length: 30 characters Introduced in v6.0; last changed in v6.0 TreeTypeName

Organization map name
Specify an optional name of the organizational tree. Type: String Optional Sample values: Organizational Map Introduced in v6.0; last changed in v6.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1061

Chapter 2

Workforce Timekeeper XML API Tag Definitions

TypeOverride Tag Override for Punch
The TypeOverride tag identifies the override that can be associated with a punch. Function Access Control Point: API.Timecard Introduced in v4

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" Parameters→ None Properties→ <TypeOverride (OverrideRuleName = String) > </TypeOverride>

Action Descriptions
Load Returns information for each punch type override defined in the system. Return Value Type: Zero or more TypeOverride tags Access Control Point Name: View Introduced in v4

Property Descriptions

1062

Kronos Incorporated

TypeOverride Tag

OverrideRuleName

Override type name
The name of an override type that can be associated with a punch Type: String Output Only Sample values: New Shift, In Punch, Out Punch Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1063

Chapter 2

Workforce Timekeeper XML API Tag Definitions

User Tag User
The User tag contains user account and related information. Used by: Personality See the validation rules for the PersonIdentity, PasswordHistory, UserAccount, and UserAccountLockout tags. Function Access Control Point: API.Person Introduced in v4; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadUserAccount" Parameters→ None Properties→ <User <Identity> <CurrentUser> | <PersonIdentity> </Identity> (<PasswordHistories> <PasswordHistory>* </PasswordHistories>) [<UserAccountData> <UserAccount> </UserAccountData>] (<UserAccountLockouts> <UserAccountLockout>* </UserAccountLockouts>)

1064

Kronos Incorporated

User Tag

</User>

Action Descriptions
Load Returns the user account, password history, and lockout information for the specified person. Return Value Type: User tag Required Properties: Identity Access Control Point Name: View Introduced in v4 LoadUserAccount Returns user account information for the specified person. Return Value Type: UserAccount tag Required Properties: Identity Access Control Point Name: View Introduced in v4

Property Descriptions
Identity

Identity
One employee, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Required Key Must uniquely identify an existing and active employee Introduced in v4 PasswordHistories

Password histories

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1065

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Encrypted passwords for the specified dates and times Type: Zero or more PasswordHistory tags Output Only Introduced in v4 UserAccountData

User account data
The user's logon, name, and password information Type: UserAccount tag Optional Required: When inserting a new user Introduced in v4 UserAccountLockouts

User account lockouts
The user's lockouts for the specified dates, times, and reasons Type: Zero or more UserAccountLockout tags Output Only Introduced in v4

1066

Kronos Incorporated

UserAccount Tag

UserAccount Tag User Account
The UserAccount tag returns logon information for the specified person; including the user's username and password. Used by: HyperFindResult, User Function Access Control Point: API.Person Introduced in v4; last changed in v5.1

Syntax
Properties→ <UserAccount [RecordManagerLockoutFlag = Boolean] [PasswordUpdateFlag = Boolean] (PasswordUpdatedDateTime = DateTime) (LockoutResetDateTime = DateTime) [LogonProfileName = String] (ConsecutiveBadLogons = Long) [UserName = String] [UserPassword = Password] > </UserAccount>

Property Descriptions
ConsecutiveBadLogons

Number of consecutive bad logons
Number of consecutive bad logon attempts the user is permitted before being locked out of the system. Type: Long Output Only Introduced in v4; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1067

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LockoutResetDateTime

Date and time when user lockout ends
The date and time after which a user who is currently locked out may log on to the system. Type: DateTime Output Only Introduced in v4; last changed in v5.1 LogonProfileName

Name of logon profile for the user
The Logon Profile column contains the name of the user's logon profile. The logon profile provides rules for password behavior or provides rules for automatic logout and lockout behavior. The following predefined data values are provided: • • • • • • • • • • • Type: String Optional Maximum length: 50 characters Default Background Processor DCM Super Access Event Manager HR- Payroll MobileTime RecordManager- IS Super Access TeleTime Logon XML

1068

Kronos Incorporated

UserAccount Tag

Default value: &DEFAULT_LOGON Introduced in v4; last changed in v5.0 PasswordUpdatedDateTime

Date and time of last password update
Date and time that the password was last updated Type: DateTime Output Only Introduced in v4 PasswordUpdateFlag

Change password?
Indicates whether the user must change the password the next time he or she logs on. The value can be: • • False if no password change is required True if a password change is required

Type: Boolean Optional Enumerated value: True, False Introduced in v4 RecordManagerLockoutFlag

Access to archive databases
Boolean value that, when true (the default), indicates that the user account will not have access to the target system after the Record Management system has copied data to it. If false, the user account will be able to access the target database. Type: Boolean Optional

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1069

Chapter 2

Workforce Timekeeper XML API Tag Definitions

This property can only be used if you have the Record Management system installed. Default value: True Enumerated value: True, False Introduced in v5.0 UserName

User name
This is the user name that allows the user to access the timekeeper system. A unique logon name is required. If your system uses authorization that is external to timekeeping, such as the Windows NT or Lightweight Directory Access Protocol (LDAP), the UserName must match the logon name for the authorization protocol. Type: String Optional Maximum length: 70 characters Must be unique for the user for all user accounts, regardless of whether they are active, inactive, or terminated. Required: When adding a new user. Introduced in v4 UserPassword

User password
The user's password must be specified if UserName is specified. Type: Password Optional Maximum length: 30 characters Do not use an encrypted value for input. However, for output, the value is encrypted. Required: When adding a new user

1070

Kronos Incorporated

UserAccount Tag

Do not specify: For an existing user Introduced in v4; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1071

Chapter 2

Workforce Timekeeper XML API Tag Definitions

UserAccountLockout Tag User Account Lockout
The UserAccountLockout tag returns the date and reason for a user being locked out of the system. Function Access Control Point: API.Person Introduced in v4; last changed in v5.1

Syntax
Properties→ <UserAccountLockout (EffectiveDateTime = DateTime) (LockoutReasonName = String) > </UserAccountLockout>

Property Descriptions
EffectiveDateTime

Date and time when the lockout starts
The date and time when the lockout becomes effective Type: DateTime Output Only Introduced in v4 LockoutReasonName

Reason for lockout
Name of the lockout reason The following predefined data values are provided: • • 1 for Inactivity Lockout 2 for Password Lockout

1072

Kronos Incorporated

UserAccountLockout Tag

3 for Maintenance Lockout

Type: String Output Only Enumerated value: 1, 2, 3 2Password Lockout 3Maintenance Lockout Introduced in v4; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1073

Chapter 2

Workforce Timekeeper XML API Tag Definitions

UserAccountStatus Tag User Account Status
The UserAccountStatus tag sets a user's account status to be active or inactive. Used by: PersonInformation Function Access Control Point: API.Person Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "LoadUserAccountStatuses" Parameters→ None Properties→ <UserAccountStatus UserAccountStatusName = String [EffectiveDate = Date] [ExpirationDate = Date] > <Identity> <CurrentUser> | <PersonIdentity> </Identity> [<Period> <TimeFramePeriod> </Period>] </UserAccountStatus>

Action Descriptions

1074

Kronos Incorporated

UserAccountStatus Tag

LoadUserAccountStatuses Returns information associated with the user account status for the specified person over the period specified. If the period is not specified, the current date through January 1, 3000 is used. The Identity and Period information associated with the request will be added to the first tag in the resulting list. An empty tag (with just the Identity and Period properties) will be returned when no data for the person or period is found. The person must exist within the system and the user must have access to that person. Return Value Type: Zero or more UserAccountStatus tags Required Properties: Identity Optional Properties: Period Access Control Point Name: View Introduced in v5.0

Property Descriptions
EffectiveDate

Date the user account becomes effective
The date when the user account becomes effective Type: Date Optional Must occur before the expiration date Default value: The current system date Introduced in v4; last changed in v5.0 ExpirationDate

Date when the user account expires
The end date for the status of the user account Type: Date

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1075

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional Must occur after the effective date. Default value: January 1, 3000 Introduced in v4 Identity

Identity
One person, as specified in a PersonIdentity or CurrentUser tag. Type: Either CurrentUser or PersonIdentity tag Optional Key Must uniquely identify a person. Introduced in v5.0 Period

Time period
The period of time associated with the user account statuses. Type: TimeFramePeriod tag Optional The time frame must evaluate to a span of time. The specified identity shall be used when the time frame requires an association with a person. Used for the LoadUserAccountStatuses action. Default value: From the current date until January 1, 3000 Introduced in v5.0 UserAccountStatusName

Account status of the user
The User Status column contains a value indicating the status of the user. Specify one of the following numbers to represent the data value: • 0 if not applicable

1076

Kronos Incorporated

UserAccountStatus Tag

• • •

1if active 2 if inactive 3 if terminated

Type: String Required Maximum length: 1 character Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1077

Chapter 2

Workforce Timekeeper XML API Tag Definitions

VacationBid Tag Vacation Bid
The VacationBid tag specifies the vacation bids requested by an employee whereas the employee bids for a specific vacation time. All Actions are validated. The validate method validates the contents of the vacation bid bean. Function Access Control Point: API.VacationBid Introduced in v5.0a; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Approve" | "Load" | "LoadByBidGroupItem" | "Reject" Parameters→ None Properties→ <VacationBid EndDate = DateTime [BidGroupItemId = Long] [Priority = Integer] StartDate = DateTime (Status = String) CreateOpenShift = Boolean HoursPerDay = TimeDuration BidId = Long > [<BidNotes> <BidNote>*

1078

Kronos Incorporated

VacationBid Tag

</BidNotes>] </VacationBid>

Action Descriptions
Approve Approve the vacation bid specified by the vacation bid id and upon approval be able to specify true or false value for creating an open shift or not. For the Approve Action, the BidId property and the CreateOpenShift property MUST be specified. Return Value Type: None Required Properties: BidId, CreateOpenShift Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0a Load Loads the vacation bid given the bid id value. For the Load Action, the BidId property must be specified. Return Value Type: VacationBid tag Required Properties: BidId Access Control Point Name: View Introduced in v5.0; last changed in v5.0a LoadByBidGroupItem Loads the vacation bid(s) given the bid group item id. For the LoadBidGroupItemId, the BidGroupItemId property MUST be specified. Return Value Type: Zero or more VacationBid tags Required Properties: BidGroupItemId Access Control Point Name: View Introduced in v5.0; last changed in v5.0a

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1079

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Reject Rejects the vacation bid specified by the vacation bid id. For the Reject Action, the BidId property MUST be specified. Return Value Type: None Required Properties: BidId Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0a

Property Descriptions
BidGroupItemId

Bid Group Item ID
BidGroupItemId identifies a row in the WPMBIDGRPPRSNMM table, which associates a person with a particular bid group. Type: Long Optional The BidGroupItemId MUST be defined for the VacationBid element in the BidGroupItem BidList for adding bids. Sample values: <VacationBid BidGroupItemId="3" Priority="5" StartDate="04/01/2004 00:00:00" EndDate="05/01/2004 11:48:56" HoursPerDay="288000" CreateOpenShift="false"> </VacationBid> Introduced in v5.1; last changed in v5.1 BidId

Vacation Bid ID
BidId uniquely identifies a row in the WMPVACATIONBID table, which contains information about vacation bids.

1080

Kronos Incorporated

VacationBid Tag

Type: Long Required Key If defined for an Action, the BidId property cannot be null. The BidId property MUST NOT be specified for the BidGroupItem AddBids Action. The BidId property MUST be defined for the ApplyBidNotes, DeleteBidNotes, BidGroupItem RemoveBids Actions. Introduced in v5.1; last changed in v5.1 BidNotes

Bid Notes
List of Bid Notes to add a specific bid. Type: Zero or more BidNote tags Optional If defined for an Action, the BidNotes property cannot be null. The contents of the BidNotes list cannot be null. The BidNotes property MUST contain one or more BidNote elements. The BidNotes property MUST be specified for the ApplyBidBNotes Action. Sample values: <VacationBid Id="501"> <BidNotes> <BidNote Sequence="1" Text="For vacation bid with Id=501"> </BidNote> </BidNotes> </VacationBid> Introduced in v5.1; last changed in v5.1 CreateOpenShift

Create Open Shift
Determines whether to create an open shift when this vacation bid is approved. Type: Boolean Required

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1081

Chapter 2

Workforce Timekeeper XML API Tag Definitions

If defined for an Action, the CreateOpenShift property cannot be null. The CreateOpenShift property MUST be defined for the VacationBid element within the BidGroupItem BidList when adding bids. Sample values: "true" or "false" Default value: "false" Introduced in v5.0; last changed in v5.1 EndDate

Bid End Date
Vacation Bidding End Date. Type: DateTime Required If defined for an Action, the EndDate property cannot be null. The EndDate property MUST be defined for the VacationBid element in the BidGroupItem BidList when you adding bids. Sample values: "05/01/2004 11:48:56" Introduced in v5.0; last changed in v5.1 HoursPerDay

Hours Per Day
Hours Per Day towards this vacation bid. Type: TimeDuration Required If defined for an Action, the HoursPerDay property cannot be null. The HoursPerDay property MUST be defined for the VacationBid element within the BidGroupItem BidList when adding bids. Sample values:

1082

Kronos Incorporated

VacationBid Tag

"288000" Introduced in v5.0; last changed in v5.1 Priority

Bid Priority
Specifies the priority of a bid, also know as the bid rank. Type: Integer Optional Priority cannot be less than 1. Required when adding vacation bids Sample values: <VacationBid BidGroupItemId="3" Priority="1" StartDate="04/01/2004 00:00:00" EndDate="05/01/2004 11:48:56" HoursPerDay="288000" CreateOpenShift="false"> </VacationBid> Introduced in v5.1; last changed in v5.1 StartDate

Bid Start Date
Vacation bid start date. Type: DateTime Required If the StartDate property is defined for an Action, StartDate cannot be null. The StartDate property MUST be defined for the VacationBid element within the BidGroupItem BidList when adding bids. Sample values: "04/01/2004 00:00:00" Introduced in v5.0; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1083

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Status

Bid Status
The status of the bid, which may be 1 of 3 states: Submitted, Approved, Rejected. Type: String Output only The BidStatus property cannot be defined for any BidGroupItem, Bid, or Vacation Bid Action. Sample values: Submitted - 0, Approved - 1, Rejected - 2 Enumerated value: Submitted - 0, Approved - 1, Rejected - 2 Introduced in v5.1; last changed in v5.1

1084

Kronos Incorporated

VolumeDataItem Tag

VolumeDataItem Tag Volume data for a location and date
This tag is used to hold information about the volume data for a specific location and a specific date. Function Access Control Point: Schedule Planner Introduced in v6.0

Syntax None

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1085

Chapter 2

Workforce Timekeeper XML API Tag Definitions

WageProfile Tag Wage Profile
The WageProfile tag returns a list of available wage profiles. The wage profile enables you to assign multiple wage rates to the same employee to comply with union regulations or company policy. For example, if people perform different jobs, they might earn a different wage rate for each job. The WageProfile and WSAWageProfile tags refer to the same database object. Function Access Control Point: API.Employee Introduced in v4; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllWageProfiles" | "LoadById" Parameters→ None Properties→ <WageProfile [WageProfileId = Integer] [WageProfileName = String] > </WageProfile>

Action Descriptions
Load Returns a wage profile, based on WageProfileName.

1086

Kronos Incorporated

WageProfile Tag

Name should be valid Return Value Type: WageProfile tag Required Properties: WageProfileName Access Control Point Name: View Introduced in v4 LoadAllWageProfiles Returns a list of all wage profiles in the system. Return Value Type: Zero or more WageProfile tags Required Properties: None Access Control Point Name: View Introduced in v4 LoadById Returns a wage profile, based on WageProfileID. ID must be valid Return Value Type: WageProfile tag Required Properties: WageProfileID Access Control Point Name: View Introduced in v4

Property Descriptions
WageProfileId

Id of wage profile
Uniquely identifies the wage profile in the database Type: Integer Optional Introduced in v4

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1087

Chapter 2

Workforce Timekeeper XML API Tag Definitions

WageProfileName

Wage profile name
The name of the person's wage profile Type: String Optional Maximum length: 50 characters Introduced in v4

1088

Kronos Incorporated

WeekDay Tag

WeekDay Tag Week Day
The WeekDay tag provides information about a week day as defined in the system. Function Access Control Point: API.Common Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAll" Parameters→ None Properties→ <WeekDay Description = String Name = String > </WeekDay>

Action Descriptions
Load Returns information for the specified weekday. Specify exactly one of Name or Description. Return Value Type: WeekDay tag Required Properties: Name, Description

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1089

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: View Introduced in v5.0 LoadAll Returns all weekday information in the system. No properties can be specified. Return Value Type: Zero or more WeekDay tags Access Control Point Name: View Introduced in v5.0

Property Descriptions
Description

Description
The localized description of the week day. This value is used as the display name in the user interface. Type: String Optional Key Introduced in v5.0 Name

Week day name
A day of the week Type: String Optional Key You must use the English name for the day, even if your application server is configured to use a different national language. Enumerated value: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday Introduced in v5.0

1090

Kronos Incorporated

WFCGenie Tag

WFCGenie Tag Retrieve data
This tag is used to retrieve a list of the querieis that return a summary of key information for multiple employees for the specified user, or to retrieve all queries that the specified user is allowed to run. Function Access Control Point: API.Genie Introduced in v5.2; last changed in v5.2

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "LoadAllGenies" | "LoadMetadata" Parameters→ None Properties→ <WFCGenie HyperFindQueryName = String GenieName = String [GenieType = String] > [<GenieColumns> <GenieColumn> </GenieColumns>] <Period> <TimeFramePeriod> </Period> <Identity> <PersonIdentity>* </Identity> [<GenieRows>

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1091

Chapter 2

Workforce Timekeeper XML API Tag Definitions

<GenieRow> </GenieRows>] </WFCGenie>

Action Descriptions
Load Returns the data and metadata for the specified item for the specified HyperFind query and date span Return Value Type: (***undefined***): Genie Required Properties: GenieName Access Control Point Name: View Introduced in v5.2 LoadAllGenies Returns the names of all items for the specified user. Return Value Type: (***undefined***): Genie Required Properties: None Access Control Point Name: View Introduced in v5.2 LoadMetadata Returns only the metadata for the specified item. Return Value Type: (***undefined***): Genie Required Properties: GenieName Access Control Point Name: View Introduced in v5.2

Property Descriptions
GenieColumns

Column data

1092

Kronos Incorporated

WFCGenie Tag

Column metadata returned. Present only in a Load or LoadMetadata response. Type: GenieColumn tag Optional Introduced in v5.2; last changed in v5.2 GenieName

Name
The name of the item to load. Required in a Load or LoadMetadata request; must be omitted in a LoadAllGenies request. Type: String Required The name must match a valid name found in the Display Profiles for the specified user. Introduced in v5.2 GenieRows

Rows
Row data returned. Present only in a Load response. Type: GenieRow tag Optional Introduced in v5.2 GenieType

Type
The type can be Detail, Roll-Up, or Multi-row. Present only in a Load or LoadMetadata response. Type: String Optional Introduced in v5.2

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1093

Chapter 2

Workforce Timekeeper XML API Tag Definitions

HyperFindQueryName

Hyper Find Query Name
The HyperFind query to use in retrieving the data. Required in a Load request; must be omitted in a LoadAllGenies or LoadMetadata request. Type: String Required The names of HyperFind queries can be found in the timekeepingl user interface. Introduced in v5.2 Identity

Person Identity
List of persons to be used, instead of a HyperFind query, in retrieving the data. Required in a Load request; must be omitted in a LoadAllGenies or LoadMetadata request. Type: Zero or more PersonIdentity tags Required Introduced in v5.2; last changed in v5.2 Period

Period
The time frame used to execute the HyperFind query. Required in a Load request; must be omitted in a LoadAllGenies request. Type: TimeFramePeriod tag Required Must evaluate to a span of time. Introduced in v5.2

1094

Kronos Incorporated

WfcJob Tag

WfcJob Tag Job in Organization
Use the WfcJob tag to add, delete, or modify a job that can be attached to locations in an organizational map. Function Access Control Point: API.Hierarchies Introduced in v5.0; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "Delete" | "LoadByName" | "UpdateOnly" Parameters→ None Properties→ <WfcJob [JobTitle = String] [LLEDesc = String] [InActiveSw = Boolean] [JobCode = String] [WfcJobDesc = String] WfcJobName = String [LLEName = String] [WfcJobNewName = String] [SortOrder = Long] > </WfcJob>

Action Descriptions

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1095

Chapter 2

Workforce Timekeeper XML API Tag Definitions

AddOnly Adds a new job to the job hierarchy. Return Value Type: None Required Properties: WfcJobName Optional Properties: WfcJobDesc, JobCode, JobTitle, LLEName, LLEDesc, InActiveSw, SortOrder Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0 Delete Marks an existing job for deletion. Return Value Type: None Required Properties: WfcJobName Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0 LoadByName Returns information for a job with the specified name. Return Value Type: WfcJob tag Required Properties: WfcJobName Access Control Point Name: View Introduced in v5.0; last changed in v5.0 UpdateOnly Updates an existing job. Return Value Type: None Required Properties: WfcJobName Optional Properties: WfcJobDesc, JobCode, JobTitle, LLEName, LLEDesc, InActiveSw, SortOrder, WfcJobNewName Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0

1096

Kronos Incorporated

WfcJob Tag

Property Descriptions
InActiveSw

Is the job inactive?
Indicates whether the job is inactive Type: Boolean Optional Default value: False Enumerated value: True, False Introduced in v5.0; last changed in v5.0 JobCode

Job code
The job code name can be used to identify a job. It is often used when the job has been imported from another system. Type: String Optional Maximum length: 30 characters Introduced in v5.0; last changed in v5.0 JobTitle

Description of job code
This is a description of the job. It is often used when the job has been imported from another system. Type: String Optional Maximum length: 250 characters Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1097

Chapter 2

Workforce Timekeeper XML API Tag Definitions

LLEDesc

Description of labor level entry
The description of the labor level entry for the specified job Type: String Optional Maximum length: 250 characters Introduced in v5.0; last changed in v5.0 LLEName

Labor level entry mapped to job
The name of the labor level entry that is mapped to the specified job. Type: String Optional Maximum length: 30 characters Required: If the job location type matches a labor level Introduced in v5.0; last changed in v5.0 SortOrder

Sort order
The sort order number controls the order in which the job appears in functions such as Schedule Planner or Staff Planner. Type: Long Optional Maximum length: 9 characters Use only integers that are greater than zero. Introduced in v5.0; last changed in v5.0 WfcJobDesc

Job description

1098

Kronos Incorporated

WfcJob Tag

The description for the specified job Type: String Optional Maximum length: 250 characters Introduced in v5.0; last changed in v5.0 WfcJobName

Job name
Job name Type: String Required Maximum length: 30 characters Must conform to the name property standards Introduced in v5.0; last changed in v5.0 WfcJobNewName

New name for job
The new job name for an existing job. Used only for the Update action. Type: String Optional Maximum length: 30 characters The name must be unique. Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1099

Chapter 2

Workforce Timekeeper XML API Tag Definitions

WorkedDuration Tag Amount of Time Worked
Use the WorkedDuration tag to add a time amount, to delete a time amount, or to add a comment to a time amount for an employee. Used by: Timesheet Function Access Control Point: API.Timecard Introduced in v4; last changed in v6.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddComment" | "AddOnly" | "Delete" Parameters→ AddOnly→ [AccrualOverride = Boolean] [allowAdHoc = Boolean] [EchoData = Boolean] Properties→ <WorkedDuration OrgJobName = String OrgJobId = String AmountInTime = TimeDuration [CommentText = String] (EnteredOnDate = Date) Date = Date [LaborAccountName = String] [ScheduledLaborAccountName = String] [NewShiftOverrideFlag = Boolean]

1100

Kronos Incorporated

WorkedDuration Tag

(EnteredOnTime = Time) [WorkRuleName = String] > [<Notes> <Note>* </Notes>] (<Comments> <Comment>* </Comments>) <Employee> <CurrentUser> | <PersonIdentity> </Employee> (<Exceptions> <TimekeepingException>* </Exceptions>) </WorkedDuration>

Action Descriptions
AddComment Adds a comment for the specified worked durations for the specified employee. Depending on the type of worked duration, you may need to specify one of the following properties: • • LaborAccountName WorkRuleName

Return Value Type: None Required Properties: AmountInTime, Date, Employee, CommentText Access Control Point Name: Edit Introduced in v4 AddOnly Adds a new worked duration with the specified amount and date for the specified employee. You can add multiple worked durations with identical amount and date values, for the same employee. Return Value Type: WorkedDuration tag Required Properties: AmountInTime, Date, Employee

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1101

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Access Control Point Name: Edit Introduced in v4
Action Parameters Parameter Name AccrualOverride Description If the action results in an accrual warning, the warning is overridden when AccrualOverride=True. Optional Default value: False Specifies whether an ad hoc labor level is allowed. Optional Default value: False If True, the Response includes a copy of this tag. Optional Default value: False Additional information Introduced in v4

allowAdHoc

Introduced in v5.0; last changed in v5.0; deprecated in v5.0. Not used Introduced in v4

EchoData

Delete Marks for deletion all worked durations for the employee and the work duration. Return Value Type: None Required Properties: AmountInTime, Date, Employee Access Control Point Name: Edit Introduced in v4

Property Descriptions
OrgJobName

Organizational job
The name of the organizational job path of the employee whose pay code amount or totaled amount is being edited.

1102

Kronos Incorporated

WorkedDuration Tag

Enter data for OrgJobName in the same format as it appears in the database. Note: OrgJobName string matching is case-sensitive on a server that connects to an Oracle database. Required: When the pay code edits, historical edit, or totaled amount being deleted or commented contained an explicit OrgJobName value Type: String Maximum length: 1000 characters You must have Functional Access for Job Transfers. A node with this Id must exist in the organizational structure Default value: null Introduced in v5.0 OrgJobId

Organizational job ID
A unique identifier for a job in the organization Type: String Default value: Null Introduced in v5.0 AmountInTime

Amount of time worked, in time
The amount of time to be added or deleted, expressed as a duration. Type: TimeDuration Required Maximum length: 30 characters Introduced in v4; last changed in v5.1 Comments

Comments
The set of comments that are associated with worked durations in the timesheet.

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1103

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Type: Zero or more Comment tags Output Only Introduced in v4 CommentText

Comment text
A text string that is attached to the pay code amount or totaled amount. Type: String Optional Maximum length: 254 characters Must match exactly an applicable comment that already exists in the database. The string matching is case-sensitive. You can find values in the Workforce Timekeeper Setup Application. Introduced in v4 Date

Effective date
The date for which the added or deleted time duration is to be posted. Type: Date Required, Key Introduced in v4; last changed in v5.1 Employee

Employee
One employee, as specified in a PersonIdentity or CurrentUser tag, who is to be credited with the time. Type: Either CurrentUser or PersonIdentity tag Required, Key Must uniquely identify an existing and active employee

1104

Kronos Incorporated

WorkedDuration Tag

Introduced in v4 EnteredOnDate

Date of the entry for worked time
The date on which this duration was added to the database Type: Date Output Only Introduced in v4 EnteredOnTime

Time of the entry for worked time
The time at which this duration was added to the database Type: Time Output Only Introduced in v4 Exceptions

Exceptions
A list of timekeeping exceptions. Dependency: Returned only when the WorkedDuration is returned as part of a the Timesheet tag, and only if the most recent totalization detected a timekeeping exception for this worked duration. Type: Zero or more TimekeepingException tags Output Only Introduced in v4 LaborAccountName

Labor account
The name of the labor account

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1105

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Enter data for labor accounts in the same format as they appear in the timekeeping database. For example, if you have a seven-level labor account, specify a value for each labor level, using the following format: 101/202/303/404/504/603/702 Do not specify labor levels that are not changing. If any of the labor levels are the same as the employee's primary labor account, you can enter @H for those labor levels instead of entering the labor entry names. Type: String Optional Maximum length: 356 characters. Introduced in v4 NewShiftOverrideFlag

Start a new shift?
The override type value, if any, that is being applied when adding a totaled amount. Values are: • • False for no new shift override True for a new shift override

Type: Boolean Optional Enumerated value: True, False Introduced in v4 Notes

Comment Notes
The list of notes for the comment to be created with the comment text Type: Zero or more Note tags Optional Introduced in v6.0

1106

Kronos Incorporated

WorkedDuration Tag

ScheduledLaborAccountName

Scheduled labor account
Denotes a labor account transfer entered by means of the scheduler application. This property can only be specified for a Delete action. Type: String Optional Introduced in v5.0; last changed in v5.0 WorkRuleName

Work rule
The work rule for which the amount is being applied. If left blank, the employee's default work rule is used. The following predefined data values are provided: • • &ALL_WORK_RULES &EMPTY

Type: String Optional Maximum length: 50 characters You can find values in the Timekeeping Application. Introduced in v4; last changed in v5.1

Groups of Mutually Exclusive Properties
OrgJob Organization Job Name or ID: If ID exists, Name is ignored. Optional Group includes: OrgJobName, OrgJobId

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1107

Chapter 2

Workforce Timekeeper XML API Tag Definitions

WorkerType Tag Worker Type
The WorkerType tag identifies an optional attribute, such as full-time or part-time, that you can assign to a person. Use this tag to add, modify, delete, load, or retrieve worker types. Function Access Control Point: API.Common Introduced in v5.0; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "AddOnly" | "Delete" | "Load" | "LoadAll" | "RetrieveAllNames" | "RetrieveForUpdate" | "Update" | "UpdateOnly" Parameters→ None Properties→ <WorkerType Name = String > <WorkerTypeElements> <WorkerTypeElement>* </WorkerTypeElements> </WorkerType>

1108

Kronos Incorporated

WorkerType Tag

Action Descriptions
AddOnly Adds a new worker type to the database. Return Value Type: None Required Properties: WorkerTypeElements Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0 Delete Marks a worker type record for deletion. This worker type must exist Return Value Type: None Required Properties: WorkerTypeElements Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0 Load Returns the specified worker type. The worker type must exist Return Value Type: WorkerType tag Required Properties: WorkerTypeElements Access Control Point Name: View Introduced in v5.0; last changed in v5.0 LoadAll Returns all available worker types. Return Value Type: Zero or more WorkerType tags Access Control Point Name: View Introduced in v5.0 RetrieveAllNames Returns the names of all worker types (SDM-required action).

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1109

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Return Value Type: (***undefined***): KBusinessObjectNameList Access Control Point Name: View Introduced in v5.1 RetrieveForUpdate Returns the specified worker type (SDM-required action). Return Value Type: WorkerType tag Required Properties: Name Access Control Point Name: View Introduced in v5.1; last changed in v5.1 Update Adds a new worker type or updates an existing one. Return Value Type: None Required Properties: WorkerTypeElements Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0 UpdateOnly Updates an existing worker type value. Return Value Type: None Required Properties: WorkerTypeElements Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0

Property Descriptions
Name

Worker Type
The name of the worker type. Type: String

1110

Kronos Incorporated

WorkerType Tag

Optional Key Maximum length: 50 characters Sample values: Full Time, Part Time, Per Diem Introduced in v5.1 WorkerTypeElements

Set of worker type elements
A list of the elements that comprise the worker type. The elements are defined using the WorkerTypeElement tag. Type: Zero or more WorkerTypeElement tags Required Introduced in v5.0; last changed in v5.1

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1111

Chapter 2

Workforce Timekeeper XML API Tag Definitions

WorkerTypeElement Tag WorkerType Elements
The WorkerTypeElement tag defines a worker type. It is used by WorkerType tag. Function Access Control Point: API.Common Introduced in v5.0; last changed in v5.0

Syntax
Properties→ <WorkerTypeElement [IsActive = Boolean] NewName = String WorkerTypeName = String > </WorkerTypeElement>

Property Descriptions
IsActive

Is worker type active?
Specifies whether the worker type is active. If True, it is active. Type: Boolean Optional Enumerated value: True, False Introduced in v5.0 NewName

New name of worker type
You can specify a new name for the worker type if you are updating an existing one. Type: String Optional Key

1112

Kronos Incorporated

WorkerTypeElement Tag

Maximum length: 50 characters Introduced in v5.0 WorkerTypeName

Worker type name
The name of the worker type Type: String Required Key Maximum length: 50 characters Sample values: Full Time, Part Time, Per Diem Introduced in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1113

Chapter 2

Workforce Timekeeper XML API Tag Definitions

WorkflowAccessAssignment Tag Process Profiles Assigned to a Person
The WorkflowAccessAssignment tag assigns a person to a specific employee process profile and/or a manager process profile. Each person is identified through the Identity property. The Identity of a person must be specified as a property of the WorkflowAcessAssignment tag. Either the EmployeeWorkflowProfileName and/ or the ManagerWorkflowProfileName must be specified to assign the specified person to the a given employee process profile and manager process profile. Function Access Control Point: API.WorkflowAccessAssignment Introduced in v5.0; last changed in v5.0

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "Load" | "UpdateOnly" Parameters→ None Properties→ <WorkflowAccessAssignment [EmployeeWorkflowProfileName = String] [ManagerWorkflowProfileName = String] > <Identity> <CurrentUser> | <PersonIdentity> </Identity> </WorkflowAccessAssignment>

1114

Kronos Incorporated

WorkflowAccessAssignment Tag

Action Descriptions
Load Retrieves a process profile access assignment given the Identity of a person. The Identity property must be specified for the Load Action. The Identity property must be specified for the Load Action. The Person or the Person Number specified in the Identity property must already exist in the database, prior to calling the Load Action. Return Value Type: WorkflowAccessAssignment tag Required Properties: Identity Access Control Point Name: View Introduced in v5.0; last changed in v5.0 UpdateOnly Assigns a person to a specific employee process profile and/or a manager process profile. For the UpdateOnly action, the Identity property MUST be specified, and EmployeeWorkflowProfileName and/or the ManagerWorkflowProfileName MUST be specified. Return Value Type: None Required Properties: Identity, Either EmployeeWorkflowProfileName and/or ManagerWorkflowProfileName Access Control Point Name: Edit Introduced in v5.0; last changed in v5.0

Property Descriptions
EmployeeWorkflowProfileName

Process profile for employees
Name of employee process profile. The EmployeeWorkflowProfileName must be specified as a property for the UpdateOnly Action, if you wish to assign a specific process profile name as the employee process profile. Type: String

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1115

Chapter 2

Workforce Timekeeper XML API Tag Definitions

Optional If the EmployeeWorkflowProfileName is defined for an action, the EmployeeWorkflowProfileName cannot be null. The EmployeerWorkProfileName must be assigned a string value of a process profile name that already exists in the database. Sample values: EmployeeWorkflowProfileName="All Process Templates" Introduced in v5.0; last changed in v5.0 Identity

Identity
Identifies the subject person. The Identity property MUST be specified for the UpdateOnly and Load Actions. Type: Either CurrentUser or PersonIdentity tag Required Key If the Identity property is defined for an action, the Identity property cannot be null. The Person or the Person Number must already exist in the database, before assigning the process profile(s). Sample values: <Identity> <PersonIdentity PersonNumber="207"> </PersonIdentity> </Identity> Introduced in v5.0; last changed in v5.0 ManagerWorkflowProfileName

Process profile for managers
Name of the manager process profile. The ManagerWorkflowProfileName must be specified as a property for the UpdateOnly Action, if you wish to assign a specific process profile name as the manager process profile. Type: String

1116

Kronos Incorporated

WorkflowAccessAssignment Tag

Optional If the ManagerWorkflowProfileName property is defined for an action, the ManagerWorkflowProfileName cannot be null. The ManagerWorkProfileName must be assigned a string value of a process profile name that already exists in the database. Sample values: ManagerWorkflowProfileName="All Process Templates" Introduced in v5.0; last changed in v5.0

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1117

Chapter 2

Workforce Timekeeper XML API Tag Definitions

WorkflowTemplateCategory Tag Workflow Template Category
The Process Template Category specifies the template categories. A process template can be assigned to one or more categories of choice. Function Access Control Point: com.kronos.wfc.business.workflow.KTemplateCategory Introduced in v5.1; last changed in v5.1

Syntax
Request→ <Request Action = Actions Parameters > Properties </Request> Actions→ "RetrieveAllCategories" Parameters→ None Properties→ <WorkflowTemplateCategory [Description = String] Id = Long Name = String Originator = Integer > </WorkflowTemplateCategory>

Action Descriptions
RetrieveAllCategories This action returns a list of the template categories. Return Value Type: WorkflowTemplateCategory tag Access Control Point Name: Edit

1118

Kronos Incorporated

WorkflowTemplateCategory Tag

Introduced in v5.0a; last changed in v5.0a

Property Descriptions
Description

Category description
A description of the category. Type: String Optional Maximum Length: 250 characters Introduced in v5.1 Id

Category identifier
The category's Id. Type: Long Required Key Must be greater than zero Introduced in v5.1 Name

Category name
The category's name. Type: String Required Maximum Length: 50 characters Introduced in v5.1 Originator

Category originator

Workforce Central Developers Toolkit Reference Guide—Timekeeping

1119

Chapter 2

Workforce Timekeeper XML API Tag Definitions

The Category Originator defines if the cat