Use blissoda in a Bliss session
===============================

Ewoks workflows are executed by workers **outside** the Bliss environment.  
They are submitted using the ``submit`` function from ``ewoksjob.client``.

The ``blissoda`` project defines the logic for **when workflows are submitted**  
and **with which parameters** for all ESRF beamlines.  
This logic is always implemented in a class derived from  
``blissoda.automation.BlissAutomationObject``.

These automation objects can be used in a Bliss session in two ways:

1. Declared in the Beacon configuration (**preferred**)  
2. Imported in the Bliss session setup script  

Beacon configuration
--------------------

Classes derived from ``blissoda.automation.BlissAutomationObject`` can be  
`configured in Beacon <https://bliss.gitlab-pages.esrf.fr/bliss/master/config_plugins.html#plugin-generic>`_.

For example, the class ``blissoda.id14.converter.Id14Hdf5ToSpecConverter``  
can be added to the configuration file:

``/users/blissadm/local/beamline_configuration/misc/blissoda.yml``

Example configuration:

.. code-block:: yaml

   - name: spec_converter
     plugin: generic
     class: Id14Hdf5ToSpecConverter
     package: blissoda.id14.converter
     queue: celery

In this example, the parameter ``queue="celery"`` is explicitly set.  
Note that ``celery`` is the **default queue** if no value is defined in Redis  
for a given Bliss session. Once a value is set in Redis, changing this parameter  
in the configuration file will have no effect.

With this configuration, any Bliss session can import the object.  
For example:

.. code-block:: yaml

   class: Session
   name: mysession
   setup-file: ./mysession_setup.py
   config-objects:
     - spec_converter

Bliss session setup script
--------------------------

As an alternative, objects can be instantiated directly in the session setup script.

For example, for a Bliss session named ``mysession`` the setup script is:

``/users/blissadm/local/beamline_configuration/sessions/mysession_setup.py``

The ``Id14Hdf5ToSpecConverter`` class can be instantiated like any other Python class:

.. code-block:: python

   from bliss.setup_globals import load_script

   load_script("mysession.py")

   from blissoda.id14.converter import Id14Hdf5ToSpecConverter
   data_converter = Id14Hdf5ToSpecConverter(config={"queue": "celery"})

   print("")
   print("Welcome to your new 'mysession' BLISS session !!")
   print("")
   print("You can now customize your 'mysession' session by changing files:")
   print("   * /mysession_setup.py")
   print("   * /mysession.yml")
   print("   * /scripts/mysession.py")
   print("")