Widgets

Point a widget at another connection

Changes which connection and which account ONE widget reads through, in the reports that bind their data sources per widget -- the ones whose report_level_data_sources is false. A report that binds once for the whole report has no per widget connection to set and is rebound with the data_sources of /v1/reports/update; this call is refused on it with 400 APPEND_NOT_ALLOWED and reason report_level_data_sources.

It writes two columns and reads the rest of the widget from its row: the definition, the format, the titles of its columns, its notes and its place are untouched. The cached results of the widget are dropped with the change, so it reads the new account at once.

The connection has to be one of the integration the widget already reads: the source of a widget that exists never changes. Every call keeps the widget as it was first and answers with the backup_key /v1/widgets/restore puts back, for 7 days -- that restore puts back the DEFINITION and leaves the connection the widget has at that moment, so the undo of this call is another call to it.

Refusals: 400 for the framework and the body, 400 APPEND_NOT_ALLOWED with reason report_level_data_sources or template_based, 400 INVALID_VALUE when the widget reads no data source at all, 400 CONNECTION_NOT_FOUND or ACCOUNT_NOT_FOUND when the pair is not one /v1/connections publishes, 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND, 409 WIDGET_NOT_EDITABLE when the widget reads several connected accounts at once (reason COMPARES_ACCOUNTS) or is a cross-platform widget that reads an accounts group, which brings the connections of its data sources (reason READS_ACCOUNTS_GROUP), 409 WIDGET_CHANGED when if_widget_hash is stale or when the widget changed after the call read it (nothing is written and no backup is kept), and 409 REPORT_IN_TRASH.

Every write endpoint reads dry_run and idempotency_key; see the Write guarantees section of the introduction.

post/widgets/set-connection

Request

  • Base URL: https://api.reportingninja.com/v1
  • URL: https://api.reportingninja.com/v1/widgets/set-connection
  • Auth: HTTP bearer

Request body

report_keystring required

The report the widget belongs to. Its report_level_data_sources has to be false: a report that binds once for the whole report is rebound with the data_sources of /v1/reports/update.

section_keystring required

The section the widget is in.

widget_keystring required

The widget to rebind.

connection_keystring required

The connection the widget reads through, from /v1/connections. It has to be one of the integration the widget already reads: the source of a widget that exists never changes.

account_idstring required

The account within that connection, checked against the accounts /v1/connections publishes for it.

dry_runboolean

Validate and answer what WOULD happen, without writing anything. Default false.

idempotency_keystring

Makes a retry safe: the answer of the first call is replayed for 24 hours to any later call with the same key and the same body.

if_widget_hashstring

The widget_hash /v1/widgets/get published for this widget. A stale one is HTTP 409 WIDGET_CHANGED; read the widget again and retry with the new hash AND THE SAME idempotency_key.

Response

The call succeeded. This endpoint reports its errors with a real HTTP status, so a 200 always carries status=ok.

status'ok' required

Changes

No recorded changes to this operation across all 1 revision of this API.