Installation and Configuration

Deploy and configure the Form Portal module.

Prerequisites

Before installing the Form Portal:

  1. Ambience kernel installed and configured
  2. Form module installed
  3. Workflow module installed (for workflow forms)
  4. ETL-core module installed
  5. MongoDB database accessible

Installation

Deploy Module Package

  1. Extract the module package: bash cp -r elx-form-portal-<version> $AMBIENCE_HOME/modules/form-portal

  2. Verify module structure: bash ls $AMBIENCE_HOME/modules/form-portal # Should show: lib/ web/

Configure Ambience

Add the form-portal module to ambience.conf:

ambience {
  modules = [
    # ... other modules
    "form-portal"
  ]
}

Module Configuration

Add Form Portal configuration to ambience.conf:

ambience {
  form-portal {
    # Number of days before forms are archived
    archive-after-days = 90
  }
}

Restart Server

Restart the Ambience server to load the module:

# Stop Ambience
$AMBIENCE_HOME/bin/stop.sh

# Start Ambience
$AMBIENCE_HOME/bin/start.sh

Verify Installation

  1. Check server logs for successful initialization: bash tail -f $AMBIENCE_HOME/logs/ambience.log # Look for: "Form Portal module initialized"

  2. Access the Form Portal: https://your-server/form-portal/index.html

  3. Verify no errors in browser console

Configuration Options

Archive Settings

Configure when forms are automatically archived:

ambience.form-portal {
  archive-after-days = 90  # Archive after 90 days
}
Option Type Default Description
archive-after-days Integer 90 Days after submission before archiving

Examples:

Development (quick archival for testing):

ambience.form-portal.archive-after-days = 7

Production (long retention):

ambience.form-portal.archive-after-days = 365

Database Configuration

The Form Portal uses MongoDB collections configured by the Form and Workflow modules. No additional database configuration is required.

Collections Used: - forms - Form definitions (from Form module) - checklists - Checklist definitions (from Form module) - formResults - Submitted form data (from Form module) - workflowInstances - Workflow instances (from Workflow module)

Logging Configuration

Configure logging in logback.xml:

<!-- Form Portal logging -->
<logger name="ambience.formportal" level="INFO"/>

Log Levels: - ERROR - Errors only - WARN - Warnings and errors - INFO - Normal operation (recommended) - DEBUG - Detailed debugging

Debug Mode:

<logger name="ambience.formportal" level="DEBUG"/>

Database Setup

MongoDB Indexes

Ensure proper indexes exist for optimal performance:

Forms Collection:

db.forms.createIndex({ "owner": 1 })
db.forms.createIndex({ "access.roles": 1 })
db.forms.createIndex({ "enabled": 1 })
db.forms.createIndex({ "name": 1 })
db.forms.createIndex({ "lastModified": -1 })

Form Results Collection:

db.formResults.createIndex({ "userId": 1, "submitted": 1 })
db.formResults.createIndex({ "formId": 1 })
db.formResults.createIndex({ "submittedDate": -1 })

Workflow Instances Collection:

db.workflowInstances.createIndex({ "userId": 1 })
db.workflowInstances.createIndex({ "workflowId": 1 })
db.workflowInstances.createIndex({ "state": 1 })

Database Maintenance

Regular Tasks: - Monitor collection sizes - Review index usage - Optimize queries - Plan for growth

Backup Strategy: - Regular MongoDB backups - Include all collections - Test restore procedures - Document backup schedule

Access Control Setup

Privileges

Create the required privileges in Ambience:

// Basic portal access
Privilege("mod-form-portal", "Access to Form Portal")

// Form features
Privilege("mod-form", "Access to forms")

// Checklist features (optional)
Privilege("mod-checklist", "Access to checklists")

Granting Access to Users

Grant privileges to users or roles:

// Grant to individual user
user.addPrivilege("mod-form-portal")
user.addPrivilege("mod-form")

// Grant to role
role.addPrivilege("mod-form-portal")
role.addPrivilege("mod-form")

Role Configuration

Users need to be assigned to roles to see forms:

// Add user to role
user.addRole(roleId)

// Roles are configured in form definitions
// via access.roles field

Workgroup Configuration

For multi-tenancy, configure workgroups:

// Add user to workgroup
user.addWorkgroup(workgroupId)

// Forms are filtered by workgroup
// Users only see forms in their workgroups

Integration Configuration

Form Module Integration

Ensure Form module is properly configured:

ambience.form {
  # Form module configuration
  # See Form module documentation
}

The Form Portal depends on: - Form definitions being accessible - Form runtime being configured - Form submission processing working

Workflow Module Integration

For workflow forms, ensure Workflow module is configured:

ambience.workflow {
  # Workflow module configuration
  # See Workflow module documentation
}

The Form Portal requires: - Workflow definitions accessible - Workflow API functional - ETL integration working

ETL Configuration

The Form Portal uses ETL steps for form creation:

Required ETL Steps: - form.NewFormInstance - Create form with workflow - form.NewChecklistInstance - Create checklist

Ensure these steps are available in your ETL configuration.

Caching

Consider caching for: - Form definitions (cached by Form module) - Role information - Workgroup data

Monitoring

Log Monitoring

Monitor logs for: - Module initialization - Form creation events - Access control decisions - Errors and exceptions

Key Log Patterns:

INFO  ambience.formportal - Form Portal initialized
ERROR ambience.formportal - Failed to create form instance
WARN  ambience.formportal - User lacks permission

Troubleshooting

Users Can’t Access

Check: 1. User has mod-form-portal privilege 2. User has mod-form or mod-checklist privilege 3. User assigned to roles 4. User in workgroups

Solutions: - Grant required privileges - Assign to roles - Add to workgroups

Forms Not Appearing

Check: 1. Forms enabled in Form Designer 2. Forms have access.roles configured 3. Forms in user’s workgroups 4. Forms not marked internal

Solutions: - Enable forms - Configure access roles - Match workgroups - Set internal = false

Form Creation Fails

Check: 1. ETL steps available 2. Workflow exists (for workflow forms) 3. Server logs for errors 4. User permissions

Solutions: - Verify ETL configuration - Check workflow enabled - Review error messages - Grant permissions

Operational Checklist

Daily

  • [ ] Monitor server logs
  • [ ] Check error rates
  • [ ] Verify user access issues resolved

Weekly

  • [ ] Review form creation/submission metrics
  • [ ] Check database performance
  • [ ] Monitor disk usage

Monthly

  • [ ] Review user roles and access
  • [ ] Audit form permissions
  • [ ] Check archival process
  • [ ] Review and optimize indexes
  • [ ] Backup verification

Quarterly

  • [ ] Update documentation
  • [ ] Plan capacity increases
  • [ ] Review security configurations
  • [ ] Update form templates

Next Steps: - Access Control - Configure permissions - REST API - API integration - Administration - Overview of admin tasks

Next: Access Control