You can configure specific Roles so that users can request "membership" to them through an application form. Community managers can view and manage (approve or deny) these applications from the Dashboard.
📝 NOTES
- This feature requires a "Feature Flag" in the config. If you're on the cloud-hosted version of Higher Logic Vanilla (Vanilla), ask Vanilla Support to add it:
"Feature.roleApplications.Enabled": true; - This feature requires configuration via the API that will require services if you do not have developers on staff. This article will give you the information you need to know so that you can understand what information to give Vanilla Support to configure Role Applications.
Why Role Applications?
There are several use-cases for leveraging Role Applications. For example:
- Maybe you have volunteer moderators and you want to have a formal application process to approve them. In this case, you can configure your moderator Role with a questionnaire to fill out. Be careful when giving moderator access to people you don't know. The default moderator Role has some permissions that are not appropriate for untrusted members, so you will most likely want to create a new Role for this purpose.
- Maybe you have several Categories that require privileged access. You can configure a Role that gives members access to the Category and then require users to apply for the Role.
Configure Role Applications
To set up a Role Application, you have to configure information for each Role you want to have applications. This is done via the various /api/v2/role-requests/metas endpoints. There is no user interface for configuring Role Applications. Typically, you would only do it once per RoleID and never need to manage it again.
The available configuration options are listed below.
- Role: Each Role must be configured separately to allow applications. Create the Role you want to configure first before enabling applications on it.
- Fields: You can provide custom fields that the user must fill out in order to apply. Each field can have a name, label, description, and type of control (textbox, text area, and checkbox are currently supported). You can also have some basic validation information such as min length, required, type (number, string, boolean). Because each field is accessible via the API, we recommend you name each field with the
camelCase version of its label. - Notification: When users are approved to a Role they are sent a notification. You can customize the name (subject) and body of the notification by passing them as Attributes to the endpoint.
- Link: We provide a module of links to Role applications based on what Roles the current user already has. You can customize the name (link text) and description for each link. Note that our default view does not output link descriptions, so you would have to do some custom theming to output them. Link properties would pass as Attributes to the Role-requests/metas endpoint.
- NotifyDenied: By default, we do not send a notification to the applicant when they are denied a Role by a moderator. If you wish to notify applicants when their application is rejected, set the attribute "notifiyDenied" to "true."
You only have to provide a Role to set up a customization, although we recommend customizing most of the other options in order to provide the easiest user experience possible.
So, for example, if you want to create a Role Application for the Moderator Role (RoleID 32) you PUT the following JSON object to /api/v2/role-requests/metas :
PUT https://[your-forum-domain]/api/v2/role-requests/metas
{
"roleID": 32,
"type": "application",
"name": "Apply to be a moderator.",
"body": "Fill in the form below.",
"format": "markdown",
"attributesSchema": {
"type": "object",
"properties": {
"license": {
"type": "string",
"description": "Enter your license code."
},
"referral": {
"type": "string",
"description": "Name a moderator who can vouch for you."
},
"notes": {
"type": "string",
"x-control": "textarea"
}
}
},
"attributes": {
"link": {
"name": "Click here to become a moderator"
},
"notification": {
"approved": {
"name": "Congratulations! You are now a moderator",
"body": "With great power comes great responsibility.",
"format": "html"
}
}
"notifyDenied": false
}
}
To retrieve the URL to the Application Form after the Form was made, you can call the API to GET the list of Application Forms you have made.
GET https://[your-forum-domain]/api/v2/role-requests/metas
[
/* ...},*/
{
"roleID": 32,
"type": "application",
"name": "Apply to be a moderator.",
"body": "Fill in the form below.",
"format": "markdown",
"attributesSchema": {
"type": "object",
"properties": {
"license": {
"type": "string",
"description": "Enter your license code."
},
"referral": {
"type": "string",
"description": "Name a moderator who can vouch for you."
},
"notes": {
"type": "string",
"x-control": "textarea"
}
}
},
"attributes": {
"link": {
"name": "Click here to become a moderator"
},
"notification": {
"approved": {
"name": "Congratulations! You are now a moderator",
"body": "With great power comes great responsibility.",
"format": "html"
}
}
},
"dateInserted": "2020-09-10T17:02:51+00:00",
"insertUserID": 1,
"dateUpdated": "2020-09-10T17:02:59+00:00",
"updateUserID": 1,
"url": "https://[your-forum-domain]/requests/role-applications?role=32"
}
]
Update Role Applications
If you need to modify an existing Role Application, use the same PUT method, just explicitly set the RoleID to the Role application you want to update. The best way to get the exact structure you want is to do a GET request for the Role application you want to modify and copy out the JSON object from the response, make your modifications, and send it in a PUT request.
Make sure you get only the object ({ "RoleID": 31,...}), the GET response returns an array ([{ "RoleID": 31, ...}]), you will get an error if you try to PUT an array.
The Role Application Links Module
Once you've configured Role Applications, you will need to link to them somehow. Make sure you add a condition to present the link only to users who do not already have the intended Role. In Vanilla's Twig rendering library, a user's Roles are not readily available. To do this, test whether the current user has permissions to view Discussions in a Category only available to users with the intended Role. In this Twig example CategoryID '21' is only available for users with the RoleID 32:
{# If the Current User cannot view Discussions in a Category 21 (that Role 32 can view). #}
{% if not hasPermission("Vanilla.Discussions.View", 21) %}
{# Give them a message and a link to the role request. #}
<div><a href="{{ url("/requests/role-applications?role=32") }}">Apply here</a></div>
{% endif %}
This will link to the page that will render the RoleApplicationLinksModule , or in other words, the Form that users can fill in to apply for the intended Role.