rest

The connector's rest property defines all REST-specific settings. This includes configuration and authentication settings. These settings are shared by all child objects of crud_objects.

config

The config object specifies basic REST settings.

accept

Optional. Specifies accepted types:

"accept":"application/json"

When not specified, the default is used:

application/json,application/xml

authentication

The authentication method used to access the external system.

Possible values:

certificate
client_credentials
basic_auth
aeries

You can customize authentication-related user input fields in the connection object.

certificate

This option uses a certificate to authenticate with the external system, and produces the following variables:

client_id
tenant_id
certificate <name of the certificate>

For an example, see the Azure AD and Google Workspace connectors.

client credentials

This option uses client credentials to authenticate with the external system, and produces the following variables:

tenant_id
client_id
client_secret

For an example, see the PowerSchool and Skyward Qmlativ connectors.

basic authentication

This option uses basic authentication to authenticate with the external system, and produces the following variables:

user_name
password

For an example, see the BambooHR connector.

baseUrl

The base URL for all REST requests. For example:

https://www.googleapis.com/admin/directory/v1

https://graph.microsoft.com/v1.0/

https://{tenant_id}}

In the last example, the {tenant_id} variable is replaced by the value of the corresponding variable in the connection object.

call_handling

Specifies the basic connector type. Required. Possible values:

azure
google
generic

For all non- Azure AD and non- Google Workspace systems, use generic.

get

Contains additional settings for get calls.

"get": {
	"maxPageCount": 999,
	"query_parameters": {}
},

maxPageCount

The default number of result objects per page. Only used by Azure AD and Google systems, and is overridden if you've specified a separate maxPageCount in the schema object. All generic systems (see call_handling) instead use pagination.

pagination

Optional. Specifies pagination. Only used by generic systems (see call_handling), not by Azure AD or Google Workspace. If not specified, no paging is used.

Two modes are supported: generic and url.

generic

Used to modify the query_parameters of paged get calls. The params object specifies the query parameters. The value of the parameters can contain the {page_number} variable, which is an incrementing number (1,2,3,…) for each page. The params are evaluated for each page.

"pagination": {
	"mode": "generic",
	"path":[],
	"page_size":998,
	"params": {
		"page":"{page_number}",
		"limit":999
	}
}

See the PowerSchool connector for an example.

url

Changes the URL for subsequent pages. With this method, the first page is requested as follows:

get [start of URL]/1/{page_size}

The external system responds with the page information for the next page.

"pagination": {
	"mode": "url",
	"field": "Paging.Next",
	"page_size": 500
}

The field property specifies the path of the response that contains the page info. In this example, the result data contains a Paging object that contains the Next property. The value of this property is added to the URL.

See the Skyward Qmlativ connector for an example.

query_parameters

Optional. Can be specified when all get calls share common query parameters.

"query_parameters": {
	"SchoolYearID": "{school_year_id}",
	"FiscalYearId": "{fiscal_year_id}"
}

The object can contain variables, and typically will.

selector

Optional. Specifies additional query_parameters for get requests, which determine the attributes to be retrieved. Only used by generic systems (see call_handling). Two different modes exist.

mode=objects

The attributes to retrieve are specified as a comma-separated list inside parameter.

"selector": {
	"mode":"objects",
	"parameter":"expansions"
}

mode=array

The attributes to retrieve are specified as separate query parameters. Each attribute has a parameter name and a parameter value.

"selector": {
	"mode": "array",
	"array": "searchFields"
}

The array property specifies the name of the parameter. The parameter name includes the index of the array. The parameter value is the name of the attribute. Example: searchFields[12]=Age

test_connection

For testing the connection with the external system. NIM appends the specified url to baseUrl and executes a REST get call. Success is indicated by a 200 response.

"test_connection": {
	"url": "/ws/v1/district/student/count"
}

authOptions

Caution

This is an advanced topic and not described in detail here. Contact Tools4ever if you need additional information.

These settings are used to authenticate the NIM service against the external system. The authentication options depend on the authentication setting.

The best way to configure these settings in your custom connector is to copy the authOptions of a connector with the same type of authentication, and modify the settings as needed.

In this section:

NIM