| Title: | R Client for 'Via Foundry' API |
|---|---|
| Description: | 'Via Foundry' API provides streamlined tools for interacting with and extracting data from structured responses, particularly for use cases involving hierarchical data from Foundry's API. It includes functions to fetch and parse process-level and file-level metadata, allowing users to efficiently query and manipulate nested data structures. Key features include the ability to list all unique process names, retrieve file metadata for specific or all processes, and dynamically load or download files based on their type. With built-in support for handling various file formats (e.g., tabular and non-tabular files) and seamless integration with API through authentication, this package is designed to enhance workflows involving large-scale data management and analysis. Robust error handling and flexible configuration ensure reliable performance across diverse data environments. Please consult the documentation for the API endpoint for your installation. |
| Authors: | Alper Kucukural [aut, cre], Via Scientific [aut, cph] |
| Maintainer: | Alper Kucukural <[email protected]> |
| License: | Apache License 2.0 |
| Version: | 1.0.1 |
| Built: | 2026-06-02 09:38:38 UTC |
| Source: | https://github.com/viascientific/viafoundry-r-sdk |
Adds file metadata to a dataset.
addFilesToDataset(datasetID, fileData)addFilesToDataset(datasetID, fileData)
datasetID |
The dataset ID. |
fileData |
A named list of file metadata. |
A JSON object confirming file addition.
Authenticates the user with the 'Via Foundry API' using either a personal access token or username and password. Retrieves a bearer token and saves it along with the 'API url' to a configuration file.
authenticate( hostname = NULL, username = NULL, password = NULL, token = NULL, identity_type = 1, redirect_uri = "http://localhost", config_path = DEFAULT_CONFIG_PATH, overwrite = FALSE )authenticate( hostname = NULL, username = NULL, password = NULL, token = NULL, identity_type = 1, redirect_uri = "http://localhost", config_path = DEFAULT_CONFIG_PATH, overwrite = FALSE )
hostname |
The API URL (optional in interactive mode; will prompt if not provided). |
username |
The login username (optional; used with password authentication). |
password |
The login password (optional; will prompt if not provided). |
token |
Personal access token (optional; recommended for security). |
identity_type |
The identity type (default is 1). |
redirect_uri |
The redirect 'URI'. |
config_path |
Path to save the configuration file. |
overwrite |
Logical flag to overwrite the existing configuration file (default is FALSE). |
Invisibly returns the configuration list containing hostname and bearer_token.
## Not run: # Using token authentication (recommended) authenticate( hostname = "https://your_foundry_server", token = "your-personal-access-token", config_path = "~/.viaenv", overwrite = TRUE ) # Using username/password authentication authenticate( hostname = "https://your_foundry_server", username = "username", password = "password", config_path = "~/.viaenv", overwrite = TRUE ) ## End(Not run)## Not run: # Using token authentication (recommended) authenticate( hostname = "https://your_foundry_server", token = "your-personal-access-token", config_path = "~/.viaenv", overwrite = TRUE ) # Using username/password authentication authenticate( hostname = "https://your_foundry_server", username = "username", password = "password", config_path = "~/.viaenv", overwrite = TRUE ) ## End(Not run)
Configure authentication using a pre-generated personal access token. This is a convenience function for token-only authentication.
authenticate_token( hostname, token, config_path = DEFAULT_CONFIG_PATH, overwrite = TRUE )authenticate_token( hostname, token, config_path = DEFAULT_CONFIG_PATH, overwrite = TRUE )
hostname |
The API url. |
token |
Personal access token. |
config_path |
Path to save the configuration file. |
overwrite |
Logical flag to overwrite the existing configuration file (default is TRUE). |
Invisibly returns the configuration list containing hostname and bearer_token.
## Not run: authenticate_token( hostname = "https://your_foundry_server", token = "your-personal-access-token" ) ## End(Not run)## Not run: authenticate_token( hostname = "https://your_foundry_server", token = "your-personal-access-token" ) ## End(Not run)
Calculate expiration date (30 days from now)
calculate_expiration_date()calculate_expiration_date()
The expiration date as a string.
Sends an HTTP request to a specified API endpoint using the stored bearer token for authentication, optionally supporting file uploads.
call_endpoint(method, endpoint, params = list(), data = NULL, files = NULL)call_endpoint(method, endpoint, params = list(), data = NULL, files = NULL)
method |
The HTTP method (e.g., "GET", "POST", "PUT", "DELETE"). |
endpoint |
The API endpoint. |
params |
A named list of query parameters (optional). |
data |
A named list or 'JSON' object to include in the request body (optional). |
files |
A list of files to upload, where each file is a named list with 'name', 'path', and optionally 'type'. |
A list containing the API response.
## Not run: response <- call_endpoint("POST", "/api/projects/upload", files = list( list(name = "file1", path = "path/to/file1.txt", type = "text/plain"), list(name = "file2", path = "path/to/file2.csv", type = "text/csv") )) print(response) ## End(Not run)## Not run: response <- call_endpoint("POST", "/api/projects/upload", files = list( list(name = "file1", path = "path/to/file1.txt", type = "text/plain"), list(name = "file2", path = "path/to/file2.csv", type = "text/csv") )) print(response) ## End(Not run)
Checks if a process is used in pipelines or runs.
checkProcessUsage(processID)checkProcessUsage(processID)
processID |
The ID of the process. |
A JSON object indicating usage information.
Create Canvas
createCanvas(canvasData)createCanvas(canvasData)
canvasData |
A named list with canvas details. |
A JSON object with the created canvas.
## Not run: canvasData <- list( name = "new_canvas", label = "New canvas" ) createCanvas(canvasData) ## End(Not run)## Not run: canvasData <- list( name = "new_canvas", label = "New canvas" ) createCanvas(canvasData) ## End(Not run)
Create Collection
createCollection(collectionData)createCollection(collectionData)
collectionData |
A named list with collection details. |
A JSON object with the created collection.
Create Field
createField(fieldData)createField(fieldData)
fieldData |
A named list with field details. |
A JSON object with the created field.
Creates a new menu group.
createMenuGroup(name)createMenuGroup(name)
name |
The name of the menu group to create. |
A JSON object containing the created menu group details.
Creates a new parameter with the given data.
createParameter(parameterData)createParameter(parameterData)
parameterData |
A list containing the parameter data. |
A JSON object containing the created parameter details.
Creates a new process using the provided data.
createProcess(processData)createProcess(processData)
processData |
A list containing the process data. |
A JSON object containing the created process details.
Assembles a complete process configuration object.
createProcessConfig( name, menuGroupName, inputParams, outputParams, summary = "", scriptBody = "", scriptLanguage = "bash", scriptHeader = "", scriptFooter = "", permissionSettings = list(viewPermissions = 3, writeGroupIds = list()), revisionComment = "Initial revision" )createProcessConfig( name, menuGroupName, inputParams, outputParams, summary = "", scriptBody = "", scriptLanguage = "bash", scriptHeader = "", scriptFooter = "", permissionSettings = list(viewPermissions = 3, writeGroupIds = list()), revisionComment = "Initial revision" )
name |
Name of the process. |
menuGroupName |
Name of the menu group. |
inputParams |
A list of input parameter specs. |
outputParams |
A list of output parameter specs. |
summary |
Optional. Summary string. |
scriptBody |
Optional. Script body. |
scriptLanguage |
Optional. Language (default "bash"). |
scriptHeader |
Optional. Script header. |
scriptFooter |
Optional. Script footer. |
permissionSettings |
Optional. A list of permission settings. |
revisionComment |
Optional. Revision comment. |
A list representing the full process config.
Delete canvas
deleteCanvas(canvasID)deleteCanvas(canvasID)
canvasID |
A character string with canvas ID. |
A confirmation object or message.
## Not run: canvasData <- list( name = "new_canvas", label = "New canvas" ) createCanvas(canvasData) search_params <- list( filter = list( name="new_canvas" ) ) canvas <- searchCanvas(search_params) deleteCanvas(canvas$data$`_id`[1]) ## End(Not run)## Not run: canvasData <- list( name = "new_canvas", label = "New canvas" ) createCanvas(canvasData) search_params <- list( filter = list( name="new_canvas" ) ) canvas <- searchCanvas(search_params) deleteCanvas(canvas$data$`_id`[1]) ## End(Not run)
Delete Collection
deleteCollection(collectionID)deleteCollection(collectionID)
collectionID |
A character string with collection ID. |
A confirmation object or message.
Deletes a data entry by ID.
deleteData(canvasID, collectionName, dataID)deleteData(canvasID, collectionName, dataID)
canvasID |
The canvas ID. |
collectionName |
The collection name. |
dataID |
The ID of the data entry. |
A JSON confirmation.
Delete Field
deleteField(fieldID)deleteField(fieldID)
fieldID |
A character string with field ID. |
A confirmation object or message.
Deletes a specific parameter by its ID.
deleteParameter(parameterID)deleteParameter(parameterID)
parameterID |
The ID of the parameter to delete. |
A confirmation message.
Deletes a specific process by its ID.
deleteProcess(processID)deleteProcess(processID)
processID |
The ID of the process to delete. |
A confirmation message.
Fetches and lists all available API endpoints from the Swagger documentation.
discover()discover()
A character vector of available endpoints.
## Not run: discover() ## End(Not run)## Not run: discover() ## End(Not run)
Creates a duplicate of an existing process.
duplicateProcess(processID)duplicateProcess(processID)
processID |
The ID of the process to duplicate. |
A JSON object containing the duplicated process details.
Fetch the 'JSON' data for a report
fetchReportData(reportID)fetchReportData(reportID)
reportID |
The ID of the report to fetch data for. |
The 'JSON' object containing the report data.
Filters parameters by name, qualifier, file type, and/or ID.
filterParameters(name = NULL, qualifier = NULL, fileType = NULL, id = NULL)filterParameters(name = NULL, qualifier = NULL, fileType = NULL, id = NULL)
name |
Optional. Name to filter. |
qualifier |
Optional. Qualifier to filter. |
fileType |
Optional. File type to filter. |
id |
Optional. ID to filter. |
A list of filtered parameters.
Sends a simple GET request to check the status of the API.
get_api_status()get_api_status()
A character vector with the API status.
## Not run: status <- get_api_status() print(status) ## End(Not run)## Not run: status <- get_api_status() print(status) ## End(Not run)
Get bearer token using the cookie token
get_bearer_token(hostname, cookie_token, name = "token")get_bearer_token(hostname, cookie_token, name = "token")
hostname |
The API url |
cookie_token |
The cookie token. |
name |
The name of the token (default is "token"). |
The bearer token.
Get headers for API requests
get_headers()get_headers()
A list of headers with the bearer token.
Recursively extract all files from deeply nested report JSON
getAllFileNames(json_data)getAllFileNames(json_data)
json_data |
The parsed report JSON returned from fetch Report Data function |
A data frame of all files and their metadata
Get unique report directories and attempt IDs for a specific report
getAllReportPaths(report_id)getAllReportPaths(report_id)
report_id |
The ID of the report. |
A character vector of unique report directories.
Get canvas
getCanvas(canvasID)getCanvas(canvasID)
canvasID |
A character string with canvas ID. |
A JSON object with canvas details.
## Not run: canvasData <- list( name = "new_canvas", label = "New canvas" ) createCanvas(canvasData) search_params <- list( filter = list( name="new_canvas" ) ) canvas <- searchCanvas(search_params) getCanvas(canvas$data$`_id`[1]) ## End(Not run)## Not run: canvasData <- list( name = "new_canvas", label = "New canvas" ) createCanvas(canvasData) search_params <- list( filter = list( name="new_canvas" ) ) canvas <- searchCanvas(search_params) getCanvas(canvas$data$`_id`[1]) ## End(Not run)
Retrieves all metadata fields for a given canvas by collecting them from each collection.
getCanvasFields(canvasID)getCanvasFields(canvasID)
canvasID |
The ID of the canvas. |
A JSON object with a list of all fields.
Get Collection
getCollection(collectionID)getCollection(collectionID)
collectionID |
A character string with collection ID. |
A JSON object with collection details.
Retrieves metadata fields by collection ID.
getCollectionFields(collectionID)getCollectionFields(collectionID)
collectionID |
The ID of the collection. |
A JSON object with a list of fields.
Retrieves a single data record by ID.
getData(canvasID, collectionName, dataID)getData(canvasID, collectionName, dataID)
canvasID |
The canvas ID. |
collectionName |
The collection name. |
dataID |
The ID of the data record. |
A JSON object with data entry.
Get Field
getField(fieldID)getField(fieldID)
fieldID |
A character string with field ID. |
A JSON object with field details.
Given a canvas ID and collection name, returns the metadata fields defined for that collection.
getFieldsForCollection(canvasID, collectionName)getFieldsForCollection(canvasID, collectionName)
canvasID |
The ID of the canvas. |
collectionName |
The name of the collection (e.g., "surveys"). |
A list of field definitions for the collection.
Get file names for a specific process
getFileNames(json_data, processName)getFileNames(json_data, processName)
json_data |
The 'JSON' object containing the report data. |
processName |
The name of the process to filter by. |
A data frame containing 'id', 'name', 'extension', 'file size', and 'route path'.
Searches for a menu group by name and returns its ID.
getMenuGroupByName(groupName)getMenuGroupByName(groupName)
groupName |
The name of the menu group. |
The ID of the menu group if found, otherwise NULL.
Retrieves the list of parameters for a specific pipeline.
getPipelineParameters(pipelineID)getPipelineParameters(pipelineID)
pipelineID |
The ID of the pipeline. |
A JSON object containing the list of parameters.
Fetches detailed information about a specific process.
getProcess(processID)getProcess(processID)
processID |
The ID of the process to retrieve. |
A JSON object containing the process details.
Get unique process names
getProcessNames(json_data)getProcessNames(json_data)
json_data |
The 'JSON' object containing the report data. |
A character vector of unique process names.
Fetches all revisions for a given process.
getProcessRevisions(processID)getProcessRevisions(processID)
processID |
The ID of the process. |
A JSON object containing the revisions.
Get directories following pub web in the route path
getReportDirs(report_id)getReportDirs(report_id)
report_id |
The ID of the report. |
A character vector of unique directories found after pub web.
Fetches all menu groups from the API.
listMenuGroups()listMenuGroups()
A JSON object containing the list of menu groups.
Fetches all parameters from the API.
listParameters()listParameters()
A JSON object containing the list of parameters.
Fetches all existing processes from the API.
listProcesses()listProcesses()
A JSON object containing the list of processes.
Loads the configuration file or triggers authentication if the file is missing.
load_config()load_config()
A list containing the host name and bearer token.
Load or download a file from a process and file name
loadFile(json_data, processName, fileName, sep = "\t", download_dir = getwd())loadFile(json_data, processName, fileName, sep = "\t", download_dir = getwd())
json_data |
The 'JSON' object containing the report data. |
processName |
The name of the process. |
fileName |
The name of the file to load or download. |
sep |
The separator for tabular files. Default is tab-separated. |
download_dir |
The directory where non-tabular files will be downloaded. |
A data frame with the file contents if the file is tabular; otherwise, NULL after downloading the file.
Login and retrieve the cookie token
login( hostname, username, password, identity_type = 1, redirect_uri = "http://localhost" )login( hostname, username, password, identity_type = 1, redirect_uri = "http://localhost" )
hostname |
The API url |
username |
The login username. |
password |
The login password. |
identity_type |
The identity type. |
redirect_uri |
The redirect URI. |
The cookie token.
Saves the current R session history to a timestamped 'R history' file.
prepareSessionHistory()prepareSessionHistory()
The file path of the saved session history file.
## Not run: history_file <- prepareSessionHistory() print(history_file) ## End(Not run)## Not run: history_file <- prepareSessionHistory() print(history_file) ## End(Not run)
Search canvas
searchCanvas(searchParams = list(filter = list()))searchCanvas(searchParams = list(filter = list()))
searchParams |
A named list of search filters. |
A JSON object with canvas search results.
## Not run: search_params <- list( filter = list( name="new_canvas" ) ) canvas <- searchCanvas(search_params) print(canvas) ## End(Not run)## Not run: search_params <- list( filter = list( name="new_canvas" ) ) canvas <- searchCanvas(search_params) print(canvas) ## End(Not run)
Search Collections
searchCollections(searchParams = list(filter = list()))searchCollections(searchParams = list(filter = list()))
searchParams |
A named list of search filters. |
A JSON object with collection search results.
Searches entries in a metadata collection.
searchData(canvasID, collectionName, filterData = list(filter = list()))searchData(canvasID, collectionName, filterData = list(filter = list()))
canvasID |
The canvas ID. |
collectionName |
The name of the collection. |
filterData |
Optional filters. |
A JSON object of matching data entries.
Lists files associated with a dataset.
searchDatasetFiles(datasetID, filterData = list(filter = list()))searchDatasetFiles(datasetID, filterData = list(filter = list()))
datasetID |
The ID of the dataset. |
filterData |
A named list of filter parameters. |
A JSON object of matching files.
Search Fields
searchFields(searchParams = list(filter = list()))searchFields(searchParams = list(filter = list()))
searchParams |
A named list of search filters. |
A JSON object with field search results.
Update canvas
updateCanvas(canvasID, updateData)updateCanvas(canvasID, updateData)
canvasID |
A character string with canvas ID. |
updateData |
A named list of canvas updates. |
A JSON object with updated canvas.
Update Collection
updateCollection(collectionID, updateData)updateCollection(collectionID, updateData)
collectionID |
A character string with collection ID. |
updateData |
A named list of collection updates. |
A JSON object with updated collection.
Updates an existing data record.
updateData(canvasID, collectionName, dataID, updateData)updateData(canvasID, collectionName, dataID, updateData)
canvasID |
The canvas ID. |
collectionName |
The collection name. |
dataID |
The ID of the data to update. |
updateData |
A named list of updates. |
A JSON object with updated entry.
Update Field
updateField(fieldID, updateData)updateField(fieldID, updateData)
fieldID |
A character string with field ID. |
updateData |
A named list of field updates. |
A JSON object with updated field.
Updates the name of an existing menu group.
updateMenuGroup(menuGroupID, name)updateMenuGroup(menuGroupID, name)
menuGroupID |
The ID of the menu group to update. |
name |
The new name of the menu group. |
A JSON object containing the updated menu group details.
Updates an existing parameter with the provided data.
updateParameter(parameterID, parameterData)updateParameter(parameterID, parameterData)
parameterID |
The ID of the parameter to update. |
parameterData |
A list containing the updated parameter data. |
A JSON object containing the updated parameter details.
Updates an existing process with the given data.
updateProcess(processID, processData)updateProcess(processID, processData)
processID |
The ID of the process to update. |
processData |
A list containing the updated process data. |
A JSON object containing the updated process details.
Upload a file to a specific report
uploadReportFile(report_id, file_path, dir = NULL)uploadReportFile(report_id, file_path, dir = NULL)
report_id |
The ID of the report for the API. |
file_path |
The local path to the file being uploaded. |
dir |
An optional directory name for organizing files. |
A list containing the server response.
Uploads the current session history to a specified report.
uploadSessionHistory(report_id, dir = NULL)uploadSessionHistory(report_id, dir = NULL)
report_id |
The ID of the report. |
dir |
The directory name for organizing session history files on the server. Defaults to 'NULL'. |
The parsed server response.
## Not run: response <- uploadSessionHistory( report_id = "12345", dir = "session_logs", ) print(response) ## End(Not run)## Not run: response <- uploadSessionHistory( report_id = "12345", dir = "session_logs", ) print(response) ## End(Not run)