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:
- Workday Admin Access - To create security groups and configure domain permissions
- Knowledge of your Workday environment:
- Implementation vs. Production tenant
- Tenant name/identifier
- REST API endpoint URL format
- Permissions to create:
- Integration System Users (ISU)
- Security Groups
- Domain Security Policies
Step 1: Create Integration System User in Workday
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
- Username:
Prevent Password Expiration
Search for Maintain Password Rules: - Add the ISU to System Users exempt from password expiration - Click OK to save changes
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
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
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
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
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
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.
Connect Workday
In the Risotto Dashboard, go to Settings > Integrations and click the Workday card. If the header shows Not connected, connect Workday.
- Select Tools in the sidebar.
Find the Tools
In the Tool groups list, select Workday.
Enable the Tools
Find Get Workday Home Address and click Enable. Then find Update Workday Home Address and click Enable.
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
Test REST API Access
Before using the tool, verify the ISU can access the REST API:
- Use a tool like Postman or curl to test authentication
- Make a GET request to:
[your_workday_url]/api/v1/workers?limit=1 - Use Basic Auth with your ISU credentials (username@tenant:password)
- You should receive a 200 OK response with worker data
Test in Risotto
Create a test ticket and try the VIEW operation:
- The tool should successfully authenticate
- It should find the employee by email
- It should return the current address or indicate no address is on file
Features
Operations
The tool supports two operations:
Display the employee's current home address on file in Workday
Submit a direct update to change the home address
View Current Address
When an employee asks to view their address, the tool:
- Looks up the employee by their email address
- Retrieves their current home address from Workday
- 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:
- Validates that all required fields are provided
- Looks up the employee by their email address
- Submits the address update to Workday
- 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:
| Parameter | Type | Required | Description |
|---|---|---|---|
operation | SELECT | Yes | Operation to perform: VIEW or UPDATE |
address_line_1 | TEXT | For UPDATE | Street number and name |
address_line_2 | TEXT | No | Apartment, suite, unit, etc. |
city | TEXT | For UPDATE | City name |
state_province | TEXT | For UPDATE | State or province code |
postal_code | TEXT | For UPDATE | ZIP or postal code |
country | TEXT | No | Country 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@tenantfor 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-Afterperiod 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:
- Use the VIEW operation to show the current address
- Ask the employee for their new address details
- Use the UPDATE operation to submit the change
- Confirm the update was successful
Address Verification
An employee wants to verify their address is correct before payroll processing:
Risotto can:
- Use the VIEW operation to display the current address on file
- Confirm with the employee if the address is correct
- 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 emailGET /api/v1/workers/{worker_id}/personalInformation- Get worker addressPUT /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
- Workday REST API Documentation
- Workday Integration System User Guide
- Workday Community - Integration Best Practices
- Risotto Documentation
Support
If you encounter issues with this tool:
- Check the troubleshooting section above
- Review Workday audit logs for API errors
- Verify ISU permissions in Workday Security
- Contact Risotto support at support@tryrisotto.com
Something wrong or missing? Report an issue · View as Markdown