tap-dayforce

A Singer tap for extracting data from the Dayforce REST API v1.

Installation

Since package dependencies tend to conflict between various taps and targets, Singer recommends installing taps and targets into their own isolated virtual environments:

Install Dayforce Tap

$ python3 -m venv ~/.venvs/tap-dayforce
$ source ~/.venvs/tap-dayforce/bin/activate
$ pip3 install tap-dayforce
$ deactivate

Install Stitch Target (optional)

$ python3 -m venv ~/.venvs/target-stitch
$ source ~/.venvs/target-stitch/bin/activate
$ pip3 install target-stitch
$ deactivate

Configuration

The tap accepts a JSON-formatted configuration file as arguments. This configuration file has four required fields:

1. username: A valid Dayforce web services user account username.
2. password: A valid Dayforce web services user account password.
3. client_namespace: A valid client name (e.g. Company Name) that will be inserted into the request URL.
4. start_date: A date to fall back on when no state.json is provided. This determines how far back the tap looks for data within the Dayforce platform.

It's important to note that the Role attached to the User Account used in the configuration file must have at minimum the "Web Services" feature, as well as the "Read Data" sub-feature enabled.

An bare-bones Dayforce configuration may file may look like the following:

{
  "username": "foo",
  "password": "bar",
  "client_namespace": "foo_bar",
  "start_date": "2019-01-01T00:00:00Z"
}

Streams

The current version of the tap syncs four distinct Streams:

1. Employees: Endpoint Documentation
2. EmployeePunches: Endpoint Documentation
3. EmployeeRawPunches Endpoint Documentation
4. PaySummaryReport Endpoint Documentation

Discovery

Singer taps describe the data that a stream supports via a Discovery process. You can run the Dayforce tap in Discovery mode by passing the --discover flag at runtime:

$ ~/.venvs/tap-dayforce/bin/tap-dayforce --config=config/dayforce.config.json --discover

The tap will generate a Catalog to stdout. To pass the Catalog to a file instead, simply redirect it to a file:

$ ~/.venvs/tap-dayforce/bin/tap-dayforce --config=config/dayforce.config.json --discover > catalog.json

Discovery mode will not select all streams for replication by default. To instruct Discovery mode to select all streams for replication, use the --select-all flag:

$ ~/.venvs/tap-dayforce/bin/tap-dayforce --config=config/dayforce.config.json --discover --select-all > catalog.json

Sync to stdout

Running a tap in Sync mode will extract data from the various selected Streams. In order to run a tap in Sync mode and have messages emitted to stdout, pass a valid configuration file and catalog file:

$ ~/.venvs/tap-dayforce/bin/tap-dayforce --config=config/dayforce.config.json --catalog=catalog.json

The tap will emit occasional Metric, Schema, Record, and State messages. You can persist State between runs by redirecting messages to a file:

$ ~/.venvs/tap-dayforce/bin/tap-dayforce --config=config/dayforce.config.json --catalog=catalog.json >> state.json
$ tail -1 state.json > state.json.tmp
$ mv state.json.tmp state.json

Sync to Stitch

You can also send the output of the tap to Stitch Data for loading into the data warehouse. To do this, first create a JSON-formatted configuration for Stitch. This configuration file has two required fields:

1. client_id: The ID associated with the Stitch Data account you'll be sending data to.
2. token: The token associated with the specific Import API integration within the Stitch Data account.
3. small_batch_url: Default to "https://api.stitchdata.com/v2/import/batch"
4. big_batch_url: Default to "https://api.stitchdata.com/v2/import/batch"
5. batch_size_preferences: Default to {}

An example configuration file will look as follows:

{
  "token": "foobar",
  "client_id": 12345,
  "small_batch_url": "https://api.stitchdata.com/v2/import/batch",
  "big_batch_url": "https://api.stitchdata.com/v2/import/batch",
  "batch_size_preferences": {}
}

Once the configuration file is created, simply pipe the output of the tap to the Stitch Data target and supply the target with the newly created configuration file:

$ ~/.venvs/tap-dayforce/bin/tap-dayforce --config=config/dayforce.config.json --catalog=catalog.json --state=state.json | ~/.venvs/target-stitch/bin/target-stitch --config=config/stitch.config.json >> state.json
$ tail -1 state.json > state.json.tmp
$ mv state.json.tmp state.json

Contributing

1. The first step to contributing is getting a copy of the source code. First, fork tap-dayforce on GitHub. Then, cd into the directory where you want your copy of the source code to live and clone the source code:

$ cd repos
$ git clone [email protected]:YourGitHubName/tap-dayforce.git

2. Now that you have a copy of the source code on your machine, create and activate a virtual envionment for tap-dayforce:

$ python3 -mvenv ~/.venvs/tap-dayforce
$ source ~/.venvs/tap-dayforce/bin/activate

2. Once inside the virtual environment, run make dev_install at the root of the repository:

$ (tap-dayforce) make dev_install

3. Run the tox testing suite in the appropriate python environment to ensure things are working properly:

$ (tap-dayforce) tox -e py37

To format your code using isort and flake8 before commiting changes, run the following commands:

$ (tap-dayforce) make isort
$ (tap-dayforce) make flake8

Once you've confirmed that your changes work and the testing suite passes, feel free to put out a PR!