Forums

Learn about the different types of Forums 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 Forum content such as discussions and comments.

API Platform Version: 8.1 and later

Table of Contents

  1. What is a Forum?
  2. How do I access a Forum?
  3. What types of content can I add to a Forum?
  4. What types of Forum items show up on which Forums?
  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 forum 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 Forum?

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

The standard user interface includes the following forums:

  • API version forum: When an API is created, a forum is automatically created for the first version. If a new version is added to the API, a new forum for that version is also created. The API version forum includes only forum items relating to that specific version.

    Navigation: API > choose API version > Forum

  • App version forum: When an app is created, a forum is automatically created for the first version. If a new version is added to the app, a new forum for that version is also created. The app version forum includes only forum items relating to that specific version.

    Navigation: App > choose app version > Forum

  • Group forum: Each time a group is created, a forum is created for the group so that group members can collaborate.

    Navigation: Group > Forum

  • User forum: Each user has a personal forum, available via the top navigation bar. The user forum aggregates forum entries for all apps, APIs, and groups the user is associated with.

    Navigation: Top navigation bar > Forum

Back to top

How do I access a Forum?

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

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

Back to top

What types of content can I add to a Forum?

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

  1. Forum item types that are added by users directly to the forum:
    • Discussions (apps, APIs, groups)
    • Reviews (apps, APIs, groups)
    • Tickets (apps, APIs)
    • Alerts (APIs)
  2. Forum 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 Forum items show up on which Forums?

Any Forum item relating to an app or group on the platform is posted to the Forum for that resource. APIs do not have a Forum; however, all Forum entries associated with any API, app, or group also post to the user forum for any users associated with that resource.

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

This Forum item type... Is posted to this Forum/Forums...
Alert API, app; user forum for users associated with the applicable app or API.
API Access Request (Contract request) API, app; user forum for users associated with the applicable app or API.
Discussion The resource the discussion relates to (API, app, or group); user forum for users associated with the applicable app, API, or group.
Group Membership Invitation Group forum; user forum for the invited user and existing group members.
Review The resource the discussion relates to (API, app, or group); user forum for users associated with the applicable app, API, or group.
Ticket not associated with a specific app API forum; User forum for user who wrote the ticket and users associated with the applicable API.
Ticket associated with a specific app API, app; User forum for user who wrote the ticket and users associated with the applicable app and API.

Note: Reviews are a Forum item type but do not show up on the Forum for a resource; instead, instead, they are visible on the Details page for the resource (app or API). In addition, all reviews are visible on the user forum for users associated with the applicable resource.

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

  • Business Admin: can approve all forum item types.
  • Site Admin: can approve all forum item types.
  • API Admin: can approve forum 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 forum 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.

For instructions, see How do I add a discussion, ticket, or alert? below.

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.

For instructions, see How do I add a discussion, ticket, or alert? below.

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.

For instructions, see How do I add a discussion, ticket, or alert? below.

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 Forum.
  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 Forum.
  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 Implementation (Sandbox or Live). 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 Forum.
  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 Implementation (Sandbox or Live).
  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. Forum 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.
  • 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 Scope 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.

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

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