Forms multitenancy

Overview

Forms now supports multi-tenancy, allowing for the segregation of access between different organizations (tenants) within the product. This feature ensures that organizations can manage their forms independently, enhancing security and privacy. This document outlines how to utilize multi-tenancy in Forms, including navigating to the builder for specific organizations and performing back-end operations in a multi-tenant mode.

Implementation Details

The implementation of multi-tenancy in Forms is based on Aidbox's standard for Organization-based hierarchical access control. This approach allows for a structured and secure method to manage access across different levels of the organization hierarchy.

Enabling Multi-Tenancy

To enable multi-tenancy for Forms, it is necessary to enable Organization-based hierarchical access control for the entire Aidbox environment. Detailed instructions on how to enable this feature can be found here: How to Enable Hierarchical Access Control.

Getting Started

Accessing Forms UI for an Organization

1. Automatic Rerouting:
   • If a user is attached to any organization, they will be automatically rerouted to the organization-based route.
2. Standard Forms UI Access:
   • Typically, to access the Forms UI, the URL fragment path used is #/.
   • Note: The organization dropdown selector will be shown if multitenancy is enabled.
3. Organization-Specific Forms UI Access:
   • To navigate to the Forms UI for a specific organization, modify the URL as follows: #/org/[organization-id]/. Replace [organization-id] with the actual ID of the Organization resource.

Performing Back-End Operations in Multi-Tenant Mode

1. Standard Back-End Call

A standard back-end operation to populate a link within a Questionnaire might look like this:

[base]/fhir/Questionnaire/[questionnaire-id]/$populatelink

[base]/Questionnaire/[questionnaire-id]/$populatelink

2. Multi-Tenant Back-End Call

In multi-tenant mode, the call is modified to include the organization context:

[base]/Organization/[organization-id]/fhir/Questionnaire/[questionnaire-id]/$populatelink
[base]/Organization/[organization-id]/aidbox/Questionnaire/[questionnaire-id]/$populatelink

[base]/Organization/[organization-id]/aidbox/Questionnaire/[questionnaire-id]/$populatelink

Replace [organization-id] and [questionnaire-id] with the respective Organization and Questionnaire resource IDs.

Important Considerations

Data Isolation

• Organization-Specific Data:
  • Each organization's data is isolated. This means that one organization cannot access the data of another organization, ensuring privacy and security.

URL Modification

• Accessing Organization-Specific Features:
  • Remember to modify URLs appropriately to access organization-specific features or perform back-end operations in a multi-tenant context.

Troubleshooting

Common Issues

• Incorrect Organization ID:
  • Ensure that the organization ID in the URL is correct. An incorrect ID can lead to access issues or errors.
• Access Denied:
  • If you encounter an "Access Denied" error, verify that you have the necessary permissions to access the organization's resources.

FAQs

Q: How does multi-tenancy affect data privacy? A: Multi-tenancy enhances data privacy by isolating each organization's data, ensuring that only authorized users within an organization can access its information.

Q: Can I prepopulate a questionnaire with resources from other organizations? A: Yes, but only if those organizations are subsidiaries of the current one and/or if the resource has a shared mode.

Multitenancy in Form UI

Multitenancy in Formbox allows organizations to manage forms and responses independently within the same instance. When multitenancy is enabled, each user operates within the context of a selected organization, ensuring proper data isolation and controlled access to shared content.

To use multitenancy, you need to:

1. Enable the multitenancy feature in your instance settings.
2. Create or import organizations into the instance.

Once these steps are completed, the organization selector becomes available in the Form UI.

Organization Selector

When multitenancy is enabled, users can switch between organizations using the Organization Selector.

If a user belongs to a specific organization, the selector is hidden. The UI automatically resolves the organization context from the user's metadata.

When an organization is selected:

• All pages show only the data related to that organization.
• Both Questionnaires (forms) and QuestionnaireResponses (responses) are filtered accordingly.

Form Templates

The Form Template page provides several actions, depending on the user's current organization and the form’s ownership.

1. Create a Form

Users can create a new form under the currently selected organization.

If no organization is selected, the form is created at the root level. Root-level forms are not owned by a specific organization and can be shared globally with all organizations in the system by using the Share globally button.

2. Delete a Form

Users can delete forms only if the form belongs to the currently selected organization.

3. Share a Form

A form can be shared either with child organizations of the current one or from the root with all organizations (globally).
Once shared, child organizations can view and use the form.

4. Duplicate a Form

Users can duplicate:

• Their own forms
• Forms shared with them by a parent organization or from the root

Duplicating a shared form creates a local copy under the selected organization, allowing independent editing.

Restrictions

Multitenancy introduces several rules to ensure proper isolation and hierarchy behavior.

1. Sharing Limitations

• Forms owned by an organization can be shared only with its child organizations.
• Sharing with sibling organizations is not allowed.
• Root-level forms can be shared globally with all organizations by using the Share globally action.
• The global sharing mode is available only for root-level forms.

2. Editing Permissions

• Users cannot edit or delete forms shared from the root or owned by another organization.
• To modify a shared form, the user must duplicate it under the selected organization.

3. Root-Level Forms

• If a form is created when no organization is selected, it becomes a root-level form.
• If shared globally, a root-level form becomes visible for all organizations.

Sharing Badges

The forms grid shows badges that indicate the user's relationship to a form:

• Shared — shown to the owner organization when the form is shared with child organizations. The owner can manage child-sharing settings.
• Provided — shown to child organizations for forms shared by a parent organization. Child organizations can use the form but cannot change the parent organization's sharing settings.
• Global — the form is a root-level form shared globally with all organizations in the system.

For globally shared root-level forms, organizations can use the form, but they do not own it.

Responses

On the Response page, users can see only the responses related to the currently selected organization.

When a user submits a form, the resulting QuestionnaireResponse is associated with the organization selected in the current context. Later, this response is visible only within that organization context.

Submitted responses cannot be shared between organizations. Even if multiple organizations use the same shared or globally shared form, each organization creates and sees only its own QuestionnaireResponse resources. On the Response page, users can see only the responses related to the currently selected organization.

When a user submits a form, the resulting QuestionnaireResponse is associated with the organization selected in the current context. Later, this response is visible only within that organization context.

Sharing is available for form templates (Questionnaire resources), but not for submitted responses. Even if multiple organizations use the same shared or globally shared form, each organization creates and sees only its own QuestionnaireResponse resources.

Form Gallery

When importing a form from the Form Gallery, the imported form is automatically added under the currently selected organization.
This ensures consistent ownership and makes the form manageable according to the multitenancy rules.