The SOAP setup

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. For the API to work, it must be created under a SOAP Server within the Web Services folder, as shown in the figure to the right. The API will then be available to enable on the Details screen of the SOAP Server, as shown in the figure below.

The SOAP API Permission And Role Service available on the SOAP Server

You can configure the settings of the SOAP API Metadata Service on its associated asset screens. The majority of these screens are the same or similar to those for a Standard Page and are described in the Asset Screens manual. In this chapter we 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. For more information about the Status, Future Status, Thumbnail and Details sections, refer to the Details Screen chapter in the Asset Screens manual.

Interface Settings

This section allows you to control which functions the SOAP API Permission And Role Service will be able to provide when enabled on a SOAP Server. The Interface Settings section of the Details screen is shown in the figure below.

The Interface Settings section of the Details screen

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
• GetPermission
• GetRole
• SetPermission
• SetRole

See the sections below for more information on each of the operations available on this API.

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:

• AssetID: the asset ID of the asset to perform the permission check on. This parameter is mandatory.
• 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.

Example 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>

Example 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:

• AssetID: the asset ID of the asset to return set permissions from. This parameter is mandatory.
• PermissionLevel: the permission level to check. For example, Write will check if the user has Write Permission. This parameter is mandatory.
• Granted: 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.
• AndGreater: 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.
• ExpandGroups: 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.
• AllInfo: 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.
• CollapseRoles: 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.

Example 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>

Example 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:

• AssetID: the asset ID of an asset to return the roles assigned to it. The default value for this parameter is NULL.
• RoleID: the asset ID of a role to return all applied roles for. The default value for this parameter is NULL.
• UserID: the asset ID of a user to return all applied roles for. The default value for this parameter is NULL.
• IncludeAssetID: 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.
• IncludeGlobals: 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.
• ExpandGroups: 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.
• IncludeDependants: 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.

Example 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>

Example 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:

• AssetID: the asset ID of the asset to set permission for. This parameter is mandatory.
• UserID: the asset ID of the user being affected by the permission. This parameter is mandatory.
• PermissionLevel: the permission level to apply. For example, Admin will give the selected user Admin Permission for the selected asset. This parameter is mandatory.
• Grant: the Grant value that will determine how the permission is implemented, for example Apply. This parameter is mandatory.
• Cascade: 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.

Expand 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>

Example 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:

• AssetID: the asset ID of the asset to set the role on. This parameter is mandatory. The default value for this parameter is NULL.
• RoleID: the asset ID of the role being applied to the asset. This parameter is mandatory. The default value for this parameter is NULL.
• UserID: the asset ID of the user being affected by the role. This parameter is mandatory. The default value for this parameter is NULL.
• Action: 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.
• GlobalRule: indicates whether the role should be performed globally. Any user linked under the role will be able to perform the granted role, not just the 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.

Example 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>

Example 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>