General Information

ETO BO Rest API allows users to programmatically create ETO Results queries and retrieve the data through an API. This feature replaces previously used Query as a Web Service functionality.

This is an add-on feature, please contact your account manager if you would like to learn more. (accountmanagement@socialsolutions.com)

Before you are able to leverage the Bonterra’s Business Objects API, please make sure to contact your support specialist to get the API URL.

In this documentation, variables will be extracted and replaced by a generic name encompassed in double curly brackets. For example, the host URL will always be referred to as ####{{hostURL}}.

Workflow

Log on. This token is required for all subsequent requests.
Request universe details that will be used to build queries. Note: This is required for the first time a query is built, but on subsequent requests if the structure of your desired query hasn’t changed you may skip to 3. This allows for caching opportunities that may simplify the workflow.
1. Request paged universes to find desired universe identifier.
2. Request universe details for the desired universe to find the dimensions/measures/filters available for queries.
Create a query. Note: Queries are only valid for the session they were created in.
1. Create the base query. This query will define the dimensions/measures you would like data returned from as well as any parameters/filters you would like to define as part of your query. Parameters can allow for complex query filters. For details and examples on how to structure parameters/filters please refer to the SAP Rest API Documentation pages 105-124
2. (Optional) Answer parameters. Note: If parameters are defined within the query they will need to be answered before the query can be run.
Request results from the query through OData feed. Note: The structure and methods for accessing data through an OData feed can vary depending on your use case. For details on the available OData methods and examples of usage please refer to the SAP Rest API Documentation pages 199-211.
For general details on the OData specification please refer to the OData website.
Log off.

Authentication

Logging On

Request

POST https://####{{hostURL}}/biprws/logon/long

Request Body:

<attrs xmlns="http://www.sap.com/rws/bip">    <attr name="userName" type="string">####{{username}} </attr>    <attr name="password" type="string">####{{password}} </attr>    <attr name="clientType" type="string">OData</attr>    <attr name="auth" type="string" possibilities="secEnterprise,secLDAP,secWinAD,secSAPR3">secEnterprise</attr></attrs>

Response

Response body:

1<entry xmlns="http://www.w3.org/2005/Atom "> 2 <author> 3 <name>####{{authorizingHostname}}</name> 4 </author> 5 <title type="text">Logon Result</title> 6 <updated>2022-05-06T02:56:33.108Z</updated> 7 <content type="application/xml"> 8 <attrs xmlns="http://www.sap.com/rws/bip"> 9 <attr name="logonToken" type="string">####{{logonToken}}</attr> 10 </attrs> 11 </content> 12</entry>

The response body will return a “logonToken” that will need to be included in the header of every request that is made as “X-SAP-LogonToken”.

Logging Off

Request

POST https://####{{hostURL}}/biprws/logoff

Request Header:

X-SAP-LogonToken: "####{{X-SAP-LogonToken}}"

Response

Response Status:

200 – Logoff attempt was successful
401 – Unauthorized or invalid logon token

Universe APIs

Query Universes

Description

Gets the list of UNX and UNV universes.

Request

GET https://####{{hostURL}}/biprws/raylight/v1/universes?offset=####{{offset}}&limit=####{{limit}}

Where:

####{{offset}} indicates the position in the list, from which universes are returned. It must be greater than or equal to 0. The default value is 0. This parameter is optional.
####{{limit}} indicates the number of universes that you can list on one page. The range is [1, 50]. The default value is 10. This parameter is optional.

Request Header:

X-SAP-LogonToken: "####{{X-SAP-LogonToken}}"

Response

Response type: application/xml

Response body: Returns the list of the universes from the request with the following elements:

id
cuid
name in the requested locale
type
folderId, which is the ID of the folder that contains the universe
Response body example:

1<universes> 2 <universe> 3 <id>####{{id}}</id> 4 <cuid>####{{cuid}}</cuid> 5 <name>####{{name}}</name> 6 <description>####{{description}}</description> 7 <type>####{{type}}</type> 8 <subType>####{{subtype}}</subType> 9 <folderId>####{{folderId}}</folderId> 10 <revision>####{{revision}}</revision> 11 </universe> 12<universes>

Get Universe Details

Description

Requests the details of a universe referenced by its ID.

Request

GET https://####{{hostURL}}/biprws/raylight/v1/universes/####{{universeId}}?aggregated=####{{aggregated}}

Where:

####{{aggregated}} is an optional, Boolean parameter that indicates if the outline must be aggregated. Default value is false.

Request Header:

X-SAP-LogonToken: "####{{X-SAP-LogonToken}}"

Response

Depending on the ####{{aggregated}} parameter value:

If false, the call returns the master view if granted or the default view if the master view is denied. The default view name is returned in the outline using the ####{{businessViewName}} element. This behavior is the one implemented in the SDK versions prior to 4.1 SP5.
If true, the call returns an aggregated outline containing all folders and objects granted to the user. This outline merges all granted objects from the granted business view and contains all objects properties such as ID, path, and name.

Response type: application/xml or application/json

Response body:

1<universe> 2 <id>####{{universeID}}</id> 3 <cuid>####{{universeCUID}}</cuid> 4 <name>####{{universeName}}</name> 5 <type>####{{universeType}}</type> 6 <folderId>####{{universeFolderID}}</folderId> 7 <maxRowsRetrieved>####{{maxRowsRetrieved}}</maxRowsRetrieved> 8 <maxRetrievalTime>####{{maxRetrievalTime}}</maxRetrievalTime> 9 <outline aggregated="true"> 10 <folder> 11 ... 12 </outline> 13</universe>

Query APIs

Create a Query

Request

POST https://####{{hostURL}}/biprws/sl/v1/queries

Request Header: X-SAP-LogonToken: ####{{X-SAP-LogonToken}}

Request Body:

1<query dataSourceType="####{{dataSourceType}}" dataSourceId="####{{universeId}}" xmlns="http://www.sap.com/rws/sl/universe"> 2 <querySpecification version="1.0"> 3 <queryData> 4 <resultObjects> 5 <resultObject path="####{{roPath}}" id="####{{roId}}"/> 6 </resultObjects> 7 </queryData> 8 </querySpecification> 9</query>

Where

<querySpecification> is the query specification
<queryOptions> is the list of query options
<queryData> is the objects used in the query as result, sort, and filter objects. There needs to be at least one <queryData>.
<filterPart> is an optional filtering component that can help to narrow down your results. Look in the Query Filters section for more information.

Response

Response body:

1<success> 2 <message>The resource of type "Query" with identifier "####{{queryId}}" has been successfully created.</message> 3 <id>####{{queryId}}</id> 4</success>

Query Available Queries

Description:

Requests the list of all query statements available in the instance of the open session.

Request

GET https://####{{hostURL}}/biprws/sl/v1/queries

Request Type: application/xml

Request Header: X-SAP-LogonToken: "####{{X-SAP-LogonToken}}"

Response

Response Type: application/xml

Response body:

1<queries xmlns="http://www.sap.com/rws/sl/universe"> 2 <query dataSourceId="####{{universeId}}" dataSourceType="####{{universeType}}"> 3 <id>####{{queryOneId}}</id> 4 </query> 5 <query dataSourceId="####{{universeId}}" dataSourceType="####{{universeType}}"> 6 <id>####{{queryTwoId}}</id> 7 </query> 8</queries>

Getting the Details of a Query

Description

Returns the query specification of a query statement created in an instance of the open session

Request

GET https://####{{hostURL}}/biprws/sl/v1/queries/####{{queryId}}

Request type: application/xml

Response

Response type: application/xml

Response body:

1<query xmlns="http://www.sap.com/rws/sl/universe" dataSourceId="####{{universeId}}" dataSourceType="unx"> 2 <id>####{{queryId}}</id> 3 <querySpecification version="1.0"> 4 <queryData> 5 <resultObjects> 6 <resultObject id="####{{roId}}" path="####{{roPath}}"/> 7 </resultObjects> 8 <filterPart> 9 <comparisonFilter id="####{{filterId}}" path="####{{pathToObjectBeingFilterd}}" operator="EqualTo"> 10 <parameterOperand> 11 <parameter constrained="true" keepLastValues="false" promptWithLov="false" optional="false"> 12 <question>Enter Record ID</question> 13 </parameter> 14 </parameterOperand> 15 </comparisonFilter> 16 </filterPart> 17 </queryData> 18 </querySpecification> 19</query>

Query Filters

Description

When creating a query, additional query filters can be added to narrow down you query results.

Comparison Filters with Zero, One, or Two Constant Operands

1<filterPart> 2 <comparisonFilter id="string" path="string" operator="string"> 3 <constantOperand searchPattern="Boolean"> 4 <value> 5 <caption type="String|Numeric|Date">

Supported Operators:

Operator

operator Attribute Value

Number of Right Operands

Is Null

IsNull

Zero

Is Not Null

IsNotNull

Zero

Equal To (=)

EqualTo

One

Not Equal To (<>)

NotEqualTo

One

Less Than (<)

LessThan

One

Greater Than (>)

GreaterThan

One

Less Than or Equal To (<=)

LessThanOrEqualTo

One

Greater Than or Equal To (>=)

GreaterThanOrEqualTo

One

Like

One

Not Like

NotLike

One

Except

Except

One

Between

Between

Two

Not Between

NotBetween

Two

Both

Both

Two

Constant Operand

searchPattern is a Boolean argument that specifies how the value of <value>/<caption> or <answerValue> is parsed without know the escape and mask characters of the underlying database. Can only be used with the Like Operator.

If set to true, the value is parsed:

The * character is replaced with the multi-character mask of the database in the resulting SQL
The ? character is replaced with the single-character mask of the database in the resulting SQL
If the pattern contains \? or \*, then ? or * are escaped. Strings containing ? or * are actually found by the operator
The _ and % wildcard characters are escaped

Example: Is Null Operator (No Constant Operand)

1<query dataSourceId="####{{universeId}}" dataSourceType="unx" xmlns="http://www.sap.com/rws/sl/universe"> 2 <querySpecification version="1.0"> 3 <queryData> 4 <resultObjects> 5 <resultObject id="####{{roId}}" path="####{{roPath}}"/> 6 </resultObjects> 7 <filterPart> 8 <comparisonFilter id="####{{roId}}" path="####{{roPath}}" operator="IsNull"/> 9 </filterPart> 10 </queryData> 11 </querySpecification> 12</query>

Example: Equal to Operator (One Constant Operand)

1<query xmlns="http://www.sap.com/rws/sl/universe" id="####{{queryId}}" dataSourceType="####{{universeType}}" dataSourceId="####{{universeId}}"> 2 <querySpecification version="1.0"> 3 <queryOptions> 4 </queryOptions> 5 <queryData> 6 <resultObjects> 7 <resultObject path="####{{roPath}}" id="####{{roId}}"/> 8 </resultObjects> 9 <filterPart> 10 <comparisonFilter operator="EqualTo" path="####{{roPath}}" id="####{{roId}}"> 11 <constantOperand> 12 <value> 13 <caption type="String">####{{comparisonValue}}</caption> 14 </value> 15 </constantOperand> 16 </comparisonFilter> 17 </filterPart> 18 </queryData> 19 </querySpecification> 20</query>

Example: Between Operator (Two Constant Operands)

1<query dataSourceId="####{{universeId}}" dataSourceType="unx" xmlns="http://www.sap.com/rws/sl/universe"> 2 <querySpecification version="1.0"> 3 <queryData> 4 <resultObjects> 5 <resultObject id="####{{roID}}" path="####{{roPath}}"/> 6 </resultObjects> 7 <filterPart> 8 <comparisonFilter id="####{{roId}}" path="####{{roPath}}" operator="Between"> 9 <constantOperand searchPattern="false"> 10 <value> 11 <caption type="Numeric">200</caption> 12 </value> 13 </constantOperand> 14 <constantOperand searchPattern="false"> 15 <value> 16 <caption type="Numeric">700</caption> 17 </value> 18 </constantOperand> 19 </comparisonFilter> 20 </filterPart> 21 </queryData> 22 </querySpecification> 23</query>

Comparison Filters for List of Values Operands

1<filterPart> 2 <comparisonFilter id="string" path="string" operator="string"> 3 <constantOperand> 4 <value> 5 <caption type=""String|Numeric|Date"> 6 <path> 7 <level> 8 <caption type=""String|Numeric|Date">

Supported Operators

Operator

operator Attribute Value

Number of Right Operands

InList

List

Not In

NotInList

List

Example: InList Operator with two cities selected from a list of values

1<filterPart> 2 <comparisonFilter operator="InList" id="####{{roId}}" path="####{{roPath}}"> 3 <constantOperand> 4 <value> 5 <caption type="String">London</caption> 6 </value> 7 <value> 8 <caption type="String">Paris</caption> 9 </value> 10 </constantOperand> 11 </comparisonFilter> 12</filterPart>

Example: InList Operator with one city selected from a hierarchal list of values

1<filterPart> 2 <comparisonFilter operator="InList" id="####{{roId}}" path="####{{roPath}}"> 3 <constantOperand> 4 <value> 5 <caption type="String">London</caption> 6 <path> 7 <level> 8 <caption type="String">England</caption> 9 </level> 10 <level> 11 <caption type="String">London</caption> 12 </level> 13 </path> 14 </value> 15 </constantOperand> 16 </comparisonFilter> 17</filterPart>

Comparison Filters with Parameters

1<filterPart> 2 <comparisonFilter id="string" path="string" operator="string"> 3 <parameterOperand> 4 <parameter constrained="Boolean" keepLastValues="Boolean" optional="Boolean" promptWithLov="Boolean"> 5 <question>

Parameters:

Attribute

Type or Value

Description

constrained

Boolean

Specifies if the user can type a new value for the parameter (false) or if the user must select only the values from the associated list of values (true).

keepLastValues

Boolean

Indicates whether the parameter keeps the previous answered values.

optional

Boolean

Specifies if the parameter is optional.

promptWithLov

Boolean

Specifies if the parameter is associated with a list of values.

Supported Operators:

Operator

operator Attribute Value

Number of Right Operands

Is Null

IsNull

Zero

Is Not Null

IsNotNull

Zero

Equal To (=)

EqualTo

One

Not Equal To (<>)

NotEqualTo

One

Less Than (<)

LessThan

One

Greater Than (>)

GreaterThan

One

Less Than or Equal To (<=)

LessThanOrEqualTo

One

Greater Than or Equal To (>=)

GreaterThanOrEqualTo

One

Like

One

Not Like

NotLike

One

Except

Except

One

Between

Between

Two

Not Between

NotBetween

Two

Both

Both

Two

Example

1<filterPart xmlns="http://www.sap.com/rws/sl/universe"> 2 <comparisonFilter id="####{{roId}}" operator="EqualTo" path="####{{roPath}}"> 3 <parameterOperand> 4 <parameter constrained="true" keepLastValues="true" optional="false" promptWithLov="true"> 5 <question>Enter Order ID</question> 6 </parameter> 7 </parameterOperand> 8 </comparisonFilter> 9</filterPart>

Object Comparison Filters

1<filterPart> 2 <comparisonFilter id="string" path="string" operator="string"> 3 <objectOperand id="string" path="string">

Supported Operators

Operator

operator Attribute Value

Number of Right Operands

Equal To (=)

EqualTo

One

Not Equal To (<>)

NotEqualTo

One

Less Than (<)

LessThan

One

Greater Than (>)

GreaterThan

One

Less Than or Equal To (<=)

LessThanOrEqualTo

One

Greater Than or Equal To (>=)

GreaterThanOrEqualTo

One

Example: EqualTo comparison

1<query xmlns="http://www.sap.com/rws/sl/universe" id="####{{queryId}}" dataSourceType="unx" dataSourceId="####{{universeId}}"> 2 <querySpecification version="1.0"> 3 <queryOptions> 4 ... 5 </queryOptions> 6 <queryData> 7 <resultObjects> 8 <resultObject path="####{{roPath}}" id="####{{roId}}"/> 9 </resultObjects> 10 <filterPart> 11 <comparisonFilter path="####{{roPath}}" operator="EqualTo" id="####{{roId}}"> 12 <objectOperand id="####{{roId}}" path="####{{roPath}}"/> 13 </comparisonFilter> 14 </filterPart> 15 </queryData> 16 </querySpecification> 17</query>

Ranking Filters

1<filterPart> 2 <rankingFilter function="Top|Bottom|topPercent|bottomPercent" level="integer"> 3 <prompt> 4 <dimension id="string" path="string"/> 5 <basedOnMeasure id="string" path="string"/> 6 <rankedByDimensions> 7 <rankedByDimension id="string" path="string"/> 8 <filterPart>

The ranking filter is defined by the following:

A ranking order (ascending or descending)
The question prompted to the end-user if the filter is triggereed by a prompt
The dimension and measure to rank
The additional dimensions used to rank
Any additional custom filter it may contain

Ranking Filter

Attribute

Type or Value

Description

function

Top|Bottom|topPercent|bottomPercent

Specifies if the ranking is ascending (Bottom, bottomPercent) or descending (Top, topPercent)

level

integer

Optional. The number of values to rank and this behavior is specific to UNV universes.

Example: Without Prompt

1<query dataSourceType="unx" dataSourceId="####{{universeId}}" xmlns="http://www.sap.com/rws/sl/universe"> 2 <querySpecification version="1.0"> 3 <queryData> 4 <resultObjects> 5 <resultObject path="####{{roPath1}}" id="####{{roId1}}"/> 6 <resultObject path="####{{roPath2}}" id="####{{roId2}}"/> 7 <resultObject path="####{{roPath3}}" id="####{{roId3}}"/> 8 <resultObject path="####{{roPath4}}" id="####{{roId4}}"/> 9 </resultObjects> 10 <filterPart> 11 <rankingFilter level="3" function="Top"> 12 <dimension path="####{{roPath3}}" id="####{{roId3}}"/> 13 <basedOnMeasure path="####{{roPath4}}" id="####{{roId4}}"/> 14 </rankingFilter> 15 </filterPart> 16 </queryData> 17 </querySpecification> 18</query>

Example: With Additional Dimensions and a Prompt

1<query dataSourceType="####{{universeType}}" dataSourceId="####{{universeId}}" xmlns="http://www.sap.com/rws/sl/universe"> 2 <querySpecification version="1.0"> 3 <queryData> 4 <resultObjects> 5 <resultObject path="####{{roPath1}}" id="####{{roId1}}"/> 6 <resultObject path="####{{roPath2}}" id="####{{roId2}}"/> 7 <resultObject path="####{{roPath3}}" id="####{{roId3}}"/> 8 <resultObject path="####{{roPath4}}" id="####{{roId4}}"/> 9 </resultObjects> 10 <filterPart> 11 <rankingFilter level="3" function="Top"> 12 <prompt>Enter ranking level :</prompt> 13 <dimension path="####{{roPath3}}" id="####{{roId3}}"/> 14 <basedOnMeasure path="####{{roPath4}}" id="####{{roId4}}"/> 15 <rankedByDimensions> 16 <rankedByDimension path="####{{roPath1}}" id="####{{roId1}}"/> 17 <rankedByDimension path="####{{roPath2}}" id="####{{roId2}}"/> 18 </rankedByDimensions> 19 </rankingFilter> 20 </filterPart> 21 </queryData> 22 </querySpecification> 23</query>

Managing Parameters

Get Parameters

Description

Returns the first contexts or parameters to be answered.

Request

GET https://####{{hostURL}}/biprws/sl/v1/queries/####{{queryId}}/parameters?formattedValues=####{{formattedValues}}

Where:

####{{formattedValues}} is an optional, Boolean parameter. Default value is false. If set to true, the DateTime and Numeric values are formatted according to the preferred viewing locale set through X-SAP-PVL in the request.

Response

Response type: application/xml or application/json

Response body:

1<parameters> 2 <parameter optional="false" type="prompt"> 3 <id>0</id> 4 <technicalName>psEnter Record ID</technicalName> 5 <name>Enter Record ID</name> 6 <answer constrained="false" type="Numeric"> 7 <info cardinality="Single" keepLastValues="false" dynamic="false"/> 8 </answer> 9 </parameter> 10</parameters>

Answering Parameters

Description

Responds to contexts and prompts. It also returns additional parameters if found when the first parameters have been responded to. Since the new parameters must also be responded, you must perform an additional call by using as request body the answers to the new parameters, and the answers to the parameters that have triggered the new parameters.

Request

PUT https://####{{hostURL}}/biprws/sl/v1/queries/####{{queryId}}/parameters?formattedValues=####{{formatedValues}}

Where:

####{{formattedValues}} is an optional, Boolean parameter. Default value is false. If set to true, the DateTime and Numeric values are formatted according to the preferred viewing locale set through X-SAP-PVL in the request.

Request Header: X-SAP-LogonToken: "####{{X-SAP-LogonToken}}"

Request body:

1<parameters> 2 <parameter optional="false" type="prompt"> 3 <id>0</id> 4 <technicalName>psEnter Record ID</technicalName> 5 <name>Enter Record ID</name> 6 <answer constrained="false" type="Numeric"> 7 <values> 8 <value>1256</value> 9 </values> 10 </answer> 11 </parameter> 12</parameters>

Response

Response type: application/xml or application/json

Response body:

1<success> 2 <message>The parameters of the resource of type "Query" with identifier "####{{queryId}}" have been answered.</message> 3 <id>####{{queryId}}</id> 4</success>

OData Feed APIs

Accessing the OData Feed

Description:

Returns the available data flows for the specified query.

Request

GET https://####{{hostURL}}/biprws/sl/v1/queries/####{{queryId}}/data.svc

Response

Response type: application/xml or application/json

The response is an Atom feed or a collection of JSON objects.

Response body response type: xml example:

1<service xml:base="http://dev.apridev.info/biprws/sl/v1/queries/####{{queryId}}/data.svc/" xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom"> 2 <workspace> 3 <atom:title>Default</atom:title> 4 <collection href="Flows0"> 5 <atom:title>Flows0</atom:title> 6 </collection> 7 </workspace> 8</service>

Response body response type: JSON example:

1{"d": 2 {"EntitySets": 3 ["Flows0"] 4 } 5}

Getting the OData Flow Content

Description

Returns the data from the specified flow

Request

GET https://####{{hostURL}}/biprws/sl/v1/queries/####{{queryId}}/data.svc/####{{flowName}}

Response

Response type: application/xml or application/json

The data of the flow is represented by an Atom feed or an array of JSON objects.

Response body example:

1<?xml version='1.0' encoding='utf-8'?> 2<feed xmlns="http://www.w3.org/2005/Atom" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xml:base="http://dev.apridev.info/biprws/sl/v1/queries/####{{queryId}}/data.svc/"> 3 <id>http://dev.apridev.info/biprws/sl/v1/queries/####{{queryId}}/data.svc/####{{flowName}}</id> 4 <title type="text">Flows0</title> 5 <updated>2022-05-09T09:01:29.721-04:00</updated> 6 <author> 7 <name/> 8 </author> 9 <link href="####{{flowName}}" rel="self" title="####{{flowName}}"/> 10 <entry> 11 <id>####{{hostUrl}}/sl/v1/queries/####{{queryId}}/data.svc/####{{flowName}}(0)</id> 12 <title type="text">Flows0</title> 13 <updated>2022-05-09T09:01:29.725-04:00</updated> 14 <category term="Flows.Flow0" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/> 15 <link href="####{{flowName}}(0)" rel="edit" title="####{{flowName}}"/> 16 <content type="application/xml"> 17 <m:properties> 18 <d:Id>0</d:Id> 19 <d:RecordId>1256.0</d:RecordId> 20 <d:Email_2423>####{{exampleValue}}</d:Email_2423> 21 </m:properties> 22 </content> 23 </entry> 24</feed>

Different Ways to Specify Desired Data from OData

Request following https://####{{hostURL}}/biprws/sl/v1

Response Description

Response Type

Request following https://####{{hostURL}}/biprws/sl/v1

Response Description

Response Type

/queries/####{{queryId}}/data.svc/####{{flowName}}/$count

The count of records for the specified query flow.

application/text

/queries/####{{queryId}}/data.svc/####{{flowName}}(####{{rowIndex}})

A row at the rowIndex index for the specified query flow where rowIndex is an integer.