|
| 1 | +# Jira Adapter |
| 2 | + |
| 3 | +The Jira adapter allows you to sync content from Atlassian Jira projects into OpenWebUI knowledge bases. This adapter uses the Jira REST API to fetch issues and comments from specified Jira projects and uploads them to OpenWebUI. |
| 4 | + |
| 5 | +## API Compatibility |
| 6 | + |
| 7 | +This adapter uses Jira REST API v3, which provides: |
| 8 | +- Modern cursor-based pagination |
| 9 | +- Improved performance and reliability |
| 10 | +- Better support for large projects |
| 11 | +- Enhanced metadata and content structure |
| 12 | + |
| 13 | +## Features |
| 14 | + |
| 15 | +- **Issue Content Sync**: Fetches all issues from specified Jira projects using Jira API v3 |
| 16 | +- **HTML to Markdown Conversion**: Converts Jira's HTML content to markdown format |
| 17 | +- **Comment Support**: downloads and syncs issue comments |
| 18 | +- **Multi-Project Support**: Can sync from multiple Jira projects |
| 19 | +- **Cursor-based Pagination**: Uses modern cursor-based pagination for efficient data retrieval |
| 20 | + |
| 21 | +## Configuration |
| 22 | + |
| 23 | +### YAML Configuration |
| 24 | + |
| 25 | +Add the following to your `config.yaml`: |
| 26 | + |
| 27 | +```yaml |
| 28 | +jira: |
| 29 | + enabled: true |
| 30 | + base_url: "https://your-domain.atlassian.net" |
| 31 | + username: "your-email@example.com" |
| 32 | + api_key: "your-jira-api-key" |
| 33 | + project_mappings: |
| 34 | + - project_key: "PROJ" |
| 35 | + knowledge_id: "your-knowledge-base-id" |
| 36 | + - project_key: "ANOTHER" |
| 37 | + knowledge_id: "another-knowledge-base-id" |
| 38 | + page_limit: 100 |
| 39 | +``` |
| 40 | +
|
| 41 | +### Environment Variables |
| 42 | +
|
| 43 | +Only the API key can be configured via environment variable (for security): |
| 44 | +
|
| 45 | +```bash |
| 46 | +JIRA_API_KEY="your-jira-api-key" |
| 47 | +``` |
| 48 | + |
| 49 | +All other configuration should be done in the `config.yaml` file. |
| 50 | + |
| 51 | +### Kubernetes Configuration |
| 52 | + |
| 53 | +#### ConfigMap |
| 54 | + |
| 55 | +```yaml |
| 56 | +apiVersion: v1 |
| 57 | +kind: ConfigMap |
| 58 | +metadata: |
| 59 | + name: connector-config |
| 60 | +data: |
| 61 | + config.yaml: | |
| 62 | + jira: |
| 63 | + enabled: true |
| 64 | + base_url: "https://your-domain.atlassian.net" |
| 65 | + username: "your-email@example.com" |
| 66 | + project_mappings: |
| 67 | + - project_key: "PROJ" |
| 68 | + knowledge_id: "your-knowledge-base-id" |
| 69 | + - project_key: "ANOTHER" |
| 70 | + knowledge_id: "another-knowledge-base-id" |
| 71 | + page_limit: 100 |
| 72 | +``` |
| 73 | +
|
| 74 | +## Authentication |
| 75 | +
|
| 76 | +The Jira adapter uses Basic Authentication with your Jira username and API key. To get an API key: |
| 77 | +
|
| 78 | +1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens) |
| 79 | +2. Click "Create API token" |
| 80 | +3. Give it a label and copy the generated token |
| 81 | +4. Use your email address as the username and the token as the API key |
| 82 | +
|
| 83 | +## Configuration Parameters |
| 84 | +
|
| 85 | +| Parameter | Type | Required | Default | Description | |
| 86 | +|-----------|------|----------|---------|-------------| |
| 87 | +| `enabled` | boolean | No | `false` | Enable the Jira adapter | |
| 88 | +| `base_url` | string | Yes | - | Your Jira instance URL (e.g., `https://your-domain.atlassian.net`) | |
| 89 | +| `username` | string | Yes | - | Your Jira username (usually your email) | |
| 90 | +| `api_key` | string | Yes | - | Your Jira API key | |
| 91 | +| `project_mappings` | array | Yes | - | List of Jira project keys and their corresponding OpenWebUI knowledge base IDs | |
| 92 | +| `page_limit` | integer | No | `100` | Maximum number of issues to fetch per project | |
| 93 | + |
| 94 | +## File Processing |
| 95 | + |
| 96 | +### Issue Content |
| 97 | + |
| 98 | +- Jira issues are converted from HTML to markdown format |
| 99 | +- Issues are saved as `.md` files with sanitized filenames |
| 100 | +- File paths follow the pattern: `{issue-id}.md` |
| 101 | + |
| 102 | +### Issue Metadata |
| 103 | + |
| 104 | +Each issue file includes: |
| 105 | +- Issue key |
| 106 | +- Reporter name |
| 107 | +- Issue type |
| 108 | +- Status |
| 109 | +- Resolution status |
| 110 | + |
| 111 | +### Comments |
| 112 | + |
| 113 | +- Comments are fetched and included in the markdown file |
| 114 | +- Each comment includes the author's display name and timestamp |
| 115 | +- Comments are formatted in markdown |
| 116 | + |
| 117 | +## Error Handling |
| 118 | + |
| 119 | +- **Authentication Errors**: Invalid credentials will cause the adapter to fail initialization |
| 120 | +- **API Errors**: HTTP errors from Jira API are logged and may cause individual issue processing to fail |
| 121 | +- **File Processing Errors**: Individual file processing errors are logged but don't stop the overall sync |
| 122 | +- **Network Errors**: Connection timeouts and network issues are handled gracefully |
| 123 | + |
| 124 | +## Limitations |
| 125 | + |
| 126 | +1. **API Rate Limits**: Jira has API rate limits that may affect sync performance |
| 127 | +2. **Large Projects**: Very large projects with many issues may take significant time to sync |
| 128 | +3. **HTML Conversion**: The HTML to markdown conversion is basic and may not preserve all formatting |
| 129 | +4. **Comment Limitations**: Comments are limited to the Jira API's available fields |
| 130 | + |
| 131 | +## Troubleshooting |
| 132 | + |
| 133 | +### Common Issues |
| 134 | + |
| 135 | +1. **Authentication Failed** |
| 136 | + - Verify your username and API key are correct |
| 137 | + - Ensure your API key has the necessary permissions |
| 138 | + |
| 139 | +2. **Project Not Found** |
| 140 | + - Check that the project key is correct |
| 141 | + - Verify you have access to the project |
| 142 | + |
| 143 | +3. **No Content Synced** |
| 144 | + - Check that the project contains issues |
| 145 | + - Verify the `page_limit` setting is appropriate |
| 146 | + - Check logs for API errors |
| 147 | + |
| 148 | +### Debug Mode |
| 149 | + |
| 150 | +Enable debug logging to see detailed information about the sync process: |
| 151 | + |
| 152 | +```yaml |
| 153 | +log_level: debug |
| 154 | +``` |
| 155 | + |
| 156 | +## Example Usage |
| 157 | + |
| 158 | +### Basic Configuration |
| 159 | + |
| 160 | +```yaml |
| 161 | +jira: |
| 162 | + enabled: true |
| 163 | + base_url: "https://mycompany.atlassian.net" |
| 164 | + username: "john.doe@mycompany.com" |
| 165 | + api_key: "ATATT3xFfGF0..." |
| 166 | + project_mappings: |
| 167 | + - project_key: "DOCS" |
| 168 | + knowledge_id: "fbc18bc4-72c1-40f0-84b1-52055368c583" |
| 169 | + - project_key: "PROJ" |
| 170 | + knowledge_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" |
| 171 | + page_limit: 100 |
| 172 | +``` |
| 173 | + |
| 174 | +### Advanced Configuration |
| 175 | + |
| 176 | +```yaml |
| 177 | +jira: |
| 178 | + enabled: true |
| 179 | + base_url: "https://mycompany.atlassian.net" |
| 180 | + username: "john.doe@mycompany.com" |
| 181 | + api_key: "ATATT3xFfGF0..." |
| 182 | + project_mappings: |
| 183 | + - project_key: "DOCS" |
| 184 | + knowledge_id: "fbc18bc4-72c1-40f0-84b1-52055368c583" |
| 185 | + - project_key: "PROJ" |
| 186 | + knowledge_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" |
| 187 | + - project_key: "OPS" |
| 188 | + knowledge_id: "98765432-10fe-dcba-0987-6543210fedcb" |
| 189 | + page_limit: 500 |
| 190 | +``` |
| 191 | + |
| 192 | +This configuration will sync up to 500 issues from each of the three specified projects. |
0 commit comments