Creating and publishing packages

Important

Before publishing a package, please make sure you read our Package Policy.

Simplifier.net offers functionality to handle packages and dependencies. This functionality allows you to publish packages based on your project resources, which can be immediately installed and used by people implementing your profiles. The Simplifier FHIR package server is NPM compatible. You may either connect to this server using a NPM client or use our cross platform FHIR command line tool called Firely Terminal. On this page we will explain how to create and manage packages in Simplifier, and where to learn about packages in Firely Terminal. The packages your project depends on are covered in Managing dependencies.

Package Releases

View releases

Visit the Releases tab of any Simplifier project to see which packages are published from this project. For more information about a package and its content, click on the name of the package.

A package page has these tabs:

  • Introduction: the release notes given by the author of the package, how many conformance resources and examples it contains, and information such as when it was created, the project it is part of, its documentation and the feeds it is in.

  • Files: every file in the package. Search and filter them by resource category, core base type, example resource type and FHIR status, the same way as on the Resources tab of a project.

  • Install: the command you need to install the package. Click on the blue copy icon to copy it to your clipboard. Click on Firely Terminal or NPM to switch to your preferred tooling.

  • Dependencies: the dependencies to other packages, see View dependencies.

  • History: the other versions of the package. Click on a version name to see the details.

Use Download in the menu at the top of the page to download the package, with or without snapshots. You need to be logged in. The first time a package is downloaded with snapshots, Download snapshots opens a console that generates a snapshot for every profile in the package and reports the profiles it could not snapshot. After that, the download starts straight away.

A package URL can name a version range instead of an exact version. https://simplifier.net/packages/nictiz.fhir.nl.stu3.zib2017/1.3.x opens the highest listed 1.3 version; 1.3 and 1.x work the same way. Pre-release and unlisted versions are skipped. If no version matches, Simplifier opens the newest version and tells you the requested version was not found.

../_images/PackageView.png

Switch to the Files tab to see the content of the package.

../_images/PackageFiles.png

If you have a combination of private and public packages in your feeds you can see a full overview of your packages in the Distribution view accessible for package team members through the package Administration.

../_images/PackageDistribution.png

Create releases

Visit the Releases tab of your project and click on Create > Create new package to create a new package. Provide a name, version number, description and release notes for your package. Note that the name of your package should include at least one dot. Indicate if your package is a prelease package or not and click Create to publish your package. To create a new version of an existing package, click on Create and select Create new version for.. followed by the name of your package. Add the required information and click Create to publish the new version of your package.

Packages can be created as private packages or public packages. Private packages are only visible for the team members inside the project from where the package is created and public packages will be visible to all of Simplifier.

../_images/PackageRelease.png

The package created with the highest semver will get the tag latest added to the package. Please see how semver works with regards to versioning and pre-release tags.

When a package is created, every resource in it that does not already have a version is given the package version in its version element.

Pin canonical references

When you create a package you can choose to pin its canonical references. Unversioned canonical references resolve to whatever version happens to be in scope, and that version can change as your dependencies evolve. Pinning locks each reference to the version found in the dependency closure at creation time, so the package keeps resolving to the versions you built and tested against.

You will find the option on the Content tab of the package creation wizard, under Versioning. Tick Pin canonical references to their resolved version before you create the package.

../_images/PackageCanonicalPinning.png

With this option enabled, unversioned canonical references (for example baseDefinition or type profiles) are pinned to the version found in the dependency closure when the package is created.

How pinned and unpinned references are resolved is explained in How references are resolved.

Note

Canonical pinning is currently in beta. We recommend running the canonical-pinning Quality Control rule before creating a package with pinning enabled, so you can catch any issues first.

Unlist releases

Once a package is created it can be used by other implementers to build their project on top of. For this reason we do not delete packages from the Registry. Once a package is created it is there to stay. Implementers can depend on the availability of published packaged.

In some cases you might want new implementers to no longer find a specific version of a package. For these cases you can unlist a package. This can be done by the package owner in the package Administration.

../_images/UnlistPackage.png

When a package is unlisted, it will no longer show up for implementers on the Registry or on Simplifier. As a creator of the package you will still be able to see the package with an unlisted label added.

../_images/UnlistedPackage.png

Bake Pipeline

Licensed Simplifier users are able to use our Bake Pipeline. The Bake pipeline is an important part of making high quality packages, but also other types of publications.

With a bake script you can define the internal structure and content of your package publication. See the FHIR Package Specification for the valid format of a FHIR package: https://confluence.hl7.org/display/FHIR/NPM+Package+Specification

On Simplifier you can start by creating your own package.bake.yaml file.

../_images/BakeYaml.png

In that yaml file you can specify if you want snapshots included for all you resources, or if you only want a specific selection of resources and example instances added to your package. You can even transform FSH files in your project into resources when creating your package!

See the full Bake syntax documentation for the script format, all available steps, and a worked example.

../_images/BakeYamlFile.png

When a package.bake.yaml file is available, Simplifier will use that file to determine the content of the package you are creating.

Below you can find an example of how to use the package.bake.yaml file in your own project.

# Transform all resources to JSON (Mandatory according to the specification)
transform-to-json:
  - source: input
  - category: Resource
  - transform: json
  - target: bucket1

# Generate snapshots for all StructureDefinitions (Optional)
# Note, since the file names stay the same the files will be overwritten and we do not need an extra bucket.
generate-snapshots:
  - source: bucket1
  - category: Profile
  - action: snapshot
  - target: bucket1

# Move all conformance resources to the /package folder (Mandatory according to the specification)
move-conformance-resources:
  - source: bucket1
  - category: Conformance
  - move: /package/
  - target: output

# Move all examples to the /package/examples folder (Optional)
move-examples:
  - source: bucket1
  - category: Instance
  - move: /package/examples
  - target: output

# Move the Package Manifest to the /package folder (Mandatory according to the specification)
manifest:
  - source: input
  - files: package.json
  - move: /package

# Generate an .index.json file with all files in the package (Optional)
index-file:
  - source: output
  - files: /package/**/*.json
  - action: create-package-index
  - move: /package

Firely Terminal

Important

Packages published outside of the Simplifier projects no longer show up under the Releases tab.

Firely Terminal is our (free) command line tool for FHIR. Firely Terminal allows you to communicate with any FHIR server. With simple commands you can easily download, upload, validate and transform resources, zip them, bundle them or split bundles. Firely Terminal offers many features. One of them is to install and create FHIR packages.

Learn more about Firely Terminal and managing FHIR packages on the command line in particular.