Forms

Inmanta is capable of generating forms for the dashboard automatically. This makes customizing models a lot easier for end-users (and it creates a rest interface for your model).

In this example, we show how to make a form to choose OpenStack or Amazon and collect the credentials.

For example:

Example Form

Full source here

Defining Forms

Forms always have to be in a module. So, in the module formtest, we define our forms.

To define a form, just create an entity that extends param::Form

import param

entity CloudProvider extends param::Form:
    string _title = "Cloud provider"
    string _help = "Select a cloud provider to deploy the application to."
    string _record_count = 1
    
    string provider
    string provider__widget = "options"
    string provider__options = "AWS,Openstack"
end
entity OpenStackForm extends param::Form:
    string _title = "OpenStack credentials"
    string _help = "Specify the credentials to login into your OpenStack provider."
    string _record_count = 1
   
    string connection_url
    string username
    string password
    string tenant
    string network_name
    string network_name__help = "The name of the network to boot the VMs in."
end

entity AWSForm extends param::Form:
    string _title = "Amazon AWS credentials"
    string _help = "Specify the credentials to login into your AWS account."
    string _record_count = 1

    string region
    string access_key
    string secret_key
    string availability_zone
    string vpc_subnet
end

entity User extends param::Form:
    string _title = "Users"
    string _help = "Add users to create them automatically"
    
    string name
    bool admin = false
    string admin__widget="checkbox"
end

Special fields and conventions:

  • Each field in the entity becomes a field in the form.
  • Fields with an _ in the name can be used to pass metadata to the forms api.
_title the title of the form
_help help text of the form
_record_count if you set this value to 1, the form can be filled in only once, otherwise multiple records can be created
fieldname__widget what widget to use in the form, options are ‘options’,’checkbox’,’slider’. Omit for textbox.
fieldname__options comma separated list of options, for use with option widget
fieldname__min lowest value for numerical values
fieldname__max highest value for numerical values
fieldname__help help text for the field

Using Forms

To access a form with only one record, use param::one. Note that you don’t get an instance of the form object back, but that you have to get the information out, one field at a time.

To access a form with multiple records, use param::instances to get a list of instances. Then use param::get to get the fields of the instances.

import param
import formtest

provider_name = param::one("provider", "formtest::CloudProvider")

std::print(provider_name)


users = param::instances("formtest::User")
for i in users:
    user_name = param::get("name", i)
    std::print(user_name)
end

When you compile a model with a form, on first compile, the form definitions are sent to the server. All calls to param::one and param::instances return ‘Unknown’ which means that parts of the model that use these values are dropped from the output.

Note

When compiling models with forms, the compiler must always be able to connect to a server, or compilation will fail.

In the dashboard, you will now see the forms you have defined. If you fill in values and recompile, the values are used in the model.

Using the CLI

Forms can also be accessed via the CLI

There are two main endpoint: forms and records. Forms gives you access to all form definitions per environment, records gives you access to all record for each form.

For example:

$> inmanta-cli form list -e b6a0357f-8936-4db5-91f9-2c5ca75bf134
+-------------------------+--------------------------------------+
| Form Type               | Form ID                              |
+-------------------------+--------------------------------------+
| formtest::CloudProvider | 78616841-d757-4112-ac79-033373c72ff4 |
| formtest::User          | e1f21a14-5e21-4c6d-82b8-2303f3a7ce60 |
+-------------------------+--------------------------------------+
$> inmanta-cli form show  -e b6a0357f-8936-4db5-91f9-2c5ca75bf134 -t formtest::User
+-------+---------------------------------------+
| Field | Value                                 |
+-------+---------------------------------------+
| name  | type: string                          |
| admin | type: bool, default: {'admin': False} |
+-------+---------------------------------------+
$> inmanta-cli record list -e b6a0357f-8936-4db5-91f9-2c5ca75bf134 -t formtest::User
+--------------------------------------+----------------------------+
| Record ID                            | Changed                    |
+--------------------------------------+----------------------------+
| 38d2a543-89c3-4e90-9602-d827f9d1e6cb | 2016-11-08T16:20:11.229000 |
| 64211c57-1874-4445-8ede-c2dfa3be3bd4 | 2016-11-08T16:20:17.047000 |
+--------------------------------------+----------------------------+
$> inmanta-cli record list -e b6a0357f-8936-4db5-91f9-2c5ca75bf134 -t formtest::User -a
+--------------------------------------+----------------------------+-------+-----------+
| Record ID                            | Changed                    | admin | name      |
+--------------------------------------+----------------------------+-------+-----------+
| 38d2a543-89c3-4e90-9602-d827f9d1e6cb | 2016-11-08T16:20:11.229000 | True  | adminuser |
| 64211c57-1874-4445-8ede-c2dfa3be3bd4 | 2016-11-08T16:20:17.047000 | False | testuser  |
+--------------------------------------+----------------------------+-------+-----------+

To create records

$> inmanta-cli record create -e b6a0357f-8936-4db5-91f9-2c5ca75bf134 -t formtest::User -p admin=False -p name=TestCLi
+-------+---------+
| Field | Value   |
+-------+---------+
| admin | False   |
| name  | TestCLi |
+-------+---------+
$> inmanta-cli record list -e b6a0357f-8936-4db5-91f9-2c5ca75bf134 -t formtest::User -a
+--------------------------------------+----------------------------+-------+-----------+
| Record ID                            | Changed                    | admin | name      |
+--------------------------------------+----------------------------+-------+-----------+
| 38d2a543-89c3-4e90-9602-d827f9d1e6cb | 2016-11-08T16:20:11.229000 | True  | adminuser |
| 64211c57-1874-4445-8ede-c2dfa3be3bd4 | 2016-11-08T16:20:17.047000 | False | testuser  |
| c954706f-c13d-40e1-8daf-e596b54e6567 | 2016-11-08T16:32:13.614000 | False | TestCLi   |
+--------------------------------------+----------------------------+-------+-----------+

Using the API

Forms can also be access via the API. This is similar to the CLI, but easier to use in scripts. Examples use httpie

Important is that the environment is passed as a header called X-Inmanta-tid

The same as above, but via http:

$> http GET 127.0.0.1:8888/form X-Inmanta-tid:b6a0357f-8936-4db5-91f9-2c5ca75bf134
{
    "forms": [
        {
            "form_id": "78616841-d757-4112-ac79-033373c72ff4",
            "form_type": "formtest::CloudProvider"
        },
        {
            "form_id": "e1f21a14-5e21-4c6d-82b8-2303f3a7ce60",
            "form_type": "formtest::User"
        }
    ]
}

$> http GET 127.0.0.1:8888/form/formtest::CloudProvider X-Inmanta-tid:b6a0357f-8936-4db5-91f9-2c5ca75bf134
{
    "form": {
        "defaults": {},
        "field_options": {
            "provider": {
                "options": "AWS,Openstack",
                "widget": "options"
            }
        },
        "fields": {
            "provider": "string"
        },
        "form_id": "78616841-d757-4112-ac79-033373c72ff4",
        "form_type": "formtest::CloudProvider",
        "options": {
            "help": "Select a cloud provider to deploy the application to.",
            "record_count": 1,
            "title": "Cloud provider"
        }
    }
}
$> http GET 127.0.0.1:8888/records form_type=formtest::User  X-Inmanta-tid:b6a0357f-8936-4db5-91f9-2c5ca75bf134
{
    "records": [
        {
            "changed": "2016-11-08T16:20:11.229000",
            "record_id": "38d2a543-89c3-4e90-9602-d827f9d1e6cb"
        },
        {
            "changed": "2016-11-08T16:20:17.047000",
            "record_id": "64211c57-1874-4445-8ede-c2dfa3be3bd4"
        },
        {
            "changed": "2016-11-08T16:32:13.614000",
            "record_id": "c954706f-c13d-40e1-8daf-e596b54e6567"
        }
    ]
}
$> http GET 127.0.0.1:8888/records form_type=formtest::User include_record=True  X-Inmanta-tid:b6a0357f-8936-4db5-91f9-2c5ca75bf134
{
    "records": [
        {
            "changed": "2016-11-08T16:20:11.229000",
            "fields": {
                "admin": true,
                "name": "adminuser"
            },
            "form_id": "e1f21a14-5e21-4c6d-82b8-2303f3a7ce60",
            "form_type": "formtest::User",
            "record_id": "38d2a543-89c3-4e90-9602-d827f9d1e6cb"
        },
        {
            "changed": "2016-11-08T16:20:17.047000",
            "fields": {
                "admin": false,
                "name": "testuser"
            },
            "form_id": "e1f21a14-5e21-4c6d-82b8-2303f3a7ce60",
            "form_type": "formtest::User",
            "record_id": "64211c57-1874-4445-8ede-c2dfa3be3bd4"
        },
        {
            "changed": "2016-11-08T16:32:13.614000",
            "fields": {
                "admin": false,
                "name": "TestCLi"
            },
            "form_id": "e1f21a14-5e21-4c6d-82b8-2303f3a7ce60",
            "form_type": "formtest::User",
            "record_id": "c954706f-c13d-40e1-8daf-e596b54e6567"
        }
    ]
}

To create records:

$> http POST 127.0.0.1:8888/records form_type=formtest::User X-Inmanta-tid:b6a0357f-8936-4db5-91f9-2c5ca75bf134 form:='{"name":"apitest","admin":false}'
{
    "record": {
        "changed": "2016-11-08T16:49:50.239000",
        "fields": {
            "admin": false,
            "name": "apitest"
        },
        "form_id": "e1f21a14-5e21-4c6d-82b8-2303f3a7ce60",
        "form_type": "formtest::User",
        "record_id": "d652db64-77b7-477b-b4f6-e222883f4a47"
    }
}

$> http GET 127.0.0.1:8888/records form_type=formtest::User include_record=True  X-Inmanta-tid:b6a0357f-8936-4db5-91f9-2c5ca75bf134
{
    "records": [
        {
            "changed": "2016-11-08T16:20:11.229000",
            "fields": {
                "admin": true,
                "name": "adminuser"
            },
            "form_id": "e1f21a14-5e21-4c6d-82b8-2303f3a7ce60",
            "form_type": "formtest::User",
            "record_id": "38d2a543-89c3-4e90-9602-d827f9d1e6cb"
        },
        {
            "changed": "2016-11-08T16:20:17.047000",
            "fields": {
                "admin": false,
                "name": "testuser"
            },
            "form_id": "e1f21a14-5e21-4c6d-82b8-2303f3a7ce60",
            "form_type": "formtest::User",
            "record_id": "64211c57-1874-4445-8ede-c2dfa3be3bd4"
        },
        {
            "changed": "2016-11-08T16:32:13.614000",
            "fields": {
                "admin": false,
                "name": "TestCLi"
            },
            "form_id": "e1f21a14-5e21-4c6d-82b8-2303f3a7ce60",
            "form_type": "formtest::User",
            "record_id": "c954706f-c13d-40e1-8daf-e596b54e6567"
        },
        {
            "changed": "2016-11-08T16:49:50.239000",
            "fields": {
                "admin": false,
                "name": "apitest"
            },
            "form_id": "e1f21a14-5e21-4c6d-82b8-2303f3a7ce60",
            "form_type": "formtest::User",
            "record_id": "d652db64-77b7-477b-b4f6-e222883f4a47"
        }
    ]
}