alfresco-ng2-components/lib/js-api/src/api/content-rest-api/docs/GroupsApi.md

GroupsApi

All URIs are relative to https://localhost/alfresco/api/-default-/public/alfresco/versions/1

Method	HTTP request	Description
createGroup	POST /groups	Create a group
createGroupMembership	POST /groups/{groupId}/members	Create a group membership
deleteGroup	DELETE /groups/{groupId}	Delete a group
deleteGroupMembership	DELETE /groups/{groupId}/members/{groupMemberId}	Delete a group membership
getGroup	GET /groups/{groupId}	Get group details
listGroupMemberships	GET /groups/{groupId}/members	List memberships of a group
listGroupMembershipsForPerson	GET /people/{personId}/groups	List group memberships
listGroups	GET /groups	List groups
updateGroup	PUT /groups/{groupId}	Update group details

createGroup

Create a group

this endpoint is available in Alfresco 5.2.1 and newer versions. You must have admin rights to create a group.

Create a group.

The group id must start with "GROUP\". If this is omitted it will be added automatically. This format is also returned when listing groups or group memberships. It should be noted that the other group-related operations also expect the id to start with "GROUP\".

If one or more parentIds are specified then the group will be created and become a member of each of the specified parent groups.

If no parentIds are specified then the group will be created as a root group.

The group will be created in the APP.DEFAULT and AUTH.ALF zones.

Parameters

Name	Type	Description
groupBodyCreate	GroupBodyCreate	The group to create.
opts.include	string[]	Returns additional information about the group. The following optional fields can be requested: parentIds, zones
opts.fields	string[]	A list of field names. You can use this parameter to restrict the fields returned within a response if, for example, you want to save on overall bandwidth. The list applies to a returned individual entity or entries within a collection. If the API method also supports the include parameter, then the fields specified in the include parameter are returned in addition to those specified in the fields parameter.

Return type: GroupEntry

Example

import { AlfrescoApi, GroupsApi } from '@alfresco/js-api';

const alfrescoApi = new AlfrescoApi(/*..*/);
const groupsApi = new GroupsApi(alfrescoApi);

const payload = {};
const opts = {};

groupsApi.createGroup(payload, opts).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
});

createGroupMembership

Create a group membership

this endpoint is available in Alfresco 5.2.1 and newer versions. You must have admin rights to create a group membership.

Create a group membership (for an existing person or group) within a group groupId. If the added group was previously a root group then it becomes a non-root group since it now has a parent.

It is an error to specify an id that does not exist.

Parameters

Name	Type	Description
groupId	string	The identifier of a group.
groupMembershipBodyCreate	GroupMembershipBodyCreate	The group membership to add (person or sub-group).
opts.fields	string[]	A list of field names. You can use this parameter to restrict the fields returned within a response if, for example, you want to save on overall bandwidth. The list applies to a returned individual entity or entries within a collection. If the API method also supports the include parameter, then the fields specified in the include parameter are returned in addition to those specified in the fields parameter.

Return type: GroupMemberEntry

Example

import { AlfrescoApi, GroupsApi } from '@alfresco/js-api';

const alfrescoApi = new AlfrescoApi(/*..*/);
const groupsApi = new GroupsApi(alfrescoApi);

const groupMembershipBodyCreate = {};
const opts = {};

groupsApi.createGroupMembership(`<groupId>`, groupMembershipBodyCreate, opts).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
});

deleteGroup

Delete a group

this endpoint is available in Alfresco 5.2.1 and newer versions. You must have admin rights to delete a group.

The option to cascade delete applies this recursively to any hierarchy of group members. In this case, removing a group member does not delete the person or subgroup itself. If a removed subgroup no longer has any parent groups then it becomes a root group.

Parameters

Name	Type	Description	Notes
groupId	string	The identifier of a group.
opts.cascade	boolean	If true then the delete will be applied in cascade to sub-groups.	default to false

Example

import { AlfrescoApi, GroupsApi} from '@alfresco/js-api';

const alfrescoApi = new AlfrescoApi(/*..*/);
const groupsApi = new GroupsApi(alfrescoApi);

const opts = { 
  cascade: true
};

groupsApi.deleteGroup(`<groupId>`, opts).then(() => {
  console.log('API called successfully.');
});

deleteGroupMembership

Delete a group membership

this endpoint is available in Alfresco 5.2.1 and newer versions. You must have admin rights to delete a group membership.

Delete group member groupMemberId (person or subgroup) from group groupId.

Removing a group member does not delete the person or subgroup itself. If a removed subgroup no longer has any parent groups then it becomes a root group.

Parameters

Name	Type	Description
groupId	string	The identifier of a group.
groupMemberId	string	The identifier of a person or group.

Example

import { AlfrescoApi, GroupsApi } from '@alfresco/js-api';

const alfrescoApi = new AlfrescoApi(/*..*/);
const groupsApi = new GroupsApi(alfrescoApi);

groupsApi.deleteGroupMembership(`<groupId>`, `<groupMemberId>`).then(() => {
  console.log('API called successfully.');
});

getGroup

Get group details

this endpoint is available in Alfresco 5.2.1 and newer versions.

You can use the include parameter to return additional information.

Parameters

Name	Type	Description
groupId	string	The identifier of a group.
opts.include	string[]	Returns additional information about the group. The following optional fields can be requested: parentIds, zones
opts.fields	string[]	A list of field names. You can use this parameter to restrict the fields returned within a response if, for example, you want to save on overall bandwidth. The list applies to a returned individual entity or entries within a collection. If the API method also supports the include parameter, then the fields specified in the include parameter are returned in addition to those specified in the fields parameter.

Return type: GroupEntry

Example

import { AlfrescoApi, GroupsApi } from '@alfresco/js-api';

const alfrescoApi = new AlfrescoApi(/*..*/);
const groupsApi = new GroupsApi(alfrescoApi);

const opts = {};

groupsApi.getGroup(`<groupId>`, opts).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
});

listGroupMemberships

List memberships of a group

this endpoint is available in Alfresco 5.2.1 and newer versions.

Gets a list of the group memberships for the group groupId. You can use the where parameter to filter the returned groups by memberType.

Example to filter by memberType, use any one of:

(memberType='GROUP')
(memberType='PERSON')

The default sort order for the returned list is for group members to be sorted by ascending displayName. You can override the default by using the orderBy parameter. You can specify one of the following fields in the orderBy parameter:

• id
• displayName

Parameters

Name	Type	Description	Notes
groupId	string	The identifier of a group.
opts.skipCount	number	The number of entities that exist in the collection before those included in this list. If not supplied then the default value is 0.	default to 0
opts.maxItems	number	The maximum number of items to return in the list. If not supplied then the default value is 100.	default to 100
opts.orderBy	string[]	A string to control the order of the entities returned in a list. You can use the orderBy parameter to sort the list by one or more fields. Each field has a default sort order, which is normally ascending order. Read the API method implementation notes above to check if any fields used in this method have a descending default search order. To sort the entities in a specific order, you can use the ASC and DESC keywords for any field.
opts.where	string	A string to restrict the returned objects by using a predicate.
opts.fields	string[]	A list of field names. You can use this parameter to restrict the fields returned within a response if, for example, you want to save on overall bandwidth. The list applies to a returned individual entity or entries within a collection. If the API method also supports the include parameter, then the fields specified in the include parameter are returned in addition to those specified in the fields parameter.

Return type: GroupMemberPaging

Example

import { AlfrescoApi, GroupsApi } from '@alfresco/js-api';

const alfrescoApi = new AlfrescoApi(/*..*/);
const groupsApi = new GroupsApi(alfrescoApi);
const opts = { };

groupsApi.listGroupMemberships(`<groupId>`, opts).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
});

listGroupMembershipsForPerson

List group memberships

this endpoint is available in Alfresco 5.2.1 and newer versions.

Gets a list of group membership information for person personId.

You can use the -me- string in place of <personId> to specify the currently authenticated user.

You can use the include parameter to return additional information.

You can use the where parameter to filter the returned groups by isRoot. For example, the following where clause will return just the root groups:

(isRoot=true)

The where parameter can also be used to filter by zone. This may be combined with isRoot to narrow a result set even further. For example, the following where clause will only return groups belonging to the MY.ZONE zone.

where=(zones in ('MY.ZONE'))

This may be combined with the isRoot filter, as shown below:

where=(isRoot=false AND zones in ('MY.ZONE'))

Note: restrictions include

• AND is the only supported operator when combining isRoot and zones filters
• Only one zone is supported by the filter
• The quoted zone name must be placed in parentheses — a 400 error will result if these are omitted.

The default sort order for the returned list is for groups to be sorted by ascending displayName. You can override the default by using the orderBy parameter. You can specify one or more of the following fields in the orderBy parameter:

• id
• displayName

Parameters

Name	Type	Description	Notes
personId	string	The identifier of a person.
opts.skipCount	number	The number of entities that exist in the collection before those included in this list. If not supplied then the default value is 0.	default to 0
opts.maxItems	number	The maximum number of items to return in the list. If not supplied then the default value is 100.	default to 100
opts.orderBy	string[]	A string to control the order of the entities returned in a list. You can use the orderBy parameter to sort the list by one or more fields. Each field has a default sort order, which is normally ascending order. Read the API method implementation notes above to check if any fields used in this method have a descending default search order. To sort the entities in a specific order, you can use the ASC and DESC keywords for any field.
opts.include	string[]	Returns additional information about the group. The following optional fields can be requested: parentIds, zones
opts.where	string	A string to restrict the returned objects by using a predicate.
opts.fields	string[]	A list of field names. You can use this parameter to restrict the fields returned within a response if, for example, you want to save on overall bandwidth. The list applies to a returned individual entity or entries within a collection. If the API method also supports the include parameter, then the fields specified in the include parameter are returned in addition to those specified in the fields parameter.

Return type: GroupPaging

Example

import { AlfrescoApi, GroupsApi } from '@alfresco/js-api';

const alfrescoApi = new AlfrescoApi(/*..*/);
const groupsApi = new GroupsApi(alfrescoApi);
const opts = {};

groupsApi.listGroupMembershipsForPerson(`<personId>`, opts).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
});

listGroups

List groups

this endpoint is available in Alfresco 5.2.1 and newer versions.

Gets a list of groups.

You can use the include parameter to return additional information.

You can use the where parameter to filter the returned groups by isRoot. For example, the following where clause will return just the root groups:

(isRoot=true)

The where parameter can also be used to filter by zone. This may be combined with isRoot to narrow a result set even further. For example, the following where clause will only return groups belonging to the MY.ZONE zone.

where=(zones in ('MY.ZONE'))

This may be combined with the isRoot filter, as shown below:

where=(isRoot=false AND zones in ('MY.ZONE'))

Note: restrictions include

• AND is the only supported operator when combining isRoot and zones filters
• Only one zone is supported by the filter
• The quoted zone name must be placed in parentheses — a 400 error will result if these are omitted.

The default sort order for the returned list is for groups to be sorted by ascending displayName. You can override the default by using the orderBy parameter. You can specify one of the following fields in the orderBy parameter:

• id
• displayName

Parameters

Name	Type	Description	Notes
opts.skipCount	number	The number of entities that exist in the collection before those included in this list. If not supplied then the default value is 0.	default to 0
opts.maxItems	number	The maximum number of items to return in the list. If not supplied then the default value is 100.	default to 100
opts.orderBy	string[]	A string to control the order of the entities returned in a list. You can use the orderBy parameter to sort the list by one or more fields. Each field has a default sort order, which is normally ascending order. Read the API method implementation notes above to check if any fields used in this method have a descending default search order. To sort the entities in a specific order, you can use the ASC and DESC keywords for any field.
opts.include	string[]	Returns additional information about the group. The following optional fields can be requested: parentIds, zones
opts.where	string	A string to restrict the returned objects by using a predicate.
opts.fields	string[]	A list of field names. You can use this parameter to restrict the fields returned within a response if, for example, you want to save on overall bandwidth. The list applies to a returned individual entity or entries within a collection. If the API method also supports the include parameter, then the fields specified in the include parameter are returned in addition to those specified in the fields parameter.

Return type: GroupPaging

Example

import { AlfrescoApi, GroupsApi } from '@alfresco/js-api';

const alfrescoApi = new AlfrescoApi(/*..*/);
const groupsApi = new GroupsApi(alfrescoApi);

const opts = {};

groupsApi.listGroups(opts).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
});

updateGroup

Update group details

this endpoint is available in Alfresco 5.2.1 and newer versions. You must have admin rights to update a group.

Parameters

Name	Type	Description
groupId	string	The identifier of a group.
groupBodyUpdate	GroupBodyUpdate	The group information to update.
opts.include	string[]	Returns additional information about the group. The following optional fields can be requested: parentIds, zones
opts.fields	string[]	A list of field names. You can use this parameter to restrict the fields returned within a response if, for example, you want to save on overall bandwidth. The list applies to a returned individual entity or entries within a collection. If the API method also supports the include parameter, then the fields specified in the include parameter are returned in addition to those specified in the fields parameter.

Return type: GroupEntry

Example

import { AlfrescoApi, GroupsApi } from '@alfresco/js-api';

const alfrescoApi = new AlfrescoApi(/*..*/);
const groupsApi = new GroupsApi(alfrescoApi);
const groupBodyUpdate = {};
const opts = {};

groupsApi.updateGroup(`<groupId>`, groupBodyUpdate, opts).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
});

Models

GroupMemberPaging

Properties

Name	Type
list	GroupMemberPagingList

GroupMemberPagingList

Properties

Name	Type
pagination	Pagination
entries	GroupMemberEntry[]

GroupMemberEntry

Properties

Name	Type
entry	GroupMember

GroupBodyCreate

Properties

Name	Type
id	string
displayName	string
parentIds	string[]

GroupMembershipBodyCreate

Properties

Name	Type
id	string
memberType	string

GroupMembershipBodyCreate.MemberTypeEnum

• GROUP (value: 'GROUP')
• PERSON (value: 'PERSON')

GroupBodyUpdate

Properties

Name	Type
displayName	string
description	string

GroupPaging

Properties

Name	Type
list	GroupPagingList

GroupPagingList

Properties

Name	Type
pagination	Pagination
entries	GroupEntry[]

GroupEntry

Properties

Name	Type
entry	Group