Frequently Asked Questions

Please see below for commonly asked questions regarding the GSRS application. If you need further information, please reach out to ncatsgsrs@mail.nih.gov.

Access Management | Data | Functionality | Message Exchange | Migration | Performance | Security | Software | Technical Specifications | Updating the Software |

Access Management

Back to Top

Question	Response
How is access to the user interface for substance data maintenance controlled?	GSRS has named users and a user table. The user table provides a set of roles for each user which designates specific privileges within both the UI and REST API.
How is access for browsing the substance data controlled?	GSRS currently has an all-or-nothing policy for viewing records. That is, if a user can see an instance of GSRS they are allowed to see all data associated with that instance in GSRS. However, the data itself has flags to designate how publishable certain elements are, and there are tools to extract only the publishable elements. At FDA , EMA and BfArM there is an internal and external of GSRS. The internal interface has all the data. The external interface is populated with “pre-scrubbed” reports from the internal version using these access fields.
Can the graphical user interface (GUI) for GSRS allow different users, with different access rights to view confidential and public substances?	We do allow different users and different roles, but we do not currently allow different users to see different data on the same instance.
Is there single sign-on (SSO) integration?	Yes. PrecisionFDA, USP, FDA internal GSRS, BfArM and EU-SRS have all successfully integrated SSO in various forms with the GSRS application.
Are there role-based access control (RBAC) capabilities?	Yes, to a certain extent. We have defined role-based access to certain capabilities of the system (editing, updating, admin functions, etc.), but do not allow special views of public vs protected data based on those roles, as explained above. Roles handle what you can do in GSRS not what you can see.
Currently the roles in GSRS are hard coded. Is there in the roadmap, the ability for the user to extend or modify these roles in order to add custom functionality / processes?	One of the items on our list of things to work on in the future is reworking user roles. We'd like to move from a hard-coded set of roles to a configurable set of granular permissions which are then assignable to certain roles. This requires some careful planning and resources, support for the legacy roles as-is if desired, enumeration of better "default" roles, a discussion of whether we need to preserve the cardinality, and the ability to change roles/impersonate a role temporarily. Tentatively, we've slated this for 3.1.1 targeted for March of 2023, but this is subject to change and is just a preliminary target. We may adjust based on needs and resources. If we can get community developer support, that would be a great boon!
Is it possible that by selecting a group in GSRS, it would then apply the appropriate roles/permissions for that user automatically based on a group definition?	It is doable but not implemented yet in a standard way. Some of our partners already do some things of this nature, but they largely do this by adding a pre-filter proxy layer embedded with the SSO which calculates/passes along the roles based on other data known about the user. Custom setups like this aren't too tricky to accomplish even now, but there's no direct support for tying groups to roles/permissions deep in the code itself. It's a worthwhile feature to consider as part of the roles rework epic discussed above!
Is there in the roadmap an ability to restrict viewing of certain records for specific groups?	Restricting access to records has come up and is something on our minds. However, we have not yet added it to the roadmap. For the time being, we have focused on creating exports that contain restricted subsets of data. By deploying a restricted subset of data on a second (or third) server, several organizations have achieved a security-based partitioning of data.
Which is the better choice, Admin: Group or Role?	For the most part, you want to use the Admin role. This allows a user to access the admin panel as well as perform some registration operations that are reserved for administrative users. (For example, admins can override complete duplicate warnings, which appear as errors to most users.) Groups within GSRS are basically reserved for future use. One exception is the group called 'sysadmin.' Adding a user to sysadmin allows the person to log in and work on the system when it is undergoing a reindexing operation. (In general, you don't want users on the system during reindexing, since most operations are very slow.)

Application Programming Interface (API)

Back to Top

Question	Response
What does the API expose?	Everything. All features of GSRS are done via the representational state transfer (REST) API. The UI, Excel Power Tools and system integrations are all done via the REST API with no other “secret” layer for doing operations on the system. The swagger documentation gives a basic overview of what is possible, but there are other features and parameters of the REST API which are not as deeply documented there. With the REST API you can, for example: -Create, update, and delete records -Retrieve a record or sub-element of a record by ID or special code -Search, sort, browse, and filter substance records -Perform chemical structure and sequence search operations -Validate a substance record -Export sets of records to various formats -Do bulk data operations (indexing/updates/reports/logs) -Create, modify and update users
What payloads are exchanged in the API?	The REST API largely accepts and produces JavaScript Object Notation (JSON). For a few endpoints it may produce a Scalable Vector Graphics (SVG), Portable Network Graphics (PNG), raw document or raw text, but these are very specific cases. Similarly, the REST API typically expects a JSON payload for substance registration, edits, etc. However, there are also endpoints to convert raw images to chemical molfiles, molfiles to JSON structures, and to upload arbitrary Multipurpose Internet Mail Extensions (MIME) type documents.

Data

Back to Top

Question	Response
How do you know which of your datasets are confidential, and which may be made public?	Data may be public if it is associated with a public data source. FDA will not release public information if it is closely aligned with trade secrets or clinical trials.
Has a decision been made about which substance identifier will be used to generate PhPIDs (pharmaceutical product identification)?	A PhPID is calculated based on four criteria levels. See FDA’s Pharmaceutical Product Identification webpage for more information. https://www.fda.gov/industry/fda-data-standards-advisory-board/pharmaceutical-product-identification
Does GSRS handle substances which are technically products (e.g., substances with an added stabilizer or when calcium and vitamin D substances are compounded together)?	Products containing more than one medicinal substance are classified as ISO 11238 Specified Substances Group 1 (SSG1). Substance-level information is managed by GSRS. However,, proprietary blends such as but not limited to colors, flavors, and fragrances may be managed as SSG1.
Does GSRS capture more than one molecular weight for a substance (e.g., proteins)?	Molecular weight is automatically calculated based on chemical composition for chemicals, proteins, and nucleotide sequences. For proteins with modified sequences, the molecular weight is manually as a property.
What is within the contents of GSRS seed data?	All FDA GSRS public data.
How does GSRS handle polymorphic substances?	Polymorphic substances are categorized as ISO 11238 Specified Substances Group 1 (SSG1). For example, solvates with different molecular formulas are managed as unique substances.
How are customized structures and definitions kept up-to-date?	Keeping substance data up to date is a complex issue, even when there is only one system. We have various reports and tools we use to find potential data issues and we often do overlap analyses with other public data sources, monitoring discrepancies in InChIKeys, IUPAC names, sequences, etc. This helps us detect potential issues where we would like to update records. We use a variety of tools from Excel plugins to KNIME workflows to help us with this task. As for making changes to the public seed data and then desiring to update the non-modified records with the new changes to the seed data that FDA would release later… this is indeed a challenge to maintain. GSRS 3.1 will provide tools to “stage” bulk records and monitor differences between different forms of the same data, but the process will still largely be manual, requiring some form of expert review in maintaining the “best” version of local records without removing custom data.
What is ISO IDMP?	International Standards Organization: Identification of Medicinal Products (ISO:IDMP) is a set of five ISO standards for uniquely and unambiguously defining medicinal products and related information. One of the primary purposes of these standards is in international pharmacovigilance.
What is ISO 11238?	ISO 11238 is the section of IDMP which deals with substances, and which was the inspiration for the data model and processes used by the ginas collaboration in the GSRS software. A major goal of the GSRS software is to support the ISO 11238 requirements of the IDMP standard.
What is the data required to get a UNII?	Unique Ingredient Identifiers are based on the principle that each distinct ingredient substance will have a distinct UNII based on the ISO 11238 substances standard https://en.wikipedia.org/wiki/Unique_Ingredient_Identifier. Here is our public home page for the standard, which is currently under revision in ISO. https://www.fda.gov/industry/fda-data-standards-advisory-board/fdas-global-substance-registration-system This standard provides data elements and vocabularies to uniquely identify substances…from an atom to an organism. Here is a public presentation (including some technical glitches) detailing our approach to substances. https://www.fda.gov/science-research/fda-grand-rounds/fdas-global-substance-registration-system-gsrs-unique-ingredient-identifiers-uniis-uniquely-define
Who is able to generate a UNII?	Our FDA GSRS team manages generation of UNIIs. NIH/NCATS has overseen development of the GSRS software which implements the ISO standard. They also host a query only public instance of the GSRS records https://gsrs.ncats.nih.gov/ginas/app/beta/home. The public UNII Search simplified dataset is available publicly on PrecisionFDA https://precision.fda.gov/uniisearch and the richest public dataset is available to registered users on PrecisionFDA who can also submit confidential GSRS/UNII data to FDA via shared review spaces.
Why there are performance data (viscosity for polymers as an example) associated to synonyms?	Not all INCI names and monographs represent unique substances according to the standard so some of these names like Acrylates/C10-30 Alkyl Acrylate Crosspolymer require additional identity characteristics to be accurately described. Copolymers require monomers, their ratios, and some measure of molecular weight. This information is managed via structural repeat units according to the standard. Here is the example of Carbopol Ultrez 20. The monomer ratios are known but not part of the public export and the viscosity property is the molecular weight measurement. https://gsrs.ncats.nih.gov/ginas/app/beta/substances/6183891a-5aba-4a60-bd6a-b16674d0dc18 https://precision.fda.gov/uniisearch/srs/unii/8Z5ZAL5H3V

Functionality

Back to Top

Question	Response
What filters are available?	The ability to sort and filter records, search results, and other types of data are available throughout the entire GSRS database.
Can we add our own controlled vocabularies?	Yes.
Where do we capture codes/IDs from the legacy dictionary?	GSRS staff encourage registrars to add external database links and identifiers for substances to the “codes” section of the model. In the substance edit window of the user interface (UI), you can add a new “code”, and select the appropriate code system. If the code system is your own database or a system not represented in the default drop-down, it can be added in the CV management tools in the admin panel. You can also bulk load a large set of code mappings to legacy dictionaries (or any other identifier) using the GSRSFind Excel plugin, and it will add each code mapping to the appropriate substance record. These codes can further be used in reports, UI filters, and to aid in mapping.
What is ginas?	“ginas” (Global Ingredient Archival System) is the name of the collaborative international effort to realize a global mechanism for substance information exchange. Officially, the software produced by NIH/NCATS is called “GSRS” (Global Substance Registration System). It is most correct to say that “GSRS” is the “software to support the GINAS initiative”. Unofficially, “GINAS” is often used interchangeably with GSRS to refer to the software. A major goal of the GSRS software is to support the ISO 11238 requirements of the IDMP standard.
Will this system help to ensure that drugs and APIs are safer or help with shortages?	The primary use case driving IDMP adoption is that of pharmacovigilance. GSRS is the first implementation of the substance information part of the IDMP standards (ISO 11238) and works with the other parts to support these efforts.
How do you export all hits after a search?	After completing a search on GSRS, an individual can export all hits also known as results to a file by clicking on the "Export" button on the results page. After clicking on "Export," select a format. After selecting a format, a screen will pop up with the following heading: "Enter A Filename". After naming the file, click on "Save." If a user sees far fewer hit than expected, it is because by default, GSRS exports only approved public records. In order to export ALL records in the list, make sure the "Include Private Data" checkbox is check marked.

Message Exchange

Back to Top

Question	Response
Will the GSRS system support the lookup of similar substances as part of registration?	Yes. The software issues warnings if there is a similar definition for a substance during registration. A registrar will have to read through those warnings and confirm that the substances are, in fact, unique. Similarity of definitions is currently defined like this:Chemicals - Any substance which is the same based on a tautomer-insensitive, stereo-insensitive, salt-stripped form is flagged as being a possible duplicate.Proteins & Nucleic Acids- Any substance for which any of the subunit sequences have an identity match greater than a preset identity cutoff for sequence alignment identity will issue a possible duplicate warning.Similarity checks for Polymers, Structurally Diverse, Mixtures and Group 1 and above will be released in subsequent versions of GSRS
What validation is required to register a substance?	Each substance must have at least 1 name in order to be registered. It may also have several codes associated with it (e.g. registry numbers, external identifiers). A validation rule also warns the user when registering a substance with a sufficiently similar name or identical code to one already registered. This is important, as many times (especially from vendors and other data sources) the exact definitional information of the substance (e.g. chemical structure) may have some minor errors, but the bulk of curation has gone into ensuring that the names / code numbers were correct.
Is GSRS envisaged as a potential replacement for a compound registration solution within a Pharma org – i.e. scales to millions of substances and supports sub-structure searching?	Yes. The chemistry support library can efficiently search through millions of substances and the database pieces are designed to scale as well. The current registration system has been tested to support 100,000 records using typical hardware; specialized configuration (e.g. more memory) may be needed to support registration of much larger sets of substances.

Migration

Back to Top

Question

Response

How can we migrate legacy definitions?

It depends on the format those definitions are in and what seed data you are starting with in your GSRS instance. At FDA it is typical for us to receive a large set of substances in various forms which need to have GSRS record mappings. A few examples of large substance bulk formats include: -Structure-data file (SD file): chemical connection table file with extra properties -Excel file: with names and perhaps CAS numbers or smiles At FDA, we typically attempt to map records in the above formats to existing records in GSRS first by using either the bulk search tools in GSRS UI or some bulk mapping tools in the GSRSFind excel tools. If we can find a direct map to an existing record, we simply load any legacy identifier or important note into the existing substance record to complete the mapping. In cases where there is no GSRS record that can be mapped based on CAS, structure, name or any other mapping field, we need to obtain the appropriate definition of the substance record. For chemicals it is typically sufficient to obtain a SMILES or a molfile for each record, and this can often be done by mapping legacy identifiers to other public chemical databases (such as PubChem and CAS registry system) and exporting those records. Once we have a spreadsheet file with SMILES or an SD file, we have bulk loading tools in the GSRSFind excel tools which we can use to load those records via the REST API. GSRS 3.1 will also have a small suite of tools to do basic extract, transform, and load (ETL) processes for common substance formats into a running instance of the database.

Performance

Back to Top

Question	Response
How many concurrent requests can the solution handle?	This is challenging to evaluate and depends on the nature of the server, the database and the requests being performed at the same time. In practice at the FDA, using a single server with an oracle database, reasonable performance for basic UI and editing actions is achieved with a few dozen concurrent users. Responses become slower when the requests are more intense (for example, substructure searches, sequence alignment searches, bulk loading operations). National Center for Advancing Translational Sciences (NCATS) and Federal Institute for Drugs and Medical Devices (Bundesinstitut für Arzneimittel und Medizinprodukte (BfArM) have both also experimented with having several “nodes” of the application running at once. This is very achievable in both 2.X and 3.X provided the instance is read-only. When the instance also requires updates to data, there are more steps needed to achieve this kind of scalability. Better preliminary support for scalable instances is planned for GSRS 3.1.2.
What is the speed of response?	This largely depends on the nature of the request. The REST API supports many kinds of endpoints, from simple type-ahead suggestion services (which typically respond in less than 100 ms in most deployments) to full-scale subgraph isomorphic searches for chemicals (which can take several minutes to execute), to admin-level data integrity reports which can sometimes execute over the course of several days. The HTTP REST API responses are intended to be returned within 5 seconds at maximum, and the goal is for all API responses to return in under a second. For many cases this is achieved now, using an asynchronous response if the execution would take a very long time. That is, the actual execution of the task may take several minutes, but the HTTP response will only take a few seconds and can be monitored. In a few cases, particularly updating large records, the REST API is still using synchronous HTTP and that can result in responses that take over a minute for particularly complex materials. Allowing asynchronous updates and validation to GSRS REST API would greatly improve this kind of worst-case response time and is planned for a near-term release.

Security

Back to Top

Question

Response

What are the security features?

This is a complex question and highly dependent on the deployment mechanism. FDA, NCATS and other organizations deploying GSRS use a variety of security tools to run penetration tests and security validation on the software, and the development team monitors and responds to those findings. The built-in spring-boot framework automatically provides considerable protection against common concerns like SQL injection and cross-site scripting. Libraries with revealed vulnerabilities like Log4j are monitored and addressed in a timely manner. All passwords are stored in a salted hashed table with new distinct hashes for each user password. But there are other security elements in place based on the deployment.

Software

Back to Top

Question	Response
Will there be any customizable workflows/processes in GSRS based upon business requirements?	However, it is possible to build a pipeline in external tools (such as KNIME or Pipeline Pilot), leveraging the GSRS API. We’ll start moving in the direction of customizable processes in release 3.1, with more work on the horizon.
Will there be settings that can be easily configured by admin users via the UI in the future. (eg; loading UNII codes via the API as discussed in a previous thread)	GSRS provides a lot of configuration through files. In version 3.1, we will provide deep configuration of bulk tools via changes to configuration files, with some configurations allowed for admin users at runtime. Making the deeper configuration tools more accessible at the UI level is an element of the epic labelled "central configuration microservice" which hasn't yet been prioritized. 3.1 will allow for many abstract and configurable bulk loading operations, but some ad-hoc bulk loads will still best be done by specific scripts/tools like the excel power tools which use the REST API directly.
What is the current roadmap GSRS? E.g., when is version 3.1 expected to be released?	We do have a roadmap, as described in the graphic below. Please take future dates as approximate.
What’s the software’s name? Ginas? GSRS?	Officially, the software produced by NIH/NCATS is called “GSRS” (Global Substance Registration System). “ginas” (Global Ingredient Archival System) is the name of the collaborative international effort to realize a global mechanism for substance information exchange. Admittedly, branding the released software with the initiative’s logo has caused a lot of confusion. It is most correct to say that “GSRS” is the “software to support the GINAS initiative”. Unofficially, “GINAS” is often used interchangeably with GSRS to refer to the software.
Where is the GSRS Software being used?	Currently, the software is being used in a supporting role for the USA FDA Substance Registration System. Several evaluation versions are being used in other regulatory environments, pharmaceutical companies, and technology firms. The software is scheduled to become the production software for the FDA’s SRS in September of 2015.
Does GSRS have an official or mandatory status?	At this time, the ginas initiative and GSRS software are neither mandatory nor officially endorsed by any regulatory agency, or governmental body.
Can I get access to the API documentation?	The software is still in active development, but preliminary API documentation can be found on the NIH NCATS git repository. Interactive examples of using the REST API can also be found here (https://tripod.nih.gov/ginas/#/api).
What is the license for the GSRS software?	Please refer to the individual licenses of referenced libraries for further information. The software includes many open source components, with associated open source licenses for their use and distribution, and some commercial components, which are licensed by us for distribution to you as part of this software product. The source code authored by NIH/NCATS are public domain and freely distributable.
Are there data included with the software?	Yes. Certain releases of GSRS are available packaged together with example seed data compiled from various sources, with the FDA SRS data as the primary contributor. At this time, the seed dataset holds no official status, and is meant only to aid in the understanding of the system and data model. As such, apparent errata in the dataset may be the result of the lossy translation process from other systems, or simply testing data meant to explore certain features of the data model.

Technical Specifications

Back to Top

Question	Response
What are recommended chemical drawing tools?	GSRS comes with the JSDraw chemical drawing tool licensed from Scilligence, and chemical substance registration supports using MDL molfiles copied from other drawing tools as well.
Will GSRS support specified substance levels 1-4?	GSRS will eventually support all specified substance levels. Currently, it supports only up to group 1 specified substance G1SS, but there are plans to expand to G2SS and G3SS in the near term (likely a ginas 2.0 release). G4SS will take a bit more time, as the details required are more complex, and have a much stronger tie to specific interpretations by the regulators, which have not yet been qualified.
What database is used?	GSRS is database agnostic. Presently, the software ships with an embedded H2 database, with supporting embedded lucene indexes. However, the software has been successfully configured and deployed in Oracle and MySQL databases as well.
What language is the code written in?	The REST api and supporting services are written in Java. The frontend registration interface is written in Javascript, primarily Angular JS, CSS and HTML.
Is a full FDA dataset available?	Yes. Please contact us for info.
What is required for PostGreSQL with GSRS 3.0?	Background: one of the goals of the GSRS project is to support a variety of relational database systems. Sometimes, an RDBMS requires a specific setting to run correctly. One such example is PostGreSQL with GSRS 3.0. In order for GSRS 3.0 to run correctly, a small configuration setting is required. Within application.conf, add this line spring.jpa.database-platform = gsrs.repository.sql.dialect.GSRSPostgreSQLDialectCustom This directs the Spring Boot framework to use the GSRSPostgreSQLDialectCustom class our team created to map large text and binary fields correctly to the database. The position of the line within the file is pretty much up to you. (As long as it follows any 'include' directives and does not break up any multi-line structures.)

Updating Software

Back to Top

Question	Response
How do I get updates to the data?	Periodic full data dumps of the seed data will be made available with every software release during development, and bi-monthly thereafter. The seed data is presently packaged together with the software itself. It is possible to receive the seed dataset independently of the software, but this is not officially supported at this time.
How do I get updates to the software?	Periodic releases of the software are posted here. Please see the (Installation instructions) for details on installation. In-place upgrades to the software are not official supported at this time.
Who is maintaining the software?	NIH NCATS is maintaining the software source code, and providing the core updates, bug fixes, and releases. NIH NCATS currently offers no official support for installations, customizations and extensions of the software by any individual or organization. That said, we want to facilitate its use by the community and make available our technical expertise for those that intend to take a deep dive with the software. Feel free to contact us with questions and feedback (including bug reports!).
Who is maintaining the data?	The seed data dump is a compilation of various data sources (most notably the FDA SRS), as well as certain testing and example data. NIH NCATS has partnered with the FDA in an attempt to make the seed dataset maximally useful, but with no guarantee of its accuracy. At this time, the source data is primarily maintained by the FDA, with the compilation procedure being maintained by NCATS.

$\textcolor{purple}{\textsf{Thank you!}}$