Public API: User-type fields only accept email strings, not numeric user IDs

[pneumatic-seidler]

Summary

This is an improvement proposal. If after review it is deemed unnecessary, this issue can be closed.

Problem

When launching a workflow via the Public API (POST /templates/<ID>/run), fields of type user in the kickoff form only accept email address strings. However, multiple parts of the API return and reference numeric user IDs, creating a confusing developer experience:

1. GET /accounts/users returns numeric id fields for each user
2. GET /templates/<ID> lists source_id as integers in raw_performers
3. The GitHub Wiki documentation states "User ID (integer)" as the expected format
4. The error message ("The user or group specified for a User field does not exist") does not indicate that the format is wrong — it sounds like the user was not found

Root cause

In backend/src/processes/services/tasks/field.py, the _get_valid_user_value method (lines 245–282) only handles:

• Strings matching an email regex → looks up via account.users.get(email__iexact=value)
• Other strings → treats as group name via account.user_groups.get(name__iexact=value)

Numeric IDs (integers) are not handled and fall through to the error.

Proposed Solutions

Option A — Accept numeric IDs (recommended):
Add an isinstance(raw_value, int) check that looks up the user via account.users.get(id=raw_value). This is backward-compatible.

Option B — Better error message:
Change the error message to: "User fields require an email address or group name string, not a numeric ID."

Option C — Both:
Accept numeric IDs and improve the error message for invalid values.

Expected Outcome

Developers can pass either a numeric user ID (from GET /accounts/users) or an email address to user-type fields when launching workflows via the API.