Help Center

Menu

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 Web services  SOAP API permission and role service

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 asset service will provide when enabled on a SOAP server.

To enable the functions for the SOAP asset service:

  1. Select Edit on the Details screen.

  2. Select the Enabled checkbox beside the function list you want to make available on the API.

  3. Select Save to make the selected functions available to use.

The Operations section below contains a full explanation of each function.

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
Example 1. HasAccess request
<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
Example 2. HasAccess response
<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 ID ⇒ allowed/denied. 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

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
Example 3. GetPermission request
<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
Example 4. GetPermission response
<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
Example 5. GetRole request
<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
Example 6. GetRole response
<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
Example 7. SetPermission request
<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
Example 8. SetPermission response
<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
Example 9. SetRole request
<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
Example 10. SetRole response
<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>