Projects and Pages

Overview

Objectives

List the main parts of the Workday Extend infrastructure.
Create a new Workday Extend application in App Builder.
Use JSON to configure a PMD page.
Save a Workday Extend application to App Hub and deploy it to a Development tenant.
List the three metadata file types in a Workday Extend application.
Explain key widget attributes.
Add View and Edit PMD pages to a Workday Extend application.

Workday Extend

Build off the underlying Workday object and security model, by accessing your company's existing Workday data or by creating your own unique Workday business objects.
Use a variety of presentation widgets like buttons, calendars, or grids to quickly add user interface components that fit in with the Workday look and feel.
Trigger real-time, event-driven processes across Workday or other external systems.

Workday Extend Infrastructure

Each company has its own Workday Extend apps and its own Workday tenants.
An app can be deployed to one or more tenants.
Each tenant has its own unique alias

The
mealOrder_zrclrm
app is deployed to two tenants:
wdayedu_wcpdev1
and
wdayedu_wcpdev2
.
The
employeeEngagement_zrclrm
app is deployed to two tenants:
wdayedu_wcpdev2
and
wdayedu_wcpdev3
.

Tenant Aliases

Tenant aliases are automatically created when your tenant is initially created. The alias is a unique value for a specific developer tenant.

Dev Site tenant alias

Application Development Process

Build the feature in App Builder.
Save and deploy your app via App Hub.
Validate your changes in your Development tenant.

Using App Builder

Icon	Definition
Workday Icon App Builder menu, navigates to app overview page	Workday W Logo. Navigate to the Developer Site.
App builder components pane toggle	Components. Collapse and expand the components pane.
App Builder app search function	Find in App. Search for text within the files of your app.
App Builder keyboard shortcuts	Keyboard Shortcuts. Show a list of App Builder keyboard shortcuts.
App Builder user profile information	User Menu. Show user information, company details, and link to Feedback category of the Developer Forum.
App Builder quick links menu	Related Actions. Show quick links to App Overview, Developer Forum, Documentation, and the Graph, REST, and SOAP API Explorers.

App Preview

App Preview allows you to render a page without deploying your app to the tenant. You can visualize quick UI changes and decrease development time.

In this image, the PMD for the home page is displayed on the left. On the right, the App Preview menu item is selected and a rendering of the page is visible. This rendering is using mock data.

Selecting App Preview expands a pane that renders your selected PMD without deploying your app or changes to your tenant.

If the PMD relies on inbound or outbound endpoints, you can use the Manage Data Connection icon (it looks like a database) to connect App Builder to your tenant to render data, or you can configure and use mock data.

Important

: When App Preview connects to a tenant, the app is actually completing all inbound and outbound API calls defined on your PMD. Take care when updating data, because your updates will affect the data in your tenant and other connected systems.

App Builder data source, connected to the tenant

Icon	Definition
	App Preview. Only available when viewing a PMD page. Open the current page in App Preview.
	Manage Data Connection. Only available in App Preview. Choose a tenant to display tenant data in App Preview, or disconnect to use mock data.
App Builder Data source connected to the tenant	Indicates that App Preview is using tenant data, from tenant alias eduwday_wcpdev2 .
App Builder data source connected to mock data	Indicates that App Preview is not connected to a tenant and instead is using mock data.

Mock Data

Mock data enables you to:

Quickly test logic and very dynamic scenarios using realistic sample JSON responses without having to change the source code.
Protect against changing data in your tenant or in external systems.

Mock data sample response

Note

: In this course, you will mainly connect App Preview to your assigned tenant.

To learn more about Mock Data, refer to the Developer Documentation: Mock Data.

App Hub

Developer collaboration.
Version and build management.
App deployment, promotion, and installation.

The source code layer. This layer provides read and update operations pertaining to app source code.
The build pipeline layer. This layer translates app source code to app artifacts. Workday environments can then consume these artifacts when you deploy or install your app.
The artifact storage layer. This layer holds the artifacts generated as the result of a successful build.

Deploying Your App

Deployment Flow: Dev Environment

Once you are ready to deploy your app to your tenant, select the Save and Deploy button. You will be prompted to select a tenant. During class, ensure that you select your assigned tenant from the drop-down list.

App Builder, select a tenant to deploy app

Deployment Security

In order to deploy your app, you need access to the following domain security policy: Manage: App Manager.

In your assigned Development tenant for class, Logan should already have the correct permissions. However, in your company's tenant, you may need to request access to this domain.

Security domain report, showing securable actions

Application Lifecycle

From the Apps page of the Developer Site, you can view a list of all of the apps you have saved to App Hub. You can also view all the apps that others in your company have saved to App Hub.

Apps That Have Been Pushed to App Hub

App promotion is managed on the Developer Site. Navigate to the App Overview page, then go to the Promotions tab.

There are four phases all apps should go through during development:

Build: Create an app that brings your idea to life.
Test: Test your app and its configurations.
Verify: Verify that your app works in a production-like environment.
Release: Release your app to production.

Each stage of the lifecycle corresponds to the promotion level of your app and the Workday environment in which you can run the app. Each completed cycle results in a new version of the app that you can run in your production environment.

When you upload source code to App Hub, App Hub compiles the code into a build that you can promote. You promote Workday Extend apps through these promotion levels. Each promotion level corresponds to the runtime environment of the tenant on which you can deploy or install your app. You can take different actions for each promotion level:

Promotion Level	Description
Development	When you build an app, you deploy your code to a WCP Development tenant. You can update and deploy your code continuously on the Development tenant to iteratively develop your app. Note : In this course, you will only deploy to a Development tenant.
Implementation Release	Promote your app to Implementation Release to install, configure, and test the app on Implementation or Implementation Preview tenants. When you promote an app to Implementation Release, you: Promote the most recent passing build of the latest Development version of your app to Implementation Release. Replace the existing Implementation Release version of the app, if one exists.
Sandbox Release	Promote your app to Sandbox Release to install, configure, and test the app on Sandbox or Sandbox Preview tenants. When you promote an app to Sandbox Release, you: Promote the latest Implementation Release version of your app to Sandbox Release. Replace the existing Sandbox Release version of the app, if one exists. Because Sandbox and Sandbox Preview tenants are refreshed every week with production data, this is a best practice to ensure that there are no issues with your code.
Production Release	When you promote your app to Production Release, your Company Administrator can install and configure the app on Production tenants.

Reminder

: Once you install an app on an Implementation, Sandbox, or Production tenant, you are no longer able to remove the app from that tenant.

JavaScript Object Notation (JSON)

{
  "employees": [
    {
      "firstName": "Logan",
      "lastName": "McNeil"
    },
    {
      "firstName": "Aesha",
      "lastName": "Pillay"
    },
    {
      "firstName": "David",
      "lastName": "Martinez"
    }
  ]
}

App Components

Presentation components: user interface and page interactions (e.g., widgets, endpoints, page flows, custom errors)
Model components: data (e.g., business objects, business processes, attachment objects, security domains, tasks, reports)
Orchestration components: real-time, event-driven processes (e.g., create/update Workday data, trigger business processes, send notifications, connect to third-party APIs)

Presentation Components Overview

Widgets built on the Workday look and feel, with customizable attributes, dynamic data bindings, and event handlers.
Endpoints that access data using Workday and third-party REST APIs.
Flows for page navigation.
Custom error pages.
Pods containing common widgets across the app.
Translated content on titles, labels, and values.

Comparing Workday to Presentation Components

Managing session state
Harmonizing or transforming data

File Structures

AMD

Each app will have one AMD, or

A

pplication

M

eta

D

ata file. AMDs contain application-level arrays, objects, and properties.

Key Elements in an AMD

App Properties

The

appProperties

array contains custom properties that you define. These properties can then be referenced in your PMD code. Each property defined in

appProperties

is an object containing a key value pair.

Sample appProperties

Flow Definitions

The

flowDefinitions

array contains

flowSteps

and

transitions

that allow you to conditionally route the user to the appropriate pages in the app. Flows are discussed in greater detail in a later chapter.

Tasks

The

tasks

array contains a task for each page that is added to your app. This array becomes an index containing every page in your app. Initially, your app AMD will only have one task in the array. This task is a pointer to your home page, or

home.pmd

.

Initial Tasks Array

When you create a new PMD, the wizard asks you for the name of the page, App Builder will automatically create an associated task in the AMD

Creating a New Page Results in a New Task Being Created

Without the task, you could not access your pages. Tasks are also referenced in

button

widgets and

flowSteps

.

One option to navigate between pages is to create a

button

widget. The

button

has a

taskId

attribute that will identify which page the user will be directed to when the

button

is selected. This

taskId

attribute is defined in the AMD task array and references a specific PMD or page in your app.

Coding a Button to Navigate to the New Page

applicationID

The

applicationId

property contains the name you provided when you created the project. This value can be referenced in your PMD code.

Data Providers

The

dataProviders

array contains objects that list the base URLs for each REST API that your app will call. The objects in the

dataProviders

array contain a key- value pair. These keys will be referenced in your PMD code, specifically in the

endPoints

and

outboundEndPoints

arrays.

Sample dataProviders Array

AMD Documentation

The developer site has documentation on all AMD components and attributes. You can find this information by searching for "App Metadata" on the Workday Developer Site.

SMD

SMD stands for

S

ite

M

eta

D

ata. SMDs contain site-level arrays, objects, and properties.

Basic SMD File

Site and Application IDs

The

siteId

property gets its value when you create the project. The SMD links to the AMD via the

applicationId

property.

Key	Definition
applicationId	A unique identifier for the app. Can be referenced from the PMD using <% site.applicationId %> .
siteId	A unique identifier of the site within the app. Can be referenced from the PMD using <% site.siteId %> .

SMD Titles Array

The

titles

array of the SMD contains the application title. Presentation Components displays the title on all the page headers and on the browser tab. You can have multiple titles, each with a localized title for a specific language.

SMD titles Array

A PMD can also contain a

title

object. It is important to note that the PMD

title

object does not override the

titles

array in the SMD.

PMD title Object

Languages

The languages array resides in the SMD. The languages array contains a nested object with code and description attributes. This is used for label translation and date and time display on the date widget. The code key uses the ISO language code.

Languages Array

SMD SiteAuth

The SMD contains a JSON array named

authTypes

. In that array, you can specify any of the following authentication schemes:

NoAuth
SSO
OAuth2
OAUTH_CLIENT_CREDENTIAL
AWSV4
WCPISU

Declare all authentication types used in your app here.

All apps default to Single Sign On (SSO). SSO uses the credentials of the authenticated user. If you are only using Workday APIs to create your app, SSO is the only auth type you need.

In a PMD, you will see endpoints that reference the auth types by their

id

. These

authTypes

allow Presentation Components to attach the correct headers to your endpoint request.

An authType in the SMD Being Used by the endPoint in a PMD

You can also specify

NoAuth

as the

authType

on an endpoint, even though it is not explicitly defined in the

authTypes

array.

SMD Documentation

Important

: The Developer site has documentation on all SMD components and attributes

PMD

Presentation Components pages are created by writing markup. Workday calls the markup presentation metadata, or PMD. You create a PMD document using JSON.

A page, or PMD, contains the following key components:

Endpoints, which represent page data (inbound and outbound)
Widgets, which define how you will present data to the user
PMD Scripting

Overall PMD Structure

Note

: The term tags refers to the JSON elements you put into a PMD. So, a tag is a design-time element. Widgets refers to the control you see on the page at runtime. For example, if you add a

text

tag in your PMD, at runtime you will see a

text

widget.

PMD Documentation

The developer site has documentation on all PMD components and attributes. Search "PMD" on the Developer site for a full list of attributes and components as well as PMD best practices.

PMD Presentation Tag

Its own attributes, like
horizontal
or
sorted
.
A
children
array, where you define the widgets that appear on the page.

Basic Page Widgets

Display	Code
	{ "type": "text", "label": "Hello World!", "value": "Welcome to Workday!" }
	{ "type": "instanceList", "label": "Projects", "values": "<% projectsData.data %>", "displayKey": "descriptor", "multiSelect": true }
	{ "type": "date", "value": "2018-04-30", "helpText": "Select the employee's hire date." }
	{ "type": "button", "label": "My Button", "taskReference": { "type": "taskReference", "taskId": "root" } }
	{ "type": "checkBox", "label": "Active?" }
	{ "type": "currency", "label": "Salary", "useDefaultCurrencyFormat": "true", "maximumValue": "10000000.00", "currencyCode": "USD", "value": "100.00" }
	{ "type": "dropdown", "label": "Dropdown", "values": "<% projectsData.data %>", "displayKey": "descriptor" }
	{ "type": "image", "imageUri": "https://cdn.workday.com/blogs/uploads/2015/03/wday_logo_dub_circle_600x600.png" }
	{ "type": "labeledImage", "charm": "FACEBOOK" }
	{ "type": "textArea", "label": "Memo" }
	{ "type": "fileUploader", "label": "Upload Files", "singular": "<% true %>", "valueOutBinding": "fileSubmit" }

readOnlyText
hidden
richText

Introduction to PMD Scripting

PMD scripting allows you to build more interactive pages. PMD scripting uses a Java-based expression language that makes your apps event driven.

You can write scripts to:

Manipulate data on a page.
Set widget properties dynamically.
Invoke an endpoint to fetch data only when needed.

To indicate a PMD script, wrap the script's contents between

<%

and

%>

tags. The code snippet below includes two PMD scripts: one that calculates today's date for the Los Angeles timezone, and one that calls a function called

calculateByDate

(which is defined elsewhere in the file).

Date scripting example

PMD scripts can be executed as the user interacts with the page. You can use PMD scripting in certain attributes, including:

onChange
onLoad
onRowSelect
onSend
onSubmit

Reminder

: Not all objects support the same interactions. Make sure you reference the documentation to verify what is supported where.

Scripts can be defined at the following levels:

Page level using the script tag.
App level by creating script modules.

For more information about PMD scripting, refer to the "Concept: PMD Scripting" and "Reference: PMD Scripting Syntax" articles on the Developer Documentation site.

Page Types

View Page

View pages render widgets that display read-only data. You can define values from an inbound data source during page load, but you cannot dynamically set values from another widget on a view page.

Important

: View pages do not have default page navigation buttons.

App Builder view only page

Edit Page

Edit pages render editable widgets that users can select or enter data.

Edit pages are enabled when the PMD contains

outboundData

, or the

presentation

tag contains the

"pageType": "edit"

key-value pair.

By default, the

enabled

attribute is set to true for all widgets on edit pages, and you are able to dynamically set widget values from a data source, function, or other widget.

Default navigation buttons are included in edit pages: OK and Cancel.

Button	Action
OK	Submits all outbound endpoints with data entered in the widgets and navigates user to another page
Cancel	Does not submit any outbound endpoints, and navigates to the previous page.

App Builder pageType: edit

Confirmation Page

Confirmation pages are configured by adding a

"pageType": "confirm"

to the presentation tag.

Confirmation pages render widgets that display read-only data. The enabled attribute of all tags on a confirmation page is always false.

Like an edit page has default navigation buttons, so does a confirmation page. The Done button will navigate you the previous page. Or, if used in a flow, the Done button will take you back to the back that the flow started on.

App Builder pageType:confirm