| Name | tap-totango JSON |
| Version |
0.5.0
JSON |
| download |
| home_page | |
| Summary | `tap-totango` is a Singer tap for the Totango API, built with the Meltano Singer SDK. |
| upload_time | 2023-05-15 16:43:33 |
| maintainer | |
| docs_url | None |
| author | Edson Nogueira |
| requires_python | >=3.7.1,<3.12 |
| license | Apache 2.0 |
| keywords |
elt
totango
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# tap-totango
`tap-totango` is a Singer tap for the [Totango API](https://support.totango.com/hc/en-us/sections/360005893212-Totango-API). It extracts data from the Search API accounts, users, and events endpoints.
Built with the [Meltano Tap SDK](https://sdk.meltano.com) for Singer Taps.
## Installation
Install from PyPi:
```bash
pipx install tap-totango
```
Install from BitBucket:
```bash
pipx install git+https://bitbucket.org/indiciumtech/tap-totango.git@main
```
## Configuration
### Accepted Config Options
A full list of supported settings and capabilities in a reasonably readable form for this tap is available by running:
```bash
tap-totango --about --format=json
```
Each endpoint from the [Totango Search API](https://support.totango.com/hc/en-us/sections/360005893212-Totango-API) requires some parameters with the same name for the query, such as `terms`, `count`, and `offset`. In these cases, we provide settings namespaced by the stream name (e.g. `accounts_terms`, `users_offset` , etc.).
``` yaml
settings_group_validation: # An array of arrays listing the minimal valid group of settings required to use the connector
- - api_url
- auth_token
- events_terms
- events_count
- events_offset
- accounts_terms
- accounts_fields
- users_terms
- users_fields
settings:
- name: api_url
description: |
The url for the API services.
https://api.totango.com is for US services, whereas https://api-eu1.totango.com is for EU services.
documentation: https://support.totango.com/hc/en-us/articles/360048132792-Search-API-events-
kind: string
value: https://api.totango.com
- name: auth_token
description: |
The token to authenticate against the API service.
documentation: https://support.totango.com/hc/en-us/articles/203036939-Personal-Access-Token-and-Service-ID
kind: password
- name: events_terms
description: |
An array containing filter conditions to use for the events stream search.
documentation: https://support.totango.com/hc/en-us/articles/360048132792-Search-API-events-
kind: array
value: []
- name: events_count
description: |
The maximum number of accounts to return in the events result set.
The max. value for count is `1000`.
documentation: https://support.totango.com/hc/en-us/articles/360048132792-Search-API-events-
kind: integer
value: 1000
- name: events_offset
description: |
Page number (0 is the 1st-page).
documentation: https://support.totango.com/hc/en-us/articles/360048132792-Search-API-events-
kind: integer
value: 0
- name: account_id
description: |
Filter the events stream results for a specific account.
documentation: https://support.totango.com/hc/en-us/articles/360048132792-Search-API-events-
kind: string
- name: accounts_terms
description: |
An array containing filter conditions to use for the accounts stream search.
documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-
kind: array
value: []
- name: accounts_fields
description: |
List of fields to return as results.
Note that the account name and account-id are always returned as well.
documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-
kind: array
value: []
- name: accounts_count
description: |
The maximum number of accounts to return in the accounts result set.
The max. value for count is 1000.
documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-
kind: integer
value: 1000
- name: accounts_offset
description: |
Record number (0 states "start at record 0").
The record size can be defined using the count parameter (and limited to 1000).
Tip: To page through results, ask for 1000 records (count: 1000). If you receive 1000 records, assume there’s more, in which case you want to pull the next 1000 records (offset: 1000…then 2000…etc.). Repeat paging until the number of records returned is less than 1000.
documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-
kind: integer
value: 0
- name: accounts_sort_by
description: |
Field name to sort the accounts stream results set by.
documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-
kind: string
value: "display_name"
- name: accounts_sort_order
description: |
Order to sort the accounts stream results set by.
documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-
kind: string
value: "ASC"
- name: users_terms
description: |
An array containing filter conditions to use for the users stream search.
documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-
kind: array
value: []
- name: users_fields
description: |
List of fields to return as results.
Note that the account name and account-id are always returned as well.
documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-
kind: array
value: []
- name: users_count
description: |
The maximum number of accounts to return in the users result set.
The max. value for count is 1000.
documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-
kind: integer
value: 1000
- name: users_offset
description: |
Record number (0 states "start at record 0").
The record size can be defined using the count parameter (and limited to 1000).
Tip: To page through results, ask for 1000 records (count: 1000). If you receive 1000 records, assume there’s more, in which case you want to pull the next 1000 records (offset: 1000…then 2000…etc.). Repeat paging until the number of records returned is less than 1000.
documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-
kind: integer
value: 0
- name: users_sort_by
description: |
Field name to sort the users stream results set by.
documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-
kind: string
value: "display_name"
- name: users_sort_order
description: |
Order to sort the users stream results set by.
documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-
kind: string
value: "ASC"
```
### 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.
### Source Authentication and Authorization
You should create a [Totango API personal access token](https://support.totango.com/hc/en-us/articles/203036939-Personal-Access-Token-and-Service-ID) and provide it as the `auth_token` setting for the tap.
We recommend passing it as an environment variable. For instance, when using the tap with Meltano you should add the following line to your `.env` file:
``` bash
export TAP_TOTANGO_AUTH_TOKEN=< YOUR_PERSONAL_ACCESS_TOKEN >
```
## Usage
You can easily run `tap-totango` by itself or in a pipeline using [Meltano](https://meltano.com/).
### Executing the Tap Directly
```bash
tap-totango --version
tap-totango --help
tap-totango --config CONFIG --discover > ./catalog.json
```
## Developer Resources
Follow these instructions to contribute to this project.
### Initialize your Development Environment
```bash
pipx install poetry
poetry install
```
### Create and Run Tests
Create tests within the `tests` subfolder and
then run:
```bash
poetry run pytest
```
You can also test the `tap-totango` CLI interface directly using `poetry run`:
```bash
poetry run tap-totango --help
```
### Testing with [Meltano](https://www.meltano.com)
_**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._
Next, install Meltano (if you haven't already) and any needed plugins:
```bash
# Install meltano
pipx install meltano
# Initialize meltano within this directory
cd tap-totango
meltano install
```
Now you can test and orchestrate using Meltano:
```bash
# Test invocation:
meltano invoke tap-totango --version
# OR run a test `elt` pipeline:
meltano elt tap-totango target-jsonl
```
### SDK Dev Guide
See the [dev guide](https://sdk.meltano.com/en/latest/dev_guide.html) for more instructions on how to use the SDK to
develop your own taps and targets.
## Acknowledgements
Edson Nogueira thanks all members of the Meltaners group @ Indicium Tech, namely Cesar Rubim, Lucas Marques, Guilherme Tavares e Igor Benincá, for the professional guidance.
Raw data
{
"_id": null,
"home_page": "",
"name": "tap-totango",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.1,<3.12",
"maintainer_email": "",
"keywords": "ELT,totango",
"author": "Edson Nogueira",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/53/cf/77ae5eb9d79b11d6dbc704de09f5bde45238be5861cdf72ee3e9a35e9508/tap_totango-0.5.0.tar.gz",
"platform": null,
"description": "# tap-totango\n\n`tap-totango` is a Singer tap for the [Totango API](https://support.totango.com/hc/en-us/sections/360005893212-Totango-API). It extracts data from the Search API accounts, users, and events endpoints.\n\nBuilt with the [Meltano Tap SDK](https://sdk.meltano.com) for Singer Taps.\n\n## Installation\n\nInstall from PyPi:\n\n```bash\npipx install tap-totango\n```\n\nInstall from BitBucket:\n\n```bash\npipx install git+https://bitbucket.org/indiciumtech/tap-totango.git@main\n```\n\n## Configuration\n\n### Accepted Config Options\n\nA full list of supported settings and capabilities in a reasonably readable form for this tap is available by running:\n\n```bash\ntap-totango --about --format=json\n```\n\nEach endpoint from the [Totango Search API](https://support.totango.com/hc/en-us/sections/360005893212-Totango-API) requires some parameters with the same name for the query, such as `terms`, `count`, and `offset`. In these cases, we provide settings namespaced by the stream name (e.g. `accounts_terms`, `users_offset` , etc.).\n\n``` yaml\nsettings_group_validation: # An array of arrays listing the minimal valid group of settings required to use the connector\n- - api_url\n - auth_token\n - events_terms\n - events_count\n - events_offset\n - accounts_terms\n - accounts_fields\n - users_terms\n - users_fields\nsettings:\n - name: api_url\n description: |\n The url for the API services. \n \n https://api.totango.com is for US services, whereas https://api-eu1.totango.com is for EU services.\n documentation: https://support.totango.com/hc/en-us/articles/360048132792-Search-API-events-\n kind: string \n value: https://api.totango.com\n - name: auth_token\n description: |\n The token to authenticate against the API service.\n documentation: https://support.totango.com/hc/en-us/articles/203036939-Personal-Access-Token-and-Service-ID\n kind: password\n - name: events_terms\n description: |\n An array containing filter conditions to use for the events stream search.\n documentation: https://support.totango.com/hc/en-us/articles/360048132792-Search-API-events-\n kind: array\n value: []\n - name: events_count\n description: |\n The maximum number of accounts to return in the events result set.\n\n The max. value for count is `1000`.\n documentation: https://support.totango.com/hc/en-us/articles/360048132792-Search-API-events-\n kind: integer\n value: 1000\n - name: events_offset\n description: |\n Page number (0 is the 1st-page).\n documentation: https://support.totango.com/hc/en-us/articles/360048132792-Search-API-events-\n kind: integer\n value: 0\n - name: account_id\n description: |\n Filter the events stream results for a specific account.\n documentation: https://support.totango.com/hc/en-us/articles/360048132792-Search-API-events-\n kind: string\n - name: accounts_terms\n description: |\n An array containing filter conditions to use for the accounts stream search.\n documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-\n kind: array\n value: []\n - name: accounts_fields\n description: |\n List of fields to return as results. \n\n Note that the account name and account-id are always returned as well.\n documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-\n kind: array\n value: []\n - name: accounts_count\n description: |\n The maximum number of accounts to return in the accounts result set. \n\n The max. value for count is 1000.\n documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-\n kind: integer\n value: 1000\n - name: accounts_offset\n description: |\n Record number (0 states \"start at record 0\"). \n \n The record size can be defined using the count parameter (and limited to 1000). \n \n Tip: To page through results, ask for 1000 records (count: 1000). If you receive 1000 records, assume there\u2019s more, in which case you want to pull the next 1000 records (offset: 1000\u2026then 2000\u2026etc.). Repeat paging until the number of records returned is less than 1000.\n documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-\n kind: integer\n value: 0\n - name: accounts_sort_by\n description: |\n Field name to sort the accounts stream results set by.\n documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-\n kind: string\n value: \"display_name\"\n - name: accounts_sort_order\n description: |\n Order to sort the accounts stream results set by.\n documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-\n kind: string\n value: \"ASC\"\n - name: users_terms\n description: |\n An array containing filter conditions to use for the users stream search.\n documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-\n kind: array\n value: []\n - name: users_fields\n description: |\n List of fields to return as results. \n\n Note that the account name and account-id are always returned as well.\n documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-\n kind: array\n value: []\n - name: users_count\n description: |\n The maximum number of accounts to return in the users result set. \n\n The max. value for count is 1000.\n documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-\n kind: integer\n value: 1000\n - name: users_offset\n description: |\n Record number (0 states \"start at record 0\"). \n \n The record size can be defined using the count parameter (and limited to 1000). \n \n Tip: To page through results, ask for 1000 records (count: 1000). If you receive 1000 records, assume there\u2019s more, in which case you want to pull the next 1000 records (offset: 1000\u2026then 2000\u2026etc.). Repeat paging until the number of records returned is less than 1000.\n documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-\n kind: integer\n value: 0\n - name: users_sort_by\n description: |\n Field name to sort the users stream results set by.\n documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-\n kind: string\n value: \"display_name\"\n - name: users_sort_order\n description: |\n Order to sort the users stream results set by.\n documentation: https://support.totango.com/hc/en-us/articles/204174135-Search-API-accounts-and-users-\n kind: string\n value: \"ASC\"\n```\n\n### Configure using environment variables\n\nThis Singer tap will automatically import any environment variables within the working directory's\n`.env` if the `--config=ENV` is provided, such that config values will be considered if a matching\nenvironment variable is set either in the terminal context or in the `.env` file.\n\n### Source Authentication and Authorization\n\nYou should create a [Totango API personal access token](https://support.totango.com/hc/en-us/articles/203036939-Personal-Access-Token-and-Service-ID) and provide it as the `auth_token` setting for the tap.\n\nWe recommend passing it as an environment variable. For instance, when using the tap with Meltano you should add the following line to your `.env` file:\n\n``` bash\nexport TAP_TOTANGO_AUTH_TOKEN=< YOUR_PERSONAL_ACCESS_TOKEN >\n```\n\n## Usage\n\nYou can easily run `tap-totango` by itself or in a pipeline using [Meltano](https://meltano.com/).\n\n### Executing the Tap Directly\n\n```bash\ntap-totango --version\ntap-totango --help\ntap-totango --config CONFIG --discover > ./catalog.json\n```\n\n## Developer Resources\n\nFollow these instructions to contribute to this project.\n\n### Initialize your Development Environment\n\n```bash\npipx install poetry\npoetry install\n```\n\n### Create and Run Tests\n\nCreate tests within the `tests` subfolder and\n then run:\n\n```bash\npoetry run pytest\n```\n\nYou can also test the `tap-totango` CLI interface directly using `poetry run`:\n\n```bash\npoetry run tap-totango --help\n```\n\n### Testing with [Meltano](https://www.meltano.com)\n\n_**Note:** This tap will work in any Singer environment and does not require Meltano.\nExamples here are for convenience and to streamline end-to-end orchestration scenarios._\n\nNext, install Meltano (if you haven't already) and any needed plugins:\n\n```bash\n# Install meltano\npipx install meltano\n# Initialize meltano within this directory\ncd tap-totango\nmeltano install\n```\n\nNow you can test and orchestrate using Meltano:\n\n```bash\n# Test invocation:\nmeltano invoke tap-totango --version\n# OR run a test `elt` pipeline:\nmeltano elt tap-totango target-jsonl\n```\n\n### SDK Dev Guide\n\nSee the [dev guide](https://sdk.meltano.com/en/latest/dev_guide.html) for more instructions on how to use the SDK to\ndevelop your own taps and targets.\n\n## Acknowledgements\n\nEdson Nogueira thanks all members of the Meltaners group @ Indicium Tech, namely Cesar Rubim, Lucas Marques, Guilherme Tavares e Igor Beninc\u00e1, for the professional guidance.\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "`tap-totango` is a Singer tap for the Totango API, built with the Meltano Singer SDK.",
"version": "0.5.0",
"project_urls": null,
"split_keywords": [
"elt",
"totango"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8ab43db81d884bb59ae1f5af603dc2268d9f99f2c6a637ce0c563ff55c3ee3f4",
"md5": "6f049c71e43b8906f33bf528a608e2b8",
"sha256": "153d98d63d8c44d8f863caea660b3a727aa4006ee6bae7a6c8f206e12c6b1373"
},
"downloads": -1,
"filename": "tap_totango-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6f049c71e43b8906f33bf528a608e2b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7.1,<3.12",
"size": 10306,
"upload_time": "2023-05-15T16:43:31",
"upload_time_iso_8601": "2023-05-15T16:43:31.521495Z",
"url": "https://files.pythonhosted.org/packages/8a/b4/3db81d884bb59ae1f5af603dc2268d9f99f2c6a637ce0c563ff55c3ee3f4/tap_totango-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "53cf77ae5eb9d79b11d6dbc704de09f5bde45238be5861cdf72ee3e9a35e9508",
"md5": "db45ab8d644c06e020e8ed39c42f6d40",
"sha256": "4fd18e02042858260dfdda8c76044fea52006196bf233bdc17da30df64be56f0"
},
"downloads": -1,
"filename": "tap_totango-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "db45ab8d644c06e020e8ed39c42f6d40",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.1,<3.12",
"size": 10232,
"upload_time": "2023-05-15T16:43:33",
"upload_time_iso_8601": "2023-05-15T16:43:33.367941Z",
"url": "https://files.pythonhosted.org/packages/53/cf/77ae5eb9d79b11d6dbc704de09f5bde45238be5861cdf72ee3e9a35e9508/tap_totango-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-15 16:43:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "tap-totango"
}
