Report Server Security Extension (RSSE) API operations
This section describes RSSE API operations. Note that TargetVolume and OrgId are set in the SOAP header of each request going to an RSSE service.
OrgId is an optional value to filter the users for a specific volume, which can be configured in System Console. How this value is used depends on the RSSE implementation.
AuthenticateUser
Verifies that the user is authorized to access the BIRT iHub System. Implement AuthenticateUser for external user authentication and external user registration.
Request elements
User
The name of the user logging on to BIRT iHub.
Password
The user password.
Credentials
Additional credentials for authenticating the user.
UserSetting
Specifies whether to return the user properties. If True, returns the user properties.
OrgID
Specifies whether to return the user’s organization identifier. If True, returns the identifier.
Response elements
UserAndProperties
The user name and properties.
DoesRoleExist
Verifies whether the role exists in the external directory. BIRT iHub can call this function to clear references to deleted roles.
Request elements
RoleName
The name of the role to verify.
Response elements
Exists
Indicates whether the role exists. If True, the role exists.
DoesUserExist
Verifies whether the user exists in the external directory. BIRT iHub can call this function to clear references to deleted users.
Request elements
UserName
The name of the user to verify.
Response elements
Exists
Indicates whether the user exists. If True, the user exists.
GetConnectionProperties
Retrieves the connection properties for a user or role from an external data source for a pass-through security operation. In pass-through security, an information object’s DCD file sets the securityPolicy to TranslatedCredential. The proxy user name and password settings, specifying the user login credentials in the DCD, contain empty quotes and are ignored by the implementation.
Request elements
FileName
The fully qualified name of an information object’s data connection definition (DCD) file.
UserName
The name of the user or role.
Response elements
ConnectionProperties
The requested name and value pairs.
GetTranslatedRoleNames
Maps the external security role names to Actuate security role names. Either use GetTranslatedRoleNames in conjunction with the external registration security level, or use the same role names for the external and Actuate roles.
For example, a user with the Actuate Administrator security role can manage all items in a volume. If the Administrator role in the external security system has a different meaning, GetTranslatedRoleNames can map the external security role to an Actuate role with a different name.
Request elements
GetTranslatedRoleNames
The external translated role names that map to the Actuate security role names.
Response elements
TranslatedRoleNames
The names that Actuate uses for external security roles.
GetTranslatedUserNames
Maps the external security user names to Actuate security user names. Either use GetTranslatedUserNames in conjunction with the external registration security level, or use the same user names for the external and Actuate users.
For example, a user with the Actuate Administrator privilege can manage all items in a volume. If the Administrator user in the external security system has a different meaning, GetTranslatedUserNames can map the external security user to an Actuate user with a different name. Deprecated in BIRT iHub Release 3.
Request elements
GetTranslatedUserNames
The external translated user names that map to the Actuate security user names.
Response elements
TranslatedUserNames
The names that Actuate uses for external security users.
GetUserACL
Retrieves the user ACL. GetUserACL applies only if using page-level security. Page-level security controls printing, navigating, and all aspects of user viewing. Page-level security requires the Page Level Security option on BIRT iHub.
Request elements
UserName
The name of the user whose ACL to retrieve.
Response elements
ACL
The list of pages of a document to which the user has access.
GetUserProperties
Retrieves the user properties from an external directory. Regardless of security level implementation, implement GetUserProperties when the user properties are stored in an external security source.
Request elements
User
The name of the user whose properties to retrieve.
ResultDef
The properties to retrieve. Can contain user property names, roles, and PrivilegeTemplate.
Response elements
ArrayOfUserAndProperties
The user properties.
GetUsersToNotify
Retrieves the list of users to notify about completed jobs.
Request elements
GetUsersToNotify
The list of users to notify about completed jobs.
Response elements
Users
The list of users to notify.
PassThrough
Calls the RSSE for general purposes such as changing or refreshing the internal library state. If implemented, the RSSE calls PassThrough in response to the BIRT iHub receiving the Information Delivery API CallOpenSecurityLibrary request.
The RSSE passes the ReturnCode as a response to CallOpenSecurityLibrary, RSSE does not interpret the parameter.
Request elements
Input
The input parameter string.
Response elements
Output
The output parameter string.
ReturnCode
The integer parameter that the caller of CallOpenSecurityLibrary interprets.
SelectRoles
Searches for roles that match the specified criteria. Required if using an external registration security level.
SelectRoles can also retrieve a user roles. To retrieve a user roles, specify a name in UserName. SelectRolesResponse then returns the list of the user roles.
The SelectRoles SOAP message invokes the SelectRolesOfUser method within the Java code, and does not invoke the SelectRoles method. iHub does not use the SelectRoles method to link a user account to a role.
Request elements
QueryPattern
The string match.
UserName
The name of a user whose information to retrieve.
FetchSize
The maximum number of records to retrieve and return in a result set. The default value is 500.
Response elements
Roles
The list of roles matching the search criteria.
TotalCount
The number of entries in the search result set.
SelectUsers
Retrieves the names of users that match the specified criteria. For example, to retrieve the names of all users in the Sales group, specify Sales in GroupName.
SelectUsers is required if using an external registration security level.
Request elements
QueryPattern
The string match.
RoleName
The name of the role whose members to retrieve.
GroupName
The name of the group whose members to retrieve.
FetchSize
The maximum number of records to retrieve and return in a result set. The default value is 500.
Response elements
Users
The list of users matching the search criteria.
TotalCount
The number of entries in the search result set.
Start
Initializes the RSSE. Implement Start to initialize RSSE. Called once for each cluster
Request elements
ServerHome
The path to the BIRT iHub installation, for example C:\Program Files\Actuate\Server on Windows.
Volume
The name of the volume.
LogFile
The path to the log file for RSSE activity.
Version
The BIRT iHub version number.
Response elements
IntegrationLevel
The integration level of external security. One of the following values:
External_Authentication
External_Registration
None
ExternalProperties
The following external user or role properties are included in the response. All properties are required except where indicated.
EmailAddress
The user’s e-mail address
Description
A description of the user
HomeFolder
The user’s home folder
ViewPreference
The user’s web viewing preference, default or DHTML
MaxJobPriority
The maximum request priority the user can set when creating a report printing or generation request
SendNoticeForSuccess
Sends a notice if the job succeeds
SendNoticeForFailure
Sends a notice if the job fails
SuccessNoticeExpiration
The number of minutes that elapse before a successful job notice is deleted
FailureNoticeExpiration
The number of minutes that elapse before a failed job notice is deleted
SendEmailForSuccess
Sends an email if the job succeeds
SendEmailForFailure
Sends an email if the job fails
AttachReportInEmail
Attaches the report to the email if the job succeeds
DefaultObjectPrivileges
The privileges that the user has by default on the objects the user creates
ChannelSubscriptionList
A list of channels to which the user subscribes
LicenseOptions (optional)
License options available to the user
RSSEVersion
The version of RSSE.
UserACLExternal
Specifies whether the user access list is stored externally. Applies only if using page-level security.
ConnectionPropertyExternal
Specifies whether the user connection properties are retrieved externally from the RSSE. If True, the connection properties are retrieved externally. In this case, BIRT iHub directs requests to set connection properties to the RSSE and does not use GetConnectionProperties.
SelectUsersOfRole
Applies only under external registration. Specifies whether the RoleName element in SelectUsers is implemented. The setting indicates whether BIRT iHub enables this feature. The default value is False.
SupportGetTranslatedUserNames
Specifies whether to support translation of user names from external source.
Stop
Stops the Report Server Security Extension service. Implement Stop to close RSSE and free system resources.
Request elements
Stop
Closes RSSE and free system resources.
Response elements
StopResponse
Contains status information on results of stop operation.
External_Authentication