Design Hub developer guide - plugins¶

Design Hub's functionality can be extended by plugins in several workflows to meet the expectations for different user groups and use-cases. Plugins are generally implemented as NodeJS modules implementing a simple stateless API, connecting to one or more web services or databases.

Table of contents:

Plugin types
Development
Download @chemaxon/dh-utils
API of @chemaxon/dh-utils

Plugin types¶

Realtime plugins

Realtime plugins encapsulate functionality that describe 1 virtual compound in 1 specific area of phys-chem properties, ADMET, commercial availability, literature data, in-silico assay data, structure checks or modeling.

For more information specifically related to realtime plugins, check the Developer guide - real time plugins.

Resolver plugins

A resolver plugin converts a corporate identifier into a chemical structure using a structure database lookup.

For more information specifically related to resolver plugins, check the Developer guide - resolver plugins.

Storage plugins

A storage plugin establishes and maintains a flat database of all virtual compounds in Design Hub. Typically implemented with a SQL database connection, this can be used to support advanced analysis, visualizations, or a backup.

For more information specifically related to storage plugins, check the Developer guide - storage plugins.

Registry plugins

A registry plugin helps lookup the synthesis status and substance ID of a compound by periodically executing searches in a compound registration system or ELN.

For more information specifically related to registry plugins, check the Developer guide - registry plugins.

Import plugins

Import plugins load chemical structures into Design Hub based on user input or automatically, followed by deduplication and processing of records.

For more information specifically related to import plugins, check the Developer guide - import plugins.

Company plugins

A company plugin assists authorizing a user by fetching project and group membership for the user.

For more information specifically related to registry plugins, check the Developer guide - company plugins.

Configuration¶

All plugins are loaded by the automatically during start up of the application. The definition of plugins to load are set in the configuration guide. For more, check the Configuration guide's servicesDirectory section.

Development¶

For the successful development of a plugin, we recommend the following preparation:

an instance of Design Hub available for development purposes, i.e.: the ability to stop and start it, to try different configuration options
familiarity with JavaScript, NodeJS and its module system
good understanding of Promises / async await

We recommend checking these basic introduction materials to get familiar with NodeJS

NodeJS beginner guide, Youtube (78m),
Getting started with NodeJS, Youtube (19m),
Intro to NodeJS, Youtube (48m)
NodeJS module description: https://nodejs.org/api/modules.html
Promise introduction: https://web.dev/articles/promises?hl=en

Utility functions¶

Most Design Hub plugins benefit from a library of commonly used functions. Chemaxon is providing one as an npm package called @chemaxon/dh-utils, including the following functions:

chemical file format conversion using JChem Microservices IO, used whenever a non-Chemaxon backend is involved in the plugin functionality
2D rendering of chemical structures using JChem Microservices IO, used whenever the (realtime) plugin needs to depict molecules
a general purpose HTTP library for REST/JSON, multipart or form-urlencoded requests, with basic or Bearer token authentication
a utility library for processing PDB files

Download `@chemaxon/dh-utils`¶

This utility library is published as a scoped npm package. The @chemaxon scope can be accessed by obtaining a Chemaxon account and setting up an npm registry for the scope to Chemaxon's public package repository. The full list of steps to configure this npm registry is:

login to https://chemaxon.jfrog.io
in the corner menu, choose Set me up
select "npm" as the repository type
choose "npm" as the repository
click on Generate Token & Create instructions
scroll to the bottom to find the Scoped .npmrc example
save the provided text as .npmrc file in your user home, or in the current working folder
replace the scope placeholder with "@chemaxon"

The resulting file should look like the following:

@chemaxon:registry=https://chemaxon.jfrog.io/artifactory/api/npm/npm/
//chemaxon.jfrog.io/artifactory/api/npm/npm/:_authToken=<credentials here>
//chemaxon.jfrog.io/artifactory/api/npm/npm/:email=<email address here>
//chemaxon.jfrog.io/artifactory/api/npm/npm/:always-auth=true

Once completed you can run:

1	`npm install @chemaxon/dh-utils`

The address of the repository changed from hub.chemaxon.com to chemaxon.jfrog.io in 2025 March.

Example usage¶

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

async function calculate(body) {
  const smiles = await dhutils.convert(body.compounds[0].mrvSource, "smiles");
}

API¶

async get(data): String | Buffer | Object

Sends an HTTP GET request using the NodeJS fetch API. For parameters see below at async req.

Returns (a Promise of) the response body depending on encoding specified in the request.

async post(data): String | Buffer | Object

Sends an HTTP POST request using the NodeJS fetch API. For parameters see below at async req.

Returns (a Promise of) the response body depending on encoding specified in the request.

async req(data): String | Buffer | Object

Sends an HTTP request using the NodeJS fetch API. Parameters:

Name	Type	Required	Description
`url`	`URL` or `string`	yes	the HTTP URL to make the request to
`jar`	`CookieJar`	no	See tough-cookie
`formData`	`FormData`	no	See FormData Web API docs
`isMultipartFormData`	`boolean`	no	Some APIs require passing `multipart/form-data` header even if binary data is not present
`json`	`boolean`	no	Shorthand property to sending the body as stringified text with `application/json` headers and parsing the response as JSON as well
`method`	`string`	no	`GET` (default), `POST`, `PUT`, `PATCH`, `DELETE`
`headers`	`Object`	no	Key-value pair of request headers
`body`	any	no	Body/payload of the request
`followRedirect`	`boolean`	no	Follow redirects
`timeout`	`number`	no	Number of milliseconds after which the request is aborted and an error is thrown
`qs`	`Object`	no	Key-value pair of URL encoded query strings (search params) to append to the path of the URL. See URLSearchParams
`auth`	`Object`	no	Allows Basic authentication using Base64 encoded credentials when `username` and `password` is specified. Allows sending Bearer tokens when `bearer` is specified
`auth.username`	`string`	no	Username of basic authentication for base64 encoding
`auth.password`	`string`	no	Password of basic authentication for base64 encoding
`auth.bearer`	`string`	no	Value of bearer token

Returns (a Promise of) the response body depending on encoding specified in the request.

async convert(structure, toFormat): String

Converts the input chemical structure to the specified format using JChem Microservices IO.

Parameters:

structure (string): the chemical structure to convert
toFormat (string): the desired format string. See File Formats.

Note: use of this method requires configuring the following environment variable:

JMS_IO_URL: URL of JChem Microservices IO, e.g.: http://localhost:8070/jwsio/

Returns:

the input chemical structure converted to the desired format.

async convertFile(fileContents, toFormat): Buffer

Converts the input chemical structure file to the specified format using JChem Microservices IO.

Parameters:

fileContents (Buffer | String): the chemical structure file to convert
toFormat (string): the desired format string. See File Formats.

Note: use of this method requires configuring the following environment variable:

JMS_IO_URL: URL of JChem Microservices IO, e.g.: http://localhost:8070/jwsio/

Returns:

the input converted to the desired format.

async batchConvert(structures, toFormat): string[]

Converts the input chemical structure to the specified format using JChem Microservices IO.

Parameters:

structures (string[]): an array of chemical structure to convert
toFormat (string): the desired format string. See File Formats.

Note: use of this method requires configuring the following environment variable:

JMS_IO_URL: URL of JChem Microservices IO, e.g.: http://localhost:8070/jwsio/

Returns:

the input chemical structure array converted to the desired format.

async append(structures, toFormat): string[]

Merges multiple input chemical structure into a single one in the specified format using JChem Microservices IO.

Parameters:

structures (string[]): an array of chemical structures
toFormat (string): the desired format string. See File Formats.

Note: use of this method requires configuring the following environment variable:

JMS_IO_URL: URL of JChem Microservices IO, e.g.: http://localhost:8070/jwsio/

Returns:

the input chemical structure array merge into a single multistructure file.

async clean(structure, dimension, format): string

Rearranges of the atomic coordinates of the input structure.

Parameters:

structure (string): the chemical structure to process
dimension (number): dimension to clean to. Values: 2, 3. Optional. Default: 2.
format (string): the desired format string. See File Formats. Optional. Default: mrv.

Note: use of this method requires configuring the following environment variable:

JMS_STRUCTURE_MANIPULATION_URL: URL of JChem Microservices Structure Manipulation, e.g.: http://localhost:8070/structure-manipulation/

Returns:

the input chemical structure with new atomic coordinates in the desired format.

async getImageURLs(structures, width = 400, height = 260, visualizationSettings?): string[]

Generates data URLs with base64 encoded PNG images of the input chemical structures using Marvin Backend Image Generation Service.

Parameters:

structures (string[]): an array of chemical structure to render as images
width (number): width of the image. Optional. Default: 400.
height (number): height of the image. Optional. Default: 260.
visualizationSettings (VisualizationSettings): configuration options for image rendering.

Note: use of this method requires configuring the following environment variable:

JMS_IO_URL: URL of JChem Microservices IO, e.g.: http://localhost:8070/jwsio/
DH_MARVIN_BIG_SERVICE: URL of Marvin Backend Image Generation Service

Returns:

an array of data URLs with base64 encoded PNG images as strings. For more details see Data URLs.

async getCleanedImageURLs(structures, width = 400, height = 260, visualizationSettings?): string[]

Rearranges the atomic coordinates of the input chemical structures, and then generates data URLs with base64 encoded PNG images using Marvin Backend Image Generation Service.

Parameters:

structures (string[]): an array of chemical structure to render as images
width (number): width of the image. Optional. Default: 400.
height (number): height of the image. Optional. Default: 260.
visualizationSettings (VisualizationSettings): configuration options for image rendering.

Note: use of this method requires configuring the following environment variable:

JMS_IO_URL: URL of JChem Microservices IO, e.g.: http://localhost:8070/jwsio/
JMS_STRUCTURE_MANIPULATION_URL: URL of JChem Microservices Structure Manipulation, e.g.: http://localhost:8070/structure-manipulation/
DH_MARVIN_BIG_SERVICE: URL of Marvin Backend Image Generation Service

Returns:

an array of data URLs with base64 encoded PNG images as strings. For more details see Data URLs.

async PDBUtilities.load(pdbCode): string

Downloads a PDB file with the specified 4 letter code from the Protein Data Bank.

Parameters:

pdbCode (string): the 4 letter code of a PDB file

Returns:

the PDB file

async PDBUtilities.findLigands(pdbCode): string[]

Downloads a PDB file with the specified 4 letter code from the Protein Data Bank and extracts the list of available ligands.

Parameters:

pdbCode (string): the 4 letter code of a PDB file

Returns:

the residue codes of the available ligands in the file as an array of strings.

async PDBUtilities.getResidue(pdbCode, ligandCode): string

Downloads a PDB file with the specified 4 letter code from the Protein Data Bank and extracts a specific ligand.

Parameters:

pdbCode (string): the 4 letter code of a PDB file
ligandCode (string): code of the ligand to extract, e.g.: HEM, A:HEM, or A:HEM350

Returns:

the ligand as a valid minimal PDB file

async PDBUtilities.findLigandsFromFile(pdbFile): string[]

Extracts the list of available ligands from the specified PDB file.

Parameters:

pdbFile (string): the contents of the PDB file

Returns:

the residue codes of the available ligands in the file as an array of strings.

async PDBUtilities.getResidueFromFile(pdbFile, residueCode): string[]

Extracts a specific ligand from the specified PDB file.

Parameters:

pdbFile (string): the contents of the PDB file
ligandCode (string): code of the ligand to extract, e.g.: HEM, A:HEM, or A:HEM350

Returns:

the ligand as a valid minimal PDB file

History of changes¶

v5.0.3

getImageURLs and getCleanedImageURLs methods use Marvin Backend Image Generation Service for image rendering

v4.2.18

with version 4 of dh-utils, the deprecated request dependency is replaced with node-fetch

v3.1.0

added append method

v3.0.1

package renamed from ml-utils to dh-utils

v2.5.0

added convertFile method

v2.4.0

added PDBUtilities.findLigandsFromFile method

v2.2.2

added batchConvert method

v2.1.6

added clean method

v2.0.0

initial version with compatibility to JChem Microservices

To find all available version numbers, use:

npm view @chemaxon/dh-utils versions

Design Hub developer guide - plugins¶

Plugin types¶

Configuration¶

Development¶

Utility functions¶

Download @chemaxon/dh-utils¶

Example usage¶

API¶

History of changes¶

Download `@chemaxon/dh-utils`¶