feat(FDSE-3324): add directory and usage modular inputs

[Arthur-10-coder]

Summary

• Adds 5 new modular inputs to the Genesys Cloud TA: users_directory, queues_directory, usage_events, org_usage, and oauth_client_usage
• Directory inputs provide daily full-snapshot ingestion for lookup-table correlation (user/queue ID → human-readable name)
• Usage inputs replace the deprecated POST /api/v2/usage/query and POST /api/v2/oauth/clients/{clientId}/usage/query endpoints (removal deadline: Oct 16, 2026)

Context

Jira: https://splunk.atlassian.net/browse/FDSE-3324

Changes

File	Description
globalConfig.json	+5 input definitions (UCC framework) with 86400s default interval
package/bin/users_directory_helper.py	GET /api/v2/users → sourcetype genesyscloud:directory:users
package/bin/queues_directory_helper.py	GET /api/v2/routing/queues → sourcetype genesyscloud:directory:queues
package/bin/usage_events_helper.py	POST /api/v2/usage/events/query → sourcetype genesyscloud:usage:events
package/bin/org_usage_helper.py	POST /api/v2/usage/aggregates/query/jobs → sourcetype genesyscloud:usage:organization
package/bin/oauth_client_usage_helper.py	POST /api/v2/usage/client/{id}/aggregates/query/jobs → sourcetype genesyscloud:usage:oauth_clients

Technical Notes

• All inputs follow existing helper pattern (UCC modular input + genesyscloud_client.py)
• Directory inputs: no checkpointing needed (full snapshot each run)
• Usage inputs: KVStore checkpointing for incremental ingestion; async job polling pattern for aggregate endpoints
• OAuth scopes required: users:readonly, routing:readonly, usage:readonly
• SDK v238 required for new endpoint support

Follow-up (separate PR)

• Custom Search Commands (| genesysusers, | genesysqueues) will be added to genesys_cloud_app_for_splunk — these live in the App, not the TA, per architectural decision

[edro15]

@Arthur-10-coder Please have a look at these changes and comments.

[edro15]

Suggested change

**OAuth scopes required (for usage inputs):** `usage:readonly`

Please move this information to the table at docs/ConfigureGenesysCloud/index.md. ALL necessary permissions for ALL inputs MUST be added to that table following given format

[edro15]

Suggested change

	## Usage Inputs Reference
	| Input | API Endpoint | Sourcetype |
	|-------|-------------|------------|
	| `operational_events` | `POST /api/v2/usage/events/query` | `genesyscloud:operational:events` |
	| `org_api_usage` | `POST /api/v2/usage/aggregates/query/jobs` | `genesyscloud:operational:usage:api` |
	| `clients_api_usage` | `POST /api/v2/usage/client/{id}/aggregates/query/jobs` | `genesyscloud:operational:usage:clients_api` |

This is not aligned with other inputs documentation. To be removed.

[Arthur-10-coder]

Update: review feedback applied + CI root cause fixed

Pushed c9f4372 addressing the review. Summary of what changed:

CI failure root cause (the 3 failing Deploy and test the TA jobs).
The UsageApi method/model names used by the helpers did not exist in the pinned SDK PureCloudPlatformClientV2==238.0.0, so the client's dynamic getattr returned None and assert response is not None failed. Corrected to the real v238 symbols:

• events: post_usage_query (ApiUsageOrganizationQuery) + poll get_usage_query_execution_id_results
• org: post_usage_aggregates_query_jobs (OrganizationPublicApiUsageQueryRequest) + get_usage_aggregates_query_job
• client: post_usage_client_client_id_aggregates_query_jobs (ClientPublicApiUsageQueryRequest) + get_usage_client_client_id_aggregates_query_job
• granularity fixed from "P1D" (invalid, coerced to outdated_sdk_version) to "Day".
• genesyscloud_client.post now passes the payload as the body= kwarg so path params like client_id are honored.

Verified locally against Mockoon + SDK 238: integration suite 26/26 passing (previously 3 failed / 20 passed).

Review comments addressed.

• Sourcetypes renamed to operational:* (operational:events, operational:usage:api, operational:usage:clients_api) across helpers, docs and props.conf.
• Input titles/descriptions cleaned (no endpoint/scope/deprecation) with the requested titles.
• max_poll_attempts / poll_interval_seconds are now user-configurable (like audit_query), added to globalConfig.json and docs; removed hard-coded constants.
• Readability: inverted if job_response and compact to_dict() forms; continue on proxy errors.
• Permissions consolidated in ConfigureGenesysCloud; version kept at 0.4.1.
• Tests consolidated into tests/integration/test_genesyscloud_client.py and tests/modinput_functional/test_genesyscloud_ta.py with mock routes for the new endpoints.

Note on scope: this revision keeps the users_directory and queues_directory inputs and consolidates the tests (rather than the separate test_operational_usage*.py files). Happy to adjust if you prefer dropping the directory inputs.