Configuring the SmartObject OData API

Microsoft Azure Active Directory is now Microsoft Entra ID

Use the SmartObject OData API to interact with SmartObject data and expose that data to developers and third-party tools, such as Microsoft Power BI and Microsoft Excel. Also, build custom reports using SmartObject data, such as workflow statistics and line of business information for which you have SmartObjects.

The product offers the following versions of the OData API:

Version	Capabilities
OData v3	The SmartObject OData v3 API supports a single List method to expose SmartObject data.
OData v4	The SmartObject OData v4 API supports all SmartObject methods to expose and interact with SmartObject data.

See the following resources for more information:

See the Considerations section in this topic for important information about using the OData API.
See Authorization Framework Overview for information on how to control or restrict access to certain application elements (e.g. forms, views, SmartObjects) or categories in your environment.
See SmartObject Authorization for information on how to apply SmartObject authorization on SmartObjects in the categories node.

If you are authenticating with Azure Active Directory (Azure Active Directory), you need to grant consent for the product to access Azure Active Directory by clicking the SETUP Azure Active Directory CONSENT button on the Integration > APIs node. See APIs for more information. You cannot setup Azure Active Directory consent with an Azure Active Directory account that has Multi-Factor Authentication (MFA) enabled. Turn off MFA before granting consent. After granting consent you can turn MFA back on.

Microsoft Azure Active Directory is now Microsoft Entra ID

Enabling 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.

The page shows the configuration options when you enable the OData API. Note that your SmartObject list is, by default, empty.

See the following resources for more information:

See How to: Use the OData Feed with Microsoft Excel for an example of exposing SmartObject data through the SmartObject OData API.
See How to: Use the OData Feed with Microsoft Power BI for an example of exposing SmartObject data through the SmartObject OData API.

OData Configuration

OData version

Select the SmartObject OData API version to use on your system. When you select OData v4, the OData URL changes. The OData URL is the URL used to access SmartObjects via OData. Click on the button to copy the URL onto the clipboard.

OData v3 URL

OData v4 URL

Which SmartObjects?

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

See the Considerations section below for information on system SmartObjects available for the OData API.

Option	Description	Actions
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.
All except these SmartObjects	This option allows you to select specific SmartObjects to remove from the OData API. Choosing this option exposes all SmartObjects not specified here.	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.
All	All SmartObjects that have at least one list method are available through the OData API.

Choose 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. The v3 endpoint is immediately updated, while the v4 endpoint takes 30 seconds to update.

You lose pending changes if you leave the page without clicking Apply Changes.
If you click on the Refresh icon before clicking Apply Changes, a warning appears.
- If you click OK, you lose and pending changes.
- If you click Cancel, the pop-up will close, and nothing will happen.

The system prepends "OData_" to the name if any SmartObjects start with a character other than a letter.

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. If you enable the data limit and the response to the OData request exceeds the record limit, the response includes a next link. Use the next link to retrieve the next set of records.

Authentication

Microsoft Azure Active Directory is now Microsoft Entra ID

The OData API is an IIS-hosted app configured with either Basic authentication (that requires a username and password), or OAuth 2.0 support that requires a valid OAuth token passed in the HTTP request to the server.

For information on using OAuth, see the section Using OAuth instead of Basic Authentication in the topic SmartObject OData API.

For Basic authentication, IIS performs the initial authentication and authorization and then passes the user’s credentials to the server to be reauthenticated.

Some third-party software (for example, PowerBI and Excel) have alternative OAuth implementations and do not work with the standard OAuth mechanism used in the product. In these cases, you can only 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.

OData v3 Considerations

System SmartObjects cannot be published to the SmartObject OData v3 API.
Not all standard OData functions are implemented in the OData API.
For v3, 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 the product. In these cases, you can only use Basic Authentication when connecting the software to the SmartObject OData Services.
What you see in the 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 Management interface to refresh the OData service. You can manually refresh the OData API v3 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 you cannot use: 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, (replace MYSMARTOBJECTNAME with the system name of the SmartObject). Note that the endpoint is based on the SmartObject System Name, not the SmartObject's Display Name. To determine the System Name for a SmartObject, view the SmartObject definition in the Management site, and check the System Name property.
You can use a $filter parameter in the OData URL as defined by the OData standardSmartObject numbers are of the Long type, and the OData standard for passing a long number in the URI calls for including L or l at the end. For example, https://k2.denallix.com/api/odata/v3/Employee?$filter=Salary gt 2147483648L
Enabling the OData API deploys two environment variables 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.
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 that 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.

OData v4 Considerations

Future releases of the OData v4 API will address some of these considerations and changes will be published here.

Some SmartObject methods do not work if the system name of the method is different from the standard method name, for example, a Create method with the name of InsertNewProduct.
If you need to assign an identifier to a method for it to work when using the v3 endpoint, some of those methods do not work with the v4 endpoint. The most likely cause of these methods not working is that the primary key that the SmartObject OData API uses is set incorrectly. You can browse to the SmartObject in Management and, on the API page, set a primary key.
Sometimes returned payloads contain null values. This can happen when you do an update or try to do something on a record that does not exist.
SmartObjects you choose on the API configuration page apply to both v3 and v4 endpoints. We recommend that you keep your existing SmartObjects used with the v3 endpoint, enabled for OData v4.
The OData API supports Execute methods if they do not have input parameters.
The OData API supports System SmartObjects if they do not have input parameters.
Method parameters are not currently supported.
Update works as an upsert (if the record does not exist, a new record is created).
The OData API supports Cross Origin Resource Sharing (CORS). Configure CORS on the Workflow REST API page in Management
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.

See the SmartObject OData API topic for additional developer information.