Premium Libraries

A guide and explanation on the change of distribution for the Premium libraries to use NPM

In an effort to improve the Developer Experience when leveraging Form.io, importing the Premium libraries into applications will leverage the public NPM distribution with the next version of these libraries. The premium libraries will use a license in order to operate within applications.

The Premium Component License does NOT affect the price amount of your current license agreement with Form.io.

Upon upgrading any applications to use the latest released premium libraries, a license must be in place at the time of upgrade. Existing applications with older versions of the premium libraries will NOT be affected. This change only applies to new versions of the premium libraries upon upgrade.

Because of this change, there are a few things that must be done prior to the upgrade of any applications to use the newest versions of the Form.io premium libraries.

Please contact [e-mail] with any questions regarding this upgrade.

What is changing

The premium libraries that are affected are as follows:

1. @formio/premium - The premium components library.

2. @formio/offline-plugin - Enables offline forms and submission support

3. @formio/reporting - The new Reporting UI library.

Previously, including these libraries within an application required a user to be included in the https://pkg.form.io distribution server.

In order to improve the overall developer experience, and to no longer require the maintenance of “accounts” in order to gain access to these libraries, the upcoming releases leverage a new streamlined method of distributing these libraries to be used within applications.

Each of our premium libraries will soon be bundled so they can be publicly distributed via NPM, and simply require a single license in order to use them at runtime in applications. This license will simply be used as follows to “use” any premium module:

import { Formio } from ‘@formio/angular’;

import premium from ‘@formio/premium’; Formio.license = ‘--- YOUR LICENSE –--’;

Formio.use(Premium);

In addition, each of these libraries can now be imported using the standard and common NPM method as shown below.

npm install --save @formio/premium

For yarn:

yarn add @formio/premium

There will no longer be a need to provide the “registry” when installing these modules or maintain / track authentication for this registry.

The following versions will include the new License system:

@formio/premium - versions greater than or equal to 3.x.x (example 3.2.2)

@formio/offline-plugin - versions greater than or equal to 5.x.x (example 5.1.2)

@formio/reporting - versions greater than or equal to 2.x.x (example 2.1.0)

Any versions that are less than these provided versions will still use the https://pkg.form.io system.

Does this change apply to me?

The applications that will be affected by this change are applications built and bundled by customers where the premium components were installed via https://pkg.form.io.

A quick way to determine if action is needed is to look inside the “package.json” file included in an application, and then confirm the presence of “@formio/premium”, “@formio/offline-plugin”, or “@formio/reporting”.

If these libraries are not included in an application, then this change does not apply and no action is required.

The application codebase can also be scanned for the following term: Formio.use

If this is not used anywhere in an application, then this change does not apply and no action is required.

For customers who use Quick Inline Embed or iFrame Embed systems to include forms within applications, this change does not apply and no action is required.

The “Launch” feature within the Form.io Developer Portal contains these libraries already, and any forms that are “Launched” and use the packaged FormView Pro application are not affected by these changes, and no action is required.

When to upgrade

Along with the release of the new NPM deployment system, all of these libraries use the latest version of the Formio.js renderer library. The changes to this renderer version are documented @ https://github.com/formio/formio.js/blob/master/Changelog.md#new-features

Upgrading to the 5.x version of the renderer (Formio/js - formerly formio.js), requires the upgrade to the latest versions of the premium libraries.

Using the 5.x renderer version with “pkg” versioned premium libraries is not supported, nor recommended.

Using the latest “npm” versioned premium libraries with the 4.x (or earlier) formio.js renderer is also not supported nor recommended.

License Requirements

In order to be properly licensed, anyone using the premium libraries will need to provide the following Domains that will be included in the License. Wildcard domains are allowed. Multiple domains can be included in a singular license.

• Enterprise Server Hostname(s) - This is the domain(s) where the formio/enterprise-server Docker containers are hosted within the customer environment. If these containers reside behind a Load Balancer, then the domains that resolve to the Load Balancers will be needed. These are also the same hostnames that are used in applications to point the API’s to the correct endpoints. For example, the following code may be in the application: Formio.setBaseUrl(....) Formio.setProjectUrl(...)

The values passed to these functions are needed in order to provide the Enterprise Server Hostname(s) to the license. A common alias for these urls are also “appUrl” and “apiUrl” within configuration files used by the Form.io libraries. These URLs do not need to be publicly accessible. If the applications that host the premium libraries can communicate to these URLs when connected to any internal networks, then these URLs must be provided and included in the license that Form.io will create and provide.

• Application Hostname(s) - This is the domain(s) that the application(s) is hosted on, which uses the Form.io renderer and Premium Libraries. For example, if End users go to the URL https://app.mysite.com to access an application that uses our Form renderer + Premium libraries, the “mysite.com” hostname is required to be provided for including in the license that Form.io will create and provide.

Examples:

Example 1:

For a SaaS product where every tenant gets their own subdomain:

https://tenanta.mysite.com

https://tenantb.mysite.com

And these applications communicate to a different endpoint as follows:

https://api.mysiteapi.com

A license with the following is required:

endpoints: *.mysiteapi.com hostnames: *.mysite.com

Example 2:

In the case there are many domains for both the application and the deployments:

Applications: www.exampleone.com

www.exampletwo.com

www.examplethree.com

Deployments:

www.eastapi.com

www.westapi.com

A license with the following is required: hostnames: exampleone.com, exampletwo.com, examplethree.com endpoints: eastapi.com, westapi.com

Please contact [e-mail] with any questions regarding this upgrade.