Skip to content

Improve documentation #217

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 10, 2025
Merged

Improve documentation #217

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5c0ee9d
docs: improve google adapter documentation
timonegk Dec 18, 2024
63043bd
docs: improve transformation documentation
timonegk Dec 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 32 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,9 @@ Note: The `asdf` plugin is not managed by inovex, but is provided by a CalendarS

## First Time Execution

Create a modified `sync.yaml` file based on the content of the `./example.sync.yaml` file. Finally, start the app using `CALENDARSYNC_ENCRYPTION_KEY=<YourSecretPassword> ./calendarsync --config sync.yaml` and follow the instructions in the output.
Create a modified `sync.yaml` file based on the content of the `./example.sync.yaml` file.
For the setup of the adapters, take a look at [the docs](docs/adapters.md).
Then, start the app using `CALENDARSYNC_ENCRYPTION_KEY=<YourSecretPassword> ./calendarsync --config sync.yaml` and follow the instructions in the output.

The app will create a file in the execution folder called `auth-storage.yaml`. In this file the OAuth2 Credentials will be saved encrypted by your `$CALENDARSYNC_ENCRYPTION_KEY`.

Expand Down Expand Up @@ -132,7 +134,33 @@ documentation [here](./docs/adapters.md).
Basically, only the time is synced. By means of transformers one can sync
individual further data. Some transformers allow for further configuration using
an additional `config` block, such as the `ReplaceTitle` transformer. Below is a
list of all transformers available:
list of all transformers available. They are applied from top to bottom.

transformerOrder = []string{
"KeepAttendees",
"KeepLocation",
"KeepReminders",
"KeepDescription",
"KeepMeetingLink",
"AddOriginalLink",
"KeepTitle",
"PrefixTitle",
"ReplaceTitle",
}

| **Name** | **Description** | **Configuration** |
|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
| `KeepAttendees` | Synchronizes the list of attendees. If `UseEmailAsDisplayName` is set to `true`, the email is used in the attendee list. Do not use when the Outlook Adapter is used as a sink as there is no way to suppress mail invitations. | `config.UseEmailAsDisplayName`, default `false` |
| `KeepLocation` | Synchronizes the location of the event. | – |
| `KeepReminders` | Synchronizes event reminders. | – |
| `KeepDescription` | Synchronizes the description of the event. | – |
| `KeepMeetingLink` | Adds the meeting link of the original meeting to the description of the event. | – |
| `AddOriginalLink` | Adds the link to the original calendar event to the description of the event. | – |
| `KeepTitle` | Synchronizes the event's title. Without this transformer, the title is set to `CalendarSync Event` | – |
| `PrefixTitle` | Adds the configured prefix to the title. | `config.Prefix`, default `""` |
| `ReplaceTitle` | Replaces the title with the configured string. Does not make sense to be used with `KeepTitle` or `PrefixTitle` | `config.NewTitle`, default `"CalendarSync Event"` |

Example configuration:

```yaml
transformations:
Expand All @@ -143,18 +171,13 @@ transformations:
- name: PrefixTitle
config:
Prefix: "[Sync] "
- name: ReplaceTitle
config:
NewTitle: "[synchronized appointment]"
# Do not use KeepAttendees when the Outlook Adapter is used as a sink. There is no way to suppress mail invitations
- name: KeepMeetingLink
- name: AddOriginalLink
- name: KeepAttendees
config:
UseEmailAsDisplayName: true
```

The transformers are applied in a specific order. The order is defined here:
[`internal/sync/transformer.go`](./internal/sync/transformer.go)

## Filters

In some cases events should not be synced. For example, declined events might
Expand Down
19 changes: 11 additions & 8 deletions docs/adapters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,13 @@ To get your calendar ID, use the [Microsoft Graph Explorer](https://developer.mi

## Google Adapter Setup

+ Open the [Google Cloud Console](https://console.cloud.google.com/home/dashboard) and login.
For the setup of the Google adapter, an OAuth client has to be created. The client configuration is saved to `sync.yaml`
and on the first run, CalendarSync will open a browser window where you can authorize the application to use your calendar.
The setup of the OAuth client is done in the Google Cloud Console. Follow these steps:

+ Open the [Google Cloud Console](https://console.cloud.google.com/home/dashboard) and log in.
+ Now you can either select *New Project* at the top left of the screen or just [click here](https://console.cloud.google.com/projectcreate)
+ Create a new project, name it as you like but make sure that the Billing Account is set correctly.
+ Create a new project, name it as you like and select a billing account. But don't worry – the Google Calendar API is free.

![new-project](../assets/gcloud-new-project.png)

Expand All @@ -61,12 +65,15 @@ To get your calendar ID, use the [Microsoft Graph Explorer](https://developer.mi
+ In the search bar, look for `google calendar` and select the **Google Calendar API**
+ You'll be redirected to the API description. Hit the *Enable* button.
+ Once the API is enabled, you'll be redirected again to the API management overview.
+ Before you are allowed to create the client, you will have to configure the *OAuth consent screen*
+ Click on *OAuth consent screen* on the left side (under *APIs & Services*)
+ Enter an app name, e.g. *CalendarSync* and your email address. As the user type, select *Internal*.
+ Click on *Credentials* in the sidebar and then on *Create Credentials*
+ We will need to create an *OAuth client ID*
+ Select *Desktop app* as application type and give it a name of your liking (*calendarsync-dev* maybe?)
+ Select *Desktop app* as application type and give it a name of your liking (*calendarsync-dev* maybe?)
+ Once The client ID is created you will see it in the overview.
+ Click on the download icon of the created client
+ You'll see a popup open. Here you can simply **Download JSON**. This will download the `credentials.json` file required.
+ You'll see a popup open. Copy the *Client ID* and *Client secret* into your `sync.yaml` as shown below.

![client-id-popup](../assets/gcloud-oauth-client.png)

Expand All @@ -80,8 +87,4 @@ sink:
clientKey: "<clientSecret>"
```

Important: When retrieving the credentials from Google, you'll get a `clientId`
and a `clientSecret`. Make sure to add the `clientSecret` to the `clientKey`
setting in your CalendarSync configuration.

If you want to use the created OAuth Application also with accounts outside of your Google Workspace, make sure to set the Usertype to `external` in the `OAuth Consent Screen` Menu.
Loading