MAJOR: solves problem related to ELABFTW_API_URL variable

if no value was specified for such variable (or .env was missing)
EAU would be set to None and get stuck in a prompt loop

solved by turning EAU into a required variable in APIHandler
(and editing a lot of code through all of src/)

.env.example

@@ -1,4 +1,4 @@
 api_key=""
 elabid=""
 ELABFTW_API_URL="https://elabftw.fisica.unina.it/api/v2"
-operative_unit="Napoli"
+operative_unit="cnr-spin.na"

.gitignore

@@ -1,3 +1,6 @@
+# ignores bkp files of drawio
+.$*.bkp
+
 # ignores logs of h5tojson, jsontoh5
 *.log
 

docs/user-manual_01.adoc

@@ -44,6 +44,7 @@ On the other hand, *NeXus* is a common data standard [.underline]#built on top o
 
 Last but not least, NeXus is also the format of choice for data sharing in the NFFA-DI guidelines. Which brings us to the reason why {software-family} exists.
 
+[#reading-nxs]
 ==== Reading HDF5/NeXus files
 While writing an HDF5/NeXus file usually requires dedicated software and/or a good knowledge of programming and familiarity with specific libraries (like h5py), there are multiple ways to read these files even without such knowledge.
 

docs/user-manual_02.adoc

@@ -0,0 +1,171 @@
+== Using the software
+WARNING: This software requires Python 3.12 or later. +
+The module *venv* and the package manager *pip* are also required.
+
+=== Downloading the source code
+IMPORTANT: Currently ({revdate}) the source code is hosted on a private Gitea instance, owned by {author}. +
+If the site is down for maintenance or temporarily unavailable please contact the webmaster via mailto:{email}[e-mail].
+
+// TO-DO: add link to direct download of package
+The source code can be acquired directly via *git*, or downloaded from the official repository on link:{repo-url}[Gitea D'Amico^].
+
+[source,bash,subs="verbatim,attributes"]
+----
+git clone {repo-url}.git {software-name}
+cd {software-name} # enter directory
+ls
+  LICENSE    docs/     output/           src/
+  README.md  glossary  requirements.txt  tests/
+----
+
+Optionally, you can access the code in the development branch by executing:
+[source,bash]
+----
+git checkout dev
+----
+
+=== Preparing the environment
+Before starting {software-name} {revnumber} requires a total of 6 modules to be installed, which are listed link:{repo-url}/src/branch/main/requirements.txt[here^]. Since installing a Python module system-wide is almost never a good idea, start by creating and activating a virtual environment.
+
+In the software folder, run:
+
+[source,bash]
+----
+# Calls venv module to create new Python virtual environment in .venv:
+python3 -m venv .venv
+# If command is successful, running ls should show a new .venv folder:
+ls -d .*
+  .venv
+# Activate venv:
+source .venv/bin/activate
+----
+
+.Most shells like Bash show very clearly when you're working inside a virtual environment.
+[#usage-venv]
+image::usage-venv.png[]
+
+At this point you're free to install the requirements through *pip*:
+[source,bash]
+----
+# Install from list in requirements.txt:
+pip install -r requirements.txt
+----
+
+Most of the warnings displayed by pip are safe and generally it's not dangerous to ignore them. +
+Unless pip exits abruptly returning an error, you environment is ready to work.
+
+=== Configuration through .env file
+// foggetaboutit
+Much like the previous step, configuring the software with your settings (API key, eLabFTW URL...) is something you do _una tantum_ and then usually forget about it.
+
+Inside the {software-name} folder there's a file called `.env.example`. Rename it removing ".example", then open it with your editor of choice. This is your *.env* (or *dotenv*) file.
+
+[source,bash]
+----
+mv .env.example .env
+vim .env
+# The file presents itself like this:
+ 1 | api_key=""
+ 2 | elabid=""
+ 3 | ELABFTW_API_URL="https://elabftw.fisica.unina.it/api/v2"
+ 4 | operative_unit="cnr-spin.na"
+----
+
+* *api_key* is your own personal eLabFTW API key. Generating one is an easy task explained in full detail below.
+* *elabid* is the elabid of the resource you'd like to select (your starting sample); this field can (and probably should) be left blank - in which case the application prompts you for an elabid on runtime, and your answer will not be stored meaning you can easily rerun the program with a different target.
+* *ELABFTW_API_URL* is the URL of your eLabFTW instance; if you're running this from the laboratories in Monte S. Angelo, Naples, you're probably leaving this field as it is.
+* *operative_unit* is the operative unit you ran your experiments from. It's only needed to compose the filename of the NeXus, which can be easily modified anytime later, and it's not necessary for creating the file itself.
+
+None of these fields are required, meaning you can technically skip this entire section. If any of the first three keys are blank or missing you will be prompted to provide the necessary info at runtime, and your answers will not be memorized - meaning e.g. you will have to provide your API key every time you run the program.
+
+NOTE: Do [.underline]#NOT# confuse .env with .venv: the first is a [.underline]#file# containing all the environmental variables you need to run {software-name} properly, the latter is a [.underline]#directory# containing your virtual environment with all the required modules.
+
+==== Generating an eLabFTW API key
+eLabFTW has its own link:{elabftw-apikey-docs}[API documentation^] on which you can rely. A new API key can be generated in the Settings → API Keys page by giving it a name and an access level:
+
+.Screenshot from our eLabFTW. The key must have a name and permissions. Naturally, the key you see here in clear has been invalidated.
+[#api-gen]
+image::usage-apigen.png[align=center,width=75%]
+
+The *name* of the key is a descriptor for you to remember why you created it in the first place - something like "parser_key01". The *permissions* can either be "_Read/Write_" or "_Read-Only_": in the first scenario the key may also be used to edit or create entries you own on eLabFTW, while read-only key only allow GET requests. {software-name} doesn't require writing permissions, so both options will do.
+
+[WARNING]
+.A few warnings.
+====
+* The key eLabFTW generates is [.underline]#only shown once#, then stored encrypted in the database. This means that after closing or refreshing the page the key [.underline]#is lost forever# if not saved on an external support. Which brings us to the second warning.
+* Store and protect your API key like you would your password, as [.underline]#it gives full/limited access to your account# exactly like your password, but without the protection given by 2FA/MFA. For this purpose there are many offline (like link:{keepass-site}[KeePass^]) or online (like link:{bitwarden-site}[BitWarden^]) **password managers**.
+* Your .env file is [.underline]#NOT# a safe place to _store_ your API key. Once pasted there be very careful who you share your files with, and be careful not to expose your key when sending your NeXus files to other computers. If you don't trust your awareness leave the api_key field blank and just paste your API key in the terminal every time you run {software-name}.
+====
+
+=== Running the program
+Open a terminal into the project folder. Before attempting to run the program:
+
+* Make sure your virtual environment is active, or if it isn't run: +
+`source .venv/bin/activate`
+* Make sure the required modules are installed, or if they aren't run:
+`pip install -r requirements.txt`
+* Make sure your .env file is properly set, or if it isn't make sure you know how to paste into the terminal the API key, the elabid of the required source and the URL of your eLabFTW instance (ending in `/api/v2`).
+
+When you're ready, run:
+[source,bash]
+====
+python3 src/main.py
+====
+
+If your .env file is completely filled out with valid values the only output you may read on the terminal are warnings or worst-case-scenario errors. Next chapter will cover all such cases. If your .env file lacks one or more values you will be asked to input the missing info at runtime.
+
+==== Entering missing values if prompted
+If you decide to run without a valid .env file (again, worst-case-scenario) you will be prompted to enter the required information directly into the terminal.
+
+.The difference between running {software-name} with no .env, and with a properly filled out .env. Same parameters, same output.
+[#usage-difference-dotenv]
+image::usage-difference-dotenv.png[]
+
+First and foremost you will be prompted for a valid API key. To paste your key in the terminal either right-click (_PowerShell_ and other terminal emulators), right-click > _Paste_, Ctrl + Shift + V (on most terminal emulators) or middle-click (Linux).
+
+Then you will be prompted for an elabid - which is a positive integer number. You can find your sample's elabid on eLabFTW, above the sample's name and before the sample's label and status. See xref:usage-elabid[xrefstyle="short"].
+
+Last but not least you will be prompted for a valid eLabFTW API endpoint URL. Such URL is composed by the base URL of your eLabFTW instance, closing with `/api/v2`. For instance: _++https://elabftw.fisica.unina.it/api/v2++_. +
+{software-name} {revnumber} will not validate such URL or return some very specific error.
+
+WARNING: Make sure the URL you paste doesn't end with a trailing slash. +
+++https://elabftw.fisica.unina.it/api/v2++ ✓ +
+++https://elabftw.fisica.unina.it/api/v2/++ ✗
+
+You won't be prompted for the operative unit, so that will require either setting up a .env or manually editing your NeXus files' names. The list of officially approved acronyms for the operative units can be consulted on NFFA-DI's link:{nffa-di-uo-acronyms}[official website^].
+
+.Where to find the elabid of a sample.
+[#usage-elabid]
+image::usage-elabid.png[]
+
+==== Retrieving and verifying your file
+By default the NeXus file will be saved in the `output/` folder. Currently ({revdate}) the software will also save a JSON dictionary with the full chain of all metadata collected on the sample. There is also an `attachments/` folder containing all the attachments downloaded during execution, which will be removed later on.
+
+The file will be recognizable by its name, which should already be in compliance with the following NFFA-DI naming guidelines:
+
+> «Each file generated in the context of a Proposal stored on OFED must use the following naming convention: ++nffa-di_[proposal_id]_[UO]_[UO_internal_id]++» - where _proposal_id_ is the approved ID of the research proposal, _UO_ is the link:{nffa-di-uo-acronyms}[official code^] of the operative unit, and «_UO_internal_id_ is a combination of the technique/instrument acronym and an Experiment ID freely decided». +
+> «Each file generated in the context of an In-house Research Project stored on OFED must use the following naming convention: nffa-di_[UO]_[project_id]_key, where the first part of the name adheres to the name of the bucket, while key is arbitrary.»
+>
+> Source: link:{nffa-di-rdp}[NFFA-DI Research Data Policy^]
+
+This means that the accepted filename for a NeXus file of a PLD, where proposal_id is _EXMPL01_, the operative unit is CNR-SPIN Naples and the sample's internal ID is _Na-26-012_ the filename will be:
+
+image::usage-name.png[]
+
+A NeXus file can be verified through one of the readers listed in xref:reading-nxs[xrefstyle="short"]. Pay attention to the following aspects:
+
+* Do I visualize the file correctly?
+* Does the file respect the fabrication method's schema?
+* Is every required field present? Do I read the same values on eLabFTW and in the NeXus file? Are the units of measurement present?
+* Can I visualize heatmaps and N-axis graphs correctly?
+
+If the answer to all previous questions is "Yes", then the output file is NFFA-DI compliant.
+
+////
+collect nxs file
+filename is: [paste link of guidelines here]
+output folder is: output/
+attachments will be in: output/attachments - to be removed
+???
+profit
+////

docs/user-manual_03.adoc

@@ -0,0 +1,3 @@
+== Troubleshooting
+
+WIP

docs/user-manual_main.adoc

@@ -1,30 +1,38 @@
 = {software-name} User Manual: eLabFTW to NeXus Parser for PLD Fabrications 
 :author: Emanuele D'Amico
 :description: eLabFTW to NeXus Parser for PLD Fabrications
+:doctype: book
 :email: emanuele+expars@damico.ing
+:imagesdir: images
 :keywords: nffa-di, elabftw, nexus, parser, data science, mdmc, naples, cnr-spin, cnr, spin institute, python, hdf5, cli
 :revdate: 2026-05-14
 :revnumber: v0.2.1
 :revremark: alpha untested
 :stem: latexmath
 :toc:
-:doctype: book
 // custom attributes
 :disclamer: I'm in no position to give anyone coding/development/programming/testing tips. The only tips I can give you are based on my personal knowledge of this specific project.
 :software-family: eXPars
 :software-name: {software-family}-PLD
 :repo-url: https://gitea.damico.ing/emanuele/eXParser-PLD
 :repo-ssh: ssh://git@gitea.damico.ing/emanuele/eXParser-PLD.git
+:elabftw-apikey-docs: https://doc.elabftw.net/docs/usage/api/#generating-a-key
 :elabftw-site: https://elabftw.net
 :nffa-di-site: https://nffa-di.it/en/about-us/project/
+:nffa-di-rdp: https://nffa-di.it/it/research-data-policy/#3.1
+:nffa-di-uo-acronyms: https://nffa-di.it/en/uo-acronyms-for-data-infrastructure-naming-convention
 :go-fair-site: https://www.go-fair.org/fair-principles/
 :fairmat-site: https://www.fairmat-nfdi.eu/fairmat/about-fairmat/consortium-fairmat#mission
+:keepass-site: https://keepassxc.org/
+:bitwarden-site: https://bitwarden.com/
 :ncnr-viewer: https://ncnr.nist.gov/ncnrdata/view/nexus-hdf-viewer.html
 :hdf5-viewer: https://myhdf5.hdfgroup.org/
 
-include::user-manual_intro.adoc[]
+include::user-manual_01.adoc[]
 
-include::user-manual_usage.adoc[]
+include::user-manual_02.adoc[]
+
+//include::user-manual_03.adoc[]
 
 ///////////////////////////////////////////////////////////////////////////
 // Look out for "method-specific" comments I've left before sections

docs/user-manual_usage.adoc

@@ -1,51 +0,0 @@
-== Using the software
-WARNING: This software requires Python 3.12 or later. +
-The module *venv* and the package manager *pip* are also required.
-
-=== Downloading the source code
-IMPORTANT: Currently ({revdate}) the source code is hosted on a private Gitea instance, owned by {author}. +
-If the site is down for maintenance or temporarily unavailable please contact the webmaster via mailto:{email}[e-mail].
-
-// TO-DO: add link to direct download of package
-The source code can be acquired directly via *git*, or downloaded from the official repository on link:{repo-url}[Gitea D'Amico^].
-
-[source,bash,subs="verbatim,attributes"]
-----
-git clone {repo-url}.git {software-name}
-cd {software-name} # enter directory
-ls
-  LICENSE    docs/     output/           src/
-  README.md  glossary  requirements.txt  tests/
-----
-
-Optionally, you can access the code in the development branch by executing:
-[source,bash]
-----
-git checkout dev
-----
-
-=== Preparing the environment
-{software-name} {revnumber} requires a total of 6 modules to be installed before starting. Since installing a Python module system-wide is almost never a good idea, start by creating and activating a virtual environment.
-
-In the software folder, run:
-
-[source,bash]
-----
-# Calls venv module to create new Python virtual environment in .venv:
-python3 -m venv .venv
-# If command is successful, running ls should show a new .venv folder:
-ls -d .*
-  .venv
-# Activate venv:
-source .venv/bin/activate
-----
-
-.Most shells like Bash show very clearly when you're working inside a virtual environment.
-image::images/usage-venv.png[]
-
-At this point you're free to install the requirements through *pip*:
-
-
-
----
-== Troubleshooting

src/APIHandler.py

@@ -23,11 +23,11 @@ class APIHandler:
     # TO-DO: remove static url.
     def __init__(self, api_key="", ELABFTW_API_URL=None):
         """Init method, api_key suggested but not required (empty by default)."""
-        if not ELABFTW_API_URL:
-            load_dotenv()
-            ELABFTW_API_URL = os.getenv("ELABFTW_API_URL") or input(
-                "Enter a valid eLabFTW API URL (ends with '/api/v2)': "
-            )
+        # if not ELABFTW_API_URL:
+        #    load_dotenv()
+        #    ELABFTW_API_URL = os.getenv("ELABFTW_API_URL") or input(
+        #        "Enter a valid eLabFTW API URL (ends with '/api/v2)': "
+        #    )
         self.api_key = api_key
         self.auth = {"Authorization": api_key}
         self.content = {"Content-Type": "application/json"}

src/classes.py

@@ -134,7 +134,7 @@ class Layer:
         self.start_time = layer_data.get("created_at") or None
         self.description = layer_data.get("body") or None
 
-    def get_instruments(self, api_key):
+    def get_instruments(self, api_key, ELABFTW_API_URL):
         """
         Retruns a dictionary of all the instruments used to create the layer.
         The format of the dictionary is:
@@ -144,18 +144,20 @@ class Layer:
                 "rheed_system": str
             }
 
-        Arg: api_key: str:  A valid API key for the eLabFTW instance where the data is stored, with permissions to access the relevant entries.
+        Args:
+            api_key: str:           A valid API key for the eLabFTW instance where the data is stored, with permissions to access the relevant entries.
                                     eLabFTW's API keys are well documented here: https://doc.elabftw.net/docs/usage/api/.
                                     If you don't have an API key and are uncapable of creating one, contact your eLabFTW administrator.
                                     Or RTFM and create one yourself, it's not that hard.
+            ELABFTW_API_URL: str:   URL for the API root endpoint of the eLabFTW instance. Ends with '/api/v2' - no trailing slash.
         """
-        raw_lasersys_data = APIHandler(api_key).get_entry_from_elabid(
+        raw_lasersys_data = APIHandler(api_key, ELABFTW_API_URL).get_entry_from_elabid(
             self.laser_system_elabid, entryType="items"
         )
-        raw_chamber_data = APIHandler(api_key).get_entry_from_elabid(
+        raw_chamber_data = APIHandler(api_key, ELABFTW_API_URL).get_entry_from_elabid(
             self.chamber_elabid, entryType="items"
         )
-        raw_rheedsys_data = APIHandler(api_key).get_entry_from_elabid(
+        raw_rheedsys_data = APIHandler(api_key, ELABFTW_API_URL).get_entry_from_elabid(
             self.rheed_system_elabid, entryType="items"
         )
         instruments_used = {
@@ -248,6 +250,7 @@ class Entrypoint:
             * linked_experiments_elabid: list:  List of eLabFTW internal id's of the experiments linked to the entrypoint.
         """
         try:
+            self.name = sample_data["title"]
             self.extra = sample_data["metadata_decoded"]["extra_fields"]
             self.linked_items = sample_data["items_links"]  # dict
             self.batch_elabid = self.extra["Substrate batch"]["value"]  # elabid
@@ -262,11 +265,6 @@ class Entrypoint:
             raise KeyError(
                 f'The provided dictionary lacks a "{k}" key. Check the sample entry on eLabFTW and make sure you used the correct Resource template.'
             )
-        # Non-required attributes:
-        self.name = (
-            sample_data.get("title") or None
-        )  # error prevention is more important than preventing empty fields here
-        # although I don't think it's even possible to fuck up this bad...
 
 
 class Material:
@@ -310,7 +308,7 @@ class Material:
                 f'The provided dictionary lacks a "{k}" key. Check the target/substrate entry on eLabFTW and make sure you used the correct Resource template.'
             )
 
-    def get_compound_data(self, apikey):
+    def get_compound_data(self, apikey, ELABFTW_API_URL):
         """
         Returns a dictionary with the relevant data on the compound of which the material is made.
         The format of the dictionary is:
@@ -320,12 +318,14 @@ class Material:
                 "cas_number": str
             }
 
-        Arg: api_key: str:  A valid API key for the eLabFTW instance where the data is stored, with permissions to access the relevant entries.
+        Args:
+            api_key: str:           A valid API key for the eLabFTW instance where the data is stored, with permissions to access the relevant entries.
                                     eLabFTW's API keys are well documented here: https://doc.elabftw.net/docs/usage/api/.
                                     If you don't have an API key and are uncapable of creating one, contact your eLabFTW administrator.
                                     Or RTFM and create one yourself, it's not that hard.
+            ELABFTW_API_URL: str:   URL for the API root endpoint of the eLabFTW instance. Ends with '/api/v2' - no trailing slash.
         """
-        raw_compound_data = APIHandler(apikey).get_entry_from_elabid(
+        raw_compound_data = APIHandler(apikey, ELABFTW_API_URL).get_entry_from_elabid(
             self.compound_elabid, entryType="items"
         )
         name = raw_compound_data["title"]
@@ -339,8 +339,20 @@ class Material:
         }
         return compound_data
 
-    def get_compound_formula(self, apikey):
-        formula = self.get_compound_data(apikey).get("chemical_formula")
+    def get_compound_formula(self, apikey, ELABFTW_API_URL):
+        """
+        Returns a string with the chemical formula of the compound.
+
+        Args:
+            api_key: str:           A valid API key for the eLabFTW instance where the data is stored, with permissions to access the relevant entries.
+                                    eLabFTW's API keys are well documented here: https://doc.elabftw.net/docs/usage/api/.
+                                    If you don't have an API key and are uncapable of creating one, contact your eLabFTW administrator.
+                                    Or RTFM and create one yourself, it's not that hard.
+            ELABFTW_API_URL: str:   URL for the API root endpoint of the eLabFTW instance. Ends with '/api/v2' - no trailing slash.
+        """
+        formula = self.get_compound_data(apikey, ELABFTW_API_URL).get(
+            "chemical_formula"
+        )
         return formula
 
 
@@ -454,7 +466,8 @@ if __name__ == "__main__":
     # print(f"Example header:\n\t{head.header}\n")
     # print("Warning: you're not supposed to be running this as the main program.")
     api_key = getpass("Paste API key here [no echo]: ")
-    handler = APIHandler(api_key=api_key)
+    ELABFTW_API_URL = input("Enter a valid eLabFTW API URL (ends with '/api/v2)': ")
+    handler = APIHandler(api_key, ELABFTW_API_URL)
     exp58 = handler.get_entry_from_elabid(elabid=58, entryType="experiments")
     layer58 = Layer(exp58)
     print(layer58.list_attachments())

src/main.py

@@ -20,7 +20,7 @@ def call_entrypoint_from_elabid(elabid):
     Arg: elabid: int    eLabFTW internal id of the selected resource.
     """
     try:
-        sample_data = APIHandler(api_key).get_entry_from_elabid(
+        sample_data = APIHandler(api_key, ELABFTW_API_URL).get_entry_from_elabid(
             elabid, entryType="items"
         )
         if not sample_data.get("category_title") == "Sample":
@@ -44,7 +44,7 @@ def call_material_from_elabid(elabid):
     arg: elabid: int    eLabFTW internal id of the selected resource.
     """
     try:
-        material_data = APIHandler(api_key).get_entry_from_elabid(
+        material_data = APIHandler(api_key, ELABFTW_API_URL).get_entry_from_elabid(
             elabid, entryType="items"
         )
         material_category = material_data.get("category_title")
@@ -75,7 +75,7 @@ def call_layers_from_list(elabid_list):
     list_of_layers = []
     for elabid in elabid_list:
         try:
-            layer_data = APIHandler(api_key).get_entry_from_elabid(
+            layer_data = APIHandler(api_key, ELABFTW_API_URL).get_entry_from_elabid(
                 elabid, entryType="experiments"
             )
             if not layer_data.get("category_title") == "PLD Deposition":
@@ -106,7 +106,7 @@ def call_proposal_from_elabid(elabid):
     Arg: elabid: int    eLabFTW internal id of the selected resource.
     """
     try:
-        proposal_data = APIHandler(api_key).get_entry_from_elabid(
+        proposal_data = APIHandler(api_key, ELABFTW_API_URL).get_entry_from_elabid(
             elabid, entryType="items"
         )
         proposal_category = proposal_data.get("category_title")
@@ -186,7 +186,7 @@ def deduplicate_instruments_from_layers(layers):
     rheeds = []
     elegant_dict = {}
     for lyr in layers:
-        instruments = lyr.get_instruments(api_key)
+        instruments = lyr.get_instruments(api_key, ELABFTW_API_URL)
         lasers.append(instruments["laser_system"])
         chambers.append(instruments["deposition_chamber"])
         rheeds.append(instruments["rheed_system"])
@@ -356,7 +356,9 @@ def make_nexus_schema_dictionary(substrate_object, layers):
         "sample": {
             "substrate": {
                 "name": substrate_object.name,
-                "chemical_formula": substrate_object.get_compound_formula(api_key),
+                "chemical_formula": substrate_object.get_compound_formula(
+                    api_key, ELABFTW_API_URL
+                ),
                 "orientation": substrate_object.orientation,
                 "miscut_angle": {
                     "value": substrate_object.miscut_angle,
@@ -384,7 +386,9 @@ def make_nexus_schema_dictionary(substrate_object, layers):
         target_object = chain_layer_to_target(layer)
         target_dict = {
             "name": target_object.name,
-            "chemical_formula": target_object.get_compound_formula(api_key),
+            "chemical_formula": target_object.get_compound_formula(
+                api_key, ELABFTW_API_URL
+            ),
             "description": target_object.description,
             "shape": target_object.shape,
             "dimensions": target_object.dimensions,
@@ -772,7 +776,7 @@ def build_nexus_file(pld_fabrication, output_path="output/nffa-di_unnamed.h5"):
             n = layer_dict["layer_number"]
             rheed_data_file = layer_dict["data"][0]  # first in the tuple
             rheed_image_file = layer_dict["data"][1]  # second in the tuple
-            handler = APIHandler(api_key)
+            handler = APIHandler(api_key, ELABFTW_API_URL)
 
             # TO-DO: maybe make a dedicated function???
             data_path = None
@@ -871,17 +875,24 @@ def build_nexus_file(pld_fabrication, output_path="output/nffa-di_unnamed.h5"):
 
 if __name__ == "__main__":
     load_dotenv()
-    api_key = os.getenv("api_key") or getpass("Paste API key here: ")
+    api_key = os.getenv("api_key") or getpass("Paste API key here: ", echo_char="*")
     elabid = (
         os.getenv("elabid")
         or input("Enter elabid of your starting sample [default = 1111]: ")
         or 1111
     )
-    handler = APIHandler(api_key)
+    ELABFTW_API_URL = os.getenv("ELABFTW_API_URL") or input(
+        "Enter a valid eLabFTW API URL (ends with '/api/v2)': "
+    )
+    handler = APIHandler(api_key, ELABFTW_API_URL)
     data = handler.get_entry_from_elabid(elabid)
     sample = Entrypoint(data)
-    sample_name = sample.name.strip().replace(" ", "_")
+    sample_name = sample.name.strip().replace(
+        " ", "-"
+    )  # returns error if no "title" or title is not str
     operative_unit = os.getenv("operative_unit") or None
+    if operative_unit:
+        operative_unit = operative_unit.strip().replace(" ", "-")
     if sample.proposal:
         sample_proposal = call_proposal_from_elabid(sample.proposal)
     else:
@@ -894,12 +905,12 @@ if __name__ == "__main__":
         "nffa-di_"
         + (f"{sample_proposal}_" if sample_proposal else "")
         + (f"{operative_unit}_" if operative_unit else "")
-        + "_"
-        + sample_name
+        + "PLD_"
+        + sample_name[:9]
     )
 
     result = make_nexus_schema_dictionary(substrate_object, layers)
     with open(f"output/{fn_base}.json", "w") as f:
         json.dump(result, f, indent=3)
 
-    build_nexus_file(result, output_path=f"output/{fn_base}.h5")
+    build_nexus_file(result, output_path=f"output/{fn_base}.nxs")