# YouTrack

**Early Access**: This integration is provided as an Open Authorization API (OAA) connector package. Contact our support team for more information.

## Veza YouTrack Connector

Python connector for YouTrack to collect organizations, groups, teams, roles, permissions and users data for the Veza Open Authorization (OAA) API.

#### Veza Application Mapping

| YouTrack      | OAA Application   | Notes |
| ------------- | ----------------- | ----- |
| Instance      | Application       |       |
| Organizations | Custom Resources  |       |
| Groups        | Local Groups      |       |
| Teams         | Local Groups      |       |
| Roles         | Local Roles       |       |
| Users         | Local Users       |       |
| Permissions   | Local Permissions |       |

#### Discovered Properties

| Entity       | Property         | Description                                               |
| ------------ | ---------------- | --------------------------------------------------------- |
| Organization | `id`             | Organization's ID provided by YouTrack                    |
| Organization | `name`           | Organization's name                                       |
| Group        | `id`             | Group/Team's ID provided by YouTrack                      |
| Group        | `name`           | Group/Team's name                                         |
| Group        | `group_type`     | Group's type can be Group/Team                            |
| Role         | `id`             | Role's ID provided by YouTrack                            |
| Role         | `name`           | Role's name                                               |
| User         | `id`             | User's ID provided by YouTrack                            |
| User         | `name`           | User's name                                               |
| User         | `email`          | User's email address                                      |
| User         | `type`           | User's type                                               |
| User         | `required_twofa` | User required two factor authentication or not as boolean |
| User         | `guest`          | User is guest user or not as boolean                      |
| User         | `user_type`      | User's detail type                                        |
| User         | `is_active`      | User active or not                                        |
| User         | `last_login_at`  | User's last active timestamp                              |
| User         | `created_at`     | User's creation timestamp                                 |
| User         | `system-admin`   | If `system-admin` value exists, user is admin             |
| Permissions  | `name`           | Permission's name                                         |

### Setup

#### YouTrack

1. To generate auth token,
   * Please follow the given steps in [Create a Permanent Token](https://www.jetbrains.com/help/youtrack/server/Manage-Permanent-Token.html#obtain-permanent-token)
   * Permanent Token must have `YouTrack Administration` access scope.

#### Veza

1. Generate an API key for your Veza user. API keys can be managed in the Veza interface under Administration -> API Keys. For detailed instructions consult the Veza User Guide.

### Running the Connector

#### Command Line

1. Install the requirements:

   ```
   pip3 install -r requirements.txt
   ```
2. Set the Secrets:

   ```
   export VEZA_API_KEY="XXXXXXX...XXXXXXXXXXXX"
   export YOUTRACK_AUTH_TOKEN="XXX...XXXXXXXXXXXX"
   ```
3. Run the connector:

   ```shell
   ./veza_youtrack.py --youtrack-url <youtrack-url> --veza-url <URL to Veza instance>
   ```

#### Parameters

| CLI Parameter     | Environment Variable  | Description                                                       |
| ----------------- | --------------------- | ----------------------------------------------------------------- |
| `--veza-url`      | `VEZA_URL`            | the URL of the Veza instance                                      |
| n/a               | `VEZA_API_KEY`        | API key for Veza connection                                       |
| n/a               | `YOUTRACK_AUTH_TOKEN` | YouTrack Auth Token to Authenicate.                               |
| `--youtrack-url`  | `YOUTRACK_URL`        | the URL of the Youtrack cloud/server to make API calls.           |
| `--debug`         | n/a                   | Set the log level to debug                                        |
| `--save-json`     | n/a                   | Save OAA JSON payload to file                                     |
| `--create-report` | n/a                   | Create/update a Veza Report. Defaults to true for first discovery |

On first discovery, connector will automatically populate Veza Insights Queries and Report associated with YouTrack. Queries created include:

* List all YouTrack Users
* List all YouTrack Groups
* List all YouTrack Roles
* List all YouTrack Organizations
* List all YouTrack Teams
* Active YouTrack Users
* YouTrack Users Not Used in Last 90 Days
* YouTrack Roles with Assigned Users
* YouTrack Roles with Assigned Groups
* List YouTrack Administrators
* YouTrack Users assigned to Groups
* YouTrack Users related to Okta Users
* YouTrack Users not related to Okta Users
* YouTrack Users related to Deactivated Okta Users
* YouTrack Users with permission to Delete Organizations
* YouTrack Users with permission to Delete Project
* YouTrack Users with permission to Delete User
* YouTrack Users with permission to Delete Group
* YouTrack Users with permission to Delete Issue
* YouTrack Users with permission to Apply Commands Silently
* YouTrack Users with permission to Delete Attachment
* YouTrack Users with permission to Delete Issue Comment
* YouTrack Users with permission to Delete Tag or Saved Search
* YouTrack Users with permission to Delete Not Own Comment and Permanent Comment Delete
* YouTrack Users with permission to Override Visibility Restrictions
* YouTrack Users with permission to Delete Article
* YouTrack Users with permission to Delete Article Comment


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/integrations/youtrack.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.