Specifying URLs

The Rest URL for a widget or external application is specified as https://YourServer/ProConAnalyticsAPI/datamodel where datamodel is one of:

• Contracts

• BreakdownItems

• LineItems

• Communications

• CommunicationReviews

• CommunicationLineItems

• Obligations

• CommunicationStories

• Tenders

• ScheduleItems

• TenderReviews

• StageGates

• ProcessingDateTime

Further options can be added to the URL to restrict, filter, sort and limit the data for use before it is used by the widget, regardless of the options selected in the widget configuration. These options are based on the OData 4.0 standard:

http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part2-url-conventions/odata-v4.0-errata02-os-part2-url-conventions-complete.html

These OData options can also be used when specifying the REST URL for use in a third-party solution.

Tip By default, data is returned from deleted contracts/tenders which are in the recycle bin. Include $filter=IsDeleted eq 'No' in your URL to exclude this data.

Return a count of records

You can use $count=true to get the number of records in a collection.

Example:

https://YourServer/ProConAnalyticsApi/Contracts?$count=true

Select specific data to return

The fields included in the data can be restricted to only those specified with $select. This can improve performance.

Warning The $select cannot be used when specifying URLs for widgets on AVEVA Contract Risk Management dashboards.

Example:

https://YourServer/ProConAnalyticsApi/Contracts?$select=ContractName,ContractType,ContractState, AwardValueBase,ProjectDepartmentName

Note Any fields you want to use in the widget configuration as the Group By field or Aggregated Columns must be included.

Filter the returned data

By using $filter in the Rest URL, you can filter the data used in the widget for specific values, e.g. for one or more communication states, or for contracts which have a Not to Exceed value.

See http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part2-url-conventions/odata-v4.0-errata02-os-part2-url-conventions-complete.html#_Toc406398094 for more details about each option.

The options which can be used are:

Examples:

• To return all communications that are Approved, Agreed, Not Agreed or Rejected:

  https://YourServer/ProConAnalyticsApi/Communications?$filter=(CommunicationState ne 'Draft' or CommunicationState ne 'Approved %26 Awaiting Agreement') and DaysTakenToRespond ne null

• To return all open contracts with a Not to Exceed value:

  https://YourServer/ProConAnalyticsApi/Contracts?$filter=ContractType eq 'Standard' and ContractState ne 'Closed' and NotToExceedBase ne null

  Tip You can use the $filter option with the Rest URL to exclude zero values from calculated averages. For example, to exclude zero values for the average DaysToRespond for communications, use $filter=DaystoRespond gt 0. See Specifying URLs for more information.

Sort and limit the returned data

Although table and chart widgets can be configured to limit the data displayed, for example to the top ten records by a particular value, this functionality can only be used in these widgets and only if you have selected a Group By field and any Aggregated Columns.

You can sort the data used by any widget by using the $orderby option in the Rest URL:

• $orderby=ColumnName asc - sorts the data by the values in ColumnName in ascending order.

• $orderby=ColumnName desc - sorts the data by the values in ColumnName in descending order.

You can limit the data used by any widget by using $top=X to return the top X records according to the applied sorting option.

You can also skip the first Y records returned, using $skip=Y. For example, if Y = 10, only records 11 to 20 are returned.

Note Where both $top and $skip are used, $skip is applied before $top.

Examples:

https://YourServer/ProConAnalyticsApi/Contracts?$filter=ContractType eq 'Standard' and ContractState ne 'Closed'&$orderby=AwardValueBase desc&$top=10

https://YourServer/ProConAnalyticsAPI/Communications?$orderby=DaysSinceCreated desc

https://YourServer/ProConAnalyticsAPI/Communications?$filter=CommunicationTemplateAbbreviation eq 'SI'&$orderby=DaysSinceCreated desc