Skip to main content
Windward

Connect to an OData Service as a Data Source v15

Data Source Type:

Odata
Versions Supported: 

1, 2, 3, 4

 

 

Overview

OData is a standard for building and consuming RESTful APIs. OData requests are made with a URL that uses http to request data, using the returned data to populate the report. For more information, see the article on the new Connection Editor here.

 

 

Key Terms Used

URIUniversal Resource Identifier – This looks just like a URL and is the connection point for an OData service.  The URI to request data is composed of two parts. First is the root of the URI, typically something like http://services.odata.org/Northwind/Northwind.svc. This root is constant for all requests against a specified OData data source.  The "select" in each request is the part of the URL added to the root in order to filter the results. So a select of "Categories" will create the URI http://services.odata.org/Northwind/...svc/Categories. Windward supports all valid OData requests.

 

 

What you will need to establish this connection

 

  • An Odata service root URI (such as: http://services.odata.org/Northwind/Northwind.svc)
  • A good network connection to your Odata service. (Please note, if you are inside a corporate network and you cannot access the cloud-hosted demo data source, your firewall may be blocking you from access. Please consult with your systems or network administrator for assistance.)

 

High level outline of the process

  1. Open MS-Word/Excel/PowerPoint (For this example, we will be using MS-Word)
  2. Go to the AutoTag Manager tab on the ribbon
  3. Click on the Data Sources icon (the Connection Editor Pops up)
  4. Fill in the appropriate information in the Datasource Connector dialog box and click OK
  5. Your Data Source is now connected to your template

 

Connecting Your Template to​ an OData Service URI 

 

Important Note: The OData wizard is not capable of creating all possible OData queries. The wizard is designed to handle 100% of the queries for 95% of our users. With this restriction, we are able to make the wizard much simpler to use.  However, any URI can be directly typed-in directly, with any level of complex query, and it will work just fine. 

 

Follow these steps in order to connect your template to an OData service URI:

 

Step 1

From MS Word, Excel or PowerPoint, navigate to the AutoTag Manager tab. Once on the AutoTag Manager tab, click on the upper half of the Data Sources button. This will open the data source Connection Editor.

 

Note that if you click on the bottom half, you will get a dropdown menu which lists data sources that are already connected; this may be blank.

 

 

Step 2

Enter your organization's information. The information for Windward's sample OData data sources is shown below.

 

1. In the Connection Editor window, in the New tab, click on OData under Web data sources. The Details pane will change to prompt you for your data source details.

 

2. Enter a Nickname for your data source connection. It is best practice to always assign a nickname to your data source in the Name field. This will make your life much easier down the road when working with templates or tracking down any issues.

 

3. Type or paste the URL, or browse to the location. If the file requires authentication, you will need to provide credentials in the Authentication Protocol fields.

 

4. Choose your Authentication Protocol form the dropdown. The Odata version defaults to 3, but you can use the dropdown to select a different version. Fill in your credentials or opt to use your Windows Identity. For additional information, see our article on Authentication Protocols.

 

5. Click Add, and then Test your connection. If all parameters and credentials are correct and a connection is made, you will receive a successful notification. Clicking Close will save your information. 

 

 

 

Notes:

  • For Odata you also specify the URL (top edit/drop down). In addition, for Odata there will always be a version property that must be set to 1, 2, 3, or 4
  • Because all protocols are always listed, you can select the FileBased or embedded protocol for Odata. But doing so is non-sensical as Odata must be making requests of a server.
  • When you set all the properties for Odata you will get a connection string in the form “Url=http://services.odata.org/Northwind/...data.Version=2;”

 

.NET Code Java Code
new ODataDataSourceImpl ( “Url=http://services.odata.org/Northwind/...data.Version=2;” ); new OdataDataSource ( “Url=http://services.odata.org/Northwind/...data.Version=2;” );

Troubleshooting

If something is not right, you will see a red error message at the bottom of the dialog.

Common Issues

Maximum Bytes error

Receiving the error: "The maximum number of bytes allowed to be read from the stream has been exceeded. After the last read operation, a total of XX bytes has been read from the stream; however a maximum of 10000000 bytes is allowed."

To raise the message size limit, set the "odata.max-message-size" property in the autotag20__.config file, under the <WindwardReports> node.

 

Java Query Failure

The java-engine specific failure of a query with multiple navigation properties. For instance, a query like: Suppliers(0)/Address/City may fail. To avoid this, use a variable (Set or Query Tag), and assign it the query: Suppliers(0). Then to get the City, you can use ${varName.Address.City}.

 

"No connection could be made because the target machine actively refused it."

If you get this exception message, especially if it refers to 127.0.0.1, check your defaultProxy in your app.config.

 

Using https to connect to OData

If you are using https to connect to OData, you may get an exception relating to lack of authority or invalid certificates. In this case you will need to add your certificate or your machine's "Trusted Root Certification Authorities" store. This can be done by following the steps here:

http://www.thewindowsclub.com/manage-trusted-root-certificates-windows