{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"style":{"value":"none"}},"macroMetadata":{"macroId":{"value":"d63cdd6e-6f40-4a3b-8b8e-beaf8fb43e39"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"96c4411c-2a68-4df8-9899-e00633f003e5"}},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"The new user management UI enables you to assign users to groups. But creating new groups is currently not available via UI. So this is a guide which leads you through the calls needed for it.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Preferences","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Token of a user / service-user which has admin role (chat.admin.all) assigned → ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The base URL of your application → ","type":"text"}]}]}]},{"type":"panel","attrs":{"panelIconId":"2139","panelIcon":":information_source:","panelIconText":"ℹ️","panelColor":"#E6FCFF","panelType":"custom"},"content":[{"type":"paragraph","content":[{"text":"Check here how to get a token: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://unique-ch.atlassian.net/wiki/spaces/PUB/pages/577929672"}},{"text":" ","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Fetching groups","type":"text"}]},{"type":"paragraph","content":[{"text":"With the following cURL you can fetch all available groups of the organisation the user/service-user belongs to. Just replace the following placeholders: / ","type":"text"}]},{"type":"paragraph","content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"excerpt-include","parameters":{"macroParams":{"":{"value":"APIs & Integrations"},"name":{"value":"internal-api-warning"},"nopanel":{"value":"true"}},"macroMetadata":{"macroId":{"value":"f6f2c161-7158-4407-a111-1dbc858f1c1e"},"schemaVersion":{"value":"1"},"title":"Insert excerpt"}},"localId":"93290b84-0185-41d8-aa93-ab601bfbd262"}}]},{"type":"codeBlock","content":[{"text":"curl --location 'https://gateway./scope-management/graphql' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer ' \\\n--data '{\"query\":\"query AllGroups {\\n allGroups {\\n id\\n name\\n parentId\\n createdAt\\n updatedAt\\n }\\n}\",\"variables\":{}}'","type":"text"}]},{"type":"paragraph","content":[{"text":"This should give you the following result:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"data\": {\n \"allGroups\": [\n {\n \"id\": \"group_123456789032eqd21xocgdfw\",\n \"name\": \"Root Group\",\n \"parentId\": null,\n \"createdAt\": \"2021-05-17T10:35:30.212Z\",\n \"updatedAt\": \"2021-09-23T09:36:11.846Z\"\n },\n {\n \"id\": \"group_0987654321jviq7tiure95uh\",\n \"name\": \"GPT-4 Group\",\n \"parentId\": \"group_123456789032eqd21xocgdfw\",\n \"createdAt\": \"2021-05-20T08:54:10.839Z\",\n \"updatedAt\": \"2021-05-20T08:54:10.839Z\"\n },\n ...\n ]\n }\n}","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"As you can see the groups can be hierarchical. This is something to keep in mind when creating new groups. ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Creating a group","type":"text"}]},{"type":"paragraph","content":[{"text":"Before creating a group you need to know how you want to organise your organisation/company. As default there is a ","type":"text"},{"text":"Root Group","type":"text","marks":[{"type":"code"}]},{"text":" created where all users (also new ones) get assigned on signup. Groups can be hierarchical. Imagine a setup where you have the ","type":"text"},{"text":"Root Group","type":"text","marks":[{"type":"code"}]},{"text":" and create a new group with ","type":"text"},{"text":"IT","type":"text","marks":[{"type":"code"}]},{"text":" and the parent is the ","type":"text"},{"text":"Root Group","type":"text","marks":[{"type":"code"}]},{"text":" and another group called ","type":"text"},{"text":"Development","type":"text","marks":[{"type":"code"}]},{"text":" with the parent ","type":"text"},{"text":"IT","type":"text","marks":[{"type":"code"}]},{"text":". People added as member to the group ","type":"text"},{"text":"Development","type":"text","marks":[{"type":"code"}]},{"text":" will automatically also gain access to the scopes/spaces of this group itself and all parent groups. With this setup you are able to replicate the organisation chart of your company and manage access. Its also possible to have a flat hierarchy of groups with multiple “root groups” and no parents or children. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Now lets create a group. This can be done with this cURL. Just replace the following placeholders: / / / ","type":"text"}]},{"type":"paragraph","content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"excerpt-include","parameters":{"macroParams":{"":{"value":"APIs & Integrations"},"name":{"value":"internal-api-warning"},"nopanel":{"value":"true"}},"macroMetadata":{"macroId":{"value":"67557cc7-3034-4344-b161-c6a73c9d201f"},"schemaVersion":{"value":"1"},"title":"Insert excerpt"}},"localId":"86cd4bb3-f0db-420a-96e2-5123789c95dc"}}]},{"type":"codeBlock","content":[{"text":"curl --location 'https://gateway./scope-management/graphql' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer ' \\\n--data '{\"query\":\"mutation CreateGroup($input: GroupCreateInput!) {\\n createGroup(input: $input) {\\n id\\n name\\n parentId\\n }\\n}\",\"variables\":{\"input\":{\"name\":\"\",\"parent\":{\"connect\":{\"id\":\"\"}}}}}'","type":"text"}]},{"type":"paragraph","content":[{"text":"If you want to make the flat hierarchy (multiple “root groups”) then you can leave out the part with the parent. Doing it like this:","type":"text"}]},{"type":"codeBlock","content":[{"text":"curl --location 'https://gateway./scope-management/graphql' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer ' \\\n--data '{\"query\":\"mutation CreateGroup($input: GroupCreateInput!) {\\n createGroup(input: $input) {\\n id\\n name\\n parentId\\n }\\n}\",\"variables\":{\"input\":{\"name\":\"\"}}}'","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"},{"text":"This should respond with the following successful response with your replaced , a new unique and if you did it hierarchical the otherwise ","type":"text"},{"text":"null","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"data\": {\n \"createGroup\": {\n \"id\": \"\",\n \"name\": \"\",\n \"parentId\": \"\" or null\n }\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Now this group is visible in the UI and users with the user management permission are able to assign and remove users from this new group. ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Updating Groups","type":"text"}]},{"type":"paragraph","content":[{"text":"In case you did a typo or a name of a group changed you can update an existing group with the following cURL. Just replace the following placeholders: / / (ID of the group you want to change) / (new name you want to set)","type":"text"}]},{"type":"paragraph","content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"excerpt-include","parameters":{"macroParams":{"":{"value":"APIs & Integrations"},"name":{"value":"internal-api-warning"},"nopanel":{"value":"true"}},"macroMetadata":{"macroId":{"value":"f0345bd8-3afb-4e64-be03-5441d01e8ab9"},"schemaVersion":{"value":"1"},"title":"Insert excerpt"}},"localId":"da7df058-0c7f-4e9f-83d6-4517f9a95759"}}]},{"type":"codeBlock","content":[{"text":"curl --location 'https://gateway./scope-management/graphql' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer ' \\\n--data '{\"query\":\"mutation UpdateGroup($updateGroupId: String!, $input: GroupUpdateInput!) {\\n updateGroup(id: $updateGroupId, input: $input) {\\n id\\n }\\n}\",\"variables\":{\"updateGroupId\":\"\",\"input\":{\"name\":\"\"}}}'","type":"text"}]},{"type":"paragraph","content":[{"text":"This should give you the following result:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"data\": {\n \"updateGroup\": {\n \"id\": \"\",\n \"name\": \"\"\n }\n }\n}","type":"text"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Updating Metadata","type":"text"}]},{"type":"paragraph","content":[{"text":"The same cURL command can be used to add/update metadata to a group. The metadata can be passed within the parameter named ","type":"text"},{"text":"configuration","type":"text","marks":[{"type":"code"}]},{"text":"in the input object. ","type":"text"},{"type":"hardBreak"},{"type":"hardBreak"},{"text":"Below you can see an example where the metadata with key ","type":"text"},{"text":"location","type":"text","marks":[{"type":"code"}]},{"text":" with a value ","type":"text"},{"text":"switzerland","type":"text","marks":[{"type":"code"}]},{"text":" is added to the group specified with ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text"}]},{"type":"codeBlock","content":[{"text":"curl --location 'https://gateway./scope-management/graphql' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer ' \\\n--data '{\"query\":\"mutation UpdateGroup($updateGroupId: String!, $input: GroupUpdateInput!) {\\n updateGroup(id: $updateGroupId, input: $input) {\\n id\\n }\\n}\",\"variables\":{\"updateGroupId\":\"\",\"input\":{\"configuration\": {\"location\": \"switzerland\"}}}}'","type":"text"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Deleting Groups","type":"text"}]},{"type":"paragraph","content":[{"text":"A group can be delted as follows, make sure the groups do not have members anymore. ","type":"text"}]},{"type":"codeBlock","content":[{"text":"curl --request POST \\\n --header 'content-type: application/json' \\\n --header 'Authorization: Bearer ' \\\n --url https://gateway./scope-management/graphql \\\n --data '{\"query\":\"mutation DeleteGroup($deleteGroupId: String!) {\\n deleteGroup(id: $deleteGroupId) {\\n id\\n }\\n}\",\"variables\":{\"deleteGroupId\":\"group_....\"}}'","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Conclusion","type":"text"}]},{"type":"paragraph","content":[{"text":"Now you should be able to fetch, create and update groups via the API. ","type":"text"},{"type":"hardBreak"}]},{"type":"rule"},{"type":"table","attrs":{"layout":"default","width":633.0,"localId":"9bb6a5c3-0d07-4a37-a162-cc4510dd04df"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[110.0]},"content":[{"type":"paragraph","content":[{"text":"Author","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[523.0]},"content":[{"type":"paragraph","content":[{"type":"mention","attrs":{"id":"63eb588dc5061c632c0caec1","text":"@Adrian Gugger"}},{"text":" ","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":" ","type":"text"}]}],"version":1}

Browser not supported