commit 050d17fa427db532ba2a43580fc1649c1b511acb
parent be856edf71386e3c89ca4490a3c9c663efeb78df
Author: Christian Grothoff <christian@grothoff.org>
Date: Fri, 2 Feb 2024 19:58:39 +0100
more nexus-manual reviewing
Diffstat:
1 file changed, 34 insertions(+), 42 deletions(-)
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
@@ -176,7 +176,7 @@ The frequency **may** be specified as
.. code-block:: ini
[nexus-submit]
- frequency = 5m
+ FREQUENCY = 5m
The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours).
@@ -215,7 +215,7 @@ send it to the bank.
.. code-block:: console
- $ libeufin-nexus ebics-submit -c $config_file --transient
+ $ libeufin-nexus ebics-submit -c "$CONFIG_FILE" --transient
The ``--transient`` flag instructs the software to perform only one pass on
the database, submit what is submittable, and return.
@@ -231,84 +231,76 @@ The ``ebics-submit`` subcommand can run in fixed frequency, or transient mode.
The fixed frequency mode causes the command to check the database every time the
frequency period expires. To activate this mode, and -- for example -- set a frequency
of five minutes, set the configuration value ``FREQUENCY`` to ``5m``. Assuming that
-``$config_fixed_frequency`` is set as described above, the following invocation would
+``FREQUENCY`` is set as described above, the following invocation would
make ``ebics-submit`` check the database every five minutes, and submit any initiated
payment according to their submission state.
.. code-block:: console
- $ libeufin-nexus ebics-submit -c $config_fixed_frequency
-
+ $ libeufin-nexus ebics-submit -c "$CONFIG_FILE"
Transient mode causes ``ebics-submit`` to check the database only once, submit any
initiated payment according to their submission state, and return.
.. code-block:: console
- $ libeufin-nexus ebics-submit -c $config
+ $ libeufin-nexus ebics-submit -c "$CONFIG_FILE"
+
+
-Downloading records
-===================
+Downloading payment records
+===========================
-Downloading records must follow a successful `EBICS subscriber setup <ebics-setup>`_,
-where the bank obtained the subscriber keys, and the subscriber accepted the bank keys.
+Downloading payment records requires that the `EBICS subscriber setup
+<ebics-setup>`_, where the bank obtained the subscriber keys and the
+subscriber accepted the bank keys has been completed.
-The configuration file must contain all the ``[ebics-setup]`` sections, plus the following
-values to set the database connection and a log directory where any downloaded record would
-be stored.
+The configuration file must contain all the ``[ebics-setup]`` sections, plus
+the following values to set the database connection and a log directory where
+any downloaded record would be stored.
.. code-block:: ini
[nexus-postgres]
config = postgres:///nexus
-Assuming that ``$config_file`` contains any required option, the following command
-would download any unseen notifications (as camt.054 files).
-
-.. code-block:: console
-
- $ libeufin-nexus ebics-fetch -c $config_file --transient
-
-The ``--transient`` flag makes the command to download only once and return. If the
-bank returned any records, look in ``$LIBEUFIN_DATA_HOME/camt/YYYY-MM-DD`` to find them.
-YYYY-MM-DD is the date when the download took place.
-
To activate periodic downloads, add the following setting to the ``nexus-fetch``
-configuration section in ``$config_file``:
+configuration section in ``$CONFIG_FILE``:
.. code-block:: ini
[nexus-fetch]
- frequency = 5m
+ FREQUENCY = 5m
-The following invocation would then download records every five minutes, asking the bank
-to only return documents that are timestamped *from* (inclusive) the last incoming transaction.
+Assuming that ``$CONFIG_FILE`` contains all required options, the following command
+would download any unseen notifications (as ``camt.054`` files):
.. code-block:: console
- $ libeufin-nexus ebics-fetch -c $config_file
+ $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --transient
+
+The ``--transient`` flag makes the command to download only once and return. If the
+bank returned any records, look in ``$LIBEUFIN_DATA_HOME/camt/YYYY-MM-DD`` to find them.
+YYYY-MM-DD is the date when the download took place. Without the flag, Nexus will
+download the transaction records at the frequency specified in the configuration.
+
Testing
-------
If the bank account history has transactions that are useful for testing, it is
-possible to redownload them via the ``--pinned-start`` argument. Note: if the Nexus
-database contains already the bank account history, you might need to **reset** it,
-in order to have the redownloaded transactions ingested.
+possible to re-download them via the ``--pinned-start`` argument.
-.. note::
-
- Double-check the configuration: resetting the wrong database might cause DATA LOSS!
-
-For example, say that three back on the 2023-06-01 an handful of incoming transactions
-got booked at the bank account watched by Nexus. After such day, the following command
-would redownload them (and ingest them, if the database doesn't have them):
+The following command redownloads transactions *from* the pinned start until
+the present:
.. code-block:: console
- $ libeufin-nexus ebics-fetch -c $config_file --pinned-start 2023-06-01
-
+ $ libeufin-nexus ebics-fetch -c "$CONFIG_FILE" --pinned-start 2023-06-01
.. note::
- The command redownloads transactions *from* the pinned start until the present.
+ If the Nexus database already contains the bank account history, you might need
+ to **reset** the database in order to have the re-downloaded transactions be
+ properly ingested. Be careful when resetting the database: resetting the wrong
+ database might cause DATA LOSS!
