NinjaCat’s variety of Smart Connectors offer the flexibility of bringing data into the platform from providers we:
- Do not have direct connections with
- Do have direct connectors with, but the desired dimensions or metrics are not available
In order to bring in this data with a smart connector, there are a few requirements that need to be met to make the data a good fit. This article will explore these base-level requirements.
Format of the Data
When bringing in data via a smart connector the data needs to be formatted in a column-based format. Depending on the smart connector that you are looking to use, these columns may exist in a raw data file (email, google sheets, FTP, S3, URL) or could also be in a database (SQL, BigQuery, etc.). In either of these situations, the headers of these columns need to be clearly defined and contain a combination of both dimensions and metrics that you would like to bring in. Additionally, it is important to note that if you are using a database Smart Connector (SQL, Big Query, etc.) that all of your data must be accessible via a basic query that does not contain any joins or transformations. All joins or transformations need to occur outside of NinjaCat in your database prior to being pulled in. If you are connecting your data via Snowflake it is important that you follow all best practices as outlined by Snowflake's documentation which can be found here.
Format of the File (For Email, FTP, S3, URL)
When working with a smart connector where we are either sending in or retrieving a file the supported formats for these connectors are .csv, .tsv, and .zip (with the exception of the URL integration which only supports direct links to .csv files). Please note that if you are using a .zip file it must have no subdirectories and the .zip file must unzip directly to a single .csv or .tsv file. Additionally, for the Email smart connector, we do support a link to a file in the email but this link must lead directly to a supported file type and have the word “report” somewhere in the destination URL. Lastly, it is important that the email smart connector follows the typical limitations of email attachments in that files should be no larger than 20Mb and that regardless of the Smart Connectors that you are using the sum of the individual files being processed by your agency on an individual day should not exceed 300Mb in total across all of your smart connectors.
To successfully report on and attribute data to an individual Account in NinjaCat there needs to be a column in the data that uniquely attributes an individual row of data to an individual Account (We call this an “Account Matching” column). Without this, there is no way to say who the data belongs to. Although some smart connectors support unique ways to attribute data to an individual account a good rule of thumb is that the values in this Account Matching column must contain one of the following:
- Account Name - The values in this field need to be a 100% exact match to the name as it is input in the Account Settings for your Account in NinjaCat in order to correctly attribute data. Note that capitalization, spacing, and punctuation do impact whether or not an Account name is a 100% direct match.
- External ID - The values in this field need to be a 100% exact match to the External ID field as it is input in the Account Settings for your Account in NinjaCat in order to correctly attribute data. Note that capitalization, spacing, and punctuation do impact whether or not an External ID is a 100% direct match. Also, note that each Account in NinjaCat can only utilize a single External ID Value. So if you have multiple data sources you would like to bring in and hope to use the External ID field for them, the value in that field needs to be the same across all of those data sources and directly match what you have input as the External ID in the Account Settings in NinjaCat.
- NinjaCat Account ID - The values in this field need to be a 100% exact match to the NinjaCat Account ID for the Account to which you would like to attribute the data. Typically using NinjaCat Account ID requires adding your NinjaCat Account IDs to your data source. You can find your NinjaCat Account IDs by using the “Export CSV” button located on the top right-hand corner when looking at your list of Accounts in NinjaCat.
- Send to Unique Email (Only available with the Email Smart Connector) - This unique way of matching data can be used if your file is formatted in a way that data can be processed by NinjaCat using the email smart connector but does not have a unique field to identify the Account. In order for this method of Account matching to work your files need to be separated in a way that each file that is going to be sent in only has a single NinjaCat Accounts worth of data. Each Account in NinjaCat will get a unique email address where you will send its data into. Also, note that if you have multiple email smart connectors using this matching method they have unique and separate email addresses from one another.
- No Value/-No Filter- (Only available with Google Sheets, FTP, S3, BiqQuery, SQL, URL ) - Using this Account matching type is the equivalent of saying there is no unique identifier in your data that ties a single line of data to a NinjaCat Account using one of the previously mentioned methods. This can present a problem in that with no filter essentially every NinjaCat Account has access to all of the data from this data source. This being said, a typical use case is to pair this data source with a Global Filter which is set up in a way that can filter this data by some sort of unique identifier in one of the fields present in the data (example: “Campaign Name” contains X). Note that using this method will require you to maintain Global Filters for yourAgency and all of your individual NinjaCat Accounts as well as apply this Global filter on any widget in which you use this data source.
Reports and dashboards in NinjaCat are date-based. When you go to pull a report or look at a dashboard you need to be able to specify what date range of data you would like to see. Due to this a date column is required for your Smart Connector. Without this column, NinjaCat is unable to tell when the data you are looking to see exists. The individual values in your date column need to correspond to a single day's worth of data for date attribution to work correctly.
Specifically for the email Smart Connector, there is a unique option for attributing the date of your data by the “date of email”. It is important to note that when using this feature the date of the email looks at the date that the file is processed and not the date that the email was sent. This is important to note as if you plan to use this feature you will need to schedule when your data will be sent accordingly to assure it is attributed to the correct date.
Additional things to consider
- Automation - Typically a major goal of using NinjaCat is to automate the amount of work that your agency is required to do to deliver your reports and/or dashboards to your clients. This automation is important to consider when thinking about how you will need to bring custom data into NinjaCat using a Smart Connector. If getting your custom data requires that you manually go into your provider to pull the data for your entire organization or individual accounts keep in mind how this will impact the requirements put on your team to generate your deliverables within the cadence required by your clients. As an example, if you hope to use dashboards for your clients it is important to note that your client can select single days of data which means that your team would need to update your data daily if the required data is coming in via a smart connector. In all possible situations, it is NinjaCat’s recommendation that you work with your providers to find a way to automate the delivery of your custom data into NinjaCat in a way that meets your clients' needs to avoid any requirements of manual work from your team.
- Consistency - It is important to note that for a custom data source to work correctly the data that it is receiving needs to remain consistent. This means that the number of columns, column headers, order, and labels needs to remain exactly the same each time new data is sent in / added. Any modifications to any of the previously mentioned criteria will at a minimum require the existing mapping to be edited and in many cases require a completely new smart connector to be set up.
Data that is not a good fit for NinjaCat:
The above data is an example of data that we might hope to send into NinjaCat via the email Smart Connection. However, looking at this data and keeping in mind the tips above we can see that it is not a good fit for NinjaCat for the following reasons:
- The data has no single column that uniquely identifies which account it is attributed to
- This data contains multiple unique “reports” with unique headers within one file rather than being a raw data file for an individual report with consistent headers
Data that is a good fit for NinjaCat:
The above data is another example of data that we might hope to send into NinjaCat via the email Smart Connection. Looking at this data we can see that it is a good fit for NinjaCat based on the tips above as it has:
- A clearly defined “Account” row (Assuming this exact account name also exists in the NinjaCat instance we would like to send the data to)
- A clearly defined “Date” row in which each line represents a single day’s worth of data
- Data that contains both dimensions and metrics
The next steps in this example would be to work with the provider of the data to see if it is possible to automate a scheduled recurring send of the data into NinjaCat via email to make this a perfect fit for the email Smart Connector.