source: trunk/docs/services/process-profiles.txt @ 615

.. _process-profiles:
    
Process Profiles Registry
=========================================  

:Authors: Nicolas Bozon, Gérald Fenoy, Jeff McKenna
:Last Updated: $Date: 2015-03-12 13:31:37 +0000 (Thu, 12 Mar 2015) $

.. contents:: Table of Contents
    :depth: 3
    :backlinks: top

Many times, services from the same ServicesProvider share inputs and
outputs. In such a casse, defining the ZCFG files for each service
from the same provider may lead to rewrite the same metadata
informations in different files. 

From `rev. 607 <http://www.zoo-project.org/trac/changeset/607>`__, the
ZOO-Kernel is able to handle metadata inheritance, it create a
Registry (before loading any other ZCFG files) containing a set of
Process Profiles organized in levels depending on their position in
the hierarchy:

:Concept: the higher level in the hierarchy, concepts are basically
   txt files containing an abstract description of a service,
:Generic: a generic profile can make reference to concepts, it defines
   inputs and outputs but nor the data format nor the maximum size
   limitation,
:Implementation: an implementation profile can inherit from a generic
   profile and make reference to concepts, it contains all the
   metadata informations about a service (see
   `ref. <cfg-reference.html#main-metadata-information>`__).

Both Generic Process Profiles and Process Implementation Profiles are
created  from ZCFG files, stored in the registry sub-directories
depending on their level: ``concept``, ``generic`` and
``implementation``.

To activate the registry, you have to add a ``registry`` key to the
``[main]`` section of your ``main.cfg`` file, and set its value to the
directory path used to store the profile ZCFG files.


Generic Process Profile
-----------------------

A Generic Process Profile is a ZCFG file located in the ``generic``
sub-directory, it defines `main metadata information
<zcfg-reference.html#main-metadata-information>`__, inputs and outputs
name, basic metadata and multiplicity. It can make reference to a
concept by defining a ``concept`` key in the `main metadata
information <zcfg-reference.html#main-metadata-information>`__ part.

You can find below the `GO.zcfg` file, a typical Generic Process
Profile for Generic Geographic Operation, taking one InputPolygon
input parameter and returning a result named Result, it make reference
to the ``GOC`` concept:

.. code-block:: none
   :linenos:
   
   [GO]
    Title = Geographic Operation
    Abstract = Geographic Operation on exactly one input, returning one output
    concept = GOC
    level = generic
    statusSupported = true
    storeSupported = true
    <DataInputs>
     [InputPolygon]
      Title = the geographic data
      Abstract = the geographic data to run geographipc operation
      minOccurs = 1
      maxOccurs = 1
    </DataInputs>
    <DataOutputs>
     [Result]
      Title = the resulting data
      Abstract = the resulting data after processing the operation
    </DataOutputs>  


.. Note:: if you need to reference more than one concept, you should
    separate their names with a comma (ie. concept = GO,GB),

Process Implementation Profile
------------------------------

A Process Implementation Profile is similar to a `ZCFG file
<zcfg-reference.html>`__ located in the `implementation`
sub-directory, it defines (or inherit from its parent) all the
properties of a `Generic Process Profile <#generic-process-profile>`__
and specify `Data Format <zcfg-reference.html#type-of-data-nodes>`__
for both inputs and outputs. It can make reference to a concept by
defining a ``concept`` key in the `main metadata information
<zcfg-reference.html#main-metadata-information>`__ part.

You can find below the `VectorOperation.zcfg` file, a typical Process
Implementation Profile for Vector Geographic Operation, it inherit
from the `GP generic profile <#generic-process-profile>`__:

.. code-block:: none
   :linenos:
   
   [VectorOperation]
    Title = Vector Geographic Operation
    Abstract = Apply a Vector Geographic Operation on a features collection and return the resulting features collection
    extend = GO
    level = profile
    <DataInputs>
     [InputPolygon]
      Title = the vector data
      Abstract = the vector data to run geographic operation
      <ComplexData>
       <Default>
        mimeType = text/xml
        encoding = UTF-8
        schema = http://fooa/gml/3.1.0/polygon.xsd
       </Default>
       <Supported>
        mimeType = application/json
        encoding = UTF-8
        extension = js
       </Supported>
    </DataInputs>
    <DataOutputs>
     [Result]
      Title = the resulting data
      Abstract = the resulting geographic data after processing the operation
      <ComplexData>
       <Default>
        mimeType = text/xml
        encoding = UTF-8
        schema = http://fooa/gml/3.1.0/polygon.xsd
       </Default>
       <Supported>
        mimeType = application/json
        encoding = UTF-8
        extension = js
       </Supported>
      </ComplexData>
    </DataOutputs>  


ZCFG inheritance
----------------------------------

For the ZCFG files at the service level, you can inherit the metadata
from a Process Implementation Profile available in the registry. As
before, you simply need to add a ``extend`` key refering the ZCFG you
want to inherit from and a ``level`` key taking the `ìmplementation``
value to your main metadata informations.

So, for example, the original `ConvexHull.zcfg
<http://www.zoo-project.org/trac/browser/trunk/zoo-project/zoo-services/ogr/base-vect-ops/cgi-env/ConvexHull.zcfg?rev=491>`__
may be rewritten as:

.. code-block:: none
   :linenos:
   
   [ConvexHull]
    Title = Compute convex hull.
    Abstract = Return a feature collection that represents the convex hull of each geometry from the input collection.
    serviceProvider = ogr_service.zo
    serviceType = C
    extend = VectorOperation
    level = implementation

Now, suppose that your service is able to return the result in KML
format, then you may write the following:

.. code-block:: none
   :linenos:
   
   [ConvexHull]
    Title = Compute convex hull.
    Abstract = Return a feature collection that represents the convex hull of each geometry from the input collection.
    serviceProvider = ogr_service.zo
    serviceType = C
    extend = VectorOperation
    level = implementation
    <DataOutputs>
     [Result]
        <Supported>
         mimeType = application/vnd.google-earth.kml+xml
         encoding = utf-8
        </Supported>
    </DataOutputs>