WTK 50 Dtkprog

Workforce Central
Developers Toolkit
Programmers Guide
A programmers guide to the XML API.
Kronos Workforce Central Suite Version 5
Document Part Number: 4703092-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 2001-2004.
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, ShopTrac, ShopTrac Pro, StarComm,
StarPort, StarSaver, StarTimer, TeleTime, Timekeeper, Timekeeper Central, TimeMaker, Visionware, Workforce
Accruals, Workforce Central, Workforce Decisions, Workforce Express, Workforce Genie, and Workforce TeleTime
are registered trademarks of Kronos Incorporated or a related company. Comm.Mgr, CommLink, DKC/Datalink,
FasTrack, HyperFind, Improving the Performance of People and Business, Kronos 4500, Kronos 4500 Touch ID,
Kronos e-Central, Labor Plus, Schedule Assistant, Smart Scheduler, StartLabor, Start Quality, Start WIP, Starter
Series, Timekeeper Decisions, Timekeeper Web, VisionPlus, Winstar Elite, WIP Plus, Workforce Activities,
Workforce Connect, Workforce Employee, Workforce HR, Workforce Manager, Workforce MobileTime, Workforce
Payroll, Workforce Record Manager, Workforce Recruiter, Workforce Scheduler, Workforce Smart Scheduler,
Workforce Tax Filing, and Workforce Timekeeper are trademarks of Kronos Incorporated or a related company.
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 a complete list of the international subsidiaries, see the following Kronos Incorporated Web page:
http://www.kronos.com/world/index.htm
Document Revision History
Document Revision
Product Version
Release Date
Workforce Central Version 5.0
March 2004
Contents
About This Guide

Who Should Read This Guide ...................................................................... vi
Organization of This Guide ......................................................................... vii
Conventions ................................................................................................viii
Presentational Conventions ..................................................................viii
General Text Formatting Conventions .................................................viii
Coding Conventions ............................................................................... ix
Abbreviations and Terms ............................................................................. xi
Workforce Timekeeper Documents ............................................................xiii
Chapter 1: Understanding the XML API
Overview ....................................................................................................1-2
Workforce Central Applications ..........................................................1-2
Understanding XML Elements and Tags ...................................................1-3
Data-Only Tags and Data-Only Target Tags .......................................1-4
Action Attribute ...................................................................................1-9
HTTP Connections, Transactions, and Sessions ..................................1-9
Structuring a Workforce Central Application ...........................................1-16
XML Declaration Tag ........................................................................1-17
Kronos_WFC Tag ..............................................................................1-17
SYSTEM Request ..............................................................................1-17
XML Character Data ................................................................................1-21
Chapter 2: Using the XML API
Combining API Tags with Other Programming Languages ......................2-2
Levels of Abstraction ...........................................................................2-2
Level One Abstraction ................................................................................2-4
Request-Response Examples ...............................................................2-4
Contents
Level Two Abstraction ............................................................................. 2-12

Request-Response Comparative Example ......................................... 2-12
Chapter 3: Advanced Programming Topics
Interpreting Response Data ........................................................................ 3-2
Adding Advanced Features to XML API Applications ............................. 3-3
Implementing a Timesheet Editor in JavaScript ........................................ 3-4
Application Overview ......................................................................... 3-5
Setup Information ................................................................................ 3-5
System Requirements .......................................................................... 3-5
Known Issues ....................................................................................... 3-6
Appendix: Creating Portals and Third-party Web Sites
Overview ...................................................................................... Appendix-2
Understanding the URLs in the DTK .......................................... Appendix-3
Calling Servlets with URLs ................................................... Appendix-3
Specifying a New Launch Window ....................................... Appendix-4
Appending Query String Parameters to URLs ...................... Appendix-5
Logging On to the Server with the Logon URL .......................... Appendix-8
Logging On Using the XmlService URL in an HTML Form Appendix-8
Redirection and Error Handling ............................................ Appendix-9
An Alternative Logon: Using the Logon Servlet .................. Appendix-9
Creating a Sample Workforce Central Portal with URLs .......... Appendix-10
Body.html Source Code File ............................................... Appendix-10
Index.html Source Code File ............................................... Appendix-10
Logon.htm File .................................................................... Appendix-11
Nav.html File ....................................................................... Appendix-13
Title.html File ...................................................................... Appendix-16
Sample Source Code for the Nav Frame .......................... Appendix-16
Enhancing a Third-party Web Site with
Workforce Central URLs .......................................... Appendix-21
Index
iv
Kronos Incorporated
About This Guide
This programmers guide is part of the Developers Toolkit (DTK) for the
Kronos Workforce Central system. A companion document titled Workforce
Central Developers Toolkit Reference Guide provides a formal definition,
description, and syntax specification for each Extensible Markup Language
(XML) tag and element in the application program interface (API).
Caution: The source code examples in this programmers guide are provided for
instructional purposes only. The XML tags described herein are not guaranteed to
be compatible with the XML tags defined in the Workforce Central Developers
Toolkit Reference Guide. In all circumstances relating to the XML API, the
reference guide takes precedence over every other Workforce Central document.
The Document Type Definitions (DTDs) in the reference guide are tag-level
descriptions that do not reflect the entire domain. No actions or parameters are
specified. The DTDs are provided for descriptive purposes only. They are not
validated, and are subject to change. They are not used by Kronos or the
Workforce Central server to validate any aspect of the XML API.
This guide documents the purpose and use of the XML API. It contains an
appendix that documents a set of Workforce Central Uniform Resource Locators
(URLs) that can invoke Workforce Central servlets from custom Workforce
Central portals and third-party Web sites.
This preface contains the following sections:
!
Who Should Read This Guide
Organization of This Guide
Conventions
Abbreviations and Terms
Workforce Timekeeper Documents
About This Guide
Who Should Read This Guide

The Workforce Central Developers Toolkit is intended for use by programmers,
system integrators, developers, Web developers, and similar software
professionals who have significant experience working with the following
software technologies:
!
Windows NT/2000 operating system
Object-oriented databases
Distributed client-server environments
High-level object-oriented languages such as Java, C++, Visual Basic, and

JavaScript
It is also assumed that these software professionals have significant prior

knowledge of the following Web-based technologies:
vi
Tag-based markup languages such as Hypertext Markup Language (HTML)

and XML
Data transfer protocols such as Transmission Control Protocol/Internet

Protocol (TCP/IP), Hypertext Transfer Protocol (HTTP), and Hypertext
Transfer Protocol Secure (HTTPS)
URLs
Request-response transactions and sessions
Static and dynamic transactions and sessions
The Workforce Central XML graphical user interface (GUI), Java applets and
servlets
Kronos Incorporated

This guide contains the following information:
!
Chapter 1, Understanding the XML API, describes the Extensible Markup

Language (XML) Application Program Interface (API) provided with the
Workforce Central Developers Toolkit (DTK).
Chapter 2, Using the XML API, describes how to use the XML API. The
levels of abstraction commonly imposed in API applications are summarized.
Chapter 3, Advanced Programming Topics, introduces and discusses

advanced HTML API programming topics. All the tags in the XML API are
defined and described in a companion document entitled Workforce Central
Developers Toolkit Reference Guide.
Appendix, Creating Portals and Third-party Web Sites, describes the set of
Uniform Resource Locators (URLs) supplied with the DTK.
Each chapter is modular in structure and sequential in presentation. Each chapter

begins with a short overview of its primary topic and presents several commented
source code examples. These examples provide multiple opportunities for
hands-on experience using the XML API tags to complete real-world tasks by
manipulating the structured data in the Workforce Central database.
Workforce Central Developers Toolkit Programming Guide
vii
About This Guide
Conventions
This guide relies on the following conventions to promote presentational clarity,
maintain internal consistency, and ensure overall accuracy and completeness:
!
Presentational Conventions
General Text Formatting Conventions
Coding Conventions
Presentational Conventions
The chapters in this guide are modular in structure and task-oriented in
composition. You are encouraged to glance through the overviews at the
beginning of earlier chapters and read ahead to later sections or chapters as you
gain experience with the API. For example, if you are a Web programmer who is
already somewhat familiar with the API, you might decide to glance through the
first two chapters before turning your attention to the extended code examples in
the final chapter.
Each chapter begins with high-level overview information and progresses to
code-level examples and explanations. Bulleted lists summarize information that
is presented in greater detail in subsequent sections. Cross-references to other
documents are presented where appropriate, but every effort has been made to
minimize the need to refer to multiple documents at the same time.
General Text Formatting Conventions

The following text formatting conventions are used throughout this guide:
viii
Monospace text identifies code-level syntax statements, code examples,

sample source code, and individual XML code elements that appear in body
text. <MonospaceText> in angle brackets (<>) in body text indicates
either an HTML tag or an XML tag.
Bold monospace text identifies code elements that are highlighted for
clarity.
Kronos Incorporated
Conventions
Italic text identifies terms that are being introduced for the first time. It also
highlights the names of parameters. For example, when name=value pairs are
discussed, the following parameter names are italicized to indicate that they
are parameter names rather than string values: name=value
Bold text identifies generic tag categories.
Bold italic text identifies code-level parameters that appear in syntax

statements. For example, in many URLs the term localhost is presented in
boldface italic text to identify it as a parameter rather than an actual system
name.
Coding Conventions
Source code examplesand all tag names and similar source-code elements that
appear in descriptive paragraphsare presented in monospace text. The
formatting of coding examples is consistent with the programming language
employed.
Large sections of source code are often presented in smaller monospace text to
promote readability by minimizing awkward line breaks.
XML Tag Syntax Statements
Syntax statements and formal code-level definitions of XML tags and similar API
elements employ the following formatting conventions, all of which are further
described in subsequent chapters and fully documented in the Workforce Central
Developers Toolkit Reference Guide:
!
XML tag names, attribute names, and property names are case sensitive and
are therefore shown in UpperLowerCase text.
In general, attribute values are case sensitive. Exceptions to this rule are
clearly noted.
Variable names are shown in Italics. For emphasis in code examples, some
variable names, parameter names, and other code elements are shown in Bold
Italics.
Brackets ([ ]) surround optional expressions in syntax statements.
ix
About This Guide
A vertical pipe ( | ) delimits mutually-exclusive options in a syntax statement.

For example, the notation option A | option B | option C can be interpreted
as Specify option A, or option B, or option C.
An asterisk (*) appended to an expression in a syntax statement indicates that

zero or more occurrences of the expression can be specified, as long as each
occurrence is separated by white space.
Comments in syntax statements are preceded by two forward slashes and

enclosed in pairs of braces ({}). For example, {//This represents a
comment in a syntax statement.}
Kronos Incorporated

The abbreviations, terms, and aliases that appear in this guide are consistent with
those defined in the Workforce Central document set. Each term that is
abbreviated is spelled out completely the first time it appears in a chapter or major
section. Its abbreviation or acronym is enclosed in parenthesis.
The following informal aliases are used in the context of the Workforce Central
Developers Toolkit:
!
The term tag is used as an informal alias for ...the XML element that
contains this tag.
Angle brackets (< >) surrounding a monospace tag name in descriptive text
serve as an informal alias for the term tag.
The following example demonstrates the use of both informal aliases:

Specify the XML element that contains the AnyName tag, is synonymous with
the aliased sentence Specify <AnyName>.
xi
About This Guide
The following abbreviations and terms appear throughout this programmers

guide:
xii
Abbreviation
Meaning
API
Application Program Interface
DTD
Document Type Definition
DTK
Developers Toolkit
GUI
Graphical User Interface
HTML
Hypertext Markup Language
HTTP
Hypertext Transfer Protocol
HTTPS
Hypertext Transfer Protocol Secure
RDBMS
Relational Database Management System
TCP/IP
Transmission Control Protocol/Internet Protocol
UI
User Interface
URL
Uniform Resource Locator
XML
Extensible Markup Language
Kronos Incorporated

The following documentation is available to help you install, maintain, and use
the Workforce Timekeeper database and software:
!
Workforce Timekeeper Installation Guide for Windows provides an overview

of the Workforce Timekeeper architecture, outlines the system requirements,
explains how to install the products server and client components, and
includes licensing and upgrade requirements.
Workforce Timekeeper Installation Guide for UNIX describes how to install

the Workforce Timekeeper server on UNIX platforms. It provides an
overview of the Workforce Timekeeper architecture, outlines the system
requirements, and explains how to install the Application Server and
Background Processor on UNIX platforms.
Getting Started with Workforce TimekeeperA Guide for Managers explains

some of the most common tasks that managers are likely to perform. It
summarizes key product features for people who access employee time and
attendance information. The book also explains the various Workforce
Timekeeper components and the most common tasks that managers are likely
to perform with each component.
Getting Started with Workforce TimekeeperA Guide for Employees (Java

version) explains some of the most common employee tasks, which include
using the Timecard and Time Stamp components, as well as viewing personal
schedules and reports.
Getting Started with Workforce TimekeeperA Guide for Employees (HTML

version) explains some of the most common employee tasks in Workforce
Employee - HTML Client, which include using the Timecard, Time Stamp,
and Quick Time Stamp components, as well as viewing personal reports.
Workforce Timekeeper System Administrators Guide describes the

administrators activities, such as system configuration and setup, and
working with log reports, predefined data, and diagnostic tools.
Workforce Central Database Tables Reference Guide contains details about

the Workforce Central database tables.
xiii
About This Guide
xiv
Workforce Central Database Views Reference Guide provides information and

details about Views and how they are used as virtual tables in Workforce
Central.
Workforce Timekeeper Database Installation Guide instructs customers and

service personnel who install or upgrade Workforce Timekeeper databases.
Instructions include installing and setting up the Relational Database
Management System (RDBMS) and Kronos application database
components, and upgrading your database components for compatibility with
new versions of Workforce Timekeeper products.
Workforce Timekeeper Database Administrators Guide explains how to

maintain the Oracle and SQL Server 2000 databases for Workforce
Timekeeper. This guide includes procedures for backing up databases,
restoring and recovering databases, adjusting performance, and using
maintenance utilities.
Workforce Timekeeper Import Guide: Table Format provides instructions and

table data for Workforce Timekeeper Import tables.
Workforce Timekeeper Import Users Guide provides information about

setting up and running XML and table imports for labor management systems.
It describes the Transaction Assistant used to correct failed XML import data.
Workforce Timekeeper XML Import Guide provides information that

specifically addresses XML import issues, and includes descriptions of all of
the tags, actions, and properties used by import transactions.
Guide to Translating and Customizing the Workforce Timekeeper User

Interface and Online Help provides instructions for editing the browser-based
graphical user interface, the Setup applications user interface, and the
associated browser-based Help files for Workforce Timekeeper and
Workforce Scheduler.
Developers Toolkit documentation: Workforce Timekeeper includes an

Application Program Interface (API) that you can use to access certain
Workforce Timekeeper features from application programs. The Workforce
Central Developers Toolkit Programming Guide includes annotated sample
programs that show how to use the API, and the Workforce Central
Developers Toolkit Reference Guide provides detailed information about each
element of the API.
Kronos Incorporated
Online Help for the Workforce Timekeeper system is installed automatically

with the product. To access online Help: click the Help link at the bottom of
the navigation bar; click the Help icon in the component; or click the Help
button in a dialog box.
Release notes provide additional information about Workforce Timekeeper,

including a list of new features, resolved issues, and late-breaking changes.
xv
About This Guide
xvi
Kronos Incorporated
Chapter 1
Understanding the XML API
This chapter describes the Extensible Markup Language (XML) Application

Program Interface (API) provided with the Workforce Central Developers
Toolkit (DTK).
This chapter contains the following sections:
!
Overview
Understanding XML Elements and Tags
Structuring a Workforce Central Application
XML Character Data
Chapter 1
Overview
The Workforce Central XML API is an open, platform-independent XML-based
programming interface. The API enables software professionals to implement
Web-based applications that programmatically transmit and receive real-time
information from the Workforce Central database.
The XML tags and attributes form a programming interface that is conceptually
object-oriented: API objects perform specified actions at the request of your client
application. The results of these actions are returned to your client application in
the form of XML responses.
In the context of this guide, an API object is an XML tag that corresponds to a
persistent object in the Workforce Central database. These tags contain both
attributes and other tags. A few API objects are transientthey do not correspond
to any object in the Workforce Central database, but they provide a container for
aggregating objects that do reside in the database.
Workforce Central Applications

When you combine the Workforce Central XML API with a high-level
programming language like JavaScript, Java, C++, or Visual Basic, or a markup
language like HTML, the resulting Web-based application represents a real-time
programmatic alternative to updating the Workforce Central database by using the
Workforce Central graphical user interface (GUI).
You can extract data from the Workforce Central database and use it in your own
application, or you can pass data from another application to Workforce Central.
For example, you can pass accruals to another application in your organization or
pass data from another application to the Workforce Central database.
You can build an interface to another technology. For example, you can create a
version of the Workforce Central timecard for use on a cell phone display.
Regardless of the programming language you select, the resulting Workforce
Central applications use Transmission Control Protocol/Internet Protocol (TCP/
IP) over an HTTP connection, as described in the next section.
1-2
Kronos Incorporated

An XML element is a hierarchically ordered container that holds a tag of the same
name plus other XML tags and/or attributes.
Note: In the context of the Developers Toolkit, the term tag is often used as an
abbreviation for ...the XML element that contains the tag.
The <Request> tag enables you to specify requests that are carried out by the
WTK server. <Request> tags are considered the root tags in the API because
they can contain every category of tag defined by the API, as indicated by the
following diagram:
<Request>
People
Access
Schedule
Labor
Accruals
HyperFind
Timekeeping
You use the <Request> tag to specify each request that your API application
submits to the Workforce Central server.
Each <Request> tag contains:
!
One Action attribute that specifies the functionality of the <Request>.
One or more Data-only tags (tags that contain only data structures) whose
syntax statements declare them to be valid Target tags of the Action
attribute (see the next two sections for formal definitions of the terms Dataonly and Target.)
Zero or more Data-only tags that are not Target tags of the Action attribute.
1-3
Chapter 1
Data-Only Tags and Data-Only Target Tags

Data-only tags, by definition, do not contain any Action attributes. They contain
only data structures that enable you to complete the specification of each
<Request>.
A small number of the Data-only tags in the API are considered Target tags or
Targets because their syntax statements designate them as valid targets of one or
more Action attributes.
The API includes the following categories of Target tags:
Category
Description
Access tags
There is only one Target tag in this category, <AccessProfile>. The

tag enables your application to retrieve the Access Profiles of the specified
Workforce Central users.
Accruals tags The following Target tags enable your API application to edit the accrual
balances of specified employees:
!
!
<ResetAccrual>
<EarnedAccrual>
HyperFind
tags
There is one Target tag in this category, <HyperFindQuery>. The tag

enables your application to request partial queries known as HyperFind
queries. These queries define sets of persons, employees, or users (see
People tags later in this table) that can be specified in subsequent requests
that normally require the specification of a single individual. See the
description of People tags later in this table for formal definitions of the
italicized terms.
Labor tags
These Target tags enable your application to create, edit, and retrieve the
seven-level Labor configuration stored in the Workforce Central database.
There are three kinds of Target tags in this category, all of which are
persistent:
<LaborLevelDefinition>-Defines the name and position (in
the seven-level hierarchy) of a given labor level.
! <LaborLevelEntry>-Defines the name of a labor entry for a
particular level.
! <LaborAccount>-Defines a seven-element tuple of labor entries.
See Target Tags that Maintain Persistence for an explanation of
Persistent tags.
!
1-4
Kronos Incorporated
Category
Description
People tags
The Person table in the Workforce Central database contains the following
information for each person in the system:
!
!
!
!
!
!
Name Information
Person Number (a unique identifier for each person in the database)
Birth Date
Hire Date
Wage Rate
Full/Part Time Hours
Every person in the Workforce Central database is represented by a

<PersonIdentity> tag, which, though not a Target tag, is associated
with the <PersonInformation> Target tag. This Target tag defines a
persons Access Assignment, Badge Assignment, Custom Data, Custom
Dates, EMail Addresses, Employment Status, Expected Hours, Home
Account, Licenses, Naming, Postal Addresses, Supervisor, Telephone
Numbers, and User Account Status.
The following Data-only tags can be added to a
<PersonInformation> tag to specify additional data:
<WTKEmployee>
Every person in the database who is also an employee has additional
information in this Data-only tag.
! <User>
Every person in the database who is also a user has additional
information in this Data-only tag.
!
The <Personality> tag maintains the informational interdependencies that exist among these different tags (status, licensing, and
so on) by checking all of the dependencies.
You can specify a <Request> tag whose Load attribute "targets" a new
<PersonInformation> Target tag, even one that contains a
<WTKEmployee> tag and/or <User> tag without specifying a
<PersonIdentity> tag. However, you cannot Add or Update a
<PersonInformation> Target tag without specifying a
<PersonIdentity> tag.
1-5
Chapter 1
Category
Description
Schedule tags There are three Target tags in this category:

<Schedule>
A temporary, transient container tag that aggregates the shifts assigned
to a set of employees or groups over a specified span of time. The tag
contains Data-only tags that represent the shifts and segments of the
schedule. You use a <Schedule> tag to retrieve schedule
information for employees and to manage the association between
employees (or Groups) and Shift tags.
! <ScheduleGroup>
Represents a collection of employees who are treated in the same way
for scheduling purposes. Since employees are moved from group to
group periodically, the content of a <ScheduleGroup> tag is
defined by the group name and an effective date span. Adding an
employee to one group implicitly removes him/her from all other
groups during that groups effective date span.
<ScheduleGroup> tags can respond to their own Action
attributes. However, these tags are more commonly used as
components of a <Schedule> tag.
! <Holiday>
Represents a predefined holiday period.
!
Timekeeping These tags create and retrieve punch, edit, audit, exception, and total
tags
information. The API provides four Target tags in this category:
<Punch>
Represents a time punch of the same type that originates from a
Kronos terminal.
! <PayCodeEdit>
Represents an amount of time or money that must be added to a pay
code.
! <WorkedDuration>
Represents a time duration to be included in the computation of hours.
See XML Character Data for more information about specifying time
durations.
! <PayCodeEditMove>
Represents an amount of time or currency that must be moved from
one labor account and paycode to another.
!
1-6
Kronos Incorporated
Note: The object System supports the Logon and Logoff Action attributes, as well
as the <Error> tag in the <Response> tag.
The following individual Target tags and Data-only tags are included in each of
the categories:
Tag
Category
Data-only
Target Tag
Related
Data-only Tags
Access Tags
<AccessProfile>
<Permission>
Accruals Tags
<ResetAccrual>
<EarnedAccrual>
<AccrualBalanceSummary>
<AccrualCode>
<AccrualProfile>
HyperFind Tags <HyperFindQuery>
<HyperFindQueryResult>
Labor Tags
<LaborAccount>
<LaborLevelDefinition>
<LaborLevelEntry>
<AdhocLaborAccount>
Schedule Tags
<ScheduleGroup>
<Schedule>
Timekeeping
Tags
<DateTotalSummary>
<ApproveSignoff>
<Exception>
<CancelDeductions>
<PeriodTotalSummary>
<WorkedDuration>
<HistoricalPayCodeEdit>
<HistoricalPayCodeMove>
<MarkForTotalization>
<PayCodeEdit>
<PayCodeMove>
<Punch>
<Timesheet>
<ScheduleShift>
<ShiftCode>
<ShiftSegment>
<ScheduleUnavailable>
1-7
Chapter 1
Tag
Category
Data-only
Target Tag
Related
Data-only Tags
People Tags
<PersonInformation>
<AccessAssignment>
<BadgeAssignment>
<CustomData>
<CustomDate>
<EmailAddress>
<EmploymentStatus>
<ExpectedHours>
<HomeAccount>
<Licenses>
<Naming>
<Person>
<PostalAddress>
<Supervisor>
<TelephoneNumber>
<UserAccountStatus>
<User>
<UserAccount>
<PasswordHistory>
<UserAccountLockout>
<Personality>
<WTKEmployee>
<PersonIdentity>
1-8
Kronos Incorporated
Action Attribute
The single Action attribute that you specify for each <Request> must be
listed in the syntax statements of all of the Target tags specified in the
<Request>. Targets are the Data-only containers through which the
functionality of the API is expressed. Targets can contain Data-only tags that are
not Targets. However, Data-only tags that are not Targets must never contain
Targets.
HTTP Connections, Transactions, and Sessions

Each Web-based application that you create with the Workforce Central XML API
runs on a client computer that may be physically separated from the computer on
which the Workforce Central server is installed. A Transmission Control Protocol/
Internet Protocol (TCP/IP) network connects the client system to the Workforce
Central server.
Your application interacts with the server through a series of transactions that are
linked into a continuous session by cookies (user-transparent data objects that can
be recorded onto a clients non-volatile storage media to preserve context and
state from transaction to transaction). The code examples in Chapter 2, Using the
XML API provide language-specific information about preserving context and
state with cookies.
1-9
Chapter 1
Request-Response Transactions
Each transaction is a two-part interaction that begins when your application
submits a single fully-specified <Request> tag to the server. Each transaction is
completed when the server returns a single <Response> to that <Request>.
Every Sessions Initial Transaction
Like a Web browser, your Web-based API application must submit an initial
request for an HTTP connection to the Workforce Central server before it can
initiate an ongoing session. The server responds to this initial request by opening
an HTTP connection as shown:
HTTP Connection
Your
Web-based
Application
Workforce
Central
Server
The HTTP request must specify:

!
The following Workforce Central URL, where localhost specifies the system
on which the Workforce Central server runs:
http://localhost/wfc/logon
All attributes of the HTTP connection required by the API mechanism.
Note: Your programming language of choice provides language-specific methods

and libraries for establishing and managing HTTP connections. See Chapter 2,
Using the XML API for several language-specific examples that demonstrate
how to configure the initial HTTP connection for a session.
1-10
Kronos Incorporated
The following sequence of events occurs each time your application opens the
HTTP connection and passes an XML <Request>:
1. Your application must first request a Logon to the Workforce Central server. It
does so by opening an HTTP request and passing the server an XML text
string that holds the content of the HTTP <Request>. See Chapter 2,
Using the XML API for language-specific details.
HTTP Connection
Your
Web-based
Application
Logon request
Workforce
Central
Server
2. The server authenticates the username and password specified in the logon
<Request>.
3. Your application opens an HTTP response and reads the content of the
servers response to its logon <Request> into a text string that represents
the XML <Response> to that <Request>.
HTTP Connection
Your
Web-based
Application
Logon response
Workforce
Central
Server
1-11
Chapter 1
4. Once the server has successfully authenticated your applications logon

<Request>, a session is established. Your application continues the session
by submitting its next <Request>.
HTTP Connection
Your
Web-based
Application
Next request
Next response
Workforce
Central
Server
5. Your application passes each subsequent <Request> to Workforce Central

and returns the results to your application in the form of a single XML
<Response> to each API application <Request>.
Note: The Workforce Central system automatically sets a JRUN session
timeout value, which is typically 30 minutes. If your XML session is inactive
for longer than this, you may lose your XML session as well as the state
information that was stored in the session cache. However, you can keep the
connection active by periodically sending at least one request while JRUN is
active. Continue to send requests periodically. Each request resets the timer. If
necessary, you can send a ping request. To do this, send an empty Request tag
with Object=System and Action=ping.
6. To close the session gracefully, your application must submit an XML Logoff
<Request>.
HTTP Connection
Your
Web-based
Application
Logoff request
Logoff response
Workforce
Central
Server
7. The Workforce Central server responds to the Logoff request by dropping the
HTTP connection. An application normally requires only one Logon, one
session, and one Logoff per execution.
1-12
Kronos Incorporated
Specifying Additional Request Tags

Between logging on and logging off of the Workforce Central server, your
application specifies a series of API <Request> tags, each of which contains a
single Action attribute and one or more Data-only tags containing a set of data
properties whose values are specified as strings. For example, the Date property
of a <Punch> tag is a string that adheres to the local-independent format for
dates. In the United States, this format might be the following string:
2/25/2001
Data Properties and Validation Rules
All Action attributes perform syntactic validation and, where appropriate,
semantic validation of the properties of the Data-only tags whose data they target.
In some cases, a property must pass the same validation rules regardless of the
Action that targets its data.
The commonly used properties listed in the following table must obey the
universal validation rules described in the subsequent table:
Property Name
Description
LaborAccountName Specifies the name of a labor account

PayCodeName
Specifies the name of a pay code
WorkRuleName
Specifies the name of a work rule
1-13
Chapter 1
The following validation rules are applied to the described properties:
1-14
Validation Rule
Description and Examples
You can specify a partial

LaborAccountName but
not a completely empty one.
You can specify a LaborAccountName property

consisting of up to six empty entries (for example, ////
//OnlyEntry/). You cannot specify an empty
LaborAccountName (for example, ///////). The
LaborAccountName that you specify is stored in the
database as specified. However, the hours computation
interprets it as a change in the specified portion of the
LaborAccount.
You can sometimes specify a

LaborAccount property
that does not already exist in
the database.
In some cases, if you specify a LaborAccount, its

entries must already exist in the database. In other cases,
if you specify a LaborAccount that contains entries
not already present in the database, the server adds those
entries to the database. This feature supports the
specification of labor entries not already present in the
database. The Workforce Central Developers Toolkit
Reference Guide clearly documents which API tags
allow you to specify a LaborAccount that contains
entries not already present in the database.
In general, you can only

specify configuration tag
properties that already exist in
the database.
Properties that denote a configuration tag in the API (for

example, PayCodeName and WorkRuleName) must
refer to an existing entry in the database. The only
exception to this rulea LaborLevelEntry for
certain properties of certain tagsis fully documented in
the Workforce Central Developers Toolkit Reference
Guide.
Kronos Incorporated
A Generic Request
The following XML code represents a generic <Request> whose syntax can be
customized to any required specification:
<? xml version = "1.0"?>
<kronos_WFC version = "1.0">
<Request
Action = "TheSpecifiedAction"
TargetTag*
/>
The asterisk (*) at the end of the TargetTag parameter indicates that multiple
Target tags can be specified in a single <Request>. Each Target tag becomes the
target of the Action attribute specified in the <Request>.
1-15
Chapter 1

Just as Data-only tags must be "nested" inside individual <Request> tags, all
<Request> tags in your application must be nested inside a single
<Kronos_WFC> tag in the following hierarchical order:
<?xml version = "1.0" encoding =
<Kronos_WFC version = "1.0">
<Request>
Logon attributes go here

</Request>
<Request>
API Tags go here

</Request>
<Request>
API Tags go here

</Request>
<Request>
Logoff attributes go here

</Request>
</Kronos_WFC>
Note: A Logon request is required to begin each session and a Logoff request is
required to gracefully end each session. However, Login and Logout do not have
to occur in the same file. For any given request, the inner tags in the previous
figure are optional.
1-16
Kronos Incorporated
XML Declaration Tag

Typically, the first tag in the hierarchy of your application is the following XML
declaration tag:
<? xml version = "1.0" encoding = "UTF-8" ?>
Note: The XML declaration tag is case-sensitive.
When this tag appears on the top line of your API application, it guarantees that
the XML parser will ensure that the contents of the XML file meets the specified
version and encoding requirements.
Kronos_WFC Tag
The highest-level tag after the XML declaration tag is the following tag, which is
also known as the document element:
This tag contains all other API tags in your Workforce Central application.
SYSTEM Request
The System object is the only <Request> in the API that does not have a tag
representation. Logon and Logoff are Actions of the System object.
1-17
Chapter 1
Logon Request
A Logon <Request> looks like this:
<?xml version = "1.0"?>
<Request
Object = "System"
Action = "Logon"
Username = "SomeValidUsername"
Password = "SomeValidPassword"
/>
</Kronos_WFC>
Note: DataSource, an optional property of the <Request> tag, enables you to
override the default database system as shown:
DataSource = "devicegroup:deviceID"
The devicegroup parameter specifies the new devicegroup and the deviceID
parameter specifies the new deviceID.
1-18
Kronos Incorporated
Logon Response
This is the WFC servers <Response> to a Logon <Request> whose
specified data was successfully authenticated:
<Response
Status = "Success"
/>
</Kronos_WFC>
Target Tags that Maintain Persistence
Many Data-only Target tags support persistence in the Workforce Central server.
These tags are Targets of some, or all, of the Action attributes described in the
following table:
Action Attribute
Description
Delete
When your application specifies a Target tag whose data

properties match those of an entry currently stored in the
Workforce Central database, the Delete attribute causes the
entry to be deleted.
Load

Workforce Central database, the Load attribute populates the
remaining properties of the Target tag with those of the
corresponding database entry. For example, if you populate a
<Schedule> tag with a badge number, a date, and a time,
those data structures are sufficient to locate a matching
Schedule entry in the database if it already exists. When the
server locates the Schedule entry, it adds all previously
unspecified properties to the corresponding <Schedule> tag.
1-19
Chapter 1
Action Attribute
Description
Update

Workforce Central database, the Update attribute updates
only those data properties of the corresponding database entry
that are changed in the corresponding Target tag. If the
database contains no entry that matches the key data properties,
a new entry is created and then updated.
AddOnly
If your application specifies a Target tag whose data properties

do not match those of an entry currently stored in the
Workforce Central database, the AddOnly attribute adds the
new database entry but does not Update any data properties
of any database entry.
UpdateOnly
If your application specifies a Target tag whose data properties

do not match those of an entry currently stored in the
Workforce Central database, the UpdateOnly attribute does
not add any new database entry but does Update any existing
data properties.
Key Properties
Each API tag has a set of key properties that represents the minimum number of
properties required to locate a unique Workforce Central database entry. If the
unique database entry is located, only those properties outside the set of key
properties are added to the corresponding API tag.
1-20
Kronos Incorporated
XML Character Data
XML Character Data

All attribute values are strings in XML. However, some strings represent specific
types of data. For example, a string might contain Boolean data or a date. These
strings always have the same representations: a Boolean string always contains a
value of TRUE or FALSE. A string that contains a date always contains a value
formatted according to the date format for your site. The following types of string
values are used throughout the XML API:
Data Type
Description/Example
AmountInTime
String of the form, "HH:mm:ss". The ss specificaton is

optional.
AmountInCurrency
Locale-specific currency string without currency symbol. For

example, 1.80, in the United States, represents $1.80
Boolean
Case insensitive, "TRUE"|"FALSE"
Date
Example: "10/1/2000"
DateSpan
Dash-separated dates. For example, "10/1/2000-10/31/

2000"
DateTimeSpan
Dash-separated DateTimes. For example,

"10/1/2000 11:00p - 10/2/2000 7:00a". There
must be at least one space before and after the hyphen ( - )
DateTime
Date followed by time. For example, "10/1/2000 9:00a"
Time
Example: "9:00:07p". Specifying the seconds is optional.
TimeSpan
Dash-separated times. For example, "9:00a-5:00p"
TimeZone
One of the five-digit identifiers in the Timezone database table

on page 1-23
Rule Names
Names of Workforce Central elements. They are always case

sensitive.
LaborAccountName
Case-insensitive string. For example, "100/200/300/400/500/

600/700"
PayCodeName
String. For example, "Regular"
WorkRuleName
String. For example, "Restricted"
1-21
Chapter 1
Data Type
Description/Example
Employee
Identifies an employee, either by badge number or by

PersonIdentity number. Tags that allow you to specify an
Employee usually accept either the badge number or the
PersonIdentity number, but not both.
For some tags the

concept of time
includes a specific time
zone and/or Daylight
Savings flag. These tags
accept a group of
attributes called
LocalTimeAttributes.
!
!
!
TIME = Time
TIMEZONE = TimeZone
DAYLIGHTSAVINGSTIME = Boolean
Use daylight savings Boolean, but only if the given timezone

allows daylight savings time.
Note: The XML API requires two kinds of time properties:

!
Non-local time, consisting solely of a number of hours, minutes, and seconds.

An example of a non-local time is the start-time of a scheduled shift, because
schedules are all assumed to operate according to the locale of the employee
or the place of work.
Local time, consisting of a non-local time plus a specific timezone of the
world (and, optionally, a flag indicating whether Daylight Savings Time
should be considered in effect for that time). An example of an interface
requiring local time is the <Punch> tag because it represents the (local) time
at which an employee punched a terminal.
The precise kind of time is specified for each interface.
1-22
Kronos Incorporated
XML Character Data
The following table is the Timezone table in the Workforce Central database.
1-23
Chapter 1
1-24
Kronos Incorporated
Chapter 2
Using the XML API
This chapter describes how to use the Workforce Central Extensible Markup
Language (XML) Application Program Interface (API). The levels of abstraction
commonly imposed in API applications are summarized.
!
Combining API Tags with Other Programming Languages
Level One Abstraction
Level Two Abstraction
Caution: The source code in this programmers guide is provided for

be compatible with the formal tag definitions presented in the companion
document titled Workforce Central Developers Toolkit Reference Guide. Its XML
definitions take precedence over XML information in every other Workforce
Central document.
Chapter 2
Using the XML API

This chapter describes how to combine the XML tags in the Workforce Central
API with other programming languages to implement Web-based applications that
programmatically transmit and receive real-time information from the Workforce
Central database.
Levels of Abstraction
There are three levels of abstraction associated with the implementation of API
applications using high-level programming languages to manipulate XML
streams. The following table summarizes all three levels of abstraction. You will
find more information about each level of abstraction in the following sections
and chapter.
Level of Abstraction Description
2-2
Level One
You embed the XML API tags directly in a static or dynamic

HTML page and programmatically manipulate the
<Response> tags with a high-level language such as
JavaScript, Visual Basic, Java, or C++.
Level Two
You use a high-level language to programatically convert XML

API tags to XML strings that are temporarily stored in one or
more files. Storing each XML string in a file permits you to
dynamically specify properties by binding properties to
specified values before passing each string to the Workforce
Central server as an XML <Request> stream.
Kronos Incorporated
Level of Abstraction Description

Level Three
It is possible to re-implement all necessary Action attributes

and XML API tags in an object-oriented language like
JavaScript, creating a comparable object class hierarchy with
equivalent methods in a process known as reification. An
added advantage of using JavaScript is that it easily
accommodates the implementation of the Document Object
Model (DOM) core API. The DOM core API enables your API
application to dynamically specify properties by accessing and
manipulating parsed XML content in a DOM Document
Object. You can bind variables to specified values and then get
the resulting XML string from the DOM Document Object and
submit it to the Workforce Central server as an XML
<Request> stream. Chapter 3, Advanced Programming
Topics, contains an extended example of this level of
abstraction implemented in JavaScript.
Using an XML Parser

Although there is no specific requirement to use an XML parser with the XML
API, the information passed in and out of the Workforce Central server is in the
form of text strings that have specific formats. Some of the <Request> tags and
many of the <Response> tags contain complex, heavily-formatted data
structures. In these cases, it can be difficult to manage these structures as simple
strings. An XML parser builds structures from these strings that are easier to
manipulate programmatically.
2-3
Chapter 2
Using the XML API

When you embed XML API tags directly into a static or dynamic HTML page,
you severely limit the programmatic manipulation of <Request> tags and
<Response> tags regardless of the high-level language you select to implement
your API application. It is possible of course, to accomplish limited batch
processing and even build dynamic selection lists, create context sensitive
navigation controls, and provide limited exception handling, but the impact on
performance will be significant, particularly if multiple users must compete for
limited resources. For this reason, this section does not offer any complete coding
examples. However, several partial examples demonstrate the request-response
cycle that is at the heart of every API application.
Request-Response Examples
This section presents several API-level examples that demonstrate the requestresponse cycle on which all API applications are based.
Caution: The programming code in this programming guide is not supported by
Kronos and is provided "as is" as an accommodation and convenience for Kronos
Customers. Customers who use any code samples contained herein, do so at their
own risk. Kronos provides no expressed or written warranties of any kind for any
of these code samples.
2-4
Kronos Incorporated
First Example
The first example uses one of the Timekeeping Target tags (<Punch>see the
Target tags described in the table on page 1-7). This Target tag has an optional
Action attribute named AddOnly that enables your application to insert a
specified Punch entry into the Workforce Central database.
The syntax statement for the <Punch> tag Identifies three properties that are
Required Keys (Date, PersonIdentity, and Time). Required Key
properties must be specified. See the syntax statement in either the HTML file or
the Workforce Central Developers Toolkit Reference Guide.
One property with a Required Key (<PersonIdentity>) is a Data-only tag
that is not a Target tag. It requires you to specify one of two data properties
(BadgeNumber or PersonNumber).
1. Request the Logon to establish the HTTP connection:
<Request
Object = "System"
Action = "Logon"
/>
</Kronos_WFC>
2. Test programatically for a successful Logon by parsing the <Response>

from the server.
2-5
Chapter 2
Using the XML API
3. Request that the specified Punch be entered into the Workforce Central
database:
<Request Action = "AddOnly">
<Punch
Date = "2/14/2001"
Time = "9a">
<Employee>
<PersonIdentity>
<PersonIdentityList>
<PersonIdentity
PersonNumber = 101 />
<PersonIdentity
PersonNumber = 102 />
</PersonIdentityList>
</PersonIdentity>
</Employee>
</Punch>
</Request>
Note: <PersonIdentity> requires you to specify one of two properties.

The PersonNumber property is specified in this example.
4. Test the <Response> from the Workforce Central server for success. The
response attribute of Status has only two possible values: Success or Failure.
2-6
Kronos Incorporated
Second Example
The XML expression in this example logs the specified user on to the Workforce
Central server and retrieves the pay period totals for the specified employee.
1. Request the Logon to establish the HTTP connection:
<Request
Object = "System"
Action = "Logon"
/>
</Kronos_WFC>
2. Test programatically for a successful Logon by parsing the <Response>

from the Workforce Central server.
3. <Request> that pay period totals be returned for the specified period
(Period = "6/1/2001 - 6/7/2001") for the specified employee
(PersonIdentityNumber = "6"):
<Request
Action = "Load"
<Timesheet>
<Employee>
<PersonIdentityNumber = "6"
/>
</Employee>
<Period>
<TimeFramePeriod
PeriodDateSpan = "6/1/2001 - 6/7/2001"
/>
</Period>
</Timesheet>
</Request>
</Kronos_WFC>
2-7
Chapter 2
Using the XML API
The <Response> returned by the Workforce Central server looks like the code
presented in this section. Long lines of code are autowrapped (automatically
reformatted for length) to fit the format of this programmers guide.
<Kronos_WFC TimeStamp = "06/06/2001 6:15PM Eastern Standard Time" >
<Response
Status = "Success">
<Timesheet
LastTotalizationDateTime = "06/06/2001 4:35PM"
TotalsUpToDateFlag = "true" >
<Employee>
<PersonIdentity PersonNumber = "6" />
</Employee>
<PeriodTotalData>
<PeriodTotals
PeriodDateSpan = "06/01/2001 - 06/07/2001" >
<Totals>
<Total IsCurrencyFlag = "false"
LaborAccountDescription = "Westside Plant/Dock Area/Shipping/SQA/
Wire Wrap/Industrial Eng/Test Supervisors" LaborAccountId = "149"
LaborAccountName = "101/201/301/401/501/601/702" AmountInCurrency =
"63.75" PayCodeId = "130" PayCodeName = "All Regular"
AmountInTime = "8:30" />
LaborAccountName = "101/201/301/401/501/601/702" AmountInCurrency
= "63.75" PayCodeId = "121" PayCodeName = "Regular" AmountInTime
= "8:30" />
= "272.00" PayCodeId = "111" PayCodeName = "Evening"
= "1,029.38" PayCodeId = "106" PayCodeName = "Daily-OT"
2-8
Kronos Incorporated
= "60.00" PayCodeId = "122" PayCodeName = "Sick" AmountInTime =

"8:00" />
</Totals>
</PeriodTotals>
</PeriodTotalData>
<Period>
<TimeFramePeriod
PeriodDateSpan = "06/01/2001 - 06/07/2001" />
</Period>
<DailyTotals>
<DateTotals Date = "06/01/2001" >
<Totals>
</Totals>
</DateTotals>
<Totals>
</Totals>
</DateTotals>
<Totals>
</Totals>
</DateTotals>
<Totals>
</Totals>
</DateTotals>
<Totals>
</Totals>
</DateTotals>
<Totals>
= "63.75" PayCodeId = "130" PayCodeName = "All Regular"
2-9
Chapter 2
Using the XML API
= "63.75" PayCodeId = "121" PayCodeName = "Regular" AmountInTime

= "8:30" />
= "272.00" PayCodeId = "111" PayCodeName = "Evening"
= "1,029.38" PayCodeId = "106" PayCodeName = "Daily-OT"
= "60.00" PayCodeId = "122" PayCodeName = "Sick" AmountInTime =
"8:00" />
</Totals>
</DateTotals>
<DateTotals
Date = "06/07/2001" >
<Totals>
</Totals>
</DateTotals>
</DailyTotals>
<TotaledPayCodeEdits>
<PayCodeEdit Date = "06/06/2001" EnteredOnDate =
"06/06/2001" EnteredOnTime = "4:40PM" AmountInTimeOrCurrency =
"8:00" IsCurrencyFlag = "false" PayCodeName = "Sick" >
<Comments>
<Comment CommentText = "Absent" />
</Comments>
</PayCodeEdit>
</TotaledPayCodeEdits>
<TotaledSpans>
</TotaledSpans>
<TotaledWorkedDurations>
<WorkedDuration Date = "06/06/2001" EnteredOnDate =
"06/06/2001" EnteredOnTime = "3:16PM" AmountInTime = "100:00" >
<Comments>
<Comment CommentText = "Absent" />
</Comments>
2-10
Kronos Incorporated
<Exceptions>
<TimekeepingException InPunchFlag = "false"
ExceptionTypeName = "UNSCHEDULED" />
<TimekeepingException InPunchFlag = "false"
DifferenceToLimit = "85:00" DurationOfException = "100:00"
ExceptionTypeName = "LONG" />
</Exceptions>
</WorkedDuration>
</TotaledWorkedDurations>
</Timesheet>
</Response>
</Kronos_WFC>
The Status attribute of the <Response> tag is specified as "Success",

which indicates that the <Request> was successful.
Note: If the Request had failed, the Status attribute of the <Response>
would be set to "Failure" and the <Timesheet> tag would be replaced by
an <Error> tag
The <Response> Action includes a <Timesheet> tag. However, unlike the
<Timesheet> tag in the <Request>, this <Timesheet> tag contains
additional data, including the data in a <PeriodTotals> tag. The hierarchical
chain of contained tags is a structured means of enumerating the totals for the pay
period.
2-11
Chapter 2
Using the XML API

You can use a high-level language to programatically manipulate XML API tags
by storing the resulting XML strings in files. Doing so enables you to dynamically
specify properties by binding them to specified values before passing each XML
string to the Workforce Central server as an XML <Request> stream.
Request-Response Comparative Example

The following example is actually two examples because it has been implemented
in two languages to simplify comparison. Each set of language-specific steps
displays the source code required to Logon to the Workforce Central server,
establish an Hypertext Transfer Protocol (HTTP) connection, and maintain that
HTTP session through the use of cookies.
Note: As described in Chapter 1, Understanding the XML API, an HTTP
connection is used to send the Logon <Request> to the Workforce Central
server. Each programming language environment provides language-specific
methods and libraries for HTTP. You must adapt the example code to your
language of choice.
Java-based Implementation
There are eight steps using the Java language:
1. Open an HTTP connection to the server using the following URL string:
URL url = new URL(http://localhost/wfc/XmlService);
HttpURLConnection conn =
(HttpURLConnection)url.openConnection();
2-12
Kronos Incorporated
2. Configure the connection by setting the HTTP method to POST and the
type of the content to text/xml as shown:
conn.setRequestMethod("POST");
conn.setRequestProperty("Content-type", "text/xml");
The HTTP connection that you establish is used for both input (sending the
XML <Request>) and output (reading the XML <Response>). You must also
ensure that any proxy server or intermediate gateway does not attempt to
cache the <Request> or the <Response>.
conn.setDoOutput(true);
conn.setDoInput(true);
conn.setUseCaches(false);
3. Set the cookies for the connection. Initially, on the first connection to the
server, the set of cookies will be empty. However, the <Response> to the
Logon <Request> will return a set of cookies that must be saved and sent
back in subsequent HTTP requests.
Vector cookies = new Vector();
//set the cookie values - if available

for (int i=0; i <cookies.size(); i++) {
String cookie = (String)cookies.elementAt(i);
conn.setRequestProperty("Cookie", cookie);
}
4. Write the XML text as part of the HTTP request.

String xml_send = <?xml version="1.0"> </Kronos_WFC>
PrintWriter out = new PrintWriter(new
outputStreamWriter(conn.getOutputStream()));
out.println(xml_send);
out.close();
5. Connect to the server.

conn.connect();
6. Open the response from the server.

InputStream is = conn.getInputStream();
2-13
Chapter 2
Using the XML API
7. Read the response. The HTTP response from the server will contain the XML
API response. In the case of the Logon request, the string xml_recv
contains the response.
int size = conn.getContentLength();
byte[] dataBytes = new byte[size];
int bytesRead = 0;
int pos = 0;
//read stream into byte array
while ( (bytesRead >= 0) && (pos < size)) {
if ((bytesRead = is.read(dataBytes, pos, size-pos)) >= 0) {
pos = pos + bytesRead;
}
}
String xml_recv = new String(dataBytes, 0, size);
is.close();
8. Read the cookies from the response and store them for subsequent HTTP
requests.
int j = 1;//
while (true) {
String key = conn.getHeaderFieldKey(j);
if (key==null)
break;
else if (key.equals("Set-Cookie")) {
String value = conn.getHeaderField(j);
cookies.addElement(value);
}
j++;
}
2-14
Kronos Incorporated
Visual Basic Implementation

In this section, the same basic steps implemented in Java in the last section are
implemented in Visual Basic. This comparison reveals that Visual Basic simplifies
the process by internally managing the cookies and much of the HTTP
connection-handling.
The following Inet1 COM object handles the invocation of the HTTP request as
shown:
Dim
Dim
Dim
Dim
sPost As String
sAction As String
sXMLData As String
sHTTPHeaders As String
sPost = "POST"
sAction = "http://localhost/wfc/XmlService"
sXMLData = "<xml ..> <request .. /></xml>"
sHTTPHeaders = "Content-type: text/xml"
' Inet1 object is an instance
' of the msinet.ocx control
' placed on the current form
Inet1.Execute sAction, sPost, sXMLData, sHTTPHeaders
2-15
Chapter 2
2-16
Using the XML API
Kronos Incorporated
Chapter 3
Advanced Programming Topics
This chapter introduces and discusses advanced XML API programming topics.
All of the tags in the XML API are defined and described in the Workforce
Central Developers Toolkit Reference Guide.
!
Interpreting Response Data
Adding Advanced Features to XML API Applications
Implementing a Timesheet Editor in JavaScript
Chapter 3
Interpreting Response Data

The information returned in <Response> tags is often difficult to anticipate
accurately because of the effect of the Workforce Central Totalizer, a software
engine that automatically manipulates Workforce Central data in the background.
The Totalizer processes data, applying rules-based calculations without explicit
notification at the XML tag level. For example, if your API application submits a
<Request> that specifies several alterations to the Workforce Central database,
subsequent <Request> submissions might not reflect the exact data
manipulations your application successfully accomplished earlier because of the
impact of the Totalizers background data-processing.
3-2
Kronos Incorporated

This section describes the Timesheet Editor sample API application. It
demonstrates many advanced features common to sophisticated API applications.
For example, it reifies (creates JavaScript code equivalents of) all XML tags in
the API, creating for each tag an equivalent JavaScript object class with
appropriate accessor methods for the attributes of the tag.
It also implements the core API of the Document Object Model (DOM), which
enables the API application to dynamically specify values by accessing and
manipulating parsed XML content in a DOM Document Object. This strategy
enables the application to bind variables to specified values, then get the resulting
XML string from the DOM Document Object and submit it to the Workforce
Central server as an XML <Request> stream. This third level of abstraction is
readily implemented in JavaScript.
3-3
Chapter 3

The API application described in this section illustrates how to use JavaScript and
HTML to build a relatively complex graphical user interface for the Workforce
Central server using the XML API.
The resulting Professional Timecard Editor is provided for instructional purposes
only and is not supported by Kronos. It might not be compatible with the version
of the XML API currently available to you and might not function as intended.
Caution: The XML tags described herein are not guaranteed to be compatible
with the XML tags defined in the Workforce Central Developers Toolkit
Reference Guide. In all circumstances relating to the XML API, the reference
guide takes precedence over every other Workforce Central document.
The XML tags used in this example have been reified in JavaScript: each tag's
corresponding object definition can be found in a file named after the tag name
with the .js extension.
Note: This example requires Internet Explorer 5.5 or greater. This example will
not work with any version of Netscape.
3-4
Kronos Incorporated
Application Overview
This example illustrates the implementation of a GUI of the Workforce Central
server using the XML API. The data transfer between the Web browser and the
Workforce Central server is performed by a JavaScript object called XMLHTTP.
The actual data transfer between the Web browser and the Workforce Central
server is handled by a JavaScript object named XMLHTTP, which is defined in the
API.js file.
Setup Information
This example has the Logon user and password hard-coded into the source code.
You can change this setting by editing the DEFAULT_USER = "superuser"
and DEFAULT_PSWD = "<superuser password>" variables in the
API.js file. Substitute the actual superuser password at your site for <superuser
password>.
System Requirements
This example requires MSXML, version 2.0 or greater. Version 3.0 sp1 has
problems, too, but is the best option. You can download it from MSDN.
Note: This example requires Internet Explorer 5.5 or greater. It does not support
Netscape. MSXML works with IE 5.0. If you get an error message about an
Automation server not being able to create an object, install the latest version of
MSXML.
3-5
Chapter 3
Known Issues
The follwing are known issues:
1. The XMLHTTP object may drop cookies. A dropped cookie causes any
<Request> to the server to fail due to not being logged on. Selecting the
Logoff option at the top of the GUI, followed by the Logon option usually
resolves the problem. If the problem persists, the Web browser may crash.
This is a known Microsoft bug. For more information, access the Microsoft
support site.
2. Error number 70: Unspecified Error can occur while you are passing data to
the Workforce Central server. You should ignore the error and try again. If the
error persists, close the Web browser window and start again.
3. When you select an existing item in the list of PayCode/Duration edits,
comments are not selected.
4. To Add a new item, select one of the following options:
!
To enter a pay code edit, select a pay code name from the drop-down list
of names.
To enter a duration edit, select Hours Worked.
Enter a date and an amount. Select the New button. The Save button becomes
enabled. Select it to submit all current changes to the Workforce Central
server.
Note: Totals are not updated in the GUI when you enter a new item and press
the Save button, even though this event submits the request to the server. To
see the updated totals, select the Refresh option at the top of the GUI. This
operation requires the background processor to be running.
5. You do not receive a warning about unsaved data when you Logoff or leave
the Web page. Unsaved changes are lost. Select Save or Run All
Transactions to ensure that all current changes have been submitted to the
Workforce Central database.
6. For debugging purposes, the GUIs XML Log window displays the XML
<Response> tags as they are received from the Workforce Central server.
You can toggle the Log display on/off with the Show/Hide XML Log button.
3-6
Kronos Incorporated
The following source code files constitute this sample API application:
!
API.js
Comment.js
Cookies.js
DateFormat.js
DropdownList.js
HyperFindQuery.js
PayCode.js
readme.htm
Recordset.js
timecardeditor.htm
Timesheet.js
Tooltip.js
Transactions.js
Of these files, the API.js file is of greatest interest in the context of this
programmers guide because it defines the reified JavaScript methods and objects
necessary to log on and off, and to pass the XML <Request> tag stream to the
Workforce Central API gateway.
3-7
Chapter 3
The GUI should look like:
3-8
Kronos Incorporated
This is the source code in the API.js file. Note that the values returned by this
application are not those returned by the XML code. For example, the login and
logout methods return true or false, depending on the Status retuned from the
XML.
Note: Substitute the actual superuser password used at your site for
<superuser password>.
/*
Copyright:Kronos, Inc. 2001
Description:
This file provides the basic methods and objects needed to
login, logout, and send xml requests to WFC v4.0 xml api
gateway.
Methods:
logon(username,password[,url])return true or false
logoff([url])
return true or false
execute(dom,url,action)return response dom if
Status="Success", else returns null
url
Object:
XMLHTTP([url])
send and receive xml streams from any given
XMLHTTP.send(xml)send the xml stream to the given url and

returns the response
Object:
Request([url][,dom][,parent])default dom is created with
Kronos_WFC/Request node path
Request.getAction()returns the action attribute value
Request.setAction(str)sets the action attribute value
Request.getObject()returns the contained node
Request.setObject(obj)sets the contained node
Request.getNode()returns the current dom
Request.execute([action][,obj]) returns the response node on
success otherwise null
Request.getResponse()returns the full response dom returned
from server after execute()
Request.onchange set this property to a function handler,
when the Request object
3-9
Chapter 3
changes, the function handler

will be invoked
Request.getDocumentElement()returns the documentElement
(i.e. top level node)
*/
// global variables
var jsessionid= ''
// constants
var SESSION_COOKIE= 'jsessionid'
var DEFAULT_URL= 'http://localhost/wfc/XmlService'
var DEFAULT_USER= 'superuser'
var DEFAULT_PSWD= '<superuser password>'
var ACTION_ATTR= 'Action'
var OBJECT_ATTR= 'Object'
var USERNAME_ATTR= 'UserName'
var PASSWORD_ATTR= 'Password'
var QUERY_NAME_ATTR= 'QueryName'
var RESPONSE_STATUS_ATTR= 'Status'
var RESPONSE_STATUS_SUCCESS = 'Success'
var DOCUMENT_ELEMENT_NAME= 'Kronos_WFC'
var REQUEST_NODE_NAME= 'Request'
var RESPONSE_NODE_NAME= 'Response'
var REQUEST_PATH= '//'+DOCUMENT_ELEMENT_NAME+'/'+REQUEST_NODE_NAME
var RESPONSE_PATH= '//'+DOCUMENT_ELEMENT_NAME+'/
'+RESPONSE_NODE_NAME
//send xml request and return xmlDom response
var XMLHTTP_count=0
function XMLHTTP(url){
this.id='XMLHTTP'+(++XMLHTTP_count)
this.url=(url)?url:DEFAULT_URL
this.method='POST'
this.contentType='text/xml'
this.send=XMLHTTP_send
this._init=XMLHTTP_init
this._http=new Object()
this.setSessionIdFromCookies=XMLHTTP_setSessionIdFromCookies
this.obj=this.id+'XMLHTTPObject'
eval(this.obj+'=this')
this._init()
}
3-10
Kronos Incorporated
function XMLHTTP_init(){
//Msxml2.XMLHTTP.3.0 //Microsoft.XMLHTTP
this._http=new ActiveXObject("msxml2.XMLHTTP")
this._http.open("POST", this.url, false)
this._http.setRequestHeader('Content-type', this.contentType)
//
//
//
//
//
//
//
//
//
normally this code is not needed, however, there is a known

bug that causes the XMLHTTP object to fail to send cookies.
this code seems to reduce the frequency of failure.
since WFC 4.0 xml api gateway uses cookies to maintain a
session id, it is impossible to get around this bug.
when Microsoft fixes this bug, it will require clients of
this code to upgrade their XMLHTTP. reference Microsoft
MSDN:// http://support.microsoft.com/support/kb/articles/
Q290/8/99.ASP if(jsessionid){
document.cookie=(SESSION_COOKIE+'='+jsessionid)
}
}
function XMLHTTP_send(xml){
//this._init()
try{
this._http.send(xml.xml)
}catch(e){
e.number = e.number & 0xFFFF
if(e.number == 5){
e.description = "Unable to find URL: "+this.url
}
throw e
}
// see note in init() method ...
this.setSessionIdFromCookies(this._http.getResponseHeader('SetCookie'))
return this._http.responseXML
}
function XMLHTTP_setSessionIdFromCookies(cookies){
if(cookies){
var startPos=cookies.indexOf('jsessionid')
if(startPos>=0){
startPos=cookies.indexOf('=')+1
var stopPos=cookies.indexOf(';',startPos)
jsessionid=cookies.substring(startPos,stopPos)
}
}
}
3-11
Chapter 3
// submit a given dom to a specified url

// return the response node on success
// if you need to know more about the error
// result, use the Request object
function execute(dom,url,action){
var root=dom.documentElement
if(action){
var node=root.selectSingleNode(REQUEST_PATH)
node.setAttribute(ACTION_ATTR, action)
}
var http=new XMLHTTP(url)
var responseDOM=http.send(root)
if(responseDOM==null){return null}
var responseNode=responseDOM.selectSingleNode(RESPONSE_PATH)
if(responseNode==null){return null}
var
success=(responseNode.getAttribute(RESPONSE_STATUS_ATTR)==RESPONSE
_STATUS_SUCCESS)
if(success){
return responseNode
}else{
return null
}
}
// LOGON method
function logon(username,password,url){
var request=new Request(null)
request.getNode().setAttribute(USERNAME_ATTR, username)
request.getNode().setAttribute(PASSWORD_ATTR, password)
request.getNode().setAttribute(ACTION_ATTR, 'LOGON')
request.getNode().setAttribute(OBJECT_ATTR, 'SYSTEM')
return(request.execute()!=null)
}
// LOGOFF method
function logoff(logoutDOM, url){
var request=new Request(null)
request.getNode().setAttribute(ACTION_ATTR, 'LOGOFF')
request.getNode().setAttribute(OBJECT_ATTR, 'SYSTEM')
return(request.execute()!=null)
}
/*
Copyright:Kronos, Inc. 2001
This code is generated. DO NOT Edit!
Request Description:
3-12
Kronos Incorporated
*/
var NODE_ELEMENT = 1
function __raiseevent(e){
eval(e)
if(this.parent){
this.parent._raiseevent(e)
}
}
var Request_count=0
function Request(url,dom,parent){
this._dom=dom
this.parent=parent
this.url=(url)?url:DEFAULT_URL
this.id='Request'+(++Request_count)
this.name=this.id
this.type=REQUEST_NODE_NAME
this.getNode=Request_getNode
this.getAction=Request_getAction
this.setAction=Request_setAction
this.getObject=Request_getObject
this.setObject=Request_setObject
this.getResponse=Request_getResponse
this.execute=Request_execute
this.onchange=new Function()
this.getDocumentElement=Request_getDocumentElement
this.obj='top.'+this.id+'RequestObject'
eval(this.obj+'=this')
}
Request.prototype._raiseevent=__raiseevent
function Request_getNode(){
if(this._dom==null){
var _newdoc=new ActiveXObject('msxml2.domdocument')
this._dom=_newdoc.createNode(NODE_ELEMENT, this.type, '')
if(this.parent){
this.parent.getNode().appendChild(this._dom)
this._documentElement=this.parent.getNode().documentElement
}else{
var doc=_newdoc.createNode(NODE_ELEMENT,
DOCUMENT_ELEMENT_NAME, '')
doc.setAttribute('Version', '1.0')
doc.appendChild(this._dom)
this._documentElement=doc
}
3-13
Chapter 3
}
return this._dom
}
function Request_execute(action,object){
if(action){this.setAction(action)}
if(object){this.setObject(object)}
var http=new XMLHTTP(this.url)
try {
this._response=http.send(this.getDocumentElement())
}catch(e){
log("Unable to send request. Possible reason:\nNumber:
"+e.number+"\nDescription: "+e.description)
}
if(this._response==null){return null}
var responseNode=this._response.selectSingleNode(RESPONSE_PATH)
if(responseNode==null){return null}
var
success=(responseNode.getAttribute(RESPONSE_STATUS_ATTR)==RESPONSE
_STATUS_SUCCESS)
if(success){
return responseNode
}else{
// use getResponse() to see the xml returned
return null
}
}
function Request_getResponse(){
return this._response
}
function Request_getDocumentElement(){
this.getNode() // insure we have a dom
return this._documentElement
}
function Request_getAction(){
return this.getNode().getAttribute(ACTION_ATTR)
}
function Request_setAction(vAction){
this.getNode().setAttribute(ACTION_ATTR, vAction)
this._raiseevent('this.onchange("'+ACTION_ATTR+'")')
}
function Request_getObject(){
return this.getNode().childNodes
}
3-14
Kronos Incorporated
function Request_setObject(vObject){
var _root = this.getNode().selectSingleNode('//'+this.type)
if(_root){
var _oldnode = _root.selectSingleNode('//'+this.type+'/
'+vObject.type)
if(_oldnode){
_root.removeChild(_oldnode)
}
}
this.getNode().appendChild((vObject.getNode)?vObject.getNode():vOb
ject)
3-15
Chapter 3
3-16
Kronos Incorporated
Appendix
Creating Portals and Third-party Web Sites
This appendix describes the set of Uniform Resource Locators (URLs) supplied
with the Workforce Central Developers Toolkit (DTK), and explains how to use
the initial set of URLs to:
!
Build the Workforce Central portals that enable users to interact with
individual Workforce Central components.
Enhance third-party Web sites by providing them with a means of launching

Workforce Central servlets.
instructional purposes only. The Extensible Markup Language (XML) tags and
URLs described herein are not guaranteed to be compatible with the XML tags
and URLs used by the Workforce Central server. In all circumstances relating to
the XML Application Program Interface (API), the XML tags defined in the
Workforce Central Developers Toolkit Reference Guide take precedence over
XML information in every other Workforce Central document.
This appendix is subject to alteration and expansion in subsequent revisions.
This appendix contains the following sections:
!
Overview
Understanding the URLs in the DTK
Logging On to the Server with the Logon URL
Creating a Sample Workforce Central Portal with URLs
Enhancing a Third-party Web Site with Workforce Central URLs
Appendix
Overview
This appendix introduces and describes the following Workforce Central URLs,
all of which share the same base href (http://localhost/wfc/
Public/Launch/) as indicated:
Appendix-2
http://localhost/wfc/Public/Launch/EventManager
http://localhost/wfc/Public/Launch/Hyperfind
http://localhost/wfc/Public/Launch/ImportAdministration
http://localhost/wfc/Public/Launch/LaborAccountSet
http://localhost/wfc/Public/Launch/MyReports
http://localhost/wfc/Public/Launch/PatternTemplate
http://localhost/wfc/Public/Launch/PeopleAdministration
http://localhost/wfc/Public/Launch/ReportCategory
http://localhost/wfc/Public/Launch/ReportSelection
http://localhost/wfc/Public/Launch/ReportSetup
http://localhost/wfc/Public/Launch/ScheduleIndividual
http://localhost/wfc/Public/Launch/ScheduleOutline
http://localhost/wfc/Public/Launch/SchedulePeriod
http://localhost/wfc/Public/Launch/SchedulePlanner
http://localhost/wfc/Public/Launch/ScheduleSnapshot
http://localhost/wfc/Public/Launch/ShiftCode
http://localhost/wfc/Public/Launch/Timecard
http://localhost/wfc/Public/Launch/Timestamp
http://localhost/wfc/Public/Launch/WorkforceGenie
http://localhost/wfc/Public/Launch/Workflow
Kronos Incorporated

The Workforce Central server is a Web-based server that runs in a Transmission
Control Protocol/Internet Protocol (TCP/IP) network. The following sequence of
events occurs when a user logs onto the Workforce Central server from a Web
browser:
1. The Workforce Central server displays a logon page. You enter a valid user ID
and password.
2. When the server authenticates your user ID and password, it establishes an
HTTP connection between the server and the users browser. This initiates a
session.
3. The Workforce Central system dynamically generates a set of HTML pages
known as the Workforce Central portal. The portal contains a frame for the
navigation bar and another frame in which the various services are presented.
The navigation bar continues to be available for the duration of the session.
When a navigation bar component is selected, the Workforce Central system
loads the appropriate service into the other frame.
Calling Servlets with URLs

In this example, the anchor tag specifies a URL named http://localhost/
wfc/Public/Launch/ServletOne, enclosing it in double quotation marks as
required:
<A HREF = "http://localhost/wfc/Public/Launch/
ServletOne">Click Here</A>
Note: The localhost parameter represents the name of the system on which
your Workforce Central server is installed.
In this example, the URL calls a fictitious servlet named ServletOne. A real
servlet would launch a corresponding applet with a similar name in the same
window of the users Web browser.
Appendix-3
Appendix
Specifying a New Launch Window

Adding the TARGET attribute to an HTML anchor tag allows you to specify a
window or frame in which the servlet will launch the applet. For example, the
following HTML anchor tag specifies that the applet corresponding to the
ServletOne servlet must be launched in a window named display:
<A HREF = "http://localhost/wfc/Public/Launch/ServletOne"
TARGET = "display"></A>
If no window or frame named display exists in the appropriate namespace, the

applet is launched in a new browser window.
To specify a string that appears in the browser window as a color-coded hot link (a
link that, when selected, calls the specified servlet to launch the applet), add the
unquoted string in the location occupied by the boldfaced string shown here:
<A HREF = "http://localhost/wfc/Public/Launch/ExampleOne"
TARGET = "display">Add String Here</A>
Note: Alternatively, you can use a Workforce Central URL to invoke a Workforce
Central servlet and launch its corresponding applet by setting the SRC attribute of
an HTML FRAME or IFRAME tag equal to the appropriate URL as shown:
<FRAME SRC = "http://localhost/wfc/Public/Launch/ServletOne">
(or)
<IFRAME SRC = "http://localhost/wfc/Public/Launch/ServletOne">
Appendix-4
Kronos Incorporated
Appending Query String Parameters to URLs

Some Workforce Central servlets require one or more query strings parameters to
launch their corresponding applets. Query string parameters are URL-encoded
name=value pairs. Their short names enable you to specify several constants (also
called keys) and date ranges in a single URL without exceeding the 256-character
limit.
The first pair of query string parameters in a URLin this example, a person
number (PID) equal to a value of 245must always be preceded by a single
appended question mark (?) as shown:
<A HREF = "http://localhost/wfc/Public/Launch/
ExampleOne?PID=245"
Additional query string parameters are appended to the URL using a single
ampersand (&) between pairs as a delimiter. For example, to append a timeframe
query string parameter whose name is tf to the previous URL, append an
ampersand followed by the timeframe name=value pair as shown:
<A HREF = "http://localhost/wfc/Public/launch/
ExampleOne?PID=245&tf=current+pay+period"
Appendix-5
Appendix
You can use the shortcut keys described in the following table in your query
strings to avoid exceeding the 256-character limitation.
Appendix-6
Key
Description
hf
Key for retrieving HyperFind ID
ha
Key indicating a HyperFind action
Value for a HyperFind action edit
Value for a HyperFind NEW action edit
Value for a HyperFind DUPLICATE action edit
qn
Value for a HyperFind query name
ts
Timestamp for a HyperFind query name
tf
Key for retrieving time frame for this applet. Add constants from next table
to specify exact pay periods and date ranges.
la
Indicates the applet that launched another applet
pid
Key for the first selected person number in the list of employees
fa
Key for the first selected labor account in the list of accounts
st
Indicates the time (generated system time) at which a selection was made
bd
Key for start date
ed
Key for end date
pemk
Key for retrieving the mode in which the people editor is launched
ap
Value for a people editor mode (Add Person)
dp
Value for a people editor mode (Duplicate Person)
Kronos Incorporated
To specify an exact pay period or date range, add keys from the following table to
the timeframe (tf) key described in the previous table.
Key
Description
Previous pay period
Current pay period
Next pay period
Previous schedule period
Current schedule period
Next schedule period
Week to date
Last week
Yesterday
Date range
10
Range of relative dates
11
Specified dates
-1
Separator ID
-2
Specified date range
-3
Specified range of relative dates
-4
Specified specific date
Appendix-7
Appendix

Before a portal can begin using any of the other Workforce Central URLs, it must
log on to the Workforce Central server.
Logging On Using the XmlService URL in an HTML Form

The XML <Request> code can be embedded in an HTML FORM and redirected
with the XmlService URL as shown here:
<HTML>
<BODY>
<FORM
action = "http://localhost/wfc/XmlService"
method = "POST>
<TEXTAREA rows=20 cols=100 id=KronosXML name=KronosXML>
<Request
Object = "System"
Action = "Logon"
/>
</Kronos_WFC>
</TEXTAREA><BR>
<INPUT type=submit value=Logon>
</FORM>
</BODY>
</HTML>
Appendix-8
Kronos Incorporated
Redirection and Error Handling

To redirect the logon of a Workforce Central-server-authenticated user, embed the
XmlService URL in an HTML form so that users can log in from a static Web
page rather than from a dynamically-constructed Workforce Central portal.
An Alternative Logon: Using the Logon Servlet

The following sequence of events establishes a valid session between the users
browser and the Workforce Central server:
1. The HTML anchor tag is coded as shown:
<A HREF="http://localhost/wfc/logon">Logon</A>
2. When the user selects the logon link, the Logon servlet is called. It creates
an HTML Logon form.
3. The user enters a valid username and password.
4. The HTML Logon form passes the username and password to the Workforce
Central server.
5. The Logon servlet attempts to authenticate the user.
6. If the user is authenticated, the Logon servlet establishes a Hypertext
Transmission Protocol (HTTP) connection and creates a session.
The Logon servlet returns the default portal page. You can redirect the Logon to
an alternate dynamically-created portal page or to a static Web page.
Appendix-9
Appendix

This section contains code samples that generate a sample Workforce Central
portal whose primary Web page is a three-frame window (the three frames are
named title, nav, and display).
The source code consists of HTML code with embedded JavaScript code as
required. In this sample, the code is stored in the following HTML files:
!
Body.html
Index.html
Logon.html
Nav.html
Title.html
Body.html Source Code File

The Body.html source code file is an untitled HTML file reserved for holding
data.
Index.html Source Code File

The Index.html source code file contains the following HTML code, which
specifies the name of each of the three frames that constitute the main page and
sets the frames location, relative size, appearance, behavior, and source of the
initial content to be displayed:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Chris's Portal</title>
</head>

<frameset rows="15%,*">
Appendix-10
Kronos Incorporated
<frame name="Title" src="Title.html" marginwidth="10"

marginheight="10" scrolling="auto" frameborder="0">
<frameset cols="20%,*">
<frame name="Nav" src="Nav.html" marginwidth="10"
<frame name="display" src="Body.html" marginwidth="10"
</frameset>
</frameset>
</html>
Logon.htm File
This file contains the HTML source code that submits the initial login request to
the Workforce Central server. Note that the actual superuser password at your site
should be substituted for <superuser password>.
<HTML>
<HEAD>
<META NAME="GENERATOR" Content="Microsoft Visual Studio 6.0">
<TITLE>Logon Page</TITLE>
</HEAD>
<BODY>
<P>
<div id="form1Div">
<form target="_top" action="http://localhost/wfc/portal"
id="LogonForm"
method="POST"
name="logonForm">
<table border="0" width="500">
<tr>
<td width="500"
colspan="2"
align="center"><span class="Heading">
Workforce Central 4.0</span></td>
</tr>
<tr>
<td width="500" colspan="2"> </td>
</tr>
<tr>
Appendix-11
Appendix
<td width="180"
align="right"
class="Label">
Username
</td>
<td width="320"
align="left">
<input value="SuperUser"
id="Username"
name="username"
maxLength="25"
size="27">
</td>
</tr>
<tr>
<td colspan="3"> </td>
</tr>
<tr>
<td width="180"
align="right"
class="Label">Password</td>
<td width="320"
align="left">
<input value="<superuser password>"
id="Password"
name="password"
type="password"
maxLength="25"
size="27">
</td>
</tr>
<tr>
<td width="180"> </td>
<td width="320"
align="left">
<input border="0"
id="LogonButton"
name="logonButton"
value="Log On"
type="submit">
</td>
</tr>
<tr>
<td width="500"
colspan="2"
align="center"
id="MessageCell">
</td>
Appendix-12
Kronos Incorporated
</tr>
</table>
</form>
</div>
</P>
</BODY>
</HTML>
Nav.html File
This file contains HTML code with JavaScript embedded in the HEAD tag:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
<html>
<head>
<title>Navigation Page</title>
<BASE HREF="http://localhost">
<SCRIPT LANGUAGE=javascript>
<!-var newWin = null
function CreateSession(){
var loading = true
newWin = window.open("logon.htm")
}
function goToTimecard(id){
//alert(id)
if(id!=-1){
parent.frames['display'].location= 'http://localhost/wfc/
timecard?pid='+id+'&tf=1'
}
}
function goToApplet(){
var radioValue = ""
for (var i = 0; i < document.timecard.rdoapp.length; i++) {
if (document.timecard.rdoapp[i].checked=="1") {
radioValue=document.timecard.rdoapp[i].value
}
}
'+radioValue+'?pid='+document.timecard.txtpid.value+'&tf=1'
}
Appendix-13
Appendix
function goToSchedule(id){
if(id!=-1){
scheduleindividuallaunch?pid='+id+'&tf=1'
}
}
function goToPersonInfo(id){
if(id!=-1){
employeeadminlaunch?la=quick&pid='+id+'&tf=1'
}
}
//-->
</SCRIPT>
</head>
<body>
<a href="javascript:CreateSession()"><B><I>Logon</I></B></a>
<font color="#008080">
<font face='ms comic sans'>
<a href="/wfc/summarylaunch/quick?viewId=1"
target="display"><I><B>Quick Find</B></I></a><br>
Look at a Timecard:<br>
<select
onchange='goToTimecard(this.options[this.selectedIndex].value)'
id=select1 name=select1>
<option value=-1 selected>Select a person
<option value=101>Adams, J A
<option value=106>Babson, M B
<option value=107>Billings, T C
<option value=221>Chin, Flo
<option value=219>Clarck, Frederic
<option value=108>Davis, R D
<option value=220>Diaz, Mercedes
<option value=214>Dolan, Bruce
</select><br>
Appendix-14
Kronos Incorporated
Get Personal Info:<br>

<select
onchange='goToPersonInfo(this.options[this.selectedIndex].value)'
</select><br>
<a href="/wfc/summarylaunch/mgr?viewId=6"
target="display"><I><B>Pay Period Close</B></I></a><br>
target="display"><I><B>Reconcile Timecard</B></I></a><br>
target="display"><I><B>Shift Start</B></I></a><br>
<a href="/wfc/scheduletabularlaunch?viewId=3"
target="display"><I><B>Schedule Planner</B></I></a><br>
<a href="/wfc/schedulegraphicallaunch?viewId=4"
target="display"><I><B>Schedule Snapshot</B></I></a><br>
<a href="/wfc/schedulesummarylaunch?viewId=5"
target="display"><I><B>Schedule Outline</B></I></a><br>
target="display"><I><B>IS Summary</B></I></a><br>
<a href="/wfc/summarylaunch/rollup?viewId=11"
target="display"><I><B>Test Rollup</B></I></a><br>
<br><br>
<form method="post" name="timecard"
onsubmit="javascript:goToApplet()">
<INPUT type="radio" name="rdoapp"
value="employeeadminlaunch">Person<br>
value="reportselectionlaunchservlet">Report<br>
value="Scheduleindividuallaunch">Schedule<br>
Appendix-15
Appendix
<INPUT type="radio" name="rdoapp" value="timecard"

checked>Timecard<br>
<input type="text" name="txtpid" maxLength="8" size="10">
<input type="image" height="21" width="21" border=0 value="Go"
name="Go" src="C:\work\MINE\gobutton.gif" align="absmiddle"
onclick="javascript:goToApplet()"> <br>
</form>
</font>
</font>
</body>
</html>
Title.html File
This HTML code specifies the font information and text string for the Title frame
of the portals initial page:
<html>
<head>
<title>Chris's Example</title>
</head>
<body>
<h1 align='center'><I><B>Chris's Portal Example</B></I></h1>
</font>
</font>
</body>
</html>
Sample Source Code for the Nav Frame

This HTML code contains JavaScript code embedded in the HEAD section that is
boldfaced for clarity:
Appendix-16
Kronos Incorporated

<html>
<head>
<title></title>
<BASE HREF="http://localhost">
<SCRIPT LANGUAGE=javascript>
<!-var newWin = null
function CreateSession(){
var loading = true
newWin = window.open("logon.htm")
}
function goToTimecard(id){
//alert(id)
if(id!=-1){
timecard?pid='+id+'&tf=1'
}
}
function goToApplet(){
var radioValue = ""
for (var i = 0; i < document.timecard.rdoapp.length; i++) {
if (document.timecard.rdoapp[i].checked=="1") {
radioValue=document.timecard.rdoapp[i].value
}
}
'+radioValue+'?pid='+document.timecard.txtpid.value+'&tf=1'
}
function goToSchedule(id){
if(id!=-1){
scheduleindividuallaunch?pid='+id+'&tf=1'
}
}
//wfc/scheduleindividuallaunch?la=quick&
Appendix-17
Appendix
function goToPersonInfo(id){
if(id!=-1){
employeeadminlaunch?la=quick&pid='+id+'&tf=1'
}
}
//-->
</SCRIPT>
</head>
<body>
<a href="javascript:CreateSession()"><B><I>Logon</I></B></a>
<a href="/wfc/summarylaunch/quick?viewId=1"
target="display"><I><B>Quick Find</B></I></a><br>
Look at a Timecard:<br>
<select
onchange='goToTimecard(this.options[this.selectedIndex].value)'
</select><br>
Get Personal Info:<br>
<select
onchange='goToPersonInfo(this.options[this.selectedIndex].value)'
Appendix-18
Kronos Incorporated
<option
<option
<option
<option
value=219>Clarck, Frederic
value=108>Davis, R D
value=220>Diaz, Mercedes
value=214>Dolan, Bruce
</select><br>
<!-<a href="/wfc/timecard?la=quick&pid=101&tf=1"
target="display">test</a><br>
<a href="javascript:goToTimecard(101)">test2</a><br>
-->
target="display"><I><B>Pay Period Close</B></I></a><br>
target="display"><I><B>Reconcile Timecard</B></I></a><br>
target="display"><I><B>Shift Start</B></I></a><br>
<a href="/wfc/scheduletabularlaunch?viewId=3"
target="display"><I><B>Schedule Planner</B></I></a><br>
<a href="/wfc/schedulegraphicallaunch?viewId=4"
target="display"><I><B>Schedule Snapshot</B></I></a><br>
<a href="/wfc/schedulesummarylaunch?viewId=5"
target="display"><I><B>Schedule Outline</B></I></a><br>
target="display"><I><B>IS Summary</B></I></a><br>
<a href="/wfc/summarylaunch/rollup?viewId=11"
target="display"><I><B>Test Rollup</B></I></a><br>
<br><br>
<form method="post" name="timecard"

onsubmit="javascript:goToApplet()">
value="employeeadminlaunch">Person<br>
value="reportselectionlaunchservlet">Report<br>
value="Scheduleindividuallaunch">Schedule<br>
<INPUT type="radio" name="rdoapp" value="timecard"
checked>Timecard<br>
<input type="text" name="txtpid" maxLength="8" size="10">
Appendix-19
Appendix
<input type="image" height="21" width="21" border=0 value="Go"

name="Go" src="C:\work\MINE\gobutton.gif" align="absmiddle"
onclick="javascript:goToApplet()"> <br>
</form>
</font>
</font>
</body>
</html>
Appendix-20
Kronos Incorporated
Enhancing a Third-party Web Site with Workforce Central URLs
Enhancing a Third-party Web Site with

Workforce Central URLs
Every Workforce Central URL that can be specified in a Workforce Central portal
can also be specified in the HTML source code of a third-party Web site. It is
possible to invoke the Workforce Central servlets that launch the Workforce
Central GUI applets that make it possible for users to log on to the Workforce
Central server from a third-party Web site and interact with the Workforce Central
functions.
Appendix-21
Appendix
Appendix-22
Kronos Incorporated
Index
A
Action attribute 1-3
AddOnly 1-20
Delete 1-19
Load 1-19
specification requirements 1-9
supporting persistence 1-19
syntax validation 1-13
Update 1-20
UpdateOnly 1-20
ampersand (&)
example of use as delimiter Appendix-5
API
application
transactions with server 1-10
objects 1-2
tag categories 1-3
B
batch processing
2-4
C
client application 1-2
client system, connecting to server 1-9
connecting to client system 1-9
context sensitive navigation controls 2-4
cookie 1-9
maintaining state example 2-12
preserving context and state using 1-9
reading and storing example

setting with Java 2-13
2-14
D
data structures, in data-only tags 1-4
database 1-2
Person table 1-5
Data-only tags 1-3
nesting inside Requests 1-16
date range
specifying in URL Appendix-5, Appendix-7
daylight savings 1-22
declaration tag 1-17
Document Object Model (DOM) 3-3
DOM
core API, purpose 2-3
Document Object
submitting as XML Request stream 2-3
dynamic selection lists 2-4
E
exception handling 2-4
Extensible Markup Language (XML)
description 1-1
disclaimer Appendix-1
G
graphical user interface (GUI)
GUI
example 3-8
1-2
Index
hot link, specifying a string as Appendix-4

HTML, SRC attribute Appendix-4
HTTP
connection
establishing Appendix-3
example 1-10
request 1-10
response 1-11
Hyperfind queries 1-4
pay period, specifying in URL Appendix-7

People tags 1-4
persistence
supported by tags 1-19
Person Number 1-5
portal
defined Appendix-3
generating an example Appendix-10
specifying in third-party Web
site Appendix-21
property
Datasource 1-18
LaborAccountName 1-13
obeying validation rules 1-13
PayCodeName 1-13
specing values as strings 1-13
WorkRuleName 1-13
Punch entry, inserting into server database,
example 2-5
J
Java language example 2-12
JavaScript
embedded in HTML Appendix-10
object 3-5
K
key
property 1-20
specifying Appendix-5
Known Issues in example 3-6
L
Labor tags 1-4
launch frame, specifying new Appendix-4
launch window, specifying new Appendix-4
levels of abstraction 2-2
Load Action attribute 1-19
Load attribute
Request tag 1-5
localhost parameter Appendix-3
N
namespace Appendix-4
nested tag 1-16
Index-2
Q
query string parameters
appending Appendix-5
defined Appendix-5
question mark (?), appending Appendix-5
quotation marks, enclosing URL Appendix-3
R
redirecting Appendix-8
reification, defined and described 2-3
reify, defined 3-3
Request
generic 1-15
specifying multiple 1-12, 1-13
Request code, embedding in HTML
form Appendix-8
Kronos Incorporated
Index
Request-Response cycle
comparative examples 2-12
examples 2-4
Response data, interpreting 3-2
Response tag, holding complex data
root tags 1-3
2-3
S
Schedule
entry in database 1-19
tags 1-6
server, described Appendix-3
server, establishing a session Appendix-9
server, logging on/off with URL Appendix-8
servlet, launching a corresponding
applet Appendix-3
session
closing gracefully 1-12
initiating Appendix-3
source code
example 3-9
examples, disclaimer Appendix-1
files, listed 3-7
syntax statement
of Target tag 1-9
T
tag
AccessAssignment 1-8
AccessProfile 1-4, 1-7
AccrualBalanceSummary 1-7
AccrualCode 1-7
AccrualProfile 1-7
AdhocLaborAccount 1-7
ApproveSignoff 1-7
BadgeAssignment 1-8
CancelDeductions 1-7
CustomData 1-8
CustomDate 1-8
Data-only 1-3
DateTotalSummary 1-7
EarnedAccrual 1-4, 1-7
EmailAddress 1-8
EmploymentStatus 1-8
Exception 1-7
ExpectedHours 1-8
highest level is document element
HistoricalPayCodeEdit 1-7
HistoricalPayCodeMove 1-7
Holiday 1-6
HomeAccount 1-8
HyperFindQuery 1-4, 1-7
HyperFindQueryResult 1-7
LaborAccount 1-4, 1-7
LaborLevelDefinition 1-4, 1-7
LaborLevelEntry 1-4, 1-7
Licences 1-8
MarkForTotalization 1-7
Naming 1-8
PasswordHistory 1-8
PayCodeEdit 1-6, 1-7
PayCodeMove 1-7
PeriodTotalSummary 1-7
Permission 1-7
Person 1-8
Personality 1-5, 1-8
PersonIdentity 1-5
PersonInformation 1-5, 1-8
PostalAddress 1-8
Punch 1-6, 1-7, 1-13, 2-5
Request 1-3
ResetAccrual 1-4, 1-7
Response
to Logon Request 1-19
Schedule 1-6, 1-7
example 1-19
ScheduleGroup 1-6, 1-7
ScheduleShift 1-7
ScheduleUnavailable 1-7
ShiftCode 1-7
1-17
Index-3
Index
ShiftSegment 1-7
Supervisor 1-8
Target 1-3
TelephoneNumber 1-8
Timesheet 1-7
User 1-5, 1-8
UserAccount 1-8
UserAccountLockout 1-8
UserAccountStatus 1-8
WorkedDuration 1-6, 1-7
WTKEmployee 1-5, 1-8
tags
combining with other languages 2-2
hierarchical order of 1-16
TARGET attribute, adding to HTML anchor
tag Appendix-4
Target tag 1-3
categories 1-4
specifying multiple tags in same
Request 1-15
time properties, descriptions 1-22
time zone 1-22
Timekeeping tags 1-6
Timesheet Editor API application, example 3-3
Totalizer, described 3-2
transaction 1-9
request-response 1-10
Transmission Control Protocol/Internet Protocol
(TCP/IP)
network 1-9
V
validation
rules 1-14
variables, binding to specified values
Visual Basic
code examples 2-15
comparing with Java 2-15
2-3
X
XML
API 1-2
API disclaimer Appendix-1
API tag 2-4
API tags, manipulating 2-12
character data 1-21
element 1-3
parser, using 2-3
Request stream, passing string as
response 1-2
streams, manipulating with other
languages 2-2
strings, storing in files 2-12
tag 1-2
2-2
U
Uniform Resource Locator (URL) Appendix-1
URL
calling servlets with Appendix-3
disclaimer Appendix-1
URLs, listed Appendix-2
user logon events Appendix-3
Index-4
Kronos Incorporated

WTK 50 Dtkprog

Diunggah oleh

Informasi Dokumen

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

WTK 50 Dtkprog

Diunggah oleh

Hak Cipta:

Format Tersedia

Workforce Central

A programmers guide to the XML API.

Kronos Workforce Central Suite Version 5

Document Part Number: 4703092-001

Workforce Central Version 5.0

About This Guide

Level Two Abstraction ............................................................................. 2-12

About This Guide

Who Should Read This Guide

Organization of This Guide

Abbreviations and Terms

Workforce Timekeeper Documents

About This Guide

Who Should Read This Guide

Windows NT/2000 operating system

Distributed client-server environments

High-level object-oriented languages such as Java, C++, Visual Basic, and

It is also assumed that these software professionals have significant prior

Tag-based markup languages such as Hypertext Markup Language (HTML)

Data transfer protocols such as Transmission Control Protocol/Internet

Request-response transactions and sessions

Static and dynamic transactions and sessions

Organization of This Guide

Organization of This Guide

Chapter 1, Understanding the XML API, describes the Extensible Markup

Chapter 3, Advanced Programming Topics, introduces and discusses

Each chapter is modular in structure and sequential in presentation. Each chapter

Workforce Central Developers Toolkit Programming Guide

About This Guide

General Text Formatting Conventions

General Text Formatting Conventions

Monospace text identifies code-level syntax statements, code examples,

Bold text identifies generic tag categories.

Bold italic text identifies code-level parameters that appear in syntax

Brackets ([ ]) surround optional expressions in syntax statements.

Workforce Central Developers Toolkit Programming Guide

About This Guide

A vertical pipe ( | ) delimits mutually-exclusive options in a syntax statement.

An asterisk (*) appended to an expression in a syntax statement indicates that

Comments in syntax statements are preceded by two forward slashes and

Abbreviations and Terms

Abbreviations and Terms

The following example demonstrates the use of both informal aliases:

Workforce Central Developers Toolkit Programming Guide

About This Guide

The following abbreviations and terms appear throughout this programmers

Application Program Interface

Document Type Definition

Graphical User Interface

Hypertext Markup Language

Hypertext Transfer Protocol

Hypertext Transfer Protocol Secure

Relational Database Management System

Transmission Control Protocol/Internet Protocol

Uniform Resource Locator

Extensible Markup Language

Workforce Timekeeper Documents

Workforce Timekeeper Documents

Workforce Timekeeper Installation Guide for Windows provides an overview

Workforce Timekeeper Installation Guide for UNIX describes how to install

Getting Started with Workforce TimekeeperA Guide for Managers explains

Getting Started with Workforce TimekeeperA Guide for Employees (Java

Getting Started with Workforce TimekeeperA Guide for Employees (HTML