tap-aircall

tap-aircall is a Singer tap for extracting data from the aircall API.

Built with the Meltano Tap SDK for Singer Taps.

Capabilities

• catalog
• state
• discover
• about
• stream-maps
• schema-flattening
• batch

Settings

Setting	Required	Default	Description
api_token	True	None	The token to authenticate against the API service
api_id	True	None	The id to authenticate against the API service
start_date	True	None	The earliest record date to sync in UTC Timezone
end_date	False	None	The lastest record date to sync in UTC Timezone
stream_maps	False	None	Config object for stream maps capability. For more information check out Stream Maps
stream_map_config	False	None	User-defined config values to be used within map expressions
flattening_max_depth	False	None	'True' to enable schema flattening and automatically expand nested properties
flattening_max_depth	False	None	The max depth to flatten schemas

A full list of supported settings and capabilities for this tap is available by running:

poetry run tap-aircall --about

Installation

• Developer TODO: Update the below as needed to correctly describe the install procedure. For instance, if you do not have a PyPi repo, or if you want users to directly install from your git repo, you can modify this step as appropriate.

pipx install tap-aircall

Configuration

Authorization Method

To run tap-aircall, you will need an API ID and an API token. Create a file named .secret/config.json and fill it with an array containing the following fields:

• api_id
• api_token
• start_date
• end_date

The config file should look like this:

{
    "api_id": "123456789",
    "api_token": "ABCDEFGHI",
    "start_date": "2023-08-07 09:30:00",
    "end_date": "2023-08-07 09:30:00",
  }

Configure using environment variables

This Singer tap will automatically import any environment variables within the working directory's .env if the --config=ENV is provided, such that config values will be considered if a matching environment variable is set either in the terminal context or in the .env file.

Usage

You can easily run tap-aircall by itself or in a pipeline using Meltano.

Executing the Tap Directly

You can launch the tap in two different ways:

1. catalog: this option retrieves all data starting from the date specified in .secrets/config.json and updates the samples/state.json file with the latest retrieved item.

./tap-aircall.sh catalog

2. state: this option retrieves all data starting from the state indicated in samples/state.json.

./tap-aricall.sh state

Developer Resources

Initialize your Development Environment

pipx install poetry
poetry install

Create and Run Tests

Create tests within the tap_aircall/tests subfolder and then run:

poetry run pytest

You can also test the tap-aircall CLI interface directly using poetry run:

poetry run tap-aircall --help

Testing with Meltano

Note: This tap will work in any Singer environment and does not require Meltano. Examples here are for convenience and to streamline end-to-end orchestration scenarios.

Your project comes with a custom meltano.yml project file already created. Open the meltano.yml and follow any "TODO" items listed in the file.

Next, install Meltano (if you haven't already) and any needed plugins:

# Install meltano
pipx install meltano
# Initialize meltano within this directory
cd tap-aircall
meltano install

Now you can test and orchestrate using Meltano:

# Test invocation:
meltano invoke tap-aircall --version
# OR run a test `elt` pipeline:
meltano elt tap-aircall target-jsonl

SDK Dev Guide

See the dev guide for more instructions on how to use the SDK to develop your own taps and targets.

Utilization

This tap can be used in three differents ways:

• Any configuration: fetch all available data for each enable stream
• start_date/end_date: fetch data since/until these dates according to the replication date key
• state: fetch data since the last update bookmarks according to the replication date key

Nevertheless, it is important to note that any update made to an element in Aircall will not be considered when retrieving data via state. This is because there is no replication key such as updated_at. In other words, if one wishes to be able to retrieve all data, including updates, it is necessary to run the tap on the entire dataset every time. The only stream for which there are no updates in the strictest sense (or at least no interesting updates to retrieve) is the Call stream. This stream also happens to be the one containing the most data by far.
Therefore, it is advised for the user to use full replication for the Users, Tags, Teams, Contacts, and Numbers streams, but to use state for the Calls stream.

Streams	Replication Key	Documation URL	Enable
Users	created_at	User overview	✔️
User	None	User overview
Calls	started_at	Call overview	✔️
Call	started_at	Call overview
Teams	None	Teams overview	✔️
Team	None	Teams overview
Numbers	created_at	Number overview	✔️
Number	None	Number overview	✔️
Contacts	created_at	Contact overview	✔️
Contact	None	Contact overview
Tags	None	Tag overview	✔️
Tag	None	Tag overview