Projects
A project is called a project in part to differentiate it from your own application(s) to which it corresponds. A project can be understood as an unlimited collection of related forms and resources that developers build and integrate/embed into one or more related application(s).There can be an unlimited number of forms and resources in a single project. There can be an unlimited number of developers working as a team on a single project. There can be an unlimited number of API submission calls on a single project.
Projects are the main working areas within the Form.io platform. Each Project is typically associated with a single form-based application, and includes many critical components such as Forms, Resources, Roles, etc. All of these components exist within a single "domain" API endpoint, where they are all encapsulated within the project context. Projects provide a contextual sandbox around the following components:
- Project Context
- Forms - Ad-hoc data collecting interfaces
- Submissions - Data submitted into each form
- Actions - Actions performed once the form is submitted; such as Email, Webhooks, etc.
- Logs - Keeps an active report of actions performed.
- Access - Assign Role-based permissions to certain actions within each form
- Revisions - If enabled, creates new revisions for every form update.
- Settings - Settings per-form
- Resources - Data model entities for an application
- Submissions - Data submitted to each resource
- Actions - Actions performed once the resource is submitted; such as Email, Webhooks, etc.
- Logs - Keeps an active report of actions performed.
- Access - Assign Role-based permissions to certain actions within each resource
- Revisions - If enabled, creates new revisions for every form update.
- Settings - Settings per-form
- Roles - Assigned to users to establish access control. Can be user defined.
- Stages - Child project contexts used to manage multiple environments and authoring workflows.
- Settings
- Integrations - Configure integrations with third-party provides, such as Email providers on a per-project basis
- Authentication - Configure SSO, OAuth, SAML, LDAP on a per-project basis.
- Stage Versions and Deployments - Used to manage the versions of this specific stage and deploy to other stages.
- On-Premise Environment - Allows you to connect a stage to a remote API server.
- General Settings - Includes CORS, API Keys, Public Configurations, etc.
New Projects can be created from the Portal home page. To get there from any part of the portal, Click on the Form.io logo within the header.
At the top will be a blue banner that contains the buttons to create a project. You can either create a custom project or use an application template.
Clicking on any of these icons will open up the Project create modal which provides you the ability to provide the following.
- Project Title: The Project Title is the name that will be used to identify and access a specific Project throughout the entire life of the Project. Keeping this in mind, a sensible Project naming convention should be utilized to clearly identify the Project as being associated with the corresponding customer Application in which it will be used.
- Description: The Project Description can be up to 512 characters and may be comprised of any letters, numbers, spaces, or other special characters. This description is simply used for reference within the Project, and is not utilized elsewhere.
- Advanced Options (Template): Project Templates are predefined templates that specify what Resources, Forms, and Actions to automatically create for you. You may select from one of our existing project templates, or upload your own. Templates can be created by exporting an existing project. For more information on templates, see the Project Templates section.
Within the modal, click Create Project and your new project will be created.
Within every project, you will see the following sections.
After your project has been created, you will land in the Project Portal. The project portal provides the ability to create new Forms, Resources, and many more features that will be covered in later sections of this documentation. Some of the project level features are as follows.
The API Explorer is a way to visualize the API's created when you build either Resources or Forms within your project. One of the more amazing things about the Form.io platform, is that when you create a new form for your application, a REST API is automatically generated to serve as the backend for not only that form, but also any other system that would like to create submissions. This API is visualized through the Swagger API documentation platform, and looks as follows.
API Explorer for the Forms and Resources created within your project
It should be noted, that this is a "live" explorer which means that any tests through this interface will actually execute the endpoints.
The Data section is a place where you can easily access the Submission data that has been submitted to each Form and Resource. It is also possible to access the data on a per-form or per-resource basis by clicking into the specific form interface, but this tab provides more direct access to that data. It first allows you to quickly find your form or resource and click on the Data button for that form or resource.
The Data section for forms and resources
Clicking on each Data section provides the following interface where you can easily manage the data within that form or resource.
Data section for each form
It should also be noted that you can perform exports of your data from within this section as well. This is discussed in more detail within the Submission Export documentation.
Also within the Access Section, you will have the ability to Create, Update, and Delete roles associated with this Project. Project Roles are documented in more detail within the Roles and Permissions section of our documentation.
The Settings section of your project allows you to configure Integrations, Authentication, Stages and Deployments, and also general settings within your project. The following sections can be configured.
This section allows you to connect the Developer Portal to any Form.io Enterprise remote environment that may be deployed. This provides a way to utilize a single form building portal interface to manage a multitude of different Environments using the staging system. To connect to a an on-premise environment, you must first have a Form.io Enterprise deployed without the portal enabled, and one that also provides a
PORTAL_SECRET environment variable. For example, the following Docker command can be used to run an environment that can be used for the On-Premise settings.docker run -d \
-e "LICENSE_KEY=YOURLICENSE" \
-e "MONGO=mongodb://mongo:27017/formio" \
-e "PORTAL_SECRET=CHANGEME" \
-e "DB_SECRET=CHANGEME" \
-e "JWT_SECRET=CHANGEME" \
--restart unless-stopped \
--network formio \
--name formio-server \
-p 3000:80 \
formio/formio-enterprise
If we were to run this docker container behind a domain name, such as https://forms.yourdomain.com, then you can connect to this environment using the following settings.
Connecting to an On-Premise environment
The following Project Path Types can be provided.
- Subdirectories: This places each project within this deployment within a "directory" structure like the following.
- https://forms.yourdomain.com/projecta
- https://forms.yourdomain.com/projectb
- Subdomains: This places each project within this deployment within a "subdomain" structure like the following.
- https://projecta.yourdomain.com
- https://projectb.yourdomain.com
It should be noted that the Subdomain project path type should be used for Advanced deployment configurations, and does require more advanced knowledge of DNS configurations and CORS considerations.
After you press Continue, you will then be presented with the following.
Select "New Stage" or pick an existing stage
This section allows you to either pick one of the following:
- New Stage - A new project on this remote environment will be created to attach to this portal project
- Existing Project - You can select any "existing" projects to "attach" this portal project to. It should be noted that by attaching to a remote project, the portal will now serve as a "window" into that remote project and will not alter the project during the attachment process.
After your project is connected to the external project, it will show all of the forms and resources as well as all submission data on that remote project. You can easily "detach" from this project by clicking on the Disconnect button.
Disconnect from a remote stage
Disconnecting from a remote stage will NOT affect the run-time performance of the remote stage. It is perfectly safe to Disconnect a portal interface from a Live Environment.
The API Settings section allows you to configure the API behaviors of your project. These include the following.
- API Keys: These allow admin access to your projects API's using the
x-tokenheader within each REST API request. - CORS Settings: This provides a way to limit the API access to your project via an application domain. For more information on how CORS works, we recommend reading the article at https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
This section allows you to configure how the Portal for this project will interact with a PDF server. The configurations for this section are as follows.
- PDF Server URL: Provides the PDF server url that will be used when uploading and connecting forms to the PDF server.
- PDF File Manager: The PDF File Management section keeps tracks of all uploaded PDF's within this project. These files are separate PDF files uploaded to remote storage providers (such as S3), and can be attached to any form within your project. This section is used to manage these files as well as delete them to free of storage space.
The Public Configuration settings provide a way to create public configurations for an application you are developing. These configurations are then represented under the following API endpoint.
https://yourproject.form.io/config.json
This can be used by your application to provide stage-specific configs that can be used for any purpose. In order to use these configurations, they must first be enabled by checking the following checkbox.
Enable Public Configurations for your project.
Next, you can provide some key-value pairs of configuration names and the values of those configurations.
For example, the above configuration will be represented by the following JSON at the
/config.json endpoint.{
"logo": "https://s3.amazonaws.com/app....",
"logoHeight": "40px",
"title": "Forms",
"baseUrl": "https://humanresources.form.io"
}
There are many times where you would like to have "global" values that can be represented on a per-stage basis within your forms. A good example of this is when you need to provide different URLs to your forms based on the stage in which the forms reside. In this situation, you can use the "Add Public Configuration to Form Schema" setting to enable the ability to expose these configurations to the evaluation contexts of your forms.
Once this is checked, all of these configuration variables will be added to each Form JSON schema under the "config" property of that form. To do this, you simply refer to this configuration using the following.
{{ config.baseUrl }}
This can be used as follows within any component.
How to use the public configurations within your form.
The Custom JS & CSS section allows any developer to inject their own custom scripts and styles to affect the behaviors as well as the look and feel of your forms.
Multiple third party services can be integrated with Form.io. These integrations cover everything from Form Actions to Data Storage options. Please see below further Integration Options:
Form.io provides multiple ways to Authenticate into the Form.io Developer Portal or your custom built applications. Please see below the various Authentication Options:
Stage Settings provide a way to create, manage and deploy Stage Versions. This process is documented in more detail within the Stages Documentation.
In addition to managing stages, this area in the developer portal enabled to ability to Export or Import Project Templates which are described in the following section.
Project Templates allow you to clone all your Forms, Resources, Roles, Settings, Permissions, Actions, etc. as a JSON Schema.
To export your project you need to navigate to Staging link in the side menu and choose Export Template.
To export, click on Export Template Button. As you may notice there are two checkboxes (Include all and Exclude Access Settings).
Include All will include ALL your Forms, Resources, Roles, Settings, Permissions, Actions, etc.
Exclude Access Settings will remove all your access settings and will provide the Default Access to your project when is imported.
Once you export a project template it will bundle all the Forms, Resources, Roles, Actions and Access into a JSON File. This JSON File can be imported into a new stage or project.
Import in a new stage.
Importing creating new project
You can upgrade your project by either clicking the 'Project Plan' button located in the side navigation bar or by clicking the Project plan Tag next to the Project title.
The Project Plan page allows you to review billing information, change your credit card, and upgrade/downgrade your project plan. Please review our Pricing Page for more information on each plan type.
Last modified 16d ago