Designing your first Cardano Integrated Joget App

Introduction

This tutorial will guide you through designing a Joget app integrated with the Cardano blockchain using the Cardano plugin pack. You’ll learn how to generate Cardano accounts, send ADA transactions, and retrieve account details from the blockchain.

Plugin information

The plugin pack's current implementation uses Bloxbean's Cardano client Java library, which, out-of-the-box, integrates with Blockfrost through the backend API.
For Joget app designers, there is no need to set up additional infrastructure (e.g., a Cardano node) to leverage Cardano's features in their Joget apps.

Get started

Prerequisites

• Register a free account on Blockfrost: To run the plugin pack, register an account at https://blockfrost.io/.

  For testing purposes, you can sign up for a free account and add a testnet project. Provide a meaningful project name & select the correct network.

  

  Then, in your Blockfrost's Dashboard, you should see a screen as shown above. 
  From here onwards, all you need is the project's API Key to access the plugins' configuration later.

Where to get the plugin

You can download the Cardano Blockchain Pack from the JogetOSS GitHub repository.

How to install

1. Click Download on this plugin screen (It will be a .jar file).
2. Go to your Joget localhost or server. In the Joget Console, go to Admin Bar > Systems Settings > Manage Plugins and click the Upload Plugins button.
3. Under Upload Plugin, select the plugin .jar file you downloaded and click Upload.
4. Depending on the plugin type, you can now view your new plugin in your form, List, or UI Builder.
5. Remember to uninstall the old plugin before uploading a new version.

How to use it

Building the app

This proof-of-concept is accomplished with Cardano plugins developed for the Joget platform. In this tutorial, we will make use of these plugins from the plugin pack:

• Cardano Generate Account Tool
  • A Process Tool plugin that allows you to generate an account on the Cardano blockchain and store the account data in a form and/or workflow variable.
• Cardano Send Transaction Tool
• A Process Tool plugin allows you to send ADA from one account to another on the Cardano blockchain, with the option to embed form data into the transaction metadata.
• Cardano Account Form Load Binder
• A Form Load Binder plugin that allows you to load account data directly from the Cardano blockchain into a form.

With these plugins alone, Joget app designers can already develop a blockchain app that performs basic Cardano blockchain functions without writing any code. Integrating a Joget app with Cardano is accomplished simply by configuring this set of Cardano plugins.

Let's design a simple sample app to demonstrate reading from and writing to the Cardano blockchain. We can use Joget to visually design the necessary forms, after which the App Generator is used to quickly create a fully working app with a simple approval-type process. After that, we can start incorporating these 3 blockchain features into the app.

Creating the base app

The first step is to design a new Joget app. Log in as an administrator in the Joget App Center and click on the Design New App button.

Fields to configure:

• App ID: cardanoSample
• App Name: Cardano Blockchain Sample

Generating cardano account

You need a form to store account data before performing ADA transactions or reading the relevant account data.

1. Now that you have a blank app design, create a new form with the following details:
   • Form ID: accountDetails
   • Form Name: Account Details
   • Table Name: cardano_accounts
2. After creating the form, using the Joget Form Builder, let's add a few text fields to store details of a Cardano account:
   • Account Base Address (with id as the field's ID)
   • Mnemonic Phrase (encrypted in DB)
   • Account Owner
   • Is Test Account?
   • Account Enterprise Address
     
     
     The minimum basic field required to operate a Cardano account is the account's mnemonic phrase. Like most blockchain technologies, it is possible to derive account data solely from the mnemonic phrase or private key. But for security and/or efficiency purposes, it is common locally to store additional safe and immutable details of an account. 
     
     As a note, the Cardano Generate Account Tool plugin will store the account's base address as the record ID of a form record and store the account's mnemonic phrase as an encrypted value in the database.
     
     
3. As end users do not need to modify any values in this form, we can set this entire section as read-only. Go to Advanced Tools, click the Permission tab, and set up the one-and-only section as readonly.
   
4. Click Save the form.
5. Once the form is saved, click the Generate App button to use the App Generator. 
6. Check the option for Generate CRUD, then click Generate.
   Note that the App Generator is a Joget Enterprise Edition feature, but you can also manually create the list, process, and UI in the Community Edition.
   Upon completing the generation and returning to the app design page, you can see that a List Builder and UI builder for the CRUD have been generated accordingly, and the app is now published.
   
7. To make the generated Account Details data list meaningful, edit it in the List Builder and add/arrange/sort the columns according to your preference. 
   Example as below:
   Remember to save the List builder after editing it.
8. Now that you have the form, list, and UI to display account data, you can incorporate the Cardano Generate Account Tool plugin into the app.
   
9. Go to the Processes tab on the app design page and click +Add New.
   
10. Now, in the Process Builder, change the process properties accordingly:
    • ID: generateAccountProcess
    • Name: Generate Account Process
      
11. Edit the one-and-only participant and give it a meaningful name (e.g., Requester).
    
12. Now, within the process design, simply drag in a process tool and use the design below. Rename the process tool with a meaningful name (e.g., Generate Account).
    
13. You are done with the process design. To deploy the process, click Run Process at the top right corner.
14. Return to the app design page, go to the Map Tools to Plugins tab, and add a plugin to the Generate Account tool.
    
15. Select Cardano Generate Account Tool.

16. Configure the Cardano Generate Account Tool accordingly by selecting the Preview Testnet network and mapping the form fields of the Account Details form to store. For more information, see the Cardano Generate Account Tool.
    
    
    

17. Save the Plugin configuration.
18. Click Run Process.
    
    
19. Upon doing so, a valid account should be generated successfully. Launch the app and go to the CRUD menu generated earlier to check this.
    You can see that there is now 1 record available.
    
    Upon viewing the record, we can see details about the particular account.
    
20. Optionally, if you wish to make this function available for end users in runtime, you can edit the UI in the UI Builder and drag it into a Run Process Menu. Configure the Run Process Menu by pointing it to the Generate Account Process you created. Remember to save the UI after editing it.
    

Loading cardano account data from Blockchain to form

Now that you can generate Cardano accounts and store their data in a form, we can use the Cardano Account Load Binder plugin to load additional mutable data of an account (e.g., account balance) directly from the Cardano blockchain into a form. 

To fund a test account, use the testnet faucet here and specify the base address of the account that you generated earlier: https://testnets.cardano.org/en/testnets/cardano/tools/faucet/. 

The requested tADA (also known as Test ADA) funds will be transferred to the testnet account you specified within about a minute, depending on the network load.

1. After funding your test account, edit the Account Details form.
2. Add a new form section. Rename the new form section accordingly (e.g., Account Details From Blockchain).
   Then, add a few more text fields to this new form section:
   • Account Balance
   • Account Type
     
     
3. Edit this new form section, go to Data Binder tab, and select the Cardano Account Load Binder plugin for the Load Binder property.
   
4. Configure the Cardano Account Load Binder accordingly by selecting the Testnet network and keying in your Blockfrost testnet project's API key, which you generated earlier, along with the necessary configurations. For more information, see Cardano Account Load Binder.
   
   
   
5. Save the form section configuration.
6. As end users do not need to modify any values in this new form section, we can set it as read-only. Go to the Advanced Tools > Permission tab and set this section as read-only.
   
7. Save the form.
8. Upon navigating back to the Account Details CRUD menu, you can now see these additional account details:
   

Performing ADA transactions w/ metadata

Now that you can see meaningful account data in our sample app, you are ready to try performing transactions on the Cardano blockchain via the Cardano Send Transaction Tool plugin.

1. To test out sending from one account to another, do generate another account in the sample app by running the Generate Account Process.
   You should end up with 2 accounts now.
   
2. On the app design page, create a new form with the following details:
   • Form ID: sendTransaction
   • Form Name: Send Transaction
   • Table Name: cardano_send_test
3. After creating the form using the Joget Form Builder, let's add a few necessary fields that a Cardano transaction requires:
   a. Sender Account
   Use a select box. Edit the element. For the Form Options Data Store, select the Form Data Options. For Form property, select the Account Details form. For the Label Column property, select the "id" field.
   
   b. Amount To Send (ADA)
   Use a text field. Edit the element, go to the Advanced Options tab, and select the Basic Validator for the Validator Field. Check the Mandatory property and select the Type property as Numeric.
   
   c. Receiver Account
   Use a select box. Edit the element. For the Form Options Data Store, select the Form Data Options. For Form property, select the Account Details form. For the Label Column property, select the "id" field.
   
4. Save the form.
5. Once the form is saved, click the Generate App button to use the App Generator.
6. Check the option for Generate Process - Approval Process, then click Generate.
   
7. Upon completing the generation and returning to the app design page, we can see that the relevant components for an approval-type process have been generated accordingly, with a Send Transaction Approval Process automatically deployed for us.
   
   
   
   
   
8. You need to modify the generated process design slightly to incorporate the Cardano Send Transaction Tool plugin into the app. Go to the Processes tab on the app design page, select the Send Transaction Approval Process in the dropdown, and click Design Process.|
9. Now that you are in the Process Builder, edit the process properties and add these additional workflow variables:
   • txValidated
   • txExplorerUrl
10. These workflow variables will later be used by the Cardano Send Transaction Tool plugin to update the transaction validation status and store an auto-generated Cardano transaction explorer URL.
    
11. Rename the process tool after the Approved path to Send Transaction.
    
12. Click Run Process at the top right corner to deploy this process.
13. Return to the app design page, go to the Map Tools to Plugins tab, and remove all the unneeded email tools automatically mapped during the approval process generation.
14. Add a plugin to the Send Transaction tool. Select the Cardano Send Transaction Tool.
    
15. Configure the Cardano Send Transaction Tool accordingly by selecting the Testnet network and keying in your Blockfrost testnet project's API key, which you generated earlier, along with the necessary configurations.
    To demonstrate the ability to embed form data into the transaction metadata, we will also check the Enable Transaction Metadata property and add these fields from the Send Transaction form:
    • id
    • dateCreated
    • createdBy
      For more information, see the Cardano Send Transaction Tool.
      
      
      
      
      
16. Launch the app to try sending transactions. Due to the approval process generation done earlier, we should see a new user view category that contains an Inbox Menu and Run Process Menu for the Send Transaction Approval Process.
    
17. Click Submit Send Transaction to start the process and follow the flow.
18. Here, select the account that you have funded previously as the sender account, specify the amount of ADA coins to send, and select the latter account that was just generated just now as the receiver account.
    
19. After submitting this activity, the process will flow to the Approval activity. Navigate to the Inbox Menu, select the Status as Approved, and submit this approval activity.
    
20. After doing so, the Cardano Send Transaction Tool will pick up these form field values and perform the transaction accordingly. To observe this, click Monitor in the admin bar and navigate to the Completed Processes tab.
    
21. Upon inspection of the completed process instance, we can see that the Transaction Validation Flag (represented by the txValidated workflow variable) is false. This is perfectly normal in the initial time period, as transactions performed on the Cardano Blockchain undergo confirmation to be accepted into the chain and become immutable. Transaction confirmations are usually completed in about 20 seconds, depending on the network load. 
    
    Note: 
    Transaction confirmations and chain confirmations (sometimes referred to as block confirmations) are different concepts. Transaction confirmation is the point in time when a transaction is accepted into the chain and becomes immutable, whereas chain confirmation is the point beyond which the chain is guaranteed by protocol not to alter any further and is usually considered complete after 15-30 blocks deep.
22. Once the transaction is confirmed and validated, the Cardano Send Transaction Tool will automatically set it to true.
    
    
23. Additionally, you can see that the Transaction Explorer URL (represented by the txExplorerUrl workflow variable) contains a URL generated by the plugin. Navigating to this URL in your browser leads to the official Cardano blockchain explorer website, where you can see this transaction as proof of existence and the form data embedded as the transaction metadata.
    
    As a proof-of-existence of this transaction done from this tutorial, you can browse to this URL to see the transaction details here: 
    https://explorer.cardano-testnet.iohkdev.io/en/transaction?id=8b8717afc57a661aed0f9156e651a663cd78cfd58e30026bbb94edcc60aa023e
    
    

Download plugin

• Cardano Blockchain Pack