From 66805c1d319a081ab859971a130fe5912c9a5847 Mon Sep 17 00:00:00 2001 From: MS Date: Tue, 6 Oct 2020 14:31:11 +0200 Subject: howto -> tutorial --- libeufin/index.rst | 2 +- libeufin/nexus-howto.rst | 169 -------------------------------------------- libeufin/nexus-tutorial.rst | 169 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 170 insertions(+), 170 deletions(-) delete mode 100644 libeufin/nexus-howto.rst create mode 100644 libeufin/nexus-tutorial.rst (limited to 'libeufin') diff --git a/libeufin/index.rst b/libeufin/index.rst index cb714203..4141f44b 100644 --- a/libeufin/index.rst +++ b/libeufin/index.rst @@ -16,4 +16,4 @@ LibEuFin is a project providing free software tooling for European FinTech. banking-protocols transaction-identification frontend - nexus-howto + nexus-tutorial diff --git a/libeufin/nexus-howto.rst b/libeufin/nexus-howto.rst deleted file mode 100644 index 73784d57..00000000 --- a/libeufin/nexus-howto.rst +++ /dev/null @@ -1,169 +0,0 @@ -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. 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. -- cgit v1.2.3