1. To change the password, use your web browser to open the below OData endpoint. https://odata.onit.com/hdpui/login.jsp

2. Enter the username and password for your OData user/useradmin, shared by Onit through OData Welcome Provision mail.

3. Click on the authenticate button. A change password screen will appear to set the new password.

4. Enter the Current Password, new password and confirm new password. Click Save to change the password.

This section describes how to add a new user for a tenant. For this, we will use the useradmin credentials, as the useradmin will be responsible for adding new users.

1. Login to the below OData endpoint using the useradmin credentials. https://odata.onit.com/hdpui/login.jsp

If the useradmin is logging in for the first time, the useradmin needs to reset the password. Refer to the “Steps to change the password” section of the document.

Once logged in, the “Manage User” page of the OData endpoint will open. This page contains a list of this tenant's available users.

2. Click on the “+ New User” button. This will open the “Create User” page.

3. In the “Create User” page, there are two sections to fill:

• General
• Authentication Setup

On the “General” tab, enter your username in the “User Name” field and select the appropriate role from the “Role” dropdown. There are three roles available in the “Role” dropdown.

• User Role: Users with this role can access the data from the OData endpoint.
• UserAdmin Role: Users with this role can create a user for a tenant.
• Tenant Administration Role: Users with this role can manage the tenant. Currently, Onit manages this role.

Here, we will create a new user named “onituser” for awsustau tenant, and the role for this user will be “User Role."

In the “Authentication Setup” tab, provide the password for the new user and click on the “Save” button, as shown in the below screenshot. When clicking the “Save” button, the page will be redirected to the “Manage User” page.

4. The useradmin should now be able to see the newly created user added in the “Manage User” page. The useradmin needs to share the credentials with the new user.

5. The new user needs to log in to the OData endpoint and change the password. A guide to changing the password for a user is provided in the “Steps to change the password” section of the document.

6. Once the password is changed, the user can connect to the OData endpoints using any of the methods mentioned in the later sections of the document.

As of now, Tableau does not support OAuth 2.0-based authentication for OData. Please refer to the OAuth Connections link for more details about the other connectors supported by Tableau.

This section describes how to connect Tableau to an OData data source. Tableau connects to OData V1, V2, and V4. Onit supports OData Version V4.

1. Start Tableau, and under Connect, select OData. For a complete list of data connections, select More under To a Server. Then do the following:

In the Server, type one of the following:

• A service URL to access all feeds inside the service.
• A feed URL to access a specific data feed.

From the Authentication dropdown, select the authentication mode for this connection.

• If you select Username and Password, type a username and password.

Select Sign In.

2. Click on OData, enter the OData endpoint URL with username and password, and click Sign In.

3. Once the connection is successful, all the apps will be visible in the Tableau table panel. You can drag and drop the tables to include them in the data source.

4. The data source can include more than one entity and the relationship between them can be specified using the joining fields.

5. Once the data source is designed, you can use the worksheet to build the Tableau dashboards/reports.

This section describes connecting PowerBI to an OData data source using OAuth 2.0-based authentication.

1. Open Visual Studio and Create New -> Project. In the left pane, choose Power Query under templates. Choose Data Connector Project and create a New Project named ‘HdpOAuth 2.0Connect’.

2. In the Solution, find HDPOAuth 2.0Connect.pq file and change the below configurations:

1. Onit OData Service URL
2. Client ID
3. Client Secret
4. Authorize URL
5. Token URL

3. Save the file and Build the Solution. This should create a HDPOAuth 2.0Connect.mez file in the bin folder. This is the Power BI extension.

4. On your PC, Go to Documents and create a Microsoft Power BI Desktop folder.

5. Under the folder Microsoft Power BI Desktop, create another folder, Custom Connectors

6. Copy the HDPOAuth 2.0Connect.mez to the folder Custom Connectors.

7. Start PowerBI Desktop. Under Get Data, select HDPAOuthConnect and click Connect.

8. In the HDPAOuthConnect dialog, click Sign In.

9. This should open the login page for you to authenticate. Enter the Username and password. Click the Authenticate button.

10. If the username and password are correct, you should see the below authorization screen. Click on the Allow button.

11. Click on Connect to see your data.

This section describes how to connect PowerBI to an OData data source.

1. Start PowerBI Desktop, and under Get Data, select OData feed.

2. In the OData Feed dialog, type the following:

• Select the Basic option, enter the OData Endpoint URL, and Click OK. (https://odata.onit.com/api/odata4/all_apps_{subdomain})

3. Enter the username and password on the OData Feed dialog and Click Connect.

4. Once the connection is successful, all the apps/entities will be visible in PowerBI's navigator panel. Select the apps/entities that you want to include as part of the data source.

5. Once complete, Power BI Desktop makes the selected tables and other data elements available in the Fields pane, found on the right side of the Reports view in Power BI Desktop.

6. You can use the Manage Relationship option to create and manage relationships between entities.

Entities are used to model and manage business data in Onit. An Onit app or database view can be considered an entity with a set of attributes, and each attribute represents a data item of a particular type.

For example, within Onit’s Enterprise Legal Management (ELM) product, the following Entity Relationship Diagram represents apps and relationships that may fit a client-specific business need for reporting.

Onit ELM-owned entities include matters, invoices, vendors, vendor_assignment_to_matters, and billing_authorization_requests. BillingPoint-owned entity is bp_invoices_line_item_cube. Relationships can be of various types and, for the most part, are defined in your Onit configuration and are available from the custom data dictionary provided during provisioning. This includes:

1. One-to-One: This relationship indicates that a single record in one entity is related to a single record in its related entity (Onit relationship type belongsTo)
2. One to Many: This relationship indicates that a single record in one entity can be related to many records in its related entity (Onit relationship type belongsTo)
3. Many to Many: This relationship indicates any record in either entity can be related to many records in the related entity (Onit relationship type ManyToMany)

A many-to-many relationship occurs when multiple rows in an entity are associated with multiple rows in a related entity. To identify unique pairs of records, this relationship type needs to be split into two one-to-many relationships, with a new data warehouse join table. The join table simply contains foreign key columns for the two related tables' (built from entities) primary keys.

A typical generic example of a many-to-many relationship is between students and courses. A student can register for many courses, and a course can include many students. We need to identify each student/course pair through a join table to get information from both student and course. In the data warehouse, a join table is created, but views that have appropriate names are also used to guide the correct join through this view. See the Tableau join example below for joining students through student_courses by id and then to the courses table through the m2m_courses column.

In Onit, be sure to enable the required ManyToMany relationship fields for reporting so that the join table is created in the data warehouse and made available in Data as a Service.

Whether creating data sources for BI tools or accessing data from the APIs, we strongly encourage selecting attributes and filtering rows to meet a specific business need for optimal performance. Consider filtering by phases, statuses, dates, or other attributes that meet your needs as efficiently as possible. For example, in ELM, you may never want to see voided invoices, so you can filter invoices.curr_state_name and exclude the voided state. You can also exclude rejected matters by filtering matters.curr_state_name and exclude the rejected state.

This section describes connecting Postman to an OData data source using OAuth 2.0-based authentication.

1. Open Postman and send a POST REQUEST as shown below; the Response from the Server will contain your Client Key and Client Secret and should be like something below.

This section describes how to fetch OData data using OAuth 2.0-based authentication.

1. Open Postman and send a POST REQUEST using the User in the welcome email. The server response will contain your Client Key and Client Secret and should look like the below.

2. Open Postman and send a POST REQUEST using the User in the welcome email. The server's Response will contain your Access Token and Refresh Token.

3. Open Postman and send a GET REQUEST as shown below using Access Token generated in the second step to fetch data using Postman.

4. OData Enpoint Data can be fetched using python. Below is the code snippet:

This section describes how to connect Postman App to an OData data source.

1. Start the Postman app and add a new request. Then do the following:
2. In the Request URL, type the below endpoint"https://odata.onit.com/api/odata4/all_apps_{subdomain}
   Note: Replace the {subdomain} with the name of your subdomain
3. On the Authorization tab, type as Basic Auth and enter the username and password provided to you.
4. Press Send button. It should return the list of apps/entities that are available as part of the OData API

1. Start the Postman app and add a new request. Then do the following:
2. In the Request URL, type the below endpoint: https://odata.onit.com/api/odata4/all_apps_{subdomain}/#metadata
   Note: Replace the {subdomain} with the name of your subdomain
3. On the Authorization tab, type as Basic Auth and enter the username and password provided to you.
4. Press the Send button. It should return the list of apps/entities metadata that are available as part of the OData API

1. Start the Postman app and add a new request.
2. In the Request URL, type the below endpoint: https://odata.onit.com/api/odata4/all_apps_{subdomain}/{entity_name} 
   Note: Replace the {subdomain} with the name of your subdomain. Replace {entity_name} with the entity's name that was returned as part of the list of entities.
3. On the Authorization tab, type as Basic Auth and enter the username and password provided to you.
4. Press Send button. It should return the list of apps/entities metadata that are available as part of the OData API

1. Start the Postman app and add a new request. Then do the following:
2. In the Request URL, type the below endpoint: https://odata.onit.com/api/odata4/all_apps_{subdomain}/{entity_name}
   Note: Replace the {subdomain} with the name of your subdomain. Replace {entity_name} with the name of the entity that was returned as part of the list of entities.
3. On the Authorization tab, type as Basic Auth and enter the username and password provided to you.
4. Press the Send button. Click on the Code icon to generate the code in the language of your choice.

import http.client
import base64

# Connect to the odata endpoint host
conn = http.client.HTTPSConnection("odata.onit.com")

# Keep the payload as empty string
payload = ''

# Pass the Authorization header with Basic authentication
# The user name and password should be encoded as Base64
# Create a base64 encoded authorization header "subdomain_user:password"
# Replace the user name and password below. It is better to store the username and password in config file or password vault
auth_string = "subdomain_user:password"

# convert to Base64 encoded authorization string
base64_bytes = base64.b64encode(auth_string.encode("ascii"))
base64_string = base64_bytes.decode("ascii")

# Prepare the request header for basic authorization
headers = {
'Authorization': f"Basic {base64_string}"
}
# Make the HTTP request. Replace the endpoint with your subdomain e.g. all_apps_subdomain
conn.request("GET", "/api/odata4/all_apps_awsustau/matters", payload, headers)
# get the response
res = conn.getresponse()
# Read the json data from the response
data = res.read()
# Print the json data
print(data.decode("utf-8"))

import http.client
import base64

# Connect to the odata endpoint host
conn = http.client.HTTPSConnection("odata.onit.com")

# Keep the payload as empty string
payload = ''

# Pass the Authorization header with Basic authentication
# The user name and password should be encoded as Base64
# Create a base64 encoded authorization header "subdomain_user:password"
# Replace the user name and password below. It is better to store the username and password in config file or password vault
auth_string = " "

# convert to Base64 encoded authorization string
base64_bytes = base64.b64encode(auth_string.encode("ascii"))
base64_string = base64_bytes.decode("ascii")

# Prepare the request header for basic authorization
headers = {
'Authorization': f"Basic {base64_string}"
}

# Create the connection configuration based on the Database where the odata endpoint data is stored
connection = get_db_connection(dbName, username, password)

# Fetching max updated_at present in the DB for that particular entity
entity_max_updated_at = connection.execute('''SELECT MAX(updated_at) FROM matters''')

# Fetching max calculated_at present in the DB for that particular entity. Calculated_at is set when a recalc is performed on an atom
entity_max_calculated_at = connection.execute('''SELECT MAX(calculated_at) FROM matters''')

# odata api url to fetch the count of incremental data

incr_dataCount_endpoint_url = f' incr_dataCount_endpoint_url = f'/api/odata4/all_apps_awsustau/matters/$count?$filter=updated_at%20gt%20{entity_max_updated_at}%20 or%20calculated_at%20gt%20{entity_max_calculated_at}'

# Make the HTTP request to get the incremental data count from odata endpoint.
conn.request("GET", incr_dataCount_endpoint_url, payload, headers)

# Get the incremental data count response
incr_dataCount_res = conn.getresponse()

# Read the incremental data count from the response
incr_dataCount = incr_dataCount_res.read()
incr_dataCount = int(incr_dataCount.decode("utf-8"))

if incr_dataCount > 0:

# odata api url to fetch the incremental data

incr_data_endpoint_url = f'/api/odata4/all_apps_awsustau/matters? ?$filter=updated_at%20gt%20{entity_max_updated_at}%20or%20calculated_at%20gt%20{entity_max_calculat ed_at}'

# Making the HTTP request to fetch the incremental data for that particular entity from odata endpoint

conn.request("GET", incr_data_endpoint_url, payload, headers)

# Get the incremental data response
incr_res = conn.getresponse()

# Read the incremental json data from the response
incr_data = incr_res.read()

# Print the incremental json data
print(incr_data.decode("utf-8"))

# Implement the delete-insert function. This function will perform below activities.
# 1. Incremental Records that are new, will be inserted into the DB.
# 2. Incremental Records that are already present in the DB, will be first deleted from DB, and then the updated version of those records will be inserted into the DB.
delete_insert_incremental_data(incr_data, connection)

else:

print("No incremental data found in odata endpoint for this entity. Hence, the data load for this entity will be skipped.")

import http.client
import base64
import json
import logging

logger=logging.getLogger(__name__)

def load_odata_data(entity_url, conn, payload, headers,batch_size):
'''
function that fetches the data from OData endpoint url and insert to target db in batch
'''
conn.request("GET", entity_url, payload, headers)
i=0
# get the response
res = conn.getresponse()

# Read the json data from the response
data_dict = json.loads(res.read())

#Entity Records
records = data_dict['value'] #OData Record list

odata_rec=[]
#Loop to process odata records and insert into target db in batch

connection=None
for rec in records:

i=i+1
odata_rec.append(rec)
if i>=batch_size:
i=0
load_target_db(connection,odata_rec)
odata_rec=[]

if len(odata_rec)>0:
load_target_db(connection,odata_rec)

def load_target_db(connection,odata_rec):

'''
Add a logic to insert the data in to target db
'''

logger.info("Total Records available for insertion : {} ".format(len(odata_rec)))

# Connect to the odata endpoint host
conn = http.client.HTTPSConnection("odata.onit.com")

# Provide the tenant and entity details here
tenant_name = 'awsustau'
entity_name = 'matters'

# Keep the payload as empty string
payload = ''

# Pass the Authorization header with Basic authentication
# The user name and password should be encoded as Base64
# Create a base64 encoded authorization header "subdomain_user:password"
# Replace the odata_username and password below. It is better to store the username and password in config file or password vault
auth_string = "awsustau_useradmin:{password}"

# Convert to Base64 encoded authorization string
base64_bytes = base64.b64encode(auth_string.encode("ascii"))
base64_string = base64_bytes.decode("ascii")

# Prepare the request header for basic authorization
headers = {
'Authorization': f"Basic {base64_string}"
}

# Make the HTTP request. Replace the endpoint with your subdomain e.g. all_apps_subdomain
entity_url = f"/api/odata4/all_apps_{tenant_name}/{entity_name}"

try:
# Batch size to load data in target db
batch_size=10
# Fetch records from odata endpoint & load to target db based on batch size
load_odata_data(entity_url, conn, payload, headers,batch_size)

except Exception as exc:
logger.error(f"{tenant_name}: Unable to fetch the data for entity '{entity_name}' : {str(exc)}")

finally:
conn.close()

To create a URL into an Onit single atom page, use the app id and atom id available as system fields as noted above with a format similar to: https://mycorp.onit.com/apps/{app_id}/atoms/{_id}

The following are the high-level features enabled for the OData service, per the OData specification.

Available query options

• $filter
• $count
• $orderby
• $skip
• $top
• $select

Built-in operators for $filter

• Equals (eq)
• Not equals (ne)
• Greater than (gt)
• Greater than or equal (ge)
• Less than (lt)
• Less than or equal (le)
• And
• Or
• Not

For more information, see OData operators.

Here are a few examples of the various query features that can be used as part of OData. Please refer to OData specification for more details about querying and filtering data using OData specification.

1. Get the count of rows for a given entity. https://odata.onit.com/api/odata4/all_apps_awsustau/matters/$count
2. Get the top 5 rows. https://odata.onit.com/api/odata4/all_apps_awsustau/matters?$top=5
3. Skip the first 5 rows and get the top 5 rows.  https://odata.onit.com/api/odata4/all_apps_awsustau/matters?$skip=5&$top=5
4. Order by field name in descending order. https://odata.onit.com/api/odata4/all_apps_awsustau/matters?$orderby=created_at desc
5. Filter data using the filter expression. https://odata.onit.com/api/odata4/all_apps_awsustau/matters?$filter=area_of_law eq 'Commercial'
6. Select specific fields from a given entity. https://odata.onit.com/api/odata4/all_apps_awsustau/matters?$select=id,status,atom_number

When a user tries to log in to https://odata.onit.com/api/odata4/all_apps_awsustau/, even with the correct credentials, Tableau or PowerBI can still sometimes face communication issues with OData. Ensure there are no leading or trailing spaces, which can sometimes happen when copying/pasting.

An idle browser window (20+ minutes) will lose connectivity, and subsequent use of the UI will result in session timeout (Error 408). Close and re-open the browser to start a new session to resolve this issue.

Even if relationship fields are not selected for reporting, they are always pulled in by the DW refresh. Hence, they are available for joins to their related app either by a BelongsTo or ManyToMany relationship.