Boards in the Community Manager developer portal

In the Community Manager developer portal, a board is a forum where users with similar interests or responsibilities can share information, report issues, and participate in discussions. The portal includes specific types of boards, and other types of boards can be created or customized. Each board includes information of a certain type or types; for example, an app version board includes information relating to the app version and for associated APIs. Types of information are categorized as Board Item Types.

This topic provides an overview of the different types of boards, how they work, who can access them, and the types of information displayed on boards. It includes:

Boards: General Guidelines

Here is some general information relating to boards and how they work:

  • Users must be logged in to create board entries.
  • Certain boards can support certain board item types. For example, the board for an API or an app can support discussions, tickets, alerts, and applicable group membership; the board for a group supports discussions and group membership, but not API contracts, tickets, or alerts.
  • In the portal, user-initiated board item types that are applicable to a specific board are shown at the top of the board. For example, on the board for a group, the only user-initiated item type available is Discussion. In the portal, the board for a group offers the logged-in group member the opportunity to create a discussion, with a visual cue at the top of the page.

Board Types

The portal includes two main board types:

  • System boards
  • User-defined boards

System boards

System boards are a part of the standard user interface. These include:

  • API board: When an API is created, a board is automatically created for the API. The API board includes board items for all versions of the API.
  • API version board: When an API is created, a board is automatically created for the first version. Each time you add a new version, a new board for that version is also created. The API version board includes only board items relating to that specific version. The board entries on the API version board are a subset of those on the API board.
  • App board: When an app is created, a board is automatically created for the app. The app board includes board items for all versions of the app.
  • App version board: When an app is created, a board is automatically created for the first version. Each time you add a new version, a new board for that version is also created. The app version board includes only board items relating to that specific version. The board entries on the app version board are a subset of those on the app board, in the same way that the API version board is a subset of the API board.
  • Group board: Each time a group is created, a board is created for the group so that group members can collaborate.

User-defined boards

Additional boards can be defined as part of site customization.

A few examples of custom boards:

  • New APIs: You could create a new board specifically for new APIs, so that all developers could visit the board to see what's new.
  • Developer issues: You could create a board for developer issues, and include a link in your customized site documentation so that a developer who experiences an issue can easily click through to browse through user-generated content for a solution.
  • Enhancement Suggestions: You could have a board for users to suggest enhancements to your product, and include a link to the enhancements board in your customized site documentation
  • Payment issues: If you have a board for payment issues, and offer a link in your customized site documentation so that a user with a payment concern can easily click through and enter comments.

These are all ways to service your customers and encourage engagement, participation, and collaboration between users.

The Support Board is also considered to be a user-defined board. The Support Board is available to all users, but is not part of the standard Community Manager developer portal user interface. The URL is: {protocol}://{hostname}/#/board/supportboard.{tenantfedmemberid}/board.

To view details of the support board, use the GET /api/boards/{BoardID} operation.

The Dashboard is not a board, but is a cumulative summary of items from all the boards that a specific user is following, as well as user-specific items. For more information about the Dashboard, see The User Dashboard below.

Board Item Types

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
    • Reviews
    • Tickets
  2. Board item types that are added as a result of performing some other action:
    • Alerts
    • API access requests (Contract requests)
    • Group membership invitations

The table below shows the board item types that are available on the standard boards in the Community Manager developer portal.

This board type... Can have these board item types...
API board

Any of the below that relate directly to the API, any version:

  • Alerts
  • API access requests (contract requests)
  • Discussions
  • Group Memberships (API Admins or groups associated with the API, only)
  • Reviews (of any API version)
  • Tickets
API version board

Any of the below that relate directly to the specific API version:

  • Alerts
  • API access requests (contract requests)
  • Discussions
  • Group Memberships (API Admins or groups associated with the API, only)
  • Reviews (of the API version)
  • Tickets
App board

Any of the below that relate directly to the app, any version:

  • Alerts
  • API access requests (contract requests)
  • Discussions
  • Group Memberships (app team only)
  • Reviews (of an associated API version)
  • Tickets
App version board

Any of the below that relate directly to the specific app version:

  • Alerts
  • API Access Request (Contract)
  • Discussions
  • Group Memberships (app team only)
  • Reviews (of an associated API version)
  • Tickets
Group board

Any of the below that relate directly to the specific group, or to an app or API the group is associated with:

  • Discussions
  • Group Memberships

Note: The group board does not allow tickets or alerts.
Support board Discussions

You can see from the above that the same board item might appear on multiple boards. Some scenarios:

An app developer initiates an API access request with a specific API version. The board item appears on the:

  • API board and applicable API version board
  • App board and applicable app version board
  • Dashboard for all API admins and app team members

Two apps have a contract with a specific API. A developer from App A writes a ticket on the API, referencing his app. The ticket appears on the:

  • API and applicable API version board
  • App board and applicable app version board for App A (visible to app developers but not general users)
  • Dashboard for all API admins
  • Dashboard for all developers associated with App A

The certificate for App C is updated. The app does not have any API contracts. The board item appears on the:

  • App board and applicable app version board for App C
  • Dashboard for all developers associated with App C

Comments

The following board item types support comments:

  • Discussion
  • Review
  • Ticket

Once a Discussion, Review, or Ticket has been created—and approved, if approval is needed before publication—users who are logged in and have visibility of the resource can comment on the board item. Comments on a board item are governed by the Comments workflow, not the workflow for the board item type itself. So, for example, discussions can have a custom workflow and comments on discussions have a different workflow, which can also be customized.

Depending on the comments workflow, comments might need to be approved before publication. In this case, the comments workflow defines whether a specific user can see the comment or not. In general, users authorized to approve the comment for publication, such as a Site Admin, have visibility of the comment. The original author always has visibility of his/her own comments. Other site users generally do not have visibility of unpublished comments even if they have visibility of the resource that the parent discussion, review, or ticket is associated with. Once the comment is published, all users who have visibility of the resource have visibility of the comment.

Note that comments are not nested, they are a flat list. This means that users cannot comment on another comment, only on the original discussion, review, or ticket.

The User Dashboard

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

  • Board items relating to all apps the user is associated with and is following. When a user creates an app, the follow relationship is created by default, but the user can still unfollow the app, in which case items relating to that app would not appear on the user's Dashboard.
  • Board items relating to all APIs the user is associated with and is following. Even if the user created the API, the follow relationship is not created by default.
  • Invitations to join a platform group, and board items relating to all groups the user is a member of.
  • Board items intended for that specific user (welcome message).

Visibility: Boards

There are several factors that affect the visibility of boards and board items. They are:

  • The visibility of the resource that the board relates to. If an app, API, or group is private, visibility is restricted to those who have visibility of the resource that the board is associated with.
  • The visibility of the individual board item types. There are specific rules associated with board item types; for example, a ticket on an API might be visible to some users who have visibility of the API but not to others. For more information, and examples, see Visibility: Board Item Types below.
  • The workflow state of the board item entry. For example, published content has the same visibility as the resource it relates to; unpublished content has a more limited audience. For more information, and examples, see Forum Moderation below.
  • For user-defined boards: visibility is defined as part of defining the board. User-defined boards are commonly used for public boards.

Note: Although the board might be visible, some board items might not be visible to different users, depending on the board item types, the user's role, and the workflow state of the board item type. For more information, see below.

Visibility: Board Item Types

Content for user-generated board item types (discussions, reviews, and tickets), as well as for comments on any of these, is governed first by the visibility rules for the resource. For example, a discussion relating to a private app is visible only to users who have visibility of the app.

In addition, there are visibility rules that might further limit visibility of certain board item types. For example:

  • Ticket visibility is governed by a platform setting, controlled by the Site Admin (Administration > Settings > Tickets > Visibility). If ticket visibility is set to Private, tickets are visible to the submitter, API Admins, and app team members only if the ticket was submitted in the context of a specific app. Users who are not app team members cannot see the ticket, even if the app is public.
  • If an app certificate is modified, there is a board item that only app team members can see, even if the app is public. General users do not see this board item.
  • An alert is written on an API. The alert entry is published on the board for the API and the specific API version, and on the board for all apps that are connected to the API. However, only the API admins and app team members see this alert, even if both the app and the API are public. Visibility is limited to team members.

Finally, if an approval process is in place, visibility of board item types is further limited by the publication state. If a new review or comment is pending approval, the pending content is only visible to the author and to authorized approvers. For more information, see Forum Moderation below.

Forum Moderation

Depending on how your installation is set up, board items might be moderated. In some cases, an item such as a discussion, review, or comment might need to be approved by an Administrator before it’s published. In this scenario, visibility of the unpublished user-generated content is governed as follows:

  • Items that are pending approval are visible only to the author and to members of the Admin team who are authorized to approve (or reject) the content.
  • Items that are approved are visible to all users who have visibility of the resource.

As an illustration, let’s take an example of a moderated discussion relating to a private API, API XYZ. A developer, whose app has a contract with the API, starts the discussion. Initially, this discussion is in an Unpublished state. At this point, it is only visible to API Admins who are authorized to approve it. Once it is approved by an API Admin, all users who have visibility of the API now see the new discussion:

  • API admins
  • Members of independent groups that are connected to the API
  • Members of the app team for any apps that are connected to the API
  • Business admins

If a discussion is created by the API admin, it's published automatically without the need for approval.

Let's say a specific user, John Thomas, comments on the discussion. His comment is pending approval. John can see his own comment immediately. Users with the authority to approve the comment also see it; in this case, API admins and business admins. Once a business admin approves the comment, it is visible to all users who have visibility of the API.

Note: The above is a description of the default workflow for the portal. If a custom workflow is in effect, the behavior might be different.

Custom Workflow

Many board item types can be governed by a custom workflow definition. The information in this document refers to the default behavior; custom workflow might define different states for the board item types and different transitions and behaviors.

For more information about custom workflows, refer to Custom Workflows in the Community Manager developer portal.

Platform API: Board Service

For general information about the Boards service, a description of each operation, and links to operations, see Boards Service: Overview.