nf-openBIS Plugin

This project implements a nextflow plugin offering channel factories emitting and consuming openBIS objects.

NOTE: this repo is based on nf-hello. Documentation and certain files reflect this.

Plugin structure

settings.gradle

Gradle project settings.
plugins/nf-hello

The plugin implementation base directory.
plugins/nf-hello/build.gradle

Plugin Gradle build file. Project dependencies should be added here.
plugins/nf-hello/src/resources/META-INF/MANIFEST.MF

Manifest file defining the plugin attributes e.g. name, version, etc. The attribute Plugin-Class declares the plugin main class. This class should extend the base class nextflow.plugin.BasePlugin e.g. nextflow.openbis.OpenbisPlugin.
plugins/nf-hello/src/resources/META-INF/extensions.idx

This file declares one or more extension classes provided by the plugin. Each line should contain the fully qualified name of a Java class that implements the org.pf4j.ExtensionPoint interface (or a sub-interface).
plugins/nf-hello/src/main

The plugin implementation sources.
plugins/nf-hello/src/test

The plugin unit tests.

Plugin classes

HelloConfig: simple example how to handle configuration options provided via the Nextflow configuration file.
HelloExtension: show how create an extension class that can be used to create custom channel factories, operation and fuctions that can be imported in the pipeline script as DSL extensions.
HelloFactory and HelloObserver: show how to intercept workflow runtime events and react correspondly with custom code.
HelloPlugin: the plugin entry point.

Unit testing

Run the following command in the project root directory (ie. where the file settings.gradle is located):

./gradlew check

Testing and debugging

To run and test the plugin in for development purpose, configure a local Nextflow build with the following steps:

Clone the Nextflow repository in your computer into a sibling directory:
```
git clone --depth 1 https://github.com/nextflow-io/nextflow ../nextflow
```
Configure the plugin build to use the local Nextflow code:
```
echo "includeBuild('../nextflow')" >> settings.gradle
```
(Make sure to not add it more than once!)
Compile the plugin alongside the Nextflow code:
```
make compile
```
Run Nextflow with the plugin, using ./launch.sh as a drop-in replacement for the nextflow command, and adding the option -plugins nf-hello to load the plugin:
```
./launch.sh run nextflow-io/hello -plugins nf-hello
```

Testing without Nextflow build

The plugin can be tested without using a local Nextflow build using those steps:

generate required artifacts with make buildPlugins
copy build/plugins/your-plugin to $HOME/.nextflow/plugins
create a pipeline with your plugin and see in action via nextflow run ./my-pipeline-script.nf

Package, upload and publish

The project should be hosted in a GitHub repository whose name should match the name of the plugin, that is the name of the directory in the plugins folder (e.g. nf-hello).

Follow these steps to package, upload and publish the plugin:

Create a file named gradle.properties in the project root containing the following attributes (this file should not be committed to Git):
- github_organization: the GitHub organisation where the plugin repository is hosted.
- github_username: The GitHub username granting access to the plugin repository.
- github_access_token: The GitHub access token required to upload and commit changes to the plugin repository.
- github_commit_email: The email address associated with your GitHub account.
Use the following command to package and create a release for your plugin on GitHub:
```
./gradlew :plugins:nf-hello:upload
```
Create a pull request against nextflow-io/plugins to make the plugin accessible to Nextflow.