diff --git a/docs/app/admin/ExternalPlatform.mdx b/docs/app/admin/ExternalPlatform.mdx index 5e465540..d94c831a 100644 --- a/docs/app/admin/ExternalPlatform.mdx +++ b/docs/app/admin/ExternalPlatform.mdx @@ -36,6 +36,7 @@ Some examples of tools that can be connected to Ganymede using this approach inc - [Spotfire](https://community.spotfire.com/articles/spotfire/spotfire-and-odbc-data-sources/) - Follow instructions for connecting to an ODBC data source using the [Simba BigQuery ODBC driver](https://cloud.google.com/bigquery/docs/reference/odbc-jdbc-drivers). - [JMP](https://community.jmp.com/t5/Discussions/ODBC-connection-to-Google-BigQuery/td-p/346253) - Establish a connection to BigQuery using the [Simba BigQuery ODBC driver](https://cloud.google.com/bigquery/docs/reference/odbc-jdbc-drivers). - [MATLAB](https://github.com/mathworks-ref-arch/matlab-google-bigquery/blob/main/Documentation/Authentication.md) - Provide service account credentials using the matlab-google-bigquery package. +- [Mathematica](https://mathematica.stackexchange.com/questions/231524/generating-google-bigquery-api-access-token-in-wolfram-language) - Generate a JSON Web Token (JWT) using the service account credentials in Ganymede. Alternatively, you can use a [BigQuery JDBC Driver](https://cloud.google.com/bigquery/docs/reference/odbc-jdbc-drivers) to connect, as described in this [reference doc](https://reference.wolfram.com/language/DatabaseLink/tutorial/DatabaseConnections.html). - [Excel](https://cloud.google.com/blog/products/bigquery/how-to-connect-bigquery-to-microsoft-excel-and-other-apps-with-our-new-odbc-driver) - Install the [Simba BigQuery ODBC driver](https://cloud.google.com/bigquery/docs/reference/odbc-jdbc-drivers) and reference the data source from Excel. ### Generating Service Account Credentials diff --git a/docs/app/agents/AgentInstall.mdx b/docs/app/agents/AgentInstall.mdx index 316fdda0..dcea03c8 100644 --- a/docs/app/agents/AgentInstall.mdx +++ b/docs/app/agents/AgentInstall.mdx @@ -101,7 +101,7 @@ There may be a slight delay as the service connection resumes. 1. Navigate to the Connections pane in the Ganymede app by selecting the
icon in the left toolbar and selecting the Connections pane. 2. Find the Connection you just created. Click the
**Edit Connections**
button at the bottom right of the Connection Settings -3. Click
Add File Tag
to open the file tag popup. +3. Click
Add file tag
to open the file tag popup. 1. Select the appropriate Tag Type Name from the dropdown 2. Add a Display Value which will appear next to each file uploaded to Ganymede via this Connection 1. Optionally, specify a Tag ID to associate with the tag. This is generally only used in situations where a non-human interpretable values to identify the tag programmatically diff --git a/docs/app/agents/QuickstartBuildAgent.mdx b/docs/app/agents/QuickstartBuildAgent.mdx index 15150b85..7950b6bb 100644 --- a/docs/app/agents/QuickstartBuildAgent.mdx +++ b/docs/app/agents/QuickstartBuildAgent.mdx @@ -2,11 +2,12 @@ id: QuickstartBuildAgent title: Build an Agent + Configure a Connection displayed_sidebar: webUiSidebar +toc_max_heading_level: 4 --- -import { BellOutlined, DownloadOutlined, PlusOutlined, UserOutlined } from '@ant-design/icons'; +import { BellOutlined, DownloadOutlined, PlusOutlined, UserOutlined, EditOutlined } from '@ant-design/icons'; -This guide will walk you through the process of creating an Agent to capture and process data from a local instrument PC. You'll create one Connection by installing the Agent on a local PC. +This guide will walk you through the process of creating an Agent to capture and process data from a local instrument PC. You'll create one Connection by installing the Agent on a local Windows machine.
Agent @@ -109,7 +110,7 @@ To check this configuration, verify the input_path variable on the Connections p
  -Choose the desired installation location and proceed through the installer to complete the installation. The default installation location is "C:\Program Files\Ganymede", but if you intend to install multiple Agents on the same PC, you should install each one in a separate subdirectory directory e.g. "C:\Program Files\Ganymede\QuickstartAgent". +Choose the desired installation location and proceed through the installer to complete the installation.
Agent installation location @@ -127,11 +128,37 @@ Choose the desired installation location and proceed through the installer to co
  -The Agent will launch automatically once installation is complete. +The Agent Connection will launch automatically once installation is complete. -### Step 4: Test the agent +### Step 4: Configure Tags for the Connection -Drop the [sample plate reader file](https://github.com/Ganymede-Bio/website-docusaurus/raw/main/PlateReader.xlsx) into the "watch_folder" created in [step 3b](#step-3b-create-a-folder-to-monitor). The agent will detect the file and upload it to the Ganymede Flow for processing. +#### Step 4a: Configure a Tag Type + +Navigate to the Ganymede web app. Click on the Files tab in the sidebar of the Ganymede application and select the "Manage Tag Types" tab. Configure a new tag type with the name "Instrument" and the description "The name of the instrument type", similar to what is shown below: + +
+Agent installation completion +
+  + +#### Step 4b: Configure Connection for Tags + +Navigate to the Connections tab in the sidebar and confirm that your Agent Connection is Online. Click on the Connection name to open the Connection details page. In the Connection Settings box, click on
Edit Connections
, followed by
Add file tag
. Select the "Instrument" tag that you have just created and the value "Plate Reader" to the Connection, click Add Tag, and then Save the configuration. + +
+Add Tag +
+  + +:::info + +Tags are useful for ensuring raw files retain experiment, user, sample, or other metadata. A list of potential tags of interest can be found on the [Suggested Tag Types](../files/SuggestedTags.mdx) page. + +::: + +### Step 5: Test the Connection + +On the instrument PC, drop the [sample plate reader file](https://github.com/Ganymede-Bio/website-docusaurus/raw/main/PlateReader.xlsx) into the "watch_folder" created in [step 3b](#step-3b-create-a-folder-to-monitor). The agent will detect the file and upload it to the Ganymede Flow for processing. Any window with the environment open will display that the Flow has been initiated. Congratulations on creating your first Agent! diff --git a/docs/app/files/SuggestedTags.mdx b/docs/app/files/SuggestedTags.mdx new file mode 100644 index 00000000..5b3fb18e --- /dev/null +++ b/docs/app/files/SuggestedTags.mdx @@ -0,0 +1,31 @@ +--- +id: SuggestedTags +title: Suggested Tags +displayed_sidebar: webUiSidebar +--- + +This page contains a list of potential tag types to use with captured files in your Ganymede environment to facilitate data organization and searchability. + +For more detail on how to add tags to your files, see the [Tagging Files](./Tags#tagging-files) page. + +For more detail on how to search for files using tags, see the [Searching for Files](./FileBrowser#finding-files) page. + +### Agent-Level Tag Types + +| Type | Description | Example | +|------|-------------|---------| +| Instrument | The name of the instrument type | AKTA Pure 25 L | +| Instrument Type | Type / category of the instrument that's generating data | Chromatography System +| Vendor | Manufacturer of Instrument | Cytiva | + +### Connection-Level Tag Types + +| Type | Description | Example | +|------|-------------|---------| +| Program/Function | The program function where the instrument is used, but the same across all connections of that agent | Analytical Dev | +| User | The user name is listed in file | Callie Saren | +| Unit of Account | The metadata (Sample ID, Plate ID, etc) for the file, if listed in file name or within file (can only pick one unit, recommend higher level unit) | Sample1234 | +| Unit of Account Type | Depending on above, set type (sample, plate, etc.) | Sample | +| Software | Tags instrument software based on file type | .mqd (MacsQuantify), .wsp (FlowJo) | +| Instrument ID/Serial Number | The identifier of the specific instance that is connected | ID24292 | +| Location | The lab location of the instrument | Building 4 | diff --git a/docs/app/files/Tags.mdx b/docs/app/files/Tags.mdx index 52d52b40..47d1dda7 100644 --- a/docs/app/files/Tags.mdx +++ b/docs/app/files/Tags.mdx @@ -2,8 +2,11 @@ id: Tags title: Tagging Files displayed_sidebar: webUiSidebar +toc_max_heading_level: 4 --- +import { PlusOutlined, EditOutlined } from '@ant-design/icons'; + ## What are File Tags? File tags in Ganymede provide a way to organize and categorize files systematically. These tags, specified in user-defined code, allow for efficient filtering and searching within the file browser. Tags can be used to capture various details about a file, such as sample ID, run purpose, experiment ID, experiment step, and any other relevant characteristic defined by users in Ganymede. @@ -15,7 +18,7 @@ Once a file is tagged, it can be easily filtered in the file browser, enabling s   -### Configuring File Tag Types +## Configuring File Tag Types Before tagging files, a file tag type must be configured. This is done in the **Manage Tag Types** section on the Files page. @@ -41,13 +44,13 @@ For each tag type, the following attributes can be specified: The strict mode setting, if disabled, allows admins to delete or modify tags. Tags may only be deleted if they are not applied to any files; the delete button will be grayed out if tag type deletion is not permitted. -### Tagging Files +## Tagging Files -Files can be tagged in user-defined code within flows and Agents, though the methods differ slightly. In flows, files are tagged by passing the file path to the `add_file_tag` function. Within Agents, files are tagged by passing the [FileParam](../../sdk/markdowns/AgentSDK#agent-triggered-flows) object into the `add_file_tag_to_fileparam` function. The FileParam object contains the file that the Agent submits to Ganymede storage (for initiating a flow if the Agent is configured to do so). +Files can be tagged in user-defined code within Flows and Agents, though the methods differ slightly. In Flows, files are tagged by passing the file path to the `add_file_tag` function. Within Agents, files are tagged either in the Connections UI, or by passing the [FileParam](../../sdk/markdowns/AgentSDK#agent-triggered-flows) object into the `add_file_tag_to_fileparam` function. The FileParam object contains the file that the Agent submits to Ganymede storage (for initiating a flow if the Agent is configured to do so). -The full set of methods available for interacting with tags can be found on the [File Tag](../../sdk/FileTags.mdx) module in the SDK documentation. +The full set of methods available for programmatically interacting with tags can be found on the [File Tag](../../sdk/FileTags.mdx) module in the SDK documentation. -#### Tagging files in Flows +### Tagging files in Flow code To tag a file within a flow, use the `add_file_tag` function in the `ganymede_sdk.file_tag` module. This function takes the following arguments: @@ -103,7 +106,20 @@ def execute(file_data: Dict[str, bytes], ganymede_context) -> NodeReturn: ) ``` -#### Tagging files in Agents or Connections +### Tagging files captured by Agents + +#### From the Connections UI + +To configure file tagging from the Connections UI, navigate to the relevant Connection on the Connections page. In the Connection Settings box, click on
Edit Connections
, followed by
Add file tag
. + +Doing so opens up the modal shown below, where you can specify the tag type and value to apply to files delivered by the Connection. + +
+Add Tag +
+  + +#### From Agent user-defined code To tag a file delivered by an Agent to Ganymede, you can configure an Agent or Connection to tag any files submitted from it using the [File tags parameter in Agent configuration](../agents/Agent). diff --git a/sidebars.js b/sidebars.js index 7eddc982..4f2b9241 100644 --- a/sidebars.js +++ b/sidebars.js @@ -42,7 +42,7 @@ module.exports = { { type: 'doc', id: 'app/agents/QuickstartBuildAgent', - label: 'Build an Agent' + label: 'Build an Agent / Install a Connection' }, { type: 'doc', @@ -189,6 +189,11 @@ module.exports = { type: 'doc', id: 'app/files/TagActivity', label: 'Exploring Tag Activity' + }, + { + type: 'doc', + id: 'app/files/SuggestedTags', + label: 'Suggested Tag Types' } ] },