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 Board items show up on which Boards?
5. What types of resources can I add reviews for?
6. I added a discussion/alert/ticket. Why can't other users see it?
7. Who has to approve board items that I add?
8. Who can add a discussion?
9. Who can add a ticket?
10. Who can add an alert?
11. How do I add a discussion, ticket, or alert?
12. How do I comment on a discussion, ticket, or alert?
13. Who can add a review?
14. How do I add a review?
15. What information is displayed in the user Dashboard?
16. 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:

• API version board: When an API is created, a board is automatically created for the first version. If a new version is added to the API, a new board for that version is also created. The API version board includes only board items relating to that specific version.
• App version board: When an app is created, a board is automatically created for the first version. If a new version is added to the app, a new board for that version is also created. The app version board includes only board items relating to that specific version.
• Group board: Each time a group is created, a board is created for the group so that group members can collaborate.

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.

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 Board items show up on which Boards?

In general, any Board item relating to a basic resource on the platform, such as an app or API, is posted to the Board for that resource. A specific user's Board only includes Board items relating to that user, not to the apps and APIs the user is associated with, since the user's associations might change. An individual user can view Board items for an app or API by going to the applicable app or API's Board..

For specific Board item types, and the Board each is posted to, refer to the table below.

Note: Reviews are a Board item type but do not show up on the Board for a resource; instead, they are visible on the Details page for the resource (app or API).

Back to top

What types of resources can I add reviews for?

You can add reviews for the following resources:

• Apps
• APIs
• Groups

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:

• Business Admin: can approve all board item types.
• Site Admin: can approve all board item types.
• API Admin: can approve board items relating to the specific API.

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:

• For an app, you must be logged in and have visibility of the app. For a public app, you do not need to be a member of the app team.
• For an API, you must be an API Admin, a member of a group associated with the API, or an app developer for an app that has a contract with the API.
• For a group, you must be logged in and have visibility of the group.

Back to top

Who can add a ticket?

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

• For an app, you must be an app developer.
• For an API, you must be an API Admin, a member of a group associated with the API, or an app developer for an app that has a contract with the 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

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

An authorized user can:

• Add a discussion for an app, API, or group (user with visibility of the app, API, or group)
• Add a ticket for an app or API (user with visibility of the app or API)
• Add an alert for an API (API Admin or Business Admin only)

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

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 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:

• Changes to apps the user is associated with. When a user creates an app, the follow relationship is created by default, but the user can still unfollow the app, in which case future items relating to that app are not posted to the user's Dashboard. Changes include:
  • New or deleted app versions.
  • App contracts with an API: new, changed, or deleted contracts.
  • App team changes: members added or removed.
  • Notifications about tickets relating to the app.
• Changes to APIs the user is following. Even if the user created the API, the follow relationship is not created by default, but the user can choose to follow the API. Board items relating to APIs include:
  • New or deleted API versions.
  • API contracts: new, changed, or deleted contracts.
  • API Admin changes: API Admins added or removed.
  • Notifications about tickets relating to the API.
  • Alerts relating to the API.
• Changes to groups the user is associated with:
  • Invitations to join a group, change in membership status, removal from a group.
  • Changes in group membership: group members added or removed, change in membership status for another group member.
• Board items intended for that specific user (welcome message).

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:

• Edit your user settings to reduce the number of different types of notifications you receive. See To edit user settings. You can check or clear the boxes to receive notifications when:
  • Your apps receive alerts
  • There are major changes to your app's lifecycle
  • Posts are created for your apps
  • There are changes to your app's team
  • There are changes to your app's access to APIs
  • Someone comments on your post
  • There are changes to your API Context Group

  You can also choose to receive news updated by email.

• Follow, or unfollow, resources depending on your level of interest. You can follow:
  • Apps: If you create an app, the follow relationship is created automatically. To unfollow, go to the App Details page and click Unfollow. You will no longer receive notifications relating to that app.
  • APIs: With an API, the follow relationship isn't created automatically, but you can follow an API to receive notifications about it. Go to the API Details page and click Follow.
  • Groups: If you create a group, the follow relationship is created automatically. To unfollow, go to the Group Details page and click Unfollow. You will no longer receive notifications relating to that group.

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:

• Plain text—always available.
• Markdown—available only if enabled for the type of content, such as discussions. The Markdown feature is enabled in the platform settings, by the Site Admin.

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.

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:

• How do I add heading styles to my markdown?
• How do I add emphasis (bold, italics, or strikethrough) to my markdown?
• How do I add blockquotes to my markdown?
• How do I add lists to my markdown?
• How do I add code tags to my markdown?
• How do I add tables to my markdown?
• How do I add links to my markdown?
• How do I add a horizontal rule to my markdown?

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.

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.

Back to top

How do I add blockquotes to my markdown?

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

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.

*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.

<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:

• Underscore
• Asterisk

___

***

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:

• JPG or JPEG
• GIF
• PNG
• TIF or TIFF
• BMP

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:

• PDF
• ZIP

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