License Management
Last updated
Was this helpful?
Last updated
Was this helpful?
Users with an installation of Form.io within their own Self-Hosted private cloud or on-premise environment will manage the of the Projects within that environment through valid License Key(s). These keys are implemented within the for the associated deployment and managed by users.
To access and manage the keys, License Managers will log into the SaaS portal at and navigate to the License Management page found in the left-hand navigation bar, or by clicking the username dropdown. You must be a License Manager User to access and manage the License Key.
The License Management page will display all licenses associated with the License Manager's account. The License line item will summarize information such as the License Key name, Start/End dates, and all the Managers associated with the License Key. Users will typically only have one license key they manage, but some users may have multiple keys associated with different environments.
Clicking the carrot icon next to the License Key Name will expand the License details. The left-hand navigation tabs will guide the user through all of the utilization options such as API and PDF Servers, Projects, and Tenants.
Environment ID: The Environment ID the Server is associated with. Use the status endpoint within your environment to view the ID associated with your deployment:
https://myenvironment.com/status
The URL will output the server version, the associated schema, and the Environment ID. The Environment ID can then be matched up with the ID found within the License Management page. This can help you determine what environment the server resides in.
Host Name: Links an environment with the Enterprise server network host it was created on.
Mongo Hash: MD5 hash of the mongoDB configuration which is useful for server logging and is an additional way to tie the user's database to the associated environment
Delete: Removes the server utilization from the License Management UI. This does not disable the functionality of the server within the self-hosted environment.
Title: Title of the Project
Name: The live endpoint name of the Project
FM: When checked, indicates if the Form Manager application is enabled for the Project. Clicking the carrot icon next to the Project title will show which stage within that project has the Form Manager enabled.
Project ID: ID found within the environment URL of the Project
Environment ID: The Environment ID the project resides in. This ID will match the associated server Environment ID within the same license.
Deleting a License utilization like an API Server, Project, or Tenant from the License Management page does not delete this item from the database. When deleted, the utilization is simply removed from the License Key which is helpful when cleaning up the UI for unused utilizations.
Deleted Project, Stage, or Tenant utilizations will reactivate if the Project or Stage is opened again by a user within the self-hosted environment.
Spinning down an API or PDF server from the database does not remove the associated License utilization and will need to be manually removed or disabled within the License Management UI.
If your Form.io deployment is experiencing license errors, it could be due to several reasons. It's important to note that when a Form.io License fails, the platform and form functionality are affected differently depending on the type of license failure that has occurred. Here are the most common causes, the type of failure that can happen, and how to fix them:
Form.io’s license verification process requires your server or application to communicate with Form.io’s license server. If there are network restrictions in place, such as firewalls, VPNs, or proxy settings, these can block the connection, leading to license validation failures. Most license connection issues occur when the server deployment is incorrectly configured, preventing a successful connection to the license server.
What can cause a License Server connection issue?
Firewalls Blocking Outbound Requests Ensure that your server can send outbound requests to the License server
Proxy Servers or VPNs Interfering with Requests If your environment requires outgoing traffic to go through a proxy server, ensure your Form.io requests are correctly routed:
Cloud Provider Security Rules (AWS, Azure, GCP, etc.) Update the Cloud Provider security rules to allow outbound HTTPS traffic to the license server.
A 12-hour grace period starts if the environment can't communicate with the license server.
During this grace period, the platform and forms will function as normal.
After the 12 hour grace period expires, the server enters restricted mode. During this time, any PUT, PATCH, and DELETE requests return 503 errors (excluding form draft PUTs).
Reconnecting to the license server restores full functionality.
When the server detects an invalid license, it will immediately shut down, requiring a valid license key or an update to the license expiration date.
What can cause an Invalid License?
Missing License Variable The LICENSE_KEY variable is missing from the environment variables.
Invalid License Key The License Key saved within the environmental variables of the deployment is invalid. Update the variable with a valid key and restart your container.
The server will immediately exit with a 503 error which will remove portal and form functionality.
If you encounter a utilization error when accessing your Project, you may have reached the allocation project limit within your license scope, or your Project status is turned off.
Error accessing project: Project license utilization is disabled
Follow these steps to review and update your license scope
Copy your Project ID from the URL endpoint within the browser
Search for the Project ID copied in step 1
If the License has available projects within the scope, simply click the Status button for the Project and then the Save Projects License. Refreshing the Project should resolve the error.
To disable a Project utilization, click the Status button of an active project within your License scope and click the Save Projects License button
With the additional Project allocation available, toggle the Status button for the Project you want to allocate and click the Save Projects Licenses button
If everything on the Project side checks out, ensure your API/PDF Server status is active. Since many users may have servers running on different environments, it's important to identify the correct environment the issue is occurring.
Within your environment, input the status endpoint within your browser
https://myenvironment.form.io/status
Copy the Environment ID found in the log
Within your License Management, click the API Server or PDF Server tab
Search for the Environment ID and determine whether the server Status is active
To free up server allocation, disable an active server by clicking the Status button and then Save API Servers Licenses
Click the Status button for the Server you wish to activate and then Save API Servers Licenses
Another avenue for troubleshooting is reviewing your container logs. These logs will often give you detailed information on what server is failing and the ID associated with the environment. This information can then be used within the License Management UI to determine the Server or Project that is consuming the utilizations.
Review your server logs and observe any license validation errors
Take note of the Environment ID within the validation error
Within your License Management, click the API Server or PDF Server tab
Search for the Environment ID and determine whether the server Status is active
Free up a utilization for an active server by clicking the Status button and then Save API Servers Licenses
Within the API Server tab of your License Management UI, click the Status button for the Server you wish to activate and then Save API Servers Licenses
With an additional API Server allocation available, you should be able to restart your Container with success.
Clicking the or Server tab will display all of the servers associated with the License. information for the servers such as what environment the server resides in, and the ability to manage the utilization. For example, you may need to disable the status of one API server to provide an allocation to a different server you're trying to spin up.
Status Toggle: Click the Toggle to disable the server utilization for the environment. Disabling will free up another server utilization for your environment. Disabling or deleting the utilization will not spin down the server. See for more information
The tab lists all Projects associated with the given License Key. License Managers can manage the utilization of the Project, Stages, and connected Form Manager Applications.
Status / Delete: Click the Status to disable the project utilization and delete to remove the utilization from the License Management UI. Disabling or deleting the utilization will not remove the project from the environment. See for more information
Stages: utilization associated with the Project. License Managers can modify the utilization of these Stages just like the Project utilization. Each Project will have 7 utilization stages available.
The tab lists all associated Tenants within the given License Key and Project. License Managers can manage the utilization of all Tenants within the License Key. Expanding the Tenant line item will display all Stages within that Tenant. The same Project and Stage utilization information is available here including IDs and the ability to disable the utilization.
Expired License The License Key associated with the environment has expired. Verify the expiration date of the license within the .
Anytime a server is spun up or a Project is created or accessed in your environment, an outbound ping is sent to the license server, and the utilization is recorded in the License Management UI. Exceeding the allocated utilization can cause license errors, blocking further server deployments and functionality of your Projects/Forms. If this occurs, access the to disable unused utilizations, making licenses available for active servers or projects.
Click the link below to read more
Access the , click the Projects tab
The following showcases the same workflow example detailed in the section, only this time, the errors will be examined from the server log perspective.
