SOAP API permission and role service
The SOAP API permission and role service asset manages the permission and role functions of the SOAP server, including setting and retrieving permissions and roles.
To add a SOAP API permission and role service, go to
You can configure the settings of the SOAP API metadata service on its associated asset screens. The majority of these screens are similar to those for a standard page. They are described in the Asset screens documentation. This documentation will describe the Details screen, which is different for a SOAP API search service.
Details screen
The Details screen allows you to configure the interface functions for the SOAP API permission and role service. Read the Asset screens documentation for more information about the Status, Future status, Thumbnail, and Details sections.
Interface settings
This section allows you to control which functions the SOAP API permission and role service will provide when enabled on a SOAP server. The interface settings section of the Details screen is shown in the figure.
In the function list, select enabled for the functions you want to make available on the API. For a full explanation of these functions, see the operations section below.
Operations
The operations that are managed by the SOAP API permission and role service are as follows:
HasAccess
The HasAccess operation will check if the requesting user has a set permission level for a specified asset. The parameters available for this operation are as follows:
HasAccessSoapInput (HasAccess)
| Elements - Parameter [Param Type] | Description | Min Occurs | Max Occurs | Type |
|---|---|---|---|---|
AssetID [string] |
The asset ID of the asset to perform the permission check on. This parameter is mandatory. |
1 |
1 |
simple |
PermissionLevel [PermissionLevel] |
The permission level to check. For example, Read will check if the user has read permission for the selected asset. This parameter is mandatory. |
1 |
1 |
simple |
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:HasAccess>
<AssetID>100</AssetID>
<PermissionLevel>Admin</PermissionLevel>
</ns1:HasAccess>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>HasAccessSoapOutput (HasAccessResponse)
| Elements - Parameter [Param Type] | Min Occurs | Max Occurs | Type |
|---|---|---|---|
HasAccessResult [boolean] |
0 |
1 |
simple |
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:HasAccessResponse>
<HasAccessResult>true</HasAccessResult>
</ns1:HasAccessResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>GetPermission
The GetPermission operation will return the permissions set for a specified asset. The parameters available for this operation are as follows:
GetPermissionSoapInput (GetPermission)
| Elements - Parameter [Param Type] | Description | Min Occurs | Max Occurs | Type |
|---|---|---|---|---|
AssetID [string] |
The asset ID of the asset to return set permissions from. This parameter is mandatory. |
1 |
1 |
simple |
PermissionLevel [PermissionLevel] |
The permission level to check. For example, Write will check if the user has write permission. This parameter is mandatory. |
1 |
1 |
simple |
Granted [boolean] |
Indicates whether the permission is applied or denied. The value for this parameter should be either TRUE (allow) or FALSE (deny). The default value for this parameter is NULL. |
0 |
1 |
simple |
AndGreater [boolean] |
Indicates whether effective access will be granted. This means that if Write permission is granted, Read permission will also be granted. Similarly, if Admin permission is granted, both Read and Write permission will be granted. The value for this parameter should be either TRUE or FALSE (or 1 or 0). The default value for this parameter is FALSE. |
0 |
1 |
simple |
ExpandGroups [boolean] |
Indicates whether permissions applied to a group should be returned as a group permission or as individual permissions for the group users. The value for this parameter should be either TRUE or FALSE (or 1 or 0). The default value for this parameter is FALSE. |
0 |
1 |
simple |
AllInfo [boolean] |
Indicates whether the returned values are in the form of user IDs or in the form or an array, for example user |
0 |
1 |
simple |
CollapseRoles [boolean] |
Indicates whether the operation should return permissions applied on users or permissions applied on users and roles. The value for this parameter should be either TRUE or FALSE (or 1 or 0). The default value for this parameter is FALSE. |
0 |
1 |
simple |
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:GetPermission>
<AssetID>100</AssetID>
<PermissionLevel>Read</PermissionLevel>
<Granted>TRUE</Granted>
<AndGreater>TRUE</AndGreater>
<ExpandGroups>FALSE</ExpandGroups>
<AllInfo>TRUE</AllInfo>
<CollapseRoles>FALSE</CollapseRoles>
</ns1:GetPermission>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>GetPermissionSoapOutput (GetPermissionResponse)
| Elements - Parameter [Param Type] | Min Occurs | Max Occurs | Type |
|---|---|---|---|
GetPermissionResult [PermissionDetail] |
0 |
/ |
complex |
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:GetPermissionResponse>
<GetPermissionResult>
<UserID>0</UserID>
<Grant>7</Grant>
</GetPermissionResult>
<GetPermissionResult>
<UserID>1</UserID>
<Grant>140</Grant>
</GetPermissionResult>
</ns1:GetPermissionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>GetRole
The GetRole operation will return an array of roles and users/groups that can or cannot perform actions on an asset. The parameters available for this operation are as follows:
GetRoleSoapInput (GetRole)
| Elements - Parameter [Param Type] | Description | Min Occurs | Max Occurs | Type |
|---|---|---|---|---|
AssetID [string] |
The asset ID of an asset to return the roles assigned to it. The default value for this parameter is NULL. |
0 |
1 |
simple |
RoleID [string] |
The asset ID of a role to return all applied roles for. The default value for this parameter is NULL. |
0 |
1 |
simple |
UserID [string] |
The asset ID of a user to return all applied roles for. The default value for this parameter is NULL. |
0 |
1 |
simple |
IncludeAssetID [string] |
Indicates whether to include the asset ID in the operation’s returned result. The value for this parameter should be either TRUE or FALSE (or 1 or 0). The default value for this parameter is FALSE. |
0 |
1 |
simple |
IncludeGlobals [string] |
Indicates whether the operation should query the role view, which includes expanded global roles as individual users. The value for this parameter should be either TRUE or FALSE (or 1 or 0). The default value for this parameter is FALSE. |
0 |
1 |
simple |
ExpandGroups [string] |
Indicates whether roles applied to a group should be returned as a group permission or as individual permissions for the group users. The value for this parameter should be either TRUE or FALSE (or 1 or 0). The default value for this parameter is FALSE. |
0 |
1 |
simple |
IncludeDependants [string] |
Indicated whether the operation should include dependant assets. The value for this parameter should be either TRUE or FALSE (or 1 or 0). The default value for this parameter is TRUE. |
0 |
1 |
simple |
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:GetRole>
<RoleID>200</RoleID>
<IncludeAssetID>TRUE</IncludeAssetID>
<IncludeGlobals>TRUE</IncludeGlobals>
<ExpandGroups>TRUE</ExpandGroups>
<IncludeDependants>FALSE</IncludeDependants>
</ns1:GetRole>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>GetRoleSoapOutput (GetRoleResponse)
| Elements - Parameter [Param Type] | Min Occurs | Max Occurs | Type |
|---|---|---|---|
GetRoleResult [RoleDetail] |
0 |
/ |
complex |
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:GetRoleResponse>
<GetRoleResult>
<RoleID>200</RoleID>
<UserID>132</UserID>
<AssetID>40</AssetID>
</GetRoleResult>
<GetRoleResult>
<RoleID>200</RoleID>
<UserID>183</UserID>
<AssetID>40</AssetID>
</GetRoleResult>
</ns1:GetRoleResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>SetPermission
The SetPermission operation will set the permission for a user on a specified asset. The parameters available for this operation are as follows:
SetPermissionSoapInput (SetPermission)
| Elements - Parameter [Param Type] | Description | Min Occurs | Max Occurs | Type |
|---|---|---|---|---|
AssetID [string] |
The ID of the asset for which to set permission. This parameter is mandatory. |
1 |
1 |
simple |
UserID [string] |
The asset ID of the user being affected by the permission. This parameter is mandatory. |
1 |
1 |
simple |
UserID [string] |
The asset ID of the user being affected by the permission. This parameter is mandatory. |
1 |
1 |
simple |
PermissionLevel [PermissionLevel] |
The permission level to apply. For example, Admin will give the selected user admin permission for the selected asset. This parameter is mandatory. |
1 |
1 |
simple |
Grant [Grant] |
The Grant value that will determine how the permission is implemented, for example Apply. This parameter is mandatory. |
1 |
1 |
simple |
Cascade [boolean] |
Indicates whether the permission will be cascaded to all child assets. The value for this parameter should be either TRUE or FALSE (or 1 or 0). The default value for this parameter is TRUE. |
0 |
1 |
simple |
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:SetPermission>
<AssetID>100</AssetID>
<UserID>90</UserID>
<PermissionLevel>Write</PermissionLevel>
<Grant>Apply</Grant>
<Cascade>TRUE</Cascade>
</ns1:SetPermission>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>SetPermissionSoapOutput (SetPermissionResponse)
| Elements - Parameter [Param Type] | Min Occurs | Max Occurs | Type |
|---|---|---|---|
SetPermissionResult [String] |
0 |
1 |
simple |
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:SetPermissionResponse>
<SetPermissionResult>1</SetPermissionResult>
</ns1:SetPermissionResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>SetRole
The SetRole operation will set a role for a user on a specified asset. The parameters available for this operation are as follows:
SetRoleSoapInput (SetRole)
| Elements - Parameter [Param Type] | Description | Min Occurs | Max Occurs | Type |
|---|---|---|---|---|
AssetID [string] |
The asset ID of the asset on which to set the role. This parameter is mandatory. The default value for this parameter is NULL. |
1 |
1 |
simple |
RoleID [string] |
The asset ID of the role being applied to the asset. This parameter is mandatory. The default value for this parameter is NULL. |
1 |
1 |
simple |
UserID [string] |
The asset ID of the user being affected by the role. This parameter is mandatory. The default value for this parameter is NULL. |
0 |
1 |
simple |
Action [RoleActionType] |
The role action type that will determine how the role is implemented, for example Add. This parameter is mandatory. The default value for this parameter is NULL. |
1 |
1 |
simple |
GlobalRole [boolean] |
Indicates whether the role should be performed globally. Any user linked under the role will be able to perform the granted role, not just that role’s specified user set. The value for this parameter should be either TRUE or FALSE (or 1 or 0). The default value for this parameter is TRUE. |
0 |
1 |
simple |
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:SetRole>
<AssetID>100</AssetID>
<RoleID>120</RoleID>
<UserID>90</UserID>
<Action>Add</Action>
<GlobalRule>TRUE</GlobalRule>
</ns1:SetRole>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>SetRoleSoapOutput (SetRoleResponse)
| Elements - Parameter [Param Type] | Min Occurs | Max Occurs | Type |
|---|---|---|---|
SetRoleResult [boolean] |
0 |
1 |
simple |
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://SYSTEM_ROOT_URL/_web_services/soap-server">
<SOAP-ENV:Body>
<ns1:SetRoleResponse>
<SetRoleResult>true</SetRoleResult>
</ns1:SetRoleResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>