1. Byosphere® Byos® Client Manual
1.1. Overview
Protein Metrics Byosphere® is a server repository where Protein Metrics Byos® projects and related files can be generated, viewed, and managed. The Byosphere Web Client is a web-based portal to load, view and manage files, project reports, folders, and jobs. The Byosphere Web Client is supported on Google Chrome, Apple Safari, Mozilla Firefox and Microsoft Edge.
The Protein Metrics Byosphere Byos Client is a client application that allows designated Users to:
- Process raw files stored on the Byosphere Server using various Byos Desktop analysis workflows.
- Inspect projects that have been saved to the Byosphere Server and modify and upload new versions.
1.2. User Privileges
Users are given access and privileges to Byosphere data when an Administrator assigns them to User Groups, which are then assigned to individual folders on the Byosphere server. There are four kinds of privileges that User Groups can be assigned that enable access to folders, files and their functions. These privileges are independent of each other and often must be assigned together.
- Viewer - User Groups given only Viewer privileges to a folder can download files from that folder. Viewers cannot upload files to or generate analyses in that folder.
- File Editor - User Groups given File Editor privileges to a folder (along with Viewer privileges) can upload files to that folder in addition to downloading files. They cannot upload folders, generate analyses, create sub-folders during file uploads, or generate reports when uploading Protein Metrics projects without additional privileges.
- Folder Editor - User Groups given Folder Editor privileges to a folder (along with File Editor and Viewer privileges) can upload folders containing files to that folder and create sub-folders under it during uploads.
- Analyst – User Groups given Analyst privileges to a folder (along with File Editor and Viewer privileges) can process, or analyze, sample files in the folder to create Protein Metrics projects through the Byosphere Byos Client. Analysts can also generate web reports when uploading Protein Metrics projects (analyses), whether projects downloaded from Byosphere or projects locally generated in Byos or other Protein Metrics applications.
Note that a special category of users called Super Users automatically have all these privileges for all files and folders. Super User privileges are assigned to users by a Byosphere Administrator.
Users with specific privileges are assigned to User Groups created by an Administrator in the Byosphere Admin Web Client. User Groups are then assigned to folders in the Byosphere Web Client by Folder Editors. Users in a User Group assigned to a folder have uniform privileges to all files in the folder.
User Group privileges are enabled or disabled by the Byosphere license. An Administrator assigns Users two kinds of entitlements from this license: product entitlements are needed to use Analyst privileges for specific Protein Metrics workflows, and role entitlements are needed to activate any privileges beyond Viewer privileges. Users who cannot exercise their assigned User Groups privileges, or who cannot submit analyses for Protein Metrics workflows they expect to have access to, should contact the Byosphere Administrator to ensure that they have the correct role or product entitlements, respectively. Users must logout and login again to enable changes made by the Administrator to their license entitlements.
1.3. Byosphere Byos Client Startup
Prior to using Byosphere, a User must have a Byosphere account. Accounts are created and managed by the Byosphere Administrator. When the Administrator creates an account (identified by a valid email address), a welcome email is sent to the User with a web link to set a password in the Byosphere Web Client.
The Byosphere Byos® Client can be accessed by clicking the following icon, which can be found on the Desktop or by searching “PMI-Byosphere-Client” in the search bar:
Figure 1.1 PMI Byosphere Byos® Client icon
Users should contact their System Administrator to download the PMIT-Byosphere-Client, which contains the Byosphere Client Application, if it is not installed already.
Once the Client launches, the user should be prompted to set up the Server address for the Client to connect to. After the address has been configured, it will remain set upon uninstallation and reinstallation However, if the user wishes to change the Server address again, this dialog can be accessed via the Server menu as mentioned below under Server > Configure.
In Byosphere, the Server menu contains the following:
Figure 1.2 Byosphere Server menu
Choose Login to access the Byosphere server. Choose Logout to close the connection. Lock is used to lock and obscure the Byosphere Byos Client screen.
Preferences sets the default download and temp directories:
Figure 1.3 Server preferences
To change the default download directory, click the 
*.pacq files. For very large files, this can consume enough disk space to potentially slow or stop processes on a C drive with limited space. If another, larger drive is available, the Temp directory should be moved to that drive. Optionally, uncheck Generate report by default if most project uploads will not require generated reports.
Configure sets the server URL address. This should be the server that the user has an account to log into:
Figure 1.4 Configure the Byosphere server
The server URL can be either the IP address or the server alias name. As a server address is typed into the cell, the expected URL is displayed below it. Click Test to confirm that Byosphere Byos Client can connect to the specified URL. The dialog will display “Connection succeeded” for valid addresses and “Connection failed” for invalid ones.
Transfer chunk size refers to the size of the blocks that a file is divided into when the file is uploaded or downloaded. A size of 1 MB is typically used.
SSO auth response timeout measures the duration of inactivity before locking the screen when Single Sign-On (SSO) is enabled. See the Single Sign-On Login section for more information.
Jobs view refresh interval allows the user to set the interval at which the jobs view refreshes automatically.
The External data sources (EDS) window shows the network drives on the user’s own computer that contain MS sample files available for use in Byosphere analyses. This section is initially configured by the Byosphere Administrator but can be edited by the user for different Path values. To edit the External data source path to a different but parallel data path as that defined by the server, double-click the entry of the path to edit and click the
Figure 1.5 Edit the External data source path
Enter the new path and click OK. The External Data Source cell updates with the new path, marked in yellow:
Figure 1.6 EDS path edited to a parallel local path
To revert to the EDS path, click the 
See the External Data Sources section for more information.
Settings sets up the Resource Cache directory and its properties:
Figure 1.7 Resource cache settings
When projects are opened from the Byosphere server to the desktop, users are given the option to also download associated sample files and other resources. These project resource files are stored in the Resource Cache for use each time any product linked to them is opened locally. Optimal cache size sets the disk space in GB set aside for storing resource files. Maximum cache size sets the space limit, beyond which older resource files are deleted. Cache location is the path to the directory that stores the files. Choose a drive that has sufficient space. The default directory listed is created if the setting is not changed. Changing the Cache location will clear the existing cache.
To access the Byosphere server, choose Server > Login:
Figure 1.8 Login to Byosphere server
Enter the user name provided by the Byosphere Administrator and the password created from the Byosphere welcome email link. Check Save user name and password to persist these entries in an encrypted file for the next time Byosphere Byos Client is opened. Uncheck Save user name and password if other users have access to this installation. The fields will be blank the next time the login dialog is opened. Click Clear credentials to remove previous user name and password entries from the encrypted file. Click Login to login to the Byosphere server. The dialog will display “Logged in successful” for valid credentials and “Network connection error” for invalid ones. The username at the top right of the Byosphere Byos Client screen displays the account username, not the Windows login username:
Figure 1.9 The Byosphere account name appears at top right
To change a Byosphere password or set one for the first time, open Byosphere in a web browser using the server URL described above. The Byosphere Web Client login dialog opens:
Figure 1.10 Login for the Byosphere Web Client
Click Forgot Password, enter the user account email and follow the directions in the email sent by the Byosphere server.
1.3.1. Single Sign-On Login
The Byosphere system may be configured for Single Sign-On (SSO) logins. When this is enabled, user credentials are not managed by Byosphere, but by a third-party identity provider, such as Active Directory. The account email used by the identity provider must match an existing Byosphere email account. Users would then login with these email accounts but also with their passwords from their identity provider service, not with the passwords managed by Byosphere.
When SSO is enable, a login to the Byosphere server opens the default web browser with a link to sign in:
Figure 1.11 SSO-enabled login
Click Sign In. The login screens that follow depend on the identify provider. The examples below use Active Directory, managing Microsoft Windows accounts:
Figure 1.12 Enter the Byosphere email account
Enter the email address shared by Byosphere and the account managed by the identity provider. In this example, click Next to move to the Password screen:
Figure 1.13 Enter the identity provider (not Byosphere) account password
Enter the password for the account managed by the identity provider, not the password managed by the Byosphere account. In this example, click Sign In:
Figure 1.14 For Microsoft Windows, choose whether to remain logged in
In this example, the User can click Yes to remain signed in when closing and reopening Byosphere Byos Client in the web browser, or click No to log out when closing the web browser.
1.4. Byosphere Byos Client Workflows
The Byosphere Byos Client processes Byos workflows to generate analyses (Protein Metrics project files) and web reports on the Byosphere server, rather than on the desktop.
The User must have Analyst privileges to a folder to generate an analysis project there. This is assigned through User Groups in the Byosphere Web Client. In addition, the User must have the correct product entitlement (such as Intact to use the Intact, Reduced or ADC workflows) and the Contributor role entitlement. Entitlements are assigned to the user by the Administrator in the Byosphere Admin Web Client.
Byosphere has the same default workflow options as Byos. To open an installed workflow, click one of the Byos workflow icons:
Figure 1.15 Byosphere Byos workflow icons
To open a custom Byos or Byosphere Byos Client workflow, choose File > Launch Workflow, navigate to and select the desired *.wflw file, and click Open. The Add sample(s) button appears under the Samples table:
Figure 1.16 Byosphere Byos Client workflow
Add sample(s) typically loads sample files from the server, although local sample files and sample files on network drives are also supported (see the Local Sample Files and External Data Sources sections, respectively). Add row adds a row without accessing the server. For example, this is used to load Trace files without associated sample files. Remove row(s) removes all selected rows. Note that local files that were stored to Byos workflows are now available for use in Byosphere analyses. However, certain types of files can only be loaded to Byosphere workflows from the server. These include trace files and report configurations.
1.4.1. Workflow Sample Files
Sample MS files are typically loaded to a workflow from the Byosphere server. To load sample raw data files to the workflow, click Add sample(s). The Choose Byosphere server file/folder dialog opens:
Figure 1.17 Choose Byosphere server file
The left panel contains all the folders available to the user in the following tabs:
- The ENT tab shows Byosphere server folders.
- The EDS (if configured) tab shows External Data Sources, network file directories mapped to the Byosphere system (see the section below).
- The Local tab shows MS files on local drives (see the section below).
The right panel contains the available sample files in the selected folder. The Choose Byosphere server file/folder dialog filters for files that contain the extension *.pacq. Sample files are compressed into the Protein Metrics proprietary *.pacq format when they are uploaded through Byosphere Byos Client. Note that sample file uploads through the Byosphere Web Client cannot be loaded into a Byosphere Byos Client workflow because they are not compressed into *.pacq format. Sample files should only be uploaded to the server through Byosphere Byos Client. For more information on Byosphere Byos Client, see the Byosphere Byos Client Uploads section.
The *.pacq compression allows consistent loading of the various combinations of the single sample files, multiple sample files or sample file directories that are supported by Protein Metrics applications. All the sample file extensions that are supported by Protein Metrics are compressed into *.pacq format upon uploading through Byosphere Byos Client. These files include: *.d, *.raw, SCIEX: *.wiff, *.wiff2, *.lcd, *.mbi, *.msfaux2, *.mzXML, and *.byspec2 files.
To load the sample files to the Byosphere workflow, select one or more and click Choose. The workflow updates with the sample files:
Figure 1.18 MS sample files added to the workflow from the Byosphere server
The text ent:file:8981_1 indicates that the record is a file from the Byosphere server with ID 8981 and version 1. The Sample name column is populated with the file name without the extension. The Traces table is populated from sample files.
1.4.1.1. Sample Metadata
Server sample files can contain metadata values. To display sample file metadata in the Samples table, first click the Metadata mappings button at the top of the workflow:
Figure 1.19 Metadata mappings button
This opens the Metadata mappings dialog. Select the desired metadata fields from the Metadata dropdown and the Samples / Custom Columns value in the Target dropdown:
Figure 1.20 Adding metadata columns to the Samples table
Click OK and the columns are added to the Samples table. When sample files are added to the table, any values in those metadata fields are displayed:
Figure 1.21 Sample file with displayed metadata column values
In addition to viewing metadata for sample files in the Sample table, sample file values from custom metadata fields containing mass (for example, Expected Mass) can be input into the Chains and Sequence combinations tables in the Sequences tab. In the Metadata mappings dialog, map the sample file mass field to the Target option Sequences / Chains Table:
Figure 1.22 Mapping a metadata field to Sequences and Chains tables
The sample file mass values are automatically input into the Chains and Sequence combinations tables in the Sequences tab:
Figure 1.23 Metadata mass value imported into the Chains and Sequence combinations tables
Users can also view and search by Metadata during file selection within the File Viewer.
Figure 1.24 Metadata in File Viewer
The radio buttons in the righthand corner allow the user to switch between Viewer and Search mode. Note that metadata values are still visible within the Viewer mode. In the Search mode, users can search through the metadata associated with samples on the enterprise server.
Figure 1.25 File Folder Search
For details about adding metadata values to sample files, see the Metadata section.
1.4.2. External Data Sources
If one or more external data source (EDS) network drives are mapped in the Byosphere system, they become available as potential sources of server MS sample files. Unlike MS sample files saved to the Byosphere server, these files are not compressed to *.pacq format. To add an MS sample file from an external data source, click Add sample(s) as before. In the Choose Byosphere server file/folder dialog, select the EDS tab. The configured EDS paths open as root directories named for their Key entries:
Figure 1.26 Choose EDS sample files filtered by same extensions as Byos does
Note that the sample raw files in EDS folders are filtered by sample file extensions. If the sample is a folder, select the parent folder and then select the sample folder on the right, not on the left:
Figure 1.27 Choose EDS sample folder
Navigate to and select one or more sample files or sample folders and click Choose. The samples are added to the workflow with the format that Byos loads local samples:
Figure 1.28 Samples table populated with EDS sample data
The MS file entry lacks the ENT file ID and the *.pacq extension. The Sample name is the MS file without an extension.
Trace files can also be loaded from external data sources. After a sample row is added (from the Add sample(s) button for an MS file or the Add sample button for Trace-only projects), double-click in the Trace files cell and click the
Figure 1.29 Choose EDS trace file filtered by same extensions as Byos does
Navigate to and select a trace file and click Choose. The trace file is added to the workflow:
Figure 1.30 Trace file loaded from an external data source
Note: Only MS files and Trace files can be added to Byosphere workflows from external data sources.
1.4.3. Local Sample Files
Local sample files and sample files in *.pacq format can be added to Byosphere workflows from the Local tab:
Figure 1.31 Choose local sample files or MS files in *.pacq format
Upon clicking Submit a job, the user is first offered the option to upload the sample file to a separate folder (Select target directory) or to the same folder chosen for the project file (Upload to the project folder):
Figure 1.32 Select the server folder for the uploaded sample files
Note: Older *.pacq sample files must be upgraded to the latest *.pacq format and saved before they can be uploaded:
Figure 1.33 Prompt to upgrade older *.pacq files
After submitting the analysis, the local sample files are first uploaded to the server in *.pacq format (if not already in this format). Then the analysis is generated with references to the uploaded server files:
Figure 1.34 The sample files upload before the analysis begins
Note: If an older *.pacq format is added, it must be updated to the latest format before it can be used in the project.
This feature allows Byos workflows containing local sample files to be opened and submitted in Byosphere Byos. Again, the local sample files will be uploaded in *.pacq format and the server project will reference those server sample files.
1.4.4. Chromeleon Sample Files
If Chromeleon 7.2 is installed and configured in Byosphere Byos, samples obtained from Chromeleon can be loaded to workflows and used to generate Byosphere analyses. To enable Chromeleon support, install Chromeleon and configure Byosphere Byos by choosing Server > Configure and open the Chromeleon tab:
Figure 1.35 Example of Chromeleon configuration in Byosphere Byos
Supply a Chromeleon download path, a Chromeleon report template URI, a Byosphere Metadata Mapping file, and check Enabled. When properly configured, the sample file chooser displays a Chromeleon tab from which to load Chromeleon samples:
Figure 1.36 An extra Chromeleon tab appears containing Chromeleon sample files
Samples are loaded into the Samples table identified with the prefix chrom:
Figure 1.37 Chromeleon samples loaded to a Byosphere workflow
After submitting the analysis, the Chromeleon files are uploaded to the Byosphere server in *.pacq format and the analysis is run using these server samples.
Metadata in the Chromeleon files is automatically uploaded with the sample files. It is generated through the Byosphere Metadata Mapping *.json file defined in the Chromeleon tab of the server configuration (contact support@proteinmetrics.com for information about creating this file).
1.4.5. Comparison Projects
Comparison projects require an MS *.pacq file or Protein Metrics *.bmp project file marked as Sample type Reference and at least one MS file or Trace file marked as Sample type NonReference. Thus, the process for adding samples is different. After launching a comparison project (where Enable Comparison mode is checked), instead of clicking Add sample(s), double-click in the MS file cell for the Reference row to reveal the
Figure 1.38 Choosing a *.bmap project or MS *.pacq file as a reference for a comparison project
Note that Enable Comparison mode is checked. Click the *.bmap or *.pacq file) and click Choose. Next, double-click in the MS file or Trace files cell of the NonReference row, click the *.pacq or trace file and click Choose. The NonReference row is populated with the file data and the Traces table is populated with corresponding Trace records:
Figure 1.39 Populated comparison project
1.4.6. Workflow: Other Server-Only Files
Certain types of files that are imported into workflows can be opened only from the Byosphere server directory. These include MS/MS search (*.byrslt) files, Byonic parameter files, report configurations, UI configurations, and UI layout files. Trace import files can be opened from the server or from EDS. Trace import files on the server that are MS files must be compressed in *.pacq format, and thus must be uploaded through Byosphere Byos Client. All the other server files, including trace import files that are not MS files (*.csv. *.txt, *.itb, and *.pi files), that are listed above are uploaded to the server without compression. Thus, they can also be uploaded through the Byosphere Web Client.
Figure 1.40 Load Trace file from server
Figure 1.41 Load MS/MS search *.byrslt file from server
Figure 1.42 Load de novo sequencing Byonic *.byparms file from server
Figure 1.43 Load HCP Fasta reference path from server
Figure 1.44 Load Report *rptc, UI column filters *.cft, and UI layout *.ini files from server
As in local Byos analyses, when a server analysis is generated without an assigned report configuration file (*.rptc), the default report template for the workflow type will be applied. Note: Since report configuration files are loaded from the server, and Byosphere cannot know in advance what IDs those server *.rptc files may have, the workflows opened from the Workflows tab are not populated with report configurations. For example, the HCP and S-S workflows would apply the Blgc_PTM (Default).rptc report configuration, if the workflow-specific report files are not manually assigned from the server. To use workflow reports other than the default Intact, Byologic or Byomap reports, upload the desired report presets to the server and then assign those server report files to the workflows. Workflows with report configurations assigned from the server can be saved for reuse, as described in the Saving and Loading Byosphere Workflows section.
1.4.7. Workflow: Local and Server Files
Many other files that are imported into workflows can be opened from either the Byosphere server or from local directories, just as with traditional Byos. These include *.FASTA files, delta mass *.csv files, sample-protein input files, modification import files, and glycan DB or import files. When loading these files, the Byosphere file chooser begins with server files in the ENT tab, but also includes the Local tab to load files from local directories and network directories:
Figure 1.45 Load Fasta file from server
The folder structure defaults to the Byosphere server. Click Choose to load a selected file. To load a file from a local directory, click the Local tab:
Figure 1.46 Load a FASTA file from local directory
Navigate to and select the desired file and click Open. The FASTA file contents is then loaded into the workflow. Likewise, delta mass *.csv files and sample-protein input *.csv files can be loaded to a workflow from either the Byosphere server or local directories.
1.4.8. Modifications
Modification can be entered manually or imported from a *.txt file from the server or a local directory. To add a modification manually, go to the Processing nodes tab, expand the Modifications section, and click the
Figure 1.47 Entering Modifications manually
Go to the last row, use the dropdown arrows to select values for Modifications, Targets and Fine Control, and click OK.
Custom modifications can also be loaded from a text file. In Byosphere Byos Client, that text file can be either a local file or a file on the server. To load modifications file, expand the Modifications section, click the
Figure 1.48 Modification local/server file import
To load a modification file from a local directory, open the Local tab, navigate to and select the modification file, and click Choose.
1.4.9. Glycans
Glycans are traditionally entered as a link to local database file. Since Byosphere analyses run on the server, local file paths are unavailable during the run. Byos Desktop and Byosphere Byos Client workflows now use glycan strings, saved directly to the workflow file. For older Byos Desktop workflows, local database files need to be converted into custom glycans. To convert a glycan database file path within a legacy workflow, go to the Processing nodes tab, click the down arrow before Glycans, and click the
Figure 1.49 Request to convert a glycan database file
Click Yes to convert the glycan database file into a list of custom glycans:
Figure 1.50 Glycan database file converted to custom glycans
Click OK to complete the conversion to a custom glycan string in the workflow. (Note: Add opens a dialog to manually add new glycans; The Import and Load buttons are discussed below).
Figure 1.51 Custom glycans loaded to Byosphere workflow
To load a different glycan database file, click the
Figure 1.52 Import glycan DB *.txt file from server
Alternatively, a glycan DB text file can be loaded from a local directory, such as from C:\Program Files\ProteinMetrics\PMI-Suite\Base\data\GlycanDatabases. To load a local glycan DB text file, open the Local tab in the Select Glycan File dialog, navigate to and select the desired glycan file and click Choose. The glycans in the DB file are converted to glycan strings in the workflow. The workflow can be saved to be launched from Byosphere Byos Client when that glycan set is needed.
The custom glycan string in the Glycans section can also be copied and saved to a text file. Copy all of the text, including the name at the top and the information line at the bottom. To load glycans in this custom string *.txt file, click the
Figure 1.53 Loading local/server custom glycan text file
1.4.10. Saving and Loading Byosphere Workflows
Byosphere Byos Client workflows can be saved as *.wflw files, either locally or to the Byosphere server. To save the Byosphere Byos Client workflow, click Save Workflow at the top, choose ENT for server directories or Local for local directories, select a directory and click Save. All references to files located on the Byosphere server, as well as loaded local file data, are retained. Saved workflow files can be opened from a local directory or the Byosphere server. To open a saved workflow, click Launch Workflow at the top to replace the current workflow with a saved local workflow, or an uploaded server workflow:
Figure 1.54 Launch Workflow from an open workflow
Alternatively, choose File > Launch Workflow:
Figure 1.55 Launch Workflow from File menu
Figure 1.56 Workflows can be saved to the server or a local directory
1.5. Submitting an Analysis
When all the desired files have been imported into the Byosphere Byos Client workflow, click Submit a job at the lower right. Enter the name of the analysis in the File name text box (the Protein Metrics file extension is displayed):
Figure 1.57 Enter file name for the analysis
To set a server destination folder, click the
Figure 1.58 Select destination server folder for the analysis
To save the completed analysis to a new folder, click Make New Folder:
Figure 1.59 Make New Folder option
Enter a name for the new folder. Edit the User groups as needed (the user groups for the parent folder are checked by default). Click OK to create a new folder as the destination. Note: the user must have Folder Editor privileges for the parent folder to make a new folder.
When the server folder is selected, click Choose folder. The Server folder cell is populated with the folder ID and name:
Figure 1.60 Analysis submit dialog with name and server folder added
Metadata is information about the project file. To add metadata, click the
Figure 1.61 Adding metadata field values to the analysis
Select the metadata field name and an appropriate value. A new metadata entry row appears. Add the desired metadata field names and values and click OK. The entered metadata is displayed in the analysis submit dialog:
Figure 1.62 Completed analysis submit dialog
If a sample contains metadata, it can be imported directly to the project. Click Import metadata from sample, select the sample containing the metadata and click OK:
Figure 1.63 Importing metadata from a sample
Note: In the Byosphere Web Client File history for analysis project files, two versions are shown for each analysis: one for the file save itself and another for the metadata added to the saved file.
The addition of a Comment to save with the analysis is optional. To submit an analysis without generating a report, uncheck Generate a report. When the file name and server folder are set, click Submit a job. A dialog appears to notify that the analysis job submission was successful:
Figure 1.64 Successful job submit notification
The View Jobs button opens the Jobs tab, which is discussed next.
1.6. Jobs Tab
Once an analysis has been submitted to the Byosphere server, the progress of the analysis can be followed in the Jobs tab:
Figure 1.65 Jobs tab
The Jobs tab displays information about the queued and running jobs for all users (to give some indication as to when a queued job might begin), all completed and failed jobs submitted by that user, and all completed and failed jobs submitted by anyone to folders for which the user has Viewer privileges. The total number of jobs displayed is set during server installation. The greater list can be filtered by entering text for any field in the Text filter cell at top right. The Jobs module of the Byosphere Web Client displays the same list.
Jobs per page allows the user to specify the number of rows per page and the number of the displayed page. The Refresh 
Job types include Analysis for projects submitted for creation on the server, Report for a report generated for a project that already has an analysis (See Report Jobs ) completed, Conversion for jobs that parse project files to load project data into tables for Deep Query dashboard searching, AuditLog for jobs that generate Byos Audit trails as part of File History Reports for projects, and Pacq.
Preview jobs and multi-doc analyses, using special Preview and Multi-doc workflows, are also supported. Submitted on, Started on and Completed on inform the user how long a queued job was waiting and how long a job took to run.
The first column represents the actions associated with Jobs:
- Click the
icon to cancel a running or queued job. Users can cancel their own jobs, while Super users can cancel any jobs.
- Click the
icon to download a log file for a completed or failed job. This is helpful to diagnose why a job failed.
Figure 1.66 Saving the job log
- Click the
icon to rerun a job that has completed or failed. In the case of an Analysis job, the workflow that was submitted reopens, populated with the original data:
Figure 1.67 Rerunning an Analysis job
In the workflow, a user can correct errors for a failed analysis, or create a variation of a completed analysis. To rerun either kind of analysis, click Submit a job, enter the analysis file name, select the server folder to save to, click Choose, and finally click Submit a job.
Because Byosphere analyses run on an external server, Byosphere Byos Client is immediately available for other purposes. Additional analyses can be set up and submitted. New analysis jobs will then be queued to run in the order they were submitted. An analysis generated on the server will automatically generate and attach a web report to the completed project. If no report template is specified in the workflow, the default report template for that project type is used.
When an analysis job has completed, the Byosphere server will send an email to the user’s email account:
Figure 1.68 Job Completed notification email
Analysis jobs with project type .blgc, .ntms, and .bmap completed from the Desktop client will be immediately available to use in Deep Query Dashboards starting with Byosphere 5.0. Note that HDX projects are not yet supported in Deep Query Dashboards. For more information on Dashboards, see the Deep Query Dashboards User Guide.
In the event of a failed job, the email will note the Job ID and the link will bring the user to the Jobs page of the Byosphere Web Client, where the user can download the log file.
For more information about available actions in search results, see the Search Module section of the Byosphere 03 Web Client Manual.
1.7. File Menu
The Byosphere Byos Client File menu includes some Byos File menu items along with several menus specialized for Byosphere:
Figure 1.69 Byosphere File menu
- Launch Workflow – See the Saving and Loading Byosphere Workflows section.
- Open Project – When projects are opened from the server for the first time, users are notified after the download if any potentially needed resources are missing from their local environment. Missing resources can include sample files, report configurations, FASTA files, or any other project resource that is saved on the server.
Figure 1.70 Opening projects from the server includes options to download support files
Click Retrieve and open to download the missing resources before the project is opened.
Click Open without retrieving to open the project directly without downloading any missing resources. Missing resources can still be downloaded later.
If the resources are downloaded, they are then mapped to the project. The project can then be modified using those resources locally. The menu Edit > Adjust MS paths shows that a copy of a server sample file is still associated with the copy of the server project:
Figure 1.71 Edit MS file paths for server projects shows server paths
A copy of the project is saved in the Projects directory under the Home directory set in Server > Preferences. The file name is prepended with the file ID to distinguish that file from other opened files with the same name. When the project is closed and reopened from File > Recent Projects, this local copy is opened.
Downloaded resources (such as sample files) are saved in the ResourceCache directory set in Server > Settings. If another server project is opened that uses a resource that was previously downloaded, the project opens mapped to that resource without downloading it again.
Note: If a project is opened through File > Download, and its resources have not been downloaded previously, the Missing resources dialog also appears. File > Open Project is recommended to open server projects because the local copy of the project maintains an association with the server project. This association is broken for local project file from File > Download.
If the opened project references an invalid server resource file (for example, if the resource was deleted from the server), the Invalid resources dialog opens:
Figure 1.72 Invalid references dialog
To fix the invalid reference, click Yes. In the Edit MS file paths dialog, click the “…” button, navigate to and select a copy of the missing file on the server and click Choose.
Figure 1.73 Replacing an MS file not found on the server
If an opened project already exists in the Home directory Projects, a new dialog File exists opens with options to open the local version (Open Local), overwrite the local version with the server version (Override Local) or save as a new copy (Download as Copy) or Cancel.
Figure 1.74 File management options if a local copy of the project file exists
- Recent Projects – shows a list of server projects opened locally. Server project files accessed through File > Open Projects display their server file ID and version prefixed to the file name:
Figure 1.75 Recent Projects list identifies server project files
Server project files are identified by the term ent:file:, followed by the file ID and version numbers. The file ID and version distinguish each file from other opened files with the same name or other versions of the server project. Local copies of project files from File > Download show the local directory path. These local copies no longer maintain a connection to the server project files.
To clear the Recent Projects list, click Clear Menu.
Locally edited server projects are marked with the term [unsaved] appended to their names:
Figure 1.76 Recent Projects file name labeled [unsaved] after it is edited
If the edited file is saved to the server as a new version using File > Save to Server, the term [unsaved] is removed from the file name.
- Retrieve missing resources – If a project is opened using File > Open Projects and the missing resources are not downloaded at the same time, Retrieve missing resources allows the user to download them later.
- Close – closes the open project. When using Close for an edited server project (or closing them directly), the user is asked whether to upload the project as a new version:
Figure 1.77 Warning when closing a locally modified server project file
If Upload is clicked, the upload dialog opened by Save to Server (see below) appears.
- Save to Server – allows the user to directly save a locally edited project to the server as a new version:
Figure 1.78 Save project as new version with File > Save to Server
Note that while the local file name is prepended with the file ID, the server file is not. The new version of this file will not be renamed with the file ID when uploading through this dialog. Because File > Upload will rename the new version of the file with file ID, it is highly recommended to use Save to Server rather than Upload for saving projects as new versions.
To save the project as a new file (instead of a new version of an existing file), choose File > Save to Server, click
- Upload – this is explained in detail in the next section.
- Download – see the Byosphere Byos Client Downloads section for detailed description.
1.8. Byosphere Byos Client Uploads
Byosphere Byos Client can be used to upload files and folders to the server.
1.8.1. Byosphere Byos Client vs. Web Client
Byosphere Byos Client should always be used to perform uploads for the following cases:
- Protein Metrics project files with reports – In order to make reports available on the Byosphere Web Client, Protein Metrics project files need to be uploaded via the Byosphere Byos Client. Byosphere Byos Client uploads include the option to generate a report for the project. Since large uploads can tie up the Byosphere Byos Client window for long periods, users can continue working in another instance of Byosphere Byos Client.
The Byosphere Web Client is recommended to perform uploads for the following cases:
- Very large files not in the list above – Very large file uploads on ordinary connections (such as home networks) can take hours. Any network interruption will cause a Byosphere Byos Client upload to fail. Web browsers tend to be more resilient to brief network interruptions.
- Multiple files not in the list above – The Byosphere Web Client creates a queue of file uploads. Several files can be added to the Add file queue from different folders, and then work can continue in another Byosphere Web Client tab or in the Byosphere Byos Client. On the other hand, Byosphere Byos Client can only upload one file at a time, requiring a manual upload for each file, only after the previous upload finishes. Alternatively, target files can be moved into a single folder and uploaded in Byosphere Byos Client to the server as a folder
1.8.2. File/Folder Uploads
To upload a file in Byosphere Byos Client, choose File > Upload. An upload dialog opens:
Figure 1.79 Byosphere Byos Client upload dialog
To select a file on your local drive to upload, click the
Figure 1.80 Choose a local file
To upload a folder and its contents, navigate to and select the folder on the right side:
Figure 1.81 Choose local folder
Click Choose and the Local file/folder cell contains the folder path and/or file name:
Figure 1.82 Local file/folder entry
Note that the Generate a report checkbox appears. This option is available for all Protein Metrics project uploads. Check this box to generate a web report for the uploaded analysis project on the Byosphere server.
If a Protein Metrics project tab is selected in Byosphere Byos Client when choosing File > Upload, the Local file/folder cell will automatically be pre-populated with that project file name and path. Selected Byosphere Byos Client report tabs do not pre-populate this cell.
To choose a destination on the Byosphere server, click the
Figure 1.83 Choosing a server folder for the upload
The user must have File Editor privileges to upload to the server folder. To create a new folder on the server for the upload, select the parent for the new folder, click Make New Folder, assign a folder name, add or remove user groups as needed, and click OK (the user must have Folder Editor privileges for the parent folder to make a new folder).
When the source folder is selected, click Choose and the folder name and ID is displayed in the Server file/folder cell:
Figure 1.84 Server destination folder and its ID
Note that the address identifies it by the folder object type and its folder ID. This address remains valid even if the folder is moved. A Comment entry is optional.
To upload a file as a new version of an existing file, navigate to and select the original server file in the right pane:
Figure 1.85 Choosing a server file to upload as a new version
Click Choose and the file name, ID and version are populated in the Server file/folder cell:
Figure 1.86 Uploading a file as new version
Now the address identifies the destination as a file object type with its file ID and version. Again, this address remains valid even if the file is moved. A Comment entry is optional.
If a project file was downloaded from the server and it is selected when choosing File > Upload, the original server file ID will be pre-populated in the Server file/folder cell. Thus, a modified project or report template can be easily uploaded as a new version.
1.8.3. Metadata
Metadata fields are information about files. In addition to the internal set of metadata fields (e.g., File Name, Alias, Created By, etc.), there are optional reserved metadata fields that are applicable to sample files and analyses that Administrators can expose. In addition, Administrators can create any number of custom metadata fields.
To include metadata in the uploaded file, click the
Figure 1.87 Adding values to metadata fields
Select the metadata field name and an appropriate value. A new metadata entry row appears. Add the desired metadata field names and values and click OK. The entered metadata is displayed in the Upload file dialog:
Figure 1.88 Upload file dialog showing metadata
Uploads also allow users to delete files and folders after they finish uploading to the server. To delete a file or folder, check Delete local file/folder after upload:
Figure 1.89 Deleting a file or folder after the upload
Note: In the Byosphere Web Client File history for uploaded files, two versions are shown for each upload: one for the file upload itself and another for the metadata added to the uploaded file.
1.8.4. Upload Progress
To begin the upload, click Upload. The dialog adds a status bar to show the upload progress:
Figure 1.90 Upload progress
To see the status of individual file uploads during a folder upload, click Details:
Figure 1.91 Click Details to show upload progress of each file in a folder
Over-long file uploads can be interrupted with the Cancel button. Click Show only failed to view only the cancelled or failed uploads:
Figure 1.92 Displaying cancelled or failed uploads
To restart a failed or cancelled upload, click Retry after that file. To restart all failed or cancelled uploads, click Retry all at the lower left.
Other Byosphere Byos Client functions are not active during the upload. Another instance of Byosphere Byos Client can be opened to continue working.
When the upload completes, a notification window opens to show that it was successful. If Generate a report was checked for a project file, the notice also confirms that the Report job was submitted:
Figure 1.93 Successful upload notification
Click OK to close the dialog. The Upload file/folder dialog remains open so that additional uploads can be initiated from the same local directory or to the same server directory.
Note: When a sample file or a folder of sample files is uploaded to the server, a copy of the files is made to the resource cache. If a server project using these samples is opened or downloaded, the sample files are immediately available and referenced in the project. These files do not need to be downloaded again
1.8.5. Report Jobs
When a Protein Metrics project file is uploaded with Generate a Report checked, the submitted report job is displayed in the Jobs tab:
Figure 1.94 Jobs tab with a Completed Report job
As with analysis jobs, click the 
Figure 1.95 Select a report configuration for a rerun Report Job
Click the *.rptc file, and click Choose. Click OK and a new version of the project will be generated using the report template chosen.
As with a Byosphere server analysis, an email is sent when the report is completed, and the link in the email opens a search for the newly uploaded analysis project.
1.9. Byosphere Byos Client Downloads
The File > Download menu can be used to download copies of server files to a local directory. Analysis projects on the Byosphere server can be opened directly. The menu item File > Open Project should be used to open projects from local directories or from the server:
Figure 1.96 File > Open Project from a local directory or the Byosphere server
1.9.1. Byosphere Byos Client vs. Web Client
Both Byosphere Byos Client and Byosphere Web Client can be used to download files. There are advantages to each kind of download:
- Byosphere Byos Client can download folders. The Byosphere Web Client can only download files.
- When Byosphere Byos Client is used to download sample raw files or folders, or folders containing sample files and/or sample folders, that were compressed to
*.pacqformat, the*.pacqfiles are decompressed into the original raw files and/or folders. - The Byosphere Web Client can download specific versions of files. By default, the Byosphere Byos Client downloads the latest version of a file.
- Web browser downloads have better error recovery systems. For some network interruptions, the web browser download can be resumed. Byosphere Byos Client downloads cannot be resumed when interrupted. The Byosphere Web Client is recommended to download very large, non-pacq files.
1.9.2. File/Folder Downloads
To download a server file or folder in Byosphere Byos Client, choose File > Download. A Download dialog opens:
Figure 1.97 Download file or folder dialog
The Local folder cell is pre-populated with the default download directory set by the Server > Preferences menu. To change the Local folder, click the
To choose a Byosphere server file or folder to download, click the
Figure 1.98 Choosing a server file to download
Click Choose and the file name and ID is populated in the Server file/folder cell:
Figure 1.99 Download with server source file and its ID and version
When Open the file when download completes is checked, and the file to download is a Protein Metrics project file, the file will automatically open in Byosphere Byos Client after the download. Other files will open with the default application assigned to that file type.
Byosphere Byos Client will always download the last version of a file on the server. Older versions of server files can be downloaded from the File History for that file in the Byosphere Web Client. For instructions, see the File History section of the Byosphere 03 Web User Manual.pdf.
To download a folder, navigate to and select the destination server folder in the left pane:
Figure 1.100 Choosing a server folder to download
Click Choose and the folder name and ID are populated in the Server file/folder cell:
Figure 1.101 Folder download with server folder name and ID
Click Open the file when download completes to automatically open the downloaded file in the app defined for that extension.
Note: If the user has privileges to a server project but does not have privileges to the sample files used by the project, the project can still be opened without the samples for viewing purposes.
The following dialog is shown when conflicts are detected while downloading the folder that has many files with the same name:
Figure 1.102 File name reserved for another file
Figure 1.103 Target location already contains a file with the same name
There are five options:
- Ignore – Files will be ignored (this option is only available for files other than
*.pacqfiles) - Rename – Shows the dialog in which files can be renamed
Figure 1.104 Rename file dialog
- Auto-rename – Files will be auto-renamed
- Overwrite – Files will be overwritten
- Cancel – Downloading a file will be canceled (this option is available only if the conflicts have been detected when copying the files to the target location – this usually can only happen for
*.pacqfiles)
Apply to all allows users to auto select the selected option for all other conflicts.
Compare files loads metadata information about old and new files:
Figure 1.105 Compare files information
1.9.3. Download Progress
To begin the download, click Download. The dialog adds a status bar to show the download progress.
Figure 1.106 Download progress
To see the status of individual file downloads during a folder download, click Details:
Figure 1.107 Click Details to show download progress of each file in a folder
Over-long file downloads can be interrupted with the Cancel button. Click Show only failed to view only the cancelled or failed downloads:
Figure 1.108 Displaying cancelled or failed downloads
To restart a failed or cancelled download, click Retry after that file. To restart all failed or cancelled downloads, click Retry all at the lower left.
Other Byosphere Byos Client functions are not active during the download. Another instance of Byosphere Byos Client can be opened to continue working.
If the Open the file checkbox is unchecked, a notification window opens after the download completes to show that it was successful:
Figure 1.109 Download succeeded notification
If the Open the file checkbox is checked, the file is opened in the app assigned to that file extension after the download completes. If the file is a Protein Metrics project, the project and its report are opened in the Byosphere Byos Client window:
Figure 1.110 Protein Metrics project and report automatically opened in Byosphere Byos Client
1.10. Appendix
1.10.1. Download Earlier Versions of Files
There is a workaround to download an earlier version of a file in the Byosphere Byos Client. For example, if more than one version of a sample file exists on the server in *.pacq format, users may wish to view the MS file(s) from an earlier version. The Web Client can download any version but does not decompress *.pacq files. To download a specific version of a file on the desktop, choose File > Download and choose the file to download. The file ID and last version is shown in the Server file cell:
Figure 1.111 Server downloads choose the latest version of files
Manually edit the version number that follows the ID number to the specific version to download:
Figure 1.112 Manually edit the file version number to download that version
Click Download and the version of the file entered will be downloaded instead of the latest version:
Figure 1.113 The specified file version is downloaded
1.10.2. Adding Metadata to Byosphere Reports
Project metadata can be added to Byosphere reports as Short Codes. To insert metadata into the Summary tab in a report, choose Edit > Current tab settings, click Edit summary template, click Short Codes, select the Project Metadata short code and click Insert:
Figure 1.114 Adding Project Metadata short code to a report
The metadata for the project is displayed in the Summary tab:
Figure 1.115 Metadata displayed in the Summary tab
Branch: release/2025.09
Compile Date: 2025-Oct-03
Compile Time: 12:00:53