[taler-docs] branch master updated: EBICS 3 tutorial.

[gnunet]

This is an automated email from the git hooks/post-receive script.

ms pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 7aeaa829 EBICS 3 tutorial.
7aeaa829 is described below

commit 7aeaa8290eaa71994675e478e3c73053d6f33ab4
Author: MS <ms@taler.net>
AuthorDate: Mon Jul 10 11:00:33 2023 +0200

    EBICS 3 tutorial.
    
    Content addressed, screenshots missing.
---
 libeufin/ebics3-test-tutorial.rst | 77 ++++++++++++++++++++++++++++-----------
 1 file changed, 55 insertions(+), 22 deletions(-)

diff --git a/libeufin/ebics3-test-tutorial.rst 
b/libeufin/ebics3-test-tutorial.rst
index b25e9323..c1211162 100644
--- a/libeufin/ebics3-test-tutorial.rst
+++ b/libeufin/ebics3-test-tutorial.rst
@@ -1,25 +1,58 @@
 EBICS 3.0 with PostFinance
 ##########################
 
-In this tutorial, LibEuFin Nexus communicates with the PostFinance
-test platform via EBICS 3.0.  The reader is required to have one account
-at the `PostFinance test platform <https://isotest.postfinance.ch>`_,
-and a Docker environment.
+The tutorial shows how to run the Docker-based EBICS 3 test,
+where the user will be guided through the three main operations.
 
-This EBICS 3.0 communication involves the following three operations:
+The main EBICS 3 operations are the following:
 
 * Key exchange: Nexus gives the customer keys to the bank, and then downloads 
the bank keys.
 * Uploading of a payment instruction: the customer sends money to another 
fictional IBAN.
 * Downloading of banking records: the customer gets their banking activity 
where the previous outgoing payment should appear.
 
-Setting up the test platform
-----------------------------
-Login and navigate to the $MEANT section and set all the
-values like shown in the following image.
+Setting up the test platform at PostFinance
+-------------------------------------------
 
-.. Pictorial example..
+Because the test is based on the PostFinance test platform, the first
+requirement is to create one account `there <https://isotest.postfinance.ch>`_.
+It's adivsed to set the language as English, as the following screenshots
+address the international audience.
 
-.. More pictorial examples here..
+Set the language in the dropdown menu and navigate to the registration
+section as it's shown below:
+
+.. image:: set-english-and-register.png
+
+After a sucessful registration, the next two settings need to be given:
+(1) EBICS 3 and (2) the format of payment confirmations (more on this later).
+
+Note: setting EBICS 3 is not *explicit*, but it's a side effect of choosing
+one particular format for downloading the bank account records.  The following
+screenshot shows how:
+
+.. image:: set-ISO20022-2019.png
+
+Payment confirmations are ISO20022 documents that witness the outcome
+of outgoing payments.  After sending 1 Swiss Franc to one arbitrary IBAN,
+the bank releases this document that contains all the payment details.  In
+this test, we use this document to test the download capability of our EBICS
+3 implementation.  The specific name of such documents is ``camt.054``, and
+the following screenshot shows how to set them:
+
+.. image:: set-camt.054.png
+
+
+.. _get-ebics-ids:
+
+The last step is to retrieve the user's EBICS identifiers, namely the
+EBICS user and partner IDs.  Please find them how it is shown below:
+
+.. image:: get-ebics-ids.png
+
+Interestingly, the same page above contains also the bank keys fingerprints
+(right bottom corner).  These are important to check that the client, along
+the keying process, has obtained the right bank keys.  The interactive test
+will give the desired time to the user to check them.
 
 Setting up the local Docker
 ---------------------------
@@ -43,19 +76,20 @@ And build the Docker image with the following command:
    docker build -t pofi .
 
 If the previous steps succeeded, the *pofi* image is ready to be run.
-Although the test runner guides the user via interactive instructions,
-it's advised to read the `Testing description` section.
 
-The test runner needs the following two values: EBICS user ID and EBICS
-partner ID.  Please, find them in the following page:
+.. note::
+  
+   Although the test runner guides the user via live instructions,
+   it's advised to read the `Testing description`_ section.
 
-.. FIXME: screenshot here.
+The test runner needs the following two values: EBICS user ID and EBICS
+partner ID.  The `previous section <get-ebics-ids_>`_ explains how
+to get them.
 
 .. code-block:: shell-session
 
   docker run -it pofi $EBICS_USER_ID $EBICS_PARTNER_ID
 
-
 Testing description
 -------------------
 
@@ -72,7 +106,7 @@ user confirm the keys via the Web interface.
 
 After the key exchange, the test runner continues by uploading one
 payment instruction.  The payment instruction is a ``pain.001`` document
-that complies with the ISO20022 specification and EBICS is responsible
+that complies with the ISO20022 specification, and EBICS is responsible
 to transport the pain.001 from the client to the bank.
 
 The payment instruction causes one outgoing payment from the user
@@ -83,7 +117,7 @@ After the upload to the bank, the execution pauses to let 
the user
 check whether the test platform has received the payment instruction.
 The following screenshot shows where to look for such check:
 
-.. FIXME: screenshot here
+.. image:: check-payment-subject.png
 
 At this point, the upload operation ended and the execution can proceed
 to test the download.  The download tries to get one ``camt.054`` (as well
@@ -93,13 +127,12 @@ in the pain.001 case, EBICS is responsible to transport 
the camt.054 from
 the bank to the client.
 
 The download operation logs its activity to the screen, and if the execution
-is correct, the user should check for the payment subject that was initially
-specified in the pain.001 document.
+is correct, the user should check the logs for the payment subject that was
+initially specified in the pain.001 document.
 
 Please, look for the following line:
 
 .. note::
-
   Replace $TIME, $PAYMENT_SUBJECT and $MSG_ID with the particular case.
 
 .. code-block:: shell-session

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.