Connecting to Oracle BI Publisher (extractor)

The Celonis Oracle BI Publisher extractor lets you bring data from your Oracle BI Publisher instances into the Celonis Platform for process mining and analysis. It supports the following basic features:

Note

Reports are extracted via the Oracle BI publisher SOAP API (Simple Object Access Protocol API). For more information, see: SOAP methods used by the extractor.

Prerequisites

This section details important prerequisites or prerequisite knowledge for using this extractor.

Oracle BI Publisher authentication methods

The Oracle BI Publisher extractor uses basic authentication. To connect to your instance, you need to provide a username and password.

Note

Ensure the user credentials provided have adequate permissions to extract the desired data. For more information, see Oracle BI Publisher user permissions.

Oracle BI Publisher user permissions

You need access to an Oracle BI Publisher user with the following permissions enabled:

Create and edit Data Model
Access to the tables that should be extracted
Create and Download Report
Access to SOAP service

Allowlisting Celonis Platform IPs and domains

If your Coupa instance is only reachable within a certain IP range, you need to allowlist the outbound IPs of the Celonis Platform, otherwise data cannot be extracted. The IPs of the Celonis Platform are different depending on the cluster (eu-1 or us-1).

For more information, see: Allowlisting Celonis domain names, IP addresses, and third-party domains

SOAP methods used by the extractor

The extraction of reports via the Oracle BI publisher is done via the SOAP API (Simple Object Access Protocol API). The following SOAP methods are used by this extractor:

getReportDefinitionReturn - Used to retrieve report's name and for connectivity check.
getXDOSchemaReturn - Used to retrieve report's metadata.
runReportReturn - Used to extract report's data.

Report configuration and further information

When configuring your reports in Oracle BI Publisher, the following applies:

Format: To extract a report it has to be saved in XML format. This can be done in Oracle via Edit Report > View a list > Output Format: Data (XML) > Default Format: Data (XML) > Save.
Maximum size: 524288000 bytes. To support this, you can create parameters for your reports and then filter the data based on that parameter. We recommend creating a date parameter, ensuring that only data from a defined date range is included (and not all data since the report started running).

For further information about using Oracle BI Publisher, see: Oracle.com - Oracle BI Publisher Overview and Best Practices and Docs.Oracle.com

Configuring the Oracle BI Publisher extractor

This section describes the basic setup of configuring the Oracle BI Publisher extractor. To configure the extractor:

From your data pool diagram, select Data Connections.
Select Add Data Connection and select Connect to Data Source.
Select Cloud - Oracle BI Publisher.
Configure the following connection details:
- Host: The URL of the Oracle BI publisher that you want to connect to. Use the following format here:
```
https://ExampleInstanceID.oracle.com
```
- Username and password: The username and password for the user configured in the prerequisites. Celonis uses key-based authentication by including the username and password in each request payload.
  Note
  Ensure the user credentials provided have adequate permissions to extract the desired data. For more information, see Oracle BI Publisher user permissions.
- Report configurations: Add each report you want to use in the Celonis Platform as an individual line item using the following format:
```
/~oracleUsername/nameOfTheReport.xdo
```
  Note
  Reports must be in XML format to be extracted. For more information, see Report configuration and further information.
Select Test Connection, and correct any issues highlighted.
Select Save.
The connection between your Oracle BI Publisher tenant and the Celonis Platform is established. You can manage this connection at any time by clicking options:

Filter and delta extractions from Oracle BI Publisher

Filters are only supported for SQL-query based reports which are configured in BI Publisher. When used in the Celonis Platform, filters always need to be passed as a string value.

To set up filters for your Oracle BI Publisher instance:

Defining a filter requires a parameter to be set-up in BI Publisher. The filter is referenced using the name of this parameter.
Filters on Datetimes and Delta Filters can be achieved using two different set-ups:
- Defining the Datatype of the respective columns in the column configuration as a STRING: The column can then be used to create a dynamic parameter. This set-up requires the BI Publisher column to have the exact same syntax as the column coming from BI Publisher (e.g. 2024-10-15T19:09:17.0000+00:00)
- Defining the Datatype of the respective columns in the column configuration as a DATETIME: Creating a view in Celonis which calculates the maximum of this column and parses it to a String (see example screenshot below). The column of this view can then be used to create a dynamic parameter. This set-up gives you the possibility to “match” the BI Publisher parameter syntax via the syntax definition as part of the view.
  For example:
```
CREATE VIEW parameter_view AS (
 select TO_CHAR(max(CREATION_DATE), 'MM-DD-YYYY') as parameter_column from myreport_G_1
```
Include the parameter in the SQL query that you define in the BI Publisher report.
For example:
When configuring an extraction in the Celonis Platform, you can now define a value for the parameter by using the filter statement.
You can only assign values to this parameter, meaning you need to use the = operator.
You can configure delta filters in the same way by using dynamic extraction parameters. See: Using delta filters with dynamic parameters.