Table of Contents

• What is the Easy Insight API?
• How do I use the Easy Insight API?
• What are the data types of the API?
• What are the operations of the API?
• Java Code Example

What is the Easy Insight API?

Easy Insight offers a SOAP API for loading data. You can use this API to publish in any variety of custom data through a programmatic mechanism. We've designed this API to handle a variety of use cases and make it as easy as possible to get the results you need in Easy Insight as quickly as possible.

How do I use the Easy Insight API?

The Easy Insight API is a SOAP web services API. The WSDL for the Easy Insight API is located at https://www.easy-insight.com/app/services/EIDataV2?wsdl. You should be able to use any SOAP stack to generate client code against this WSDL.

Once you have client code, you'll need to authenticate against the web service by basic authentication. As the username and password in your basic authentication setup, you need to use the key and secret key found under your "My API Information..." section of the API page in Easy Insight. You may need to enable API access to your account if you have not done so already. This can be done by an account administrator under My API Information or Account Settings.

What are the data types of the API?

All of the calls pass across Row objects, along with various other parameters. Row contains three properties, all arrays.

The first array, stringPairs, contains StringPair objects. Use this array for any Grouping fields you may be passing into Easy Insight--string fields such as Customer, OrderID, or Project. StringPair itself contains a String key and a String value.

The second array, numberPairs, contains NumberPair objects. Use this array for any Measure fields you may be passing into Easy Insight--numeric fields such as Revenue, Count, or Units. NumberPair itself contains a String key and a Double value. Do not pass numeric IDs such as CustomerID into this field--use StringPair for identifiers. Only use NumberPair for those fields which you'll want to sum, average, and so on.

The third array, DatePairs, contains DatePair objects. Use thise array for any Date fields you may be passing into Easy Insight.

What are the operations of the API?

• addRow

addRow adds a single row to a data source. The operation takes a data source name and a Row.

• addRows

addRow adds multiple rows to a data source. The operation takes a data source name and an array of Rows.

• updateRow
• updateRows
• replaceRows
• deleteRows

Java Code Example

Let's build an example of an API call. This call will add a row of hypothetical order data to Easy Insight. Our order data has three fields:

• Customer

The name of the customer who made the order

• Units

The number of units ordered by the customer

• Order Date

When the order was made

At this point, we have nothing set up in Easy Insight as far as data sources specific to this data. We're going to use the API to do everything for us.

Your first step will be to generate client code against the WSDL found at https://www.easy-insight.com/app/services/EIDataV2?wsdl. The exact process for this code generation will vary depending on your SOAP stack and IDE, but it should involve something along the lines of WSDL to Java. For the client code and authentication shown in this example, we'll be demonstrating with Metro (Jax-WS).

Once you have the generated client code, you need to establish and authenticate the service connection to Easy Insight. The code shown below creates a Service object, retrieves the Port from the service, and sets the key/secret key (found under API Information) as the username/password in the basic auth credentials.

    BasicAuthEIV2APIService service = new BasicAuthEIV2APIService();
    EIDataV2 port = service.getBasicAuthEIV2APIPort();
    ((BindingProvider)port).getRequestContext().put(BindingProvider.USERNAME_PROPERTY, key);
    ((BindingProvider)port).getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, secretKey);
                    

The next step is to create an actual Row object with the business data we described earlier. We'll create a Row, then add a StringPair, NumberPair, and DatePair to the row with the business data.

    Row row = new Row();
    StringPair customerName = new StringPair();
    customerName.setKey("Customer");
    customerName.setValue("Joe Smith");
    NumberPair orderUnits = new NumberPair();
    orderUnits.setKey("Units");
    orderUnits.setValue(100);
    DatePair orderDate = new DatePair();
    orderDate.setKey("Order Date");
    GregorianCalendar cal = (GregorianCalendar) GregorianCalendar.getInstance();
    cal.setTime(new Date());
    XMLGregorianCalendar xmlCalendar = DatatypeFactory.newInstance().newXMLGregorianCalendar(cal);
    orderDate.setValue(xmlCalendar);
    row.getStringPairs().add(customerName);
    row.getNumberPairs().add(orderUnits);
    row.getDatePairs().add(orderDate);
                    

Finally, we'll send the actual Row across to Easy Insight. The first parameter of the call is the name of the data source we're going to send the data into and the second parameter is the Row itself. The third parameter is the one slightly tricky one here--if you specify true for changeDataSourceToMatch, Easy Insight will automatically create and/or update the data source on the server side to match with the data you've sent in. For development purposes, setting this parameter to true can rapidly accelerate your development time. However, we recommend that you set the parameter to false once you have stable code--otherwise, you stand a risk of accidentally changing your data structure in adverse ways when you're past the normal development process.

    port.addRow("Data Source Name", row, true);