7. Collaboration Setup¶

The Collaboration feature allows Specification Compliance Manager (SCM) users to create, view, and manage team discussions related to a product and specifications. A free and open-source Internet forum software called Discourse is used for supporting collaboration in SCM. To activate collaboration in the SCM, you need to set up and complete some configurations in both Discourse and the SCM server.

7.1 Discourse Setup¶

To set up and log in to Discourse, complete the following steps.

7.1.1 Notification Email Setup¶

Create a new email ID to use as administrator for configuring login and password during Discourse installation.

Note: Existing email ID that has been previously used for Discourse configuration can also be reused.

The configuration of notification emails can be done using the SMTP services offered by "Google Workspace" or "Office 365."

Note:
For Google Workspace Accounts, you can use App Password instead of the actual password of the email ID for security reasons. To generate an app password for the Google workspace account, follow the steps in the link Sign in with App Passwords.
For Office 365 Accounts, please refer to the Office 365 Tweaks topic in Troubleshoot email on a new Discourse install.

7.1.2 Basic Installation and Setup¶

The hardware specifications and installation instructions can be found at Install Discourse webpage.

7.1.3 Configuring SSL Certificates (if local domain is used)¶

To set up SSL, you need to use a self-signed certificate or an acquired domain name rather than a local domain, otherwise the Discourse app cannot be opened in HTTPS mode. Modify the Discourse's default setting to configure a self-signed certificate. Refer to the Allow SSL / HTTPS for your Discourse Docker setup for instructions on installing a self-signed certificate or custom certificate.

7.1.4 Configuring Single Sign ON (SSO)¶

You can log in to Discourse with Google, Twitter, Facebook, Github or Discord accounts. A Discourse administrator can enable logins through Settings ->Login. To enable Google account login for Discourse, refer to Configure Google Login For Discourse. To enable Microsoft login, you need to use the OpenID authentication mechanism, because Microsoft account login is not a native feature of Discourse. Refer to Discourse OpenID Connect or instructions on installing and setting up the Discourse OpenID Connect plugin. You can also use the OpenID connect plugin to enable Gmail and other logins.

7.1.5 Creating Admin API Key¶

To create admin API key, refer to the link, How to create and configure an API Key. This is needed for all functionalities related to collaboration to work properly in Specification Compliance Manager. This API key will be used in the 7.2.1 Adding Discourse Configuration section as part of Discourse configuration.

Note: It is recommended to provide Global scope to the API key and select All Users for User Level to make sure integration with Specification Compliance Manager is working fine.

7.1.6 Adding Specification Compliance Manager Redirect Route To User API Settings¶

Log in to Discourse with admin credentials.
Go to Settings -> User API
Add https://<specification-compliance-manager-server-domain-name>/collaboration/redirect to "allowed user api auth redirects" section. Use http if HTTPS is not enabled for Specification Compliance Manager server. Replace <specification-compliance-manager-server-domain-name> with actual domain name in the URL.

7.1.7 Installing Discourse Data Explorer Plugin¶

Specification Compliance Manager needs Discourse Data Explorer plugin to fetch data about open threads. Refer to the Discourse Data Explorer link for additional information about the plugin and how to install it.

This plugin needs to be installed in the machine (linux) where Discourse is installed. Make sure to Rebuild Discourse after changing the app.yml file. After installing the plugin, a new query needs to be added to the plugin to complete the plugin setup.

7.1.7.1 Adding a new query¶

Log in to Discourse application with admin credentials.
Go to Settings -> Plugins -> Data Explorer.
Create a new query with the name "SCM_Get_Open_Threads_By_Spec"

Copy the query below and paste it as the input. Save the query.

-- [params]
-- boolean :closed
-- int :user_id
-- int :category_id
-- int :offset
SELECT name as specid, MAX(IsCurrentUserInvolved) as IsCurrentUserInvolved FROM
(Select t.name, 
CASE WHEN p.user_id = :user_id THEN 1 
ELSE 0 END 
IsCurrentUserInvolved
from topic_tags tt 
join tags as t on t.id = tt.tag_id 
JOIN topics as tp on tp.id = tt.topic_id 
JOIN posts p on p.topic_id = tp.id 
JOIN categories as cat on cat.id = tp.category_id 
WHERE tp.closed = :closed 
AND tp.deleted_at IS NULL
AND p.deleted_at IS NULL
AND t.name LIKE 'spid-%' AND cat.id = :category_id
GROUP BY t.name, p.user_id) userresult
GROUP BY name
ORDER BY name OFFSET :offset

Set admin group in Allow groups to access this query.

To test the query syntax, enter random values and run the query. If the query runs successfully without any errors, the syntax is correct.

IMPORTANT: The name of the query should be the same as mentioned above. Providing a different query name prevents the collaboration feature in the SCM from working properly.

7.1.8 Rate Limits Configuration¶

7.1.8.1 Configuring Rate Limits From App¶

Discourse enforces various rate limits. For instance, a user may not be able to create more than 3 topics on the first day after signing up. Discourse admin can customise these settings. To change the default limits, go to Settings -> Rate Limits.

7.1.8.2 Configuring API Rate Limits From Configuration File¶

Specification Compliance Manager (SCM) uses Discourse APIs to integrate with Discourse. Increase the rate limits to a higher value for uninterrupted usage of Collaboration feature from Specification Compliance Manager.

Refer to Available settings for global rate limits and throttling for changing the default values. Make sure a high value is provided for Admin API rate limits and User API rate limits.

The following variables may not be present in the app.yml file by default. Add them with the right value and rebuild the app. A value of 10000 or higher is a good number for rate limits. A lower value can be given for per minute rate limits.

DISCOURSE_MAX_USER_API_REQS_PER_MINUTE
DISCOURSE_MAX_USER_API_REQS_PER_DAY
DISCOURSE_MAX_ADMIN_API_REQS_PER_MINUTE

Note: Configuring the rate limits can be optional. The decision to configure rate limits can be taken based on the number of users using the Specification Compliance Manager application and how frequently they use the collaboration feature.

Make sure to Rebuild Discourse after changing the limits.

7.1.9 Rebuilding Discourse¶

To rebuild the Discourse app, refer to the Edit Discourse Configuration topic of the Install Discourse documentation. It is recommended to make all the required changes to the app.yml before rebuilding Discourse to avoid multiple rebuilds and to save time.

7.1.10 Discourse Versions Supported¶

The Specification Compliance Manager can support 2.9.0-beta10 or higher versions of Discourse but it is currently tested with version 2.9.0.beta10 (Discourse Git Commit: 4b2cc2de1e4abeb9db20e7c8620ff21e52e66d0f)

7.2 Interfacing Discourse With Specification Compliance Manager¶

There are a few settings that must be completed in SCM for the integration of Discourse to be successful.

7.2.1 Adding Discourse Configuration¶

IMPORTANT: The following steps should be done in the machine where the Specification Compliance Manager service is installed

To enable the collaboration feature in Specification Compliance Manager, a configuration file containing Discourse server information needs to be created.

Go to C:\ProgramData\National Instruments\SCM. Create a folder if it doesn't already exist.

Create a json file named settings.json with the following content

{
"collaboration" :{
"platform": "discourse",
"discourse": {
"url": "<full-url-of-the-discourse-site>",
"adminApiKey": "<Admin Api key>",
"adminUserName": "<Username of the admin user>"
}
}
}

From Start menu Open NI SystemLink Server Configuration and click Restart under NI SystemLink Service Manager

Last update: December 2, 2022