Jira toolkit documentation (#306)

Author: byrro

pages/toolkits/productivity/jira.mdx

@@ -0,0 +1,31 @@
+# Jira Environment Variables
+
+### `JIRA_MAX_CONCURRENT_REQUESTS`
+
+Arcade uses asynchronous calls to request Jira API endpoints. In some tools, multiple concurrent HTTP requests may be made to speed up execution. This environment variable controls the maximum number of concurrent requests to Jira API in any tool execution.
+
+The value must be a numeric string with an integer greater than or equal to 1.
+
+**Default:** `3`
+
+
+### `JIRA_API_REQUEST_TIMEOUT`
+
+Controls the maximum number of seconds to wait for a response from the Jira API. This is also applied, in some cases, as a global max timeout for multiple requests that are made in a single tool execution. For instance, when a tool needs to paginate results from a given endpoint, this timeout may apply to the entire pagination process in total, not only to the individual requests.
+
+The value must be a numeric string with an integer greater than or equal to 1.
+
+**Default:** `30`
+
+
+### `JIRA_CACHE_MAX_ITEMS`
+
+<Note>
+  The caching strategy does not involve caching Jira API responses that go into tool output, but only internal values.
+</Note>
+
+The Arcade Jira toolkit will cache some values that are repeatedly used in tool execution to enable better performance. This environment variable controls the maximum number of items to hold in each cache.
+
+The value must be a numeric string with an integer greater than or equal to 1.
+
+**Default:** `5000`

pages/toolkits/productivity/jira/environment_variables.mdx

@@ -0,0 +1,15 @@
+# Jira Reference
+
+Below is a reference of enumerations used by some tools in the Jira toolkit:
+
+## PrioritySchemeOrderBy
+
+- **NAME_ASCENDING**: `name ascending`
+- **NAME_DESCENDING**: `name descending`
+
+## IssueCommentOrderBy
+
+- **CREATED_DATE_ASCENDING**: `created_date_ascending`
+- **CREATED_DATE_DESCENDING**: `created_date_descending`
+
+

pages/toolkits/productivity/jira/reference.mdx

@@ -0,0 +1,34 @@
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
+
+const USER_ID = "[email protected]";  // Unique identifier for your user (email, UUID, etc.)
+const TOOL_NAME = "Jira.AddCommentToIssue";
+
+// Start the authorization process
+const authResponse = await client.tools.authorize({tool_name: TOOL_NAME});
+
+if (authResponse.status !== "completed") {
+  console.log(`Click this link to authorize: ${authResponse.url}`);
+}
+
+// Wait for the authorization to complete
+await client.auth.waitForCompletion(authResponse);
+
+const toolInput = {
+  "issue": "PROJ-123",
+  "body": "This is a comment on the issue.",
+  "reply_to_comment": "456",
+  "mention_users": [
+    "[email protected]",
+    "[email protected]"
+  ]
+};
+
+const response = await client.tools.execute({
+  tool_name: TOOL_NAME,
+  input: toolInput,
+  user_id: USER_ID,
+});
+
+console.log(JSON.stringify(response.output.value, null, 2));

public/examples/integrations/toolkits/jira/add_comment_to_issue_example_call_tool.js

@@ -0,0 +1,32 @@
+import json
+from arcadepy import Arcade
+
+client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
+
+USER_ID = "[email protected]"  # Unique identifier for your user (email, UUID, etc.)
+TOOL_NAME = "Jira.AddCommentToIssue"
+
+auth_response = client.tools.authorize(tool_name=TOOL_NAME)
+
+if auth_response.status != "completed":
+    print(f"Click this link to authorize: {auth_response.url}")
+
+# Wait for the authorization to complete
+client.auth.wait_for_completion(auth_response)
+
+tool_input = {
+    "issue": "PROJ-123",
+    "body": "This is a comment on the issue.",
+    "reply_to_comment": "456",
+    "mention_users": [
+        "[email protected]",
+        "[email protected]"
+    ]
+}
+
+response = client.tools.execute(
+    tool_name=TOOL_NAME,
+    input=tool_input,
+    user_id=USER_ID,
+)
+print(json.dumps(response.output.value, indent=2))

public/examples/integrations/toolkits/jira/add_comment_to_issue_example_call_tool.py

@@ -0,0 +1,33 @@
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
+
+const USER_ID = "[email protected]";  // Unique identifier for your user (email, UUID, etc.)
+const TOOL_NAME = "Jira.AddLabelsToIssue";
+
+// Start the authorization process
+const authResponse = await client.tools.authorize({tool_name: TOOL_NAME});
+
+if (authResponse.status !== "completed") {
+  console.log(`Click this link to authorize: ${authResponse.url}`);
+}
+
+// Wait for the authorization to complete
+await client.auth.waitForCompletion(authResponse);
+
+const toolInput = {
+  "issue": "JIRA-123",
+  "labels": [
+    "bug",
+    "urgent"
+  ],
+  "notify_watchers": true
+};
+
+const response = await client.tools.execute({
+  tool_name: TOOL_NAME,
+  input: toolInput,
+  user_id: USER_ID,
+});
+
+console.log(JSON.stringify(response.output.value, null, 2));

public/examples/integrations/toolkits/jira/add_labels_to_issue_example_call_tool.js

@@ -0,0 +1,31 @@
+import json
+from arcadepy import Arcade
+
+client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
+
+USER_ID = "[email protected]"  # Unique identifier for your user (email, UUID, etc.)
+TOOL_NAME = "Jira.AddLabelsToIssue"
+
+auth_response = client.tools.authorize(tool_name=TOOL_NAME)
+
+if auth_response.status != "completed":
+    print(f"Click this link to authorize: {auth_response.url}")
+
+# Wait for the authorization to complete
+client.auth.wait_for_completion(auth_response)
+
+tool_input = {
+    "issue": "JIRA-123",
+    "labels": [
+        "bug",
+        "urgent"
+    ],
+    "notify_watchers": True
+}
+
+response = client.tools.execute(
+    tool_name=TOOL_NAME,
+    input=tool_input,
+    user_id=USER_ID,
+)
+print(json.dumps(response.output.value, indent=2))

public/examples/integrations/toolkits/jira/add_labels_to_issue_example_call_tool.py

@@ -0,0 +1,30 @@
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
+
+const USER_ID = "[email protected]";  // Unique identifier for your user (email, UUID, etc.)
+const TOOL_NAME = "Jira.AttachFileToIssue";
+
+// Start the authorization process
+const authResponse = await client.tools.authorize({tool_name: TOOL_NAME});
+
+if (authResponse.status !== "completed") {
+  console.log(`Click this link to authorize: ${authResponse.url}`);
+}
+
+// Wait for the authorization to complete
+await client.auth.waitForCompletion(authResponse);
+
+const toolInput = {
+  "issue": "ISSUE-123",
+  "filename": "report.pdf",
+  "file_content_base64": "[base64_encoded_content]"
+};
+
+const response = await client.tools.execute({
+  tool_name: TOOL_NAME,
+  input: toolInput,
+  user_id: USER_ID,
+});
+
+console.log(JSON.stringify(response.output.value, null, 2));

public/examples/integrations/toolkits/jira/attach_file_to_issue_example_call_tool.js

@@ -0,0 +1,28 @@
+import json
+from arcadepy import Arcade
+
+client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
+
+USER_ID = "[email protected]"  # Unique identifier for your user (email, UUID, etc.)
+TOOL_NAME = "Jira.AttachFileToIssue"
+
+auth_response = client.tools.authorize(tool_name=TOOL_NAME)
+
+if auth_response.status != "completed":
+    print(f"Click this link to authorize: {auth_response.url}")
+
+# Wait for the authorization to complete
+client.auth.wait_for_completion(auth_response)
+
+tool_input = {
+    "issue": "ISSUE-123",
+    "filename": "report.pdf",
+    "file_content_base64": "[base64_encoded_content]"
+}
+
+response = client.tools.execute(
+    tool_name=TOOL_NAME,
+    input=tool_input,
+    user_id=USER_ID,
+)
+print(json.dumps(response.output.value, indent=2))

public/examples/integrations/toolkits/jira/attach_file_to_issue_example_call_tool.py

@@ -0,0 +1,37 @@
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
+
+const USER_ID = "[email protected]";  // Unique identifier for your user (email, UUID, etc.)
+const TOOL_NAME = "Jira.CreateIssue";
+
+// Start the authorization process
+const authResponse = await client.tools.authorize({tool_name: TOOL_NAME});
+
+if (authResponse.status !== "completed") {
+  console.log(`Click this link to authorize: ${authResponse.url}`);
+}
+
+// Wait for the authorization to complete
+await client.auth.waitForCompletion(authResponse);
+
+const toolInput = {
+  "title": "Bug in login feature",
+  "issue_type": "Bug",
+  "project": "PROJ123",
+  "due_date": "2025-01-15",
+  "description": "There is a bug that prevents users from logging in.",
+  "labels": [
+    "login_issue",
+    "urgent"
+  ],
+  "assignee": "[email protected]"
+};
+
+const response = await client.tools.execute({
+  tool_name: TOOL_NAME,
+  input: toolInput,
+  user_id: USER_ID,
+});
+
+console.log(JSON.stringify(response.output.value, null, 2));