Skip to content

Update & Extend documentation #1078

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bcantoni merged 4 commits into from
Aug 6, 2022
Merged

Update & Extend documentation #1078

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
31015f3
update/fix some documentation aspects
bossenti Jul 23, 2022
3e64006
provide documentation for `schedules.add_to_schedule()`
bossenti Jul 23, 2022
04ce8a6
address review comments
bossenti Jul 29, 2022
0803b97
update description of `schedule_id`
bossenti Jul 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 62 additions & 14 deletions docs/api-ref.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -256,10 +256,8 @@ The `ConnectionCredentials` class is used for workbook and data source publish r
Attribute | Description
:--- | :---
`name` | The username for the connection.
`embed_password` | (Boolean) Determines whether to embed the password (`True`) for the workbook or data source connection or not (`False`).
`embed` | (Boolean) Determines whether to embed the password (`True`) for the workbook or data source connection or not (`False`).
`password` | The password used for the connection.
`server_address` | The server address for the connection.
`server_port` | The port used by the server.
`ouath` | (Boolean) Specifies whether OAuth is used for the data source of workbook connection. For more information, see [OAuth Connections](https://help.tableau.com/current/server/en-us/protected_auth.htm).


Expand Down Expand Up @@ -562,7 +560,7 @@ None. A list of `ConnectionItem` objects are added to the data source (`datasour
#### datasources.publish

```py
datasources.publish(datasource_item, file_path, mode, connection_credentials=None)
datasources.publish(datasource_item, file, mode, connection_credentials=None, as_job=False)
```

Publishes a data source to a server, or appends data to an existing data source.
Expand All @@ -576,9 +574,10 @@ REST API: [Publish Datasource](https://help.tableau.com/current/api/rest_api/en-
Name | Description
:--- | :---
`datasource_item` | The `datasource_item` specifies the new data source you are adding, or the data source you are appending to. If you are adding a new data source, you need to create a new `datasource_item` with a `project_id` of an existing project. The name of the data source will be the name of the file, unless you also specify a name for the new data source when you create the instance. See [DatasourceItem](#datasourceitem-class).
`file_path` | The path and name of the data source to publish.
`file` | The file path or file object of the data source to publish.
Comment thread
bcantoni marked this conversation as resolved.
`mode` | Specifies whether you are publishing a new data source (`CreateNew`), overwriting an existing data source (`Overwrite`), or appending data to a data source (`Append`). If you are appending to a data source, the data source on the server and the data source you are publishing must be be extracts (.tde files) and they must share the same schema. You can also use the publish mode attributes, for example: `TSC.Server.PublishMode.Overwrite`.
`connection_credentials` | (Optional) The credentials required to connect to the data source. The `ConnectionCredentials` object contains the authentication information for the data source (user name and password, and whether the credentials are embedded or OAuth is used).
`as_job` | (Optional) If this value is set to `True`, the publish operation will be asynchronous and return a JobItem.



Expand Down Expand Up @@ -2655,7 +2654,7 @@ Source file: models/schedule_item.py
Name | Description
:--- | :---
`name` | The `name` of the schedule.
`id` | The identifier for the schedule. Use the `schedules.get()` method to get the identifiers of the schedules on the server.
`priority` | The priority of the schedule (integer). Lower values represent higher priorities, with `0` indicating the highest priority.
`schedule_type` | The type of task. The types are either an `Extract` for an extract refresh task or a `Subscription` for a scheduled subscription.
`execution_order` | Specifies how the scheduled task should run. The choices are `Parallel`which uses all available background processes for this scheduled task, or `Serial`, which limits this schedule to one background process.
`interval_item` | Specifies the frequency that the scheduled task should run. The `interval_item` is an instance of the `IntervalItem` class. The `interval_item` has properties for frequency (hourly, daily, weekly, monthly), and what time and date the scheduled item runs. You set this value by declaring an `IntervalItem` object that is one of the following: `HourlyInterval`, `DailyInterval`, `WeeklyInterval`, or `MonthlyInterval`.
Expand Down Expand Up @@ -2683,10 +2682,59 @@ The schedule methods are based upon the endpoints for schedules in the REST API

Source files: server/endpoint/schedules_endpoint.py

#### schedule.create
#### schedules.add_to_schedule

```py
schedules.add_to_schedule(schedule_id, workbook=None, datasource=None, flow=None, task_type=None)
```

Adds a `DatasourceItem`, `FlowItem`, or `WorkbookItem` to a schedule.


REST API: [Add Data Source to Schedule](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#add_data_source_to_schedule)



**Parameters**

Name | Description
:--- | :---
`schedule_id` | The identifier (id) of the schedule to add the data source or workbook to. Can be retrieved from a `ScheduleItem`, e.g., by performing `schedules.get()`.
`workbook` | (Optional) A `WorkbookItem` that should be added to the schedule. Only provide either `workbook` or `datasource`, passing multiple items will be deprecated.
`datasource` | (Optional) A `DatasourceItem` that should be added to the schedule. Only provide either `workbook` or `datasource`, passing multiple items will be deprecated.
`flow` | (Optional) A `FlowItem` that should be added to the schedule. Only applicable if `workbook = None` and `datasource = None`.
`task_type` | (Optional) Determines the type of task. One of `TaskItem.Type`: `ExtractRefresh`, `DataAcceleration`, `RunFlow`.


**Returns**
Returns a List of `AddResponses`.


**Example**

```py
import tableauserverclient as TSC
# sign in, etc.
# get a datasource item that should be added to a schedule
datasource_item = server.datasources.get("d14dd951-01c1-4879-8bc2-e96d7dec9f0")

# retrieve the id of the target schedule
schedule_id = schedule_item.id # can be a freshly created schedule or one queried via `schedules.get()`

# Add the data source to the schedule
server.schedules.add_to_schedule(
schedule_id=schedule_id,
datasource=datasource_item,
)
```
<br>
<br>


#### schedules.create

```py
schedule.create(schedule_item)
schedules.create(schedule_item)
Comment thread
bcantoni marked this conversation as resolved.
```
Creates a new schedule for an extract refresh or a subscription.

Expand Down Expand Up @@ -2731,10 +2779,10 @@ import tableauserverclient as TSC
<br>


#### schedule.delete
#### schedules.delete

```py
schedule.delete(schedule_id)
schedules.delete(schedule_id)
```

Deletes an existing schedule for an extract refresh or a subscription.
Expand Down Expand Up @@ -2762,10 +2810,10 @@ Error | Description
`Schedule ID undefined` | The identifier is not a valid identifier for a schedule on the server.


#### schedule.get
#### schedules.get

```py
schedule.get([req_options=None])
schedules.get([req_options=None])
```

Returns all schedule items from the server.
Expand All @@ -2781,7 +2829,7 @@ Name | Description
:--- | :---
`req_options` | (Optional) Additional request options to send to the endpoint.

#### schedule.update
#### schedules.update

<br>
<br>
Expand Down Expand Up @@ -5100,7 +5148,7 @@ Name | Description
`workbook_item` | The `workbook_item` specifies the workbook you are publishing. When you are adding a workbook, you need to first create a new instance of a `workbook_item` that includes a `project_id` of an existing project. The name of the workbook will be the name of the file, unless you also specify a name for the new workbook when you create the instance. See [WorkbookItem](#workbookitem-class).
`file_path` | The path and name of the workbook to publish.
`mode` | Specifies whether you are publishing a new workbook (`CreateNew`) or overwriting an existing workbook (`Overwrite`). You cannot appending workbooks. You can also use the publish mode attributes, for example: `TSC.Server.PublishMode.Overwrite`.
`connections` | List of `ConnectionCredentials` objects for the connections created within the workbook.
`connections` | List of `ConnectionItems` objects for the connections created within the workbook.
`connection_credentials` | (Optional) The credentials (if required) to connect to the workbook's data source. The `ConnectionCredentials` object contains the authentication information for the data source (user name and password, and whether the credentials are embedded or OAuth is used). **Deprecated since API server version 2.3.**
`skip_connection_check` | (Optional) Set to `True` to skip connection check at time of upload. Publishing will succeed but unchecked connection issues may result in a non-functioning workbook. Defaults to `False`.
`as_job` | (Optional) Set to `True` to run the upload as a job (asynchronous upload). If set to `True` a job will start to perform the publishing process and a `Job` object is returned. Defaults to `False`.
Expand Down