Flow Designer

Authentication Flow Designer is a complete set of tools that you need to build, manage, maintain, and test your Agama projects and authentication flows. You can use the flow designer to

Create and manage Agama projects using the dashboard
Create and make changes to the authentication flows using a low-code drag-drop visual editor
Manage multiple projects from a single development repository
Publish and release an Agama project to a release repository
Use template editor to create and edit UI templates used in the flow
Import and export flows
Deploy and test Agama projects

Agama Project Life-cycle

Creating A New Project

After installing the GitHub Agama Lab app, you can create an Agama project using the Agama Lab. High-level steps involved in creating, updating, and releasing a project are as below:

Create a new public repository in GitHub. We will use this as a development repository. Make an initial commit to this repository to initialize it, for example, creating a README. A repository without an initial commit will not be visible to the Agama Lab.
Allow access to Agama Lab to the development repository.
Sign in to the Agama Lab, navigate to Flow Designer, and click select repository.
Select whether your GitHub account is an organization or an individual account. Select the development repository from the dropdown. Click on Let's go button.
Click on + New Project button to create a new Agama Project in the development repository.
Once a project is created, it can be developed and updated using the Flow Designer’s visual editor. Every time the flow is changed and saved, the Agama Lab adds a new commit to the development repository’s agama-lab-branch branch.
When the flow has been created in the project, and tested as well, the project is ready to be released as .gama package. But this can not happen in the current development repository. This is because a development repository may have multiple other projects which are still under development. To release a project, it has to be moved to a different GitHub repository called a release repository. This process of making the first release from the development repository to the release repository is also called publishing an Agama project.

Publishing A Project

In the GitHub account, create a new repository that will be used as release repository. To create this repository, follow the same steps that were followed while creating development repository.
Allow the Agama Lab access to this repository using Agama Lab GitHub app.
From the Agama Lab flow designer, open the development repository and open the project that you want to release.
On the left navigation menu, right-click on the code directory and click on publish project option. Provide the desired first version number and the URI of the target repository. Pressing ok will initiate the publishing process where Agama Lab will move the complete project from development repository to the new release repository. You can see the release artifacts like .gama package under the release section of the release repository.

Releasing A Project

The first release of the project has already been created as a part of the publishing process. As a result of the publishing process, the project has been moved to its dedicated release repository as well. All subsequent changes to the project should be made to this release repository and not to the development repository.code directory and click on publish project option. Provide the desired first version number and the URI of the target repository. Pressing ok will initiate the publishing process where Agama Lab will move the complete project from development repository to the new release repository. You can see the release artifacts like .gama package under the release section of the release repository.

Owner Workflow

The owner of the GitHub release repository can use Agama Lab to make changes to the project in the release repository.

Open the release repository and the project in the Agama Lab
Make the required changes to the project
Save the project
Right click on the code directory on the left navigation and click on Release Project option
Provide the version number to be used for the next release and click on Release button. This should create a new release in the GitHub release repository.

When the changes are ready, the owner can create a new release from Agama Lab in the release repository.

Contributor Workflow

If you are not an owner of the release repository but want to propose changes to the project, Follow the steps below:

Create a fork of the release repository
Open project in Agama Lab from the forked repository
Make the desired changes and save the project. This will create a commit in the forked repository
Go to GitHub and create a PR targeting the release repository

Once the owner merges the PR in the release repository, the changes will be available in the next release of the project

Glossary of Terms

Agama project

An Agama project is represented by a .gama archive. It contains one or more .flow files of related authentication flows along with the libraries, UI assets, and the documentation required for the flows. A .gama package is used to deploy the Agama project on a compatible IAM server.

Agama flow

An Agama flow is represented by a .flow file. Code is written using Agama DSL.

Development Repository

A development repository is a GitHub repository that stores multiple Agama projects and it is used during the development of the projects. All the projects are stored in the branch agama-lab-flow-designer.

Release repository

A release repository is a GitHub repository where an Agama project is published from a development repository when the project is ready to move to production. The release repository holds a single Agama project in the main branch.