How to Contribute to OWOX Data Marts (Even If You’ve Never Coded)

Have you ever wanted to extend your reporting tools but felt blocked by not knowing how to code? With OWOX Data Marts, you don’t need years of developer experience to make a real impact. The community edition is designed so that anyone, analysts, marketers, or spreadsheet builders, can create and share connectors that power useful reports.

This guide will walk you through building a connector step by step, using Google Apps Script and GitHub. In less than 30 minutes, you’ll be able to publish your work, share it with others, and strengthen both your skills and the OWOX community.

Why Community Contributions Matter for Data Marts

Community contributions make OWOX Data Marts more powerful and relevant. Each new connector strengthens the ecosystem, shortens delivery time, and solves problems that matter in real workflows.

• Accelerate Connector Availability: Community-built connectors bring new data sources faster, without waiting on vendor roadmaps or internal dev cycles.
• Empower Non-Developers: Contributions from analysts and no-code builders prove that coding isn’t a barrier, encouraging wider participation in data stack growth.
• Solve Niche Data Needs: Many community connectors target regional or underserved APIs, filling critical gaps left by commercial ETL tools.
• Ensure Real-World Relevance: Shared connectors are based on actual reporting use cases, making them instantly useful to other teams.
• Encourage Reuse and Improvement: Open-source code enables connectors to be forked, improved, and stress-tested, resulting in stronger, long-term solutions.
• Career & Visibility Benefits: Contributors gain GitHub portfolio projects, professional recognition, and valuable skills in open-source collaboration.
• Sustainability & Impact: Active contributions ensure the project evolves, stays relevant, and continues to deliver value over time.

Essential Requirements to Contribute to OWOX Data Marts

Before you can build and share a connector, a few essentials must be in place. These requirements ensure you have the right access, tools, and basic knowledge to get started smoothly with OWOX Data Marts contributions.

Google Account with Sheets Access

A Google account is the first requirement for contributing to OWOX Data Marts. Google Sheets serves as your primary workspace, where you configure connectors, run tests, and view imported data. With Sheets, you can easily validate results, troubleshoot issues, and share your work with others in the community.

GitHub Account for Collaboration

A GitHub account is required to fork the OWOX Data Marts repository, manage changes, and submit your connector through a pull request. GitHub also enables collaboration, allowing you to invite others as contributors, share feedback, and track versions, making it easier to refine and maintain connectors as part of an open-source community. 

Basic Familiarity with Google Apps Script

A basic understanding of Google Apps Script is essential for customizing OWOX connector templates. You’ll use it to integrate REST APIs, edit logic, and implement functions like fetchData(). Always copy the shared library before making modifications, ensuring your changes aren’t accidentally overwritten during future updates or template refreshes.

Access to a REST API for Data Fetching

Every connector needs a data source, and that’s where REST APIs come in. By obtaining API keys or tokens, you can call endpoints to fetch JSON data from platforms like GitHub or any Ads platform. REST principles, statelessness, authentication, and cacheable responses ensure reliable access, making APIs the foundation of your connector’s functionality.

Understand the File Structure

Each connector relies on a clear and structured design. The Config sheet stores setup parameters, while Code.gs handles script logic. An Apps Script menu provides control options for managing runs and credentials. The library itself is split into Core/ and Sources/ folders. All connectors run in the V8 runtime with UTC timezone for consistency.

Step-by-Step: Build and Submit a Connector in 30 Minutes

This walkthrough is designed for beginners with no coding background. Using prebuilt OWOX templates and the GitHub API as an example, you’ll learn how to configure, test, and publish a working connector in under 30 minutes.

Want to see the whole process in action? Watch our step-by-step demo on building a GitHub connector in just 25 minutes.

👉 Watch the video here and follow along as we set up, test, and publish a working connector.

Step 1: Set Up Your Google & GitHub Accounts (No Coding Needed)

This first step is about preparing the basic accounts and skills you’ll need. Without these, you can’t build, test, or publish your connector effectively.

Before starting, here are the requirements to develop and publish a connector:

• Google Account: Needed to work in Google Sheets and ingest data using Apps Script.
• GitHub Account: Required not just for GitHub APIs, but also to join discussions, ask questions, and publish your connector to the community.
• Basic Apps Script Knowledge: A light understanding helps you edit templates and implement functions without difficulty.

Step 2: Check If Your Data Source Already Exists

Before building a connector, confirm whether it already exists in the OWOX GitHub repo. This saves time and avoids duplication. If it’s not available, you’ll know you’re creating something new and valuable for the community.

• Browse the repo’s list of available data sources.
• Check the Discussions and Issues tabs for mentions of your API.
• If it’s not listed, proceed with building your connector.

Step 3: Understand the Metrics and Reporting Needs

In this step, you define exactly what the connector should deliver.

Business users often make broad requests, so it’s your job to turn them into concrete requirements: which metrics to pull, how often to refresh, and how the report should look.

• Ask the right questions: “What dimensions and metrics do you need?” “How often should the data update?” “What should the report look like?”
• Define clear outputs: For example, track stars and contributors from GitHub, update daily at midnight, and log results as one row per day.
• Plan refresh timing carefully: “Daily” can mean different things. If users check reports at 9 AM, but your connector runs at 10 AM, they’ll see outdated data. Consider hourly runs for reliability.
• Avoid duplicates: If running more than once per day, define a unique key so updates replace existing rows instead of creating duplicates.

Step 4: Handle Google Apps Script’s Scheduling Limitations

Before scheduling your connector, it’s important to understand how Google Apps Script works. Triggers can only run hourly, not at an exact time like 09:17 AM. This means your script might execute at slightly different times each day, which can cause reporting issues.

To avoid problems:

• Expect time variation: Runs may shift between minutes on each execution.
• Prevent duplicate rows: Use a unique key (such as date + identifier).
• Apply logic in your script: If a row for today already exists, update it; otherwise, insert a new one.

Step 5: Define a Unique Key to Avoid Duplicate Rows

In this step, you’ll set rules that prevent duplicate rows when your connector runs more than once per day. A unique key identifies each record, allowing the script to determine whether to update an existing row or create a new one.

• GitHub Example: Use the date as the key. If the connector runs five times on June 2, only one row for June 2 will remain.
• Composite Key Example: Some connectors require multiple fields. In the Facebook Ads connector, the key combines:
  
  • ad_id
  • date_start
  • date_stop

This approach ensures every row is unique, even across repeated runs.

Step 6: Get Your API Token and Test the Endpoint

To connect your script with the GitHub API, you’ll need a Personal Access Token. This token authenticates your requests and ensures you can pull the data safely. You don’t need deep API knowledge; basic testing tools are enough.

How to create a GitHub token:

• Go to GitHub → Settings → Developer settings → Personal access tokens (classic).
• Click Generate new token and give it a clear name (e.g., OWOX Data Marts GitHub Demo).
• Set an expiration date (e.g., one year) and choose read-only access.
• Click "Generate token" and copy it to a safe location.

Testing the API:

• To fetch stars: call the GitHub repository API and check the stargazers_count field in the JSON response.
• To fetch contributors: call the /contributors endpoint, then use Apps Script to count the number of entries in the returned list.

Step 7: Use the Right Template to Set Up Your Connector

In this step, you’ll set up the actual integration using OWOX templates. Always pick the right template for your API type.

• Template options: Use the 
  
  • Public Endpoint template for open APIs.

• Use the Token-Based Endpoint template for APIs requiring authentication.

• Copy correctly: Don’t create Drive shortcuts. Open each file manually and choose File → Make a copy to save them to your own Google Drive.
• Update the Config sheet: Remove unnecessary rows and add new parameters. For GitHub, add:
  
  • Name: repository
  • Value: owox/owox-data-marts
  • Description: Name of the repository to fetch data from

This ensures your connector pulls the right repository data dynamically.

Google Sheets

Data sources

Free Facebook Ads Connector to Google Sheets

Download template

Step 8: Securely Store Your API Token (Without Exposing It)

Authentication is required to fetch GitHub data, but tokens must be stored safely. Never put them in sheet cells or hardcode them into scripts. Instead, use Document Properties in Apps Script to keep tokens private and secure.

How to store your token securely:

• Open the Apps Script editor from your copied Sheet and rename the project (e.g., GitHub Connector Demo).
• Check if a manageCredentials() function exists; if not, copy it from another connector. This function prompts you for the token, stores it in Document Properties, and hides it from sheets and source code.

• In your sheet, click Manage Credentials from the custom menu, paste the token, and it will be stored securely.

Step 9: Customize Connector and Pipeline Logic

This step defines how your connector behaves and how the pipeline processes data. Both files work together but serve different purposes.

Connector File:

• Create a new GitHubConnector.
• Require the repository name as an input parameter.
• Validate inputs early (e.g., ensure the repo string contains “/”).
• Define how data is fetched and transformed before passing it forward.

Pipeline File:

• Controls import flow, scheduling, and error handling.
• Manages the process of injecting data into the spreadsheet.
• By default, pipelines expect a date range (startDate, endDate). Since GitHub only returns the current state, override this logic to avoid unnecessary parameters.

Step 10: Write the fetchData Function to Retrieve Your Data

The heart of every connector is the fetchData() function. This function handles the whole process of retrieving data from the API and preparing it for use in Google Sheets.

What it does:

• Pulls configuration values such as the repository name.
• Loads your GitHub token securely from Document Properties.
• Sends API requests to the GitHub endpoints.
• Parses the response into structured rows.
• Builds clean output for your spreadsheet.

Example: GitHub Connector

• Stars → Call GET https://api.github.com/repos/{owner}/{repo} and extract the stargazers_count field.
• Contributors → Call GET https://api.github.com/repos/{owner}/{repo}/contributors?per_page=1000 and count the number of items in the returned list. 
•  GitHub does not provide a total_contributors field, so you must calculate it manually in your script.

Access Token Handling:
Always retrieve the token securely with:

1const token = getCredentials().github_token.value;

‍

Step 11: Schedule Your Connector to Run Automatically

Once your connector runs correctly on demand, the next step is to automate it with a time-driven trigger in Google Apps Script. This ensures your data refreshes daily or hourly without manual effort.

How to schedule the connector:

1. Open your Apps Script file → Extensions → Apps Script.
2. Go to the Triggers panel (represented by a clock icon).
3. Click + Add Trigger.
4. Configure the settings:
   
   • Function to run → importData
   • Deployment → Head
   • Event source → Time-driven
   • Type of trigger → Hour timer (every hour)

5. Click Save.
   
   

Your connector will now automatically fetch GitHub data and update the sheet on a scheduled basis.

Step 12: Publish Your Connector via GitHub PR

Once your connector is tested and ready, it’s time to contribute it back to the community. Start by forking the OWOX repository, creating a new branch, committing your changes, and pushing them to GitHub.

Next, open a Pull Request with a clear description of your connector and the data source. A CLA bot will prompt you to sign the Contributor License Agreement (CLA) before your contribution is reviewed and merged.

Troubleshooting & Debugging Common Issues While Building a Connector

Even with the right setup, some common problems arise when developing connectors. Below are the typical issues you may face and how to resolve them quickly.

Use Run History to Debug Failures

⚠️ Error: Connectors can fail without obvious signs, leaving reports incomplete or outdated. Failures may occur due to invalid parameters, token issues, or API rate limits; however, without logs, it’s difficult to determine the root cause.

✅ Solution: Open the Run History tab in Apps Script or OWOX Data Marts. Review timestamps, error messages, and status codes to quickly trace failures and identify the exact reason the connector run failed.

Fix Common Token Errors (Expired or Invalid)

⚠️ Error: Expired or invalid tokens are the most common reason connectors stop working. Errors such as invalid_grant, expired access, or missing API keys often occur when tokens are hardcoded, saved in spreadsheet cells, or not refreshed on time.

✅ Solution: Refresh tokens regularly and store them only in Document Properties, never in plain text. Use manageCredentials() to verify values. Before triggering, test API requests with tools like Boomerang, a browser, or a terminal to confirm credentials are active.

Handle API Errors and Missing Data

⚠️ Error: APIs may throttle requests, change endpoints, or return incomplete data, causing broken connectors and missing fields in your reports.

✅ Solution: Add retry logic, pagination, and custom error handling in fetchData(). Wrap requests in try/catch blocks for 4xx/5xx responses. Use Logger.log() or append error rows to your sheet to track and debug failures effectively.

Resolve PR Rejection Issues

⚠️ Error: GitHub Pull Requests are often rejected due to missing documentation, unclear function names, untested logic, or unsigned Contributor License Agreements (CLA).

✅ Solution: Review the connector template guidelines, maintain consistent naming and formatting, and ensure tests run properly. Follow GitHub reviewer comments, make corrections, and update your branch. Once fixes are applied, reopen and resubmit your PR for acceptance.

Advanced Contributor Guide: Build a New Connector from Scratch

For technical contributors, this guide explains how to extend the OWOX codebase. With APIs constantly evolving, no template fits every case. Below are the key areas to focus on when creating new connectors or adjusting existing ones.

Explore the File Structure: Sheets, Scripts, and Configs

Each connector relies on a clear structure that links Sheets and Apps Script. The Config tab defines parameters, the custom menu controls actions, and Code.gs connects everything by calling library functions. 

Together, they provide a user-friendly interface while handling data fetch logic in the background. You can copy and customize these files as needed.

Link and Customize the Apps Script Library

To customize a connector safely, link or copy the shared Apps Script library. Templates already include the correct library, but blank Sheets require manual linking in Code.gs. Always make your own copy before editing. 

The library contains:

• Core/ – Shared logic used across all connectors.
• Sources/ – Data source–specific logic you may need to modify.
• UTC timezone – Required for consistent scheduling and data accuracy.
• V8 runtime – Mandatory for proper execution of the scripts.

Create a New Connector Folder in the Source Code

When building a connector from scratch, you need to set up a dedicated folder in the source code. 

• Start copying the Google Sheets and Apps Script files from the Templates folder. 

• Replace YOUR_DATA_SOURCE with your actual source name, then add methods based on requirements. 
• Finally, create a new folder under packages/connectors/src/Templates/ and update manifest.json with the correct data source title.

Define Connector, Source, and Storage Classes (UML Explained)

When building a connector from scratch, it’s important to understand how the pieces fit together. OWOX uses a UML-style modular design to describe the relationship between components. 

UML (Unified Modeling Language) is a way to visualize how different parts of a system interact, making it easier to maintain structure and consistency across connectors.

In this design, every connector has three main building blocks:

• Connector: Orchestrates data transfer by linking Config, Source, and Storage. It must extend AbstractConnector and is stored in src/Sources/[SOURCE_NAME]/Connector.js.
• Source: Fetches data from the API and extends AbstractSource. Implements fetchData() for API-specific requests, handles authentication, and transforms raw responses into clean rows for the connector.
• Storage: Manages how data is saved and updated. Extends AbstractStorage, with Google Sheets currently supported. Applies unique key logic to insert or update rows, ensuring reliable and duplicate-free storage.

Sign the OWOX Contributor License Agreement (CLA)

All contributors must sign the OWOX CLA before their pull request is merged. This agreement clarifies intellectual property rights, protects both you and the community, and does not restrict the use of your own contributions elsewhere. A bot will prompt you after opening a PR. If you cannot sign, open an issue instead of submitting code.

For more details, please review the full OWOX CLA.

Pull Request authors must sign the OWOX CLA. It will show up in an automated comment after you create a PR.

Why OWOX Connectors Offer the Best Balance of Speed, Control, and Cost

Choosing the right connector matters. OWOX connectors are designed to be fast to set up, flexible to customize, and cost-efficient to run. Below are the key reasons they strike the best balance for analysts and teams.

ROI Snapshot – Build Faster, Refresh Automatically

With OWOX templates and Apps Script, you can create a working connector in under 30 minutes, no backend setup required. Once built, add hourly or daily triggers to automate refreshes, thereby eliminating the need for manual exports or clicks. Data flows directly into Google Sheets, giving you immediate insights. 

Compared to tools like Airbyte or Meltano, setup is lighter, and unlike static CSV imports, OWOX connectors keep reports dynamic and always up to date.

Full Control Over Logic and API Behavior

With OWOX connectors, you’re not limited by the restrictions of no-code ETL tools. Every part of the data flow is under your control. You can define pagination rules, add retry logic, transform responses, and handle errors directly in your fetchData() and startImportProcess() functions. 

This flexibility means you decide how APIs are called, how failures are managed, and how data is prepared, ensuring the connector behaves exactly as your reporting workflow requires.

Automate Refresh with Time-Based Triggers

OWOX connectors let you keep reports up to date without lifting a finger. Using Google Apps Script’s time-driven triggers, you can schedule refreshes to run hourly, daily, or weekly, depending on your needs.

 Once set, the connector automatically fetches and updates your Google Sheets, ensuring that business users always see the freshest data. No more manual clicks or exports - just consistent, reliable updates that align with your team’s reporting schedule.

Zero Platform Costs for Small Teams

OWOX connectors rely on Google Sheets and Apps Script, both of which are free for individual use and small teams. This means no subscription tiers, credits, or hidden charges. Unlike Airbyte or other premium tools, you can start building and refreshing connectors without worrying about costs. For growing teams, this zero-cost model enables experimentation, iteration, and ongoing reporting to be sustainable.

Full Customization & Control

With a script-based approach, you own the entire data flow. From fetch logic to pagination, retry behavior, and error handling, everything can be tailored to your needs. Unlike black-box no-code tools, everything is transparent, providing you with complete transparency and flexibility.

Scalability & Extensibility on Your Terms

Your connectors evolve at your pace. Add new API endpoints, extend transformations, or integrate additional data sources as requirements grow. With no vendor lock-in or restricted features, you define the extent of your reporting stack, maintaining full ownership of scalability and functionality.

OWOX connectors enable you to move as quickly as no-code ETL tools, while keeping costs low, logic transparent, and control in your hands. Here’s how OWOX + Apps Script compares with popular ETL options:

Explore the OWOX Data Marts (Community Edition) Built for Data Analysts

OWOX Data Marts (Community Edition) is designed for analysts who require speed, flexibility, and full control, without the need for expensive tools or vendor lock-in. Whether you’re extending existing connectors or building new ones, the community edition provides ready-to-use GitHub templates and detailed guides to help you contribute confidently. 

By publishing your own connectors, you not only strengthen your reporting stack but also support the open-source community. It’s free, transparent, and designed for analysts who want more from their data workflows.

👉 Explore OWOX Community Edition on GitHub