NIM

Custom REST connector development

This section describes how to develop Custom connectors for REST systems, and specifies the NIM REST connector file format.

A REST connector lets NIM connect to any external system that offers a REST API, and make arbitrary calls. It runs on NIM's proprietary REST engine.

Important

The REST connector format is under development and is subject to change.

Last updated: March 14, 2022

Connector file

A NIM REST connector is a single JSON file. The file must be a valid NIM connector file, or NIM will not load any Systems that use it.

After you edit a connector, you must either 1) restart the NIM service or 2) go to Configuration > Connectors, select the relevant System, and then click Reload Connector.

All REST connectors are stored in the following directory:

C:\Program Files\Tools4ever\NIM\sysconfig\rest\systems\

The best way to get started developing a custom REST connector is to copy one of the official connectors in this folder and customize it for your system.

The connector file name (without the .json extension) becomes the System Type in the NIM Studio. The file name is case sensitive.

2022-03-09_12-13-40.png

The connector file does not contain any sensitive information. Credentials are stored in a different location and encrypted.

Architecture

NIM reads and writes to external REST Systems via CRUD calls. Collected data is stored in Data tables in the Vault. To create a custom connector, you must define these calls and data tables for the relevant external system.

In a REST connector file, data tables are defined by child objects of crud_objects in the schema object. Inside each child object are operations and resources objects, in which you define calls and object attributes, respectively. Attributes become columns in the associated NIM data table, and correspond to REST resources. Rows represent object instances.

NIM supports all major REST authentication protocols. See authentication.

URL

Each REST call consists of a REST HTTP verb (get, put, post, patch . . .) and a URL, using the following syntax:

get https://domain_port/base_path/request_path?query

The base_path is the same for all calls to the system and is equal to the value of baseUrl. The request_path varies by call.

Testing

To test a custom REST connector, see REST connector test. We recommend thoroughly testing your connector any time the external system API changes, as well as after a NIM upgrade.

REST vs. PowerShell

Because it's possible to make REST calls in PowerShell, you can potentially build custom REST connectors using either NIM's PowerShell connector format or its REST connector format.

The latter uses a proprietary REST engine that is more resource- and code-efficient. However, the trade-off is that NIM's REST engine is not user-extensible, whereas PowerShell always is. If you choose to develop a custom REST connector and need to implement features that the engine doesn't currently support, you'll have to contact Tools4ever to request the necessary features to the REST engine. Your connector development will then be blocked until Tools4ever can add them.

Due to this trade-off, our currently-recommended best practice is to create source-only connectors using Custom PowerShell connectors. On the other hand, custom connectors which will be used in both source and target contexts should be created using the REST connector format. They tend to involve an overwhelming amount of PowerShell code and thus benefit more from the REST connector format, despite its potential drawbacks. See Sources and targets.

Additionally, if you've created a custom PowerShell connector which is underperforming, you may want to convert it to REST.

Contact Tools4ever for help with custom connector development.