Console Overview

Overview

project:DABL is a cloud platform built to help you take your SaaS application from humble beginnings to mass adoption with as little development as possible.

DABL is a great option for any developer looking to build a simpler, scalable backend for their application with a serverless experience.

Almost any application heavier than a pure web app can benefit from using project:DABL as a backend. Developers are using project:DABL to build applications like crypto exchanges, loan management platforms, medical claims management, digital rights management, and many more.

Witness the powerful combination of DAML and DABL in this video that shows how to build and deploy a simple chat app from scratch in under 10 minutes.

Home

Home is the first tab you see when signing into project:DABL. From here, you can join existing project:DABL applications, or head over to the Workspace to create your own. You can also get an overview of Recent Activity across all the DABL apps you are currently participating in.

Screenshot Placeholder

Apps

If you've been invited to join a project:DABL application, you'll be able to click the Join by Ledger ID button to add it to your Apps list. While you're joining an app by Ledger ID, you will be prompted to enter in a custom name for the application. This is for your convenience, so you can remember the application when you see it again later.

After joining the app, you will have the ability to create contracts on the ledger, see your current active contracts, and exercise choices. See Live Data for more details.

Recent Activity

As activity from the ledgers you've joined starts coming in, the Recent Activity section will begin to populate, telling you: what contracts have been created that are visible to you, the name of the contract's template, and the parties associated with the contract. Clicking on the contract in the Recent Activity list will take you directly to it on the Live Data page, where more options are available.

Workspace

After signing in to project:DABL, you will be given your very own app building workspace. The workspace is where you can manage files and organize your ledgers into projects. Each project can contain multiple ledgers, that differ based on their deployments. Both projects and ledgers can be created and deleted within the workspace. For more information on ledgers, please see the DA Ledger Model.

Screenshot Placeholder

The collections tab in the workspace is where you can upload DAML, automation, UI assets or integration files. By keeping your files in your workspace collections, it is easier to deploy and re-deploy them across multiple ledgers. Files can be deployed from the workspace collections by clicking the button Deploy to..., or by simply dragging and dropping into a ledger.

The workspace is also home to pre-built sample applications. For more information and a quick start guide, see Deploying your own DABL Chat app.

Ledger Limits

For users on the DABL Free Tier, created ledgers are subject to becoming paused after 24 hours of inactivity. This means that the ledger and all of its deployed artifacts (user websites, automations, and integrations) are suspended. At any point within a 90 day period after being paused, the ledger can be resumed from the Workspace.

After 90 consecutive days of inactivity, the paused ledger and all of its deployed artifacts will be permanently removed.

File Size Limit

File size limit for all files, including .dar, .dit, .tar, .tgz, .tar.gz, and, .zip is 32 MB.

Quick Build

The Quick Build tab is revealed when you click "Wondering what to do next?". It shows you the building blocks of your DABL app, and the file count of your current ledger. Click on a tile to upload DAML, DAML Triggers, automation, and UI assets directly to your ledger.

Screenshot Placeholder

Deployments

By clicking on a ledger in the workspace, you can view its console. The Deployments tab in the ledger's console is where you can manage app artifacts, configure files, and publish a frontend for your application.

Files uploaded will automatically be deployed, unless they require pre-configuration. Unconfigured files that have yet to be deployed will appear under Action Needed.

Screenshot Placeholder

Once configured, deployments are listed in the Deployments table. Here you can easily manage and access each deployment's data, instances, logs, code, and settings.

Screenshot Placeholder

DAML Models

DAML templates define the data model and the functional features of your application. For more information on DAML, and DAML Models, see An Introduction to DAML.

Automation

Most applications powered by project:DABL will include a combination of DAML templates and automation. You can write automated services in Python or by using DAML Triggers.

DAML Triggers

DAML Triggers allow you to write your app's automated processes in DAML. To deploy a DAML Trigger to DABL, have all of the DAML templates compiled into one model .dar. Have the separate trigger project import this model in the dependencies of daml.yaml.

sdk-version: X.X.X
name: copy-trigger
source: daml
parties:
  - Alice
  - Bob
version: 0.0.1
# trigger-dependencies-begin
dependencies:
  - daml-prim
  - daml-stdlib
  - daml-trigger
  - copy-trigger-model-0.0.1.dar
# trigger-dependencies-end

Execute daml build on the trigger project, then upload both the model .dar and the trigger build separately to your DABL ledger.

Screenshot Placeholder

For more information on DAML Triggers see Runnning a DAML Trigger.

For limits on file size for .dar see file size limit above.

Python Bots

Python bots must be uploaded and deployed in the form of .tar, .tgz or .tar.gz files. You can read more about how to write and test bots here.

For limits on file size for .tar, .tgz, and, .tar.gz see file size limit above.

Integrations

Integrations are installable modules that allow your app to interact with the outside world by sending and receiving requests from external systems. Once installed in a DABL app, an integration mediates between the DABL ledger and an external system, managing connections to the external system, converting data to and from DAML contracts, and participating fully in the DAML security and permissions model. Integrations are uploaded and deployed in the form of .dit files and managed through the DABL console. To get started, there is a standard package of some basic integrations available in the Workspace under After you create a project.... You can read more about how to configure and install integrations here.

App UI

The App UI allows you to provide a frontend for your app by publishing files to a ledger-specific subdomain. These assets must be uploaded and deployed in the form of .zip files. The .zip should contain a single root directory and the contents of that directory should contain an index.html, along with the rest of the resources for your UI. A good example of this file structure can be found in here in the DABL Chat repo.

Once your UI Asset is deployed to its associated ledger, you can publish it to a unique subdomain. Once the website spins up, you can visit your new site by clicking View Site.

For limits on file size for .zip see file size limit above.

Live Data

The Live Data tab allows you to explore the DAML contracts on your ledger.

The table displays a list of contracts filtered by party. Therefore, the contracts listed at any given time are those that the selected party can view and take action on. You can manually add parties by clicking the Add Party button.

You can view a specific contract's data by selecting it from the center column. Additionally, you can exercise choices on behalf of your currently selected party. DAML contracts can be created in two ways: either by clicking the Add Contract button and creating a new contract from a template or by exercising a choice on an existing contract. New contracts are temporarily marked with a green dot to indicate that they have been recently created.

Screenshot Placeholder

When creating a contract from a template, be advised of the following type structure:

  • Primitives - For Int, Decimal, Text, Timestamp, Scenario, and ContractId simply enter the value in the empty field. Date lets you select the date you want from a calendar. Party and Bool inputs contain dropdowns where you select the desired value.

    Note: The Party dropdown will only display the parties that are visible to you. If you've created the ledger, you will see all the parties of each joined user. If you've joined someone else's ledger, you will only be privy to the parties that you've created. If you would like to input a party that you don't have visibility to, you will need to ask that party's user for their party ID, and paste it into the dropdown directly.

  • Lists - Enter each value of the list separately and press enter. An empty list is created by default if you don't enter any values. If you wish to delete a single value, press on the x that appears above it.
  • Optionals - Optional primitives are inline whereas optional records and variants are on newlines. To input an optional value, click on the view button and fill in the fields. The information is saved even when you collapse the window. If you don't want to enter anything, leave the fields blank.
  • Maps - Maps are represented as key-value pairs. Keys and values have their respectively separate input fields.
  • User-Defined Types - Variants appear as dropdowns and records as blocks containing their values. Variants with constructors appear as dropdown menus. Each constructor is an item on the dropdown. Once a constructor is chosen, the input fields for it appear below.

The representation of user-defined types may become arbitrarily complicated and this user interface assumes a relatively simple structure of the latter.

Sample Apps

Deploy your own DABL Sample App

After signing in to the project:DABL console, a few sample apps will appear at the bottom of the workspace. These are simple DABL applications, built by DABL engineers. Deploy them onto a ledger to get started with a fully implemented example.

1. Create a project in the Workspace

Click on New Project and provide a unique name for your project and first ledger. A new project and dedicated ledger will be deployed in a couple of minutes.

Screenshot Placeholder

2. In the bottom section of the workspace, pick an app to deploy, and click Add to Project.

Screenshot Placeholder

3. Choose the project and ledger you just made. All the necessary files will be promptly deployed.

Screenshot Placeholder

4. When the files finish deploying, click on the ledger you just deployed to.

Screenshot Placeholder

5. Configure the deployed files in your ledger.

Go to the Deployments tab. The uncongifured Automation Files will appear under Action Needed. Click on each and configure the automation to run as UserAdmin. Click Launch. It will take a couple of minutes to deploy.

Screenshot Placeholder

Once the automation is running, it will appear under Deployments.

6. Publish your UI Asset

In the Deployments tab is a file listed as a UI Asset. If not already published, click Publish. It will take a few seconds, once it's deployed, click on Visit Site at the top of the deployments table to interact with your very own sample app instance!

7. You're live!

Interact with the application through the app’s UI:

Screenshot Placeholder

8. Explore your app in the DABL console

After deploying your sample app, you can inspect active contracts on the ledger and create new ones from the Live Data tab, upgrade and view your artifacts in the Deployments tab, and learn more about your ledger in Ledger Settings.

If you want to modify a sample app according to your needs you can find the source code on:

DABL Chat Github

OpenWork Board Github.

DABL Chess Github (coming soon!)

Integrations

Installing and Managing Integrations

Installing Integration Types

DABL integration types are defined using .dit files containing the resources needed for the integration to operate. This always includes the executable code required for the integration and often includes one or more DAML models used to represent the data managed by the integration. Deploying a .dit file into a ledger makes both the DAML models and the integration code itself available for use within the ledger.

Deploying the .dit file is done in the same style as other deployable artifacts, either by dragging the filename from the collection to the ledger in the workspace, or with the Deploy to... command:

Screenshot Placeholder

Once a .dit file has been deployed into a ledger, the resources defined within that file are shown as Deployments. In this case, starting with an empty ledger, deploying the .dit has added a DAML model and two integration types that can be configured.

Screenshot Placeholder

For limits on file size for .dit see file size limit above.

Creating and Managing deployments

Clicking on a type of integration in the action needed section, links to a page that describes the operation of the integration and allows configuration properties of that integration to be specified.

Every integration has two standard configuration fields - a field for a human-readable comment describing the purpose of the specific integration, and a field identifying the ledger party the integration will run as. When running, the integration has only the rights of the "Run As" party - It can only see events relating to the contracts visible to that party and can only exercise choices on behalf of that party. If there is a need for an integration to run as more than a single party, a separate deployment of the integration must be created for each party. Some integrations also allow for additonal configuration fields beyond just these two.

Screenshot Placeholder

Once the integration has been launched, it appears on a list of deployments of that type of integration. Additional deployments (running as different parties or with different configuration settings) can be added by clicking on Configure New deployment. The Pause button temporarily disables the integration, and the Delete button completely deletes it.

Screenshot Placeholder

There are also options availble under Details for inspecting and adjusting the configuration of the integration, viewing the detailed status of the integration, and seeing a technical log of how the integration is operating.

You can view running integrations as listed on the Deployments screen. Clicking on the name of the integration links to the deployment list for that specific integration and the screen for creating new deployments of that type:

Screenshot Placeholder

Core Integrations

DABL ships with two special purpose core integrations. These are not typical integrations in that they do not strictly integrate with external systems, but they are intended for solving specific problems without additonal code. The first is a periodic timer integration that allows ledger choices to be exercised in response to a periodic timer. The second is a Loopback integration that allows ledger commands to be issued in response to events occurring on the ledger.

Custom Integration Types

If you have an interest in adding custom integration types to DABL, either for your own use or for the community, please contact Digital Asset for more details.

Ledger Initialization with DAML Script

DAML script is a development tool with a simple API that runs against an actual ledger. Using it with DABL achieves automated and accurate ledger bootstrapping, enabling you to skip manual onboarding and other preliminary logic to initialize the state of your ledger.

Migrating Scenarios to DAML Script

The simplest way to write DAML script is to use pre-existing scenarios and make simple changes to them. The DAML docs have a migration guide that explains this simple translation. Otherwise, the DAML docs also have a guide for writing DAML Script from scratch, which is very similar to writing scenarios.

Changing the scenario code of your .dar will ultimately change its hash. To avoid this, create a directory containing the project with your DAML models, and create a new project in that directory containing a single file for your DAML Script.

Now, copy your scenario code into the single file of your script project. Convert it to DAML Script and import the contracts used in your models, as well as Daml.Script.

In the case of onboarding ledger parties, your DAML script should include a record containing the ledger parties in your workflow. This record is passed in as the argument for your script. Below is an example of a script that takes parties as input:

  module Setup where

  import Actors.Intern
  import Actors.Analyst
  import Actors.Associate
  import Actors.VicePresident
  import Actors.SeniorVP
  import Actors.ManagingDirector

  import Daml.Script

  data LedgerParties = LedgerParties with
    intern : Party
    analyst : Party
    associate : Party
    vicePresident : Party
    seniorVP : Party
    managingDirector: Party
      deriving (Eq, Show)


  initialize : LedgerParties -> Script ()
  initialize parties = do
    let intern = parties.intern
        analyst = parties.analyst
        associate = parties.associate
        vicePresident = parties.vicePresident
        seniorVP = parties.seniorVP
        managingDirector = parties.managingDirector

    -- continue with the rest of your script's logic...

Configure your build with DAML Script

In the daml.yaml file of your script project, add daml-script to the list of dependencies, the ledger parties that you specified as arguments to your script, and under data-dependencies add the name of the corresponding .dar containing your models. If you are not using a separate project for your script, you can exclude that line.

  sdk-version: 1.3.0
  name: bootstrap-script1
  source: daml
  init-script: Setup:initialize
  parties:
    - Intern
    - Analyst
    - Associate
    - VicePresident
    - SeniorVP
    - ManagingDirector
  version: 0.0.1
  dependencies:
    - daml-prim
    - daml-stdlib
    - daml-script
  data-dependencies:
    - ../bootstrap/.daml/dist/bootstrap-0.0.1.dar
  sandbox-options:
    - --wall-clock-time

Deploy your .dar to a Project:DABL ledger

In the terminal, execute the command daml build in your script project. Then, upload the .dar containing your models to an empty ledger in DABL.

Screenshot Placeholder

For limits on file size for .dar see file size limit above.

Download the script’s ledger parties from DABL

Next, add the ledger parties from your script to your ledger in the Live Data view. All this is doing is initializing parties, so there will be no contracts yet.

Screenshot Placeholder

Now, download these parties and their access tokens to use as inputs to your script. DABL produces a participants.json for you in the Ledger Settings tab.

Screenshot Placeholder

Add the participants.json file to your script project.

Initialize ledger inputs

As the final step, create a file named ledger-parties.json in your script project.

The json here must be formatted [party_name] : value, which is the reverse mapping of the party_participants field in participants.json. Here is an example of the contents of ledger-parties.json:

{
    "intern": "ledger-party-2b645725-41d2-441d-b259-fb8dab0aad11",
    "analyst": "ledger-party-0423c1fe-2287-4bd0-a20b-9624b4005d13" ,
    "associate": "ledger-party-581594c7-bd48-489b-a62d-9ec79c214cdf" ,
    "vicePresident": "ledger-party-964ef06c-e7f3-41fe-8517-426797944b00" ,
    "seniorVP": "ledger-party-0ae3d20a-b418-4b10-a20c-6f9ee0410233" ,
    "managingDirector": "ledger-party-dab32e1e-c472-4930-96e5-f105c3303cb5"
}

Run the script against your ledger

Now that you have all the inputs for our DAML Script, we need to run it against the ledger with the following command:

daml script --participant-config participants.json --json-api --dar <Name of .dar that contains the DAML Script> --script-name <Name of DAML Script function> --input-file ledger-parties.json

The command consists of our participant-config being the participants.json file, the json-api tag because DABL uses the Json API, the name of the dar that contains the DAML Script which in the example would be .daml/dist/bootstrap-script1-0.0.1.dar, the name of the script function which in the example would be Setup:initialize, and the input file ledger-parties.json.

After running this command, go back to your project:DABL ledger, and you will see the contracts created by the DAML script bootstrap process.

For more details on DAML Script, visit the DAML docs .