License Management

Users with an installation of Form.io within their own Self-Hosted private cloud or on-premise environment will manage the utilization of the Projects within that environment through valid License Key(s). These keys are implemented within the environment variables for the associated deployment and managed by Licensed Manager users.

Accessing License Management

To access and manage the keys, License Managers will log into the SaaS portal at portal.form.io 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.

License Manager UI

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.

API / PDF Server

Clicking the API or PDF 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.

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.

{"version":"9.3.0","schema":"3.3.17","environmentId":"64760b724279d9df47xxxxxx"}

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

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 Deleting a License Utilization for more information

Delete: Removes the server utilization from the License Management UI. This does not disable the functionality of the server within the self-hosted environment.

Projects

The Project 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.

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.

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 Deleting a License Utilization for more information

Stages: Stage 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.

Tenants

The Tenants 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.

Deleting a License Utilization

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.

License Management Troubleshooting

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:

License Server Connectivity Issues

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.

What happens if the Form.io license server connection is lost:

• 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.

Invalid License

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.

• Expired License The License Key associated with the environment has expired. Verify the expiration date of the license within the License Management UI.

What happens if the Form.io license is invalid:

• The server will immediately exit with a 503 error which will remove portal and form functionality.

License Utilization Issues

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 License Management UI to disable unused utilizations, making licenses available for active servers or projects.

Is my Project utilization active?

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

1. Copy your Project ID from the URL endpoint within the browser

1. Access the License Management UI, click the Projects tab

2. Search for the Project ID copied in step 1

3. 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.

1. To disable a Project utilization, click the Status button of an active project within your License scope and click the Save Projects License button

1. With the additional Project allocation available, toggle the Status button for the Project you want to allocate and click the Save Projects Licenses button

Is my API/PDF Server utilization active?

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.

1. Within your environment, input the status endpoint within your browser https://myenvironment.form.io/status

2. Copy the Environment ID found in the log

1. Within your License Management, click the API Server or PDF Server tab

2. Search for the Environment ID and determine whether the server Status is active

1. To free up server allocation, disable an active server by clicking the Status button and then Save API Servers Licenses

2. Click the Status button for the Server you wish to activate and then Save API Servers Licenses

Checking Server Logs

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.

The following showcases the same workflow example detailed in the Is my API/PDF Server Active? section, only this time, the errors will be examined from the server log perspective.

1. Review your server logs and observe any license validation errors

2. Take note of the Environment ID within the validation error

1. Within your License Management, click the API Server or PDF Server tab

2. Search for the Environment ID and determine whether the server Status is active

1. Free up a utilization for an active server by clicking the Status button and then Save API Servers Licenses

2. 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

1. With an additional API Server allocation available, you should be able to restart your Container with success.