RPA.Smartsheet
Adds a column to the current sheet.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
title | str | null | Column title. |
column_type | str | TEXT_NUMBER | Column type, must be a supported type. Defaults to TEXT_NUMBER. |
formula | str, None | None | Formula for the column (e.g., =data@row). Defaults to None. |
hidden | bool | False | Whether the column is hidden. Defaults to False. |
index | int, None | None | Index of the column. You can insert a column into and existing sheet by setting this index. Index is zero-based. Defaults to None which will add the column to the end of the sheet. |
description | str, None | None | Column description. Defaults to None. |
primary | bool | False | Whether the column is considered the primary key for indexing and searching. Defaults to False. |
format_string | str, None | None | Column format using a format descriptor string. Defaults to None. |
locked | bool | False | Whether the column is locked. Defaults to False. |
options | List[str], None | None | List of options for a PICKLIST or MULTI_PICKLIST column. Defaults to None. |
symbol | str, None | None | When a CHECKBOX or PICKLIST column has a display symbol, you can set the type of symbols by selected an appropriate string from the symbol columns definitions. Defaults to None. |
validation | bool | False | Whether validation has been enabled. Defaults to False. |
width | int, None | None | Column width in pixels. Defaults to None. |
param title: | Column title. |
---|---|
param column_type: | |
Column type, must be a supported type. Defaults to TEXT_NUMBER. | |
param formula: | Formula for the column (e.g., =data@row). Defaults to None. |
param hidden: | Whether the column is hidden. Defaults to False. |
param index: | Index of the column. You can insert a column into and existing sheet by setting this index. Index is zero-based. Defaults to None which will add the column to the end of the sheet. |
param description: | |
Column description. Defaults to None. | |
param primary: | Whether the column is considered the primary key for indexing and searching. Defaults to False. |
param format_string: | |
Column format using a format descriptor string. Defaults to None. | |
param locked: | Whether the column is locked. Defaults to False. |
param options: | List of options for a PICKLIST or MULTI_PICKLIST column. Defaults to None. |
param symbol: | When a CHECKBOX or PICKLIST column has a display symbol, you can set the type of symbols by selected an appropriate string from the symbol columns definitions. Defaults to None. |
param validation: | |
Whether validation has been enabled. Defaults to False. | |
param width: | Column width in pixels. Defaults to None. |
Examples
Adds columns to the current sheet. Columns must be defined as a list of dictionaries or Column objects. Dictionaries can have additional keys set, see Add Column keyword for more information.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
columns | List[Dict | Column], None | None | Columns as a list of dictionaries or Column objects. |
Column types must be supported by the Smartsheet API
param columns: | Columns as a list of dictionaries or Column objects. |
---|
Adds rows to the current sheet with the provided data.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
data | List, Table | null | |
native | bool | False |
You can provide the data in several ways:
- As a list of dictionaries: each list item represents a row as a single dictionary. The keys of the dictionary are the column IDs or Titles and the values are the values for the cells.
- As a list of lists of dictionaries: each sub list item is a row and each dictionary is a cell. The keys of the dictionary should match cell attributes, e.g., column_id, title, value, etc. See the smartsheet API docs for more information. The dictionary keys must be provided in snake case. You must use this method to set formulas on the row.
- As a list of native Row objects: each Row object is a native object from the API with new values for the cells.
- As a Table object: the columns of the Table must either be the column IDs or Titles.
Examples:
Robot Framework:
Python:
Converts a row object to a dictionary.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
row | Row | null |
Converts the current sheet to table. You can provide a differnt native sheet object to be converted via the sheet parameter.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
sheet | Sheet, None | None |
This keyword attempts to return the sheet as a table via RPA.Tables, but if that library is not available in this context, the sheet is returned as its native data model (e.g., no operation is performed).
If the sheet contains additional data from the include argument, they will be appended to the end of the table as additional columns in the data model. These additional objects will be attached as a list of objects depending on the items requested.
Creates a new sheet with the given name and columns, then sets the current sheet to the new sheet and returns it as a native Smartsheet object.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
name | str | null | Name of the new sheet. |
columns | List[Dict | Column], None | None | List of columns to create in the new sheet. |
from_sheet_id | int, str, None | None | Sheet ID to use as a template for the new sheet. |
param name: | Name of the new sheet. |
---|---|
param columns: | List of columns to create in the new sheet. |
param from_sheet_id: | |
Sheet ID to use as a template for the new sheet. |
Examples
Downloads the provided attachment from the currently selected sheet to the provided download_path, which defaults to the ${OUTPUT_DIR}.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
attachment | int, str, Dict, Attachment | null | An integar representing the attachment ID, a dictionary with at least the key id, or a native Attachment data model object. |
download_path | Path, str, None | None | The path to save the attachment to. |
The attachment can be provided as an integer representing the attachments ID, a dictionary with at least the key id or as the native Attachment data model type.
param attachment: | |
---|---|
An integar representing the attachment ID, a dictionary with at least the key id, or a native Attachment data model object. | |
param download_path: | |
The path to save the attachment to. |
Examples:
Robot Framework:
Python:
Gets application constants from the server. This is not necessary for most automation scenarios, but may be useful for debugging or for other advanced scenarios.
Retrieves the history of a cell in a row of the current sheet.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
row | int, Row | null | The row ID, row number, or a Row object. |
column | int, str, Column | null | The column ID or title. |
param row: | The row ID, row number, or a Row object. |
---|---|
param column: | The column ID or title. |
Examples:
Robot Framework:
Python:
Gets the current authenticated user, which is also set in the library's memory as the current user. Call this again if you switch user or begin to impersonate a user.
Returns a single row from the current sheet.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
row | int, Row | null | |
include | str, List[Any], None | None | |
exclude | str, List[Any], None | None | |
native | bool | False |
You can provide the row as a native Row object or as an integer representing the row ID.
Retrieves a sheet from Smartsheet. This keyword also sets the currently selected sheet to the returned sheet.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
sheet_id | int, None | None | The ID of the sheet to get. You cannot supply both a sheet_id and sheet_name. |
sheet_name | str, None | None | The name of the sheet to get, it will return the first sheet name matching the provided name. You cannot supply both a sheet_id and sheet_name. |
include | str, List[Any], None | None | Additional metadata which can be retrieved with the table. The list can only contain the following items: attachments, attachmentFiles, discussions, rowPermalink, or ALL. Note that attachmentFiles will only download files if you do not set native to True. |
row_ids | str, List[Any], None | None | A list of row IDs to include. All other rows will be ignored. The list can be a list object or a comma-separated list as a string. |
row_numbers | str, List[Any], None | None | A list of row numbers to include. All other rows will be ignored. The list can be a list object or a comma-separated list as a string. |
column_ids | str, List[Any], None | None | A list of column IDs to only include, others will not be returned. The list can be a list object or a comma-separated list as a string. |
filter_id | int, None | None | The ID of a filter to apply. Filtered out rows will not be included in the resulting table. |
native | bool | False | Defaults to False. Set to True to change the return type to the native Smartsheet data model. The native type is useful for passing to other keywords as arguments. |
download_path | Path, str, None | None | Defaults to None. Can be set when attachmentFiles is included in the include parameter. All attachments will be downloaded to the provided directory. |
You cannot provide both a sheet_id and sheet_name.
param sheet_id: | The ID of the sheet to get. You cannot supply both a sheet_id and sheet_name. |
---|---|
param sheet_name: | |
The name of the sheet to get, it will return the first sheet name matching the provided name. You cannot supply both a sheet_id and sheet_name. | |
param include: | Additional metadata which can be retrieved with the table. The list can only contain the following items: attachments, attachmentFiles, discussions, rowPermalink, or ALL. Note that attachmentFiles will only download files if you do not set native to True. |
param row_ids: | A list of row IDs to include. All other rows will be ignored. The list can be a list object or a comma-separated list as a string. |
param row_numbers: | |
A list of row numbers to include. All other rows will be ignored. The list can be a list object or a comma-separated list as a string. | |
param column_ids: | |
A list of column IDs to only include, others will not be returned. The list can be a list object or a comma-separated list as a string. | |
param filter_id: | |
The ID of a filter to apply. Filtered out rows will not be included in the resulting table. | |
param native: | Defaults to False. Set to True to change the return type to the native Smartsheet data model. The native type is useful for passing to other keywords as arguments. |
param download_path: | |
Defaults to None. Can be set when attachmentFiles is included in the include parameter. All attachments will be downloaded to the provided directory. |
Examples
Returns the owner's username and ID for the current sheet.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
sheet_id | int, None | None | |
sheet_name | str, None | None |
Gets a list of all attachments from the currently selected sheet.
This will include attachments to the sheet, rows, and discussions.
Examples:
Robot Framework:
Python:
Returns a list of columns for the current sheet.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
sheet_id | int, None | None | The ID of the sheet to get columns from. |
sheet_name | str, None | None | The name of the sheet to get columns from. |
param sheet_id: | The ID of the sheet to get columns from. |
---|---|
param sheet_name: | |
The name of the sheet to get columns from. |
Returns a list of available filters for the current sheet. You can specify a different sheet via the sheet_id or sheet_name parameters.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
sheet_id | int, None | None | |
sheet_name | str, None | None |
The returned list of filters can be used with the filter_id argument of the get_sheet keyword.
Examples
Lists all sheets available for the authenticated account. Uses cached lists if available unless use_cache is set to False.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
use_cache | bool | True | Defaults to True. You can set to False to force a reload of the cached list of sheets. |
The cached lists is used for other keywords, so if you need to refresh the cache for other keywords to use, you must do so via this keyword.
param use_cache: | |
---|---|
Defaults to True. You can set to False to force a reload of the cached list of sheets. |
Examples
Refreshes the current sheet from the API and returns it either as a Table or native data model depending on the native argument.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
native | bool | False |
Searches for all sheets for text matching the query. Returns a list of native Smartsheet Sheet objects. You can use the additional parameters to filter the search and increase speed.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
query | str | null | The text to search for. |
location | str, None | None | The location to search. When specified with a value of personalWorkspace, the search will be limited to the current user's personal workspace. |
modified_since | int, str, None | None | The date to search from. This can be either a string or an integer. If an integer is provided, it will be interpreted as a Unix timestamp. If a string is provided, it will be parsed via the Robot Framework time utilities, so you can provided it using keywords like NOW - 1 day. |
include | str, List[Any], None | None | When specified with the value of favoriteFlag, results will either include a favorite attribute or parentObjectFavorite attribute depending on the type of object found by the search engine. |
scopes | str, List[Any], None | None | If search fails, try using an array for each type of this comma-separated list of search filters. The following strings can be used to filter the search results: attachments: Search in attachments. cellData: Search in cell data. comments: Search in comments. folderNames: Search in folder names. reportNames: Search in report names. sheetNames: Search in sheet names. sightNames: Search in sight names. summaryFields: Search in summary fields. templateNames: Search in template names. workspaceNames: Search in workspace names. |
param query: | The text to search for. |
---|---|
param location: | The location to search. When specified with a value of personalWorkspace, the search will be limited to the current user's personal workspace. |
param modified_since: | |
The date to search from. This can be either a string or an integer. If an integer is provided, it will be interpreted as a Unix timestamp. If a string is provided, it will be parsed via the Robot Framework time utilities, so you can provided it using keywords like NOW - 1 day. | |
param include: | When specified with the value of favoriteFlag, results will either include a favorite attribute or parentObjectFavorite attribute depending on the type of object found by the search engine. |
param scopes: | If search fails, try using an array for each type of this comma-separated list of search filters. The following strings can be used to filter the search results:
|
Examples
Sets the access token to be used when accessing the Smartsheet API.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
access_token | str | null | The access token created for your Smartsheet user. |
Learn more about authenticating to Smartsheets here.
param access_token: | |
---|---|
The access token created for your Smartsheet user. |
Examples
Sets the max retry time to use when sending requests to the Smartsheet API. Returns the current max retry time.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
max_retry_time | str, int | null | Maximum time to allow retries of API calls. Can be provided as a time string or int. |
param max_retry_time: | |
---|---|
Maximum time to allow retries of API calls. Can be provided as a time string or int. |
Updates a single row of the current sheet with the provided data.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
row | int, Row | null | |
data | Dict, List[Dict], Row, None | None | |
native | bool | False |
You can provide the row as a native Row object or as an integer representing the row ID. You may omit the data argument if you are providing a native Row object.
You can provide the data in several ways:
- As a dictionary: the keys of the dictionary are the column IDs or Titles and the values are the values for the cells.
- As a list of dictionaries: each dictionary is a cell. The keys of the dictionary should match cell attributes, e.g., column_id, title, value, etc. See the smartsheet API docs for more information. The dictionary keys must be provided in snake case. You must use this method to set formulas on the row.
- As a native Row object: a native object from the API with new values for the cells.
For examples, see Set Rows.
Updates rows of the current sheet with the provided data.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
data | List, Table | null | |
native | bool | False |
Note
In order to update rows, you must identify the rows to the API. You can do this by providing the rowId or rowNumber as a column in the data. The ID must be the API ID, while the number is the row number per the UI. This can only be excluded if the length of the data matches the length of the sheet.
You can provide the data in several ways:
- As a list of dictionaries: each list item represents a row as a single dictionary. The keys of the dictionary are the column IDs or Titles and the values are the values for the cells.
- As a list of lists of dictionaries: each sub list item is a row and each dictionary is a cell. The keys of the dictionary should match cell attributes, e.g., column_id, title, value, etc. See the smartsheet API docs for more information. The dictionary keys must be provided in snake case. You must use this method to set formulas on the row.
- As a list of native Row objects: each Row object is a native object from the API with new values for the cells.
- As a Table object: the columns of the Table must either be the column IDs or Titles.
Examples:
Robot Framework:
Python:
Resets the current sheet to None.
Updates a column in the current sheet. See the Add Column keyword for a list of supported attributes.
Arguments
Argument | Type | Default value | Description |
---|---|---|---|
column | int, str, Column | null | Column ID or title. |
kwargs | null | Column attributes to update. See Add Column keyword for a list of supported attributes. |
param column: | Column ID or title. |
---|---|
param kwargs: | Column attributes to update. See Add Column keyword for a list of supported attributes. |