Role Applications - Vanilla Success
<main> <article class="userContent"> <div class="blockquote"><div class="blockquote-content"><p class="blockquote-line">This feature requires a "Feature Flag" in the config. If you're on the cloud-hosted version of <strong>Higher Logic Vanilla (Vanilla)</strong>, ask Vanilla Support to add it: <code class="code codeInline" spellcheck="false" tabindex="0">"Feature.roleApplications.Enabled": true;</code></p></div></div><p>Vanilla allows you to configure certain roles so that users can request membership in them through an application form. Community managers then approve or deny the applications from the Dashboard.</p><p>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 to your CSM to configure <strong>Role Applications</strong>.</p><h2 data-id="why-role-applications">Why Role Applications?</h2><p>You might want to configure Role Applications for several reasons. Two examples are: </p><ul><li>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.</li><li>Maybe you have several Categories that require privileged access. You can configure a role that gives members access to the Category and have them apply for the role.</li></ul><h2 data-id="configure-role-applications">Configure Role Applications</h2><p>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 <code class="code codeInline" spellcheck="false" tabindex="0">/api/v2/role-requests/metas</code> endpoints. There is no user interface for configuring Role Applications. Normally you would only do it once per RoleID and never have to touch it again. There are a lot of configuration options. The customization options are listed below.</p><ul><li><strong>Role: </strong>Each role must be configured separately to allow applications. Create the role you want to configure first before enabling applications on it.</li><li><strong>Fields: </strong>You can provide custom fields that the user must fill out in order to apply. Each field can have a <strong>name</strong>, <strong>label</strong>, <strong>description</strong>, and <strong>type of control</strong> (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 <code class="code codeInline" spellcheck="false" tabindex="0">camelCase</code> version of its label.</li><li><strong>Notification:</strong> When users are approved to the role they get sent a notification. You can customize the <strong>name</strong> (subject) and <strong>body</strong> of the notification by passing them as <strong>Attributes</strong> to the endpoint. </li><li><strong>Link</strong>: We provide a module of links to role applications based on what roles the current user already has. You can customize the <strong>name</strong> (link text) and <strong>description</strong> 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.</li><li><strong>NotifyDenied</strong>: 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."</li></ul><p>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.</p><p>So, for example, if you want to create a Role Application for the Moderator role (RoleID 32) you <code class="code codeInline" spellcheck="false" tabindex="0">PUT</code> the following JSON object to <code class="code codeInline" spellcheck="false" tabindex="0">/api/v2/role-requests/metas</code> :</p><pre class="code codeBlock" spellcheck="false" tabindex="0">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": { "name": "Congratulations! You are now a moderator", "body": "With great power comes great responsibility.", "format": "html" }, "notifyDenied": false, } } </pre><p>This PUT will return a JSON representation of the Application Form that will be presented to the user when he/she is applying for the role and the URL to the that Application Form. </p><p>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.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">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": { "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" } ] </pre><h2 data-id="update-role-applications">Update Role Applications</h2><p>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 (<code class="code codeInline" spellcheck="false" tabindex="0">{ "RoleID": 31,...}</code>), the GET response returns an array (<code class="code codeInline" spellcheck="false" tabindex="0">[{ "RoleID": 31, ...}]</code>), you will get an error if you try to PUT an array. </p><h2 data-id="the-role-application-links-module">The Role Application Links Module</h2><p>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 <strong>do not</strong> already have the intended role. In Vanilla's Twig rendering library, a user's roles are not readily available. To do this you test if 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:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">{# 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 %} </pre><p>This will link to the page that will render the <code class="code codeInline" spellcheck="false" tabindex="0">RoleApplicationLinksModule</code> , or in other words, the Form that users can fill in to apply for the intended role.</p> </article> </main>