Groups API

This API is available from version 9.0 or above of PowerFolder server.

 

Using the Groups API you can create, modify and delete groups.

Please read the main article about the API to understand how it works.

Using the Groups API

The service is available at the URI: /api/groups

Example

https://powerfolder.example.com/api/groups

Overview

 

Actions supported by the Groups API

Action: getInfo

This action returns the basic information about a group. Existing groups will be looked up by ID first and then by name.

ParameterRequiredDescriptionExample
actionYesMust always be getInfo.getInfo
nameYes, if ID is missingThe name of the group.Research
IDYes, if name is missingThe universal unique ID of the group.
0B5DA216628547228F23187C17AD5407


Example

https://powerfolder.example.com/api/groups?action=getInfo&name=Research

 

Return value
{
  "ID":"0B5DA216628547228F23187C17AD5407",
  "name":"Research",
  "notes":"Notes can be very helpful",
  "nAccounts":2,
  "nFolder":1,
  "organizationID":"0B5DA216628547228F23187C17AD5407"
}
Result KeyDescriptionExample
IDGroup ID
0B5DA216628547228F23187C17AD5407
nameGroup nameResearch
notesCustom text notes

Notes can be very helpful

nAccountsNumber of accounts that are member of the group17
nFolderNumber of folder that belong to the group

5

organizationIDThe id of the organization the group is in
0Z5DA289628547228F23187C17CE5899

 

Action: getAccounts

Get a full list of all accounts that are member of the group.

ParameterRequiredDescriptionExample
actionYesMust always be getAccounts.getAccounts
nameYes, if ID is missingThe name of the groupResearch
IDYes, if name is missingThe universal unique ID of the group.
0B5DA216628547228F23187C17AD5407

 

Example

http://powerfolder.example.com/api/groups?action=getAccounts&name=Research

 

Return value
{
  "ResultSet":{
    "Result":[
      {
        "username":"employee1@example.com",
        "ID":"Fs9ojjjRJjUorufY8kpS",
		"organizationID":"GhbNBZkfUHbTbCo73VbN"
      },
      {
        "username":"employee2@example.com",
        "ID":"BtzEN9DCM7higRZkdgTW",
		"organizationID":"GhbNBZkfUHbTbCo73VbN"
      }
    ]
  }
}

Action: getFolders

Get a full list of all folders that belong to the group and the permissions granted to the members of the group.

ParameterMandatoryDescriptionExample
actionYesMust always be getFolders.getFolders
nameYes, if ID is missingThe name of the groupResearch
IDYes, if name is missingThe universal unique ID of the group.
0B5DA216628547228F23187C17AD5407


Example

http://powerfolder.example.com/api/groups?action=getFolders&name=Research


Return value
{
  "ResultSet":{
    "Result":[
      {
        "folderName":"Documents",
        "folderID":"[BiLhdsJFyyxJZ9FKg55J]",
        "permission":"READ_WRITE"
      },
      {
        "folderName":"Deployment",
        "folderID":"[i1hyN6hB8jz8t6WxisD]",
        "permission":"READ"
      }
    ]
  }
}

Action: store

This action creates or modifies a group. If the group does not exist yet, it will be created. If an existing group is found, it will be updated. Existing groups will be searched by ID first and then by name.

ParameterRequiredDescriptionExample
actionYesMust always be storestore
nameYesThe name of the groupDevelopment
newObjectNoMust be "true" for a new grouptrue
IDNoThe universal unique ID of the group. Will be used to find/create the group. Can be any external ID if unique.1DCB5E177F3A4ACA8C7E0842159E56D5
notesNoCustom text notesR&D without the R
organizationIDNoThe Organization ID of the Group1DCB5E177F3A4ACA8C7E0842159E56D5


Example

http://powerfolder.example.com/api/groups?action=store&ID=123&name=Development&notes=R%26D%20without%20the%20R&newObject=true


Return value
{
  "ID":"123",
  "name":"Development",
  "notes":"R&D without the R",
  "nAccounts":0,
  "nFolder":0,
  "organizationID":"3pZKEgh2UFsWwDSgGxTZ"
}

Action: addUser

Add a user to an existing group.

ParameterRequiredDescriptionExample
actionYesMust always be addUseraddUser
nameYes, if ID is missingThe name of the groupResearch
IDYes, if name is missingThe universal unique ID of the group1DCB5E177F3A4ACA8C7E0842159E56D5
accountIDYesUser account IDC13s8qtAW8StkVvbEVtf
accountNameYesUser account nameemployee2@example.com
createAccountNoCreate the user if not existingtrue


Example

http://powerfolder.example.com/api/groups?action=addUser&name=Research&accountID=C13s8qtAW8StkVvbEVtf&accountName=employee2@example.com&createAccount=true


Return value
{
	"ID" : "C13s8qtAW8StkVvbEVtf",
	"username" : "employee2@example.com",
	"message" : "Added user 'employee2@example.com' to group 'Research'"
}

Action: removeUser

This action will remove a user out of a group.

ParameterRequiredDescriptionExample
actionYesMust always be removeUserremoveUser
IDYes, if name is missingThe universal unique ID of the group.
0B5DA216628547228F23187C17AD5407
nameYes, if ID is missingThe name of the group.MyGroup
userIDYes, if username is missingThe ID of a user
0C5DF216629747228F23157C17FA5488
usernameYes, if userID is missingThe name of a userthomas@example.com


Example

https://powerfolder.example.com/api/groups?action=removeUser&name=mygroup&userid=0B5DA216628547228F23187C17AD5407

 

Return value
{
	"ID" : "0C5DF216629747228F23157C17FA5488",
	"username" : "thomas@example.com",
	"message" : "Removed user 'thomas@example.com' from group 'MyGroup'"
}

Action: delete

This action deletes a group and all referenzes to it.

ParameterRequiredDescriptionExample
actionYesMust always be deletedelete
nameNoThe name of the groupResearch
IDYesThe ID of an existing group

1DCB5E177F3A4ACA8C7E0842159E56D5


Example

http://powerfolder.example.com/api/groups?action=delete&ID=1DCB5E177F3A4ACA8C7E0842159E56D5


Return value
{
  "ID":"1DCB5E177F3A4ACA8C7E0842159E56D5",
  "message":"Successfully deleted group Research. Removed 15 Accunts and 4 Folders."
}

Action: addFolder

This action will grant a group specified folder permissions.

ParameterRequiredDescriptionExample
actionYesMust always be addFolderaddFolder
IDYes, if name is missingThe universal unique ID of the group.
9QusRjrxuTxqrLyjPjTz
nameYes, if ID is missingThe name of the groupMyGroup
folderIDYesThe ID of the folder
246jRkZiDdgpFXaqe9rJ6
permissionYesThe Permission the group will be grantedREAD_WRITE


Example

https://powerfolder.example.com/api/groups?groups?action=addFolder&ID=9QusRjrxuTxqrLyjPjTz&folderID=246jRkZiDdgpFXaqe9rJ6&permission=READ_WRITE

 

Return value
{
	"ID" : "9QusRjrxuTxqrLyjPjTz",
	"name" : "MyGroup",
	"message" : "Added Folder 'Documents' to group 'MyGroup'"
}

Action: removeFolder

This action will revoke specified folder permissions from a group.

ParameterRequiredDescriptionExample
actionYesMust always be removeUserremoveFolder
FolderIDYesThe ID of the folder
0C5DF216629747228F23157C17FA5488
nameYes, if ID is missingThe name of the groupMyGroup
IDYes, if name is missingThe universal unique ID of the group.
0B5DA216628547228F23187C17AD5407
PermissionYesThe Permission the group will be revokedFolderReadWritePermission


Example

https://powerfolder.example.com/api/groups?action=removeFolder&name=mygroup&folderid=0C5DF216629747228F23157C17FA5488&permission=FolderReadWritePermission

 

Return value
{
	"ID" : "0B5DA216628547228F23187C17AD5407",
	"name" : "MyGroup",
	"message" : "Removed Folder 'Documents' from group 'MyGroup'"
}

Action: saveAccountsToGroup

This action will add multiple accounts with one request to a group.

The length of the accountID and accountName must be equal.

ParameterRequiredDescriptionExample
actionYesMust always be removeUserremoveUser
nameYes, if ID is missingThe name of the groupMyGroup
IDYes, if name is missingThe universal unique ID of the group.
0B5DA216628547228F23187C17AD5407
accountIDYesThe ID's of the accounts that should be added to the groupplease take a look at the example
accountNameYesThe Name's of the accounts that should be added to the groupplease take a look at the example


Example

https://powerfolder.example.com/api/groups?action=saveAccountsToGroup&name=MyGroup&accountID=0C5DF216629747228F23157C17FA5488&accountName=Thomas&accountID=8E5CF216629747228F46157A17FA7845&accountName=Peter

Action: saveFoldersToGroup

This action will add multiple folders with one request to a group.

The length of the folderID and folderName must be equal.

ParameterRequiredDescriptionExample
actionYesMust always be removeUserremoveUser
nameYes, if ID is missingThe name of the groupMyGroup
IDYes, if name is missingThe universal unique ID of the group.
0B5DA216628547228F23187C17AD5407
folderIDYesThe ID's of the accounts that should be added to the group0C5DF216629747228F23157C17FA5488
folderNameYesThe Name's of the accounts that should be added to the groupMyFolder
permissionYesThe Permission that will be added to the group for the specified folderREAD


Example

https://powerfolder.example.com/api/groups?action=saveFoldersToGroup&name=MyGroup&folderID=0C5DF216629747228F23157C17FA5488&folderName=MyFolder&permission=READ_WRITE&folderID=8E5CF216629747228F46157A17FA7845&folderName=MyOtherFolder&permission=READ