Dayforce Web Services Configuration

Guide
Dayforce Release 2023.2.0
This document contains confidential and proprietary information of Ceridian HCM, Inc.
(“Ceridian”) or its affiliates and is intended only for the person(s) to whom it is transmitted by
Ceridian. Any reproduction of this document, in whole or in part, or the divulgence of any of the
information without the prior written consent of Ceridian is prohibited. Ceridian reserves any and
all rights in the information contained in this document. Neither Ceridian nor any of its affiliates
shall in any circumstances be held liable for any damages howsoever caused by reliance on
information contained herein.

Ceridian, Dayforce, the respective logos, and Makes Work Life Better are either trademarks or
registered trademarks of Ceridian or its affiliates in the United States and/or other countries.

All other brand and product names referenced herein are the trademarks or registered trademarks
of their respective holder.

Release Version: 2023.2.0

Document Version: Rev 1
Publication Date: 8/11/2023
Table of Contents

About This Guide 5

Run a Keyword Search 5
Additional Resources 6

Getting Started 7

Acceptable Use of Dayforce Web Services 9

Web Services Configuration Guide Overview 11

Configuration Guidelines 11

Web Services Development Planning 12

Determine Your Requirements 12
Configure a Test Instance 12
Assess Your Security Requirements 12
Configure Your Firewall to Allow Traffic from Dayforce Web Services 13
Develop Your External Projects to Access Dayforce Web Services 13
Design and Develop a Test Application to Consume Dayforce Web Services on a Non-
Production Instance 13
Configure and Deploy the Application to Your Production Environment 14

Configure Dayforce Web Services 15

Before You Begin 15
Standard Configuration Steps (Required) 16
1. Create a Common Password Policy for all Consumers 16
2. Create a Primary Role for Each Consumer 16
3. Configure Access to Web Services Features for Each Consumer’s Role 17
4. Create a User Account for Each Consumer 20
5. Configure IP Address Filtering (Optional) 20
Get Employees Request Security Configuration 20
Email Notifications 21
Two-Layer Security Mechanism 21
Configure the Access Authorizations for Each Consumer’s Role 21
Configure Field-Level Data Access for Each Consumer’s Role 21
POST/PATCH Employees Request Security Configuration 23

Page 3 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 Configuration Required for Get Report Requests 23
1. Create Specific Topics Designed for Web Services 24
2. Create Specific Report Definitions for Each Consumer’s Role 24
3. Add the Report Definitions to Each Consumer’s Role 25
4. Add the Access Authorizations Based on the Allowed Report Definitions 25
5. Verify the Report Configuration Using Web Services Explorer 25
Create Subscriptions for Each Subscriber 26
Configuration Required for Notifications 28
Configure Each Notification Receiver Service as a Subscriber 28
Workflow for Use With Workflow Notifications 29
Configuration Required for RESTful Retrieving Employee Documents 30

The Notification Status Feature for Troubleshooting 32

Notification Status Screen Overview 32
Using the Notification Status Screen in Conjunction with Error Emails 34
Retrieve Notification Details Manually 35

Page 4 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
About This Guide

This guide is intended for administrators who need to configure Dayforce to support using web
services. It explains how to configure your Dayforce instance for Dayforce web services
application programming interface (API) use.

Note: The content of some of the new or updated features in this release might not yet be
localized for French or for the other languages supported in Dayforce. Translation efforts for this
content are ongoing. Also, because Dayforce is highly customizable, some of the features and
options discussed in this guide might not be visible when you access Dayforce. If this occurs,
please contact your organization's Dayforce administrator for more information.

Run a Keyword Search

You can search for words or phrases in this guide by pressing Ctrl+F or Command+F. This opens
a search field where you can type the text that you want to find. The field looks like this in Acrobat
Reader:

Type a word or phrase and press the Enter key to go to the closest match in the document. You
can keep pressing the Enter key to move through each instance.

Note: Search is not case sensitive, but it finds only exact word or phrase matches. If you don’t find
a term (for example, policy), try a variation of the word (for example, policies). This lets you find
instances of the word or phrase in headings or within a paragraph.

For example, say you want to learn more about the Favorites button of Dayforce. To do this, type
favorites in the search field. Then, press the Enter key to move to the closest instance of the
word "favorites" in the document.

Page 5 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Additional Resources
It is recommended that you read the Dayforce Web Services Introduction Guide before beginning
a development project. It contains important information about using Dayforce web services,
including acceptable use, request parameters, design considerations and limitations.

The entire documentation set is available at help.dayforce.com.

To register on the Dayforce Help Portal:

1. On the Dayforce Help Portal login page, click Sign Up (it's in the top right corner).
2. Enter your name and email address, and choose a password.
3. Click Sign Up.
4. Select the Remember me checkbox to bypass the login page in the future.

You can also access help directly in Dayforce by clicking the help icon in the toolbar.

Page 6 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Getting Started

Dayforce doesn’t charge for the use of web services, but does offer a number of resources, such
as guides and sample applications, with the expectation that you will use these resources as a
starting point for development and as reference guides throughout your development process.
Dayforce also offers premium customized web services development services at an additional
cost.

Before starting a web services development project, ensure that you have the necessary
resources (based on your current version of Dayforce).

Resources for the Dayforce Web Services

Resource Description
The Dayforce Developer Network is a website for developers who want
to design and program data integration. On the Dayforce Developer
Dayforce Developer Network, you can download web services documentation and sample
Network apps, and browse and try the different web service calls that are
offered. See "Dayforce Developer Network" in the Dayforce Web Ser-
vices Introduction Guide.
This guide provides a description and the suggested use of each of the
Dayforce Web Ser-
Dayforce web services methods. Read this first to determine which
vices Introduction
methods are the best fit for your development needs and to ensure your
Guide
design falls within the acceptable usage guidelines.
Dayforce Web Ser-
This guide provides step-by-step instructions for configuring Dayforce
vices Configuration
to support the web services methods that you will be using.
Guide
Dayforce RESTful Web This guide describes in detail how to add RESTful web services to .NET
Services Developer and Java development projects. The examples provided in the doc-
Guide umentation are available as working sample applications.
This Excel file lists the data elements that are available in some of the
Data Elements Avail-
RESTful web services requests. It contains important information about
able in RESTful Web
the data elements, including the access authorizations that the con-
Services
sumer must have to access them.
Dayforce SOAP Web This guide describes in detail how to add SOAP web services to .NET
Services Developer and Java development projects. The examples provided in the doc-
Guide umentation are available as working sample applications.
Dayforce Web Ser- This guide provides a detailed breakdown of the Employee object, and
vices SOAP API Docu- it should be used as a reference for locating specific data elements
mentation within the results returned by a Get Employee method.

Page 7 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Resources for the Dayforce Web Services
Resource Description
This document lists the data elements that are available in SOAP Get
Data Elements Avail-
Employee web services requests. It contains important information
able in SOAP Get
about the data elements, including the access authorizations that the
Employee Requests
consumer must have to access them.
With each release, Dayforce creates SOAP and RESTful sample
applications for both of our supported development platforms (.NET
Sample Applications
and Java). With simple tweaks (described in the ReadMe.txt files
for Dayforce SOAP or
within the development projects), the sample application can work with
RESTful Web Services
your Dayforce instance, providing a demonstration of web services
coding and displaying meaningful data.

To find these resources:

1. Go to https://support.dayforce.com and log in.
2. Click the Support Downloads link.
3. In the Admin & User Guides section, click More.
4. Download the Dayforce Web Services Docs ZIP file that corresponds to your current
release.

Page 8 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Acceptable Use of Dayforce Web
Services

Before you begin: To ensure that you have the best experience when using Dayforce web
services, Ceridian HCM, Inc. expects you to adhere to the acceptable use guidelines when
designing your consuming applications and using Dayforce web services.

To ensure the best experience for all clients using web services, Ceridian HCM, Inc expects
clients to adhere to the following guidelines when designing their consuming applications and
using Dayforce web services. Ceridian HCM, Inc. reserves the right to charge for overages or
interrupt service if a client’s use of the web services features deviates from these guidelines.

Dayforce doesn't charge for the use of web services, provided the following conditions are met:
l You use the available documentation, sample applications, and tools to develop your applic-
ation without the engagement of Dayforce resources; and
l Your consuming application adheres to the following standards for acceptable use:
o Consuming applications should be designed for system-to-system integration and

not to directly populate a user interface or a mobile app.

o The number of records retrieved should be optimized using a changes since the pre-

vious request approach. This also applies to the design of the reports used with Get
Report requests.
o Get Employee requests shouldn't return more than 1,000 employees per request.

See the table Frequency of web services calls based on request type, immediately fol-
lowing this list.
o Get Report requests shouldn't return more than 1,000 rows per request.
o You should use web services development frameworks that can handle additions to

existing response objects without interrupting web services processing in production

applications. Examples of such frameworks include Microsoft .NET and Java with the
Apache CXF framework.

Frequency of web services calls based on request type

Calls to be made no more frequently
Description of request
than
SOAP GetEmployeeXRefCodes - Requests for employ-
Every 15 minutes
ees who were updated within a specific timeframe
SOAP GetEmployeeXRefCodes - Requests other than
Every 2 minutes
for updated employees

Page 9 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Frequency of web services calls based on request type
Calls to be made no more frequently
Description of request
than
SOAP GetReport, OpenReportPages, and CloseRe-
Every 15 Minutes
portPages
RESTful requests for employees who were updated within
Every 5 minutes
a specific timeframe
All other requests No restrictions

Important: Dayforce reserves the right to charge for overages and, or, to interrupt service if your
use of Dayforce web services deviates from these guidelines.

As Dayforce continues to enhance our web services offerings, new data entities and or elements
might be added to existing response objects. Dayforce doesn't consider the addition of new data
entities and, or, elements to be a break in backward-compatibility.

When selecting your development frameworks, be sure that they support these types of additions
without causing failures in your existing consuming applications. Though you might choose to use
other frameworks, doing so might result in production web services applications returning errors
and possibly failing to operate.

Page 10 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Web Services Configuration Guide
Overview

Note: This guide only describes the product’s configuration requirements. It assumes that you
already reviewed the information in the Dayforce Web Services Introduction Guide, which
provides a description of current Dayforce Web Services features.

Moreover, developers who will create code to interact with the Dayforce Web Services API should
see the Dayforce RESTful Web Services Developer Guide.

The following topics are covered in the Dayforce Web Services Configuration Guide:
l Web Services Development Planning (see page 12)
l Configure Dayforce Web Services (see page 15)
l Configure Dayforce Web Services (see page 15)

Note on terminology: The term "consumer" is used throughout this guide to refer to any external
application that a client builds to use the Dayforce Web Services API. While reviewing this
content, keep in mind that one client might have multiple consumers, and one consumer could be
used by more than one of the client's systems.

Configuration Guidelines
In order to ensure that access to features and data is not compromised by configuration changes
made for web services and vice-versa, you should observe the following guidelines:
l User accounts, roles, report definitions, etc., used for web services should be configured
specifically for use with a given consumer. This means that existing items shouldn't be
reconfigured to support web services, and, once created, web services items shouldn't be
attached to existing roles.
l Separate user accounts, roles, etc., should be configured for each web services consumer,
allowing a greater amount of flexibility as our features and client use of web services
become more complex.

Page 11 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Web Services Development Planning

Before you begin: It’s recommended that you have a client administrator user role or work with a
user with that role type. The following process steps assume that you have with a client
administrator user role.

After you have these resources locally available, you can begin planning and developing.

Determine Your Requirements

Review the Dayforce Web Services Introduction Guide to learn about the available web services
features and their acceptable usage guidelines. Consult with your developers to help determine
the web services methods that you want to use.

Configure a Test Instance

Configure a test instance of Dayforce to work with the web services methods you decided on in
the first step.

Assess Your Security Requirements

Use the Web Services Explorer to ensure compliance with data security guidelines and to
understand the web services methods your organization will use.

Before you begin: Don’t access Dayforce web services from an external application until this
step is complete, because it guarantees configuration problems won’t interfere with the expected
results.

For RESTful services, use a web browser, or you can use the Postman app with Google Chrome.

Important: Be advised that Dayforce doesn’t provide support for third party applications such as
Google Chrome or the Postman app.

For SOAP services, go to HCM Anywhere > Web Services > Explorer to use the Web Services
Explorer feature to perform the following steps:

Page 12 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 1. Confirm that data is secure before you provide developers with the credentials created for
web services.
2. Get a more thorough understanding of the web services methods your organization might
use. The Web Services Explorer feature provides actual data from the Dayforce instance. It
also provides code snippets in both .NET and Java, so your developers can see exactly
how requests are made based on the inputs provided. An administrator might need to
provide some assistance with understanding the data or building reports in Dayforce and
making them available to web services.

Configure Your Firewall to Allow Traffic from

Dayforce Web Services
If your firewall is configured to block traffic to external IP addresses, you need to add Dayforce IP
addresses to the allowlist in order to use web services successfully. These addresses are listed in
the Dayforce IP Allowlist document.

Develop Your External Projects to Access

Dayforce Web Services
After you confirm the security configuration and you understand which web services methods to
use, your organization can begin developing external projects to access Dayforce web services.
Your developers should use the provided sample application that corresponds with the
development platform (.NET or Java) that they will use to build their web services-consuming
application.

The ReadMe.txt file in the sample application describes the minimal changes necessary to
make the application work with your instance of Dayforce. Developers should run the configured
sample application in debug mode to trace its actions and view results at each critical step. This
process ensures that the developers have a thorough understanding of the Dayforce web
services model by providing a hands-on approach for walking through working code.

Design and Develop a Test Application to

Consume Dayforce Web Services on a Non-
Production Instance
First, design the application that will consume Dayforce web services. Ensure that your design
accounts for data storage, data formatting, error trapping, and processing logs as required by your
organization’s planned use.

Next, develop the web services consuming application using a non-production instance of
Dayforce.

Page 13 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Finally, test the web services application using a non-production instance of Dayforce, verifying
data using the Web Services Explorer for SOAP services or using Postman for Restful services,
and other Dayforce UIs as needed.

Configure and Deploy the Application to Your

Production Environment
Repeat the final web services configurations in the production instance of Dayforce.

Test the production configurations using the same tools used to verify configurations in the test
instance.

Finally, redirect and redeploy the web services application for production use.

Page 14 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Configure Dayforce Web
Services

The following is a general process flow for configuring Dayforce web services:
l Before You Begin (see page 15)
l Standard Configuration Steps (Required) (see page 16)
l Get Employees Request Security Configuration (see page 20)
l Configuration Required for Notifications (see page 28)
l Configure Each Notification Receiver Service as a Subscriber (see page 28)
l Create Subscriptions for Each Subscriber (see page 26)
l Configuration Required for Get Report Requests (see page 23)
l Workflow for Use With Workflow Notifications (see page 29)
l Configuration Required for RESTful Retrieving Employee Documents (see page 30)

Before You Begin

To configure Dayforce for web services use:
1. Identify the web services consumers that need to be set up.
2. Determine which web services features each consumer will use.
3. Identify the data elements required by each consumer.

Identify Consumers
A good process for identifying web services consumers (defined above) is to:
1. List all of the client systems that will receive or retrieve data from Dayforce.
2. For each system identified in step 1, note the application that will be used to interact with
Dayforce Web Services. This will likely be a new client application built (or existing applic-
ation updated) specifically for Dayforce integration.
3. The list of applications noted in step 2 are the consumers requiring configuration in Day-
force.

Determine Which Features to Use

See the Dayforce Web Services Introduction Guide for a description of each available Dayforce
Web Services feature and information about each feature’s intended use.

Identify Required Data Elements

Page 15 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
If any Dayforce web services other than Get Report Data requests are used by a consumer,
the consumer must have field-level access defined. To determine which fields a consumer
requires, all systems that the consumer interacts with should be considered, and the cumulative
list of data elements will likely be what is required for the consumer

For a complete list of fields available for field-level access configuration, see the “Appendix – Data
Elements Available in Get Employee Requests”. It is helpful to note both the field name and the
associated access authorization given that both aspects need to be configured.

Standard Configuration Steps (Required)

There are a number of configuration steps that you must complete to use Dayforce Web Services.
Because these steps involve system security and feature access, they must be completed by a
user who has the Client Admin role.

Important: The following procedures are required for all uses of Dayforce Web Services. For
more details about how to perform each step, see the Dayforce Implementation Guide.

To use Dayforce Web Services, you must:

1. Create a Common Password Policy for all Consumers.
2. Create a Primary Role for Each Consumer.
3. Configure Access to Web Services Features for Each Consumer’s Role.
4. Create a User Account for Each Consumer.
5. Configure IP Address Filtering (Optional).

1. Create a Common Password Policy for all

Consumers
To avoid issues with expired passwords, create a password policy that has non-expiring, complex
passwords. This policy can be applied to all roles created for web services consumers, but note
that it must not be marked as the default password policy.

2. Create a Primary Role for Each Consumer

l Each web services user account should have its own primary role in Dayforce.
l Only one role should be assigned to the user account for the consumer because the
account’s web services permissions are derived solely from the role marked as Primary. An
existing role should never be used for web services, because changes to the role for other
users might result in data becoming available in web services features for the consumer
when it has not been authorized, and vice versa.
l For security purposes, roles with access to web services shouldn't be allowed to access
Dayforce UIs. This type of configuration prevents people with access to the consumer’s cre-

Page 16 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 dentials from accessing or adding features, access authorizations, data elements, or
reports without authorization.

Important: Add the password policy created in the first section to each new role as it's created.

3. Configure Access to Web Services Features

for Each Consumer’s Role
The primary role assigned to a consumer’s account must have access to the appropriate web
services role features for that consumer’s authentication to be successful. You can configure role
access in the Features tab of System Admin > Roles, under HCM Anywhere > Web Services.

User roles that are used by web services consumers must be assigned the HCM Anywhere and
Web Services role features. Additionally, one or more of the following features must be assigned,
depending on which operations the consumer performs:
l Delete Payroll Elections: Grants the ability to delete payroll elections data using the
PATCH method in the Payroll Election API. The user role also needs to be assigned the
Patch/ Post Payroll Elections role feature to delete data using the PATCH method. Also
see Patch/Post Payroll Elections.
l Delete Payroll Time Data: Grants the ability to delete imported time and attendance data
using the PATCH method in the Payroll Time Data Import API. The user role also needs to
be assigned the Payroll Time Data API - Delete Imported Data access authorization in
the Authorizations tab in System Admin > Roles to delete the imported data.
l Explorer: Enables HCM Anywhere > Web Services > Explorer, which is a feature in Day-
force where you can learn about the operations available in the SOAP API. In Explorer,
you can test the instance’s web services security configuration, retrieve sample code, and
troubleshoot client-side applications.
l Notification Status: Enables HCM Anywhere > Web Services > Notification Status,
which is a feature in Dayforce where administrators can view the status of SOAP noti-
fications for their subscribers and reset any that are in the Max Retry Reached state.
l Notification Subscriptions: Enables HCM Anywhere > Web Services > Notification
Subscriptions, which is a feature in Dayforce where administrators can create and man-
age SOAP notifications and subscriptions.
l Patch/Post Candidate and Job Application Sourcing: Enables web services consuming
applications to insert and update candidate job applications that include questionnaires.
l Patch/Post Candidate Assessment Data: Allows the role to be used when integrating
with assessment service providers.
l Patch/Post Candidate Screening: Enables web services consuming applications to insert
and update background screening data in Recruiting using the RESTful POST and PATCH
operations.
Note: This role feature should be assigned to the role used for the integration user. You
don't have to assign it to any other user role in Dayforce.
l Patch/Post Client Payroll Country: Enables web services to retrieve, add, or update the
list of countries for Dayforce and ConnectedPay to configure pay groups.

Page 17 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
l Patch/Post Configuration Data: This role feature and its two sub-features, Organization
Setup and OrgUnits, must all be selected to enable web services consuming applications
to insert and update org unit data using the POST and PATCH operations.
l Patch/Post Employee Balance Transaction: Enables web services consuming applic-
ations to insert and update employee balance transactions using the RESTful POST and
PATCH operations.
l Patch/Post Employee HR Data: Enables web services consuming applications to insert
and update employee HR data using the RESTful POST and PATCH operations.
l Patch/Post Employee Schedules: Enables web services consuming applications to insert
and update employee schedules using the RESTful POST and PATCH operations.
l Patch/Post Employee Time Off: Enables web services consuming applications to insert
and update time away from work using the RESTful POST and PATCH operations.
l Patch/Post HireRight Candidate Screening: Enables web services consuming applic-
ations to insert and update HireRight background screening data in Recruiting using the
RESTful POST and PATCH operations.
Note: This role feature should be assigned to the HireRight Integration System Role. You
don't have to assign it to any other user role in Dayforce
l Patch/Post Labor Metrics Code: Enables web services consuming applications to insert
and update labor metric codes using the RESTful POST and PATCH operations.
l Patch/Post Labor Metrics Type: Enables web services consuming applications to insert
and update labor metric types using the RESTful POST and PATCH operations.
l Patch/Post Pay Adjustment: Enables web services consuming applications to insert and
update employee pay adjustments using the RESTful POST and PATCH operations.
l Patch/Post Payroll Elections: Enables web services consuming applications to insert and
update employee payroll elections using the RESTful POST and PATCH operations. Also
see Delete Payroll Elections.
l Patch/Post Payroll Quick Entry: Enables web services to add or update payroll quick
entries for employees in the Quick Entry tab in Payroll > Pay Run Management.
l Patch/Post Projects: Enables web services consuming applications to insert and update
projects data using the RESTful POST and PATCH operations.
l Patch/Post/Delete Labor Validation: Enables web services consuming applications to
insert, update, and delete labor validation policy rules using the RESTful POST, PATCH, and
DELETE operations.
l Patch/Post/Delete Legacy Labor Metric: Enables web services consuming applications
to insert, update, and delete legacy labor metrics using the RESTful POST, PATCH, and
DELETE operations
l Post Employee Availability: Enables web services consuming applications to insert
employee availability records using the RESTful POST operation.
l Post Document Import: Allows the role to use the Documents Import API to import file
metadata using the RESTful POST operation.
l Post Employee Raw Punch: Enables web services consuming applications to insert
employee raw punches using the RESTful POST operation.
l Post Right To Work Data: Enables web services consuming applications to insert can-
didate right to work survey data in Recruiting using the RESTful POST operation.

Page 18 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 l PutWorkflowValidationAction: Enables the external validation node in the workflow con-
figuration to allow web services consuming applications to use the GET Employee request
to retrieve the minimum employee HR information required by local payroll systems (or “in-
country providers”) for validations, to indicate when external review and action is required
for payroll changes.
l Read Data: Controls the ability to retrieve data from Dayforce using SOAP and RESTful
GET requests. The ability to retrieve specific response types is controlled separately using
the settings in the Web Services Field-Level Access tab in System Admin > Roles.

To assign web services access to a role:

1. Go to System Admin > Roles.
2. In the Features tab, select the web services role that you are configuring.
3. Locate and expand HCM Anywhere, then expand Web Services.
4. Select HCM Anywhere, Web Services, and each of the sub-features as necessary.
5. Click Save, then click Refresh.

Workflow Validation Feature

Dayforce offers the ability to use web services notifications as a vehicle for validating and taking
action on workflow transactions. If you have very complex data validation requirements, you can
create applications that ensure that your unique business needs are accounted for prior to data
being committed to the database. This process is triggered using a new External Validation
workflow configuration object. When a transaction reaches this object in the process flow,
Dayforce creates a Workflow Notification event that can either be pushed to a client-hosted
receiver service or that can be retrieved by a Get Notifications request.

To avoid confusion, the External Validation workflow configuration object is not available in the
Workflow Manager screen by default.

You must add the feature specifically. If you plan on using the web services Workflow Validation
process, you must specifically add the feature to a role by taking the following steps:
1. Go to System Admin > Roles.
2. Select the role that you’re adding the feature to.
3. Locate and expand Workflow Administration > Workflow Designer.
4. Select the External Validation Admin role feature.
5. Click Save, then click Refresh.

You must select the Workflow Administration > Workflow Designer > External Validation
Admin feature in for the object to be available in the workflow configuration area.

Note: Consider giving this role access to the Home > Welcome feature. Adding this feature
provides a consistent starting point for the user account if it's used to log in to Dayforce directly.

Page 19 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
4. Create a User Account for Each Consumer
Consumers must always authenticate with Dayforce to retrieve detailed information from the
application.

As with UI users (users of the application via the user interface), an account must be established
for each consumer using web services features. This allows Dayforce to properly track a given
consumer’s usage and activities and allows Dayforce to properly secure data for ongoing use as
well as to meet the general security audit requirements of most clients.

Configure Location Access for Each Consumer’s User

Account
A consumer’s access to employee information is controlled by the org locations attached to their
user account. Only the employees in the allowed locations are included in web services
interactions.

5. Configure IP Address Filtering (Optional)

You can restrict the IP addresses and ranges that can originate web service requests. This is an
optional level of security that you can apply by creating Dayforce service entries in System
Admin > IP Network Filtering.

See “Restrict Dayforce Web Services by IP Address” in the Dayforce Implementation Guide.

Get Employees Request Security

Configuration
The Get Employees request (and its derivatives) is controlled by the common configuration
described in Standard Configuration Steps (Required) on page 16. Additionally, a two-layer
data security mechanism has been implemented for these requests because access
authorizations (the first layer) handle security based on groupings of information, and it's very
likely that some data elements included in a given grouping shouldn't be included in the results of
a Get Employees request. For that reason, a second layer of data security has been added.

The second layer of data security for Get Employees requests is field-level access, which controls
availability at the individual data elements level (no groupings) using a Can Read setting similar to
access authorizations.

Page 20 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Email Notifications
Consumers receiving Event Notifications need to use Get Employees requests to act on the
received notifications. Therefore, consumers using the following requests must be configured as
noted in this section:
l Get Employees Request
l Get Employee XRefCodes Request
l Get Employees By XRefCode Request
l DF Notification Data Request (used to retrieve detailed information for a particular Noti-
fication Event)

Two-Layer Security Mechanism

The employee object (results set) returned by the Get Employees request always uses the
same structure; that is, it contains the same data entities and elements. However, the two-layer
security mechanism determines which data elements are populated with values when the
response is returned to the consumer.

When the request is processed, access authorizations are applied in the first step and only the
allowed values are included. In the second step, field-level access is applied, resulting in the
population of the final employee object. All entities and fields are available to the consumer, but
only those allowed by this two-layer security process will have resulting values.

Configure the Access Authorizations for Each

Consumer’s Role
For the consumer’s role, select Read access for the access authorizations used by the required
data elements.

Note: When you apply access authorization changes to a role, system caching can result in a wait
time of up to one minute to become available in the web services feature. This is the same
caching function that impacts reporting and other parts of the Dayforce application.

Configure Field-Level Data Access for Each

Consumer’s Role
Field-level access must be configured for each role used by a consumer to control the specific
data elements that are populated when that consumer requests data. This field-level data access
is configured in the Web Services Field-Level Access tab of System Admin > Roles.

To access the Web Services Field-Level Access tab:

Page 21 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 1. Log in to Dayforce as an administrator that has access to the web services features.
2. Go to System Admin > Roles and click the Web Services Field-Level Access tab.

The Web Services Field-Level Access tab provides a hierarchical view of the web services
response types separated by the type of service (RESTful Services and SOAP Services) and
the data entities and elements available within each. In order for the response object to return
populated data for a given data element, the element must be selected (enabled) for the primary
role of the user account being used by web services.

The DFNotificationEvent item controls access to the fields that are available in the Notification
object, and it must be configured for applications using the DFNotificationsRequest to query for
unacknowledged notifications. This normally applies to notification subscribers that are
configured for Event Detection Only, and it usually doesn't apply to subscribers configured for
notification receiver services.

The Documents item controls access to the documents attached to the employees, which are
returned in the response for Get a List of Employee Documents and Get Document
Details. Document retrieval is only available in the RESTful Services. Select the checkbox next
to each data element that should be populated for these requests.

The Workforce Management item controls access to workforce management data such as
availability, punches, schedules, and time away from work.

The Employee item controls access to the fields that are available in the Employee Object, which
is the response for Get Employee and Get Employees By XRefCode requests. Select the
checkbox next to each data element that should be populated for these requests.

Each of the subordinate employee HR data endpoints has a corresponding field-level role feature.
For more information about the subordinate endpoints, see “RESTful Retrieving Employee HR
Data” in the Dayforce Web Services Introduction Guide.

The EmployeeTimeAwayFromWork item controls access to the calendar of scheduled time

away from work periods for the employee.

The EmployeePunch item controls access to employee worked shift timesheet data.

Note: Top parent items (such as Employee or Document) are automatically selected if any of their
child items are selected. All child items can be selected or cleared by clicking the name of the
parent item. In order for a child item to be included in the results, the parent item must be selected.

The GetEmployeeXRefCodesResponse item controls access to the fields that are available in
the GetEmployeeXRefCodesResponse Object, which is specific to the Get Employee
XRefCodes requests. If this request type will be used by the consumer, select the checkbox next
to the GetEmployeeXRefCodesResponse item to ensure all of the values in the response are
populated.

Access to the Employee response object for RESTful requests is separate from the access to the
SOAP Employee response object for the following reasons:

Page 22 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 l For security considerations, Dayforce cannot assume that a client means to allow access to
the information from two different styles of requests; and
l the response objects aren't identical.

POST/PATCH Employees Request Security

Configuration
Posting a new hire requires the web services user role to be able to assign the relevant role to the
new hire record. The relevant role must be assigned to the web service user role in System
Admin > Roles, in the New Hire Role Assignments tab.

Patching existing employee roles also requires these roles to be assigned to the web service user
role in System Admin > Roles, in the New Hire Role Assignments tab.

For example, if a consuming application needs to post employees assigned to “Canadian

Associate” or “Canadian Manager” roles, or to assign existing employees to these roles, they
need to be assigned to the Web Services role:

Configuration Required for Get Report

Requests
Get Report Requests are designed to return the raw report data from reports that are based on
Data & Analytics > Reporting > Reports. If a consumer uses Get Report requests, then
additional configuration, as described in the following process flow, is required:

Page 23 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 1. Create Specific Topic Designed for Web Services.
2. Create Specific Report Definitions for each Consumer’s Role
3. Add the Report Definitions to Each Consumer’s Role
4. Add the Access Authorizations Based on the Allowed Report Definitions
5. Verify the Report Configuration Using Web Services Explorer

1. Create Specific Topics Designed for Web

Services
To keep your web service calls operating, it can be helpful to create specific topics for web service
calls. These topics should only contain the tables and parameters that are needed for the calls.

2. Create Specific Report Definitions for Each

Consumer’s Role
Important: The field-level data security layer used by Get Employees requests doesn't apply to
Get Report requests.

Report security, along with the configuration of data elements in the report definition, controls the
information that is ultimately available to the consumer. As such, only the required data elements
should be included in the report definitions used by web services.

Moreover, given that the data elements allowed from one consumer to another varies, it's best
practice to keep the report definitions separate, allowing for ongoing changes for one consumer
without affecting others.

Report data filtering is controlled in the report definition, and this is another important reason for
creating separate report definitions for each consumer. Reports with parameters and some user
defined fields can be included in reports used by web services in version 7.47 and later; however,
report definitions containing advanced formatting will not be usable by web services.

One of the most important aspects of designing reports for use with web services is ensuring the
report returns an optimized set of data. Instead of returning large result sets, such as a full list of
employees, the report definition should include only changed details since the previous
successful Get Report request. The best way to accomplish this is to use a datetime report
parameter that will be populated by the Get Report request and compared to the last modified
time or start date of the records included in the report. Additional information for report parameters
can be found in the Ad Hoc Reporting Guide.

Page 24 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
2.1 Add an XRefCode to the Report Definitions
Created for Each Consumer
The XRefCode field is available in the Report Properties UI only when a user has (temporary)
Web Services feature access attached to their role.

Important: Get Report requests use XRefCode as request parameter that identifies the report
definition to run, and only report definitions that have an XRefCode value, defined in the Report
Integration Name field, will be available to this web services feature.

Additionally, report definitions that include advanced formatting aren't available for use with web
services requests. The Advanced Formatting flag
(ReportDefinition.AdvancedFormatting = 1) will be set if there is any column total or
summary total setup in the Totals window.

3. Add the Report Definitions to Each

Consumer’s Role
Update the role for each consumer (using Get Report requests) to include the report definitions
that were configured in the previous step.

4. Add the Access Authorizations Based on the

Allowed Report Definitions
When Get Report requests are processed, the reporting engine assembles and secures the data
based on access authorization settings. The Role of the requesting web services User Account
must have Read access to the data elements in order for the values to be populated and sent
downstream. The process for configuring access authorizations for Get Report requests is the
same as the process used for configuring access to the data when reports are generated through
the Reporting feature.

5. Verify the Report Configuration Using Web

Services Explorer
To ensure that configured report definitions are accessible via web services, it's strongly
recommended that you use the web services explorer. In addition to the other functionality
available on the web services explorer, you can use the Get Report Definitions button to retrieve
all available reports.

Go to HCM Anywhere > Web Services > Explorer.

Page 25 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
For the purposes of using the GetReportDefinitions request for this topic, it's important to
note that reports are comprised of two basic elements: a report topic and a report definition.

Reports will be included in the results if ALL of the following conditions apply:
l The report topic can be found in, or built using, Reporting > Report Designer > Dataset
Builder. Not all report topics available to the application are necessarily available to web
services.
l The report definition is defined in Data & Analytics > Reporting > Reports using one of
the report topics available in Reporting > Report Designer > Dataset Builder. These
reports are marked as V2 in the Topic Type column.
l The report has an XRefCode, which you can set in the Report Integration Name field in
the Properties dialog box when you create or edit a report definition in Data & Analytics
> Reporting > Reports.
l The report definition doesn't have any column total nor summary total set up in the Totals
dialog box when you create or edit a report definition in Data & Analytics > Reporting >
Reports.
l The report definition is available to the web services user's primary role, which you can spe-
cify in the Properties dialog box when you create or edit a report definition in Data
& Analytics > Reporting > Reports.

After you configure the report definition, you can go to HCM Anywhere > Web Services >
Explorer and use the Web Services Explorer and search for any available report definitions by
entering the user name and password for the web services user with access to the report
definitions and clicking Get Report Definitions. If you include an XRefCode, only the report
definition with that specific Report Integration Name will be returned. If no report definitions are
returned, verify that all of the prerequisites listed above have been fulfilled.

Note: For each report definition parameter, the explorer limits the number of available values to
250. For Get Report, the Explorer limits the results to 1,000. These limitations only apply to the
Explorer and don't apply when the call is performed outside of this tool.

Create Subscriptions for Each Subscriber

Dayforce contains a list of Notification Events (including Hire, Rehire, Termination, Workflow
Validation, and their associated Cancel events).

The combination of Notification Events and Subscribers are called Subscriptions. As of version
7.47, consumers receiving notifications should have subscriptions for all events to ensure they're
notified of data changes properly.

Cancel Events

It's up to the consumer to decide whether they take action based on a given Event Type. This is
important to note because Dayforce Notifications include Cancel events that alert the consumer if
a transaction has been reversed.

Page 26 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
For example, if a New Hire occurs, the Dayforce notification publisher sends a notification to the
consumer. If that Hire is then deleted or terminated as a way of canceling it with Dayforce, the
Dayforce notification publisher sends another transaction to notify the consumer of this change. In
this scenario, both Hire Cancel and Termination can be considered cancel events for the Hire
event, and as such, both must have Subscriptions.

Configuration

Subscriptions appear in the data grid in the lower panel of the UI, however they're not added or
edited within the grid.

When you click New or click an existing subscription record, the Subscription dialog box opens,
which you can use to create a grouping of events. The subscription must have a name, a start
date, and at least one event. As noted above, in version 7.47, it's best practice to include all
events in the subscription.

Important: As changes are made in each field of the Subscription dialog box, they're reflected in
the Subscriptions feature. The information is committed to the database when you click Save.
Some fields aren't enabled in the Subscription dialog box after the subscription is saved. This is
because the Notification Publisher might have previously or might be currently processing the
notifications for the subscription based on the existing configuration.

Page 27 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Configuration Required for Notifications
To use the Dayforce Notification web services, clients need to create a Notification Receiver
service and use it to receive and acknowledge notifications pushed from Dayforce. A Notification
Receiver is another example of a web services consumer (a client might have multiple
consumers). In this case, these consumers are the Notification Receiver services.

To configure Dayforce to push event notifications to receivers, go to HCM Anywhere > Web
Services > Notification Subscriptions and do the following:
1. Configure Each Notification Receiver Service as a Subscriber (see page 28)
2. Create Subscriptions for Each Subscriber (see page 26)

Configure Each Notification Receiver

Service as a Subscriber
The subscriber configuration in Dayforce contains the information that defines the Notification
Receiver service, which acknowledges events when they're sent to a web services consumer.
The interface that you use

To configure a notification receiver service as a subscriber:

1. Go to HCM Anywhere > Web Services > Notification Subscriptions.
2. In the toolstrip, click New.
3. Complete the following details:
l Subscriber Name: The name of the application that processes notification event

data. This field is required for all subscriber types.

l Reference Code: A short code used to uniquely identify the subscriber. This value is

required for all subscriber types and is used by applications that query for unac-
knowledged notifications (in lieu of a receiver service). This field is required for all sub-
scriber types.
l Event Detection Only: Select the checkbox to indicate Yes, or clear it to indicate

No. This identifies subscribers that query for unacknowledged notifications (in lieu of
a receiver service). For this type of subscriber, the value should be set to Yes.
l Service URL: The web address of the notification receiver service if one is being

used. This field is required when Event Detection Only is cleared.

l User Name: The name of the receiver service account the Dayforce Notification Pub-

lisher uses to authenticate with it. This field is optional, though Dayforce strongly

Page 28 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
 recommends that external parties use authentication as a means of securing their
receiver services. This field is not used when Event Detection Only is selected.
l Password: The password associated with the receiver service account the Dayforce

Notification Publisher uses for authentication. Using authentication credentials in the

receiver service is optional, though Dayforce strongly recommends that external
parties use authentication as a means of securing their receiver services. This field is
not used when Event Detection Only is selected.
l Max Retry Attempts: The maximum number of attempts that can be made to push a

notification to a notification receiver service. When the threshold is reached, the Day-
force Notification Publisher sends an error message to the configured Alert Email
Address advising of the difficulties encountered. This field is required when Event
Detection Only is cleared.
l Max Retry Minutes: The maximum number of minutes allowed to pass after the ini-

tial send attempt time. When the threshold has been reached, the Dayforce Noti-
fication Publisher sends an error message to the configured alert email address
advising them of the problem. This field is required when Event Detection Only is
cleared.
l Alert Email: The email address the Dayforce Notification Publisher uses to send

messages when a notification event for a given subscriber reaches an error state
(Max Retry Attempts or Minutes is reached). This field is required when Event
Detection Only is cleared.
4. Click Save, then click Refresh.

Workflow for Use With Workflow

Notifications
The Workflow Validation and Workflow Validation Cancel events are created by the Dayforce
workflow engine based on the workflow configuration. The External Validation node must be
made available via feature security (described earlier in this guide) for it to appear in Workflow
Administration > Workflow Designer.

The External Validation should be used only once in a given workflow configuration, and if any
client workflow configurations contain the External Validation node, at least one notification
subscriber must have currently-effective subscriptions for both the Workflow Validation and
Workflow Validation Cancel events. If the workflow engine is unable to find a subscriber with
currently-effective subscriptions to the Workflow Validation and Workflow Validation Cancel
events, an error is returned and the transaction processing stops.

The External Validation node is closely related to the Decision node in that it’s designed to allow
the client to configure the possible outcomes.

Page 29 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Unlike the Decision node, the External Validation node doesn't require and shouldn't have a
preceding Routing node, given that an external system retrieves the data in the workflow
transaction and performs automated validation. The External Validation node can have any
combination of the following actions:
l Approve
l Approve with Warnings
l Reject
l Timeout

The actions (Message Responses) attached to the External Validation node determine the
actions that are available in the Put Workflow Validation Action operation.

The workflow configuration should be set up so that, when a transaction is rejected, it's directed to
a user who understands the message provided by the external application and can take the
appropriate action.

Workflow configurations can be designed so that process directs the transaction to the External
Validation node multiple times. As an example, a transaction flows to the External Validation node
where it's rejected, a client administrator then resubmits the transaction and as a result, the
transaction arrives at the External Validation node a second time. Each time a transaction arrives
at the External Validation node, a new Workflow Validation event is created so the external
application knows it can retrieve the most recent data.

Configuration Required for RESTful

Retrieving Employee Documents
Using RESTful Web Services, consumer applications can retrieve documents attached to
employees. The primary roles defined for the web services application users (Available Roles)
must have access to the relevant document types added (Roles), as illustrated in the following
screenshot. Each document type represents a type of employee data the document is associated
to (for example, marriage certificate or contact details).

Because Read access is typically all that is needed to retrieve the data, you need only select that
option, as shown here:

Page 30 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
To configure access to the different document types:
1. Go to Documents > Admin > Document Types.
2. For each document type the consumer application needs access to, do the following:
a. Select the document type in the Document Type list.
b. In the Available Roles column, choose the relevant primary roles attached to the
consumer application user and move them to the Roles column using the arrow
icons.
c. Check the selected roles' access rights to the document type and select the accesses
required. As a rule, only Read access is needed to retrieve the document.
3. Click Save, then click Refresh.

Page 31 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
The Notification Status Feature for
Troubleshooting

The Notification Status feature is available under HCM Anywhere > Web Services. This feature
should be enabled for the Client Administrator role and any roles used as the primary role for a
web services notification processing application.

Notification Status Screen Overview

The Notification Status feature is designed to assist users in the following ways:
l Helping users research the statuses of subscribers as well as specific notification events.
l Indicating items that are in a pending or error status.
l Enabling users to reset notifications that are in an error status.
l By working in conjunction with error alert emails sent by the Dayforce Notification Publisher
to provide focus for notifications that might need to be addressed manually or to be reset.

When a user navigates to this feature for the first time, the filter section opens and no data
appears in the data grid. Rather than waiting for data to load, the feature expects the user to
provide filter information and click Apply to load data that is relevant to the user’s current needs.

When the user supplies the necessary filter criteria and clicks Apply Filter, the data grid is
refreshed with the requested data.

Page 32 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Yellow indicators in the left-most column indicate notifications that are currently in a
Pending/Incomplete status.
l When the Dayforce Notification Publisher encounters a preceding notification that is in an
error state (Max Retry Attempts or Minutes has been reached), it stops attempting to send
notifications to the notification receiver. This behavior is designed to ensure the notification
receiver processes events in the order of occurrence and, when this happens, events that
are detected after the errored event are held until the block event is reset.
l Yellow indicator is used in conjunction with a Reset icon in the Send Attempts column to
indicate the record has been Reset and is currently in a pending status (awaiting action by
the Dayforce Notification Publisher or the notification receiver service).
l Yellow Indicators are also used for events for Event Detection Only subscribers that haven't
been acknowledged.
l Red indicators in the left-most column indicate notifications that are in an error state. This
occurs only with subscribers using receiver services.
l Notifications that have been successfully acknowledged won't have an indicator visible in
the left-most column.

The ID column displays the Notification Event ID for the given record. This number will appear to
be duplicated across records for clients with multiple subscribers with subscriptions to the same
event types. This is because the record displayed in the data grid is based on the combination of
Notification ID and Subscriber.

Note: Notification events are detected only once and assigned a notification ID, though multiple
subscribers might be configured to receive a notification for it.

Page 33 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
The lower panel of the feature provides the log information for each attempt the Dayforce
Notification Publisher has made to push the notification to the subscriber’s receiver service. This
information is shown based on the selected record in the upper data grid. When a notification is
successfully acknowledged, the record in the lower grid shows the sent and response times, and
no error message is shown.

The Notification Status feature allows the user to reset a notification selected in the upper grid if
it's currently in an error state (max retry attempts or minutes has been reached). The reset
process clears the Send Attempts column and adds an icon to show that the item was reset. It
also clears the First Attempt Time information. Both pieces of information are removed so the
Dayforce Notification Publisher doesn't detect a max retry attempts or minutes error. The log
information in the lower panel isn't removed. When the record is reset, a Yellow indicator icon will
appear in the left-most column.

Using the Notification Status Screen in

Conjunction with Error Emails
When a notification for a given subscriber reaches an error state, the Dayforce Notification
Publisher sends an email to the email address configured for the subscriber.

The email provides a link to Dayforce that directs the user to the error notification record. When
the link is clicked, the following sequence of events takes place:
1. A browser window opens and shows the Dayforce login screen.
2. The user must authenticate with Dayforce.
3. If the user has multiple roles available, the user must select a role that has access to the
Notification Status feature.
4. The Notification Status feature loads.
a. The filter criteria appears with the notification ID, subscriber, and appropriate date
range.
b. The upper data grid displays the error record.

Page 34 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.
Retrieve Notification Details Manually
If it's necessary to manually retrieve the data for a given notification, the Web Services Explorer
feature can be used. The user’s role must have access to this feature and to the Dayforce web
services credentials (user name and password used by the application processing the given
notification). The Get Notifications and Get Notification Data tabs in Explorer can be used to
retrieve the data.

Page 35 of 35
Copyright © 2023 Ceridian HCM, Inc. All Rights Reserved.