howto -> tutorial

1 files changed, 169 insertions, 0 deletions

diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst
new file mode 100644
index 00000000..73784d57
--- /dev/null
+++ b/libeufin/nexus-tutorial.rst
@@ -0,0 +1,169 @@
+Nexus How-To
+############
+
+.. contents:: Table of Contents
+
+Nexus is a Web service that provides a JSON abstraction layer to
+access bank accounts.  It is **not** itself a bank, but a translator
+between JSON requests and more structured banking protocols (like
+EBICS, for example.), that are offered by actual banks.
+
+This document explains how to setup Nexus to access a bank account
+via the EBICS protocol.  In order to follow all the steps below, the
+reader should already have one EBICS subscriber activated at their bank.
+
+Obtain Nexus
+============
+Nexus belongs to the LibEuFin project, and can be downloaded via Git:
+``$ git clone git://git.taler.net/libeufin``
+
+Note that Kotlin+Gradle should already work on the host system.
+
+Install Nexus
+=============
+Navigate into the `libeufin` local repository, and from top-level run:
+
+.. code-block:: shell
+
+  $ ./gradlew -Pprefix=$PREFIX nexus:installToPrefix
+  $ ./gradlew -Pprefix=$PREFIX cli:installToPrefix
+
+In case of success, the two following commands should be found:
+
+.. code-block:: shell
+
+  $ which libeufin-nexus
+  $ which libeufin-cli
+
+Connect Nexus with a EBICS account
+==================================
+
+Use the following command to *(1) run the nexus service*:
+
+.. code-block:: shell
+
+  $ libeufin-nexus
+
+At this point a *(2) superuser account needs to be activated
+into the system*:
+
+.. code-block:: shell
+
+  $ libeufin-nexus superuser foo # Will interactively ask for password
+
+For simplicity, we'll enable the superuser to access the bank account
+via the EBICS protocol, but a API to create less privileged users is
+as well offered.
+
+Nexus needs now to associate the user to a EBICS subscriber that was
+activated on the bank.  In the Nexus terminology, this is called *(3)
+creating a EBICS connection*.
+
+.. code-block:: shell
+
+  ./libeufin-cli \
+    connections \
+      new-ebics-connection \
+        --connection-name $NEXUS_BANK_CONNECTION_NAME \
+        --ebics-url $EBICS_BASE_URL \
+        --host-id $EBICS_HOST_ID \
+        --partner-id $EBICS_PARTNER_ID \
+        --ebics-user-id $EBICS_USER_ID \
+        --nexus-user-id $NEXUS_USER \
+        --nexus-password $NEXUS_PASSWORD \
+        $NEXUS_URL
+
+If the previous command succeeded, Nexus must communicate all the details
+to the bank.  Therefore, it will *(4) synchronize the connection*.
+
+.. code-block:: shell
+
+  ./libeufin-cli \
+    connections \
+      sync \
+        --connection-name $NEXUS_BANK_CONNECTION_NAME \
+        --nexus-user-id $NEXUS_USER \
+        --nexus-password $NEXUS_PASSWORD \
+        $NEXUS_URL
+
+Once the connection is synchronized, Nexus needs to import locally the data
+corresponding to the bank accounts offered by the bank connection just made.
+The command below *(5) downloads the list of the bank accounts offered by the*
+``$NEXUS_BANK_CONNECTION_NAME``.
+
+.. code-block:: shell
+
+  ./libeufin-cli \
+    connections \
+      download-bank-accounts \
+        --connection-name $NEXUS_BANK_CONNECTION_NAME \
+        --nexus-user-id $NEXUS_USER \
+        --nexus-password $NEXUS_PASSWORD \
+        $NEXUS_URL
+
+It is now possible to *(6) list the accounts offered by the connection*.
+
+.. code-block:: shell
+
+  ./libeufin-cli \
+    connections \
+      list-offered-bank-accounts \
+        --nexus-user-id $NEXUS_USER \
+        --nexus-password $NEXUS_PASSWORD \
+        $NEXUS_URL
+
+Nexus now needs an explicit *(7) import of the accounts it needs to manage*.
+This step is needed to let the user pick a custom name for such accounts.
+
+.. code-block:: shell
+
+  ./libeufin-cli
+    connections \
+      import-bank-account \
+        --connection-name $NEXUS_BANK_CONNECTION_NAME \
+        --nexus-user-id $NEXUS_USER \
+        --nexus-password $NEXUS_PASSWORD \
+        --offered-account-id $ACCOUNT_NATIVE_NAME \
+        --nexus-bank-account-id $CUSTOM_RENAMING_FOR_ACCOUNT \
+        $NEXUS_URL
+
+Once a Nexus user imported a bank account (``$CUSTOM_RENAMING_FOR_ACCOUNT``)
+under a certain connection (``$NEXUS_BANK_CONNECTION_NAME``), it is possible
+to accomplish the usual operations for any bank account: asking for the
+list of transactions, and making a payment.
+
+Request history of transactions
+===============================
+
+It is first needed to tell Nexus to download the latest news
+from the bank, and then ask it again to return the results.
+
+This command asks Nexus to *download the latest bank statements*:
+
+.. code-block:: shell
+
+  ./libeufin-cli \
+    accounts \
+      fetch-transactions \
+        --nexus-user-id $NEXUS_USER \
+        --nexus-password $NEXUS_PASSWORD \
+        --account-name $CUSTOM_RENAMING_FOR_ACCOUNT \
+        $NEXUS_URL
+
+Once Nexus stored all the information in the database, the
+client can ask to actually **see** the transactions:
+
+.. code-block:: shell
+
+  ./libeufin-cli
+    accounts \
+      transactions \
+        --nexus-user-id $NEXUS_USER \
+        --nexus-password $NEXUS_PASSWORD \
+        --account-name $CUSTOM_RENAMING_FOR_ACCOUNT \
+        $NEXUS_URL
+
+Make a payment
+==============
+
+TBD.