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
custom_post_token

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.

custom_post_token

This option sends a custom POST request to retrieve a token, and then uses that token as a header in REST calls to authenticate with the external system.

When using this option, configure authOptions as follows:

"authOptions": {
	"authUrl": "<url here>",
	"postData": {
		"credentials": {
			"name": "{user_name}",
			"password": "{password}",
			"site": {
				"contentUrl": "{content_url}"
			}
		}
	},
	"directToken": true,
	"tokenPath": "credentials.token",
	"headerName": "X-Tableau-Auth",
	"headerTemplate": "{token}"
}

postData: Customize as necessary to create the POST request. The postData shown above is just an example. If you use variables, define them in the items array of connection.
directToken: Always set to true.
tokenPath: The name of the property in the response JSON containing the token.
headerName: The header to send the retrieved token in (default is Authorization).
headerTemplate: How to send the token in the header. Default is Bearer {token}, but often {token} is used instead.

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.

Three modes are supported: generic, url, and skip_take.

generic

Used to modify paged get calls. The page and pagesize properties defined in the params object are passed into the query_parameters. When calls are made, NIM automatically increments {page_number} for each page.

totalAttribute and totalPageAttribute are optional, and can be used to control how many pages NIM requests. totalAttribute takes the name of the property in the response data which specifies how many total records will be returned. totalPageAttribute takes the name of the property which specifies how many total pages will be returned. If values exist for both properties, totalAttribute is used. If neither property exists, NIM will continue to request pages until a page is returned which contains fewer records than the page_size value.

"pagination": {
	"mode": "generic",
	"totalAttribute": "total_records",
	"totalPageAttribute": "page_count",
	"params":{
		"page":"{page_number}",
		"pagesize":512
	}
}

See the PowerSchool and Zoom connectors for examples.

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.

skip_take

Works almost the same as the generic mode, but alternates between skipping and retrieving records. The skip and take properties defined in the params object are passed into the query_parameters. You must define the {skip_count} and {take_count} variables in the items array of connection. The {take_count} should typically be the same as the defined page_size. When calls are made, NIM automatically increments {skip_count} based on the number of records already retrieved. NIM will continue to request pages until a page is returned which contains fewer records than the page_size value.

"pagination": {
	"mode":"skip_take",
	"page_size": 1000,
	"params": {
		"skip":"{skip_count}",
		"take":"{take_count}"
	}
}

See the HelloID 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