The `.gama` file format#

In practice, a web flow will make use of a bunch of artifacts, like UI pages, images, stylesheets, and source code. Actually, to solve a real-world problem several flows are needed to be able to keep flexibility and complexity at acceptable levels. Here is where the concept project emerges.

A project can be thought of as a container to hold all flows and related assets aimed at solving a particular problem - including metadata of the project itself. The idea of defining a standard way to specify projects brings several benefits:

Provide a uniform conceptual scheme for community actors to interchange flows
Provide Agama engine implementors common ground for the materialization of flows deployment
Serve as reference for developers interested in coding tools such as an Agama IDE

Anatomy of a project#

The below shows the structure of an Agama project:

├── code/
├── lib/           
├── web/
├── project.json   
├── LICENSE        
└── README.md

code directory holds all flows part of the project. Every flow - implemented in Agama language - has to reside in a separate file with extension flow and with file name matching the qualified name of the flow in question. This directory can have nested folders if desired
lib may contain source code files in languages other than Agama and binary libraries required by the project, if any. Every engine can make use of the contents of this folder as needed
web is expected to hold all UI templates plus required web assets (stylesheets, images, etc.) that all flows in this project may use
project.json file contains metadata about this project. More on this later
README.md file may contain extra documentation in markdown format
LICENSE file may contain legal-related information

Except for code and web directories, all elements in the file structure above are optional. Note that files in web must follow a directory structure that is consistent with respect to Basepath and RRF directives found in the included flows.

Metadata#

project.json file is expected to contain metadata about the contents of the project in JSON format.

Field	Description	data type
`projectName`	A unique name that will be associated to this project	string
`version`	Project's version. It is recommended to use semantic versioning format	string
`author`	A user handle that identifies the author of the project	string
`license`	A reference to applicable license terms	string
`description`		string
`configs`	Object containing exemplifying configuration properties for flows that may need them. The keys of this field, if any, are qualified flow names already part of the project	json object
`noDirectLaunch`	An array holding zero or more qualified flow names. This list is used to prevent certain flows to be launched directly from a web browser. It's a security measure to avoid end-users triggering flows at will	array

All fields are optional and more can be added if desired.

Below is an example of a project.json file:

{
  "projectName": "biometric-auth",
  "version": "2.0.3",
  "author": "avgJoe123",
  "license": "apache-2.0",
  "description": "Allows users to authenticate via fingerpint and/or iris recognition",
  "configs": {
    "com.acme.bio.IrisScan": {
        "prop1": "secret",
        "prop2": { "subprop": [1, 2, 3] }
    }
  },
  "noDirectLaunch": [ "com.acme.bio.TraitExtractor" ]
}

Important

Use the configs section wisely: .gama files must not contain real configuration properties because these files may be freely distributed; in practice, configurations hold sensitive data that should not be exposed

Sample project#

As an example assume you want to deliver these two flows:

Flow test
    Basepath "hello"

in = { name: "John" }
RRF "templates/index.htm" in

Log "Done!"
Finish "john_doe"

Flow com.foods.sweet
    Basepath "recipes/desserts"

...

choice = RRF "selection.htm"
list = Call com.foods.RecipeUtils#retrieveIngredients choice.meal
...

Here is how the project folder might look like:

├── code/
│   └── test.flow
│   └── com.foods.sweet.flow
├── web/
│   ├── hello/
|   |   └── templates/
│   |       └── index.htm
│   |           └── js/
│   |               └── font-awesome.js
|   └── recipes/
│       └── desserts/
│           └── selection.htm
│           └── logo.png
├── lib/
│   └── com/
│       └── foods/
│           └── RecipeUtils.java
└── project.json

`.gama` file#

Dealing with a folder this way can be awkward for sharing and other tasks. Instead, if the project contents are compressed using the ZIP file format, we have what is known as .gama file. Thus, a .gama file is a project archive that can be shared and deployed to an Agama engine.

Project deployment#

The actual "deployment" of an Agama project is an engine-specific detail. Engines must offer mechanisms for administrators and developers to "install" .gama files.

Last update: 2023-12-29
Created: 2023-06-06

The .gama file format#