[Jira ArcToolkit][ENG-1537] Adding documentation for new tools GetBoards and ListSprintsForBoards (#384)

* Adding documentation for new tool

* update enum refs

---------

Co-authored-by: Francisco Liberal <[email protected]>

Author: jottakka

pages/toolkits/productivity/jira.mdx

@@ -11,7 +11,7 @@ import ToolFooter from "@/components/ToolFooter";
   author="Arcade"
   codeLink="https://github.com/ArcadeAI/arcade-ai/tree/main/toolkits/jira"
   authType="OAuth2"
-  versions={["1.0.0"]}
+  versions={["2.2.0"]}
 />
 
 <Badges repo="arcadeai/arcade_jira" />
@@ -23,6 +23,7 @@ The Jira toolkit provides a comprehensive set of tools for interacting with Jira
 - Manage issue labels and attachments, including adding and removing them.
 - Transition issues between different statuses and manage comments on issues.
 - Browse and list available projects, priorities, and users within Jira.
+- Browse and list information of available boards and sprints within a Jira cloud.
 
 This toolkit streamlines the process of issue management, making it easier to integrate Jira functionalities into applications and workflows.
 
@@ -60,6 +61,7 @@ This toolkit streamlines the process of issue management, making it easier to in
       ["Jira.AddLabelsToIssue", "Add labels to an existing Jira issue."],
       ["Jira.RemoveLabelsFromIssue", "Remove labels from an existing Jira issue."],
       ["Jira.UpdateIssue", "Update an existing Jira issue."],
+      ["Jira.ListSprintsForBoards", "Retrieve sprints from Jira boards with filtering options for planning and tracking purposes."],
       ["Jira.ListLabels", "Get the existing labels (tags) in the user's Jira instance."],
       ["Jira.ListUsers", "Browse users in Jira."],
       ["Jira.GetUserById", "Get user information by their ID."],
@@ -76,6 +78,7 @@ This toolkit streamlines the process of issue management, making it easier to in
       ["Jira.ListProjects", "Browse projects available in Jira."],
       ["Jira.SearchProjects", "Get the details of all Jira projects."],
       ["Jira.GetProjectById", "Get the details of a Jira project by its ID or key."],
+      ["Jira.GetBoards", "Get Jira boards, with the option to filter by a list of board names or IDs (accepts a mix of both). Supports 'offset' and 'limit' parameters."],
       ["Jira.GetPriorityById", "Get the details of a priority by its ID."],
       ["Jira.ListPrioritySchemes", "Browse the priority schemes available in Jira."],
       ["Jira.ListPrioritiesAssociatedWithAPriorityScheme", "Browse the priorities associated with a priority scheme."],
@@ -401,6 +404,35 @@ Update an existing Jira issue.
 - **atlassian_cloud_id** (`string`, optional) The ID of the Atlassian Cloud to use (defaults to None). If not provided and the user has a single cloud authorized, the tool will use that. Otherwise, an error will be raised.
 
 
+## Jira.ListSprintsForBoards
+
+<br />
+<TabbedCodeBlock
+  tabs={[
+    {
+      label: "Call the Tool Directly",
+      content: {
+        Python: ["/examples/integrations/toolkits/jira/list_sprints_for_boards_example_call_tool.py"],
+        JavaScript: ["/examples/integrations/toolkits/jira/list_sprints_for_boards_example_call_tool.js"],
+      },
+    },
+  ]}
+/>
+
+Retrieve sprints from Jira boards with filtering options for planning and tracking purposes.
+
+**Parameters**
+
+- **board_identifiers_list** (`array[string]`, optional) List of board names or numeric IDs (as strings) to retrieve sprints from. Include all mentioned boards in a single list for best performance. Optional, defaults to None.
+- **max_sprints_per_board** (`integer`, optional) Maximum sprints per board (1-50). Latest sprints first. Optional, defaults to 50.
+- **offset** (`integer`, optional) Number of sprints to skip per board for pagination. Optional, defaults to 0.
+- **state** (`Enum` [SprintState](/toolkits/productivity/jira/reference#SprintState), optional) Filter by sprint state using SprintState enum value. Available options: SprintState.FUTURE (future sprints), SprintState.ACTIVE (active sprints), SprintState.CLOSED (closed sprints), SprintState.FUTURE_AND_ACTIVE (future + active), SprintState.FUTURE_AND_CLOSED (future + closed), SprintState.ACTIVE_AND_CLOSED (active + closed), SprintState.ALL (all states). Optional, defaults to None (all states).
+- **start_date** (`string`, optional) Start date filter in YYYY-MM-DD format. Can combine with end_date. Optional, defaults to None.
+- **end_date** (`string`, optional) End date filter in YYYY-MM-DD format. Can combine with start_date. Optional, defaults to None.
+- **specific_date** (`string`, optional) Specific date in YYYY-MM-DD to find sprints active on that date. Cannot combine with start_date/end_date. Optional, defaults to None.
+- **atlassian_cloud_id** (`string`, optional) Atlassian Cloud ID to use. Optional, defaults to None (uses single authorized cloud).
+
+
 ## Jira.ListLabels
 
 <br />
@@ -784,6 +816,31 @@ Get the details of a Jira project by its ID or key.
 - **atlassian_cloud_id** (`string`, optional) The ID of the Atlassian Cloud to use (defaults to None). If not provided and the user has a single cloud authorized, the tool will use that. Otherwise, an error will be raised.
 
 
+## Jira.GetBoards
+
+<br />
+<TabbedCodeBlock
+  tabs={[
+    {
+      label: "Call the Tool Directly",
+      content: {
+        Python: ["/examples/integrations/toolkits/jira/get_boards_example_call_tool.py"],
+        JavaScript: ["/examples/integrations/toolkits/jira/get_boards_example_call_tool.js"],
+      },
+    },
+  ]}
+/>
+
+Retrieve Jira boards either by specifying their names or IDs, or get all
+
+**Parameters**
+
+- **board_identifiers_list** (`array[string]`, optional) List of board names or numeric IDs (as strings) to retrieve using pagination. Include all mentioned boards in a single list for best performance. Default None retrieves all boards. Maximum 50 boards returned per call.
+- **limit** (`integer`, optional) Maximum number of boards to return (1-50). Defaults to max that is 50.
+- **offset** (`integer`, optional) Number of boards to skip for pagination. Must be 0 or greater. Defaults to 0.
+- **atlassian_cloud_id** (`string`, optional) Atlassian Cloud ID to use. Defaults to None (uses single authorized cloud).
+
+
 ## Jira.GetPriorityById
 
 <br />

pages/toolkits/productivity/jira/reference.mdx

@@ -2,6 +2,18 @@
 
 Below is a reference of enumerations used by some tools in the Jira toolkit:
 
+## SprintState
+
+Sprint states are used in the `Jira.ListSprints` tool to filter sprints. The following enumeration values represent the possible states supported by the Jira API, either individually or in combination:
+
+- **FUTURE**: `future`
+- **ACTIVE**: `active`
+- **CLOSED**: `closed`
+- **FUTURE_AND_ACTIVE**: `future_and_active`
+- **FUTURE_AND_CLOSED**: `future_and_closed`
+- **ACTIVE_AND_CLOSED**: `active_and_closed`
+- **ALL**: `all`
+
 ## PrioritySchemeOrderBy
 
 - **NAME_ASCENDING**: `name ascending`

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

@@ -0,0 +1,33 @@
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
+
+const USER_ID = "{arcade_user_id}";
+const TOOL_NAME = "Jira.GetBoards";
+
+// 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 = {
+  "board_identifiers_list": [
+    "123",
+    "Project Board"
+  ],
+  "limit": 10,
+  "offset": 0
+};
+
+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/get_boards_example_call_tool.py

@@ -0,0 +1,26 @@
+import json
+from arcadepy import Arcade
+
+client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
+
+USER_ID = "{arcade_user_id}"
+TOOL_NAME = "Jira.GetBoards"
+
+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 = {
+    'board_identifiers_list': ['123', 'Project Board'], 'limit': 10, 'offset': 0
+}
+
+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/list_sprints_for_boards_example_call_tool.js

@@ -0,0 +1,35 @@
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
+
+const USER_ID = "{arcade_user_id}";
+const TOOL_NAME = "Jira.ListSprintsForBoards";
+
+// 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 = {
+  "board_identifiers_list": [
+    "123",
+    "456"
+  ],
+  "max_sprints_per_board": 10,
+  "state": "active",
+  "start_date": "2023-01-01",
+  "end_date": "2023-12-31"
+};
+
+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/list_sprints_for_boards_example_call_tool.py

@@ -0,0 +1,30 @@
+import json
+from arcadepy import Arcade
+
+client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
+
+USER_ID = "{arcade_user_id}"
+TOOL_NAME = "Jira.ListSprintsForBoards"
+
+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 = {
+    'board_identifiers_list': ['123', '456'],
+    'max_sprints_per_board': 10,
+    'state': 'active',
+    'start_date': '2023-01-01',
+    'end_date': '2023-12-31'
+}
+
+response = client.tools.execute(
+    tool_name=TOOL_NAME,
+    input=tool_input,
+    user_id=USER_ID,
+)
+print(json.dumps(response.output.value, indent=2))