HRA - RUI Locations Processor

The HRA - RUI Locations Processor is a basic tool for processing the RUI Locations to minimize the human efforts and reducing errors thereby maintaining the consistency across the application.

Quick Start

Once installing Node.js v16+ with NPM, you can run

npx github:hubmapconsortium/hra-rui-locations-processor help

to run the code without checking out the code manually with github.

Steps to install the software

Prerequisite

• Microsoft Visual Studio Code ( VS Code) - https://code.visualstudio.com/download
• Adding the YAML Extension - In the VS Code, on the vertical ribbon (Activity Bar) to the left click on Extension icon () and search for yaml and chose the one developed by Red Hat and install.
• Node.js v16+

1. Clone the repo

$ git clone https://github.com/hubmapconsortium/hra-rui-locations-processor.git
$ cd hra-rui-locations-processor

Or check out the same with Visual Studio Code or GitHub Desktop

2. Setting up the software

$ npm ci

3. Interacting with the software

The software can be interacted with a terminal. There are two options the software provides:

• normalize: With this option, the registrations.yaml file will be scanned, the missing metadata will be generated and added, and rui_locations.jsonld file will be generated.

Commands to interact with the software

​Open a terminal and refer to the commands below.

$ npm run hra-registration-processor <command> <path/to/directory>

# Example:
$ npm run hra-registration-processor new ./data/sea-ad/            # This command starts a new registrations digital object.
$ npm run hra-registration-processor normalize ./data/sea-ad/      # This command will normalize the registrations.yaml file. It will search for the file in '.data/sea-ad/' folder.
$ npm run hra-registration-processor json-schema ./temp/file.json  # (Rarely used) this command will generate a new json-schema which will be used to validate against the registrations.yaml file. The new json-schema will be created in the temp folder, the file name will be file.json
$ npm run hra-registration-processor help 	# This command will show the help menu which displays the options and descriptions.

If everything goes well, after executing the commands, you will not see any error(s).

Documentation

The tool uses a YAML file to generate the JSON-LD file containing the providers, and the RUI Locations. The examples (refer here) provides 3 schemas. Refer the registrations.yaml file in each folder to view the schemas.

Notice the first line of each registrations.yaml file, ( # yaml-language-server: $schema=https://raw.githubusercontent.com/hubmapconsortium/hra-rui-locations-processor/main/registrations.schema.json). The YAML file will be validated against this registrations.schema.json file. This file can be generated by choosing option as json-schema while interacting with the software.

So, on first line of every registrations.yaml file, you need to mention the path of schema file (schema.json) file.

# yaml-language-server: $schema=<path/to/schema.json>

Once the schema file is set, and loaded properly into the yaml file (Setting the first line) you can start entering the data.

YAML is case-sensitive and whitespace-sensitive and indentation defines the structure.

Cheat sheet for editing the YAML file

• The array in YAML starts with a hyphen (-) followed by a space.

• Press ctrl+space to get suggestions about adding any key field in the YAML file.

• If any required key is missing, it will be denoted by a small red marker for the section. Hover over it and it will tell which property is missing.

• The value for rui_locations can be either a JSON filename containing the RUI locations or an object containing the RUI locations in YAML format defined in same file.