Browse Source

edited the readme to fit in with the new changes.

master
Roxie Gibson 4 years ago
parent
commit
a2a91f434d
No known key found for this signature in database
1 changed files with 28 additions and 25 deletions
  1. +28
    -25
      readme.md

+ 28
- 25
readme.md View File

@@ -5,7 +5,7 @@ Script to generate a seating plan via calendar events in an organsation's Office

## What it does

The script looks at the current week and generates a seating plan for that week. It does this by looking at the email provided by the user, and looking at that emails default calendar. This means it works with a dedicated account that's sole use is to log when people are out of the office. It does this by looking at events listed during that week, and checking who is attending that event. It then logs these people as out of the office for that day and omits them from the normal seating plan of that day.
The script looks at the current week and generates a seating plan for that week. By getting the calendar of a dedicated room or account, it can see who will be out of the office during the week. It then creates a

> **Note:** Current week is defined during the normal work weeks. If the script is ran on the weekend (Saturday and Sunday) the script will generate next weeks and label it as such.

@@ -47,47 +47,50 @@ cd seatplangen
python3 -m pip install . --user
```

Once installed, you can run the script like this.

```sh
seatingplan -c "CLIENT_ID" -t "TENANT_ID" -s "CLIENT_SECRET"
```

The first time the script is ran, it will ask you to visit a url. Open the url in your browser and allow the script access to the requested permissions. Once you have done that, you will be redirected to a blank page. Copy the URL and paste it into the console and press enter.

> **Note:** You should login and give permission to the app *as* the account with the calendar you want to use. This calendar should be the one you are using to store who is out of office.

This will only need to be done every 90 days.
This installs the script to your Python user bin.

## Configuration

### ID's and Secrets

Configuration like the `CLIENT_ID`, `CLIENT_SECRET`, etc. can be inputted via the command line or via a config file. A config file might be better over a command line input as this does not expose sensitive information to the stdout of the tty. It also means not remembering this every time you run the script. Seeing as a client secret can only be viewed once and has to be stored, I recommend the config file for long term use. To create a config file, do the following:
Configuration like the `CLIENT_ID`, `CLIENT_SECRET`, etc. need to be inputted into a config file. Let's create one in the user config folder.

```sh
touch ~/.config/seatingplan.conf
touch ~/.config/seatingplan.yaml
```

This should create an empty text file. Open up this file with your text editor of choice and copy and paste this example.
This should create an empty yaml file. Open up this file with your text editor of choice and copy and paste this example.

```ini
[client]
id=CLIENT_ID
secret=CLIENT_SECRET
tenant=TENANT_ID
```yaml
client_id: "CLIENT_ID"
client_secret: "CLIENT_SECRET"
tenant_id: "TENANT_ID"
ooo_email: "example@example.com"
users: ["Bob", "Alice"]
```

> **Note:** If you are trying to find this file in a file browser and cannot find it, ~/.config is a hidden directory and you will need to enable viewing hidden directories and files in your file browser.

Make sure to replace `CLIENT_ID` etc. with your own client_id for the app you created earlier.
Replace `CLIENT_ID`, `CLIENT_SECRET`, and `TENANT_ID` with the values from the Azure website we wrote down earlier. Replace `ooo_email` with the email of the calendar that has the out of office events. Replace `users` with a list of all the first names of employee's in your organisation. This is case insensitive but has to be spelt the same as their Office365 accounts.

### Output (Optional but recommended)

With this file, you now should be able to run the script like this:
***ADD ADVICE HERE ABOUT DATETIME FORMATTING AND HOW TO NAME THE OUTPUT CSV HERE WHEN YOU FINISH ALL THAT CODE***

## Running the program

Now we have configured everything, we can now run the script. To run the script, enter this inside of the terminal.

```sh
seatingplan -c ~/.config/seatingplan.conf
seatingplan -c ~/.config/seatingplan.yaml
```

### Output
This will generate a `Seating Plan.csv` file in the directory you ran this program. Look at [Output](#Output) to see how to configure the file name of the output.

***ADD ADVICE HERE ABOUT DATETIME FORMATTING AND HOW TO NAME THE OUTPUT CSV HERE WHEN YOU FINISH ALL THAT CODE***
The first time the script is ran, it will ask you to visit a url. Open the url in your browser and allow the script access to the requested permissions. Once you have done that, you will be redirected to a blank page. Copy the URL and paste it into the console and press enter.

> **Note:** You should login and give permission to the app as a user with *full* permissions to the out of office calendar. This is to ensure the script has permissions to view this calendar in full. This will only need to be done every 90 days.

## Known Issues

- Long events (longer than a month) may not get picked up in the script as their start dates and end dates may not be in reach of the programs search range.

Loading…
Cancel
Save