Developers
Danger
It is important to note that developing Connectors or Scripts comes with a "Use at Your Own Risk" policy. We would like to emphasize that any such tools, connectors, or scripts that have not been developed directly by Tools4ever are outside the scope of our standard support services. Users are advised to exercise caution and discretion when employing any non-official tools or scripts in conjunction with Tools4ever products.
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: May 20, 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.
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.
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 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 under-performing, you may want to convert it to REST.