Usage

The following usage docs provide instructions for common tasks and workflows in Song:

📄️ Metadata Submission

Submitting new metadata entries (Analyses) to Song.

📄️ Metadata Retrieval

Query & retrieval of metadata (Analyses) from Song.

📄️ Updating Metadata

Updating metadata for analyses in Songs database using various methods.

📄️ Publication Controls

Managing data release with publication controls.

📄️ Data Model Management

Creating & updating the data model using JSON schema.

📄️ Schema Strictness

Song's schema strictness determines whether analyses adhere strictly to the latest schema version or can use any version.

📄️ ID Management

Song provides two distinct approaches for managing primary keys across entities (Donors, Specimens, Samples, and Files):

📄️ Kafka Setup

Song can be configured to integrate with Kafka for event streaming. This page explains how to enable and configure the Kafka integration.

📄️ Configuring Keycloak

There are multiple methods of deploying Keycloak. Documentation on Keycloak deployment can be found on the Official Keycloak website.

Songs API is a RESTful API that uses JSON for request and response bodies. It follows standard HTTP methods and status codes, providing a robust interface for managing song-related data in the Overture platform.

📄️ Client Reference

Commands and options supported by the Song client.

Song Terminology

Whether you're new to these tools or looking to refresh your understanding, this glossary is here as a reference of key terms and concepts.

Analysis: A trackable unit of data in Song that combines metadata and associated data files. It's the main entity in a Song database.
Analysis ID: A unique identifier (UUID) assigned to each analysis in Song. It's used to track, retrieve, and manage specific analyses throughout the Song and Score.
Analysis State: The current status of an analysis in Song. States include PUBLISHED, UNPUBLISHED, and SUPPRESSED.
Analysis Type: A category of analysis defined by Song administrators, which describes the structure and content of a particular kind of data submission.
Dynamic Schema: A JSON-based schema that defines the structure and constraints of an analysis type in Song.
Manifest: A file generated by Song that establishes a link between an analysis ID and the data files on your local system, used by Score for file uploads.
Metadata: Data that describes other data. In the context of Song, it refers to the information about data files included in an analysis.
Payload: A formatted set of metadata conforming to a specific analysis type schema, submitted to Song as part of the data submission process.
Score: A file transfer and storage system designed to work alongside Song for managing large data files.
Song: A metadata management system used to track and manage metadata related to files in a data repository. s
Study: A collection of analyses in Song, typically representing a coherent set of data for a particular research project or data submission.
Published Analysis: An analysis in Song that has been marked as ready for downstream processing and is searchable within the system.
Unpublished Analysis: An analysis in Song that has been created but is not yet ready for downstream processing or searching.
Suppressed Analysis: An analysis in Song that has been temporarily hidden or removed from active use, typically due to data quality issues or other concerns.