{"id":13339916,"url":"https://github.com/uPortal-contrib/fbms","last_synced_at":"2025-03-11T15:31:47.921Z","repository":{"id":41886110,"uuid":"132671252","full_name":"uPortal-contrib/fbms","owner":"uPortal-contrib","description":"Form Builder Microservice","archived":false,"fork":false,"pushed_at":"2024-08-08T05:59:43.000Z","size":331,"stargazers_count":3,"open_issues_count":13,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-08-08T07:14:57.278Z","etag":null,"topics":["form-builder","microservice","uportal"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uPortal-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-08T22:19:33.000Z","updated_at":"2023-06-02T05:59:54.000Z","dependencies_parsed_at":"2023-12-22T06:29:23.899Z","dependency_job_id":"959de437-4384-42ab-aa20-359c0b883155","html_url":"https://github.com/uPortal-contrib/fbms","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uPortal-contrib%2Ffbms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uPortal-contrib%2Ffbms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uPortal-contrib%2Ffbms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uPortal-contrib%2Ffbms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uPortal-contrib","download_url":"https://codeload.github.com/uPortal-contrib/fbms/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221233152,"owners_count":16781694,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["form-builder","microservice","uportal"],"created_at":"2024-07-29T19:21:21.714Z","updated_at":"2024-10-23T20:31:56.119Z","avatar_url":"https://github.com/uPortal-contrib.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Form Builder Microservice (FBMS)\n\nThe _Form Builder Microservice_ (FBMS) project is an Apereo uPortal Ecosystem component that adds\nForm Builder capabilities to uPortal.  This Git repo contains the sources for the _back-end_\nelements of this solution;  to use FBMS in uPortal, you must also include its _front-end_ component:\n`form-builder`.  The `form-builder` web component is developed independently at the following\nlocation:  [uPortal-contrib/form-builder][].  Front-end, back-end, and uPortal communicate\nexclusively through REST APIs.\n\nFBMS is developed with the following Java Platform technologies:\n\n  - Spring Boot\n  - Spring Security\n  - spring-data-jpa\n  - Hibernate\n  - Jackson (JSON)\n\n## Running This Project\n\n### Using FBMS in uPortal\n\nFBMS does not need uPortal to run, but can be integrated with uPortal version 5.1 or higher.\n\nIf you are not setting up a released version of FBMS, run the following to create a snapshot WAR file for FBMS:\n\n```shell\n./gradlew clean build install\n```\nNote the version for this snapshot that can be found in `gradle.properties`.\n \nThe remaining steps are ALL completed in your uPortal-start repo.\n\n\n#### Step One:  Bundling FBMS\n\nIn uPortal-start, add an `overlays/fbms/build.gradle` file with the following contents:\n\n```groovy\nimport org.apereo.portal.start.gradle.plugins.GradleImportExportPlugin\n\napply plugin: GradleImportExportPlugin\n\ndependencies {\n    runtime \"org.jasig.portal.fbms:fbms-webapp:${fbmsVersion}@war\"\n    compile configurations.jdbc\n}\n\nwar {\n    archiveName 'fbms.war'\n}\n\n/*\n * Import/Export Support\n */\n\nimport org.apereo.portal.start.shell.PortalShellInvoker\n\ndependencies {\n    impexp configurations.jdbc\n    impexp 'org.springframework.boot:spring-boot-starter-tomcat:2.0.3.RELEASE' // Version should match FBMS\n}\n\ndataInit {\n    /*\n     * Drop (if present) then create the Hibernate-managed schema.\n     */\n    doLast {\n        File serverBase = rootProject.file(rootProject.ext['buildProperties'].getProperty('server.base'))\n        File deployDir = new File (serverBase, \"webapps/${project.name}\")\n\n        ant.setLifecycleLogLevel('INFO')\n        ant.java(fork: true, failonerror: true, dir: rootProject.projectDir, classname: 'org.apereo.portal.fbms.ApereoFbmsApplication') {\n            classpath {\n                pathelement(location: \"${deployDir}/WEB-INF/classes\")\n                pathelement(location: \"${deployDir}/WEB-INF/lib/*\")\n                project.configurations.impexp.files.each {\n                    pathelement(location: it.absolutePath)\n                }\n            }\n            sysproperty(key: 'portal.home', value: project.rootProject.ext['buildProperties'].getProperty('portal.home'))\n            arg(value: '--init')\n            arg(value: '--spring.jpa.hibernate.ddl-auto=create')\n        }\n    }\n    /*\n     * Import database entities located anywhere within the folder\n     * specified by 'implementation.entities.location'.\n     */\n    doLast {\n        File serverBase = rootProject.file(rootProject.ext['buildProperties'].getProperty('server.base'))\n        File deployDir = new File (serverBase, \"webapps/${project.name}\")\n        String implementationEntitiesLocation = PortalShellInvoker.createGroovySafePath(rootProject.ext['buildProperties'].getProperty('implementation.entities.location'))\n\n        ant.setLifecycleLogLevel('INFO')\n        ant.java(fork: true, failonerror: true, dir: rootProject.projectDir, classname: 'org.apereo.portal.fbms.ApereoFbmsApplication') {\n            classpath {\n                pathelement(location: \"${deployDir}/WEB-INF/classes\")\n                pathelement(location: \"${deployDir}/WEB-INF/lib/*\")\n                project.configurations.impexp.files.each {\n                    pathelement(location: it.absolutePath)\n                }\n            }\n            sysproperty(key: 'portal.home', value: project.rootProject.ext['buildProperties'].getProperty('portal.home'))\n            arg(value: '--import')\n            arg(value: \"${implementationEntitiesLocation}/fbms\")\n        }\n    }\n}\n```\n\nAdd the following to `gradle.properties` file \n```groovy\nfbmsVersion=\u003cversion\u003e\n```\nReplace `\u003cversion\u003e` with the version (number) of FBMS you want to use.\n\nAdd the following to `settings.gradle` file\n```groovy\ninclude 'overlays:fbms'\n```\n\n#### Step Two:  Bundling `form-builder`\n\nAdd the following to `overlays/resource-server/build.gradle` (inside the\n`dependencies {}` section):\n\n```\nruntime \"org.webjars.npm:uportal__form-builder:${formBuilderVersion}@jar\"\n```\n\nAdd the following to `gradle.properties` (under `# Versions of WebJars included with\nresource-server`):\n\n```\nformBuilderVersion=\u003cversion\u003e\n```\nReplace `\u003cversion\u003e` with the version (number) of `form-builder` you want to use.\nSee https://mvnrepository.com/artifact/org.webjars.npm/uportal__form-builder\n\n#### Step Three:  Initialize FBMS Database Tables\n\nForm definition JSON files should be copied into a new directory under `data/quickstart/` (or your specific dataset)\nnamed `fbms`. For example:\n```shell\nmkdir data/quickstart/fbms\ncp \u003cfbms_repo_dir\u003e/docs/examples/*.json data/quickstart/fbms/\n```\n\nThen, run one of the following to initialize the FBMS data.\n\nTo initialize _just_ the FBMS tables and data, run:\n```shell\n./gradlew :overlays:fbms:dataInit\n```\nOr, if you want to re-initialize all uPortal, portlet and FBMS data:\n```shell\n./gradlew dataInit\n```\n#### Step Four:  Publishing a Form with FBMS\n\nUse a SimpleContentPortlet to publish the following HTML markup as a portlet:\n\n```html\n\u003cscript src=\"/resource-server/webjars/uportal__form-builder/build/static/js/form-builder.js\"\u003e\u003c/script\u003e\n\u003cform-builder\n  fbms-base-url=\"/fbms\"\n  fbms-form-fname=\"\u003cform.fname\u003e\"\n  oidc-url=\"/uPortal/api/v5-1/userinfo\"\u003e\n\u003c/form-builder\u003e\n```\n\nReplace `\u003cform.fname\u003e` with the `fname` of your form (in FBMS). The form's `fname` can be found in its definition file.\nThese were the files added to `data/quickstart/fbms/`.\n\n### Final Step: Provide uPortal's Signature Key to FBMS\n\nFinally, we need to provide the signature key that uPortal uses to sign the user's JWT for authentication.\nThis is usually found in uPortal-start's `etc/portal/uPortal.properties` or may have been moved to `global.properties`\nin the same directory. It may be commented out to use the default, but the default entry should be there:\n```properties\norg.apereo.portal.soffit.jwt.signatureKey=CHANGEMEBx0myZ/pv/e7+xrdDLYGC1iIzSa6Uw5CPpH0KCCS1deESk3v+b+LYMz1ks57tjFb9vudpSCyRKXO5TeEBc45rfMyGtkRa1zri+hukZIAfgrvCbFixpCBxBusRs+uhXRuLxOe6k77VE+EMM4jVJArtNBgVPyV7iOC05kHNiYIGgs=\n```\nAgain, this is the default. Your uPortal-start may have a different value.\n\n1. Copy this into `etc/portal/fbms.properties`.\n2. Copy this file into your $PORTAL_HOME directory, usually in uPortal-start at `./gradle/tomcat/portal/`\n3. Restart Tomcat\n\nThis Completes the uPortal Setup Instructions\n\n---------------------------\n\n### Running FBMS with `bootRun`\n\nIt is sometimes helpful to run FBMS without uPortal for development purposes.  Use the Spring\nBoot Gradle Plugin to launch this project from a local clone of FBMS (this repository).\n\n#### Pre-Requisite: Database Setup\n\nBefore using FBMS stand-alone, the database will need to be configured and a driver added as a dependency.\n\n1. The drive should be added to `fbms-webapp/build.gradle` at the end of the dependency section. There already exists\na comment and example for HSQL. You may add any other database driver as needed as a `runtime` dependency.\n\n2. `fbms-webapp/src/main/resources/fbms.properties` should be edited to include database connection configuration.\nOther values may also require adjusting based on your needs.\n#### Starting FBMS Stand-Alone\n\n```console\n$ ./gradlew fbms-webapp:bootRun\n```\n#### Import/Export Features\n\nApereo FBMS provides support for importing and exporting data from the console.  These features are\ntremendously useful for provisioning new environments and migrating data.\n\n##### Initializing the Database Schema\n\nUse the following command to drop (if necessary) and create the Hibernate-managed database tables:\n\n```bash\n$ ./gradlew assemble fbms-webapp:bootRunDataInit\n```\n\n##### Importing\n\nUse the following command to import all Form objects serialized into JSON files that are located in\nthe `docs/examples` directory:\n\n```bash\n$ ./gradlew assemble fbms-webapp:bootRunDataImport\n```\n\n**NOTE:** The location of this directory is very likely to change or (even more likely) become a\nparameter in the future.  Check this document for changes.\n\n## Configuration\n\n:note: FBMS supports the standard uPortal convention for external configuration based on\n`$PORTAL_HOME`.  Use `global.properties` for settings that are shared between modules.  Use\n`fbms.properties` for settings that are exclusive to this module, or to override a setting defined\nin `global.properties`.\n\n### CORS Support\n\nBrowser-based clients for this microservice will often need to run on a different host or port.  In\nthese cases, support for CORS is required.\n\nUse the `org.apereo.portal.fbms.api.cors.origins` application property to specify allowed origins\nfor CORS requests.  The default value of this property is `http://localhost:8080`.\n\n#### CORS Example\n\n```\norg.apereo.portal.fbms.api.cors.origins=http://localhost:8080\n```\n\n### Permissions\n\nTypically authenticated users have permission to read any form, as well as create, read, and update\ntheir own responses to forms.  (In the future FBMS may support *updating* responses both by\noverwriting an existing response and submitting a new response.)\n\nAs far as managing forms themselves, there are three types of access:\n\n  - `createAuthority`\n  - `updateAuthority`\n  - `deleteAuthority`\n\nThe `createAuthority` allows you to create new forms, whereas `updateAuthority` and `deleteAuthority`\napply to any form that has been previously created.\n\nThe default value for each of these authorities is `Portal Administrators`, which corresponds to the\ngroup of the same name in uPortal.\n\n#### Permissions Example\n\nUse the following properties to assign these permissions to one or more different portal groups:\n\n```\norg.apereo.portal.fbms.security.createAuthority=Portal Administrators, Forms Authors\norg.apereo.portal.fbms.security.updateAuthority=Portal Administrators, Forms Editors\norg.apereo.portal.fbms.security.deleteAuthority=Portal Administrators\n```\n\n## API Documentation\n\nFBMS provides API documentation based on [Swagger][].  You can access the Swagger client at\n`http[s]://hostname[:port]/swagger-ui.html`.\n\n[uPortal-contrib/form-builder]: https://github.com/uPortal-contrib/form-builder\n[Swagger]: https://swagger.io/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FuPortal-contrib%2Ffbms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FuPortal-contrib%2Ffbms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FuPortal-contrib%2Ffbms/lists"}