Create a Custom Role
Collapse the table of content
Expand the table of content
This documentation is archived and is not being maintained.

Create a Custom Role

Dynamics
banner art

[Applies to: Microsoft Dynamics CRM 4.0]

Find the latest SDK documentation: CRM 2015 SDK

This sample shows how to create a custom security role called "Call Center Representative". This new role has all privileges necessary to read accounts and contacts and to manage cases and activities for those customers. The required privileges include the following:

  • Local Read on Contact, Accounts, Cases, and Activities
  • Local Create on Cases and Activities
  • Local Write on Cases and Activities
  • Local Append on Cases and Activities
  • Local AppendTo on Accounts and Contacts

Note    When you create a new role, you must also add a set of privileges that all roles should have by default. For more information, see Default Privileges Required. This sample code does not add all of these privileges but it can be easily modified to do so.

This sample code can be found in the following files in the SDK download:

Server\HowTo\CS\Entities\CustomRolesHowTo.cs
Server\HowTo\VB\Entities\CustomRolesHowTo.vb

For more information about the helper methods in the Microsoft.Crm.Sdk.Utility.CrmServiceUtility namespace, see Utility Sample Code.

Example

[C#]
using System;
using CrmSdk;
using Microsoft.Crm.Sdk.Utility;

namespace Microsoft.Crm.Sdk.HowTo
{
      public class CustomRolesHowTo
      {
            static void Main(string[] args)
            {
                  // TODO: Change the server URL and Organization to match your Microsoft Dynamics CRM Server and Microsoft Dynamics CRM organization.
                  CustomRolesHowTo.Run("http://localhost:5555", "CRM_SDK");
            }

            public static bool Run(string crmServerUrl, string orgName)
            {
                  #region Setup Data Required for this Sample

                  bool success = false;

                  #endregion


                  // Set up the CRM Service.
                  CrmService service = CrmServiceUtility.GetCrmService(crmServerUrl, orgName);

                  WhoAmIRequest userRequest = new WhoAmIRequest();
                  WhoAmIResponse user = (WhoAmIResponse)service.Execute(userRequest);

                  #region Create the Role
                  // Create the role object.
                  role role = new role();

                  // Set the property of the role.
                  role.name = "Call Center Representative";
                  role.businessunitid = new Lookup();
                  role.businessunitid.type = EntityName.businessunit.ToString();
                  role.businessunitid.Value = user.BusinessUnitId;

                  // Create the role.
                  Guid roleId = service.Create(role);
                  #endregion

                  #region Retrieve the Permission Set
                  // Create the request object.
                  RetrievePrivilegeSetRequest retrieve = new RetrievePrivilegeSetRequest();

                  // Execute the request.
                  RetrievePrivilegeSetResponse retrieved = (RetrievePrivilegeSetResponse)service.Execute(retrieve);

                  // Build the permission set.
                  RolePrivilege[] privileges = new RolePrivilege[12];// The role is receiving 12 permissions

                  // The variable is declared outside the loop.
                  privilege currentPrivilege;

                  // Iterate through all the returned permissions and get the GUID of the permissions being granted.
                  for (int i = 0; i < retrieved.BusinessEntityCollection.BusinessEntities.Length; i++)
                  {
                        currentPrivilege = (privilege)retrieved.BusinessEntityCollection.BusinessEntities[i];

                        // The GUID of currentPrivilege is added to the list if it is one of the permissions being given to the role.
                        switch (currentPrivilege.name)
                        {
                              case "prvReadContact":
                                    // If the current privilege is the prvReadContactPrivilege, a new RolePrivilege object is added to the privilege set.
                                    privileges[0] = new RolePrivilege();
                                    // The RolePrivilege's PrivilegeId is set to the currentPrivilege's privilegeid
                                    privileges[0].PrivilegeId = currentPrivilege.privilegeid.Value;
                                    // The RolePrivilege's Depth is set to the access the depth that the role is being granted for this privilege.
                                    privileges[0].Depth = PrivilegeDepth.Local;
                                    break;
                              case "prvReadAccount":
                                    privileges[1] = new RolePrivilege();
                                    privileges[1].PrivilegeId = currentPrivilege.privilegeid.Value;
                                    privileges[1].Depth = PrivilegeDepth.Local;
                                    break;
                              case "prvReadIncident":
                                    privileges[2] = new RolePrivilege();
                                    privileges[2].PrivilegeId = currentPrivilege.privilegeid.Value;
                                    privileges[2].Depth = PrivilegeDepth.Local;
                                    break;
                              case "prvReadActivity":
                                    privileges[3] = new RolePrivilege();
                                    privileges[3].PrivilegeId = currentPrivilege.privilegeid.Value;
                                    privileges[3].Depth = PrivilegeDepth.Local;
                                    break;
                              case "prvCreateIncident":
                                    privileges[4] = new RolePrivilege();
                                    privileges[4].PrivilegeId = currentPrivilege.privilegeid.Value;
                                    privileges[4].Depth = PrivilegeDepth.Local;
                                    break;
                              case "prvCreateActivity":
                                    privileges[5] = new RolePrivilege();
                                    privileges[5].PrivilegeId = currentPrivilege.privilegeid.Value;
                                    privileges[5].Depth = PrivilegeDepth.Local;
                                    break;
                              case "prvWriteIncident":
                                    privileges[6] = new RolePrivilege();
                                    privileges[6].PrivilegeId = currentPrivilege.privilegeid.Value;
                                    privileges[6].Depth = PrivilegeDepth.Local;
                                    break;
                              case "prvWriteActivity":
                                    privileges[7] = new RolePrivilege();
                                    privileges[7].PrivilegeId = currentPrivilege.privilegeid.Value;
                                    privileges[7].Depth = PrivilegeDepth.Local;
                                    break;
                              case "prvAppendToIncident":
                                    privileges[8] = new RolePrivilege();
                                    privileges[8].PrivilegeId = currentPrivilege.privilegeid.Value;
                                    privileges[8].Depth = PrivilegeDepth.Local;
                                    break;
                              case "prvAppendToActivity":
                                    privileges[9] = new RolePrivilege();
                                    privileges[9].PrivilegeId = currentPrivilege.privilegeid.Value;
                                    privileges[9].Depth = PrivilegeDepth.Local;
                                    break;
                              case "prvAppendAccount":
                                    privileges[10] = new RolePrivilege();
                                    privileges[10].PrivilegeId = currentPrivilege.privilegeid.Value;
                                    privileges[10].Depth = PrivilegeDepth.Local;
                                    break;
                              case "prvAppendContact":
                                    privileges[11] = new RolePrivilege();
                                    privileges[11].PrivilegeId = currentPrivilege.privilegeid.Value;
                                    privileges[11].Depth = PrivilegeDepth.Local;
                                    break;
                              default:
                                    break;
                        }
                  }
                  #endregion

                  #region Grant Role Permissions
                  // Create the request object.
                  AddPrivilegesRoleRequest add = new AddPrivilegesRoleRequest();

                  // Set the properties of the request object.
                  add.RoleId = roleId;
                  add.Privileges = privileges;

                  // Execute the request.
                  AddPrivilegesRoleResponse added = (AddPrivilegesRoleResponse)service.Execute(add);
                  #endregion

                  #region check success


                  try
                  {
                  // Be aware that using AllColumns may adversely affect
                  // performance and cause unwanted cascading in subsequent 
                  // updates. A best practice is to retrieve the least amount of 
                  // data required.
                        role roleCheck = (role)service.Retrieve(EntityName.role.ToString(), roleId, new AllColumns());

                        if (roleCheck.roleid.Value == roleId)
                        {
                              RetrieveRolePrivilegesRoleRequest retrievePrivileges = new RetrieveRolePrivilegesRoleRequest();
                              retrievePrivileges.RoleId = roleId;

                              RetrieveRolePrivilegesRoleResponse retrievedPrivileges = (RetrieveRolePrivilegesRoleResponse)service.Execute(retrievePrivileges);

                              // For this test, we will see whether the resulting role has the same number of privileges.
                              // We could loop through the privileges and compare them all, but, because the platform
                              // could return them in a different order, for this test a length check is sufficient.
                              const int DEFAULT_PRIV_COUNT = 12;

                              success = retrievedPrivileges.RolePrivileges.Length == privileges.Length + DEFAULT_PRIV_COUNT;
                        }
                  }
                  finally
                  {

                  #endregion

                        #region Remove Data Required for this Sample

                        service.Delete(EntityName.role.ToString(), roleId);

                        #endregion
                  }

                  return success;
            }
      }
}
[Visual Basic .NET]
Imports System

Imports CrmSdk
Imports Microsoft.Crm.Sdk.Utility

Namespace Microsoft.Crm.Sdk.HowTo

      Public Class CustomRolesHowTo

            Sub Main()

                  ' TODO: Change the server URL and Organization to match your CRM Server and CRM Organization
                  CustomRolesHowTo.Run("http://localhost:5555", "CRM_SDK")

            End Sub

            Public Shared Function Run(ByVal crmServerUrl As String, ByVal orgName As String) As Boolean
                  
                  '---- Setup Data Required for this Sample ------------------------------
                  Dim success As Boolean = False
                  '-----------------------------------------------------------------------

                  ' Set up the CRM Service.
                  Dim service As CrmService =  CrmServiceUtility.GetCrmService(crmServerUrl,orgName)
                  Dim userRequest As New WhoAmIRequest()
                  Dim user As WhoAmIResponse = CType(service.Execute(userRequest), WhoAmIResponse)

                  '---- Create the Role --------------------------------------------------
                  ' Create the role object.
                  Dim role As New role()

                  ' Set the property of the role.
                  role.name = "Call Center Representative"
                  role.businessunitid = New Lookup()
                  role.businessunitid.type = EntityName.businessunit.ToString()
                  role.businessunitid.Value = user.BusinessUnitId

                  ' Create the role.
                  Dim roleId As Guid = service.Create(role)
                  '-----------------------------------------------------------------------

                  '---- Retrieve the Permission Set --------------------------------------
                  ' Create the request object.
                  Dim retrieve As New RetrievePrivilegeSetRequest()

                  ' Execute the request.
                  Dim retrieved As RetrievePrivilegeSetResponse = CType(service.Execute(retrieve), RetrievePrivilegeSetResponse)

                  ' Build the permission set. The role receives 12 permissions.
                  Dim privileges(11) As RolePrivilege 
                  ' Variable declared outside the loop.
                  Dim currentPrivilege As privilege

                  ' Iterate through all the returned permissions and get the GUID of the permissions being granted.
                  Dim i As Integer
                  For i = 0 To retrieved.BusinessEntityCollection.BusinessEntities.Length - 1
                        currentPrivilege = CType(retrieved.BusinessEntityCollection.BusinessEntities(i), privilege)

                        ' The GUID of currentPrivilege is added to the list if it is one of the permissions being given to the role.
                        Select Case currentPrivilege.name
                              Case "prvReadContact"
                                    ' If the current privilege is prvReadContactPrivilege, a new RolePrivilege object is added to the privilege set.
                                    privileges(0) = New RolePrivilege()
                                    ' The PrivilegeId of the RolePrivilege is set to the privilegeid of the currentPrivilege. 
                                    privileges(0).PrivilegeId = currentPrivilege.privilegeid.Value
                                    ' The RolePrivilege's Depth is set to the access depth of the role that is being granted for this privilege.
                                    privileges(0).Depth = PrivilegeDepth.Local
                              Case "prvReadAccount"
                                    privileges(1) = New RolePrivilege()
                                    privileges(1).PrivilegeId = currentPrivilege.privilegeid.Value
                                    privileges(1).Depth = PrivilegeDepth.Local
                              Case "prvReadIncident"
                                    privileges(2) = New RolePrivilege()
                                    privileges(2).PrivilegeId = currentPrivilege.privilegeid.Value
                                    privileges(2).Depth = PrivilegeDepth.Local
                              Case "prvReadActivity"
                                    privileges(3) = New RolePrivilege()
                                    privileges(3).PrivilegeId = currentPrivilege.privilegeid.Value
                                    privileges(3).Depth = PrivilegeDepth.Local
                              Case "prvCreateIncident"
                                    privileges(4) = New RolePrivilege()
                                    privileges(4).PrivilegeId = currentPrivilege.privilegeid.Value
                                    privileges(4).Depth = PrivilegeDepth.Local
                              Case "prvCreateActivity"
                                    privileges(5) = New RolePrivilege()
                                    privileges(5).PrivilegeId = currentPrivilege.privilegeid.Value
                                    privileges(5).Depth = PrivilegeDepth.Local
                              Case "prvWriteIncident"
                                    privileges(6) = New RolePrivilege()
                                    privileges(6).PrivilegeId = currentPrivilege.privilegeid.Value
                                    privileges(6).Depth = PrivilegeDepth.Local
                              Case "prvWriteActivity"
                                    privileges(7) = New RolePrivilege()
                                    privileges(7).PrivilegeId = currentPrivilege.privilegeid.Value
                                    privileges(7).Depth = PrivilegeDepth.Local
                              Case "prvAppendToIncident"
                                    privileges(8) = New RolePrivilege()
                                    privileges(8).PrivilegeId = currentPrivilege.privilegeid.Value
                                    privileges(8).Depth = PrivilegeDepth.Local
                              Case "prvAppendToActivity"
                                    privileges(9) = New RolePrivilege()
                                    privileges(9).PrivilegeId = currentPrivilege.privilegeid.Value
                                    privileges(9).Depth = PrivilegeDepth.Local
                              Case "prvAppendAccount"
                                    privileges(10) = New RolePrivilege()
                                    privileges(10).PrivilegeId = currentPrivilege.privilegeid.Value
                                    privileges(10).Depth = PrivilegeDepth.Local
                              Case "prvAppendContact"
                                    privileges(11) = New RolePrivilege()
                                    privileges(11).PrivilegeId = currentPrivilege.privilegeid.Value
                                    privileges(11).Depth = PrivilegeDepth.Local
                              Case Else
                        End Select
                  Next i
                  '-----------------------------------------------------------------------

                  '---- Grant Role Permissions -------------------------------------------
                  ' Create the request object.
                  Dim add As New AddPrivilegesRoleRequest()

                  ' Set the properties of the request object.
                  add.RoleId = roleId
                  add.Privileges = privileges

                  ' Execute the request.
                  Dim added As AddPrivilegesRoleResponse = CType(service.Execute(add), AddPrivilegesRoleResponse)
                  '-----------------------------------------------------------------------

                  '---- check success ----------------------------------------------------
                  ' Be aware that using AllColumns may adversely affect 
                  ' performance and cause unwanted cascading in subsequent 
                  ' updates.  A best practice is to retrieve the least amount of 
                  ' data required.
                  Dim roleCheck As role = CType(service.Retrieve(EntityName.role.ToString(), roleId, New AllColumns()), role)

                  If roleCheck.roleid.Value.Equals(roleId) Then

                        Dim retrievePrivileges As RetrieveRolePrivilegesRoleRequest = new RetrieveRolePrivilegesRoleRequest()
                        retrievePrivileges.RoleId = roleId

                        Dim retrievedPrivileges As RetrieveRolePrivilegesRoleResponse = CType(service.Execute (retrievePrivileges), RetrieveRolePrivilegesRoleResponse)

                        ' For this test, we will see whether the resulting role has the same number of privileges.
                        ' We could loop through the privileges and compare them all, but, because the platform
                        ' could return them in a different order, for this test a length check is sufficient.
                        const DEFAULT_PRIV_COUNT as Integer = 12
                        success = retrievedPrivileges.RolePrivileges.Length.Equals(privileges.Length + DEFAULT_PRIV_COUNT)

                  End If

                  '-----------------------------------------------------------------------

                  '---- Remove Data Required for this Sample -----------------------------
                  service.Delete(EntityName.role.ToString(), roleId)
                  '-----------------------------------------------------------------------

                  Return success
            End Function 'Run
      End Class 'CustomRolesHowTo
End Namespace 'Microsoft.Crm.Sdk.HowTo

See Also

Reference


© 2010 Microsoft Corporation. All rights reserved.


Show:
© 2016 Microsoft