PutEndpointsCollectionsAcl

General

URL

https://{host}/attunityenterprisemanager/api/v1/servers/{server}/endpoints/{endpoint}?action=acl

Description

Sets a list of users/groups that have permissions on all endpoints in Qlik Enterprise Manager.

The method will replace any existing explicit ACL with the ACL in the request.

The request also includes a Boolean flag for specifying if the endpoints should inherit ACLs from their ancestors (in addition to their explicitly defined ACLs) or not.

The inherited ACLs (that is, the ACLs of an endpoint's ancestors) are not affected by this method.

The PutEndpointsCollectionsAcl can be used together with the GetEndpointsCollectionsAcl method in order to update an existing endpoint's ACL. First call GetEndpointsCollectionsAcl, then edit the returned roles as required, and finally, call PutEndpointsCollectionsAcl.

Behavior when putting a partial request

When the request body includes only some of the roles (as opposed to all four of them), only the roles specifically defined in the request body will be set on the endpoints; roles that are missing or empty will be inherited, but only if the following are true:

The disable_inheritance flag is set to "True".
The roles that are missing/empty in the request are defined for the ancestors.

Behavior on conflicts

If the disable_inheritance flag is set to "False" and the explicit roles in the request conflict with existing inherited roles, then the explicit roles will take precedence. For example, if the request defines user A as a Viewer on All Endpoints and user A is also defined as an Admin on EndpointB, then user A will be defined as an Viewer on All Endpoints.

The user permissions in Enterprise Manager are completely independent of the user permissions in Replicate. Consequently, PutEndpointsCollectionsAclwill affect the endpoint's Enterprise Manager user permissions, but will not affect Replicate's user permissions.

Moreover, when performing an operation via Enterprise Manager, the user permissions defined for the endpoint entity in Enterprise Manager apply, whereas when performing an operation directly via the Replicate Console, the user permissions defined in Replicate apply.

Defining the same user/group in different roles is not allowed. However, if the same user or group is defined in different roles but with a different case (for example, Mike vs. mike or Analysts vs. ANALYSTS), no error will be returned and the strongest role will take precedence.

HTTP method

PUT

Required user role

See Required Enterprise Manager permissions.

Request parameters

Request parameters
Location	Name	Required	Example
URL	Host [string]	Yes	computer.network.net
URL	Server [string]	Yes	myrepsrv1
URL	Endpoint [string]	Yes	MyEndpoint
Header	EnterpriseManager.APISessionID [string]	Yes	wCo0_KvjEUFROvfHF5KGrw

Request body


{
  "admin_role": {
    "users": [ { "name": "{string}"}, { "name": "{string}"}, … ],
    "groups": [ { "name": "{string}"}, { "name": "{string}"}, … ]
  },
  "designer_role": {
    "users": [ { "name": "{string}"}, { "name": "{string}"}, … ],
    "groups": [ { "name": "{string}"}, { "name": "{string}"}, … ]
  },
  "operator_role": {
    "users": [ { "name": "{string}"}, { "name": "{string}"}, … ],
    "groups": [ { "name": "{string}"}, { "name": "{string}"}, … ]
  },
  "viewer_role": {
    "users": [ { "name": "{string}"}, { "name": "{string}"}, … ],
    "groups": [ { "name": "{string}"}, { "name": "{string}"}, … ]
  },
  "disable_inheritance": "{bool}"
}

Request parameters

admin_role
- users: An array of users assigned as Admins on all endpoints.
  - name: A single Admin user.
- groups: An array of groups assigned as Admins on all endpoints.
  - name: A single Admin group.
designer_role
- users: An array of users assigned as Designers on all endpoints.
  - name: A single Designer user.
- groups: An array of groups assigned as Designers on all endpoints.
  - name: A single Designer group.
operator_role
- users: An array of users assigned as Operators on all endpoints.
  - name: A single Operator user.
- groups: An array of groups assigned as Operators on all endpoints.
  - name: A single Operator group.
viewer_role
- users: An array of users assigned as Viewers on all endpoints.
  - name: A single Viewer user.
- groups: An array of groups assigned as Viewers on all endpoints.
  - name: A single Viewer group.
disable_inheritance: If set to "true", the endpoints do not inherit ACLs from their ancestors (in addition to its explicit ACLs). If set to "false", the endpoints inherit ACLs from their ancestors, in addition to any explicit ACLs.

Response parameters
Name	A	B	Description
admin_role	-	-	-
-	users	-	An array of users assigned as Admins on the server.
-	-	name	A single Admin user.
-	groups	-	An array of groups assigned as Admins on the server.
-	-	name	A single Admin group.
designer_role	-	-	-
-	users	-	An array of users assigned as Designers on the server.
-	-	name	A single Designer user.
-	groups	-	An array of groups assigned as Designers on the server.
-	-	name	A single Designer group.
operator_role	-	-	-
-	users	-	An array of users assigned as Operators on the server.
-	-	name	A single Operator user.
-	groups	-	An array of groups assigned as Operators on the server.
-	-	name	A single Operator group.
viewer_role	-	-	-
-	users	-	An array of users assigned as Viewers on the server.
-	-	name	A single Viewer user.
-	groups	-	An array of groups assigned as Viewers on the server.
-	-	name	A single Viewer group.
disable_inheritance	-	-	If set to "true", the server does not inherit ACLs from its ancestors (in addition to its explicit ACLs). If set to "false", the server inherits ACLs from its ancestors, in addition to any explicit ACLs.

Example: Add a user with Operator permission to all endpoints

Replace the placeholders before running the commands:

https://{host}
<SESSION_ID>
<Server Name>
domain\\existing_user and domain\\new_user

PUT

curl -k -X PUT "https://{host}/attunityenterprisemanager/api/v1/servers/<Server Name>/endpoints?action=acl" \ --header "EnterpriseManager.APISessionID: <SESSION_ID>" \ --header "Content-Type: application/json" \ --data-raw '{ "admin_role": {"users": [{"name": "domain\\existing_user"}], "groups": []}, "designer_role": {"users": [], "groups": []}, "operator_role": {"users": [{"name": "domain\\new_user"}], "groups": []}, "viewer_role": {"users": [], "groups": []}, "disable_inheritance": false }'

Verify (GET)

curl -k -X GET "https://{host}/attunityenterprisemanager/api/v1/servers/<Server Name>/endpoints?action=acl" \ --header "EnterpriseManager.APISessionID: <SESSION_ID>"

Error response

All of the general errors as well as the errors listed in the table below.

Error responses
HTTP Code	Enterprise Manager Code	Text	Description
500	DESERIALIZE_TO_TYPE	"Failed to deserialize json to type AemAuthorizationAcl: {message}"	Returned when the JSON format is invalid format. For example, such an error will be returned if the JSON contains an unknown role.
500	AEM_PUT_SERVER_ACL_INNER_ERR	Failed to put ACL of endpoint "{endpoint}". Error: "{message}".	Returned if Qlik Enterprise Manager encounters an error/exception when trying to put an endpoint's ACL.
500	AEM_NO_ DOMAIN_IN_USER	User "{userName}" must be preceded by a domain name, separated by a backslash. Example: domain_name\user_name.	Returned when the domain is missing from the user name.
500	AEM_NO_ DOMAIN_IN_GROUP	Group "{groupName}" must be preceded by a domain name, separated by a backslash. Example: domain_name\group_name.	Returned when the domain is missing from the group name.
500	AEM_NO_ADMIN_ON_SERVER	Requested endpoint "{endpointName}" has no admin user. At least one user or group must be assigned to the "admin" role.	Returned when there is no admin on the server. Possible reasons: The request JSON is set to disable_inheritance=true and the explicit admin role in the JSON is empty. The JSON is set to disable_inheritance =true, the explicit admin role in the JSON is empty, and the parent levels do not have an admin user to inherit.
500	AEM_USER_ASSIGNED_TO_MULTIPLE_ROLES	User "{userName}" is assigned to multiple roles. Users can only be assigned to a single role.	Returned when a user is assigned to multiple roles.
500	AEM_GROUP_ASSIGNED_TO_MULTIPLE_ROLES	Group "{groupName}" is assigned to multiple roles. Groups can only be assigned to a single role.	Returned when a group is assigned to multiple roles.
500	AEM_USER_GROUP_MULTIPLE_ASSIGNED	"{userName/groupName}" is assigned to multiple roles or to the same role twice. Users/groups can only be assigned once, and to a single role.	Returned either when the specified user already exists as a group in the same/another role, or the specified group already exists as a user in the same/another role.

Did this page help you?

If you find any issues with this page or its content – a typo, a missing step, or a technical error – please let us know!

Leave your feedback here