Design Hub developer guide - company support plugins

• NodeJS module API
• Plugin skeleton

Design Hub's company supports plugins are a collection of API endpoints that facilitate integrating the application into an organization's project management, authorization and enterprise resource planning systems. As such it handles concepts other than the rest of the plugin types.

A company plugin is a NodeJS module, stored in a folder set by Design Hub's configuration file (servicesDirectory).

NodeJS module API

Company support plugins are NodeJS modules, denoted by their filename: *.company.js and location in the services directory as configured during installation.

A company support plugin exports the following properties:

Name	Type	Required	Description
name	string	yes	Unique identifier of the plugin, used by Design Hub for identification and internal communication. If multiple plugins use the same identifier, the last one to be loaded overrides the others.
label	string	yes	Human readable name of the plugin, used by Design Hub to display GUI elements related to this plugin.
getProjects	async function	no	Called automatically during initialization and then on a predefined daily schedule to obtain an overall list of projects to be used by the application. Arguments: none Return value: Promise of array of objects. Each object corresponds to a project. The objects in the array should contain name and label attributes for a project. Label will be used on the GUI.
getUserProjects	async function	no	Called automatically during the successful authentication of a user, to obtain project assignments. The function must return a Promise of the results. The results are stored in the application database and used for authorization. Arguments: user (object) A javascript object describing the calling user this includes domain for the current call Return value: Promise of array of objects. Each object corresponds to a project. The objects in the array should contain name and label attributes for a project.
getUserGroups	async function	no	Called automatically during the successful authentication of a user, to obtain group memberships. The function must return a Promise of the results. The results are stored in the application database and used for authorization. Arguments: user (object) A javascript object describing the calling user this includes domain for the current call Return value: Promise of array of string. Each string corresponds to a group's name.
domains	array of strings	yes	List of domains where this plugin may be used, when authentication is enabled in Design Hub. Use * to allow any domain.
onConfigurationChanged	function	no	A callback function that Design Hub calls during initialization and whenever an administrator updates the Secrets of the system. Arguments: config (Object) An object with secrets attribute containing the key-value pairs of secrets from the Admin interface

Plugin Skeleton

skeleton.company.js

//@ts-check
"use strict";

const dhutils = require("@chemaxon/dh-utils");

/**
 * @typedef User
 * @prop {string} userName
 * @prop {TokenSet} [tokenSubset]
 * 
 * @typedef TokenSet
 * @prop {string} [access_token]
 * @prop {string} [token_type]
 * @prop {string} [id_token]
 * @prop {string} [refresh_token]
 * @prop {number} [expires_in]
 * @prop {number} [expires_at]
 * @prop {string} [session_state]
 * @prop {string} [scope]
 * 
 * @typedef GetCompanyContext
 * @prop {string} domain
 *
 * @typedef Project
 * @prop {string} name
 * @prop {string} label
 * 
 * @typedef ConfigurationValues
 * @prop {{[key: string]: string}} secrets
 */


/**
 * Find project membership of user
 * @this {GetCompanyContext}
 * @param {User} user
 * @returns {Promise<Project[]>}
 */
async function getUserProjects(user) {
    if (!user?.tokenSubset?.access_token) {
        console.error("getUserProjects - missing access token for user", user);
        throw new Error("getUserProjects access token not found for user");
    }

  //load projects of user

    return [{
        name: "p1",
        label: "Project 1"
    }];
}

/**
 * Find group/roles of user
 * @this {GetCompanyContext}
 * @param {User} user
 * @returns {Promise<string[]>}
 */
async function getUserGroups(user) {
    if (!user?.tokenSubset?.access_token) {
        console.error("getUserGroups - missing access token for user", user);
        throw new Error("getUserGroups access token not found for user");
    }

    //load groups of user

    return ["USER"];
}


/**
 * Load complete project dictionary
 * @this {GetCompanyContext}
 * @return {Promise<Project[]>}
 */
async function getProjects() {
    return [{
        name: "p1",
        label: "Project 1"
    }];
}


/**
 * Store and use values provided by Admin interface's Secret manager
 * @param {ConfigurationValues} config
 */
function onConfigurationChanged(config) {
  console.log("plugin-name configuration", config.secrets);
}

module.exports = {
    name: "skeleton",
    label: "Skeleton Company",
    getUserProjects: getUserProjects,
    getUserGroups: getUserGroups,
    getProjects: getProjects,
    onConfigurationChanged: onConfigurationChanged,
    domains: ["*"]
};