Introduction

This document describes the key design problem statement and probable solutions for
Discussion-UI library integration with Sunbird Portal (or any partner application).

Background

No API exists to create the forum, add privileges, create groups.
As of now, We are using the admin panel to do so

Problem Statement

How to enable discussion forum from UI?
How can we create a forum without using the admin panel?
How to create sub-categories for a forum?
How to add privileges to the parent category and the sub-categories?

Key design problem:

Single API to create forum, categories, groups, privileges & adding users?

Solution:

Workflow Diagram: <diagram>

A form API will be created based on the action we are intending to add the Discussion for:

For courses:

Request:

{
    "request": {
        "type": "global",
        "subType": "forum",
        "action": "course" // It will be varied like: "groups" etc.
    }
}

Response:

{
  "response": {
    "primaryCategory": "course",
    "SbRoles": {
      "creator": {
        "type": "course",
        "identifier": "$courseId"
      },
      "mentor": {
        "type": "batch",
        "identifier": "$batchId"
      }
    },
    "forum": {
      "category": {
        "name": "Cateogry name",
        "pid": "{parent_category_id}",
        "description": "...",
        "context": [
          {
            "type": "course",
            "identifier": "$courseId"
          }
        ],
        "enbaleGroups": "true/false",
        "groups": [
          {
            "name": "Owner Group",
            "privileges": [
              "groups:topics:reply",
              "groups:topics:create"
            ]
          },
          {
            "name": "enrolled users group",
            "privileges": [
              "groups:topics:reply",
              "groups:topics:create"
            ]
          }
        ],
        "privileges": {
          "copytoChildren": "true/false",
          "copyFromCategory": "{category_id}"
        }
      },
      "subcategories": [
        {
          "name": "Annoucements",
          "pid": "{parent_category_id}",
          "description": "...",
          "context": [
            {
              "type": "batch",
              "identifier": "$batchId"
            }
          ],
          "privileges": {
            "copyFromCategory": "{category_id}",
            "groups": [
              {
                "name": "enrolled users group",
                "privileges": [
                  "groups:topics:reply"
                ]
              }
            ],
            "users": [
              {
                "uid": "{nodebb_uid}",
                "privileges": [
                  "groups:topics:reply"
                ]
              }
            ]
          }
        },
        {
          "name": "General discussions",
          "pid": "{parent_category_id}",
          "description": "...",
          "context": [
            {
              "type": "batch",
              "identifier": "$batchId"
            }
          ]
        }
      ]
    }
  }
}

For groups:

Create Form:

Endpoint:

POST: /data/v1/form/create

Request Body:

{
  "request": {
    "type": "forum",
    "subType": "group",
    "action": "create",
    "data": {
      "templateName": "defaultTemplate",
      "action": "create",
      "fields": [
        {
          "category": {
            "name": "General Discussion",
            "pid": "30",
            "uid": "4",
            "description": "",
            "context": [
              {
                "type": "group",
                "identifier": "_groupId"
              }
            ]
          }
        }
      ]
    }
  }
}

Fetching the form data:

Request:

{
    "request": {
        "type": "forum",
        "subType": "group",
        "action": "create"
    }
}

Response:

{
    "id": "api.form.read",
    "params": {
        "resmsgid": "f18a1975-8d64-4590-b419-be495cd9d6c4",
        "msgid": "255e08db-2464-4edd-aab6-cbde4308f53e",
        "status": "successful"
    },
    "responseCode": "OK",
    "result": {
        "form": {
            "type": "forum",
            "subtype": "group",
            "action": "create",
            "component": "*",
            "framework": "*",
            "data": {
                "templateName": "defaultTemplate",
                "action": "create",
                "fields": [
                    {
                        "category": {
                            "name": "General Discussion",
                            "pid": "30",
                            "uid": "4",
                            "description": "",
                            "context": [
                                {
                                    "type": "group",
                                    "identifier": "_groupId"
                                }
                            ]
                        }
                    }
                ]
            },
            "created_on": "2021-02-15T05:33:03.734Z",
            "last_modified_on": "2021-02-15T09:52:41.820Z",
            "rootOrgId": "*"
        }
    },
    "ts": "2021-02-15T10:14:08.707Z",
    "ver": "1.0"
}

As it is clear from the response, the form API will be used to perform the below tasks:

To get forum ids mapped to sbIdentifier.
To create a forum for a sbType. ( eg: “course“, “batch“, “group“ )

Fetch the attached category id for a particular sbType:

We will be using the below API to get the category_ids linked to a sbType:

Request:

Post: {host}/discussion/forum/v2/read   
{ 
  "request": {
    "type": "Course",
    "identifier": ["do_11317805943810457614592"]
  }
}

Response:

{
    "id": "api.discussions.category.forum",
    "ver": "1.0",
    "ets": 1609741189797,
    "params": {
        "resmsgid": "c9c1842d-3dfb-45df-b827-c31522f13fa4",
        "msgid": "",
        "status": "successful"
    },
    "responseCode": "OK",
    "result": [
        {
            "_id": "5ff2b287ac74be004547f69e",
            "sbType": "course",
            "sbIdentifier": "do_11317805943810457614592",
            "cid": 16,
            "__v": 0
        },
        {
            "_id": "3df2b287ac74be004547f78a",
            "sbType": "course",
            "sbIdentifier": "do_11317805943810457614547",
            "cid": 17,
            "__v": 0
        }
    ]
}

Now you can see the payload used to fetch the category ids will be fetched from the above form API itself. We will be using the "SbRoles" attached for a particular type.

{
  "SbRoles": {
    "creator": {
      "type": "course",
      "identifier": "$courseId"
    },
    "enrolledUser": {
      "type": "batch",
      "identifier": "$batchId"
    }
  }
}

It will vary for other types. For example, groups don't have a creator or enrolled users roles that exist. so it will be different from the courses.

Create forum:

Table to explain all the properties/fields of API

Property	Sub-property	Values	Description
name		{category name}	name of the category.
pid		{parent category id}	under which parent category, this category should get created.
Context	{ "type": "course", "identifier": "$courseId" } or { "type": "batch", "identifier": "$batchId” }	{ "type": "course", "identifier": "do_37819” } or { "type": "batch", "identifier": "0312047" }	type: this is the sbType identifier: this is the sbIdentifier if you want to add different types we have to change the value of types ex: “Course”, “Batch”, “Group”, “GroupMember”
enbaleGroups (to de discussed)		true / false	If set true then, It will be used to create groups to add privileges to a certain set of user (according to our requirement)
groups (optional)	{ "name": "<group name>", "privileges": [ < set of privileges > ] }	{ "name": "category owner", "privileges": [ "groups:topics:reply", "groups:topics:create" ] }	If this object is exist then create the group else don't create It will be used to define certain set of privileges so that it can be used for the categories. If `copyFromCategory` is defined, then this is optional. Because all the groups added for `copyFromCategory` will be adding to this category
privileges			To set some rules for the users, if we dont want to create the groups. That
	copytoChildren	true/false	This is used to copy the `groups` to all sub-categories The same group will be added to sub-categories with the privileges.
	copyFromCategory	{category_id}	When we mention this property, `groups` object will become optional. It will copy all the groups & privileges from the specified category & add it to the new category(with the same group name & privileges)
copytoChildren		true / false	If set, it will take the rules from the given category.
copyFromCategory			category_id, from where it should take the privileges. groups are optional when category_id mention here. It will copy the group & privileges from category_id
subcategories			categories which is gonna be created under the parent category
name		Example: “Announcement“, “General discussion“	name of the subcategory
pid			parent category id under which the sub-category will be created
description			description of the sub-category
context	{ "type": "batch", "identifier": "$batchId" }	{ "type": "batch", "identifier": "0123456" }	this is to communicate with the mapping table.
privileges			This is to override the privileges given at category level for group or user
copyFromCategory			category_id, from where it should take the privileges.
groups	{ "groups": [ { "name": "<group_name>", "privileges": [ <privileges for the group> ] } ] }	{ "groups": [ { "name": "enrolled users group", "privileges": [ "groups:topics:reply" ] } ] }	It will be used to define certain set of privileges so that it can be used for the categories. this is optional.
users	"users": [ { "uid": "{nodebb_uid}", "privileges": [ <previleges for given set of users> ] } ]	"users": [ { "uid": "test_df_1994", "privileges": [ "groups:topics:reply" ] } ]	the set of users, the privilges gonaa be set for.

Generalization api for Update(If there is any mistakes)

Mandatory Parameters

1. Master Token(masterToken)

2. Admin UID (adminUid)

Update Category Details

If you want to update parent category for a particular child category. Follow this API curl

curl --location --request PUT 'https://staging.sunbirded.org/discussions/api/v2/categories/{cid}?_uid={adminUid}' \
--header 'Authorization: Bearer {masterToken}' \
--header 'Content-Type: application/json' \
--header 'Cookie: express.sid=s%3AqiNDVx5w84QRoUGABEkEdq1cqO7bXP_y.MMB8cjhTP19d9Zv%2B%2FxiBtqctd0M%2FY7eQk9Q0tQSLqqc' \
--data-raw '{
    "parentCid": 61
}'

Property	Type
cid	path parameter
adminUid	query parameter
Authorization	header

Required Parameters

Path Parameters: you need to pass cid (which category id you have to move forum one category to another category).

Query Parameters: You have to pass admin uid for this api (It is mandatory).

Headers: You need to pass nodebb master token as a authorization token (it is mandatory).

Body: In body all are optional parameters, If you pass any value for a particular field, it will update that field. if you are not passing any parameters it won’t update any thing.

{
name: "New name", // optional
description: "New description", // optional
bgColor: "New bgColor", // optional
color: "New color", // optional
parentCid: "New parentCId", // optional
backgroundImage: "New backgroundImage" // optional
}

Update Group privileges For a category

If you want to update privileges for a particular group for a category follow this curl

curl --location --request PUT 'https://staging.sunbirded.org/discussions/api/v2/categories/{cid}/privileges?_uid={adminUid}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {masterToken}' \
--header 'Cookie: express.sid=s%3AY3Utp3Ffto0AkXex1QAmAK5HWn60mVz6.8ev45%2FlFxF6Piaje2GZh%2BJaRpIjWXETd5Mah8w5bx3M' \
--data-raw '{
    "privileges": ["groups:topics:reply", "groups:topics:create"],
    "groups": ["guests", "Category Owner"]
}'

Property	Type
cid	path parameter
adminUid	query parameter
Authorization	header

Required Parameters

Path Parameters: you need to pass cid (which category id you have to enable privileges).

Query Parameters: You have to pass admin uid for this api (It is mandatory).

Headers: You need to pass nodebb master token as a authorization token (it is mandatory).

Body:

Privileges : what are the privileges you wnat to enable.
Groups: To which group you have to add those privileges.

{
    "privileges": ["groups:topics:reply", "groups:topics:create"],
    "groups": ["guests", "Category Owner"]
}

List of privileges

Privilege	Value
`groups:find`	true/false
`groups:read`	true/false
`groups:topics:read`	true/false
`groups:topics:create`	true/false
`groups:topics:reply`	true/false
`groups:topics:tag`	true/false
`groups:posts:edit`	true/false
`groups:posts:history`	true/false
`groups:posts:delete`	true/false
`groups:posts:upvote`	true/false
`groups:posts:downvote`	true/false
`groups:topics:delete`	true/false
`groups:posts:view_deleted`	true/false
`groups:purge`	true/false
`groups:moderate`	true/false

Get groups List

To get list of groups, follow the below CURL

curl --location --request GET 'https://staging.sunbirded.org/discussions/api/groups' \
--header 'Cookie: express.sid=s%3AqiNDVx5w84QRoUGABEkEdq1cqO7bXP_y.MMB8cjhTP19d9Zv%2B%2FxiBtqctd0M%2FY7eQk9Q0tQSLqqc'

Add User into group

We can add user into a particular group manually, Followthis CURL

curl --location --request PUT 'https://staging.sunbirded.org/discussions/api/v2/groups/{groupSlug}/membership/{uid}?_uid={adminUid}' \
--header 'Authorization: Bearer {masterToken}' \
--header 'Cookie: express.sid=s%3AqiNDVx5w84QRoUGABEkEdq1cqO7bXP_y.MMB8cjhTP19d9Zv%2B%2FxiBtqctd0M%2FY7eQk9Q0tQSLqqc'

Property	Type
groupslug	path parameter
uid	path parameter
adminUid	query parameter
Authorization	header

Required Parameters

Path Parameters: you need to pass group slug (which group we want to addthe user) and nodebb UID (Which user you wnatto add).

Query Parameters: You have to pass admin uid for this api (It is mandatory).

Headers: You need to pass nodebb master token as a authorization token (it is mandatory).

Body: NO

Getting Nodebb UID's By sending Sunbird Identifiers

As we don’t know nodebb uids and we have only sunbird identifiers.so the below api will give you nodebb uids by sending sunbird identifiers.

curl --location --request POST 'http://localhost:4567/api/forum/v2/uids' \
--header 'Authorization: Bearer 550998a7-4036-4482-b152-03ff5dedcde0' \
--header 'Content-Type: application/json' \
--header 'Cookie: express.sid=s%3AafcKVNRDU5uKTnTDVIWvs1zZbtdfRYj9.2gZpGnKf6S8PhOk0GsDauciGdZ%2F%2BxPqNPTSy6wQ6WZU' \
--data-raw '{
    "request": {
        "sbIdentifiers": ["fca2925f-1eee-4654-9177-fece3fd6afc9","8454cb21-3ce9-4e30-85b5-fade097880d8"]
    }
}'

Discussion Forum: Generalisation of Course & Groups integration logic

Introduction

Background

Problem Statement

Key design problem:

Solution:

For courses:

Request:

Response:

For groups:

Create Form:

Endpoint:

Request Body:

Fetching the form data:

Request:

Response:

Fetch the attached category id for a particular sbType:

Create forum:

Generalization api for Update(If there is any mistakes)

Mandatory Parameters

Update Category Details

Required Parameters

Update Group privileges For a category

Required Parameters

List of privileges

Get groups List

Add User into group

Required Parameters

Getting Nodebb UID's By sending Sunbird Identifiers