Other features
==============

Electronic logbook
------------------

`IcatClient` can be used to send messages and images to beamline and experiment session logbooks.

1. Getting an `IcatClient` instance

From the current BLISS session:

.. code-block:: python

    from bliss import current_session

    icat_client = current_session.scan_saving.icat_client

or create an `IcatClient`:

.. code-block:: python

    from pyicat_plus.client.main import IcatClient

    API_KEY = ""  # Replace with your API key
    ENDPOINT_URL = "https://icatplus.esrf.fr"

    client = IcatClient(elogbook_url=ENDPOINT_URL, elogbook_token=API_KEY)

2. Send a message to the beamline logbook

.. code-block:: python

    BEAMLINE = "ID00"
    TAGS = ["test"]

    # Send a text message
    client.send_message(
        msg="This is a message to the beamline logbook",
        beamline=BEAMLINE,
        beamline_only=True,
        tags=TAGS,
    )

    # Send an image or a file
    client.send_binary_file(
        filename="/path/to/file.png",  # Replace with your file
        beamline=BEAMLINE,
        beamline_only=True,
        tags=TAGS,
    )

3. Send a message to the experiment session logbook

.. code-block:: python

    PROPOSAL = "id002510"

    # Send a text message
    client.send_message(
        msg="This is a message to the experiment session logbook",
        beamline=BEAMLINE,
        proposal=PROPOSAL,
        tags=TAGS,
    )

    # Send an image or a file
    client.send_binary_file(
        filename="/path/to/file.png",  # Replace with your file
        beamline=BEAMLINE,
        proposal=PROPOSAL,
        tags=TAGS,
    )


To log to the electronic logbook from BLISS, see the `BLISS documentation <https://bliss.gitlab-pages.esrf.fr/bliss/master/data/data_logbook.html>`_. 


Authenticated access
--------------------

Using SSO:

.. code-block:: python

    from pyicat_plus.client.main import IcatClient

    URL = "https://icatplus.esrf.fr/"
    sso_token = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

    icatClient = IcatClient(icatplus_restricted_url=URL)
    icatClient.do_log_in(sso_token)


Using another authentication plugin:

.. code-block:: python

    from pyicat_plus.client.main import IcatClient

    URL = "https://icatplus.esrf.fr/"
    
    icatClient = IcatClient(icatplus_restricted_url=URL)
    icatClient.do_log_in(password="****", username="daiquiri", plugin="db")


Example: retrieve sample metadata

.. code-block:: python

    from datetime import date

    metadata = icatClient.get_sample_metadata_by(
        proposal="hg237", beamline="id13", session_start_date=date(2025, 7, 24)
    )
    print(metadata)


Drac Report Builder
-------------------
`DracReportBuilder` generates Data Portal-compatible dataset reports containing text, tables, files, and image galleries.  
Reports can be previewed locally as HTML and exported as JSON for ingestion into the Data Portal.

Example:

   .. code-block:: python

      from pyicat_plus.metadata.drac_report_builder import DracReportBuilder

      # Create report
      report = DracReportBuilder(
          dataset_type="Characterisation",
          dataset_title="Characterisation Results",
      )

      # Add text elements
      report.add_info("This is a demo info item.")
      report.add_warning("Warning !")

      # Add a table
      report.add_table(
          title="Sample Table",
          columns=["Name", "Value"],
          data=[["Alpha", 1], ["Beta", 2]],
          orientation="horizontal",
      )

      # Add a downloadable file
      report.add_log_file(
          title="My Log",
          link_text="My Log",
          path_to_log_file="log.txt",
      )

      # Add a row of images (must be inside an image list)
      report.start_image_list()
      report.add_image(
          path_to_image="Image1.png",
          image_title="AXO",
          path_to_thumbnail_image="Image_thumbnail.png",
          thumbnail_height=100,
          thumbnail_width=100,
      )
      report.add_image(
          path_to_image="Image2.png",
          image_title="AXA",
          path_to_thumbnail_image="Image_thumbnail.png",
          thumbnail_height=40,
          thumbnail_width=40,
      )
      report.end_image_list()

      # Preview locally (optional)
      report.render_html(
          path_to_html_dir="./path_to_preview_dir/",
          name_of_index_file="index.html",
      )

      # Export DRAC JSON
      report.render_json(
          path_to_json_dir="./path_to_gallery",
      )