Skip to main content
Windward

Windward Access Providers - Data Sources and Import Tags

Overview

Starting in v15.1.48.0, Windward is using a single set of code to address accessing files and web-based data. This adds features with regard to your Data Source credentials as well as how Import Tags access content.

 

Access Providers

These provide a new consistent way to access files and web based data across AutoTag. Windward ships with the following access providers:

.NET (.NET Engine, RESTful Engine, AutoTag)

Java Engine

  1. File based – anonymous & Windows security
  2. Embedded Windows resource
  3. HTTP – anonymous
  4. HTTP – basic
  5. HTTP – digest
  6. HTTP – negotiate (NTLM & KEREBROS)
  7. Claims Based (Microsoft)
  8. AllHttp (try protocols 3 – 6 above)
  1. File based – anonymous
  2. Embedded JAR resource
  3. HTTP – anonymous
  4. HTTP – basic
  5. HTTP – digest
  6. AllHttp (try protocols 3 – 5 above)

 

Customers can write their own Access Provider and it will get added to this list at runtime and is treated identically to the existing providers. A provider should be able to be written in under 200 lines of code (usually much less).

Authentication Protocol

How it works

In the Authentication Protocol field, select the type you want from the dropdown and then fill in the credential fields for that option.  This combination defines the protocol and its properties, and is saved as a connection string in the form “AccessProvider=Basic;Username=username;Password=password;”

 

Note:

  • All of the connection string keywords and any of the common values are in BaseAccessProvider.java if needed directly in your code. AutoTag will build this string for you.
  • One of the protocols is FileBased which is used for reading a local file as well as http files.
  • If no AccessProvider is set in the connection string, Windward it will look at the URL and set it to "AllHttp" if the url starts with  http:, https:, ftp:, etc. Otherwise it will set it to FileBased.

Via Your Data Source

When you edit or create a new web or file-based Data Source, you can set the Authentication Protocol. In AutoTag this is done by selecting the protocol itself and then setting the properties for that protocol. Open your Data Source Connection Editor (see this article for more) and edit or create a new Web/File connection. In the Authentication Protocol field, select the type you want from the dropdown and then fill in the credential fields for that option. The connection editor screen will look slightly different depending on the type of connection. 

 

 

For specific settings with your data source, see these pages:

Connect to a JSON Data Source

Connect to an XML Data Source

Connect to an OData Data Source

Via Your Import Tags

To access the Authentication Protocol for an Import Tag, open the Tag Editor and navigate to the Properties pane. In the Tag Properties, click the [...] button to bring up the Connection String interface.

 

 

There is no URL in the Import Tag credentials because the Import Tag itself provides the URL. 

The Connection String Interface

Use variable

If you select “Use variable,” the variable dropdown will show all variables defined in the template you have open. In this case, the variable needs to be set to find the connection string you want to use; a Set Tag is usually the best Tag to use for this. "Use variable" is very useful if the username/password is to be set differently during production. It is also useful if the same protocol and credentials are used with multiple Import Tags.

Set explicitly

Use this option to set the credentials for this particular Import Tag. The fields will be the same as those used in the Data Connection Editor Interface. 

In the URL

Normally the Import Tag will return something like http://www.windward.net/images/logo.png and all the provider information is set as above. However, if you type or paste a select into your Query Pane similar to what is shown below, all of the above settings, if they exist, are ignored. Instead, Windward assumes the returned value is the entire connection string. 

Url= http://www.windward.net/images/logo.png;AccessProvider=Digest;Username=yourusername;Password=yourpassword; 

 

It uses this mode if it finds  Url= in the string.

 

Passing credentials to an Import Tag via the Engine

Use this Sample Invoice to play along!

 

To pass credentials via the Engine, follow these steps:

Step 1

In your template in AutoTag, create an Input Variable.

  • Give it a variable name, and a default value. The final form of the value you pass in will need to be in this form:

“AccessProvider=Basic;Username=username;Password=password;”

  • Note the variable name because you will use it later!

 

Step 2 

Next Open your Import Tag and navigate to the Properties Pane. Open the Connection String interface, click Use Variable, and select the variable name from the dropdown menu. 

 

 

Once your template has this set up run it to make sure it works in AUtoTag. Once you've tested that, it's time to try it in your Engine.

 

Step 3

Now locate the engine code you're using; either open Catapult, or navigate to where the Windward Engine Samples are stored on your machine. 

Find the Advanced section/folder, and open the Variables example. Here is the basic information that will need to be added to your code:

 

.NET (C#) Java (note 
            //This is where we pass in the parameters
            Dictionary<string, object> map = new Dictionary<string, object>();
            //order is our variable
            map.Add("order", “AccessProvider=Basic;Username=username;Password=password;”);
            //This is the function where we actually tell our report the parameter values
            data.Map = map;
       //This is where we pass in the parameters to the datasource
        Map map = new HashMap();
        map.put("order", “AccessProvider=Basic;Username=username;Password=password;”);
        //the actual function that gives the datasource our parameters
        data.setMap(map);

 

Creating a Custom Access Provider

Step 1

Create a new .NET class library project in visual studio, and add assembly references to WindwardReportDrivers.dll, WindwardReports.dll, and IKVM.OpenJDK.Core.

  • If you have installed the .NET engine these assemblies will be in a folder called DLL in your Windward install directory or in the GAC depending on the options you selected on install.
  • If you have AutoTag installed these assemblies will be in the GAC.

 

Step 2

Create a new class that inherits from WindwardReportsDrivers.net.windward.AccessProviders.protocols.HttpAccessProvider, and implement the required methods (see description and example below).

Properties{get;} 

Here you will define a list of properties that are required to make your connection.

GetConnectionStringProperties()

This method takes in a connection string and converts it to a dictionary of properties.

CreateConnectionString()

This method takes in a dictionary of properties and converts it to a connection string.

Name{get;}

This is the name of your AccessProvider

Description{get;}

This is a description of your access provider

Request()

This method does the actual work of creating and making the http request.

 

Example:

 

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Text;
using System.Threading.Tasks;
using net.windward.util;
using net.windward.util.AccessProviders;
using WindwardReportsDrivers.net.windward.AccessProviders;
using WindwardReportsDrivers.net.windward.AccessProviders.protocols;
using Convert = System.Convert;

namespace SampleAccessProvider
{
    public class SampleHttpAccessProvider : HttpAccessProvider
    {
        private static readonly string USERNAME = "Username";
        private static readonly string PASSWORD = "Password";

        /// <summary>
        /// This provides a list of the properties that are needed for this connection.
        /// This list will be used to form the property grid for this connection in AutoTag.
        /// </summary>
        public override List<PropertyInfo> Properties
        {
            get
            {
                return new List<PropertyInfo>
                {
                    //Arguments for property info constructor.
                    //arg 1: prompt for the property: This is the way the property will be displayed in the connection grid.
                    //arg 2: Property discription: This will be used for tool tips in the AutoTag UI.
                    //arg 3: Property Key: The name of this property to be used in the connection string. (ex Username=example@windward.net)
                    //arg 4: Default value: A default value for this property.
                    //arg 5: Property type: the type this property needs to be when passed for the connection. (note: if you specify integer all values provided must be parsable as integers)
                    //arg 6: IsPassword: Only used to determine if property should be masked in the ui.
                    new PropertyInfo("Username", "The username for the connection", USERNAME, "",typeof(string), false),
                    new PropertyInfo("Password", "The password for the connection", PASSWORD, "", typeof(string), true)
                };
            }
        }

        /// <summary>
        /// returns the properties from the connection string as a Dictionary
        /// </summary>
        /// <param name="connectionString"></param>
        /// <returns></returns>
        public override Dictionary<string, string> GetConnectionStringProperties(string connectionString)
        {
            Dictionary<string, string> dict = new Dictionary<string, string>();
            //grab any properties you have defined as required in your in your properties list.
            string username = StringUtils.getConnectionStringProperty(connectionString, USERNAME);
            dict.Add(USERNAME, username);
            string password = StringUtils.getConnectionStringProperty(connectionString, PASSWORD);
            dict.Add(PASSWORD, password);
            
            //the url that will be used for this connection
            string connectionUrl = StringUtils.getConnectionStringProperty(connectionString,
                BaseAccessProvider.CONNECTION_URL);
            dict.Add(CONNECTION_URL, connectionUrl);

            //you will also need the type of this provider.
            dict.Add(CONNECTION_ACCESS_PROVIDER, Name);

            return dict;
        }

        /// <summary>
        /// Returns a connection string using the provided properties
        /// </summary>
        /// <param name="properties"></param>
        /// <returns></returns>
        public override string CreateConnectionString(Dictionary<string, string> properties)
        {
            StringBuilder connStrBuilder = new StringBuilder();
            //add our access provider to the string
            connStrBuilder.Append(string.Format("{0}={1};", CONNECTION_ACCESS_PROVIDER, Name));
            if(properties.ContainsKey(CONNECTION_URL))
                connStrBuilder.Append(string.Format("{0}={1};", CONNECTION_URL, properties[CONNECTION_URL]));
            if (properties.ContainsKey(USERNAME))
                connStrBuilder.Append(string.Format("{0}={1};", USERNAME, properties[USERNAME]));
            if (properties.ContainsKey(PASSWORD))
                connStrBuilder.Append(string.Format("{0}={1};", USERNAME, properties[USERNAME]));

            return connStrBuilder.ToString();
        }

        /// <summary>
        /// The name of this access provider.
        /// </summary>
        public override string Name { get { return "BasicHttpAccessProviderExample"; } }

        /// <summary>
        /// A Description of what this access provider is for.
        /// </summary>
        public override string Description { get
            {
                return "An example of an AccessProvider implementing basic http authentication.";
            }
        }
        
        /// <summary>
        /// Handles building your custom request.
        /// </summary>
        /// <param name="url">The url to make the request from</param>
        /// <param name="credentials">If you use the static user name and password strings from BaseFullAccessProvider to define your props your credentails will be here</param>
        /// <param name="headers">http headers for "content-type" and "accept" if applicable</param>
        /// <param name="allProps">A dictionary of all the properties you have defined for your connection.</param>
        /// <returns></returns>
        public override ResponseHttp Request(string url, NetworkCredential credentials, IDictionary<string, string> headers, Dictionary<string, string> allProps)
        {
            HttpWebRequest request = (HttpWebRequest)BuildRequest(url, headers);


            //set up basic authentication
            request.KeepAlive = true;
            // this part is not used until after a request is refused, but we add it anyways
            CredentialCache myCache = new CredentialCache();
            myCache.Add(new Uri(url), "Basic", credentials);
            request.Credentials = myCache;

            // this is how we put the uname/pw in the first request (avoids 2 tries to succeed)
            string cre = string.Format("{0}:{1}", allProps[USERNAME], allProps[PASSWORD]);
            byte[] bytes = Encoding.ASCII.GetBytes(cre);
            string base64 = Convert.ToBase64String(bytes);
            request.Headers.Add("Authorization", "Basic " + base64);

            return new ResponseHttp(request.GetResponse(), url);
        }
    }
}

 

 

Using Your Custom Access Provider

You will need to add your dll to the <WindwardReports> section of your AutoTag or .NET engine config file (depending on if you are using the engine or AutoTag) as shown below.

 

<?xml version="1.0"?>

<configuration>

<configSections>

<section name="WindwardReports" type="System.Configuration.NameValueSectionHandler, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>

</configSections>

<WindwardReports>

<add key="ImportFileClass" value="C:\full\path\to\my\AccessProvider.dll=ClassName.Including.Namespace.For.MyAccessProvider"/>

</WindwardReports>

</configuration>

 

After doing this your access provider should be available in the engine, and will show up in the list of access providers when forming and editing connections in AutoTag.