Docs

Integrations / HR systems / Workday

Manage Workday Home Address

Enable employees to view and update their home address in Workday through Risotto

Enable employees to view and update their home address in Workday directly through Risotto. This tool uses Workday's REST API with Basic Authentication to provide self-service address management.

Authentication

This tool uses Basic Authentication with Workday's Integration System User (ISU) credentials. You'll need to create an ISU account in Workday with appropriate permissions to read and update worker personal information.

Setup Requirements

Prerequisites

Before configuring this tool, ensure you have:

  1. Workday Admin Access - To create security groups and configure domain permissions
  2. Knowledge of your Workday environment:
    • Implementation vs. Production tenant
    • Tenant name/identifier
    • REST API endpoint URL format
  3. Permissions to create:
    • Integration System Users (ISU)
    • Security Groups
    • Domain Security Policies

Step 1: Create Integration System User in Workday

  1. Create Integration System User

    Search for Create Integration System User in Workday:

    • Username: risotto_integration (without @tenant suffix)
    • Password: Generate a strong password
    • Session Timeout Minutes: 0 (no timeout)
    • Check Do Not Allow UI Sessions to restrict UI access
    • Click OK to create the user
  2. Prevent Password Expiration

    Search for Maintain Password Rules: - Add the ISU to System Users exempt from password expiration - Click OK to save changes

  3. Create Integration Security Group

    Search for Create Security Group: - Type: Integration System Security Group (Unconstrained) - Name: "Risotto Integration Security Group" - Click OK to create the group

  4. Add ISU to Security Group

    After creating the security group: - Edit the security group - Add the ISU created in Step 1 as a member - Click OK to save

  5. Assign Domain Permissions

    Search for Maintain Permissions for Security Group: - Select your integration security group - Add the following domain security policies: - Worker Data: Personal Information - Set to Get (View) - Worker Data: Personal Information - Set to Put (Modify) - Click OK to save permissions

  6. Activate Security Changes

    Search for Activate Pending Security Policy Changes:

    • Review the pending changes
    • Add a comment (e.g., "Enabling Risotto integration")
    • Click OK to activate

Step 2: Configure Authentication Policies

  1. Manage Authentication Policies

    Search for Manage Authentication Policies:

    • Edit the relevant authentication policy for your tenant
    • Ensure the ISU is included in an authentication rule
    • Set Allowed Authentication Types to include "User Name Password"
    • Click OK to save
  2. Activate Authentication Changes

    Search for Activate All Pending Authentication Policy Changes:

    • Review and confirm the changes
    • Click OK to activate

Step 3: Enable the Tools in Risotto

Risotto has two tools for home addresses: Get Workday Home Address and Update Workday Home Address. Both use your organization's Workday connection. You do not enter Workday credentials on the tools.

  1. Connect Workday

    In the Risotto Dashboard, go to Settings > Integrations and click the Workday card. If the header shows Not connected, connect Workday.

  2. Select Tools in the sidebar.
  3. Find the Tools

    In the Tool groups list, select Workday.

  4. Enable the Tools

    Find Get Workday Home Address and click Enable. Then find Update Workday Home Address and click Enable.

  5. Configure the Tools (optional)

    Open a tool and click Edit to change its settings:

    • Requires Approval: Require human approval before the tool runs
    • Restrict to Requestor Only: Only operate on the ticket requestor. On by default.

    Click Save.

The tools are now available for use in runbooks and can be invoked by Risotto's AI assistant.

Step 4: Verify the Integration

  1. Test REST API Access

    Before using the tool, verify the ISU can access the REST API:

    1. Use a tool like Postman or curl to test authentication
    2. Make a GET request to: [your_workday_url]/api/v1/workers?limit=1
    3. Use Basic Auth with your ISU credentials (username@tenant:password)
    4. You should receive a 200 OK response with worker data
  2. Test in Risotto

    Create a test ticket and try the VIEW operation:

    1. The tool should successfully authenticate
    2. It should find the employee by email
    3. It should return the current address or indicate no address is on file

Features

Operations

The tool supports two operations:

VIEW

Display the employee's current home address on file in Workday

UPDATE

Submit a direct update to change the home address

View Current Address

When an employee asks to view their address, the tool:

  1. Looks up the employee by their email address
  2. Retrieves their current home address from Workday
  3. Displays the address in a formatted, easy-to-read format

Example Output:

**Current Home Address for John Doe:**

123 Main Street
Apt 4B
San Francisco, CA 94102
US

To update your address, use the UPDATE operation with your new address details.

Update Address

When an employee requests an address update, the tool:

  1. Validates that all required fields are provided
  2. Looks up the employee by their email address
  3. Submits the address update to Workday
  4. Confirms the update was successful

Required Fields:

  • Address Line 1 (street address)
  • City
  • State/Province code (e.g., CA, NY, TX)
  • Postal/ZIP code

Optional Fields:

  • Address Line 2 (apartment, suite, etc.)
  • Country (defaults to US)

Automatic Email Matching

The tool automatically identifies employees using their email address from the ticket context. This means:

  • Employees can only view/update their own address
  • No manual employee ID lookup required
  • Secure by default - users can only access their own data

Configuration Options

When configuring this tool in a runbook or allowing AI to invoke it, the following parameters are available:

ParameterTypeRequiredDescription
operationSELECTYesOperation to perform: VIEW or UPDATE
address_line_1TEXTFor UPDATEStreet number and name
address_line_2TEXTNoApartment, suite, unit, etc.
cityTEXTFor UPDATECity name
state_provinceTEXTFor UPDATEState or province code
postal_codeTEXTFor UPDATEZIP or postal code
countryTEXTNoCountry code (defaults to US)

Security & Privacy

Data Protection

  • Encrypted Credentials: ISU credentials are stored encrypted in the Risotto database
  • Self-Service Only: Employees can only access their own address information
  • Audit Trail: All address updates are logged in Workday's audit system
  • Ticket Context: Tool execution is tied to ticket context for accountability

Access Control

  • Tool can be configured to require human approval for address updates
  • Only works within ticket context - cannot be invoked outside of a support request
  • Employee identity is verified via email address matching in Workday

Troubleshooting

Worker profile not found

Cause: The employee's email address doesn't match any worker in Workday

Solution:

  • Verify the employee's email is registered in Workday
  • Check for typos in the email address
  • Ensure the email domain matches your Workday configuration
  • Contact HR to update email address in Workday if needed
Authentication failed

Cause: ISU credentials are incorrect, expired, or not properly configured

Solution:

  • Verify the ISU username format is username@tenant for API calls
  • Check that the password is correct and hasn't expired
  • Ensure the ISU account is active and not locked
  • Verify Do Not Allow UI Sessions is checked for the ISU
  • Check that authentication policies allow "User Name Password" authentication
  • Ensure all pending authentication policy changes were activated
  • Verify the ISU is in the password expiration exemption list
Permission denied

Cause: ISU doesn't have required permissions or security changes weren't activated

Solution:

  • Verify the ISU is in an Integration System Security Group (Unconstrained)
  • Check the security group has these domain policies:
    • Worker Data: Personal Information - Get (View)
    • Worker Data: Personal Information - Put (Modify)
  • Ensure all pending security policy changes were activated
  • Verify the security group type is "Unconstrained" not "Constrained"
  • Check that the ISU is properly assigned as a member of the security group
Missing required address fields

Cause: UPDATE operation called without all required fields

Solution:

  • Ensure these fields are provided:
    • address_line_1 (street address)
    • city
    • state_province (2-letter code)
    • postal_code
  • The AI should prompt the user for missing information
Invalid Workday tenant URL

Cause: Workday URL is malformed or incorrect

Solution:

  • Verify URL format: https://wd2-impl-services1.workday.com/ccx/service/tenant_name
  • Remove trailing slashes from the URL
  • Ensure you're using the correct Workday environment (implementation vs. production)
  • Check that the tenant name in the URL matches your tenant

Rate Limiting

Workday enforces API rate limits to protect system performance:

  • The tool automatically handles rate limiting with retry logic
  • If rate limited (HTTP 429), the tool waits for the Retry-After period before retrying
  • Maximum of 3 retry attempts with exponential backoff
  • For high-volume usage, contact Workday to discuss rate limit increases

Best Practices

Configuration

  • Use a dedicated ISU: Create a separate Integration System User specifically for Risotto
  • Rotate credentials regularly: Update ISU password on a regular schedule (e.g., every 90 days)
  • Test in implementation environment: Verify the tool works in your Workday implementation before deploying to production
  • Monitor usage: Review Workday audit logs periodically to monitor tool usage

User Experience

  • Enable approval workflows: For sensitive changes, enable human approval in the tool configuration
  • Provide clear instructions: Include helpful context in runbooks about what information is needed
  • Validate addresses: Consider adding validation for common address format issues
  • Set expectations: Let employees know how long address updates take to reflect in Workday

Example Use Cases

Self-Service Address Update

An employee messages Risotto: "I need to update my home address"

Risotto can:

  1. Use the VIEW operation to show the current address
  2. Ask the employee for their new address details
  3. Use the UPDATE operation to submit the change
  4. Confirm the update was successful

Address Verification

An employee wants to verify their address is correct before payroll processing:

Risotto can:

  1. Use the VIEW operation to display the current address on file
  2. Confirm with the employee if the address is correct
  3. If incorrect, guide them through the UPDATE process

Technical Details

API Endpoints Used

This tool uses Workday REST API v1 endpoints:

  • GET /api/v1/workers?search={email} - Find worker by email
  • GET /api/v1/workers/{worker_id}/personalInformation - Get worker address
  • PUT /api/v1/workers/{worker_id}/personalInformation - Update worker address

Authentication Method

The tool uses HTTP Basic Authentication with the ISU credentials:

  • Username format: username@tenant
  • Authorization header: Basic base64(username:password)

Additional Resources

Support

If you encounter issues with this tool:

  1. Check the troubleshooting section above
  2. Review Workday audit logs for API errors
  3. Verify ISU permissions in Workday Security
  4. Contact Risotto support at support@tryrisotto.com

Something wrong or missing? Report an issue · View as Markdown