Running SUSHI

Running SUSHI

SUSHI is executed from the command line. The general form of the SUSHI execution command is as follows:

 sushi {specification-directory} {options}

where options include the following (in any order):

-d, --debug         output extra debugging information
-h, --help          output usage information
-i, --init          initialize a SUSHI project
-o, --out <out>     the path to the **fsh-generated** folder
-p, --preprocessed  output FSH produced by preprocessing steps
--require-latest    indicate that SUSHI should halt if the latest SUSHI version is not installed
-s, --snapshot      generate snapshot in Structure Definition output (default: false)
-v, --version       print SUSHI version

Command Line Argument Details

The following sections give further detail on using certain command line options.

--out

The --out or -o flag specifies where SUSHI’s output, the fsh-generated folder, should be written. By default, the folder will be written to the root folder, i.e., parallel to the input folder. When SUSHI begins, any existing content in the designated location is deleted. Within the fsh-generated folder, SUSHI generates file names based on the resource id (i.e., ${resourceType}-${resourceId}.json). If the id contains one or more path separators, SUSHI will sanitize file names to assure all files are written to the target directory. (Note: the --out option does not refer to the output folder written by the IG Publisher).

--preprocessed

The --preprocessed or -p flag can be used to to create a folder named _preprocessed in SUSHI’s output folder. This folder will contain representations of the input FSH after several preprocessing steps have taken place. These steps include resolution of Alias values, insertion of RuleSet rules, and resolution of soft indexing. This is mainly provided as a debugging tool, for the author to verify that SUSHI is preprocessing the input FSH in an expected way, and to help trace errors in the output of SUSHI back to their source. For example, if the IG Publisher reports an error on element Bundle.entry[56].resource, it may be difficult to identify the problematic entry in your FSH source if you used soft-indexing. It is much easier, however, to identify the problematic element in the preprocessed FSH that contains explicit indices.

The example below shows a FSH snippet and a preprocessed version of that snippet. In this snippet, a Profile is defined using a RuleSet and an Alias, and below an Instance is defined which uses soft indexing.

Alias: $CAT = http://hl7.org/fhir/ValueSet/observation-category

Profile: ObservationProfile
Parent: Observation
* insert Metadata
* category from $CAT (required)

RuleSet: Metadata
* ^version = "1.2.3"
* ^publisher = "Example publisher"

Instance: PatientInstance
InstanceOf: Patient
* name.given[+] = "John"
* name.given[+] = "Q"

The preprocessed version of the above FSH is shown below. The $CAT alias has been resolved to its full URL, the rules contained in the RuleSet have been inserted onto the ObservationProfile, and the RuleSet itself has been removed, and the rules on the PatientInstance have been resolved to fully specified paths, which do not use soft indexing.

Alias: $CAT = http://hl7.org/fhir/ValueSet/observation-category

// Originally defined on lines 3 - 6
Profile: ObservationProfile
Parent: Observation
Id: ObservationProfile
* ^version = "1.2.3"
* ^publisher = "Example publisher"
* category from http://hl7.org/fhir/ValueSet/observation-category (required)

// Originally defined on lines 12 - 15
Instance: PatientInstance
InstanceOf: Patient
Usage: #example
* name.given[0] = "John"
* name.given[1] = "Q"

--snapshot

By default, SUSHI only generates the profile differential, allowing the IG Publisher to create the profile snapshot. This is the approach recommended by HL7 FHIR leadership. If authors prefer, the --snapshot (or -s) option can be used to cause SUSHI to generate the snapshot without having to run the IG Publisher.

Status Messages

While SUSHI is running, it will print status messages as it processes your project files. When SUSHI has completed, you should receive a summary like the following:

╔════════════════════════ SUSHI RESULTS ══════════════════════════╗
║ ╭───────────────┬──────────────┬──────────────┬───────────────╮ ║
║ │    Profiles   │  Extensions  │   Logicals   │   Resources   │ ║
║ ├───────────────┼──────────────┼──────────────┼───────────────┤ ║
║ │       1       │      1       │      1       │       1       │ ║
║ ╰───────────────┴──────────────┴──────────────┴───────────────╯ ║
║ ╭────────────────────┬───────────────────┬────────────────────╮ ║
║ │      ValueSets     │    CodeSystems    │     Instances      │ ║
║ ├────────────────────┼───────────────────┼────────────────────┤ ║
║ │         1          │         1         │         1          │ ║
║ ╰────────────────────┴───────────────────┴────────────────────╯ ║
║                                                                 ║
╠═════════════════════════════════════════════════════════════════╣
║ Fin-tastic job!                        0 Errors      0 Warnings ║
╚═════════════════════════════════════════════════════════════════╝
Last modified June 23, 2022: Update sushi doc (#64) (7c3c8b4)