Skip to content

Commit 5f6999e

Browse files
Copilotphrocker
Copilot
and
phrocker
committed
Complete JIRA capabilities integration with documentation and demonstration
Co-authored-by: phrocker <[email protected]>
1 parent 5dddd3a commit 5f6999e

File tree

2 files changed

+215
-0
lines changed

2 files changed

+215
-0
lines changed

‎demo/jira-capabilities-demo.sh‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
#!/bin/bash
2+
3+
# JIRA Capabilities Integration Demonstration Script
4+
# This script demonstrates the AI agent workflow for discovering and using JIRA capabilities
5+
6+
echo "==========================================="
7+
echo "JIRA Capabilities Integration Demonstration"
8+
echo "==========================================="
9+
echo
10+
11+
echo "This demonstrates how an AI agent would discover and use JIRA capabilities:"
12+
echo
13+
14+
echo "1. AI Agent discovers available capabilities:"
15+
echo " GET /api/v1/capabilities/verbs"
16+
echo " -> Returns list of all AI-callable verb methods"
17+
echo
18+
19+
echo "2. AI Agent finds JIRA-related verbs in the response:"
20+
echo " - searchForTickets: Search for JIRA tickets using query"
21+
echo " - assignTicket: Assign a ticket to a user"
22+
echo " - updateTicket: Add a comment to a ticket"
23+
echo " - isJiraAvailable: Check if JIRA integration is configured"
24+
echo
25+
26+
echo "3. AI Agent checks JIRA availability:"
27+
echo " CALL isJiraAvailable()"
28+
echo " -> Returns true if JIRA integration is configured"
29+
echo
30+
31+
echo "4. AI Agent searches for tickets:"
32+
echo " CALL searchForTickets('project = SUPPORT AND status = Open')"
33+
echo " -> Returns list of matching tickets:"
34+
echo " [{"
35+
echo " \"id\": \"SUPPORT-123\","
36+
echo " \"summary\": \"Login issue reported\","
37+
echo " \"status\": \"Open\","
38+
echo " \"type\": \"jira\""
39+
echo " }]"
40+
echo
41+
42+
echo "5. AI Agent assigns a ticket:"
43+
echo " CALL assignTicket('SUPPORT-123', currentUser)"
44+
echo " -> Returns true if assignment successful"
45+
echo
46+
47+
echo "6. AI Agent adds a comment:"
48+
echo " CALL updateTicket('SUPPORT-123', currentUser, 'Investigating this issue')"
49+
echo " -> Returns true if comment added successfully"
50+
echo
51+
52+
echo "==========================================="
53+
echo "Implementation Benefits:"
54+
echo "==========================================="
55+
echo "✓ AI agents can discover JIRA capabilities automatically"
56+
echo "✓ Works whether JIRA is configured or not"
57+
echo "✓ Uses existing security and authentication"
58+
echo "✓ Minimal changes to existing codebase"
59+
echo "✓ Consistent with other Sentrius capabilities"
60+
echo
61+
62+
echo "==========================================="
63+
echo "Key Components Implemented:"
64+
echo "==========================================="
65+
echo "✓ JiraVerbService - Exposes JIRA operations as @Verb methods"
66+
echo "✓ Conditional availability checking"
67+
echo "✓ AI-callable annotations (isAiCallable = true)"
68+
echo "✓ Integration with existing CapabilitiesApiController"
69+
echo "✓ Comprehensive unit tests"
70+
echo "✓ Documentation and examples"
71+
echo
72+
73+
echo "Ready for AI agent integration!"

‎docs/JIRA_CAPABILITIES_INTEGRATION.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# JIRA Capabilities Integration for AI Agents
2+
3+
This implementation enables AI agents to discover and call JIRA integration capabilities through the Sentrius capability discovery system.
4+
5+
## Architecture
6+
7+
The solution consists of several components working together:
8+
9+
1. **JiraVerbService** - Exposes JIRA operations as `@Verb` methods that AI agents can discover and call
10+
2. **CapabilitiesApiController** - Provides REST endpoints for capability discovery
11+
3. **EndpointScanningService** - Scans the application for available capabilities including JIRA verbs
12+
4. **Existing JIRA Infrastructure** - TicketService and JiraService provide the underlying JIRA integration
13+
14+
## JIRA Verb Methods
15+
16+
The `JiraVerbService` exposes the following AI-callable methods:
17+
18+
### `searchForTickets(String query)`
19+
- **Description**: Search for JIRA tickets using a query string. Can use JQL or simple text search.
20+
- **Parameters**: Search query string (JQL or simple text)
21+
- **Returns**: List of TicketDTO objects
22+
- **AI Callable**: Yes
23+
24+
### `assignTicket(String ticketKey, User user)`
25+
- **Description**: Assign a JIRA ticket to a user
26+
- **Parameters**: JIRA ticket key (e.g., PROJ-123), User to assign the ticket to
27+
- **Returns**: Boolean (true if successful)
28+
- **AI Callable**: Yes
29+
30+
### `updateTicket(String ticketKey, User user, String message)`
31+
- **Description**: Add a comment to a JIRA ticket
32+
- **Parameters**: JIRA ticket key, User adding the comment, Comment message
33+
- **Returns**: Boolean (true if successful)
34+
- **AI Callable**: Yes
35+
36+
### `isJiraAvailable()`
37+
- **Description**: Check if JIRA integration is configured and available
38+
- **Parameters**: None
39+
- **Returns**: Boolean (true if JIRA is available)
40+
- **AI Callable**: Yes
41+
42+
## Conditional Availability
43+
44+
All JIRA verbs include logic to check if JIRA integration is available before attempting operations:
45+
46+
```java
47+
private boolean isJiraIntegrationAvailable() {
48+
try {
49+
List<IntegrationSecurityToken> jiraIntegrations = integrationService.findByConnectionType("jira");
50+
return !jiraIntegrations.isEmpty();
51+
} catch (Exception e) {
52+
log.error("Error checking JIRA integration availability", e);
53+
return false;
54+
}
55+
}
56+
```
57+
58+
This ensures that:
59+
- JIRA verbs are always discoverable (listed in capabilities)
60+
- JIRA verbs gracefully handle the case when no JIRA integration is configured
61+
- AI agents can call `isJiraAvailable()` to check availability before attempting operations
62+
63+
## AI Agent Discovery
64+
65+
AI agents can discover JIRA capabilities through the existing capabilities API:
66+
67+
### 1. Query All Capabilities
68+
```http
69+
GET /api/v1/capabilities/endpoints
70+
```
71+
72+
This returns all available endpoints including JIRA verbs.
73+
74+
### 2. Query Only Verb Methods (AI-focused)
75+
```http
76+
GET /api/v1/capabilities/verbs
77+
```
78+
79+
This returns only `@Verb` methods that are marked as AI-callable.
80+
81+
### 3. Filter for JIRA Capabilities
82+
The response will include JIRA verbs with metadata like:
83+
84+
```json
85+
{
86+
"name": "searchForTickets",
87+
"description": "Search for JIRA tickets using a query string. Can use JQL or simple text search.",
88+
"type": "VERB",
89+
"className": "io.sentrius.sso.core.integrations.ticketing.JiraVerbService",
90+
"methodName": "searchForTickets",
91+
"parameters": [
92+
{
93+
"name": "query",
94+
"description": "Search query string (JQL or simple text)",
95+
"type": "class java.lang.String",
96+
"required": true,
97+
"source": "METHOD_PARAM"
98+
}
99+
],
100+
"returnType": "interface java.util.List",
101+
"metadata": {
102+
"isAiCallable": true,
103+
"outputInterpreter": "io.sentrius.sso.core.model.verbs.DefaultInterpreter",
104+
"inputInterpreter": "io.sentrius.sso.core.model.verbs.DefaultInterpreter"
105+
}
106+
}
107+
```
108+
109+
## Usage Example
110+
111+
An AI agent workflow might look like:
112+
113+
1. **Discovery**: Call `/api/v1/capabilities/verbs` to discover available capabilities
114+
2. **Check Availability**: Call `isJiraAvailable()` to verify JIRA is configured
115+
3. **Search Tickets**: Call `searchForTickets("project = SUPPORT AND status = Open")` to find tickets
116+
4. **Assign Ticket**: Call `assignTicket("SUPPORT-123", currentUser)` to assign a ticket
117+
5. **Add Comment**: Call `updateTicket("SUPPORT-123", currentUser, "Working on this issue")` to update
118+
119+
## Integration with Existing Systems
120+
121+
This implementation leverages existing Sentrius infrastructure:
122+
123+
- **Security**: Uses existing `@LimitAccess` annotations and authentication
124+
- **JIRA Service**: Delegates to existing `TicketService` and `JiraService` classes
125+
- **Discovery**: Integrates with existing `EndpointScanningService` and `CapabilitiesApiController`
126+
- **Configuration**: Works with existing JIRA integration configuration
127+
128+
## Testing
129+
130+
The implementation includes comprehensive unit tests:
131+
132+
- **JiraVerbServiceTest**: Tests all verb methods with mocked dependencies
133+
- **Conditional Logic**: Verifies behavior when JIRA is/isn't available
134+
- **Error Handling**: Tests exception scenarios
135+
136+
## Benefits
137+
138+
1. **AI Discoverability**: JIRA capabilities are automatically discoverable by AI agents
139+
2. **Graceful Degradation**: Works whether JIRA is configured or not
140+
3. **Consistent Interface**: Uses the same patterns as other Sentrius capabilities
141+
4. **Minimal Changes**: Builds on existing infrastructure without breaking changes
142+
5. **Security**: Maintains existing security and access control patterns

0 commit comments

Comments
 (0)