All custom integration / ETL ought to behave/operate in the exact same way. Adhering to this documentation will allow this
Tokens:
- extractor_to_avalara_token: Formerly known as connector_2_tf_token, identifies the extractor and restricts access to environments / version of TF API the extractor is certified for (see below for token usage in header)
- avalara_to_extractor_token: Formerly known as the trustfile_2_connector_token, authorizes Trustfile (and other consumers), and Extractor to access operate the extractor micro-service API
- connectionId: identifies and authorizes access to the Trustfile (or CUP) company to push data into. Mapped to a UUID Company Token in database
Extractor
- Extractor will be the source of truth for all extractor tokens etc
- Disabling/updating an extractor will go through Extractor
Extractor Management API responsibility
- Integrating with Extractor Items API
- Integrating with host system API, including authorization (typically something like oAuth)
- ETL of sales/refunds/tax/shipping data into TrustFile data model
- Basic management of user data sources: CRUD, enable/disable/status
- Scheduling and load balancing of users data synchronization
- Data integrity. It is the responsibility of the extractor micro-service to know what data has been processed by Extractor.
Extractor Management API is not responsible for
- User experience
- Branding of experience (aside from the popup for authentication with host system)
Provisioning of TFO by extractors - workflow
- Create a user in the extractor db, enabled should be false, startDate should be null (extractor should not be syncing)
- Call TFO signup: /v4/company/signup
- In TFO, a modal will pop up which will allow the user to set the startDate, which will call PUT /connections/{connectionId} with the following example body: { "enabled": true, "startDate": "2018-04-01" }
Hosting / Language
- All extractors will be hosted and operated from the Heroku PaaS
- Language: choose between - Ruby/Node/Java
- DB: Postgres (on heroku)
Dates and Timestamps
- Dates are in yyyy-mm-dd format
- Timestamps are in the ISO format: 2015-07-06T22:26:28+00:00
- Timestamps are in UTC +00:00 timezone
Configs
Put localization configs (specific to a given environment) into environment variables. Document the required variables in the README.md of the project. https://devcenter.heroku.com/articles/config-vars
Security:
API requests except orangez/health are authorized with Header param
Authorization: Bearer avalara_to_extractor_token