Ideas Tools¶
The ideas_* tools work with idea labs and ideas: finding and reading them, submitting and editing ideas, voting and following, creating and deleting labs, and turning an idea into a wiki page.
The tools are in the ideas tool group, except ideas_to_page, which is in crossapp. They need Huddo Ideas; ideas_get_idea also needs Discussions, and ideas_to_page also needs Wikis.
Tools that act on one lab take its labId or its url, and tools that act on one idea take its ideaId or its url. Give one of them.
In a lab where ideas are anonymous, the tools hide who submitted each idea from everyone, lab owners included; they report the author as anonymous. The only exception is ideas_get_idea, which shows the user their own idea's author. In a lab where voting is anonymous, they hide who voted.
Lab stages and idea statuses¶
A lab's stage is voting, review or completed.
An idea's status is one of:
| Status | Meaning |
|---|---|
voting |
Open for votes |
in-review |
In review |
pending-promotion |
Waiting to be promoted |
successful |
Marked successful |
unsuccessful |
Marked unsuccessful |
Every Ideas tool reports statuses with these words, and ideas_to_page writes them into the pages it creates. The filter parameter of ideas_find_ideas uses the same words for voting, in-review and successful, but there's no filter for pending-promotion or unsuccessful. It also has filters that aren't statuses: completed, has-votes, following and all.
ideas_find_labs¶
Lists the idea labs the user can see.
Read-only · Needs: Ideas
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
filter |
string | No | all |
all, my-labs, active, completed or following |
sort |
string | No | recent |
recent, popular, deadline or trending |
groupId |
id | No | Only the labs in one space (the space's groupId) |
|
text |
string | No | Words to match in the lab's question, 1 to 200 characters | |
limit |
integer | No | 20 | 1 to 50 |
page |
integer | No | 1 | The page of results, starting at 1 |
text filters only the page of labs fetched, not every lab.
Returns: labs, each with id, question, stage, votingType, deadline, ideaCount, latestActivity and url; total; and page.
Example: "Which idea labs are open right now?"
ideas_get_lab¶
A lab in full: its question and description, stage, voting type and the user's votes left, its rules, the custom fields ideas must fill in, idea counts by status, its most-voted ideas, and whether the user follows it.
Read-only · Needs: Ideas
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
labId |
id | No | The lab's id | |
url |
URL | No | Instead of labId: the URL of the lab or one of its ideas |
|
includeAutomations |
boolean | No | false | Also list the lab's automations (what happens when an idea succeeds) |
maxChars |
integer | No | 4,000 | 200 to 20,000. The most characters of the description |
Returns: id, question, description (Markdown), stage, visibility, votingType, allocatedVotes, myVotesUsed and myVotesLeft (in a voting-pool lab); rules (deadline, votingTarget, ideaLimit, autoPromote); isAnonymous, isVotingAnonymous and voteJustificationRequired; customFields (id, label, required); ideasByStatus, the number of ideas in each of the five statuses; topIdeas, up to 5 ideas with at least one vote for them, in the Ideas service's vote ranking, each with id, title, url, status and votes (all-time net votes, which can be zero or less; they're read separately from the ranking, so a vote cast in between can leave the list slightly out of order). Ideas with only votes against them aren't listed; following; automations (if asked for); and url.
Example: "What's the Q4 innovation lab about, and how many votes do I have left?"
ideas_lab_summary¶
What's happened in a lab since a date: new ideas and who submitted them, older ideas that were edited or changed status, counts by status, and the ideas with the most votes cast since the date.
Read-only · Needs: Ideas
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
labId |
id | No | The lab's id | |
url |
URL | No | Instead of labId: the URL of the lab or one of its ideas |
|
since |
date or date-time | No | A week ago | Where the summary starts |
Returns: the lab (id, question, stage, URL) and since; newIdeaCount and up to 10 newIdeas (title, status, author, created, URL); updatedIdeaCount and up to 10 updatedIdeas (title, status now, updated, URL); countsByStatus, the number of ideas in each status; and mostVotedSince, up to 5 ideas with the most votes cast or changed since the date, each with id, title, votes and url. These votes count only that period; for all-time votes, use ideas_get_lab. The lab keeps no status history, so each idea shows its status now.
Example: "What's happened in the Customer Feedback lab this week?"
ideas_find_ideas¶
Lists ideas: the ideas in a lab, the user's own ideas across labs, the user's drafts in a lab, or the ideas they follow. To search inside idea descriptions, assistants use search_content with apps set to ideas.
Read-only · Needs: Ideas
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
scope |
string | No | lab |
lab, mine, drafts or following |
labId |
id | No | Required for lab and drafts |
|
filter |
string | No | all |
all, voting, in-review, successful, completed, has-votes or following |
sort |
string | No | recent |
recent, latest, votes, trending or status |
text |
string | No | Words to match in idea titles, 1 to 200 characters | |
limit |
integer | No | 20 | 1 to 50 |
offset |
integer | No | 0 | Ideas to skip, to read the next page |
text filters only the page of ideas fetched, not every idea.
Returns: scope, ideas and total. Each idea has id, labId, title, status (see statuses), isDraft, votes, myVotes, creatorId, updatedAt and url. Descriptions aren't included; read an idea with ideas_get_idea.
Example: "Show me the most-voted ideas in the Customer Feedback lab."
ideas_get_idea¶
One idea in full: its title and description, status, lab, author, votes and the user's own votes, who voted, custom field answers, the Boards board an automation created for it, and its comments.
Read-only · Needs: Ideas and Discussions
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
ideaId |
id | No | The idea's id | |
url |
URL | No | Instead of ideaId: the idea's URL |
|
maxChars |
integer | No | 4,000 | 200 to 20,000. The most characters of the description |
includeComments |
boolean | No | true | Include up to 20 of the idea's comments |
Returns: id, title, status, isDraft, lab (id, question, stage, voting type), creator, createdAt, updatedAt, votes, myVotes, voters (up to 20, or a note that voting is anonymous), customFields (label, required, answer), boardURL, markdown (the description), comments and url.
Example: "Summarise the idea about a four-day work week and the discussion on it."
ideas_create_lab¶
Creates an idea lab asking a question, open to the user's whole organisation to contribute ideas. The user becomes its owner. Everything else (theme, custom fields, limits, automations) starts with the defaults and can be changed in the lab's settings.
Write · Needs: Ideas
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
question |
string | Yes | 1 to 300 characters | |
description |
string | No | Markdown, up to 100,000 characters | |
votingType |
string | No | like |
like, like_dislike or voting_pool (20 votes for each person) |
deadline |
date-time | No | When the lab closes to new ideas. Must be in the future, with the user's time zone offset | |
groupId |
id | No | Create the lab in a space (the space's groupId). The user needs the right to add content to the space, and the space's owners also own the lab |
Returns: id, question, url, stage and next, what to tell the user.
Example: "Create an idea lab asking 'How can we cut our cloud costs?' with a deadline at the end of the month."
ideas_submit_idea¶
Submits an idea to a lab, as a draft that only the user can see, or published. It also publishes an existing draft.
Write · Needs: Ideas
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
labId |
id | No | The lab to submit to | |
ideaId |
id | No | Instead of labId: a draft to update or publish |
|
title |
string | No | 1 to 300 characters. Required for a new idea | |
body |
string | No | Markdown, up to 100,000 characters. Required to publish | |
customFields |
array | No | None | Up to 100 answers, each with a fieldId and a response (1 to 5,000 characters). Required fields must be answered to publish |
mentionUserIds |
array of user ids | No | None | Up to 20 people to mention. They're notified when the idea is published |
draft |
boolean | No | true | false publishes the idea |
An idea can't be published when the lab is past its voting stage or deadline, or has reached its idea limit.
Returns: id, title, status, isDraft, url and unresolvedMentions.
Example: "Submit an idea to the cloud costs lab: switch dev environments off overnight."
ideas_update_idea¶
Changes an idea's title, description or custom field answers. Only the fields given change; a new description replaces the whole description. It never changes the idea's status. Only the idea's author or a lab owner can update it.
Overwrite · Needs: Ideas
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
ideaId |
id | Yes | The idea's id | |
title |
string | No | 1 to 300 characters | |
body |
string | No | Markdown, up to 100,000 characters. Replaces the whole description | |
customFields |
array | No | Up to 100 answers, each with a fieldId and a response (1 to 5,000 characters) |
|
mentionUserIds |
array of user ids | No | None | Up to 20 people to mention |
Give at least one of title, body and customFields.
Returns: id, title, url and unresolvedMentions.
Example: "Add an estimated saving of $40k to my overnight shutdown idea."
ideas_delete_idea¶
Permanently deletes an idea, with its votes, comments and attachments. Only the idea's author or a lab owner can delete it.
Delete · Needs: Ideas
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
ideaId |
id | No | The idea's id | |
url |
URL | No | Instead of ideaId: the idea's URL |
|
confirmTitle |
string | Yes | The idea's exact title. A title that doesn't match is refused |
Returns: deleted, id and title.
Example: "Delete my duplicate idea about overnight shutdowns."
ideas_delete_lab¶
Permanently deletes a lab, with all its ideas and their votes, comments and attachments. Only a lab owner can delete it.
Delete · Needs: Ideas
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
labId |
id | No | The lab's id | |
url |
URL | No | Instead of labId: the lab's URL |
|
confirmQuestion |
string | Yes | The lab's exact question. A question that doesn't match is refused |
Returns: deleted, id, question and ideasDeleted.
Example: "Delete the test lab I created this morning."
ideas_vote¶
Sets the user's vote on an idea to a number. It can also post a justification for the vote as a comment on the idea.
Write · Needs: Ideas (a justification also needs Discussions)
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
ideaId |
id | No | The idea's id | |
url |
URL | No | Instead of ideaId: the idea's URL |
|
votes |
integer | Yes | The user's vote, not a change to it. See below | |
justification |
string | No | Markdown, 1 to 5,000 characters, posted as a comment. Not allowed when voting is anonymous |
The vote depends on the lab's voting type:
like: 0 or 1.like_dislike: -1, 0 or 1.voting_pool: 0 up to the votes the user has left.
Votes are only accepted while the lab is in its voting stage and the idea's status is voting. Some labs require a justification with a first vote on someone else's idea. A vote that's already at that number changes nothing and posts no comment.
Returns: ideaId, myVotes, ideaTotal, votesLeft (in a voting-pool lab) and justified.
Example: "Vote for the overnight shutdown idea, and say it would save us a lot on dev environments."
ideas_follow¶
Follows or unfollows a lab or an idea, so its activity reaches the user's inbox.
Write · Needs: Ideas
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
labId |
id | No | The lab to follow | |
ideaId |
id | No | Instead of labId: the idea to follow |
|
follow |
boolean | No | true | false unfollows |
Returns: the labId or ideaId, and following.
Example: "Follow the cloud costs lab."
ideas_to_page¶
Turns an idea into a wiki page. The page holds the idea's description, a properties block (a link to the idea, its lab, status, votes unless voting is anonymous, who submitted it unless ideas are anonymous, and each custom field's answer) and a link back to the idea. Images in the idea are copied onto the page, up to 20 images and 12 MiB in total. A link to the new page is added to the idea.
On a wiki without approvals, the page is live straight away. On a wiki with approvals, it's submitted for approval and readers see it blank until it's approved or published.
Write · Needs: Ideas and Wikis (announce also needs Discussions)
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
ideaId |
id | No | The idea's id | |
url |
URL | No | Instead of ideaId: the idea's URL |
|
wikiSlug |
string | Yes | The wiki to create the page in | |
parentSlug |
string | No | A page to create it under | |
announce |
boolean | No | false | Also post a comment on the idea with a link to the new page |
Returns: pageId, slug, pageUrl, next (what to tell the user), linkRefId, announced, and warnings for any step that didn't work, such as an image that couldn't be copied or a link the user wasn't allowed to add to the idea. The page is created even when a later step fails.
Example: "Turn the winning idea in the cloud costs lab into a page in the Platform wiki."