416.467.9100 | Dundas Data Visualization | Login
Welcome Guest
Dashboard v5.0

This site makes extensive use of JavaScript.

Please enable JavaScript in your web browser and reload the page before proceeding.

Dundas Dashboard Administration API

Hide navigation
RSS
Modified on Thu, 21 Nov 2013 12:26 PM Categorized as Administration, Level-Advanced, Open APIs, Support

Overview

The administration API allows you to programmatically perform tasks that are normally done through the dashboard designer:

  • Manage accounts and groups
    • Create, retrieve, update, and delete users and groups
    • Change group membership
  • Manage Dashboard objects
    • Move, rename, or delete objects
    • Duplicate projects
  • Manage object permissions

All the examples in this article require you to use the assemblies Dundas.Dashboard.Extensibility.Server.dll, Dundas.Dashboard.Server.Integration.dll and Dundas.Dashboard.Business.Server.dll from the Program Files\Dundas Data Visualization Inc\Dundas Dashboard\{InstanceName}\SDK\lib\Server\ folder. You will also need to import the namespaces:

using Dundas.Dashboard;
using Dundas.Dashboard.Extensibility;
using Dundas.Dashboard.Integration;
using Dundas.Dashboard.Integration.Administration;
using Dundas.Dashboard.Integration.Business;

Tip: This article is not a complete API listing. It gives an overview of all the general functionality the API provides, how to use it, and simple examples of common tasks. Various methods and overloads are omitted for simplicity.

Initialization and clean-up

Before using the administration API, you need to first initialize the IntegrationHelper with your Dashboard instance's URL, and a valid session for an account with admin privileges. Here is an example of the structure your code needs:

string adminAccountName = ""; // The name of your admin account (e.g. "admin")
string adminPassword = ""; // Admin account password (e.g. "password")
string dashboardUrl = ""; // URL to the Dundas Dashboard application (e.g. "http://dashboard.example.com/")

IntegrationHelper.ServerUri = new Uri(dashboardUrl, UriKind.Absolute); LoginStatus loginStatus = IntegrationHelper.LoginLocal(adminAccountName, adminPassword, true); if (loginStatus.LoginFailureReason == LoginFailureReason.None) { try { // Provide the IntegrationHelper with an admin session IntegrationHelper.SetCurrentSessionId(loginStatus.SessionId);

// *** Use the admin API here *** } finally { // Close admin session IntegrationHelper.Logout(loginStatus.SessionId); IntegrationHelper.ClearCurrentSessionId(); } }

Accounts and Groups

The administration API can create, retrieve, update, and delete accounts and groups. These settings can be modified through the API:

  • Account settings
    • First and last name
    • Email
    • Default culture
    • Privileges
    • Role
    • Password settings
      • Can user change password
      • Is password expired
      • Set password

  • Group settings
    • Comment describing the group

  • Common settings
    • Account name
    • Custom attributes
    • Enabled or disabled

Create

Dundas Dashboard has 3 types of accounts you can create:

Account typeDescription
LocalUserAccountA standard account in dashboard.
WindowsUserAccountAn account based on a Windows user.
WindowsGroupAccountAn account based on a Windows group. Any members of this group who log in have the viewer role.

Tip: The only other account type, VirtualWindowsUserAccount, is created automatically for users that log in via a Windows group. This account type cannot be directly created, disabled, or deleted.

To create an account, create a new instance of the desired account type and call Save:

// Example: Creating a local user.
LocalUserAccount localUserAccount = new LocalUserAccount("username", "password");
localUserAccount.IsEnabled = true;
localUserAccount.Save();

// Example: Creating a Windows user. WindowsUserAccount windowsUserAccount = new WindowsUserAccount(@"domain\user"); windowsUserAccount.IsEnabled = true; windowsUserAccount.Save();

// Example: Creating a Windows group user. WindowsGroupAccount windowsGroupAccount = new WindowsGroupAccount(@"domain\group"); windowsGroupAccount.IsEnabled = true; windowsGroupAccount.Save();

Creating a group is identical:

// Example: Creating a group.
Group group = new Group("group");
group.IsEnabled = true;
group.Save();

Tip: The default value of IsEnabled on Account and Group is false.



Retrieve

To retrieve accounts or groups, use the static methods on Account or Group:

// Example: Retrieve an account by name.
Account account1 = Account.GetByName("account");

// Example: Retrieve an account by ID. Account account2 = Account.GetById(new Guid("d37514fa-a1be-407a-9d47-7eb669372ca5"));

// Example: Retrieve all accounts. IEnumerable<Account> accounts = Account.GetAccounts();

// Example: Retrieve a group by name.
Group group1 = Group.GetByName("group");

// Example: Retrieve a group by ID. Group group2 = Group.GetById(new Guid("cbb1962f-22e3-4c25-8f35-b89c24b59ecf"));

// Example: Retrieve all groups. IEnumerable<Group> groups = Group.GetGroups();

Update

After making any modifications to the properties an account or group, call Save to commit the changes:

// Example: Save changes to an account.
account.Save();

// Example: Save changes to a group.
group.Save();

Delete

To delete an account or group, invoke the static method Delete on Account or Group.

// Example: Delete an account.  Requires the account's GUID.
Account.Delete(accountId);

// Example: Delete a group.  Requires the group's GUID.
Group.Delete(groupId);

Controlling group membership

Accounts can be added and removed from groups one of two ways:

  • Modify the Groups collection on an Account.
  • Modify the Accounts collection on a Group.

Both Account and Group instances have a method GetInfo which you'll need when adding items to the Groups or Accounts collection, respectively.

// Example: Remove the "admin" account from all groups and add only to the "administrators" group.
Account adminAccount = Account.GetByName("admin");
Group adminGroup = Group.GetByName("administrators");
adminAccount.Groups.Clear();
adminAccount.Groups.Add(adminGroup.GetInfo());

// Example: Remove all accounts from the "administrators" group and only add the "admin" account.
Account adminAccount = Account.GetByName("admin");
Group adminGroup = Group.GetByName("administrators");
adminGroup.Accounts.Clear();
adminGroup.Accounts.Add(adminAccount.GetInfo());

Setting password

The API can reset the password for local accounts in Dashboard:

// Example: Change the password for the local "viewer" account.
LocalUserAccount localAccount = (LocalUserAccount)Account.GetByName("viewer");
LocalUserAccount.SetPassword(localAccount.Id, "password");

Setting privileges

Accounts and groups can be granted or denied privileges.

PrivilegeDescription
Privileges.AdminPerform administrative operations.
Privileges.NotificationCreateCreate notifications.
Privileges.NotificationControlModify or delete notifications created by other users.
Privileges.NotificationSubscribeOthersSubscribe or unsubscribe others to notifications belonging to this user.
Privileges.AnnotateCommandUse the viewer's Annotate command.
Privileges.BookmarkCommandUse the viewer's Bookmark command.
Privileges.CustomizeCommandUse the viewer's Customize command.
Privileges.ExportCommandUse the viewer's Export command.
Privileges.FilterAnnotationGroupsCommandUse the viewer's Filter Annotation Groups command.
Privileges.FormulasMenuCommandUse the viewer's Formulas command.
Privileges.HelpCommandUse the viewer's Help command.
Privileges.ManageContentCommandUse the viewer's Manage Content command.
Privileges.NotificationCommandUse the viewer's Notification command.
Privileges.PerformanceInfoCommandUse the viewer's Performance Information Dialog command.
Privileges.PrintCommandUse the viewer's Print command.
Privileges.SaveMashupCommandUse the viewer's Save Mashup command.
Privileges.ShareCommandUse the viewer's Share command.
Privileges.ViewerNavigationRibbonUse the viewer navigation ribbon.

// Example: Give the "viewer" account print permissions but deny export.
Account account = Account.GetByName("viewer");
account.DeniedStandardPrivileges.Add(Privileges.ExportCommand);
account.GrantedStandardPrivileges.Add(Privileges.PrintCommand);

Tip: Deny is more powerful than grant. When calculating effective privileges, the union of all granted and denied privileges for a user and all the groups they belong to is determined. The total granted permissions then subtracts all denied permissions, and the result is the user's effective privileges.

Tip: If the user's effective privileges contains the Admin privilege, then the user can perform any operation and has all privileges granted.

Note: In Dundas Dashboard 5.0.1 or later, an exception will be thrown if the exact same privilege is both granted and denied.

Setting role

Accounts fall under one of 4 possible roles:

RoleDescription
ViewerRoleNormal viewer that uses a floating license.
NamedViewerRoleNamed viewer that reserves a license.
DashboardDesignerRoleDashboard designer that can edit only dashboards.
DashboardDeveloperRoleDashboard developer that can use all functions of the designer.

To give an account a role, simply assign a new instance of one of these 4 classes to the account's Role:

account.Role = new ViewerRole();

The dashboard developer role has privileges which can be turned on and off, such as data connector or virtual structure editing privileges. Privileges contains static members which includes all role privileges. Here is an example of how you assign the dashboard developer role without data connector editing privileges:

DashboardDeveloperRole role = new DashboardDeveloperRole();
role.AssociatedPrivileges.Remove(Privileges.DataConnectorAnalyst);
account.Role = role;

Dashboard objects

All objects in dashboard are represented by an ObjectInfo. Objects can be moved, renamed, and deleted. Folders are a specific subclass, FolderInfo, and are the only object type the API can create.

If you need to traverse Dashboard's file system to work on multiple objects, or don't know an object's ID, start at one of the top-level folders and inspect its contents. The top-level folders have fixed IDs that are contained in FolderIds:

  • File system root - FolderIds.FileSystemRoot
    • Bookmarks - FolderIds.BookmarksRootFolder
    • Projects - FolderIds.ProjectsRootFolder
    • Shared Resources - FolderIds.SharedResourcesRootFolder

All other objects in Dashboard are contained within these folders.

Create folders

FolderInfo newFolderInfo = FolderInfo.CreateFolder("New Folder", parentFolderId);

Move

ObjectInfo.Move(objectId, folderId):

Rename

ObjectInfo.Rename(objectId, "name");

Delete

ObjectInfo.Delete(objectId);

Duplicate project

IntegrationHelper.DuplicateProject(projectId, "new project name");
IntegrationHelper.DuplicateProject(projectId, targetProjectId);

Create bookmark

Bookmark b = new Bookmark();
b.Name = "My new bookmark";
b.BusinessObjectId = new Guid("9f79a7f3-2eb8-4057-bed7-d7bf613c0f7b"); //The GUID of the dashboard
IntegrationHelper.SaveBookmark(loginStatus.SessionId, b);

Object permissions

All permissions for objects in Dashboard are handled using ObjectAccessRights. The static method Get retrieves the permissions for any object. The permissions on ObjectAccessRights are:

PermissionDescription
ReadCan access this object.
WriteCan make changes to this object.
DeleteCan delete this object.
FullControlCan change permissions on this object.

Each permission has a collection for accounts or groups that have been granted or denied access.

// Example: Get the access rights for the Sonatica Executive and Sales dashboards.
// Grant the "viewer" account read access on the Executive dashboard and deny read access on the Sales dashboard.
ObjectAccessRights sonaticaExecutiveRights = ObjectAccessRights.Get(new Guid("7bcebd59-d425-4f29-9ea4-73033d50d515"));
ObjectAccessRights sonaticaSalesRights = ObjectAccessRights.Get(new Guid("de3fc12b-e5ea-40de-85f9-1d56631b6751"));

Account viewerAccount = Account.GetByName("viewer"); PrivilegeAssignee viewerPrivilegeAssignee = new PrivilegeAssignee(PrivilegeAssigneeType.LocalUserAccount, viewerAccount.Id, viewerAccount.AccountName);

sonaticaExecutiveRights.Read.GrantedTo.Add(viewerPrivilegeAssignee); sonaticaSalesRights.Read.DeniedTo.Add(viewerPrivilegeAssignee);

// Apply new permissions. sonaticaExecutiveRights.Save(); sonaticaSalesRights.Save();

Tip: When permissions are set on a folder, the permissions are applied recursively to all child objects.

Related topics

IntegrationHelper API

About Dundas | Contact Us Follow us on Twitter! | Privacy Statement | Report Site Issues

Copyright © 2009-2014 Dundas Data Visualization, Inc.