diff options
Diffstat (limited to 'libeufin')
| -rw-r--r-- | libeufin/nexus-tutorial.rst | 264 |
1 files changed, 222 insertions, 42 deletions
diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst index fd12ad26..d20fb7a4 100644 --- a/libeufin/nexus-tutorial.rst +++ b/libeufin/nexus-tutorial.rst @@ -1,19 +1,37 @@ -Nexus How-To -############ +LibEuFin 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. +The LibEuFin Nexus is a Web service that provides a JSON abstraction layer to +access bank accounts. It does **not** itself offer banking services, but is a +translator between JSON requests and other banking protocols (such as EBICS), +that are offered by banks. This document explains how to set up 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. +via the EBICS protocol. + +In order to follow all the steps below, the reader should either +have access to a bank account with EBICS support or follow the +steps in "Setting up the Sandbox". + + +Installing LibEuFin +=================== + +Downloading prebuilt binaries +----------------------------- + +Pre-built packages can be obtained from the `taler.net website +<https://taler.net/files/libeufin>`__. + +Unpack the ``libeufin-$version.zip `` file to +your desired location (typically ``/opt`` or ``~/opt``) and make sure that your ``$PATH`` +variable contains the ``bin/`` directory of the unpacked archive. + +Building from source +-------------------- -Obtain Nexus -============ Nexus belongs to the LibEuFin project, and can be downloaded via Git: .. code-block:: console @@ -22,8 +40,6 @@ Nexus belongs to the LibEuFin project, and can be downloaded via Git: 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:: console @@ -32,6 +48,9 @@ Navigate into the *libeufin* local repository, and from top-level run: $ ./configure --prefix=$PREFIX $ make install +Verifying your installation +--------------------------- + In case of success, the two following commands should be found: .. code-block:: console @@ -39,19 +58,109 @@ In case of success, the two following commands should be found: $ which libeufin-nexus $ which libeufin-cli -Connect Nexus with a EBICS account + +(Optional) Configuring the Sandbox ================================== -Use the following command to *(1) run the nexus service*: +If you don't have access to a real bank account with an EBICS API, you can set +up the sandbox. The sandbox is a simplistic and incomplete implementation of a +core banking system with EBICS access to bank accounts. + +For the following commands, the sandbox service must be running. +The sandbox service is started with the following command: + +.. code-block:: console + + $ libeufin-sandbox serve --port 5000 + +To reset the state of the sandbox, delete the database. By default, +the database is a SQLite3 file in ``/tmp/libeufin-sandbox.sqlite3``. + +For invocations of the LibEuFin command line interface tool (``libeufin-cli``), +the following environment variable must be set to the URL of the sandbox +service: + +.. code-block:: console + + export LIBEUFIN_SANDBOX_URL=http://localhost:5000/ + +Verify that the sandbox is running: + +.. code-block:: console + + $ libeufin-cli sandbox check + +Now an EBICS host can be created: + +.. code-block:: console + + $ libeufin-cli sandbox ebicshost create --host-id testhost + +Note that most ``libeufin-cli`` subcommands will ask for input interactively if +the respective value is not specified as a command line option. + +Next, create an EBICS subscriber (identified by the partner ID and user ID) for the host: + +.. code-block:: console + + $ libeufin-cli sandbox ebicssubscriber create \ + --host-id testhost --partner-id partner01 --user-id user01 + +Create a bank account for the subscriber and add a sample transaction: + +.. code-block:: console + + $ libeufin-cli sandbox ebicsbankaccount create \ + --currency EUR \ + --iban DE18500105172929531888 \ + --bic INGDDEFFXXX \ + --person-name "Jane Normal" \ + --account-name "testacct01" \ + --ebics-host-id testhost \ + --ebics-user-id user01 \ + --ebics-partner-id partner01 + +The account name "testacct01" is the unique identifier of the account within +the sandbox. The EBICS parameter identify the subscriber that should have +access to the bank account via EBICS. + +To populate the account with some test transactions, run the following command +(note that we use the bankaccount subcommand, as this command is not +EBICS-specific!): + +.. code-block:: console + + $ libeufin-cli sandbox bankaccount generate-transactions testacct01 + +Payments to a sandbox bank account can be listed as follows: + +.. code-block:: console + + $ libeufin-cli sandbox bankaccount transactions testacct01 + +.. note:: + + The sandbox is intended as a testing tool and thus not stable. + + For more information on the available commands, use the built-in ``--help`` flag. + + The full functionality of the sandbox is available via the API. + + +Connect Nexus with an EBICS account +=================================== + +Use the following command to run the nexus service: .. code-block:: console - $ libeufin-nexus serve + $ libeufin-nexus serve --port 5001 -We recommend using the ``--db-conn-string=$DBCONN`` option. It -instructs Nexus to reach the database addressed by the connection -string. Only *SQLite* and *PostgreSQL (only via TCP)* are supported -right now. +By default, the SQLite3 database ``/tmp/libeufin-nexus.sqlite3`` will be used. + +We recommend using the ``--db-conn-string=$DBCONN`` option. It instructs Nexus +to reach the database addressed by the JDBC connection URI. Only *SQLite* and +*PostgreSQL (only via TCP)* are supported right now. For example: @@ -59,27 +168,32 @@ For example: $ libeufin-nexus serve --db-conn-string=jdbc:postgresql://127.0.0.1:5433/libeufindb?user=foo&password=secret -At this point a *(2) superuser account needs to be activated -into the system*: +At this point a superuser account needs to be created: .. code-block:: console $ libeufin-nexus superuser --db-conn-string=jdbc:postgresql://127.0.0.1:5433/libeufindb?user=foo&password=secret foo # Will interactively ask for password -For simplicity, a superuser can as well act as a normal user, but a API +For simplicity, a superuser can as well act as a normal user, but an API to create less privileged users is 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*. +.. note:: + + Privilege separation is not fully implemented yet. + +The command line interface needs the following three values +to be defined in the environment: ``LIBEUFIN_NEXUS_URL``, ``LIBEUFIN_NEXUS_USERNAME``, +and ``LIBEUFIN_NEXUS_PASSWORD``. In this example, ``LIBEUFIN_NEXUS_USERNAME`` should be +set to ``foo``, and ``LIBEUFIN_NEXUS_PASSWORD`` to the value given for its password +in step (2). + +Next, we will create an EBICS *bank connection* that that +nexus can use to communicate with the bank. .. note:: - The command line interface needs the following three values - to be defined in the environment: ``NEXUS_BASE_URL``, ``NEXUS_USERNAME``, - and ``NEXUS_PASSWORD``. In this example, ``NEXUS_USERNAME`` should be - set to ``foo``, and ``NEXUS_PASSWORD`` to the value given for its password - in step (2). + For the sandbox set up in this guide, the EBICS base URL + is ``http://localhost:5000/ebicsweb``. .. code-block:: console @@ -107,9 +221,24 @@ a backup copy* of such keys. $CONNECTION_NAME At this point, Nexus must communicate all the details to the bank. Therefore, -it will *(5) synchronize the connection*. In this EBICS example, Nexus will send +it will synchronize the connection. In this EBICS example, Nexus will send the *INI* and *HIA* messages to the bank. +Now that the bank has received the public keys of the subscriber electronically, +it also needs to verify them offline. For this, the nexus can generate a key letter: + +.. code-block:: console + + $ libeufin-cli connections keyletter $CONNECTION_NAME out.pdf + +.. note:: + + The resulting PDF should be sent to the bank, which will verify + that the keys printed in it match the keys sent electronically. + + When using the LibEuFin sandbox, subscribers are automatically + activated after keys are received electronically. + .. code-block:: console $ libeufin-cli \ @@ -119,7 +248,7 @@ the *INI* and *HIA* messages to the bank. 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 *(6) downloads the list of the bank accounts offered by the* +The command below downloads the list of the bank accounts offered by the ``$CONNECTION_NAME``. .. code-block:: console @@ -129,7 +258,7 @@ The command below *(6) downloads the list of the bank accounts offered by the* download-bank-accounts \ $CONNECTION_NAME -It is now possible to *(7) list the accounts offered by the connection*. +It is now possible to list the accounts offered by the connection. .. code-block:: console @@ -138,8 +267,8 @@ It is now possible to *(7) list the accounts offered by the connection*. list-offered-bank-accounts \ $CONNECTION_NAME -Nexus now needs an explicit *(8) import of the accounts it needs to manage*. -This step is needed to let the user pick a custom name for such accounts. +Nexus now needs an explicit import of the accounts it should to manage. This +step is needed to let the user pick a custom name for such accounts. .. code-block:: console @@ -159,6 +288,7 @@ Request history of transactions =============================== .. + FIXME: explain why requesting the history goes through these two-phases. @@ -174,20 +304,27 @@ This command asks Nexus to *download the latest bank statements*: fetch-transactions \ $CUSTOM_RENAMING_FOR_ACCOUNT +.. note:: + + By default, the latest available transactions are fetched. It is also + possible to specify a custom data range (or even all available transactions) + and the type of transactions to fetch ( inter-day statements or intra-day + reports). + Once Nexus stored all the information in the database, the client can ask to actually **see** the transactions: .. code-block:: console - $ libeufin-cli - accounts \ - transactions \ - $CUSTOM_RENAMING_FOR_ACCOUNT + $ libeufin-cli accounts \ + transactions \ + $CUSTOM_RENAMING_FOR_ACCOUNT Make a payment ============== .. + FIXME: explain why payments go through these two-phases. Payments pass through two phases: preparation and submission. @@ -199,9 +336,9 @@ The following command prepares a payment: $ libeufin-cli \ accounts \ prepare-payment \ - --credit-iban $IBAN_TO_SEND_MONEY_TO \ - --credit-bic $BIC_TO_SEND_MONEY_TO \ - --credit-name $LEGAL_ENTITY_RECEIVING_THE_PAYMENT \ + --creditor-iban $IBAN_TO_SEND_MONEY_TO \ + --creditor-bic $BIC_TO_SEND_MONEY_TO \ + --creditor-name $CREDITOR_NAME \ --payment-amount $AMOUNT \ --payment-subject $SUBJECT \ $CUSTOM_RENAMING_FOR_ACCOUNT @@ -221,6 +358,49 @@ in the next step, to **send the payment instructions to the bank**: --payment-uuid $UUID \ $CUSTOM_RENAMING_FOR_ACCOUNT +Automatic scheduling +==================== + +With an EBICS bank connection, the LibEuFin nexus needs to regularly query for +new transactions and (re-)submit prepared payments. + +It is possible to schedule these tasks via an external task scheduler such as +cron. However, the nexus also has an internal task scheduling mechanism for +accounts. + + +The following two create a schedule for submitting payments hourly, +fetching transactions (intra-day reports) every 5 minutes and once at 11am every +day (inter-day statements): + +.. code-block:: console + + $ libeufin-cli accounts task-schedule myacct \ + --task-type="submit" + --task-name='submit-payments-hourly' + --task-cronspec='0 0 *' + + $ libeufin-cli accounts task-schedule myacct \ + --task-type="fetch" \ + --task-name='fetch-5min' \ + --task-cronspec='0 */5 *' \ + --task-param-level=report \ + --task-param-range-type=latest + + $ libeufin-cli accounts task-schedule myacct \ + --task-type="fetch" \ + --task-name='fetch-daily' \ + --task-cronspec='0 0 23' \ + --task-param-level=statement \ + --task-param-range-type=latest + +The cronspec has the following format, which is slightly non-standard due to +the ``SECONDS`` field + +.. code-block:: none + + SECONDS MINUTES HOURS DAY-OF-MONTH[optional] MONTH[optional] DAY-OF-WEEK[optional] + Restore the backup ================== |