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.
Request paged universes to find desired universe identifier.
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.
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
(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.
Authentication
Logging On
Request
POST https://{{hostURL}}/biprws/logon/long
Request Body:
1<attrs xmlns="http://www.sap.com/rws/bip"> 2 <attr name="userName" type="string">{{username}} </attr> 3 <attr name="password" type="string">{{password}} </attr> 4 <attr name="clientType" type="string">OData</attr> 5 <attr name="auth" type="string" possibilities="secEnterprise,secLDAP,secWinAD,secSAPR3">secEnterprise</attr> 6</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 |
| Zero |
Is Not Null |
| Zero |
Equal To (=) |
| One |
Not Equal To (<>) |
| One |
Less Than (<) |
| One |
Greater Than (>) |
| One |
Less Than or Equal To (<=) |
| One |
Greater Than or Equal To (>=) |
| One |
Like |
| One |
Not Like |
| One |
Except |
| One |
Between |
| Two |
Not Between |
| Two |
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 SQLThe
?character is replaced with the single-character mask of the database in the resulting SQLIf the pattern contains
\?or\*, then?or*are escaped. Strings containing?or*are actually found by the operatorThe
_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 |
In |
| List |
Not In |
| 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 |
| 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). |
| Boolean | Indicates whether the parameter keeps the previous answered values. |
| Boolean | Specifies if the parameter is optional. |
| Boolean | Specifies if the parameter is associated with a list of values. |
Supported Operators:
Operator | operator Attribute Value | Number of Right Operands |
Is Null |
| Zero |
Is Not Null |
| Zero |
Equal To (=) |
| One |
Not Equal To (<>) |
| One |
Less Than (<) |
| One |
Greater Than (>) |
| One |
Less Than or Equal To (<=) |
| One |
Greater Than or Equal To (>=) |
| One |
Like |
| One |
Not Like |
| One |
Except |
| One |
Between |
| Two |
Not Between |
| Two |
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 (=) |
| One |
Not Equal To (<>) |
| One |
Less Than (<) |
| One |
Greater Than (>) |
| One |
Less Than or Equal To (<=) |
| One |
Greater Than or Equal To (>=) |
| 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 |
|
| Specifies if the ranking is ascending ( |
| 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 isfalse. If set totrue, the DateTime and Numeric values are formatted according to the preferred viewing locale set throughX-SAP-PVLin 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-PVLin 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 | Response Description | Response Type |
Request following | Response Description | Response Type |
| The count of records for the specified query flow. |
|
| A row at the |
|
| Information about a specified object from the index specified where |
|
| Returns the raw value of an object specified by the provided parameters |
|
| Query results in chunks starting with the record number specifed by the |
|
| The first |
|
| The first |
|