Configuring the SmartObject OData API

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.

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:

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 some SmartObjects 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 on 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, the changes will be lost.
• If you click on the Refresh icon before clicking Apply Changes, a warning popup display
  • If you click ok, the changes (addition or removal) will be lost.
  • If you click cancel, the pop up will close and nothing will happen.

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.

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.

Some third-party software (for example PowerBI and Excel) have alternative OAuth implementations and do not work with the standard OAuth mechanism used in K2. In these cases, you will only be able to use Basic Authentication when connecting the software to the SmartObject OData Services.

You can create your own custom Power BI Extension for use with OAuth authentication. See https://www.progress.com/tutorials/odata/connect-to-odata-from-power-bi-using-oauth2-authentication for further information.

• 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
• Multi-Value properties are not returned by the OData endpoint

• Some third-party software (for example PowerBI and Excel) have alternative OAuth implementations and do not work with the standard OAuth mechanism used in K2. In these cases, you will only be able to use Basic Authentication when connecting the software to the SmartObject OData Services.

• What you see in K2 Designer may be different from what you see returned from the OData API. This is because the API uses system names for SmartObjects and properties, not display names
• Use the K2 Management interface to refresh the OData service. You can manually refresh the K2 OData service with the following endpoint: https://[k2_site_name]/api/odata/op/refresh
• 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://[K2Site]/api/odata/v3/MYSMARTOBJECTNAME, (where MYSMARTOBJECTNAME is replaced with the system name of the SmartObject). Note that the endpoint is based the SmartObject System Name, not the SmartObject's Display Name. To determine the System Name for a SmartObject, view the SmartObject definition in the K2 Management site, and check the System Name property.
  
• You can use a $filter parameter in the OData URL as defined by the OData standard. 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

  

• To use the OData feed in Tableau, format the feed as Atom
• You can only use the SmartObject OData Service API environments where AD or AAD is the default identity provider. You cannot use the API in K2 environments that use SQLUM
• Using input parameters in SmartObject list method calls do not work with the SmartObject OData Service API, doing so results in the following error:
  "The SmartObject [SMOName] has [SMOField] as a required parameter. Parameters are not currently supported by SmartObject Services at this time."
  

• SmartObject calls through the OData API Service do not return data which contain an underscore (_) character when using the Equal (Eq) query filter

• When you have a list method that contains files the SmartObject OData API doesn’t return the files in the list but instead provide URLs that you can use to retrieve each file. These URLs use a read method under the same SmartObject to return the file. The read method must have the same property mapped to its input as what is defined as the identifier for the SmartObject. By default, the identifier is the first property declared in the SmartObject, but can also be set on the API page. The file returned won’t work if the read method uses a parameter, or if it requires any other inputs besides the identifier that is mapped. When using more than one read method, the read method containing the identifier must be the first read method in the list of SmartObject methods.