The Form Builder Microservice (FBMS) project is an Apereo uPortal Ecosystem component that adds Form Builder capabilities to uPortal. This Git repo contains the sources for the back-end elements of this solution; to use FBMS in uPortal, you must also include its front-end component: form-builder. The form-builder web component is developed independently at the following location: uPortal-contrib/form-builder. Front-end, back-end, and uPortal communicate exclusively through REST APIs.

FBMS is developed with the following Java Platform technologies:

• Spring Boot
• Spring Security
• spring-data-jpa
• Hibernate
• Jackson (JSON)

FBMS does not need uPortal to run, but can be integrated with uPortal version 5.1 or higher.

In uPortal-start, add an overlays/fbms/build.gradle file with the following contents:

import org.apereo.portal.start.gradle.plugins.GradleImportExportPlugin

apply plugin: GradleImportExportPlugin

dependencies {
    runtime "org.jasig.portal.fbms:fbms-webapp:${fbmsVersion}@war"
    compile configurations.jdbc
}

war {
    archiveName 'fbms.war'
}

/*
 * Import/Export Support
 */

import org.apereo.portal.start.shell.PortalShellInvoker

dependencies {
    impexp configurations.jdbc
    impexp 'org.springframework.boot:spring-boot-starter-tomcat:2.0.3.RELEASE' // Version should match FBMS
}

dataInit {
    /*
     * Drop (if present) then create the Hibernate-managed schema.
     */
    doLast {
        File serverBase = rootProject.file(rootProject.ext['buildProperties'].getProperty('server.base'))
        File deployDir = new File (serverBase, "webapps/${project.name}")

        ant.setLifecycleLogLevel('INFO')
        ant.java(fork: true, failonerror: true, dir: rootProject.projectDir, classname: 'org.apereo.portal.fbms.ApereoFbmsApplication') {
            classpath {
                pathelement(location: "${deployDir}/WEB-INF/classes")
                pathelement(location: "${deployDir}/WEB-INF/lib/*")
                project.configurations.impexp.files.each {
                    pathelement(location: it.absolutePath)
                }
            }
            sysproperty(key: 'portal.home', value: project.rootProject.ext['buildProperties'].getProperty('portal.home'))
            arg(value: '--init')
            arg(value: '--spring.jpa.hibernate.ddl-auto=create')
        }
    }
    /*
     * Import database entities located anywhere within the folder
     * specified by 'implementation.entities.location'.
     */
    doLast {
        File serverBase = rootProject.file(rootProject.ext['buildProperties'].getProperty('server.base'))
        File deployDir = new File (serverBase, "webapps/${project.name}")
        String implementationEntitiesLocation = PortalShellInvoker.createGroovySafePath(rootProject.ext['buildProperties'].getProperty('implementation.entities.location'))

        ant.setLifecycleLogLevel('INFO')
        ant.java(fork: true, failonerror: true, dir: rootProject.projectDir, classname: 'org.apereo.portal.fbms.ApereoFbmsApplication') {
            classpath {
                pathelement(location: "${deployDir}/WEB-INF/classes")
                pathelement(location: "${deployDir}/WEB-INF/lib/*")
                project.configurations.impexp.files.each {
                    pathelement(location: it.absolutePath)
                }
            }
            sysproperty(key: 'portal.home', value: project.rootProject.ext['buildProperties'].getProperty('portal.home'))
            arg(value: '--import')
            arg(value: "${implementationEntitiesLocation}/fbms")
        }
    }
}

Also add include 'overlays:fbms' to your settings.gradle file.

In uPortal-start, add the following to overlays/resource-server/build.gradle (inside the dependencies {} section):

runtime "org.webjars.npm:uportal__form-builder:${formBuilderVersion}@jar"

In uPortal-start, add the following to gradle.properties (under # Versions of WebJars included with resource-server):

formBuilderVersion=<version>

Replace <version> with the version (number) of form-builder you want to use.

Use a SimpleContentPortlet to publish the following HTML markup as a portlet:

<script src="/fbms/webjars/uportal__form-builder/0.1.2/build/static/js/form-builder.js"></script>
<form-builder
  fbms-base-url="/fbms"
  fbms-form-fname="<form.fname>"
  oidc-url="/uPortal/api/v5-1/userinfo">
</form-builder>

Replace <form.fname> with the fname of your form (in FBMS).

It is sometimes helpful to run FBMS without uPortal for development purposes. Use the Spring Boot Gradle Plugin to launch this project from a local clone of FBMS (this repository).

$ ./gradlew fbms-webapp:bootRun

:note: FBMS supports the standard uPortal convention for external configuration based on $PORTAL_HOME. Use global.properties for settings that are shared between modules. Use fbms.properties for settings that are exclusive to this module, or to override a setting defined in global.properties.

Browser-based clients for this microservice will often need to run on a different host or port. In these cases, support for CORS is required.

Use the org.apereo.portal.fbms.api.cors.origins application property to specify allowed origins for CORS requests. The default value of this property is http://localhost:8080.

org.apereo.portal.fbms.api.cors.origins=http://localhost:8080

Typically authenticated users have permission to read any form, as well as create, read, and update their own responses to forms. (In the future FBMS may support updating responses both by overwriting an existing response and submitting a new response.)

As far as managing forms themselves, there are three types of access:

• createAuthority
• updateAuthority
• deleteAuthority

The createAuthority allows you to create new forms, whereas updateAuthority and deleteAuthority apply to any form that has been previously created.

The default value for each of these authorities is Portal Administrators, which corresponds to the group of the same name in uPortal.

Use the following properties to assign these permissions to one or more different portal groups:

org.apereo.portal.fbms.security.createAuthority=Portal Administrators, Forms Authors
org.apereo.portal.fbms.security.updateAuthority=Portal Administrators, Forms Editors
org.apereo.portal.fbms.security.deleteAuthority=Portal Administrators

Apereo FBMS provides support for importing and exporting data from the console. These features are tremendously useful for provisioning new environments and migrating data.

Use the following command to drop (if necessary) and create the Hibernate-managed database tables:

$ ./gradlew assemble fbms-webapp:bootRunDataInit

Use the following command to import all Form objects serialized into JSON files that are located in the docs/examples directory:

$ ./gradlew assemble fbms-webapp:bootRunDataImport

NOTE: The location of this directory is very likely to change or (even more likely) become a parameter in the future. Check this document for changes.

FBMS provides API documentation based on Swagger. You can access the Swagger client at http[s]://hostname[:port]/swagger-ui.html.