OData for ByD Analytics can be used to access the results of ByD analytics queries. In other words you can query and retrieve data and key figures exposed in ByD analytics reports. This includes

• standard data sources and reports,
• data sources and reports created via SAP Cloud Applications Studio,
• custom reports based on standard or custom data sources, created as key user, and
• extension fields added by key user tools or SAP Cloud Applications Studio.

As result, ByD OData for Analytics provides you a highly flexible framework to query, read and analyze ByD business data, well-suited to serve your integration scenario.

Below I will consider ByD OData rather from a business analytics point of view than from a REST point of view.

Further information about REST, the OData-protocol in general and OData specifications can be found at http://www.odata.org or http://docs.oasis-open.org/odata.

Meta Data

The goal is to get all analytics reports that I can access and all meta data (characteristics, key figures, data types, ...) for those reports.

Get OData "containers" for dialog user, or from a business user point of view: get all available work center for the current/logon user.

URL pattern: <your system hostname>/sap/byd/odata

Example: https://my123456.sapbydesign.com/sap/byd/odata

Get OData "entities" for a container, or get all available reports per work center incl. all report meta data like properties (key figures, characteristics), data types, etc..

URL pattern: <your system hostname>/sap/byd/odata/<shortened name of work center>_analytics.svc/$metadata

Example: https://my123456.sapbydesign.com/sap/byd/odata/bpm_businesspartnerdata_analytics.svc/$metadata

Get meta data for a specific entity, or get all meta data for a specific report.

URL pattern: <your system hostname>/sap/byd/odata/<shortened name of work center>_analytics.svc/$metadata?entityset=RP<report ID>QueryResults

Example: https://my123456.sapbydesign.com/sap/byd/odata/cc_home_analytics.svc/$metadata?entityset=RPCRMSLOIB_MQ0001QueryResults

Fetch Report Data

In all further examples I will skip the system host name.

Let me list some simple examples before I go through the OData options step by step.

You can fetch entity data by adding the ByD analytics report ID to your OData URL.

URL pattern: <your system hostname>/sap/byd/odata/<shortened name of work center>_analytics.svc/RP<report ID>QueryResults

Example:/sap/byd/odata/cc_home_analytics.svc/RPCRMSLOIB_MQ0001QueryResults

As result the system returns the first 50 entries of report "Sales Order Volume" (50 entries is the default page size).

Some more examples for ByD standard business partner reports:

Account collaboration data: /sap/byd/odata/bpm_businesspartnerdata_analytics.svc/RPBPCSCARB_Q0001QueryResults

Account contacts data: /sap/byd/odata/bpm_businesspartnerdata_analytics.svc/RPBPCSCONTB_Q0001QueryResults

... or little more sophisticated:

Assume you would like to analyze the consumption of customer contracts. For this scenario you create a joined data source with ByD service confirmation items and customer contract items and a ByD report to list and analyze service confirmation items aggregated by customer contract information.

Assume further the custom report has the report ID ZABCDEF12345678ABCDEF.

Get service confirmations for contract CC1001:

/sap/byd/odata/cc_home_analytics.svc/RPZABCDEF12345678ABCDEFQueryResults?$inlinecount=allpages&$select=FCISL_ACT_QTY_B,FCACCO_IAV_INV_QTY_BU,FCACCO_ITV_REQU_QTY_BU,
FCZ0COUNT,CIBR_CUCO_ID,TIBR_CUCO_ID,CIBR_CUCO_I_ID,TIBR_CUCO_I_ID,CCCCO_DPY_MAINBUYERPTY,
TCCCO_DPY_MAINBUYERPTY,CACCO_ITM_CREATIONDATE,CACCO_ITM_LASTCHANGEDATE
&$filter=CIBR_CUCO_ID eq 'CC1001'

Get service confirmations joined with contract information, filtered by contract ID and contract item last changed date greater than 19th Feb. 2014:

/sap/byd/odata/cc_home_analytics.svc/RPZABCDEF12345678ABCDEFQueryResults?$inlinecount=allpages&$select=FCISL_ACT_QTY_B,FCACCO_IAV_INV_QTY_BU,FCACCO_ITV_REQU_QTY_BU,
FCZ0COUNT,CIBR_CUCO_ID,TIBR_CUCO_ID,CIBR_CUCO_I_ID,TIBR_CUCO_I_ID,
CCCCO_DPY_MAINBUYERPTY,TCCCO_DPY_MAINBUYERPTY,CACCO_ITM_CREATIONDATE,
CACCO_ITM_LASTCHANGEDATE
&$filter=CIBR_CUCO_ID eq 'CC1001' and CACCO_ITM_LASTCHANGEDATE ge datetime'2014-02-19T00:00:00'

Get service confirmations joined with contract information, filtered by contract ID and some extension field of type datetime:

/sap/byd/odata/cc_home_analytics.svc/RPZABCDEF12345678ABCDEFQueryResults?$inlinecount=allpages&$select=FCISL_ACT_QTY_B,FCZ0COUNT,CITM_POST_DT,CITM_CREATED_DT,
CITM_CHANGED_DT,ZY86ABC123_ABC8D1B123
&$filter=CIBR_CUCO_ID eq 'CC1001' and ZY86ABC123_ABC1234567 ge datetime'2014-02-19T00:00:00'

OData Query Options

The ByD OData URL consists of 4 components:

• your system host name,
• a shortened name of the ByD work center,
• a report ID, and
• query options.

URL pattern: https://<your system host name>.com/sap/byd/odata/<shortened name of work center>_analytics.svc/RP<report ID>QueryResults?
<query options>

ByD OData supports the following query options:

• $select
  Expansion: $select=<one or more specified characteristics separated by commas>
• $orderby (ascending)
  Expansion: $orderby=<one or more specified characteristics followed by asc, separated by commas>
• $orderby (descending)
  Expansion: $orderby=<one or more specified characteristics followed by desc, separated by commas>
• $totals
  Expansion: $totals=<one or more specified characteristics separated by commas>
• $filter
  Expansion: $filter=<specified characteristic> eq '<filter value>'
• $top
  Expansion: $top=<specified number>
• $skip
  Expansion: $skip=<specified number>
• $count
• $inlinecount
• $format

Select Option

The select option can be used to choose properties (key figures and characteristics) that shall be returned. Properties are specified using its technical names as provided in the entity meta data (e.g. CACCDOCTYPE for Journal Entry Type ID).

If no select options are specified in the URL, then the system returns all key figures and characteristics of the entity definition (report definition).

Example:

Select multiple characteristics:
&select=CCUSTOMER,TCUSTOMER,CCUCOREF,TCUCOIUUID,CPOSTDATE,CACCDCHUID,CSETOFBKS,CSRCNTHREF,CITM_ID

Please note that key figures are aggregated according the selected characteristics.

Example:

You query sales order items and select the key figures Number of Sales Order Items and Net Value, and the characteristics Product Category:

/sap/byd/odata/cc_home_analytics.svc/RPCRMSLOIB_MQ0001QueryResults?$inlinecount=allpages&$select=FCITEM_COUNT,FCITV_NET_AMT_RC,CIPR_CATCP_N,TIPR_CATCP_N

As result the system returns one entry per product category with aggregated sales order net values and the number of sales order items per product category:                      

The OData interface returns at maximum 50 properties (corresponding to a report with 50 columns).
If an entity has more properties defined, then specifying select options in the OData URL is mandatory. However, in this case I would recommend to copy the report and reduce the number of properties to 50.

Filter Option

Examples:

• Filter by customer ID and set of books ID: $filter=CCUSTOMER eq '1029754' and CSETOFBKS eq '4010'
• Filter by posting date (type date time): $filter=CPOSTDATE ge datetime'2014-01-14T00:00:00'

Report default selections cannot be overwritten with OData based retrieval => I would recommend to copy the report and remove default selections.

Order By Option

The options $orderby=<characteristics name> asc or $orderby=<characteristics name> desc enable you to sort your query result ascending or descending with respect to a specific characteristics.

You can sort by characteristics, but not by key figures.

Example:

Select sales order net values per product category sorted by the product category ID and the product category name (ok, the example sorting doesn't make much sense, but it shows how it works):

/sap/byd/odata/cc_home_analytics.svc/RPCRMSLOIB_MQ0001QueryResults?$inlinecount=allpages&$select=FCITEM_COUNT,FCITV_NET_AMT_RC,CIPR_CATCP_N,TIPR_CATCP_N
&$orderby=CIPR_CATCP_N%20desc,TIPR_CATCP_N%20desc

Top, Skip Option (Paging)

The $top option specifies that only the first n records will be returned.

The $skip option specifies that the result shall not include the first n entities.

Both query options together can be used to process a paging through the server side hit list.

If no paging options are specified, ByD returns the first 50 entries due to default page size = 50.

Example:

Select the 3rd page of 10 entries (skip 20 and return 10), sorted by characteristic CIPY_BUY_CNTCD_N:

/sap/byd/odata/cc_home_analytics.svc/RPCRMSLOIB_MQ0001QueryResults?$inlinecount=allpages&$select=CIPY_BUY_CNTCD_N,FCITEM_COUNT,FCITV_NET_AMT_RC,
CIPY_BUYER_PTY,TIPY_BUYER_PTY,CIPR_CATCP_N,TIPR_CATCP_N
&$orderby=CIPY_BUY_CNTCD_N%20asc&$skip=20&$top=10

Totals Option

Using the totals option you can add entries with totals to the OData result.

Example:

The URL

/sap/byd/odata/cc_home_analytics.svc/RPCRMSLOIB_MQ0001QueryResults?$inlinecount=allpages&$select=CIPY_BUY_CNTCD_N,FCITEM_COUNT,FCITV_NET_AMT_RC,
CIPY_BUYER_PTY,TIPY_BUYER_PTY,CIPR_CATCP_N,TIPR_CATCP_N,
TotaledProperties&totals=CIPY_BUY_CNTCD_N,CIPY_BUYER_PTY,CIPY_BUY_CNTCD_N
&$orderby=CIPY_BUY_CNTCD_N%20asc

results in the additional totals entries (marked orange):

Other Options

Count:
Returns the total number of entries.

Example:

/sap/byd/odata/cc_home_analytics.svc/RPCRMSLOIB_MQ0001QueryResults/$count

Inline Count:

Returns the number of entries included in the query result.

Example:

/sap/byd/odata/cc_home_analytics.svc/RPCRMSLOIB_MQ0001QueryResults?$inlinecount=allpages&$select=FCITEM_COUNT,FCITV_NET_AMT_RC,CIPY_BUYER_PTY,
TIPY_BUYER_PTY,CIPR_CATCP_N,TIPR_CATCP_N,CIPY_BUY_CNTCD_N

Format:

Allows you to specify the result format:

• Atom (default)
• JSON

Example:
/sap/byd/odata/cc_home_analytics.svc/RPCRMSLOIB_MQ0001QueryResults?$inlinecount=allpages&$select=FCITEM_COUNT,FCITV_NET_AMT_RC,CIPY_BUYER_PTY,
TIPY_BUYER_PTY,CIPR_CATCP_N,TIPR_CATCP_N,CIPY_BUY_CNTCD_N&$format=json

Debug:

Example:

/sap/byd/odata/cc_home_analytics.svc/RPCRMSLOIB_MQ0001QueryResults?$select=FCITEM_COUNT,FCITV_NET_AMT_RC,CIPY_BUYER_PTY,TIPY_BUYER_PTY,
CIPR_CATCP_N,TIPR_CATCP_N,CIPY_BUY_CNTCD_N&sap-ds-debug=true

ID Access

Access an entry with a specified ID. IDs are provided in query results.

Example:

/sap/byd/odata/pmm_productdata_analytics.svc/RPSERVICE_Q0002QueryResults
('%7CCCHG_DATE%3D03/06/2015%7CCSERV_INT_ID%3DMCD-ICSP-1000%7C')

URL with special characters

Some OData consumer/browser may require URLs w/o. spaces and some special characters. In this case replace special characters
by the corresponding %-syntax:             

Example:

Readable version: $filter=CIBR_CUCO_ID eq '1001'

with %-Syntax: $filter=CIBR_CUCO_ID%20eq%20%271001%27

Authorization for OData Access

Every ByD user with read access to a work center with a report assigned has access to the corresponding entity via OData as well.

Technical users (e.g. from communication arrangements) cannot be used for OData access.

Steps to create a user with OData for Analytics authorizations:

1. Create a ByD analytics report and assign the report to a ByD work center.
2. Create a ByD employee or service agent (for service agents: request a ByD user).
3. Assign the work center which contains the analytics report to the access rights of the employee or service agent.

The business user might get a specific security policy assigned that prevents password aging and hence necessity to change the password periodically.

If SAML SSO is configured on the tenant, and OData shall be accessed using basic authentication, SAML needs to be explicitly disabled for an OData call.

Example: /sap/byd/odata/srm_supplierbase_analytics.svc/RPBUPSPP_Q0001QueryResults?saml2=disabled

Some Trouble Shooting...

Error message: “Program error in class CL_RSBOLAP_QV_RESULT_SET method : TOO_MANY_DRILL_DOWN_OBJECTS”

=> Report has too many properties; the report must not have more than 50 properties. Reduce the number of requested properties using parameter $select.

Error message: "Ressource für das Segment 'RP<report ID>QueryResults' nicht gefunden"

=> Logon user does not have authorization to access the report.

Error code: http 404

=> IE Version (better use Firefox) or user/password.

Meta data for report not shown, even if report can be used.

=> (Re-)assign report to work center.

Why does the oData service return 50 entries only?

=> 50 entries is the default if the parameter $top is not specified in the oData URL.Use $top, $skip and $inlinecount=allpages to
specify the number of entries to be returned and for paging.

Why does the oData service return less entries than expected, even if I didn't set any filter?

=> Report default selections cannot be overwritten with oData-based retrieval => Copy report w/o default selections.