gcube-cms-suite/geoportal-service/docs/lifecycle.rst

5.0 KiB

Project Management (Lifecycle)

Note

You can experiment with the service by following the quickstart.

From creation to its publication/deletion, documents pass through various PHASES of their life. These PHASES define what operations (called STEPS) can be performed with the project, being them automatic or human-driven (e.g. moderated review). When invoked, operations may trigger collateral EVENTS (e.g. ON_EDIT). The result of all these operations may change the nature of the target project, which contains a specific report for this (see lifecycle)

Note

In brief : STEPS are operations that can be invoked by callers, EVENTS are collateral operations.

Projects lifecycle can vary depending on the configuration declared in its related ucd. However they may change, each project lifecycle starts from the predefined PHASE = DRAFT; what comes after that, depends on the configured lifecycle.

_static/imgs/2phase_lc.png
A 2-phase lifecycle.

In the figure above is represented a 2-PHASES lifecycle. In green, STEPS and PHASES defined by the lifecycle itself. In blue are re, the common operations Edit, Delete and the DRAFT PHASE. In red the DELETE PHASE (which isn't material).

Common Lifecycles

The suite comes with a pre-built set of implemented lifecycles with their STEPS, EVENTS and PHASES.

2 - Phases Lifecycle

_static/imgs/2phase_lc.png

3 - Phases Lifecycle

_static/imgs/3phase_lc.png

*************** Operation on documents*************** .. note:: You can experiment with the service API by following the quickstart.

Warning

Read and write permissions on projects are defined in ucd

While projects lifecycle can vary depending on the configuration declared in its related ucd, following operations are common and available for every project.

Basic operations

  • Create New : The starting operation of every project. It expects a JSON metadata document, which will constitute the document section of the project.
  • Edit : Allows for the replacement of document.
  • Delete : Deletes the specified project
  • List / get by Id : allows access to projects.

Querying

Querying allows for the filtered access of subsets of projects. The following options are allowed in query operations

Note

Query engine is supported by MongoDB and exploits its query language. Check it out to learn more about it.

  • filter : condition by witch to select returned projects
  • ordering : field set and direction
  • paging : limit and offset
  • projection : projects fields selection to return in result

Registering / Unregistering FileSets

filesets are sets of files representing a single entity, which need to be handled together (e.g. a dataset and its index, a file and its crc).

Each filesets is (un)registered at a particular path of the document with requests with the following information :

Warning

Filesets fields need to be defined in ucd in order to be registered.

  • field Name : fileset target field name
  • parent path : the path of the target parent for the fileset
  • field Definition path : the path of the field definition inside schema
  • streams : url or gCube storage Volatile IDs of payloads and related filenames
{
"fieldDefinitionPath":"$.section._children[?(@.fileset)]",
"parentPath":"$.section",
"fieldName":"fileset",
"streams":[{"url":"https://www.cnr.it/sites/all/themes/custom/cnr03_theme/img/cnrlogo.svg","filename":"myLogo.svg"}]
}

Note

Note that paths can be explicit or express a query. Refer to jsonpath lib.

Warning

Paths are required to match a single field for fileset registration.

Executing STEPS

In order to expose a common API while serving varying / customizable possible scenarios, the service expose only a single method for STEP execution.

The method perform STEP allows for the execution of the configured STEPs by serving requests with the following information:

  • STEP ID : must be supported by the configured lifecycle
  • options [optional]: a JSON document with all expected parameters for the execution of the specified STEP

Note

Outcome of STEPS and operations is reported in :ref`lifecycle` section of the project.

Steps execution may trigger EVENTS and sometimes other automatic STEPS. The following represents how this behaviour is implemented.

_static/imgs/step_execution.png