# 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

   > **Note:** This prevents the integration from breaking due to password expiration

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

   > **Tip:** Use "Unconstrained" type for REST API access. Constrained groups are for
   > report/web service access only.

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

   > **Warning:** Changes won't take effect until activated. This step is critical!

### 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

   > **Note:** This ensures the ISU can authenticate via username/password for REST API calls

### 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. **Find the Tools**

   In the **Tool groups** list, select **Workday**.

3. **Enable the Tools**

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

4. **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

   > **Tip:** If you get a 401 Unauthorized, verify the authentication policy configuration and that all changes were activated.

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:

| 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@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)`

> **Note:** While Workday's newer integrations use OAuth2, the REST API v1 continues to
> support Basic Authentication for backward compatibility.

## Additional Resources

- [Workday REST API Documentation](https://community.workday.com/sites/default/files/file-hosting/restapi/index.html)
- [Workday Integration System User Guide](https://doc.workday.com)
- [Workday Community - Integration Best Practices](https://community.workday.com)
- [Risotto Documentation](https://www.tryrisotto.com/docs)

## 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>

Source: https://www.tryrisotto.com/docs/integrations/tools/workday/manage_address
