Configuring the SmartObject OData API

You must enable the SmartObject OData API before you can use it. This image shows the configuration options once the API is enabled:

You must enable the SmartObject OData API feature before configuring the SmartObjects for use with the service. Click the Slider to activate the OData API preview.

OData URL

The OData URL is the URL used to access SmartObjects via OData Click on the Copy button to copy the URL onto the clipboard.

Which SmartObjects?

Select which SmartObjects to publish to the OData API by using one of the following options:

K2 System SmartObjects cannot be published to the SmartObject OData API.

Option Description Actions
All All SmartObjects that have at least one list method are available through the OData API.
Selected SmartObjects This option allows you to select someSmartObjects to make available through the OData API.
  • Click on the plus sign at the bottom of the Selected SmartObjects list to add SmartObjects. Select the SmartObjects in the Choose SmartObject page and click on Select.
  • To remove a SmartObject from this list, select that SmartObject and click on the trash icon.
  • Click on the pencil icon to edit a SmartObject.
Not these SmartObjects This option allows you to select specific SmartObjects to remove from the OData API. ALL SmartObjects not specified here are exposed.
  • Click on the plus sign at the bottom of the Not these SmartObjects list to add SmartObjects. Select the SmartObjects in the Choose SmartObject page and click on Select.
  • To remove a SmartObject from this list, select that SmartObject and click on the trash icon.
  • Click on the pencil icon to edit a SmartObject.

Search if you know the name of the SmartObject, or browse to the SmartObject.

Click Select to add a SmartObject to the list.

When adding and removing SmartObjects from the list, you must click the Apply Changes button for the changes to take effect.

  • If you leave the page without clicking Apply Changes, your changes are lost.
  • If you click the Refresh icon before clicking Apply Changes, a warning popup display
    • If you click OK, your changes (addition or removal) are lost.
    • If you click Cancel, the pop up closes and nothing happens.

If any SmartObjects start with a character other than a letter, "OData_" is prepended to the name.

Endpoint Data Limits

The Record Limit defaults to 1000 records. You can turn off or adjust the value of this cap. Configure the record limit to a positive number between 1 and 999,999,999. The request is capped at the maximum number of records and a "next" link is included in the response pointing to the next set of records to retrieve when the data limit is turned on and the maximum number of records is exceeded by an OData request.

K2 saves the settings automatically; however, you must click Refresh Service before the change in settings is active.

Authorization Issues

On the main APIs page, click on the Setup AAD Consent button to enable Azure Active Directory authorization. This only needs to be performed once.

If you see a message saying that Your account does not currently have permissions to make changes to K2 APIs , add yourself to the API Administrators list on the API Authentication and Administrators configuration page. See API Configuration for further details. Once you do this, refresh your browser.

K2 System SmartObjects cannot be published to the SmartObject OData API.

Not all standard OData functions are implemented in the OData API.

The OData API can only expose SmartObjects that have a List method. To change the default list method see the SmartObject Default List topic.

If any SmartObjects start with a character other than a letter, "OData_" is prepended to the name.

The OData API uses prefixes beginning with "OData" and ending with an underscore "_" to avoid collisions and address names that do not meet the OData specification. Do not use these prefixes as SmartObject or Property names. Examples of names that cannot be used: OData_MyName, ODataProperty_MyName, ODataFoo_MyName.

You can specify a SmartObject in the OData URL used by your third party application by adding the name of the SmartObject to the end of the OData URL. For example: https://k2.denallix.com/api/odata/v3/MYSMARTOBJECTNAME, (where MYSMARTOBJECTNAME is replaced with the name of your SmartObject). A filter may also be used. However, SmartObject numbers are of the Long type, and OData standards for passing a long number in the URI must be followed by L or l, therefore use L at the end of the number i.e. https://k2.denallix.com/api/odata/v3/Employee?$filter=Salary gt 2147483648L.

When the OData API is installed, two environment variables are deployed to the Default Environment Library. If an administrator changes the default Environment Library, you will run into errors on the management site, for example:

To avoid the problem, go to the new default Environment Library and fill in the values of these two variables. Copy the values from the original default Environment Library. See Environment Library for more information.

Tableau

To use the OData feed in Tableau, format the feed as Atom.

Permissions

The OData API uses SmartBox SmartObjects to store settings and other information.

The K2_net4 app pool account needs read (Load and Get List) permissions on the PublishedObjects and Settings SmartBox SmartObjects.

The K2 Service account needs read (Load and Get List) permissions on the PublishedObjects and Settings SmartBox SmartObjects.

K2 installs these permissions during installation, but you can use the Management site to change them. If you change the permissions, you could break the service. If you see, for example, an authorization exception on server startup, ensure that the app pool account has the correct permissions.

The K2 Administration account should have a mix of read and write permissions on the PublishedObjects, and Settings SmartBox SmartObjects, as shown below. The user defined as the K2 Administrator account on the Service Accounts Configuration page during installation is granted these permissions. If, after installation, you decide to add another K2 Administration account, then you need to set the same permissions or you may receive authorization errors in the Management site when you try to manage the APIs). In the SmartBox Object - SmartBox Object Security, apply the following permissions:

  • PublishedObjects: Read and Write permissions (Create, Save, Delete, Load, and Get List)
  • Settings: Read and Write permissions (Save, Load, and Get List)
You cannot log in to the SmartObject OData API using Basic Authentication with an Azure Active Directory account that has Multi-Factor Authentication (MFA) enabled.

The OData API is an IIS-hosted app and configured with Basic authentication that requires your Active Directory username and password (or Azure Active Directory if K2 is in the cloud) or OAuth 2.0 support requiring a valid OAuth token to be passed in the HTTP request to the server.

For Basic authentication, IIS performs the initial authentication and authorization and then passes the user’s credentials to the K2 server. At this point the user is authenticated again.

An external user who is not from another AAD tenant will not be able to authenticate to the OData endpoint. Any external user added to the tenant AAD can be authenticated to the OData API only if that external user account is from another AAD. External users with Live accounts can’t login.

Related Topics