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.

Table of Contents

Using Markdown

What is a Forum?

In the Community Manager 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: APIs > My APIs > choose 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: Apps > My Apps > choose app > Forum

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

    Navigation: More > Groups > My Groups > choose 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: More > Forum

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 Apps > My Apps > choose app > Overview. At the top right, choose the app version. Then, on the left menu, click Forum.
API forum APIs > My APIs > choose API > Overview. At the top right, choose the API version. Then, on the left menu, click Forum.
Group forum More > Groups > My Groups > choose group > Forum
User's Forum In top navigation bar: More > Forum

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

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.

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?

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

If moderation is turned on in the version of the Community Manager 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.

Who has to approve forum items that I add?

If moderation is turned on in the version of the Community Manager 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.

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.

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.

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.

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, choose where you want to start the discussion:
    • Apps: Click Apps > My Apps > choose app > Forum.
    • APIs: Click APIs > My APIs > choose API > Forum.
    • Groups: Click More > Groups > My Groups > Forum.
  2. Click the Discussion topic type.
  3. Click the What do you want to discuss? text box to expand it.
  4. Enter a title for the discussion.
  5. Enter one or more tags to identify the discussion. Tags are used by the search feature to help users find your content.
  6. 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.
  7. 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, choose the app or API you want to write a ticket for:
    • Apps: Click Apps > My Apps > choose app > Forum.
    • APIs: Click APIs > My APIs > choose API > Forum.
  2. Click the Ticket topic type.
  3. Click the What issues would you like to report? text box to expand it.
  4. Enter a title for the ticket.
  5. Enter one or more tags to identify the ticket. Tags are used by the search feature to help users find your content.
  6. 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.
  7. Specify priority (minor, major, or critical) and Implementation (Sandbox or Live). If applicable, specify which of your apps the ticket relates to.
  8. 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 APIs > My APIs > choose API > Forum.
  2. Click the Alert topic type.
  3. Click the text box to expand it.
  4. Enter a title for the alert.
  5. Enter one or more tags to identify the alert. Tags are used by the search feature to help users find your content.
  6. 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.
  7. Specify priority (minor, major, or critical) and Implementation (Sandbox or Live).
  8. 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.

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

To add a comment on a discussion, ticket or alert, 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?

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?

How do I add a review?

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

To write a review

  1. Go 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.

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 Community Manager developer portal (see below) and/or review the topics in this document.

Help in the Community Manager 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.

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?

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.

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

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.

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

How do I add blockquotes to my Markdown?

To indent one level, 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

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) (plus see Note below) 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

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

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>

```

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

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.

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

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
  • BMP

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

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

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