Share this page

# OData for developers

You can use OData to extend and improve reporting capabilities, above and beyond the functionality provided by dashboard widgets. OData (Open Data Protocol), is the OASIS REST-based standard for accessing data.

In this topic:

## Using OData overview

This overview describes the use cases for developers to use the OData standard to access data.

OData version 4.0 is supported.

For OData version support, download and install the Microsoft Power Query for Excel add-in.

Caution: Tableau’s support for OData is limited. For example, Tableau's OData support currently does not include the $expand interactive query argument, which is used extensively for cross entity reporting. Consider using a different reporting or business intelligence tool.

Developers can retrieve data over OData in the following ways.

Access method | Steps
--- | ---
Directly, by querying with an API client | Connect to OpenText Software Delivery Management's OData support using basic authentication. For details, see Basic authentication. Access the data. For details, see Access data using OData with a REST client. Use OData resources to work with OpenText Software Delivery Management data. For details, refer to the OData documentation.
By designing applications to integrate with OpenText Software Delivery Management over OData | Connect to OpenText Software Delivery Management's OData support using basic authentication. For details, see Basic authentication. Use OData resources to work with OpenText Software Delivery Management data. Note: Only GET requests are supported when working with OData.

## Prerequisites

- Request that the site admin or space admin activate basic authentication for each space with the SUPPORTS_BASIC_AUTHENTICATION_FOR_ODATA configuration parameter. This enables ODATA integrations to connect using Basic Authentication. For details, see Configuration parameters.

- If OpenText Software Delivery Management is configured for SSO authentication, create API keys for working with OData integration.

## Base URI to access data using OData

The server base URI for accessing data using OData is:

<https://<server> /odata/v4/shared_spaces/<space_ID>/workspaces/<workspace_ID>/

Troubleshooting: If there is no successful response to an OData consumer request, it might be because the base URL used is different than expected. Consider modifying ODATA_USE_SERVER_BASE_URL and SERVER_BASE_URL as described under Set configuration parameters or Configuration parameters.

Tip: You can restrict the expansion depth and control the OData behavior for private, non-selectable fields. For details, see the ODATA_* site parameters in Configuration parameters.

## Access data using OData with a REST client

The section describes how to access data using OData with a REST client.

### Authenticating

To work with OData, review the prerequisites for basic authentication under Prerequisites, and then authenticate with basic authentication.

Caution: Activating basic authentication enables external systems to access OpenText Software Delivery Management using this authentication method, not just OData.

You can authenticate with either:

- Your user name and password.

- An API access key.

For details, see Basic authentication.

Tip: When working with basic authentication, on each successful authentication, the LWSSO_COOKIE_KEY cookie is included in the response. We recommend that you send the LWSSO_COOKIE_KEY cookie with each subsequent OData request for enhanced performance. For details, see the information about the LWSSO_COOKIE_KEY under the topic Authentication.

### Retrieving data

You can use OData to retrieve data, but you cannot update (POST, PUT, DELETE) data. Only GET operations are supported.

By default, a maximum of 1000 items are returned.

Example: To see all defects: `GET <base_URI>/defects`

### Specify an offset within history records - OData (technical preview)

A history log is created when a new item is created or when you click Save after changing item fields. Each history log can contain one or more history records.

You can use OData calls to retrieve an audit of the history through the history_records entity. The OData history_records entity is parsed and derived from the history_log entity.

To enable the fetching of history records, set the EXPAND_HISTORY_RECORDS parameter to true. For details, see Configuration parameters.

When using the $skip option with the history_records entity, you must include two additional parameters: $originalSkip and $innerOffset to indicate which history record and the offset within the record:

- originalSkip. How many history logs to skip.
- innerOffset. How many records to skip within the specified history log.

These parameters are calculated on the server side, and they are automatically added to the "next" link in a response, if a next page exists. Manually changing these parameters in the link, could result in inconsistent data fetching.

Note: The history_records API call is limited to fetching up to 10,000 history logs. If your results exceed this amount, you receive a warning asking you to filter the request. You can filter by time/date, by entity_ID, by user_id, by action, or by entity_type.

The actual number of history records may exceed 10,000, as long as the history logs do not exceed that amount. Each history log contains one or more history records, where all history records for a specific time interval are combined together, but parsed separately.

The following example skips to record 3 within history record 1084:

https://host.name.com/odata/v4/shared_spaces/1001/workspaces/1002/history_records?null&$skip=6000&originalSkip=1083&innerOffset=2

## OData options and operators

You can use OData options and operators to further refine your results.

The following URI conventions are supported.

Area | Supported conventions
--- | ---
Options | $select, $search, $filter, $orderby, $top, $count, $paging, $skip, $format, $expand, $link & $count, and returning the raw value. Note: When using the $skip option with the history_records entity, add two additional parameters: $originalSkip and $innerOffset. For details, see Specify an offset within history records - OData (technical preview).
$filter operators | Logical operators: eq, ne, gt, ge, lt, le, and, or, not, ( ). - Filtering with logical operators on entities that have associations is not always supported. You cannot filter entities involved in associations with a multiplicity of *. To find out whether you can filter an entity with logical operators, check the OData $metadata file to look for the entity's associations. The following OData metadata excerpt demonstrates that runs and releases have an association:
    <Association Name="run_to_release">
     <End Type="OData.Octane.run" Multiplicity="*" Role="run->release"/>
     <End Type="OData.Octane.release" Multiplicity="1" Role="release->run"/>
    </Association>
The release's multiplicity is 1, so you can filter the run entity for a specific release with logical operators. Only one release can be associated with a run. The run's multiplicity is *, so you cannot filter the release entity for a specific run with logical operators. Many runs can be associated with a release.
Functions | String functions: bool substringof, bool endswith, bool startwith

### URI examples

Goal | Method
--- | ---
Return all defects with the selected fields | `/defects?$select=id,name,description`
Return defect 6001 with all its fields | `/defects('6001')`
Return all defects by name in descending order | `/defects?$orderby=name desc`
Return all defects assigned to any sprint | `/defects?$filter=sprint ne null`
Return all suite runs that have linked defects | `/suite_run?$filter=defect_indirect ne null&$expand=defect_indirect`
Return all the defects created after 2017-08-23 | `/defects?$filter=creation_time ge datetimeoffset'2017-08-24T00:00:00Z'`
Return all defects with assigned teams | `/defects?$filter=team ne null`

## See also

- OData support for reporting
- View history (technical preview)

https://admhelp.microfocus.com Software Delivery Management 8942
Tips to improve your search results... OpenText™ Software Delivery Management Help Center OpenText™ Software Delivery Management Help 26.3 All View Local Help Center View Online Help Center Version: