Staffjoy is shutting down, so we are open-sourcing our code. This version of our V1, intended for on-demand companies and call centers, has been heavily modified so that Staffjoy customers may continue using the software. It is a full workforce management suite, including time off requests, compliance management, and clock-in. Workers can even clock in and claim shifts. If you're managing small businesses and want only basic schedulding with text message support, please use Staffjoy V2
API Documentation is available on staffjoy-suite.readme.io.
The authors of the original code were @philipithomas, @andhess, and @bahador. This is a fork of the internal repository. For security purposes, the Git history has been squashed.
If you are using this repo for commercial purposes, please review the Highcharts licensing requirements for commercial use, in addition to the LICENSE
file in this repo.
Staffjoy Suite is open-source workforce management software for large teams.
This table intends to explain the main requirements specified in app/config.py
. This configuration file can be manually edited, but be careful to not commit secret information into the git repository. Please explore the config file for full customization info.
Name | Description | Example Format |
---|---|---|
ENV | "prod", "stage", or "dev" to specify the configuration to use. When running the code, use "prod". | prod |
BASE_URL | URL where the code is hosted. | https://suite.staffjoy.com |
MANDRILL_API_KEY | API Key for Mandrill for sending emails. | |
FROM_EMAIL | Email address from which notifications will be sent in Mandrill | team@staffjoy.com |
RECAPTCHA_PUBLIC_KEY | Public key for Recaptcha | |
RECAPTCHA_PRIVATE_KEY | Private key for Recaptcha | |
REDIS_HOST | Host for redis | localhost |
REDIS_PORT | Port to connect to Redis on. Defaults to 6379. | 6379 |
REDIS_DATABASE | If using multiple databases, set the number. Defaults to 0 | 0 |
SQLALCHEMY_DATABASE_URI | Connection info, including username, password, and database for MySQL | mysql://root:bacon@localhost/dev |
SECRET_KEY | A unique, secret key for your application that is used to sign cookie data. Make sure it is the same across instances in an environment. Setting this key is critical for security. (details) | anyLongSecretKeyYouMakeUpAndIsRandom |
STATUS_PAGE_ID | Optional page id for a Status Page integration | |
STATUS_PAGE_API_KEY | Corresponding API key for Statuspage.io | |
INTERCOM_ID | Optional - application ID for an Intercom app | |
INTERCOM_SECRET | Optional - Intercom secret used for signing user hashes | |
INTERCOM_API_KEY | Optional - Intercom API key used for sending events to the Intercom API | |
TWILIO_ACCOUNT_SID | API Key for Twilio - note that the TWILIO_NUMBER variable in config.py needs to be updated with sending phone numbers that you own for this to work. |
|
TWILIO_AUTH_TOKEN | Twilio secret key |
The /api/v2/internal/cron/
endpoint must be triggered every 60 seconds. We open-sourced our Cron microservice that does this, but consider just using a Jenkins job with:
curl --user API_KEY: http://suite.local/api/v2/internal/cron/
(NOTE: the trailing colon after the API key is required)
Required for calculating shifts from forecasts. View Chomp's source code on github.com/staffjoy/chomp-decomposition
Mobius assigns workers to shifts, subject to constraints. View Mobius's source code on github.com/staffjoy/mobius-assignment
/health
endpoint to determine instance healthALLOW_COMPANY_SIGNUPS
in app/config.py
Prequisites:
Add your email to the file user.txt
, e.g. if your email is lenny@staffjoy.com:
echo "lenny@staffjoy.com" > ./user.txt
This auto-registers you on first boot, and makes you an admin.
To boot a dev server for the first time, run:
make dev
The first time it launches, it will take a long time to download the required base images. After that, required packages and images will be cached. The app will be running at suite.local
To quickly launch a dev server that has already been built, you can use this shortcut command from the project root:
vagrant up
vagrant ssh
cd /vagrant
make dev-server
Be advised that this does not update any required packages or recompile the less stylesheets, so please run make dev
occasionally.
Add new dependencies to the end of requirements.txt
, then run make dev
. The dev server is booted, the dependencies are installed, then the boot script immediately runs pip freeze
to update requirements.txt with the latest version number, and nested dependencies.
If you run into issues or if you messed up your environment, you can delete its caches with vagrant destroy -f
. Running make dev
will take longer as the system re-fetches dependencies.
After creating a Staffjoy account in your dev environt, use the commands below to access the shell:
vagrant ssh
cd /vagrant
make shell
Now in the shell window, write and execute the following code:
print User.query.get_all() # To find users - don't do this in prod where there are lots of user :-)
u = User.query.get(<id>)
u.sudo = True
db.session.commit()
The id will correspond to the id of the user that you just created and will be visible in the URL bar
To access the current environment, use:
from flask import current_app
print current_app.config.get("ENV") # dev or prod - as defined in config.py.
# Note that stage is treated as prod except for the robots.txt
Dev - uses MySQL just like production. To access it, run the following commands from the project root:
vagrant ssh
<wait for login>
cd /vagrant
mysql -u root -p
<enter the password "bacon">
use dev;
The development MySQL root password is bacon
.
make db-migrate
make db-deploy
Note: Commit the migration files
While your vagrant machine is running, SSH into the instance with vagrant ssh
. Then in /vagrant/
, run make db-migrate
to generate a migration. To apply the database change, you can either run make db-deploy
, or opt for a standard make-dev
.
It's easier to wipe a database than try and do a rollback. Log into the Dev MySQL Instance and run this command to wipe it:
drop database dev;
create database dev;
Exit MySQL and now run make db-deploy
to rebuild it. You will have to create a new sudo user with the Shell Context.
You can run python main.py shell
and interact directly with the app, users, etc.
e.g.
python manage.py shell
u = User()
u.password = 'cat'
u.password_hash # See hash
u.verify_password('cat')
u.verify_password('dog')
db.session.commit()
This is useful in dev environments for clearing out the database or going into production web servers to flag a user as "sudo".
Public docs forthcoming
Tokens are time-based tokens with a default life of 6 hours. API keys are permanent until revoked.
We authenticate using HTTP basic auth, where the username is the token and the password is blank. To do this with curl, use this command: (noting that the trailing colon after the token is important because it means "no password")
curl -u TOKEN: https://www.staffjoy.com/api/v2/
You can always get a new token for your logged-in user at /auth/api-token.
Our API uses JSON. Response data is in the data
field, resources on the object are given in the resources
field, and other metadata - like limit
or offset
may be provided.
This library uses the Google YAPF library to enforce PEP-8. Using it is easy - run make fmt
to format your code inline correctly. Failure to do this will result in your build failing. You have been warned.
To disable YAPf around code that you do not want changed, wrap it like this:
# yapf: disable
FOO = {
# ... some very large, complex data literal.
}
BAR = [
# ... another large data literal.
]
# yapf: enable
If you end up with multiple heads, do:
python main.py db heads
# Using the two hashes
python main.py db merge <hash1> <hash2>
This is not a perfect copy of our internal repo. For ease of use, sanity, and security, removed parts include:
nginx.conf
@staffjoy.com
email addressescurrent_app
rather than the generator create_app
. This should be corrected.