CB Replicator - User Manualtest.connecting-software.com/wp-content/uploads/2015/08/CB-Repli… ·...

All rights reserved. No part of the document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the written permission of Connecting Software s.r.o. & Co. KG. Company or product names mentioned in this document may be trademarks or registered trademarks of their respective companies.

Connecting Software CB Dynamics CRM privileges to SharePoint

permissions replicator User Manual

Summary

This document describes the installation and the configuration of the CB Dynamics CRM privileges to SharePoint permissions replicator.

Supported versions:

Dynamics CRM: 2011, 2013, 2015, Online

SharePoint: 2010, 2013, Online

Product version: 2.5.1.0

Document History

Version Date Author Changes

1.0 2015-04-13 JKT Review

1.1 2015-05-05 TOL Added SharePoint late group creation

1.2 2015-05-13 TOL Added Group caching

1.3 2015-05-22 TOL Added omit empty groups

1.4 2015-05-27 TOL Added security role filter

1.5 2015-06-03 TOL Permission mapping per entity

1.6 2015-07-06 TOL Changed default permission mapping

1.7 2015-07-16 TOL Added licensing description

2.0 2015-07-31 MBE Design adaption

CB Dynamics CRM privileges to SharePoint permissions replicator Connecting Software

2015-07-31 /43

Table of Contents

1 General ............................................................................................................. 4 2 How does it work ................................................................................................ 4 3 System Requirements ......................................................................................... 5 4 Installation......................................................................................................... 6

4.1 CRM Solution installation ...............................................................................10 5 General configuration ........................................................................................ 11

5.1 Configuration possibilities ..............................................................................11 5.1.1 CB Replicator Controller ...........................................................................11

5.2 Global settings (optional) ..............................................................................11 6 Multitenancy .................................................................................................... 12

6.1 Multitenancy concept ....................................................................................12 6.2 UI Tenant configuration.................................................................................12

6.2.1 Create/delete tenant ...............................................................................13 6.2.2 Connecting to specific tenant....................................................................13

7 Single tenant configuration ................................................................................ 14 7.1 Initial setup .................................................................................................14 7.2 Options .......................................................................................................19

7.2.1 General .................................................................................................19 7.2.2 Connections ...........................................................................................20 7.2.3 Notifications ...........................................................................................22

7.3 Configuration attributes ................................................................................23 7.4 SharePoint(s) configuration ...........................................................................26

7.4.1 User mapping (optional) ..........................................................................28 7.4.2 Permission mapping (optional) .................................................................30 7.4.3 URL Aliases (optional) .............................................................................33

7.5 Entity filter (optional) ...................................................................................34 7.6 Security role filter (optional) ..........................................................................35

8 Running CB Replicator ....................................................................................... 38 8.1 Force full iteration ........................................................................................39 8.2 Clear local database .....................................................................................39

9 Licensing ......................................................................................................... 40 10 Troubleshooting .............................................................................................. 41

10.1 Log file ......................................................................................................41 10.2 CB Replicator Controller logs ........................................................................41


2015-07-31 /43

10.2.1 Real-time logs ......................................................................................41 10.2.2 Historical logs .......................................................................................42 10.2.3 Exporting logs ......................................................................................43

11 Known issues.................................................................................................. 43 11.1 Custom position hierarchy – user without Read privilege .................................43


2015-07-31 /43

1 General

The out-of-the box integration between Dynamics CRM and SharePoint as document storage has a lot of advantages but also some disadvantages. The most significant disadvantage is absence of permissions integration. Each one of the systems has its own security model and there is no out-of-the-box integration between them. This undesirable behaviour causes serious security issues in many companies.

The CB Dynamics CRM privileges to SharePoint permissions replicator product solves this problem easily (sample video).

Key features

Replicate CRM permissions as item (folder) level permissions in SharePoint document libraries

Event-based service Configurable user mapping Configurable permission mapping Multitenancy Multi SharePoint support

2 How does it work The CB Dynamics CRM privileges to SharePoint permissions replicator consists of 2 basic components:

CB Dynamics CRM privileges to SharePoint permissions replicator service CRM Solution – CB Replicator

CRM Solution contains plugin that registers all the steps that can influence permissions in Dynamics CRM. When one of these steps occurs the plugin will notify CB Replicator service, the service will ensure permission write into SharePoint. This ensures that the rights in CRM will be exactly replicated to SharePoint folder(s). There are several ways to change permissions in CRM and this solution covers all of them:

User Security roles Sharing Teams, access teams and access team templates Business unit Hierachy security – manager and position (CRM 2015 and Online)


2015-07-31 /43

WARNING: This service will modify the item level security for folders in the SharePoint document libraries. We are not responsible for recovering permissions to initial state. Please test the service in your test environment first and create backups before implementing to the production environment.

3 System Requirements

.NET Framework (4.5) single windows machine (at least Windows 7 Service Pack 1, Windows 8, Windows

Server 2008 R2 or later) with reachable CRM and SharePoint single CRM user – System Administrator (login and password) single SharePoint user – Site collection administrator (login and password) properly configured document management between CRM and SharePoint


2015-07-31 /43

4 Installation

Basically the solution consist of following components:

1) CB Dynamics CRM privileges to SharePoint permissions replicator service It is a core service that contains all the logic for replication process. 2) CB Replicator Controller

It is a graphical user interface to configure CB Replicator and controls replication process

3) Connect Bridge Server with CRM and SharePoint connector

It is a platform from Connecting Software that provides connectivity to Dynamics CRM and SharePoint.

Required CRM connector version: 2.1.2 Required SharePoint connector version: 1.0.6.5

4) ODBC Driver

Connect Bridge ODBC Driver that provides connectivity between Connect Bridge server and CB Replicator.

There are various scenarios how to install / deploy components. This manual will describe 2 most frequently used scenario:

a) Single package deployment (Connect Bridge server included) b) Connect to existing Connect Bridge server instance

To start the installation, run CB Replicator setup.exe from delivered package (administrator privileges will be required during installation).


2015-07-31 /43

First step is the installer introduction screen. Click Next to continue.

The Install Now will install all the features – will install as single package.

Clicking on Custom you have possibility to choose which components will be installed.

If you want to make full installation (single package) leave all the items checked.


2015-07-31 /43

If you have an existing Connect Bridge Server instance in the same machine you can uncheck whole Connect Bridge node. If you have an existing Connect Bridge Server instance on different machine you can uncheck only Server Lite (in case that Connect Bridge ODBC driver is not installed yet).

In next dialog you can specify whether you want to create shortcuts for CB Replicator Controller.


2015-07-31 /43

Following dialog allows you to specify target folder of CB Replicator installation.

Click on Install and the file copying will begin.

When installation is done, by clicking on Close you can close the installer. Clicking at Run CB Replicator will start CB Replicator Controller tool. You can view also release notes by clicking at View Readme File.


2015-07-31 /43

CB Dynamics CRM privileges to SharePoint permissions replicator service is started by default in idle state (not processing data), you must configure your service first.

4.1 CRM Solution installation One of the component is CB Replicator is small Dynamics CRM Solution called also CB Replicator. The solution will be automatically installed and published on first run so there are no additional steps required.

The solution is managed so it can be fully uninstalled at any time.

2015-07-31 /43

5 General configuration

5.1 Configuration possibilities You have 2 possibilities how to configure CB Dynamics CRM privileges to SharePoint permissions replicator:

Use CB Replicator Controller Edit configuration file directly

The full configuration is provided only by XML configuration file CB Replicator.exe.config in service install directory (by default C:\Program Files\Connecting Software\CB replicator\).

Note: For editing configuration file you may be requested to elevate administrator permissions.

Note: Every manual change in this configuration file requires to restart the service in order to apply changes

5.1.1 CB Replicator Controller CB Replicator controller is UI tool that provides you comfortable way how to configure and monitor status of CB Dynamics CRM privileges to SharePoint permissions replicator service. CB Replicator Controller can be started from Start menu in your Windows or immediately after installation.

Note: To use CB Replicator Controller tool the CB Dynamics CRM privileges to SharePoint permissions replicator service must be running!

5.2 Global settings (optional) Global settings are available only in configuration file. Usually there is no need to change this configuration.

The top level configuration starts at <mainConfiguration/> element.

<mainConfiguration UseCustomAdminConnection="false" ConnectionString_Admin="Driver={Media Gateway ODBC Driver};IMPL=CORBA;HOST=localhost';PORT='8087';ACC='ACCOUNT_ADMINISTRATION';UID='administrator';PWD='1234'" IsBundle="true" ControllerServiceAddress="net.tcp://localhost:32157/CBReplicator/{1}"> > <Tenants>  </Tenants> </mainConfiguration>


2015-07-31 /43

Complete list of mainConfiguration element attributes are described in following table:

Attribute name Values Description Required Default value

UseCustomAdminConnection

boolean If set to true the custom ODBC connection string will be used for Administration of CB (see following property – ConnectingString_Admin)

No false

ConnectionString_Admin string ODBC Connectionstring pointing to Connect Bridge server and configured pointing to CB administration account.

Note: Valid only for custom connection

No

ControllerServiceAddress int WCF endpoint that CB Replicator Controller connects to. Each tenant needs to have its own endpoint address. The placeholder {1} will be automatically replaced with tenant ID to ensure uniqueness.

No

(advanced)

net.tcp://localhost:32157/CBReplicator/ControllerService/{1}

IsBundle boolean Specifies whether CB Replicator was installed with embedeed Connect Bridge server

No (internal)

true

6 Multitenancy

6.1 Multitenancy concept In single CB Replicator instance you can run several tenants. The tenant is single CRM integrated with at least one SharePoint or SharePoint site collection. Tenants are independed from each other and has its own configuration.

After installation there is one predefined tenant called “Default”.

Note: If you do not plan to have multiple tenants you can skip this chapter.

6.2 UI Tenant configuration Tenants can be managed by CB Replicator Controller. The CB Replicator Controller can be connected only to single tenant at once. However you can open multiple instances of CB Replicator Controller in parallel and connect to different tenant.


2015-07-31 /43

6.2.1 Create/delete tenant There are 2 possibilities how to create new tenant by user interface:

- Go to menu Tenant -> New tenant - Go to menu Tenant -> Open tenant and click on Add tenant (green plus icon)

After tenant is created you need to make necessary configuration.

The tenant can be deleted from tenant selector (Tenant -> Open tenant) by clicking at Delete tenant (red X icon).

6.2.2 Connecting to specific tenant If there is only single tenant defined the CB Replicator Controller will connects automatically to this tenant.

If there is zero or multiple tenants defined the tenants selector will be shown in order to choose concreate tenant that you want connect. This selector can be shown explicitly by clicking at Tenant -> Open tenant.

In user interface you can identify concrete tenant by:

- prefix at window title - left bottom toolbar icon with tenant name

To disconnect from current tenant go to menu Tenant -> Close tenant.


2015-07-31 /43

7 Single tenant configuration

Before you start processing with CB Dynamics CRM privileges to SharePoint permissions replicator you have to make appropriate configuration. This section will describes configuration of concrete single tenant.

7.1 Initial setup When you install CB Replicator for the first time the configuration wizard will be opened. This wizard will automatically connect to Default tenant and will guide you through initial setup process.

Note: This wizard is only valid for single package deployment


2015-07-31 /43

Clicking next the Request license screen will be shown.

Clicking on Next will generate license request file (*.req extension). You need to send this file to [email protected]. If you have preconfigured email client a new email message with attached request will be created automatically. If not you need to store file and send manually.

Afterwards our team will generate license for you (*.lic extension). Please navigate to file and click on Next. The license will be activated.


2015-07-31 /43

After activating a license you need to configure connection for target systems: Dynamics CRM and SharePoint. Please enter valid server and credentials for each of the systems.

Note: If your connections are failing please try to put URL into your browser and try to login with that credential to make sure that you have correct URL and credentials!

For Dynamics CRM you need single user, let’s call him “service user”. It needs to be system administrator in your Dynamics CRM. To configure CRM you need to pass following parameters:

- Server – address of your Dynamics CRM instance (e.g. http://contosocrm:5555/sampleorg/ )

- User – username (e.g. smith, contoso\smith, [email protected] ...) - Password – password for user


2015-07-31 /43

Similar for SharePoint you need single user that is site collection administrator, let’s call him “service user”. To configure SharePoint you need to pass following parameters:

- Server – address of your SharePoint site (e.g. http://contososp:5555/documentsitecollection/ )

- User – username (e.g. smith, contoso\smith, [email protected] ..) - Password – password for user


2015-07-31 /43

After successful configuration using wizard your CB Replicator is configured and ready to run.

Selecting checkbox at last page of wizard and click Finish will starts replication process immediately.

Another way how to start CB Replicator is to close the wizard and press Start button.


2015-07-31 /43

7.2 Options Frequently used configuration settings are available via user interface. Go to Tools -> Options.

7.2.1 General

In General tab you can edit basic configuration.

- Tenant name is custom name for current tenant. - Tenant description is custom description for current tenant - Auto start specifies whether synchronization process will be started automatically

after CB Replicator service is started - Automatically delete events specifies whether event will be automatically

deleted from CRM queue after it has been processed - User mapping auto refresh specifies whether service will automatically match

user in specified intervals - User mapping refresh interval is value in seconds specifying time interval

between automated users matching - Late SharePoint group creation specifies whether SharePoint groups will be created

immediately (unchecked) or only when they are really needed (checked). The checked option has better performance (recommended).


2015-07-31 /43

- SharePoint group local caching. If checked the SharePoint groups and their memberships will be cached in local database. This will improve speed of Full iteration. It is recommended to keep this setting (checked).

- Omit empty SharePoint groups. Only SharePoint groups containing users will be created. Empty will be skipped or deleted.

- Diff permission write mode. If checked only changes (add/remove) to permissions will be applied. The whole permission set for folder will not be ensured. The checked option has better performance (recommended) but will not overwrite manual modification of SharePoint groups.

7.2.2 Connections In Connections -> CRM / SharePoint you can configure connection to target system. You can choose if you enter credentials directly (Basic tab, available only for single package deployment) or use existing connection string pointing to existing Connect Bridge server (Advanced tab).

To enter credential directly select CRM or SharePoint Basic tab and fill necessary credentials.

For configuring connection string directly select Advanced tab. Check “Use direct access ...” flag.

Note: When “Use direct access ...” is checked then Basic tab with credentials is ignored.


2015-07-31 /43

The similar settings are available also for SharePoint however you have possibility to add more SharePoints or SharePoint document locations for single CRM (within single tenant).

New connection will create additional connection to SharePoint or SharePoint site collection. You need to pass some name for new connection.


2015-07-31 /43

Note: Please be careful to do not create more connection pointing to the same SharePoint site collection.

Edit name will show dialog to change name of existing SharePoint connection.

Delete connection will remove existing SharePoint connection. It will not delete any existing data or permissions from SharePoint. It will just prevent CB Replicator from processing SharePoint document locations pointing to deleted SharePoint connection.

7.2.3 Notifications Notifications part provide configuration if way how Dynamics CRM will notify CB Replicator about changes in its security mode. Basically you can have 3 possibilities:

- Pooling only - Pooling + notifications - Direct notifications

7.2.3.a Pooling only With this setup there is no communication flow triggered by CRM. There is only event queue (cs_cbreplicatorevent entity) in Dynamics CRM and our CRM plugin only enqueues new events. The CB Replicator is periodically pooling for new events.

In orger to configure this setup you need to leave Enable notifications flag unchecked.

7.2.3.b Pooling + notifications This is combination of previous approach and WCF notifications. Basically there is still above mentioned queue of events in CRM that is periodically pooled. However there is also a WCF channel and CRM can notify CB Replicator about existence of new even in real-time. Then CB Replicator will read this event from queue. This ensure that new event processing will be started immediately.

In order to configure this setup you need to check Enable notifications flag but leave Direct notifications flag unchecked.


2015-07-31 /43

7.2.3.c Direct notifications This setups relies only on WCF notifications. The events are not persisted in Dynamics CRM queue but they are send to CB Replicator directly. This setup will ensure best performance.

In order to configure this setup you need to check Enable notifications and Direct notifications flags.

7.3 Configuration attributes The full configuration is provided by XML configuration file CB Replicator.exe.config in service install directory (by default C:\Program Files\Connecting Software\CB replicator\).

Note: For editing configuration file you may be requested to elevate administrator permissions.

Note: Every manual change in this configuration file requires to restart the service in order to apply changes

Main configuration element for tenant is called <Tenant/> and must be placed inside <Tenants/> element.


2015-07-31 /43

Sample Tenant element could look like this: <Tenant InstanceID="00000000-0000-0000-0000-000000000001" Name="Default" Description="Default tenant description" AutoStart="true" NotificationsEnabled="false" NotificationAddress="" PoolNotificationInterval="30" > <SharePoint> <SharePoint Name="Default" Key="1"/> </SharePoint> </Tenant>

Complete list of Tenant element attributes are described in following table:

Attribute name Values Description Required

Default value

InstanceID Guid (string)

Unique identifier of tenant Yes

Name String Custom tenant name Yes

Description String Custom tenant description No

UseCustomCRMConnection

boolean If set to true the custom ODBC connection string will be used for CRM (see following property – ConnectingString_CRM)

No false

ConnectionString_CRM string ODBC Connectionstring pointing to Connect Bridge server and configured CRM account.


No

AutoStart boolean Specifies whether synchronization process will be started automatically after CB Replicator service is started. IT should be set to true in production.

No false

NotificationsEnabled boolean Specifies whether notifications about events from Dynamics CRM will be send to CB Replicator service via WCF

No false

UserMapping_AutoRefresh

boolean Whether service will automatically match user in specified intervals (UserMapping_RefreshInterval).

No true


2015-07-31 /43

If false the users will be matched only at service startup.

UserMapping_RefreshInterval

int Value in seconds specifying time interval between automated users matching. Valid only if UserMapping_AutoRefresh = “true”

E.g. used in scenario when new users will be added into CRM and SharePoint.

No 120s

LateGroupCreateEnabled boolean Specifies whether SharePoint groups will be created immediatelly (True) or only when they are really needed (False). The True option has better performance (recommended).

No True

GroupCaching boolean If True the SharePoint groups and their memberships will be cached in local database. This will improve speed of Full iteration

No True

OmitEmptyGroups boolean Only SharePoint groups containing users will be created. Empty will be skipped or deleted.

No True

DiffPermissionWriteMode boolean If True only changes (add/remove) to permissions will be applied. The whole permission set for folder will not be ensured. The True option has better performance (recommended) but will not overwrite manual modification of SharePoint groups.

No True

DirectNotifications boolean Notification without temporary storing events in Dynamics CRM. The CRM plugin will only call CB Replicator WCF service.

No false

NotificationsAddress int Endpoint address of CB Replicator service for Dynamics CRM notifications

Valid only if NotificationsEnabled = “true”

No http://{hostname}:19527/CBReplicator/NotificationService/{InstanceId}

PoolNotificationInterval int Interval for iterative read of notifications from Dynamics CRM. It specified how often will service check for new

No 120s

2015-07-31 /43

events. It is important mainly when NotificationsEnabled = false

AutoEventDelete boolean Specifies whether event will be automatically deleted from CRM after it has been processed

No true

FullIterationAfterFailure boolean Specifies whether service will perform full iteration when some record fails.

Note: not recommended because it can cause service to always stops at same broken record!

No false

FailureRetryAttempts int Number of additional attempts to perform write operation into SharePoint when it fails. E.g. when network connection is temporary unavailable

No false

ShowWizard boolean Internal configuration property. It is set to true after installation. It is sign for UI Controller to pop-up configuration wizard when started.

No (internal)

false

DatabaseLoggingEnabled boolean Specifies whether logging to local database is enabled

No true

ExportLogPeriod uint Value specified how many days of historical logs will be exported.

No 7

Inside <Tenant/> element you can customize SharePoints configuration <SharePoint/> and <EntityConfiguration/> elements. <Tenant>  <SharePoint>  </SharePoint> <EntityConfiguration>  </EntityConfiguration> </Tenant>

7.4 SharePoint(s) configuration Sample SharePoints configuration element looks like this

2015-07-31 /43

Inside <SharePoint/> element you can customize user mapping <UserMapping/>, permission mapping <PermissionMapping/> and URL aliases <Aliases/> elements: <SharePoints> <SharePoint Name="Default" Key="1"> <UserMapping>  </UserMapping> <PermissionMapping>  </PermissionMapping> <Aliases>  </Aliases> </SharePoint>  </SharePoints>

Complete list of SharePoint element attributes are described in following table:


Key uint Unique key of SharePoint connection

Yes

Name string Custom name for current SharePoint connection

Yes

UseCustomSharePointConnection

boolean

If set to true the custom ODBC connection string will be used for SharePoint (see following property – ConnectingString_SharePoint)

No false

ConnectionString_SharePoint string ODBC Connectionstring pointing to Connect Bridge server and configured SharePoint account.


No

IsFallback boolean

If true all unrecognized SharePoint URLs will be executed using this connection

No false


2015-07-31 /43

7.4.1 User mapping (optional) The service provides out of the box automated algorithm to match (map) between users in Dynamics CRM and SharePoint. Additionally you can configure custom user mapping.

Note: each configured SharePoint instance has its dedicated user mapping

Go to View -> User mapping.

When you open user mapping when service is stopped a preview of user mapping will be loaded.

The Mapped column identifies whether CRM user has belonging pair user in SharePoint. When user is not mapped clicking on Add will create custom mapping. In dialog you need to select target SharePoint user to be mapped.


2015-07-31 /43

Edit allows you to change existing configuration.

Remove will delete selected custom mapping.

Refresh will reload preview of user mapping with actual user list retrieved from target systems.

The user mapping can be also configured directly in configuration file also. In <UserMapping/> section you can specify one or more user pairs that will be added to the automated mapping or will replace automated mapping. To configure this mapping you have to add UserPair element.


2015-07-31 /43

<UserMapping Mode="APPEND"> <UserPairs> <UserPair

CRM_ID="2f164f25-d2d9-e311-93f0-00155dc10f2f" SharePoint_ID="56">

</UserPair> </UserPairs> </UserMapping>

UserMapping element attributes are described in the following table:

Attribute name

Values

Description Required Default value

Mode string

Specify whether the custom configuration will be appended to automated matching or fully replace automated matching

Accepted values are: APPEND, REPLACE

No APPEND

UserPairs is a collection of UserPair elements. UserPair element represent single mapping between CRM and SharePoint user. UserPair element collection attributes are described in following table:

Attribute name

Values Description Required Default value

CRM_ID guid CRM user’s ID

Note: Available users in Dynamics CRM can be listed via Connect Bridge calling SELECT * FROM [systemuser] in Query Analyzer.

Yes

SharePoint_ID int SharePoint user’s ID

Note: Available users in SharePoint can be listed via Connect Bridge calling EXEC SP_SELECT_USERS in Query Analyzer.

Yes

Name string User name (not used for matching) No

Email string Email address (not used for matching) No

7.4.2 Permission mapping (optional) Dynamics CRM and SharePoint security model differs. The mapping between them is required. The CB Replicator automatically creates dedicated permission levels in target SharePoint. The application has preconfigured mapping between Dynamics CRM and SharePoint that should be suitable for most deployments:


2015-07-31 /43

CRM access right SharePoint permission level SharePoint permissions

ReadAccess cbreplicator_crm_ReadAccess ViewListItems, OpenItems, ViewVersions, ViewFormPages, Open, BrowseDirectories, BrowseUserInfo, UseClientIntegration, UseRemoteAPIs, CreateAlerts

WriteAccess cbreplicator_crm_WriteAccess AddListItems, EditListItems, DeleteListItems, DeleteVersions

However the CB Replicator provides possibility to modify predefined permission mapping. The permission mapping can be configured also per entity.

Note: each configured SharePoint instance has its dedicated permission mapping

Go to View -> Permission mapping.

When you open permission mapping when service is stopped a current mapping will be loaded.


2015-07-31 /43

The Custom column identifies whether displayed permission mapping is default or custom (user defined). Entity filter restricts entity that are affected by mapping – the global mapping (--) for specific CRM access right is overridden in this case. CRM Access Right and SharePoint Privilege Level Name (SharePoint_RoleID) columns are explained below.

Mode specifies whether the custom mapping will be appended to predefined mapping (APPEND) or fully replace predefined mapping (REPLACE).

To create new custom mapping click at Add button. Choose the appropriate CRM access right, SharePoint privilege and possibly Entity filter. Click at Save.

To modify existing custom mapping click at Edit.

To remove existing custom mapping click at Delete.

Note: Edit and delete operations are available only for custom mapping.

To reload current mapping you can use Refresh button.

If you want to modify predefined mapping you can use PermissionMapping configuration element.

<PermissionMapping Mode="REPLACE"> <Permissions> <add

CRM_AccessRight="CreateAccess" SharePoint_RoleID="1073741827">

</add> </Permissions> </PermissionMapping>


2015-07-31 /43

PermissionMapping element attribute is described in following table:


Mode string

Specify whether the custom mapping will be appended to predefined mapping or fully replace predefined mapping. Accepted values are: APPEND, REPLACE

No APPEND

Permissions is a collection of PermissionPair elements. PermissionPair elements represent single mapping between CRM access right and SharePoint security role (permission level). PermissionPair element attributes are described in following table:


CRM_AccessRight

string CRM access right name. Accepted values are: AppendAccess, AppendToAccess, AssignAccess, CreateAccess, DeleteAccess, ReadAccess ,ShareAccess ,WriteAccess

Yes

SharePoint_RoleID

int SharePoint security role ID (permission level).

Note: You can list security roles of your SharePoint via Connect Bridge calling EXEC SP_SELECT_SECURITY_ROLES in Query Analyzer.

Yes

EntityName string Logical name of CRM entity. This attribute is used when you want to override global mapping of specific CRM access right for specific CRM entity.

No

Name string Mapping name (optional) No

7.4.3 URL Aliases (optional) CB Replicator has automatic URL resolver that decides based on sharepointdocumentlibrary URL to which SharePoint needs to be permission written. However there is a possibility that SharePoint can be accessible via various alternative hostnames (e.g. sp-prod, sp-prod.contoso.com, 192.168.1.199 ..).

CB Replicator provides feature called aliases. To each SharePoint you can configure unlimited number of aliases. These aliases can be useful when your CRM sharepointdocumentlocation records are pointing to same SharePoint site collection with different hostnames.


2015-07-31 /43

The sample configuration can look like:

<Aliases> <Alias Hostname="sp-prod.contoso.com"/> <Alias Hostname="192.168.1.199"/> </Aliases>

7.5 Entity filter (optional)

The CB Replicator gives you possibility to select only specific Dynamics CRM entities that will be replicated.

Go to Tools -> Options -> Entity filter.

If Process all entities is checked the all CRM entities will be automatically replicated.

If Process all entities is unchecked only checked entities in list will be processed.

Note: Only entities with enabled Document management are listed.

If you want to modify entity filter in configuration file you can use EntityConfiguration element.


2015-07-31 /43

<EntityConfiguration AllEntitiesEnabled="false"> <EnabledEntities> <add EntityName="account"/> <add EntityName="contact"/> </EnabledEntities> </EntityConfiguration>

EntityConfiguration element attribute is described in following table:


AllEntitiesEnabled boolean

If true all the CRM entities will be automatically processed. If false only entities defined in EnabledEntities collection will be processed.

Note: If true the EnabledEntities collection will be ignored

No true

Entity elements represent single CRM entity (logical entity name). EnabledEntities represents collection of Entity records. Entity element attributes are described in following table:


EntityName string Name of CRM entity. It must be logical entity name. The attribute is case insensitive.

Yes

7.6 Security role filter (optional)

The CB Replicator gives you possibility to filter Dynamics CRM security roles that will be replicated.

Go to Tools -> Options -> Security role filter.


2015-07-31 /43

If Enable role filter is unchecked all the Dynamics CRM security roles will be automatically replicated.

If Enable role filter is checked the behaviour depends on Filter mode:

- Include – only checked security roles will be replicated - Exclude – checked security roles will be excluded from replication

If you want to modify security role filter in configuration file you can use RoleFilterConfigurationElement.

<RoleFilterConfiguration Mode="INCLUDE"> <Roles> <clear /> <Role Name="Salesperson" /> <Role Name="System Administrator" /> </Roles>

</RoleFilterConfiguration>


2015-07-31 /43

RoleFilterConfigurationElement element attribute is described in following table:


Mode string

Specify behaviour of security role filter.

Accepted values are: NONE, INCLUDE, EXCLUDE.

No NONE

Role element represent a CRM security role (referenced by name). Roles represents collection of Role records. Role element attributes are described in following table:


Name string Name of Dynamics CRM security role. The attribute is case sensitive.

Yes


2015-07-31 /43

8 Running CB Replicator

The CB Replicator consists of 2 services:

- CB Dynamics CRM privileges to SharePoint permissions replicator - CB Replicator server (optional)

To start CB Replicator please start both of these services (if not running) – always start CB Replicator server as first one.

Note: If you haven’t configured AutoStart property to true the service will start in idle mode. It means that service will be started but no processing will be performed. You must use CB Replicator Controller to fire processing.

Note: In order to have the service starting automatically you need to set service Startup type to Automatic.

To control CB Replicator the CB Replicator Controller tool can also help you.

Clicking at Start button will begin permission transfer process. Clicking at Stop button will request cancellation process (this could take some time until processing will be cancelled).


2015-07-31 /43

In the bottom right corner you can see processing status. Available options are:

- Starting – CB Replicator is initializing - InitialLoading – CB Replicator is doing initial processing - Started – CB Replicator has been started - Stopping – CB Replicator is stopping - Stopped – CB Replicator has been stopped

In the bottom left corner you can see number of pending events that are waiting until CB Replicator will process them.

8.1 Force full iteration When you start your replication process the full replication iteration will be performed. It reload whole security model and check all SharePoint document locations. When your replication process is running it is processing only events occurring in CRM.

CB Replicator has possibility to invoke this full iteration at any time while your service is running. You need to go to menu Actions -> Force full iteration.

Note: In some cases the full iteration can be started automatically during replication if algorithm evaluates that it is easier to run full iteration instead performing all the changes.

8.2 Clear local database CB Replicator remembers permissions that have been written into SharePoint. So if there is no permissions change resulting from CRM side the SharePoint permissions will not be overwritten. To force overwriting of all permission the local database needs to be cleared.

To clean local database go to menu Actions -> Clear local database.

Note: This feature is available only when replication process is not running.


2015-07-31 /43

9 Licensing

CB Replicator license checks following:

- Validity date - Total user count - Total tenant count

Validity date means that license will be expired on specified date. With expiration of license the CB Replicator will stop working completely.

Total user count specifies maximum number of mapped user across all running tenants. It means that total number of users is shared across all started tenants. If this number is reached the users over limit will not be mapped so they will not be replicated. The CB Replicator will continue working.

Total tenant count limit number of tenants running in parallel. You can define more tenants than allowed but you will be not able to start in parallel all of them. The CB Replicator will continue working.

You can check your current license info at HELP -> License.

Tenant license info:

- Total -> maximum tenants you are allowed to start in parallel - Free -> number of non-started tenants that you can possibly start - In-use -> number of tenants running in parallel

User license info:

- Total (shared) -> maximum count of users that can be mapped across all the tenants

- Free (shared) -> count of users that can be mapped - In use -> used user licenses across all the tenants - In use by current tenant -> used user license by this tenant


2015-07-31 /43

10 Troubleshooting

CB Dynamics CRM privileges to SharePoint permissions replicator service is by default configured to create logs (audit) about its activity. The information are stored at following places:

- Log files - Log database - Windows event log (source = CB CRM Replicator)

10.1 Log file Implicitly log file is called cb_replicator_log.txt and you can be found in C:\ProgramData\Connecting Software\CB CRM replicator\Logs\. If CB Dynamics CRM privileges to SharePoint permissions replicator service is not working correctly this should help diagnosing the problem.

The CB Replicator produces following log entries (event types):

- Debug – internal information that could be used to troubleshooting - Info – general information from CB Replicator service - Warning – warning message - Error – error message - CRM Event – received event from CRM - Permissions - transfer of permissions into SharePoint

If a problem occurs which you are not able to solve on your own please contact the support of CB Dynamics CRM privileges to SharePoint permissions replicator.

10.2 CB Replicator Controller logs For basic troubleshooting you can use CB Replicator Controller. It can show you real-time logs and you can also browse logs from past.

10.2.1 Real-time logs The purpose of real-time logs is to show current activity of CB Replicator (not historical events). When you start processing the Real-time logs tab is shown automatically. You can open log window manually by View -> Real-time logs.


2015-07-31 /43

10.2.2 Historical logs History logs allows you to browse history of jobs that have been performed by CB Replicator. To open log history go to View -> Historical logs.


2015-07-31 /43

Historical logs are stored in local database. They can be enabled/disabled via Tools -> Options -> Logs and checking/unchecking Log history enabled flag.

Older logs can be deleted in the same window by clicking at Clear history logs button. You will need to specify how old logs you wish to delete.

10.2.3 Exporting logs CB Replicator Controller provides quick way to export log file in case of issue you are not resolve on your own. To export log go to Help -> Export log. It will create ZIP. Please send this file to CB Replicator support.

11 Known issues 11.1 Custom position hierarchy – user without Read privilege

When custom position hierarchy is configured the CB Replicator creates each position as SharePoint group. It assigns SharePoint permissions at specific folder for each position at hierarchy chain as folder level permission for SharePoint group. However Dynamics CRM has prerequisite that records are accessible only via user that has at least Read privilege on specific entity. With other words it means that there can exist users at position that have access and other do not have.

This would lead to serious performance consequences so CB Replicator ignores Read privilege prerequisite for position hierarchy security and simply all the users at position can access specific record in SharePoint.

Note: Manager hierarchy security follows this prerequisite so this issue is valid only for custom position hierarchy.

CB Replicator - User Manualtest.connecting-software.com/wp-content/uploads/2015/08/CB-Repli… ·...

Documents

Transcript of CB Replicator - User Manualtest.connecting-software.com/wp-content/uploads/2015/08/CB-Repli… ·...