Workday Integration

​

0. At a Glance

• Connector: Workday LMS External Content Provider
• Supported Write Resources: Content (upsert), Completions (push), Categories (list/get)
• Integration Direction: Bidirectional (content push, completion tracking)
• Partnership Requirements: Standard Workday tenant access required
• Key Behaviours:
  • Auto-completes content when users launch from Workday UI
  • Uses both external_reference and title for content deduplication
  • Requires base64 encoded cover images
• Key Quirks:
  • Auto-creates enrollments and completions, causing potential discrepancies
  • Content categorization may show as internal even for external providers
  • Rate limited to 5-10 requests per second

​

1. Integration Overview

​

1.1 What This Connector Does

​

1.2 System UI Overview (Video)

​

1.3 High-Level Data Flow

​

2. Requirements & Prerequisites

​

2.1 Partnership / Commercial Requirements

• Vendor partnership: Not required - standard integration
• Customer-specific setup: Yes - Workday tenant configuration required
• Marketplace approval: Not required
• Any mandatory agreements or feature enablement: Standard Workday LMS module access

​

2.2 System-Side Prerequisites

• Required modules: Workday Learning Management System
• Required admin permissions: Learning Administrator role for content management
• Required system features: External content feature enabled in Workday tenant

​

2.3 StackOne-Side Prerequisites

• Required connector meta fields: Content categories configuration
• Required configuration flags: Enrollment requirements, mobile content duplication
• Sandbox/test requirements: Workday sandbox tenant for testing

​

3. Behaviour of Write Operations

​

3.1 Content / Object Upsert

• Supported operations: Create, Update content items
• Identity / Deduplication rules: Uses both external_reference and content title. If title matches existing content, the external_reference will be updated.
• Lifecycle behaviour:
  • Creation: Auto-creates course wrapper with default settings (Lesson Order 1, Lesson Mandatory True, Registrable Status Open)
  • Update: Updates existing content based on deduplication rules
  • Disabling: Uses active field to hide courses
• System defaults applied:
  • Content set to require enrollment by default
  • Lesson Mandatory: True
  • Lesson Order: 1
  • Registrable Status: Open
• Limitations:
  • Cover images must be base64 encoded
  • Content must include valid Workday category
  • Categories must be customer-specific or from unified categories endpoint

​

3.2 Completion / Status Push

• Identifiers used: learning_object_external_reference for content identification
• Creation vs. update behaviour: Updates existing completion records rather than creating duplicates
• Timing and sequencing considerations:
  • Workday auto-creates completions when users launch content
  • StackOne completions update existing records to avoid discrepancies
  • DELETE user completion endpoint available for cleanup

​

3.3 Additional Writeable Resources

• List/get categories from Workday tenant
• Required for content categorization during upsert

​

4. Field-to-UI Mapping

​

4.1 Overview

​

4.2 Mapping Table

Unified API Field	Workday Field / Behaviour	UI Location	Screenshot Placeholder	Notes
title	Course & Lesson Title	Discover card + Course header		Updates everywhere when changed
external_reference	Learning Course ID	Admin View		Must be unique; changing creates new course
description	Description	Course page		HTML stripped; truncated on tiles
duration	Time Value Reference + Total Course Duration	Course page + Admin		ISO-8601 converted to minutes
categories	Topics Reference	Additional Course Details		Must match existing topics
skills	Skill Reference	Course page		Unknown skills cause failure
languages	Language Reference	Additional Details		Only first language displayed
content_url	External Content URL	Admin → Lessons		Hidden from learners; launched via Start/Enroll
cover_url	Course Image Data	Discover tile + Course page		Must be publicly accessible
active	Inactive	Admin		false → hides course
requires_enrollment	Requires Enrollment	Admin		false → self-directed
mobile_url	Mobile Lesson	Lessons tab		Creates additional mobile lesson

​

4.3 UI Walkthrough

​

4.3.1 Discover Catalogue

• Course appears with:
  • Cover image
  • Title
  • Duration
  • Short description excerpt
• Users can filter by Topic, Language, Content Provider

Screenshot: Screenshot: Screenshot:

​

4.3.2 Course Page (Learner View)

• Full description
• Skills
• Cover image
• Start/Enroll button
• Completion badge if completed

Screenshot:

​

4.3.3 Lessons in This Course

• Lesson 1 auto-generated
• Type: External Lesson
• Required flag visible

Screenshot:

​

4.3.4 Admin View

• External Reference
• Requires Enrollment
• Enforce Lesson Order
• Topics, Skills, Languages

​

5. Derived Values & Defaults

​

5.1 Derived / Computed Values

• Cover images: URLs converted to base64 encoding automatically
• Duration: ISO-8601 format converted to minutes for Workday display
• Course wrapper: Auto-generated around individual content items

​

5.2 System Defaults Applied by StackOne

• Content requires enrollment: True (configurable at account level)
• Lesson Mandatory: True
• Lesson Order: 1
• Registrable Status: Open
• Course creation: Auto-wraps individual content in course structure

​

5.3 Hardcoded / Strict Enums

• Languages: Locale codes (e.g., en_gb)
• Result: pass or fail
• Categories: Must match existing Workday categories or use unified categories endpoint

​

6. Configuration

​

6.1 StackOne Config Options

• Enrollment Required (Content): Yes/No - Controls whether content requires enrollment
• Create Duplicate Content for Mobile: Yes/No - Creates additional mobile lesson when mobile_url provided
• Content Categories: Customer-specific category mapping

​

6.2 System-Level Configuration

• External content feature must be enabled in Workday tenant
• Learning Administrator role assigned to managing users
• Category structure configured for content organization

​

6.3 Identity / SSO Mapping

• Users identified through Workday’s internal user management
• Completions linked via learning_object_external_reference
• Auto-enrollment creates user-content relationships

​

6.4 Account Configuration

• Requires Enrollment (Account): Yes/No - Toggle whether a user needs approval to launch a course.
• Media File ID (WID): If using the Media File CompletionBlocker approach, enter the Workday WID of the file used for the blocker.

​

7. Quirks & Limitations

​

Known Limitations

• Rate Limits: 5-10 requests per second
• Cover Images: Must be base64 encoded; URL conversion failures cause upsert failures
• Mobile Content: No native support; requires duplicate lesson creation

​

System-Specific Behaviours

• Content Categorization: Content may be categorized as internal, even if it links to an external provider
• Auto-Completion: Workday auto-completes content when users launch from UI
• Deduplication: Uses both external_reference AND title, not just external_reference

​

Known Bugs or Inconsistencies

• Enrollments and Completions: Workday auto-creates these, potentially causing discrepancies between external provider progress and Workday status
• Single Content Auto-Complete: If course has single lesson, Workday completes entire course on launch

​

Mitigation Strategies

• Completions update existing records rather than creating new ones
• DELETE user completion endpoint available for cleanup
• SCORM course blocker workaround available for auto-completion issues

​

8. Testing & Validation

​

8.1 Recommended Test Cases

1. Content Creation: Push new content with all fields → Verify appears in Discover with correct metadata
2. Content Update: Update existing content title → Verify deduplication works correctly
3. Completion Push: Send completion for enrolled user → Verify updates existing record without duplicate
4. Mobile Content: Push content with mobile_url and mobile duplication enabled → Verify two lessons created
5. Category Validation: Push content with invalid category → Verify appropriate error handling
6. Cover Image Handling: Push content with URL-based cover image → Verify base64 conversion success

​

8.2 Sample Payloads

// Content Upsert (PUT /unified/lms/content)
{
  "title": "Advanced Sales Techniques",
  "external_reference": "ADV-SALES-001",
  "description": "A comprehensive course covering modern B2B sales strategies.",
  "languages": [
    { "value": "en_GB" },
    { "value": "fr_FR" }
  ],
  "content_url": "https://provider.example.com/courses/adv-sales-001",
  "cover_url": "https://cdn.example.com/images/adv-sales-001.jpg",
  "active": true,
  "duration": "PT1H30M45S",
  "skills": [
    { "id": "skill-001", "name": "Sales Techniques", "hierarchy": { "value": "primary" }, "language": { "value": "en_GB" } },
    { "name": "Customer Engagement", "hierarchy": { "value": "secondary" } }
  ],
  "order": 1,
  "categories": [
    { "name": "Sales" },
    { "id": "cat-technology", "name": "Technology" }
  ],
}

// Completion Push (POST /unified/lms/users/{id}/completions)
{
  "learning_object_external_reference": "ADV-SALES-001",
  "result": { "value": "Pass" },
  "completed_at": "2025-01-15T14:45:30.000Z",
  "time_spent": "PT45M",
  "score": {
    "value": 100,
    "raw_value": "A+"
  }
}

​

8.3 Troubleshooting Checklist

​

Integration Configurations

​

Media File Completion Blocker

​

Mobile Content Lesson

1. Configure the Create Duplicate Content for Mobile to Yes in the Integration Configuration
2. Include a value in the Mobile Launch Content URL field.