Using Boards

Learn about the different types of Boards and how you can use them to add or contribute to discussions, tickets, or alerts, or write reviews, to stay informed and collaborate. Learn about using markdown in Board content such as discussions and comments.

Table of Contents

  1. What is a Board?
  2. How do I access a Board?
  3. What types of content can I add to a Board?
  4. What types of resources can I add reviews for?
  5. I added a discussion/alert/ticket. Why can't other users see it?
  6. Who has to approve board items that I add?
  7. Who can add a discussion?
  8. Who can add a ticket?
  9. Who can add an alert?
  10. Who can add a review?
  11. How do I add a discussion, ticket, or alert?
  12. How do I comment on a discussion, ticket, or alert?
  13. How do I add a review?
  14. What information is displayed in the user Dashboard?
  15. Can I control which items appear on my Dashboard?
Using Markdown
  1. What markdown version does the platform support?
  2. How do I use markdown in my discussions, tickets, alerts, reviews, or comments?
  3. I want to use markdown to add formatting to my discussion, ticket, alert, review, or comment, but don't have the option. Why not?
  4. How do I add heading styles to my markdown?
  5. How do I add emphasis (bold, italics, or strikethrough) to my markdown?
  6. How do I add blockquotes to my markdown?
  7. How do I add lists to my markdown?
  8. How do I add code tags to my markdown?
  9. How do I add tables to my markdown?
  10. How do I add links to my markdown?
  11. How do I add a horizontal rule to my markdown?
  12. What kind of images can I add to my discussion, ticket, alert, or review?
  13. How do I add an image to my discussion, ticket, alert, review, or comment?
  14. What kind of files can I add to my discussion, ticket, alert, review, or comment?
  15. How do I add a file to my discussion, ticket, alert, review, or comment?

What is a Board?

In the developer portal, a board is a forum where users with similar interests or responsibilities can share information, report issues, and participate in discussions.

The standard user interface includes the following boards:

The platform also includes, for each user, a user Dashboard. The Dashboard is an aggregate of all the boards that the user is following.

Back to top

How do I access a Board?

For instructions to access different types of boards, refer to the table below.

To access this type of board... Follow these steps...
User's Dashboard In top navigation bar, click Dashboard.
App board My Apps > specific app > at top right, choose app version > on left menu, click Board.
Group board My Groups > specific group > on left menu, click Board.
API board My APIs > specific API > at top right, choose API version > on left menu, click Board.

Back to top

What types of content can I add to a Board?

Depending on the nature of a specific board, it might contain one or more of the following board item types, which fall into two categories:

  1. Board item types that are added by users directly to the board:
    • Discussions (apps, APIs, groups)
    • Reviews (apps, APIs, groups)
    • Tickets (apps, APIs)
    • Alerts (APIs)
  2. Board item types that are added as a result of performing some other action:
    • Alerts
    • API access requests (Contract requests)
    • Group membership invitations

Back to top

What types of resources can I add reviews for?

You can add reviews for the following resources:

For instructions, see How do I add a review?

Back to top

I added a discussion/alert/ticket. Why can't other users see it?

If moderation is turned on in the version of the developer portal you are using, the content you add has to be approved, usually by an Administrator, before it's published.

When you add content and it's pending approval, it's visible only to you and to users who are authorized to approve it. When it's published, it's visible to all who have visibility of the resource, such as an app, API, or group.

Back to top

Who has to approve board items that I add?

If moderation is turned on in the version of the developer portal you are using, the content you add has to be approved before it's published.

In most cases, users with the following roles can approve board items:

Note: The above is the default behavior. In some cases, behavior might be modified by a custom workflow.

Back to top

Who can add a discussion?

An authorized user can add a discussion to the board for an app, API, or group:

Back to top

Who can add a ticket?

An authorized user can write a ticket on an app or API:

Back to top

Who can add an alert?

An authorized user can write an alert on an API. To write an alert, you must be an API Admin.

Note: In addition to user-generated alerts, some alerts are generated by the platform based on certain events.

Back to top

Who can add a review?

You can write a review for any app, API, or group you have access to.

You must be logged in to write a review.

For instructions, see How do I add a review?

Back to top

How do I add a discussion, ticket, or alert?

An authorized user can:

To add a discussion for an app, API, or group:
  1. On the top navigation bar, click My Apps, My APIs, or My Groups, and choose the specific app, API, or group.
  2. At the Details page for the resource, on the left menu bar, click Board.
  3. Click the Discussion topic type.
  4. Click the What do you want to discuss? text box to expand it.
  5. Enter a title for the discussion.
  6. Enter one or more tags to identify the discussion. Tags are used by the search feature to help users find your content.
  7. Enter information about what you want to discuss. If you see additional icons, markdown is supported. For details about adding markdown formatting, links, and files, see How do I use markdown in my discussions, tickets, alerts, reviews, or comments? If the icons are not visible, only plain text is supported.
  8. Click Submit.

Note: Depending on the platform's moderation settings, the discussion is either published immediately or goes through an approval process during which time it's visible only to you and to users who are authorized to approve it.

To write a ticket on an app or API:
  1. On the top navigation bar, click My Apps or My APIs and choose the specific app or API.
  2. At the Details page for the app or API, on the left menu bar, click Board.
  3. Click the Ticket topic type.
  4. Click the What issues would you like to report? text box to expand it.
  5. Enter a title for the ticket.
  6. Enter one or more tags to identify the ticket. Tags are used by the search feature to help users find your content.
  7. Enter information about the ticket. If you see additional icons, markdown is supported. For details about adding markdown formatting, links, and files, see How do I use markdown in my discussions, tickets, alerts, reviews, or comments? If the icons are not visible, only plain text is supported.
  8. Specify priority (minor, major, or critical) and environment (sandbox or production). If applicable, specify which of your apps the ticket relates to.
  9. Click Submit.

Depending on the platform's moderation settings, the ticket is either published immediately or goes through an approval process during which time it's visible only to you and to users who are authorized to approve it.

To add an alert for an API:
  1. On the top navigation bar, click My APIs and choose the API.
  2. At the API Details page, on the left menu bar, click Board.
  3. Click the Alert topic type.
  4. Click the text box to expand it.
  5. Enter a title for the alert.
  6. Enter one or more tags to identify the alert. Tags are used by the search feature to help users find your content.
  7. Enter information about the alert. If you see additional icons, markdown is supported. For details about adding markdown formatting, links, and files, see How do I use markdown in my discussions, tickets, alerts, reviews, or comments? If the icons are not visible, only plain text is supported.
  8. Specify priority (minor, major, or critical) and environment (sandbox or production).
  9. Click Submit.

Depending on the platform's moderation settings, the alert is either published immediately or goes through an approval process during which time it's visible only to you and to users who are authorized to approve it.

Back to top

How do I comment on a discussion, ticket, or alert?

To add a comment on a discussion, ticket or alert, just click into the Write a Comment box to expand the canvas.

Type the comment, and then click Post.

If markdown is supported for comments on the platform, you'll see the markdown icons above the comment box. For more information, see How do I use markdown in my discussions, tickets, alerts, reviews, or comments?

Back to top

How do I add a review?

You can write a review for an app, API, or group.

To write a review:
  1. Navigate to the Details page for the app, API, or group you would like to review.
  2. Go to the Write a Review section.
  3. Enter a title for the review.
  4. Write the review. If you see additional icons, markdown is supported. For details about adding markdown formatting, links, and files, see How do I use markdown in my discussions, tickets, alerts, reviews, or comments? If the icons are not visible, only plain text is supported.
  5. Click Save.

Depending on the platform's moderation settings, the review is either published immediately or goes through an approval process during which time it's visible only to you and to users who are authorized to approve it.

Note: If someone comments on your review, you receive a notification email.

Back to top

What information is displayed in the User Dashboard?

The Dashboard is a configurable information system that helps users stay informed about relevant activity in the developer portal. Each user's Dashboard is an aggregate of information relating to all the boards that the user is following, including boards for apps, APIs, and groups. It's like a newsfeed.

When you log in to the platform, the first page that displays is your personal Dashboard page. If you're on another page, you can get to your Dashboard by clicking the link in the top navigation bar.

An individual user's Dashboard includes information such as:

For more information on notifications and newsfeed functionality, see How do I enable or disable email notifications, How do notifications work?, and What information is displayed on my Dashboard?

Back to top

Can I control which items appear on my Dashboard?

There are a couple of ways you can help make sure you have relevant information on your Dashboard, without having so many messages that you miss important ones. You can:

Back to top

Using Markdown

 

What markdown version does the platform support?

If markdown is enabled for discussions, tickets, alerts, reviews, or comments, the platform supports adding formatting, and possibly images, links, and files, with a subset of a flavor of markdown called CommonMark. For more information, see http://spec.commonmark.org/0.19. For information on the specific subset that's supported, use the help link in the developer portal (see below) and/or review the topics in this document.

You can also review the examples page.

Help in the developer portal: For help with the markdown, including examples, click the help button in the document window when you're adding a discussion, ticket, alert, review, or comment with markdown support. The inline help page shows the markdown you can use and also what it will look like to users.

Back to top

How do I use markdown in my discussions, tickets, alerts, reviews, or comments?

When you create discussions, tickets, alerts, or reviews, or comment on an existing discussion, ticket, or alert, there are two text formats that might be available:

If markdown is enabled for the resource, you'll see icons above the textbox where you enter the main content. The example shown below is for Discussions.

markdown icons

The first icon allows you to upload a file into your markdown; the file itself is not displayed, but users see a clickable link and can download the file. The second icon allows you to upload an image, which will be displayed inline in your content.

To enter markdown comments, type the text, adding markdown as you go. To see how the markdown will look to viewers, click Preview. To continue writing, click back to the Source tab.

For information on how to add specific formatting, click the ? icon below the Tags line. You can also review the topics below:

For information on how to upload files and add images for your markdown, see How do I add a file to my discussion, ticket, alert, review, or comment? and How do I add an image to my discussion, ticket, alert, review, or comment?

Back to top

I want to use markdown to add formatting to my discussion, ticket, alert, review, or comment, but don't have the option. Why not?

If you feel you should be able to use markdown, but the feature is not enabled, contact your Site Admin.

Back to top

How do I add heading styles to my markdown?

The platform's markdown feature supports six levels of heading. Use one hash sign (#) for Heading 1, a second for Heading 2, and so on. Make sure there's a space between the character and the heading text. See below.

For this style... Use these characters... Like this...
Heading 1 # # Heading 1 text
Heading 2 ## ## Heading 2 text
Heading 3 ### ### Heading 3 text
Heading 4 #### #### Heading 4 text
Heading 5 ##### ##### Heading 5 text
Heading 6 ###### ###### Heading 6 text

Back to top

How do I add emphasis (bold, italics, or strikethrough) to my markdown?

To add inline bold, italics, or strikethrough to your copy, use the formatting shown below.

Just add the required characters before and after the copy you want to format.

For this style... Use these characters... Like this...
Bold **Text** **This is bold text**
Bold, alternative __Text__ __This is bold text__
Italics *Text* *This is italic text*
Italics, alternative _Text_ _This is italic text_
Strikethrough ~~Text~~ ~~This is strikethrough text~~

Back to top

How do I add blockquotes to my markdown?

To indent one level, just use the greater than character as shown below.

For this style... Use these characters... Like this...
Indented once > >This is indented copy
Indented twice >>

>This is indented copy

>>This is indented even more

Indented additional times >>> etc.

>This is indented copy

>>This is indented even more

>>>This is indented even more

Back to top

How do I add lists to my markdown?

You can add ordered (numbered) lists, unordered (bulleted) lists, and nested lists. Follow the instructions and examples below.

For this style... Use these characters... Like this...
Unordered list (bullets) + or - or * (followed by a space)
+ JSON
+ XML
- JSON
- XML
* JSON
* XML
these all render as:
  • JSON
  • XML
Ordered list (numbers)* Number plus period. For example: 1. (followed by period then space).
1. Java
1. C++
1. Perl
1. Java
2. C++
3. Perl
1. Java
2. C++
4. Perl
these all render as: 1. Java
2. C++
3. Perl
Ordered list, not starting at 1 Starting number in the first position (followed by period then space).
3. Java
7. C++
7. Perl
becomes 3. Java
4. C++
5. Perl
   
Sub-list List characters plus indent two spaces - Java
- Perl
  * sub first
    * sub second

*On ordered lists, whatever number you use on the first item becomes the starting number. Whatever numbers you use for subsequent items, the list is numbered sequentially from the first number.

Back to top

How do I add code tags to my markdown?

You can format whole lines or sections of code, or just a fragment of code that's an inline part of your content. See below.

For this style... Use these characters... Like this...
Inline `{code text}` Here is a code example inline: `var x = 10`.
Code font plus box around

```

{code text}

```

```

<licenses>
  <license name="Beta"/>
</licenses>

```

Back to top

How do I add tables to my markdown?

To add a table to your markdown, use the hyphen and bar characters to create a grid. See below.

| Option | Description |
| ------ | ----------- |
| Discussion | Allows users to share information on a specific topic. |
| Ticket | Reports an issue with a resource. |
| Alert | Informs users about an issue. |

Alignment:

To right align table rows, use a colon at the bottom right of the header row as shown below.

| Option | Description |
| ------:| -----------:|

Back to top

How do I add links to my markdown?

To add a link, enclose the link text, that users will click, in a set of square brackets. Then put the actual URL in parentheses right next to it. See below.

[link text](http://www.example.com)

To add hover text to a link, add a forward slash after the URL, then add the hover text in double quotes, and then close the parentheses. See below.

[link text](http://www.example.com/ "title text!")

For example:

To find out more, go to [our website](http://www.example.com "find out more at our website!")!

Note: Depending on the platform settings, it's possible that markdown is enabled but links are disabled. If links are disabled and you add a link to an external site or resource in your markdown, you'll see an error message.

Back to top

How do I add a horizontal rule to my markdown?

To add a horizontal rule, make a line of at least three of any one of the following characters:

___

***

Back to top

What kind of images can I add to my discussion, ticket, alert, review, or comment?

When you're adding a discussion, ticket, alert, review, or comment, and markdown is supported, you can upload an image file to display in your content. The supported image file types are:

Back to top

How do I add an image to my discussion, ticket, alert, review, or comment?

When you're adding a discussion, ticket, alert, review, or comment, and markdown is supported, you can upload an image and display it inline in your content.

Follow the steps below.

To add an image to a discussion, ticket, alert, review, or comment:
  1. Navigate to the resource you want to add content for, and click to expand the discussion, ticket, alert, review, or comment box.
  2. Click the Upload an Image icon.
  3. Navigate to the location of the image and select it.
  4. Click Upload. The image is uploaded and displayed below the canvas window, and the code for the image is displayed on the canvas. For example:
    ![image](img_dollars.jpg "img_dollars.jpg")
  5. To view your content, including the image, click the Preview tab. Adjust the code as needed. By default, the file name is used as the hover text, enclosed in double quotes. If needed, you can change it to a more helpful description for the image.
  6. When you're satisfied with your content, click Submit.

Back to top

What kind of files can I add to my discussion, ticket, alert, review, or comment?

When you're adding a discussion, ticket, alert, review, or comment, and markdown is supported, you can upload a file and then link to it inline in your content. Some examples of supported image file types are:

Back to top

How do I add a file to my discussion, ticket, alert, review, or comment?

When you're adding a discussion, ticket, alert, review, or comment, and markdown is supported, you can upload a file and then link to it inline in your content. For example:

Download our tutorial PDF: [oauth_tutorial.pdf](oauth_tutorial.pdf "OAuth Tutorial PDF")

Follow the instructions below.

To add a file to a discussion, ticket, alert, review, or comment:
  1. Navigate to the resource you want to add content for, and click to expand the discussion, ticket, alert, review, or comment box.
  2. Click the Upload a File icon.
  3. Navigate to the location of the file and select it..
  4. Click Upload. The file is uploaded and displayed below the canvas window, and the code for the link to the file is displayed on the canvas. For example:
    @[filelink](business-export.zip)
  5. To view your content, including the link, click the Preview tab.
  6. When you're satisfied with your content, click Submit.

Back to top