Expose refreshExtractTriggered on SubscriptionItem by jacalata · Pull Request #1861 · tableau/server-client-python

jacalata · 2026-08-16T12:06:54Z

Summary

Adds support for the REST API's refreshExtractTriggered="true" attribute on subscriptions -- the wire form of Tableau Cloud's "On Extract Refresh" subscriptions. When True, the subscription fires when the referenced schedule's extract refresh completes, rather than on the schedule's time trigger.

Closes #1658.

What changes

New SubscriptionItem.on_extract_refresh(subject, extract_refresh_schedule_id, user_id, target) classmethod factory -- the recommended way to construct these subscriptions.
refresh_extract_triggered is now a boolean property on SubscriptionItem. Its docstring covers the two ways the server can surprise callers:
- Setting True with a non-extract-refresh schedule id is a server-side error.
- Updates that change schedule_id cause the server to silently clear the flag to False on that same call; converting an existing time-based subscription requires two updates.
Subscriptions.create() and .update() now raise ValueError up front if schedule_id is missing, so what used to be a confusing wire-layer error becomes an actionable client-side message.
create_req emits refreshExtractTriggered="true" only when set. update_req emits both "true" and "false" unconditionally, so callers can turn the flag off on an existing subscription (the server retains the prior value when the attribute is absent).
_parse_element reads the attribute back into the property.

Compatibility note

Every subscriptions.update() payload now carries refreshExtractTriggered="true|false". Older servers that don't know the attribute should ignore unknown attrs on the <subscription> element per the schema's <xs:anyAttribute processContents="skip"/>; the attribute has been on the server since long before TSC's current minimum version.

Test plan

pytest test/test_subscription.py -q -- 16 pass, including 12 new tests covering the factory, defaults, create_req emit-when-set / omit-when-false, update_req always-emits in both directions, parse round-trip with and without the attribute, parse of inline-schedule responses (no schedule_id), and create()/update() rejection of missing schedule_id.
Full test suite -- 879 pass, 1 pre-existing skip.
Manual verification on a Tableau Cloud site: create a subscription via on_extract_refresh(), confirm it appears as "On Extract Refresh" in the web UI, and confirm it fires when the referenced extract refresh runs.

🤖 Generated with Claude Code

The Tableau REST API supports a `refreshExtractTriggered="true"` attribute on subscription payloads that makes the subscription fire when its referenced schedule's extract refresh completes, rather than on the schedule's time trigger. On Tableau Cloud, this is the wire form of an "On Extract Refresh" subscription. TSC never exposed this attribute; users trying to create these subscriptions were passing `schedule_id=None` and hitting a confusing wire error deep in the endpoint layer. Changes: - `SubscriptionItem.on_extract_refresh(...)` classmethod factory constructs a subscription with an extract-refresh schedule id and the flag set. - `refresh_extract_triggered` exposed as a property with a docstring covering the two ways the server surprises callers (server rejects True with a non-extract schedule; server silently clears the flag when a schedule change is included in an update). - `Subscriptions.create()` and `.update()` now raise `ValueError` up front when `schedule_id` is missing, so the wire error becomes an actionable client-side message. - `create_req` emits `refreshExtractTriggered="true"` only when set; `update_req` emits both true and false so callers can turn the flag off on an existing subscription. - `_parse_element` reads the attribute back into the property; parse continues to accept inline-schedule responses (schedule_id=None). Tests cover: factory sets flag + schedule id; default false; create_req emit-when-set/omit-when-false; update_req always emits; parse round-trip for both true and missing; parse of inline-schedule responses; create() and update() reject missing schedule_id. Related to #1658. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

github-actions · 2026-08-16T12:07:40Z

Coverage Report

File	Stmts	Miss	Cover	Missing
tableauserverclient
__init__.py	5	0	100%
config.py	15	0	100%
datetime_helpers.py	25	1	1	96%
exponential_backoff.py	20	0	100%
filesys_helpers.py	31	0	100%
namespace.py	26	3	3	88%
tableauserverclient/bin
__init__.py	2	0	100%
_version.py	358	212	212	41%
tableauserverclient/helpers
__init__.py	1	0	100%
logging.py	2	0	100%
strings.py	31	1	1	97%
tableauserverclient/models
__init__.py	46	0	100%
collection_item.py	41	7	7	83%
column_item.py	55	32	32	42%
connection_credentials.py	35	11	11	69%
connection_item.py	94	14	14	85%
custom_view_item.py	144	21	21	85%
data_acceleration_report_item.py	54	1	1	98%
data_alert_item.py	158	4	4	97%
data_freshness_policy_item.py	155	15	15	90%
database_item.py	207	36	36	83%
datasource_item.py	300	12	12	96%
dqw_item.py	104	5	5	95%
exceptions.py	4	0	100%
extensions_item.py	132	4	4	97%
extract_item.py	44	4	4	91%
favorites_item.py	69	8	8	88%
fileupload_item.py	19	0	100%
flow_item.py	149	10	10	93%
flow_run_item.py	71	0	100%
group_item.py	89	6	6	93%
groupset_item.py	49	7	7	86%
interval_item.py	182	32	32	82%
job_item.py	192	10	10	95%
linked_tasks_item.py	79	1	1	99%
location_item.py	29	2	2	93%
metric_item.py	129	13	13	90%
oidc_item.py	63	3	3	95%
pagination_item.py	34	1	1	97%
permissions_item.py	111	12	12	89%
project_item.py	207	31	31	85%
property_decorators.py	100	18	18	82%
reference_item.py	26	2	2	92%
revision_item.py	59	1	1	98%
schedule_item.py	209	6	6	97%
server_info_item.py	37	7	7	81%
site_item.py	636	13	13	98%
subscription_item.py	116	1	1	99%
table_item.py	119	18	18	85%
tableau_auth.py	61	25	25	59%
tableau_types.py	27	1	1	96%
tag_item.py	15	0	100%
target.py	6	0	100%
task_item.py	56	2	2	96%
user_item.py	310	18	18	94%
view_item.py	220	16	16	93%
virtual_connection_item.py	64	8	8	88%
webhook_item.py	69	1	1	99%
workbook_item.py	362	16	16	96%
tableauserverclient/server
__init__.py	9	0	100%
exceptions.py	4	0	100%
filter.py	29	1	1	97%
pager.py	33	1	1	97%
query.py	143	15	15	90%
request_factory.py	1339	177	177	87%
request_options.py	386	5	5	99%
server.py	188	23	23	88%
sort.py	6	0	100%
tableauserverclient/server/endpoint
__init__.py	35	0	100%
auth_endpoint.py	77	11	11	86%
custom_views_endpoint.py	152	12	12	92%
data_acceleration_report_endpoint.py	21	0	100%
data_alert_endpoint.py	94	23	23	76%
databases_endpoint.py	111	30	30	73%
datasources_endpoint.py	323	33	33	90%
default_permissions_endpoint.py	44	3	3	93%
dqw_endpoint.py	45	16	16	64%
endpoint.py	212	20	20	91%
exceptions.py	77	6	6	92%
extensions_endpoint.py	31	0	100%
favorites_endpoint.py	94	22	22	77%
fileuploads_endpoint.py	51	0	100%
flow_runs_endpoint.py	62	9	9	85%
flow_task_endpoint.py	21	2	2	90%
flows_endpoint.py	198	53	53	73%
groups_endpoint.py	126	9	9	93%
groupsets_endpoint.py	72	7	7	90%
jobs_endpoint.py	67	9	9	87%
linked_tasks_endpoint.py	37	0	100%
metadata_endpoint.py	88	14	14	84%
metrics_endpoint.py	55	6	6	89%
oidc_endpoint.py	42	1	1	98%
permissions_endpoint.py	44	3	3	93%
projects_endpoint.py	178	24	24	87%
resource_tagger.py	127	35	35	72%
schedules_endpoint.py	119	11	11	91%
server_info_endpoint.py	36	10	10	72%
sites_endpoint.py	130	27	27	79%
subscriptions_endpoint.py	60	13	13	78%
tables_endpoint.py	110	36	36	67%
tasks_endpoint.py	63	6	6	90%
users_endpoint.py	183	8	8	96%
views_endpoint.py	150	9	9	94%
virtual_connections_endpoint.py	113	10	10	91%
webhooks_endpoint.py	54	9	9	83%
workbooks_endpoint.py	338	22	22	93%
TOTAL	12030	1403	88%

Copilot

Pull request overview

Adds first-class support for Tableau REST API’s refreshExtractTriggered subscription attribute (Tableau Cloud “On Extract Refresh” subscriptions) by exposing it on SubscriptionItem, emitting/parsing it in XML requests/responses, and improving client-side validation/errors when schedule_id is missing.

Changes:

Introduces SubscriptionItem.refresh_extract_triggered plus SubscriptionItem.on_extract_refresh(...) factory for extract-refresh-triggered subscriptions.
Updates subscription request XML generation/parsing to handle refreshExtractTriggered (create emits only when true; update always emits true/false).
Adds endpoint-level validation for missing schedule_id and expands test coverage for the new behavior and regression cases.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
`test/test_subscription.py`	Adds tests for factory, defaults, XML emit/omit behavior, parsing, and create/update validation.
`tableauserverclient/server/request_factory.py`	Emits `refreshExtractTriggered` in create/update subscription request payloads.
`tableauserverclient/server/endpoint/subscriptions_endpoint.py`	Validates `schedule_id` presence for create/update and raises clearer `ValueError`s.
`tableauserverclient/models/subscription_item.py`	Adds property + factory, documents behavior, and parses `refreshExtractTriggered` from responses.

Suppressed comments (1)

tableauserverclient/server/endpoint/subscriptions_endpoint.py:75

update() uses a truthiness check for schedule_id, which won’t reject whitespace-only values and is slightly inconsistent with update_req (which treats schedule_id as optional and would emit a without an id). Making the validation explicit for None/empty/whitespace keeps failures predictable and avoids generating invalid XML.

        if not subscription_item.schedule_id:
            # A subscription round-tripped from an inline-schedule response
            # (Cloud/TOL) has schedule_id=None. Updating it in that state
            # sends <schedule/> with no id and hits the same wire-layer error
            # that create() guards against. See tableau/server-client-python#1658.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

- Docstring on `refresh_extract_triggered` now warns about the manual- build update() footgun: because every subscriptions.update() payload carries the attribute, a caller who builds a fresh SubscriptionItem locally, stamps _id, and updates will silently flip an existing on-extract-refresh subscription off. Fetch first. - Soften create()'s "schedule_id is required" error so someone who just forgot to set schedule_id on a time-based subscription doesn't get steered exclusively toward SubscriptionItem.on_extract_refresh(...); the factory is now mentioned as a conditional pointer. - __init__'s schedule_id parameter is now typed str | None, matching the real state: _parse_element sets it to None on inline-schedule responses. Drop the two `# type: ignore` markers in test/test_subscription.py that were papering over the earlier lie. - create_req asserts schedule_id non-None to satisfy mypy after the parameter widening; subscriptions.create() already guards this path before request emission. - Add samples/create_extract_refresh_subscription.py demonstrating the full flow: sign in, resolve view/workbook and user by name, pick an extract-refresh schedule from the schedules list, build the subscription via on_extract_refresh(), post it. Highest-leverage discoverability artifact for callers searching "on extract refresh". - CHANGELOG entry.

Three fresh-eyes findings: - Remove the "Subscriptions cannot use On Extract Refresh" entry. The REST API's refreshExtractTriggered attribute does support this, and TSC support is landing in #1861 (which closes the tracker #1658). The entry is about to be factually wrong on both counts. - Soften the intro: it promised "follow the appropriate issues" for every item, but the vf_-silently-dropped entry has no tracker filed. New wording says "where filed" so the doc doesn't overpromise. - Reword the daily-schedules note to describe behavior neutrally ("currently runs daily schedules hourly instead") rather than calling it a "bug", which reads punchy on a public docs page.

* docs: add Known server-side limitations section Add a new user-facing section to docs/api-ref.md that lists behaviors users may hit that are constrained by the Tableau Server REST API rather than by TSC. Each entry links its tracking issue and notes where the fix is expected to land. Cross-link the new section from the top-of-page note, and point at the `Server-Side Enhancement` label as the live tracker maintained by this repo. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: drop internal work-item IDs and per-bullet fix-scope tag Public docs on gh-pages will be indexed, so remove the internal work-item numbers (W-...) from the Known server-side limitations section along with the paragraph that described what they were. Also strip the redundant per-bullet "Fix expected: server-side" tag: the section title already scopes the whole list to server-side gaps. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Drop On Extract Refresh entry, soften intro and daily-schedule wording Three fresh-eyes findings: - Remove the "Subscriptions cannot use On Extract Refresh" entry. The REST API's refreshExtractTriggered attribute does support this, and TSC support is landing in #1861 (which closes the tracker #1658). The entry is about to be factually wrong on both counts. - Soften the intro: it promised "follow the appropriate issues" for every item, but the vf_-silently-dropped entry has no tracker filed. New wording says "where filed" so the doc doesn't overpromise. - Reword the daily-schedules note to describe behavior neutrally ("currently runs daily schedules hourly instead") rather than calling it a "bug", which reads punchy on a public docs page. * Drop the vf_ exact-match limitation entry Opus-5 review found the entry's tracker link (#1431) points at a closed-not-planned issue; the underlying gap was filed with the Tableau REST API docs team internally and there's no realistic timeline for it being tracked back in the TSC repo. Rather than carry an untracked entry indefinitely, drop it. The behavior claim (vf_ is exact-match / OR-list only) is now covered by the expanded docstring on RequestOptions.vf() in #1840. --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Round of fixes for the sample-scripts refactor after fresh-eyes review. Blocker: publish_workbook.py reused `-u` for --thumbnails-user-id while _shared.py add_common_arguments already binds `-u` to --username, so argparse raised ArgumentError on module load and the script would not start. Renamed to `-U`. Real bugs: - _shared.py .env search now checks cwd, samples/, and repo root (in that order) so the docstring stops lying about "next to the sample or cwd." - resolve_credentials now gates input()/getpass on sys.stdin.isatty() as the docstring already promised, so piped/CI invocations no longer hang forever. - manage_subscriptions.py --attach-image switched to argparse.BooleanOptionalAction so users can actually pass --no-attach-image; the previous store_true+default=True made the flag a permanent True. - Header docstring in _shared.py no longer claims "no existing command line breaks" (which was false: -p migrated from --token-name to --password in an earlier commit). Documented the tabcmd-aligned short flags instead. - Corrected Python-version headers on login.py, list_jobs.py, manage_subscriptions.py, publish_workbook.py, refresh_tasks.py, move_workbook_sites.py, publish_datasource.py, and update_workbook_data_freshness_policy.py -- repo floor is 3.10 per pyproject.toml. - list_jobs._wait_for_job: reordered excepts so JobCancelledException (a subclass of JobFailedException) is caught first, otherwise cancelled jobs were reported as failed with the wrong exit code. - login.py sign-in banner now branches on JWTAuth as well, so JWT logins no longer print "Username: None". Header env-var list updated to include TABLEAU_JWT / TABLEAU_JWT_FILE. New JWT support: _shared.py add_common_arguments now exposes --jwt and --jwt-file, resolves TABLEAU_JWT / TABLEAU_JWT_FILE from env, reads a JWT file path into args.jwt during resolve_credentials, and returns TSC.JWTAuth from build_auth when a JWT is present. JWT takes priority over PAT and username/password. Extract-refresh subscription: manage_subscriptions.py create now accepts --on-extract-refresh, which calls SubscriptionItem.on_extract_refresh() to construct a subscription that fires when the referenced extract-refresh schedule completes (the flow introduced in #1861). Rebased this branch onto jac/subscription-refresh-extract-triggered so the flag lands on top of the new API without conflicts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

jacalata requested a lite review from Copilot August 17, 2026 20:03

Copilot started reviewing on behalf of jacalata August 17, 2026 20:04 View session

Copilot AI reviewed Aug 17, 2026

View reviewed changes

Comment thread tableauserverclient/server/endpoint/subscriptions_endpoint.py Outdated

Navigation Menu

Uh oh!

Expose refreshExtractTriggered on SubscriptionItem - #1861

Expose refreshExtractTriggered on SubscriptionItem#1861
jacalata wants to merge 2 commits into
developmentfrom
jac/subscription-refresh-extract-triggered

jacalata commented Aug 16, 2026

Uh oh!

github-actions Bot commented Aug 16, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

jacalata commented Aug 16, 2026

Summary

What changes

Compatibility note

Test plan

Uh oh!

github-actions Bot commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Aug 16, 2026 •

edited

Loading