Next Plus Connector toolkit documentation
The toolkit provides API for communication with Next Plus server and the table data interaction, such as insert rows, read rows, update rows, read table, etc.
Supported LabVIEW Versions: 2020 and higher.
Installation
Toolkit is installed via VI Package Manager.
Install location is C:\Program Files (x86)\National Instruments\LabVIEW XXXX\vi.lib\NextPlus, where XXXX – specific LabVIEW version.
Toolkit’s VIs could be found on the Addons palette:
List of API VIs
Initialize Connector.vi.
This VI is used to initialize the toolkit.
Release Connector.vi
This VI is used to deinitialize the toolkit, and release all the initialized resources.
Authorize.vi.
This VI is used to authorize the user to the server using provided credentials, and obtain the token. Token is used internally in the API VIs.
Inputs:
- Username: string input, required parameter. Is used to provide user name to be authorized.
- Password: string input, required parameter. Is used to provide user’s password.
- Server URL: string input, required parameter. Is used to specify URL of the Next Plus server. For example, https://<server>.nextplus.io, where <server> is name of the dedicated server.
- Force login: boolean input, recommended parameter. If TRUE, then previously issued tokens are invalidated. By default, this option is set to FALSE.
Configure.vi.
This VI is used to configure logger and error handling parameters.
Inputs:
- Log Root Folder: path input, recommended parameter. This path specifies root folder for log files/directories. If it is empty, then <User Documents>\Next Plus Connector directory is used.
- Log Level: enum selector, recommended parameter. By default it is “Trace” log level. There are 3 log levels available: Trace, Info, Error.
o Trace: all requests and errors are logged, including full request and response JSON bodies.
o Info: all requests and errors are logged, without request/response JSON bodies.
o Error: only errors are logged.
Trace log level is recommended for debugging and troubleshooting, while for production Info or Error logs are recommended, in order to decrease log file sizes and improve log files readability.
- Display Error Dialog?: boolean input, recommended parameter. If TRUE, then built-in error dialog is used, and in case of error the dialog is shown. If FALSE, error is propagated by error wires, but no built-in error dialog is shown.
Read Tables List.vi.
This VI is used to read list of table names and ids for which authorized user has access to.
Outputs:
- Table Names, string array. List of table names.
- Table Ids, string array. List of table Ids.
This VI could be used to find id of the table, based on its name. There could be created multiple tables with the same name, so Id allows to specify exactly the table of the interest.
Read Table Structure.vi.
This VI is used to get structure of the table, based on table Id.
Inputs:
- Table Id: string input, required parameter. Is used to provide table Id to read its structure.
Outputs:
- Table Structure: array of clusters. Cluster has the following structure:
o Column Name: string. Name of the column.
o Column Id: string. Id of the column.
o Column Type: string. Type of the column. There are the following types available: string, numeric, boolean, datetime.
Insert Row.vi.
This VI is used to write new row to the table.
Inputs:
- Table Id: string input, required parameter. Is used to provide table Id.
- Row data (cluster): variant input, required parameter. It is used as input cluster with data to be written to the table (row).
Note: input cluster should match (at least partially) to the table structure. If it contains some additional fields which are not present in the table or there is type mismatch – error will be thrown.
Read Table.vi.
This VI is used to read the entire table.
Inputs:
- Table Id: string input, required parameter. Is used to provide table Id.
- Row Data Type (array of clusters): variant input, required parameter. Is used to specify rows structure. As table is array of rows, then there is needed to connect array of clusters (where cluster represents table’s row structure).
Outputs:
- Table (array of clusters): variant. This output returns variant which is array of clusters. In order to convert it to array of clusters, additional use of Variant To Data function is needed.
Read Rows.vi.
This VI is used to read all rows from the table, that match the specified filter.
Inputs:
- Table Id: string input, required parameter. Is used to provide table Id.
- Rows Filter: string input, required parameter. Is used to provide filter expression. Please refer to documentation https://loopback.io/doc/en/lb3/Where-filter.html for valid filter formats.
- Row Data Type (array of clusters): variant input, required parameter. Is used to specify rows structure. As filter could return multiple rows, then there is needed to connect array of clusters (where cluster represents table’s row structure).
Outputs:
- Rows (array of clusters): variant. This output returns variant which is array of clusters. In order to convert it to array of clusters, additional use of Variant To Data function is needed.
Update Rows.vi.
This VI is used to read all rows from the table, that match the specified filter.
Inputs:
- Table Id: string input, required parameter. Is used to provide table Id.
- Rows Filter: string input, required parameter. Is used to provide filter expression. Please refer to documentation https://loopback.io/doc/en/lb3/Where-filter.html for valid filter formats.
- Row Data Type (array of clusters): variant input, required parameter. Is used to specify rows structure. As filter could return multiple rows, then there is needed to connect array of clusters (where cluster represents table’s row structure).
Next Plus Connector Error Dialog.vi.
This VI is used to display custom dialog window.
Inputs:
- error in: cluster input, required parameter. If there is error (status flag = TRUE), then dialog is shown. If status flag = FALSE, then no dialog is shown.
- Window Title: string input, recommended parameter. Is used to set window title of the error dialog. By default is empty.
Outputs:
- Error out: cluster output. Note, that input error is propagated via this output. So even if this error dialog is used in the application, proper error handling is needed.
List of errors
Error code | Message | Description/Possible reason |
5001 | Table Id is empty. Please specify Table Id. | - |
5002 | Empty Token. Please use Authorize.vi to obtain the token. | Authorize.vi for some reason failed, so no token has been obtained. |
5003 | Input string is empty/not valid. | Internal error when some of the required strings are empty/not valid (mostly in case of JSON conversion issues). |
5004 | '<table id>' table structure is not found | This error is thrown when there was not found table structure for the specified table id, during validation of rows structure. Could happen if table id is valid Guid, but there is no such table with this id found. |
5005 | Data structure validation failed. '<reason>'. | Error is thrown during rows structure validation (validation of the input cluster). Possible reasons: provided column name is empty/not valid, column name is not found for the table, column name is found but data types are not matched. |
5006 | Not successful authorization. Response from server: <response body> | Error is thrown when authorization request has failed. Reason is usually specified in the response body. |
5007 | Credentials validation failed. Reason: <failure reason> | Error is thrown when there are validation errors for user name and/or password. |
5008 | Table Id '<table id>' is not a Guid. | Table Id must be of globally unique identifier (Guid) formatted value. |
5009 | Rows filter '<filter value>' is not valid! | Error is thrown if rows filter validation has failed due to the following possible reasons: rows filter string is empty/not valid, rows filter string is not of JSON format. |
5010 | Can not deserialize string '<string value>'. | Server’s response is of JSON format, which is then deserialized to the specific cluster structure. Thus if for some reason the response is not valid JSON – this error is thrown. |
5011 | Server URL validation has failed. Reason: <reason> | Error is thrown when server url is empty/not valid string, or when it does not follow url structure. |
Filtering
As it was mentioned before, some VIs use filters to filter the data. Format of the filter could be found by this link https://loopback.io/doc/en/lb3/Where-filter.html.
Filters are expressions with JSON format and the special syntax, described in the details on the above-mentioned link.
Examples of the most commonly used filters could be the following:
Filters all rows in table:
{"where":{"deletedAt":null}}Filters rows where "Total sum" column is equal to 10:
{"where":{"Total sum":10}}Filters rows where "Serial" column equals "123" and "testId" column value equals to "789":
{"where":{"and":[{"Serial":"123"},{"testId":"789"}]}}
Examples
Toolkit comes with 3 examples of how to use the toolkit.
Examples can be found in the following directory: C:\Program Files (x86)\National Instruments\LabVIEW XXXX\examples\NextPlus\Next Plus Connector.
Usage flow is always the following:
Initialize Connector.vi -> Configure.vi -> Authorize.vi -> perform different operations -> Release Connector.vi.
For example:
Additionally, there is used Read Tables List.vi in order to fetch list of table names and ids, and then find table id by its name.
After data read operations, there are used Variant to Data functions (to type cast variant to the specific cluster).
Logging
As it was mentioned before, there are 3 log levels:
- Trace: all requests and errors are logged, including full request and response JSON bodies.
- Info: all requests and errors are logged, without request/response JSON bodies.
- Error: only errors are logged.
Logs are stored in calendar tree folder structure. Which means the following structure:
<Root log folder>\<year>\<month>\<day>. For example, <User Documents>\Next Plus Connector\2023\12\19.
Log file name is in ISO 8601 format (so it is timestamp).
Log files have .csv extension, and csv format with the following columns:
Timestamp: ISO 8601 format string;
Tag: log level;
Source: call stack;
Message: full message string.
Also, log files are rolling, which means that if log file size exceeds 10 MB, new log file is created under the same directory.