Merge pull request #600 from xbolshe/pr2

Add channels.setCustomFields and groups.setCustomFields. Fix purpose.
RocketChat · May 28, 2018 · 47d2c13 · 47d2c13
2 parents c327582 + a8a3a53
commit 47d2c13
Show file tree

Hide file tree

Showing 10 changed files with 182 additions and 35 deletions.
diff --git a/_data/toc.yml b/_data/toc.yml
@@ -237,6 +237,7 @@
         - removeModerator
         - removeOwner
         - rename
+        - setCustomFields
         - setDescription
         - setJoinCode
         - setPurpose
@@ -283,6 +284,7 @@
         - removeModerator
         - removeOwner
         - rename
+        - setCustomFields
         - setDescription
         - setPurpose
         - setReadOnly

diff --git a/contributing/documentation/documentation-map/README.md b/contributing/documentation/documentation-map/README.md
@@ -278,6 +278,7 @@ Here you can also find what articles are incomplete and missing.
             - removeModerator
             - removeOwner
             - rename
+            - setCustomFields
             - setDescription
             - setJoinCode
             - setPurpose
@@ -326,6 +327,7 @@ Here you can also find what articles are incomplete and missing.
             - removeModerator
             - removeOwner
             - rename
+            - setCustomFields
             - setDescription
             - setPurpose
             - setReadOnly

diff --git a/developer-guides/rest-api/README.md b/developer-guides/rest-api/README.md
@@ -79,6 +79,7 @@ When calling a production Rocket.Chat server, ensure it is running via HTTPS and
 | `/api/v1/channels.list`                       | Retrieves all of the channels from the server.              | [Link](channels/list/)                          |
 | `/api/v1/channels.open`                       | Adds the channel back to the user's list of channels.       | [Link](channels/open/)                          |
 | `/api/v1/channels.rename`                     | Changes a channel's name.                                   | [Link](channels/rename/)                        |
+| `/api/v1/channels.setCustomFields`            | Sets a channel's custom fields.                             | [Link](channels/setcustomfields/)               |
 | `/api/v1/channels.setAnnouncement`            | Sets a channel's announcement.                              | [Link](channels/setannouncement/)               |
 | `/api/v1/channels.setDescription`             | Sets a channel's description.                               | [Link](channels/setdescription/)                |
 | `/api/v1/channels.setJoinCode`                | Sets the channel's code required to join it.                | [Link](channels/setjoincode/)                   |
@@ -106,6 +107,7 @@ When calling a production Rocket.Chat server, ensure it is running via HTTPS and
 | `/api/v1/groups.listAll`        | List all the private groups.                       | [Link](groups/listall/)        |
 | `/api/v1/groups.open`           | Adds the private group back to the list of groups. | [Link](groups/open/)           |
 | `/api/v1/groups.rename`         | Changes the name of the private group.             | [Link](groups/rename/)         |
+| `/api/v1/groups.setCustomFields | Sets private group's custom fields.                | [Link](groups/setcustomfields/)|
 | `/api/v1/groups.setDescription` | Sets a private group's description.                | [Link](groups/setdescription/) |
 | `/api/v1/groups.setPurpose`     | Sets a private group's description.                | [Link](groups/setpurpose/)     |
 | `/api/v1/groups.setReadOnly`    | Sets whether the room is read only or not.         | [Link](groups/setreadonly/)    |

diff --git a/developer-guides/rest-api/channels/README.md b/developer-guides/rest-api/channels/README.md
@@ -23,6 +23,7 @@
 | `/api/v1/channels.removeModerator` | Removes the role of moderator from a user in a channel. | [Link](removemoderator/) |
 | `/api/v1/channels.removeOwner` | Removes the role of owner from a user in a channel. | [Link](removeowner/) |
 | `/api/v1/channels.rename` | Changes a channel's name. | [Link](rename/) |
+| `/api/v1/channels.setCustomFields` | Sets a channel's custom fields. | [Link](setcustomfields/) |
 | `/api/v1/channels.setDescription` | Sets a channel's description. | [Link](setdescription/) |
 | `/api/v1/channels.setJoinCode` | Sets the channel's code required to join it. | [Link](setjoincode/) |
 | `/api/v1/channels.setPurpose` | Sets a channel's description. | [Link](setpurpose/) |

diff --git a/developer-guides/rest-api/channels/setcustomfields/README.md b/developer-guides/rest-api/channels/setcustomfields/README.md
@@ -0,0 +1,55 @@
+# Channel Set Custom Fields
+
+Sets the custom fields for the channel.
+
+| URL | Requires Auth | HTTP Method |
+| :--- | :--- | :--- |
+| `/api/v1/channels.setCustomFields` | `yes` | `POST` |
+
+## Payload
+
+One of roomId or roomName is required.
+
+| Argument | Example | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `roomId` | `GENERAL` | Required | The channel's id |
+| `roomName` | `general` | Required | The channel's name |
+| `customFields` | `{"organization": "tra-la-la"}` | Required | The custom fields to set for the channel. |
+
+## Example Call
+
+```bash
+curl -H "X-Auth-Token: 8h2mKAwxB3AQrFSjLVKMooJyjdCFaA7W45sWlHP8IzO" \
+     -H "X-User-Id: ew28FnZqipDpvKw3R" \
+     -H "Content-type: application/json" \
+     http://localhost:3000/api/v1/channels.setCustomFields \
+     -d '{"roomId": "GENERAL", "customFields":{"organization": "tra-la-la"} }'
+```
+
+## Example Result
+
+```json
+{
+  "channel":{
+    "_id":"GENERAL",
+    "ts":"2018-02-18T19:41:02.875Z",
+    "t":"c",
+    "name":"general",
+    "msgs":236,
+    "default":true,
+    "_updatedAt":"2018-02-23T11:09:05.973Z",
+    "lm":"2018-02-18T22:18:20.288Z",
+    "customFields":{
+      "organization":"tra-la-la"
+    }
+  },
+  "success":true,
+  "developerWarning":"[WARNING]: The \"usernames\" field has been removed for performance reasons. Please use the \"*.members\" endpoint to get a list of members/users in a room."
+}
+```
+
+## Change Log
+
+| Version | Description |
+| :--- | :--- |
+| 0.62.0 | Added |
diff --git a/developer-guides/rest-api/channels/setpurpose/README.md b/developer-guides/rest-api/channels/setpurpose/README.md
@@ -1,6 +1,6 @@
 # Channel Set Purpose
 
-Sets the description for the channel.
+Sets the description for the channel (the same as channels.setDescription, obsolete).
 
 | URL | Requires Auth | HTTP Method |
 | :--- | :--- | :--- |

diff --git a/developer-guides/rest-api/groups/README.md b/developer-guides/rest-api/groups/README.md
@@ -22,6 +22,7 @@
 | `/api/v1/groups.removeModerator` | Removes the role of moderator from a user in a group. | [Link](removemoderator/) |
 | `/api/v1/groups.removeOwner` | Removes the role of owner from a user in a group. | [Link](removeowner/) |
 | `/api/v1/groups.rename` | Changes the name of the private group. | [Link](rename/) |
+| `/api/v1/groups.setCustomFields` | Sets private group's custom fields. | [Link](setcustomfields/) |
 | `/api/v1/groups.setDescription` | Sets a private group's description. | [Link](setdescription/) |
 | `/api/v1/groups.setPurpose` | Sets a private group's description. | [Link](setpurpose/) |
 | `/api/v1/groups.setReadOnly` | Sets whether the room is read only or not. | [Link](setreadonly/) |

diff --git a/developer-guides/rest-api/groups/setcustomfields/README.md b/developer-guides/rest-api/groups/setcustomfields/README.md
@@ -0,0 +1,61 @@
+# Group Set Custom Fields
+
+Sets the custom fields for the private group.
+
+| URL | Requires Auth | HTTP Method |
+| :--- | :--- | :--- |
+| `/api/v1/groups.setCustomFields` | `yes` | `POST` |
+
+## Payload
+
+One of roomId or roomName is required.
+
+| Argument | Example | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `roomId` | `euzoT67Gx6nXcn66M` | Required | The private group's id |
+| `roomName` | `channel.cf.1518990680083` | Required | The private group's name |
+| `customFields` | `{"company": "sell-and-more"}` | Required | The custom fields to set for the private group. |
+
+## Example Call
+
+```bash
+curl -H "X-Auth-Token: 8h2mKAwxB3AQrFSjLVKMooJyjdCFaA7W45sWlHP8IzO" \
+     -H "X-User-Id: ew28FnZqipDpvKw3R" \
+     -H "Content-type: application/json" \
+     http://localhost:3000/api/v1/groups.setCustomFields \
+     -d '{"roomId": "euzoT67Gx6nXcn66M", "customFields":{"company": "sell-and-more"} }'
+```
+
+## Example Result
+
+```json
+{
+  "group":{
+    "_id":"euzoT67Gx6nXcn66M",
+    "name":"channel.cf.1518990680083",
+    "fname":"channel.cf.1518990680083",
+    "t":"p",
+    "msgs":0,
+    "u":{
+      "_id":"ew28FnZqipDpvKw3R",
+      "username":"rocketchat.internal.admin.test"
+    },
+    "customFields":{
+      "company":"sell-and-more"
+    },
+    "ts":"2018-02-18T21:51:20.091Z",
+    "ro":false,
+    "sysMes":true,
+    "_updatedAt":"2018-02-23T11:27:01.411Z",
+    "username":"rocketchat.internal.admin.test"
+  },
+  "success":true,
+  "developerWarning":"[WARNING]: The \"usernames\" field has been removed for performance reasons. Please use the \"*.members\" endpoint to get a list of members/users in a room."
+}
+```
+
+## Change Log
+
+| Version | Description |
+| :--- | :--- |
+| 0.62.0 | Added |
diff --git a/developer-guides/rest-api/groups/setpurpose/README.md b/developer-guides/rest-api/groups/setpurpose/README.md
@@ -1,6 +1,6 @@
 # Group Set Purpose
 
-Sets the description for the private group.
+Sets the description for the private group (the same as groups.setDescription, obsolete).
 
 | URL | Requires Auth | HTTP Method |
 | :--- | :--- | :--- |

diff --git a/developer-guides/schema-definition/README.md b/developer-guides/schema-definition/README.md
@@ -20,27 +20,36 @@
   "u": {                                   // Object           Owner User
     "_id": "CABrXSHpDqbZXGkYR",            // Random.id()      User Id
     "username": "john"                     // String           User Username
+  },
+  "customFields": {                        // Object           User defined custom fields (for t:c and t:p only)
+     "userDefinedField": "userValue",      //                  User defined field example
+     "userDefinedField2": true,            //                  User defined field example
+     "userObject3": {                      //                  User defined field example
+        "a": "hello",
+        "b": "lalala"
+     }
   }
 }
 ```
 
 ### Fields
 
-| Fields      | Type          | Description              |
-| :---------- | :------------ | :----------------------- |
-| \_id        | Random.id()   | Room Id                  |
-| t           | String        | Room Type                |
-| ts          | Date          | Room Creation Timestamp  |
-| name        | String        | Room Name (t:d -> empty) |
-| lm          | Date          | Last Message Timestamp   |
-| msgs        | Integer       | Messages Counter         |
-| cl          | Boolean       | If users can leave room  |
-| ro          | Boolean       | Read Only                |
-| usernames   | Array[String] | Room Users               |
-| usernames.0 | String        | User Username            |
-| u           | Object        | Owner User               |
-| u.\_id      | Random.id()   | User Id                  |
-| u.username  | String        | User Username            |
+| Fields       | Type          | Description                               |
+| :----------- | :------------ | :---------------------------------------- |
+| \_id         | Random.id()   | Room Id                                   |
+| t            | String        | Room Type                                 |
+| ts           | Date          | Room Creation Timestamp                   |
+| name         | String        | Room Name (t:d -> empty)                  |
+| lm           | Date          | Last Message Timestamp                    |
+| msgs         | Integer       | Messages Counter                          |
+| cl           | Boolean       | If users can leave room                   |
+| ro           | Boolean       | Read Only                                 |
+| usernames    | Array[String] | Room Users                                |
+| usernames.0  | String        | User Username                             |
+| u            | Object        | Owner User                                |
+| u.\_id       | Random.id()   | User Id                                   |
+| u.username   | String        | User Username                             |
+| customFields | Object        | User custom fields (for t:c and t:p only) |
 
 ### Indexes
 
@@ -70,30 +79,44 @@
   "v": {                                   // Object           Visitor
     "_id": "CABrXSHpDqbZXGkYR",            // Random.id()      Visitor Id
     "username": "anonymous"                // String           Visitor Username
+  },
+  "customFields": {                        // Object           User defined custom fields
+     "userDefinedField": "userValue",      //                  User defined field example
+     "userDefinedField2": true,            //                  User defined field example
+     "userObject3": {                      //                  User defined field example
+        "a": "hello",
+        "b": "lalala"
+     }
   }
 }
 ```
 
 ### Fields
 
-| Fields     | Type        | Description                                                      |
-| :--------- | :---------- | :--------------------------------------------------------------- |
-| \_id       | Random.id() | Subscriptions Id                                                 |
-| t          | String      | Subscription Type (copy from Room)                               |
-| ts         | Date        | Subscription Creation Timestamp                                  |
-| ls         | Date        | Last Seen Timestamp                                              |
-| name       | String      | Subscription Name (t:d -> target username)                       |
-| rid        | Random.id() | Room Id                                                          |
-| f          | Boolean     | Favorited                                                        |
-| open       | Boolean     | Is Room Opened                                                   |
-| alert      | Boolean     | Room has unread messages for this user                           |
-| unread     | Integer     | Counter of unread messages with mentions or from direct messages |
-| u          | Object      | User                                                             |
-| u.\_id     | Random.id() | User Id                                                          |
-| u.username | String      | User Username                                                    |
-| v          | Object      | Visitor                                                          |
-| v.\_id     | Random.id() | Visitor Id                                                       |
-| v.username | String      | Visitor Username                                                 |
+| Fields       | Type        | Description                                                      |
+| :----------- | :---------- | :--------------------------------------------------------------- |
+| \_id         | Random.id() | Subscriptions Id                                                 |
+| t            | String      | Subscription Type (copy from Room)                               |
+| ts           | Date        | Subscription Creation Timestamp                                  |
+| ls           | Date        | Last Seen Timestamp                                              |
+| name         | String      | Subscription Name (t:d -> target username)                       |
+| rid          | Random.id() | Room Id                                                          |
+| f            | Boolean     | Favorited                                                        |
+| open         | Boolean     | Is Room Opened                                                   |
+| alert        | Boolean     | Room has unread messages for this user                           |
+| unread       | Integer     | Counter of unread messages with mentions or from direct messages |
+| u            | Object      | User                                                             |
+| u.\_id       | Random.id() | User Id                                                          |
+| u.username   | String      | User Username                                                    |
+| v            | Object      | Visitor                                                          |
+| v.\_id       | Random.id() | Visitor Id                                                       |
+| v.username   | String      | Visitor Username                                                 |
+| customFields | Object      | User custom fields                                               |
+
+Notes about customFields:
+
+- customFields inherits from room's customFields for channels (Room Type: c = chanel) and groups (Room Type: p = group) and changes with room's customFields
+- customFields inherits from user's customFields for Direct Messages (Room Type: d = direct) and changes with user's customFields. Note that users of Direct Messages room will have own customFields.
 
 ### Indexes