== Introduction

QGIS' [https://docs.qgis.org/testing/en/docs/user_manual/processing/index.html# Processing framework] is a geoprocessing environment that can be used to call native and third-party algorithms from QGIS. GRASS GIS is supported as an algorithm provider among a variety of external (to QGIS) applications. More details can be found at [https://docs.qgis.org/testing/en/docs/user_manual/processing/3rdParty.html#grass QGIS processing framework > Configuring external applications > GRASS].

== How does it work?

The GRASS provider for QGIS’ Processing is a graphical interface towards GRASS. In overview:

* A GRASS GIS data base is created on-the-fly in a temporary directory

* Input layers/rasters are imported (or referenced) into this GRASS GIS data base

* Launching a GRASS algorithm from the [https://docs.qgis.org/testing/en/docs/user_manual/processing/toolbox.html Processing Toolbox] is essentially a GRASS GIS command line with the requested parameters, executed in the shell or as a system call onto the temporary GRASS GIS database. This command line is recorded in a log.

* Results returned by the algorithm, are extracted from the GRASS GIS temporary database and converted into layers/rasters (and directly opened in QGIS if the respective option has been enabled).

* Finally, the temporary GRASS GIS data base is deleted

== Integrating an add-on under the GRASS provider

To integrate an add-on in the GRASS provider, it is required to build a ''description'' file. A ''description'' file will suffice for ''simple algorithms'', i.e. import input data, execute a single GRASS GIS command and extract data.  However, if an algorithm consists of multiple actions (i.e. a preliminary check of the imported data, executing more than one GRASS GIS commands or transforming the output data before the extraction), then the ''ext'' mechanism has to be used. The ''ext'' mechanism is a way to add additional logic to an algorithm. More on this mechanism in the following sections.

=== Description file

* A '''description file''' describes the different parameters of an add-on

* The name of the description file must be identical to the add-on name

* Description files are placed under `python/plugins/processing/algs/grass7/description/`.  Reading some of those files helps to understand the different options.

=== QGIS' Processing interface to GRASS

In the code of the GRASS provider for QGIS' Processing framework (`python/plugins/processing/algs/grass7/Grass7Algorithm.py`) there are 4 pre-defined methods to interact with GRASS GIS. These are: `processCommand`, `processInputs`, `processOutputs`, `checkParameterValuesBeforeExecuting`.

These methods reflect 4 levels of algorithmic building blocks:

1. '''Checking the input parameters'''. For example, in the case of two exclusive options, to verify that both have been enabled.

2. '''Processing inputs import'''. In the case of processing input layers after importing.

3. '''Processing the command by itself'''. For example, chaining several GRASS commands together.

4. '''Processing the outputs export'''. For example to perform special things before exporting layers or if using special export methods.

=== Building complex algorithms

To add some logic on one or more levels, the pre-defined methods will be overriden by custom ones defined in a Python file, named after the add-on and placed under the `ext` directory.  In this way, the custom methods will be imported and run instead of the pre-defined ones. This enables to build an interface for complex GRASS GIS algorithms in QGIS' Processing Toolbox.

Specifically, a `.py` file, named after the add-on ('''note:''' substitute `.` with `_`), has to be created under `python/plugins/processing/algs/grass7/ext`. In this Python file, custom methods need to be defined with the following names:

- `checkParameterValuesBeforeExecuting` for Input parameters
- `processInputs` for Inputs import
- `processCommand` for Inputs import
- `processOutputs` for Outputs export