Table of Contents

Class OpenBiApiClientRoleExtensions

Namespace
BiExcellence.OpenBi.Api.Roles
Assembly
BiExcellence.OpenBi.Api.Client.dll

Extension methods for the /roles, /rolecontent, /rolecontentelements and /rolecontenthistory REST API.

public static class OpenBiApiClientRoleExtensions
Inheritance
object
OpenBiApiClientRoleExtensions

Methods

AssignRoleContentAsync(IOpenBiApiClient, string, string, AssignRoleContentRequest?, CancellationToken)

Places a standalone RoleContentElement into a role's content tree (creating the placement, or updating it if already assigned). Throws OpenBiApiException (404) when the role does not exist or the element has no default-language version, and (400) when ParentId is not a GUID. RemoveRoleContentAsync(IOpenBiApiClient, string, string, bool, bool, CancellationToken) undoes it.

public static Task AssignRoleContentAsync(this IOpenBiApiClient client, string roleId, string elementId, AssignRoleContentRequest? request = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
roleId string
elementId string
request AssignRoleContentRequest
cancellationToken CancellationToken

Returns

Task

AssignRoleOrganisationAsync(IOpenBiApiClient, string, string, RoleAssignmentRequest?, CancellationToken)

Assigns the role to an organisation, so it is available within that data scope. The optional RoleAssignmentRequest makes the access read-only or time limited; without it the assignment is valid for 30 days. Idempotent - assigning again replaces those fields. Throws OpenBiApiException (404) when the role or the organisation does not exist. RemoveRoleOrganisationAsync(IOpenBiApiClient, string, string, CancellationToken) undoes it.

public static Task AssignRoleOrganisationAsync(this IOpenBiApiClient client, string roleId, string organisationId, RoleAssignmentRequest? assignment = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
roleId string
organisationId string
assignment RoleAssignmentRequest
cancellationToken CancellationToken

Returns

Task

AssignRoleUserAsync(IOpenBiApiClient, string, string, RoleAssignmentRequest?, CancellationToken)

Assigns the role to one user. The optional RoleAssignmentRequest makes the access read-only or time limited; without it the assignment is valid for 30 days. Idempotent - assigning again replaces those fields. Throws OpenBiApiException (404) when the role or the user does not exist. RemoveRoleUserAsync(IOpenBiApiClient, string, string, CancellationToken) undoes it.

public static Task AssignRoleUserAsync(this IOpenBiApiClient client, string roleId, string userId, RoleAssignmentRequest? assignment = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
roleId string
userId string
assignment RoleAssignmentRequest
cancellationToken CancellationToken

Returns

Task

AssignRoleUsergroupAsync(IOpenBiApiClient, string, string, RoleAssignmentRequest?, CancellationToken)

Assigns the role to a usergroup, which hands it to every member of the group - the usual way to grant it. The optional RoleAssignmentRequest makes the access read-only or time limited; without it the assignment is valid for 30 days. Idempotent - assigning again replaces those fields. Throws OpenBiApiException (404) when the role or the usergroup does not exist. RemoveRoleUsergroupAsync(IOpenBiApiClient, string, string, CancellationToken) undoes it.

public static Task AssignRoleUsergroupAsync(this IOpenBiApiClient client, string roleId, string usergroupId, RoleAssignmentRequest? assignment = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
roleId string
usergroupId string
assignment RoleAssignmentRequest
cancellationToken CancellationToken

Returns

Task

CreateRoleAsync(IOpenBiApiClient, Role, CancellationToken)

Creates a role and returns it as stored, including the server-assigned id. Set Type to CMS when the role will carry a website. A new role is empty until elements are placed into it with AssignRoleContentAsync(IOpenBiApiClient, string, string, AssignRoleContentRequest?, CancellationToken). UpdateRoleAsync(IOpenBiApiClient, string, Role, CancellationToken) creates as well, under an id the caller picks.

public static Task<Role?> CreateRoleAsync(this IOpenBiApiClient client, Role role, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
role Role
cancellationToken CancellationToken

Returns

Task<Role>

CreateRoleContentElementAsync(IOpenBiApiClient, RoleContentElement, CancellationToken)

Creates a content element (POST rolecontentelements) - a dashboard, report, stored view, uploaded file or CMS page - and returns it with its server-assigned id. The element exists independently of any role; place it with AssignRoleContentAsync(IOpenBiApiClient, string, string, AssignRoleContentRequest?, CancellationToken), in as many roles as needed. Every save is recorded in GetRoleContentElementHistoryAsync(IOpenBiApiClient, string, string?, OpenBiListRequest?, CancellationToken).

public static Task<RoleContentElement?> CreateRoleContentElementAsync(this IOpenBiApiClient client, RoleContentElement element, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
element RoleContentElement
cancellationToken CancellationToken

Returns

Task<RoleContentElement>

DeleteRoleAsync(IOpenBiApiClient, string, CancellationToken)

Deletes a role together with its assignments to users, usergroups and organisations and its placements of content. The content elements themselves survive; delete them with DeleteRoleContentElementAsync(IOpenBiApiClient, string, string?, CancellationToken).

public static Task DeleteRoleAsync(this IOpenBiApiClient client, string id, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
id string
cancellationToken CancellationToken

Returns

Task

DeleteRoleContentElementAsync(IOpenBiApiClient, string, string?, CancellationToken)

Deletes a content element in every language, or only the version in language when one is given, together with its history. Deleting the default-language version also removes the element from every role, its usergroup restriction and its stored file. To take it out of one role only, use RemoveRoleContentAsync(IOpenBiApiClient, string, string, bool, bool, CancellationToken).

public static Task DeleteRoleContentElementAsync(this IOpenBiApiClient client, string id, string? language = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
id string
language string
cancellationToken CancellationToken

Returns

Task

DownloadRoleContentElementAsync(IOpenBiApiClient, string, bool, CancellationToken)

Downloads the file behind a role content element. The REST equivalent of the legacy /downloadrolecontentelement?element= endpoint: range requests are supported, and which elements the caller may see is decided by their own role content. The caller owns and must dispose the stream.

public static Task<Stream> DownloadRoleContentElementAsync(this IOpenBiApiClient client, string id, bool inline = false, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient

The client.

id string

The role content element id.

inline bool

Ask for an inline rather than an attachment content disposition.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<Stream>

DownloadRoleContentElementsAsync(IOpenBiApiClient, IEnumerable<string>, bool, CancellationToken)

Downloads several role content elements at once as a zip archive (a single id still yields the plain file). The caller owns and must dispose the stream.

public static Task<Stream> DownloadRoleContentElementsAsync(this IOpenBiApiClient client, IEnumerable<string> ids, bool folders = false, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient

The client.

ids IEnumerable<string>

The role content element ids.

folders bool

Recreate the role content folder structure inside the archive.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<Stream>

GetRoleAsync(IOpenBiApiClient, string, CancellationToken)

Reads one role by id. Throws OpenBiApiException (404) when there is no role with this id. Use GetRolesAsync(IOpenBiApiClient, OpenBiListRequest?, CancellationToken) with a filter to fetch several.

public static Task<Role> GetRoleAsync(this IOpenBiApiClient client, string id, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
id string
cancellationToken CancellationToken

Returns

Task<Role>

GetRoleContentAsync(IOpenBiApiClient, string, CancellationToken)

Lists the content placed in a role (GET roles/{id}/content): each entry says both what the element is and how it is placed in the role (parent folder, order, usergroup restriction). Elements are created with CreateRoleContentElementAsync(IOpenBiApiClient, RoleContentElement, CancellationToken) and placed with AssignRoleContentAsync(IOpenBiApiClient, string, string, AssignRoleContentRequest?, CancellationToken); SearchRoleContentAsync(IOpenBiApiClient, string?, string?, string?, string?, string?, string?, CancellationToken) searches across all roles instead.

public static Task<OpenBiListResult<RoleContentAssignment>> GetRoleContentAsync(this IOpenBiApiClient client, string roleId, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
roleId string
cancellationToken CancellationToken

Returns

Task<OpenBiListResult<RoleContentAssignment>>

GetRoleContentElementAsync(IOpenBiApiClient, string, string?, CancellationToken)

Reads one content element, independent of the roles it is placed in. Leave language unset for the default.

public static Task<RoleContentElement> GetRoleContentElementAsync(this IOpenBiApiClient client, string id, string? language = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
id string
language string
cancellationToken CancellationToken

Returns

Task<RoleContentElement>

GetRoleContentElementHistoryAsync(IOpenBiApiClient, string, string?, OpenBiListRequest?, CancellationToken)

Lists the saved revisions of a content element in one language (the default when language is unset), newest first. GetRoleContentHistoryRecordAsync(IOpenBiApiClient, string, CancellationToken) reads one.

public static Task<OpenBiListResult<RoleContentElementHistory>> GetRoleContentElementHistoryAsync(this IOpenBiApiClient client, string id, string? language = null, OpenBiListRequest? request = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
id string
language string
request OpenBiListRequest
cancellationToken CancellationToken

Returns

Task<OpenBiListResult<RoleContentElementHistory>>

GetRoleContentHistoryRecordAsync(IOpenBiApiClient, string, CancellationToken)

Reads one revision out of GetRoleContentElementHistoryAsync(IOpenBiApiClient, string, string?, OpenBiListRequest?, CancellationToken), with its content, so it can be inspected or restored by saving its fields back with UpdateRoleContentElementAsync(IOpenBiApiClient, string, RoleContentElement, CancellationToken). Throws OpenBiApiException (404) when there is no history record with this id.

public static Task<RoleContentElementHistory> GetRoleContentHistoryRecordAsync(this IOpenBiApiClient client, string historyId, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
historyId string
cancellationToken CancellationToken

Returns

Task<RoleContentElementHistory>

GetRoleOrganisationsAsync(IOpenBiApiClient, string, OpenBiListRequest?, CancellationToken)

Lists the organisations the role is assigned to. Assign one with AssignRoleOrganisationAsync(IOpenBiApiClient, string, string, RoleAssignmentRequest?, CancellationToken).

public static Task<OpenBiListResult<Organisation>> GetRoleOrganisationsAsync(this IOpenBiApiClient client, string roleId, OpenBiListRequest? request = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
roleId string
request OpenBiListRequest
cancellationToken CancellationToken

Returns

Task<OpenBiListResult<Organisation>>

GetRoleUsergroupsAsync(IOpenBiApiClient, string, OpenBiListRequest?, CancellationToken)

Lists the usergroups the role is assigned to. Assign one with AssignRoleUsergroupAsync(IOpenBiApiClient, string, string, RoleAssignmentRequest?, CancellationToken).

public static Task<OpenBiListResult<Usergroup>> GetRoleUsergroupsAsync(this IOpenBiApiClient client, string roleId, OpenBiListRequest? request = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
roleId string
request OpenBiListRequest
cancellationToken CancellationToken

Returns

Task<OpenBiListResult<Usergroup>>

GetRoleUsersAsync(IOpenBiApiClient, string, OpenBiListRequest?, CancellationToken)

Lists the users the role is assigned to directly; members of an assigned usergroup are not listed. Assign one with AssignRoleUserAsync(IOpenBiApiClient, string, string, RoleAssignmentRequest?, CancellationToken).

public static Task<OpenBiListResult<User>> GetRoleUsersAsync(this IOpenBiApiClient client, string roleId, OpenBiListRequest? request = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
roleId string
request OpenBiListRequest
cancellationToken CancellationToken

Returns

Task<OpenBiListResult<User>>

GetRolesAsync(IOpenBiApiClient, OpenBiListRequest?, CancellationToken)

Lists roles (GET roles), with the shared list options - select, filter, search, order, paging and count. Use QueryRolesAsync(IOpenBiApiClient, OpenBiListRequest?, CancellationToken) when a filter is too long for a URL.

public static Task<OpenBiListResult<Role>> GetRolesAsync(this IOpenBiApiClient client, OpenBiListRequest? request = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
request OpenBiListRequest
cancellationToken CancellationToken

Returns

Task<OpenBiListResult<Role>>

QueryRolesAsync(IOpenBiApiClient, OpenBiListRequest?, CancellationToken)

Lists roles with the options in the request body instead of in the query string - the QUERY-method form of the list route, for filters that do not fit in a URL.

public static Task<OpenBiListResult<Role>> QueryRolesAsync(this IOpenBiApiClient client, OpenBiListRequest? request = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
request OpenBiListRequest
cancellationToken CancellationToken

Returns

Task<OpenBiListResult<Role>>

RemoveRoleContentAsync(IOpenBiApiClient, string, string, bool, bool, CancellationToken)

Removes a content element from a role's content tree. Set deleteElement to also delete the underlying element when no role references it anymore.

public static Task RemoveRoleContentAsync(this IOpenBiApiClient client, string roleId, string elementId, bool recursive = false, bool deleteElement = false, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
roleId string
elementId string
recursive bool
deleteElement bool
cancellationToken CancellationToken

Returns

Task

RemoveRoleOrganisationAsync(IOpenBiApiClient, string, string, CancellationToken)

Withdraws the role from an organisation. Removes the assignment only; the role and its content stay. Removing one that is not there is not an error.

public static Task RemoveRoleOrganisationAsync(this IOpenBiApiClient client, string roleId, string organisationId, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
roleId string
organisationId string
cancellationToken CancellationToken

Returns

Task

RemoveRoleUserAsync(IOpenBiApiClient, string, string, CancellationToken)

Withdraws the role from a user. Removes the assignment only; the role and its content stay. Removing one that is not there is not an error.

public static Task RemoveRoleUserAsync(this IOpenBiApiClient client, string roleId, string userId, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
roleId string
userId string
cancellationToken CancellationToken

Returns

Task

RemoveRoleUsergroupAsync(IOpenBiApiClient, string, string, CancellationToken)

Withdraws the role from a usergroup. Removes the assignment only; the role and its content stay. Removing one that is not there is not an error.

public static Task RemoveRoleUsergroupAsync(this IOpenBiApiClient client, string roleId, string usergroupId, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
roleId string
usergroupId string
cancellationToken CancellationToken

Returns

Task

SearchRoleContentAsync(IOpenBiApiClient, string?, string?, string?, string?, string?, string?, CancellationToken)

Searches role content across all roles by name/content text and other filters (GET rolecontent/search). name and content match as substrings and an element matching either is returned; the other filters match exactly, type being the numeric content type code. The result is ordered by name and leaves Content and UsergroupIds empty.

public static Task<OpenBiListResult<RoleContentAssignment>> SearchRoleContentAsync(this IOpenBiApiClient client, string? roleId = null, string? roleType = null, string? type = null, string? language = null, string? name = null, string? content = null, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
roleId string
roleType string
type string
language string
name string
content string
cancellationToken CancellationToken

Returns

Task<OpenBiListResult<RoleContentAssignment>>

UpdateRoleAsync(IOpenBiApiClient, string, Role, CancellationToken)

Creates or updates the role with the given id (POST roles/{id}): an id that does not exist yet is inserted rather than answered with a 404.

public static Task<Role?> UpdateRoleAsync(this IOpenBiApiClient client, string id, Role role, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
id string
role Role
cancellationToken CancellationToken

Returns

Task<Role>

UpdateRoleContentElementAsync(IOpenBiApiClient, string, RoleContentElement, CancellationToken)

Creates or updates the content element with the given id and Language. The saved state is recorded in GetRoleContentElementHistoryAsync(IOpenBiApiClient, string, string?, OpenBiListRequest?, CancellationToken), from where an overwrite can be restored.

public static Task<RoleContentElement?> UpdateRoleContentElementAsync(this IOpenBiApiClient client, string id, RoleContentElement element, CancellationToken cancellationToken = default)

Parameters

client IOpenBiApiClient
id string
element RoleContentElement
cancellationToken CancellationToken

Returns

Task<RoleContentElement>