4 Getting Started with Administering BDSS

This chapter describes the administrative tasks for Business Data Synchronization Server (BDSS).

This chapter includes the following topics:

Overview of Administration Tasks
Managing Connectors
Managing BDSS Server Instances
Managing Connector Instances
Managing Domains
Managing Domain Filters
Managing Users
Managing Profiles

4.1 Overview of Administration Tasks

Typically, the administration tasks include:

Managing the instances of PIM servers
Managing connectors:
- Creating and deleting connectors
- Setting the synchronization direction (inbound, outbound, or both) for a connector
- Creating connector instances
- Pointing the connector instance to the connector's WSDL
Managing Domains:
- Creating and deleting the domains for a connector
- Setting the synchronization direction (inbound, outbound, or both) for a domain
Managing Users:
- Creating and deleting a user and a Hub user
- Changing the synchronization direction (inbound, outbound, or both) for the domain of a specified connector user
Using filters to remove outdated task records
Creating, deleting, or updating the parameters for a connector's profile

These tasks are enabled through the attributes and operations of the ServerDomainConfigMBean, the UserConfigMBean, and the ProfileRuntimeInfo MBean. An MBean (managed bean) is a Java object that represents a JMX-manageable resource in a distributed environment, such as an application, a service, a component, or a device.

The attributes and operations of the ServerDomainConfigMBean (listed in Table 4-1) enable you to perform tasks related to managing connectors, PIM servers, and domains.

Table 4-1 Operations of the ServerDomainConfigMBean

Task	Operation
Viewing the Connector Configuration	`showConnectorDetails`
Adding and Updating Connectors	`updateConnectorForPIM`
Deleting a Connector	`deleteConnector`
Adding and Updating BDSS Instances	`updatePimServerInstance`
Deleting a PIM Server Instance	`deletePimServerInstance`
Adding and Updating Connector Instances	`updateConnectorInstance`
Deleting a Connector Instance	`deleteConnectorInstance`
Creating a Domain for a Connector	`updateDomainForConnector`
Deleting a Domain from a Connector	`deleteDomainForConnector`
Creating a Filter for a Domain	`updateFilterForDomain`
Deleting a Filter from a Domain	`deleteFilterForDomain`

The operations of the UserConfigMBean (listed in Table 4-2) enable you to perform such tasks as creating users and configuring user domains.

Table 4-2 Operations of the UserConfigMBean

Task	Operation
Viewing User Status	`showUserList`, `showFailinguserList`, `showUserStatus`
Creating Connector Users	`addConnectorUser`
Deleting Hub Users	`removeHubUser`
Configuring User-Level Synchronization	`updateUserSyncEnablementFlag, updateConnectorUserDomainSyncLevel`

4.1.1 Managing BDSS Components Using MBeans

You can configure these MBeans through a JMX console (such as JConsole) supported by any J2EE-compliant server. This document describes accessing the MBeans using Oracle Enterprise Manager 11g Fusion Middleware Control (the Enterprise Manager console).

4.1.1.1 Accessing MBeans through the Oracle Enterprise Manager Console

To access the MBeans through the Oracle Enterprise Manager console:

Select Application Deployment.
Select System MBean Browser from the list (Figure 4-1). The System MBean Browser page appears. The navigation tree view displays the MBeans registered to the application.

Figure 4-1 Selecting the System MBean Browser
Select an MBean to view its attributes, operations, statistics, and notifications. Oracle Enterprise Manager organizes these components as tabs.
Click Invoke to commit any changes to the MBean's operations. Click Apply to commit any changes to the MBean's attributes.

4.1.1.2 Accessing MBeans through JConsole

To access the MBeans using JConsole, select the MBeans tab:

Click the MBeans tab.
Expand a MBean node in the navigation tree. The attributes, operations, and notifications of the MBean appear as subnodes.
To invoke operations:
1. Select the Operations node in the tree. All of the operations appear as buttons in the right pane. The parameters appear as fields.
2. Update the parameter fields as needed for an operation.
3. Click the operation button to invoke the operation.
To update an individual operation:
1. Expand the Operations node in the tree. The operation nodes appear.
2. Select an operation in the tree to display its MBeanOperationInfo and Descriptor information in the right pane. The operation itself is represented as a button, which you click to invoke the operation.
3. Update the MBeanOperationInfo as needed.
4. Click the button for the operation to invoke the operation.
To set the attributes of an MBean:
1. Expand the Attributes node from the tree. The attributes node appear.
2. Select an attribute. The attribute's value, its MBeanAttributeInfo, and its descriptor appear in the right pane.
3. Set the attribute by first selecting it and then editing it.

For more information about using JConsole, see

http://download.oracle.com/javase/6/docs/technotes/guides/management/jconsole.html

4.1.2 Specifying the Synchronization Direction

The MBean operations enable you to set the inbound, outbound, and full synchronization direction at the connector, domain, and user levels. For more information, see Table 4-15.

Connector Level Synchronization

You can set the maximum synchronization direction for every domain that the connector synchronizes. For information about setting synchronization at the connector level, see Section 4.2.2.1, "Configuring Connector-Level Synchronization and Event Notification."

Domain Level Synchronization

You can set the synchronization direction for a specific data domain for a connector. For information about setting synchronization of the domain level, see Section 4.5.1.1, "Configuring Domain-Level Synchronization."

User-Level Synchronization

You can set the synchronization direction for a particular user for a particular domain. This is the most restrictive level of synchronization. For information about setting synchronization at the user level, see Section 4.7.3.1, "Enabling Synchronization for Hub Users."

4.2 Managing Connectors

Use the operations of ServerDomainConfigMBean listed Table 4-3 to create, delete and view operations of this MBean that enable you to manage the configuration details for connectors.

Table 4-3 Connector Management Operations of the ServerDomainConfigMBean

Operation	Administrative Task
`showConnectorDetails`	Viewing the Connector Configuration
`updateConnectorForPIM`	Adding and Updating Connectors
`deleteConnector`	Deleting a Connector

4.2.1 Viewing the Connector Configuration

To view the configuration for all connectors or for a specific connector:

Select the showConnectorDetails operation.
To view the configuration for a specific connector, enter the display name for the connector as the value for the connectorName attribute. Leave the field blank to view the configuration information for all connectors.
Click Invoke.

4.2.2 Adding and Updating Connectors

The updateConnectorForPIM operation of the ServerDomainConfigMBean enables you to create or update a connector and also enables you to specify how the connector synchronizes.

4.2.2.1 Configuring Connector-Level Synchronization and Event Notification

You enable synchronization for a connector by setting the EnableForSync parameter to true and then selecting a synchronization level (Full, Inbound, Outbound, or None). Setting the synchronization at the connector level sets the direction for every domain synchronized by the connector.

The updateConnectorForPim operation also allows you to enable the connector to send event notifications. Using this operation, you can also enable a connector to inform BDSS when Insert, Update, or Delete events occur for user data.

Note:

Perform event based synchronization through MBeans instead of directly setting the SYNC_EVENTS_ENABLED_FLG, SUPPORTS_EVENTS_FLG, and USER_EVENT_FLG flags in the CONNECTORS table.

To add or update a connector:

Select the updateConnectorForPIM operation.

Define the parameters listed in Table 4-4 and then click Invoke.

Table 4-4 Parameters for the updateConnectorForPIM Operation

Parameter	Description
ConnectorName	The display name for the connector. If you do not define a name for the connector, the BDSS creates one. Otherwise, BDSS modifies the existing one.
SupportsEventNotifications	Select `true` if the connector can notify BDSS when Insert, Update, or Delete events occur for a user's data. Otherwise, select `false` to prevent a connector from notifying BDSS of these events.
syncEventsEnabled	Select `true` to enable the connector to send event notifications. (A connector can support event notification even if it is not prompted to send them).
PimServerType	Specify the PIM server type, such as Exchange2007. You can configure other types of PIM servers.
MaxSyncLevel	The maximum synchronization level for the connector: Full: Enables bidirectional (that is, both inbound and outbound) synchronization. If you set the `MaxSyncLevel` parameter to `Full`, then the connector can both propagate and extract Create, Read, Update, and Delete events between the Hub and the PIM server. Inbound: Enables propagation of Create, Update, and Delete record event data into a PIM server. If you select `Inbound Only` as the value for the `MaxSyncLevel` parameter, then it does not extract data from the PIM server. Outbound: Enables the connector to extract Create, Read, Update, and Delete record event data from the PIM server. If you select `Outbound Only` as the value for the `MaxSyncLevel` parameter, then it does not propagate Create, Read, Update, and Delete record event data to the PIM server. None: Setting the `MaxSyncLevel` parameter to `None` prevents the connector from synchronizing.
EnabledForSync	Select `true` to enable synchronization. Select `false` to disable synchronization.

4.2.3 Deleting a Connector

To delete a connector:

Select the deleteConnector operation.
Specify the ConnectorName parameter (described in Table 4-4) and then click Invoke.

4.3 Managing BDSS Server Instances

Use the operations of the ServerDomainConfigMBean listed in Table 4-5 to create or delete the server instances used by the connectors.

Table 4-5 Operations for Managing Server Instances

Operation	Administrative Task
`updatePimServerInstance`	Adding and Updating BDSS Instances
`deletePimServerInstance`	Deleting a PIM Server Instance

4.3.1 Adding and Updating BDSS Instances

To add or update a BDSS instance:

Select the updatePimServerInstance operation.

Specify the parameters listed in Table 4-6 and then click Invoke.

Table 4-6 Parameters of the updatePimServerInstance Operation

Parameter	Description
PimServerInstance	The name of the PIM server instance. This should be the name of the PM server as it would be returned by Active Directory or by the network directory service used by your network.
ConnectorName	The display name for the connector for which the PIM server instance is configured.

4.3.2 Deleting a PIM Server Instance

To delete a PIM server instance:

Select the deletePimServerInstance operation.
Specify the parameters listed in Table 4-6 and the click Invoke.

4.4 Managing Connector Instances

A connector instance represents a specific installation of a connector. The instance can be a single connector or represent a group of connectors that are accessed from the same load-balanced URI (Universal Resource Identifier).

Use the operations of the ServerDomainConfigMBean listed in Table 4-7 to manage the instances of a connector.

Table 4-7 Operations for Managing Connector Instances

Operation	Administrative Task
`updateConnectorInstance`	Adding and Updating Connector Instances
`deleteConnectorInstance`	Deleting a Connector Instance

4.4.1 Adding and Updating Connector Instances

To add or update a connector instance:

Select the updateConnectorInstance operation.

Specify the parameters listed in Table 4-8 and then click Invoke.

Table 4-8 Parameters of the updateConnectorInstance Operation

Parameter	Description
connectorInstName	The display name for the connector instance
connectorName	The name of the connector for which the connector instance is configured. You can find this name using the `showConnectorDetails` operation. Although the SQL scripts seed the names for the Exchange 2007 and BPEL Task connectors, you can add a different name.
pimServerInst	The PIM server instance used by this connector
url	The URL of the connector's Web service

4.4.2 Deleting a Connector Instance

To delete a connector instance:

Select the deleteConnectorInstance operation.
Specify the connectorInstName and connectorName parameters (described in Table 4-8) and then click Invoke.

4.5 Managing Domains

A domain is a class of records, such as a calendar, business contacts, personal contacts, or tasks. Each connector has a set of domains on the PIM servers (connector domains) that is mapped to a central set of Hub domains. A Hub domain is an abstract representation of a domain defined in the XSD (XML Schema Definition) for the Hub. For more information, see Chapter 8, "Mapping Connector Fields to Hub Fields."

Use the operations of the ServerDomainConfigMBean listed in Table 4-9 to manage domains.

Table 4-9 Operations for Managing Domains

Operation	Administrative Task
`updateDomainForConnector`	Creating a Domain for a Connector
`deleteDomainForConnector`	Deleting a Domain from a Connector

4.5.1 Creating a Domain for a Connector

To add or update a domain for a connector:

Select the updateDomainForConnector operation.
Specify the parameters listed in Table 4-10 and then click Invoke.

Table 4-10 Parameters of the updateDomainForConnector

Parameter	Description
domainName	The name of the domain
domainType	The type of domain, such as Task
connectorName	The display name of the connector for which the domain is configured
synclevel	The maximum synchronization level for the domain: Full Inbound Only Outbound Only None
Priority	Select an integer that determines the priority that the connector domain takes over other connector domains of the same type. You can use any integer (negative, positive or 0) to set the priority. Domains with priority of -2 would be synchronized before domains with a priority of 1. For more information, see Section 4.5.1.1. You must set the Priority parameters to different values for the same domain on each connector. For example, you cannot set the Tasks domain priority to 1 on both the Exchange 2007 connector and another type of connector. If the priorities match for the same domain, then BDSS throws exceptions.

4.5.1.1 Configuring Domain-Level Synchronization

The updateDomainForConnector operation enables you to set the synchronization configuration for a specific domain for a connector through its synclevel and Priority parameters. The synclevel parameter sets the level of synchronization for the domain and the Priority parameter determines which record change event wins a synchronization conflict between record changes from different PIM servers. The Engine synchronizes Hub domains serially, not concurrently. For example, it synchronizes Hub domain A before domain B during a given synchronization session for a user.

Note:

Any number of connectors can link to a Hub domain concurrently. Connector domains that share the same parent Hub domain must have a unique priority number.

The synchronization levels available using the synclevel parameter are as follows:

Full

Enables bidirectional synchronization of a Hub domain across the connectors. If you set the synclevel parameter to Full for a connector domain, then the connector can both propagate and extract Create, Read, Update, and Delete events between the domain and its corresponding domain on another PIM server.

Inbound Only

If you select Inbound Only for a connector domain, then the Engine only propagates record change event data to the PIM for that connector domain. In this case, the Engine does not extract data from the PIM server for the corresponding connector domain when you select this option.

Outbound Only

A domain with an outbound only synchronization level enables the connector to extract Create, Read, Update, and Delete record event data from the corresponding domain on the PIM server. If you select Outbound Only as the value for the synclevel parameter, then the connector does not propagate Create, Read, Update, and Delete record event data to the PIM server for this domain.

None

Setting a synchronization level of None for a connector domain prevents a domain from participating in either inbound or outbound synchronization. No Create, Read, Update, or Delete record event data is propagated to, or extracted from, the corresponding domain on another PIM server.

4.5.2 Deleting a Domain from a Connector

To delete a domain from a connector:

Select the deleteDomainForConnector operation.
Specify the domainName and connectorName parameters (described in Table 4-10) and then click Invoke.

4.6 Managing Domain Filters

Filters are specific to connector domains and enable you to exclude a set of records from the extract result set based on defined criteria. BDSS supports any filter used by a connector.

Note:

For Oracle Fusion Middleware 11g release 1, BDSS ships with a coordinated universal time (UTC) date-time value filter that the Exchange 2007 Connector uses to remove old task records. Using this filter, the Exchange 2007 Connector evaluates the due date of each task record and excludes the record from the extract result set if the filter's date value is more recent than the record's due date.

4.6.1 Creating a Filter for a Domain

To create or update a filter for a connector's domain:

Select the updateFilterForDomain operation of the ServerDomainConfigMBean.

Specify the parameters listed in Table 4-11 and then click Invoke.

Table 4-11 Parameters of the updateFilterForDomain Operation

Parameter	Description
domainFilterName	The name of the filter. This name must be unique within each connector domain
domainName	The name of the domain for which this filter is configured
connectorName	The display name of the connector that owns the filter
DomainFilterValue	The value configured for this filter
DomainFilterSeq	An integer greater than 0 that determines the order that this filter is applied compared to other filters for this domain

4.6.2 Deleting a Filter from a Domain

To delete a filter from a domain:

Select deleteFilterForDomain.
Specify the domainFilterName, domainName, and connectorName parameters and then click Invoke.

4.7 Managing Users

The operations of the UserConfigMBean (listed in Table 4-12) enable you to view user status, create and delete users, and set the synchronization configuration of domains on a per-user basis.

Table 4-12 Operations for Managing Users

Operation	Task
`showUserList`, `showFailinguserList`, and `showUserStatus`	Viewing User Status
`addConnectorUser`	Creating Connector Users
`removeHubUser`	Deleting Hub Users
`updateHubUserSyncEnableFlag`	Enabling Synchronization for Hub Users
`updateUserDomainSyncLevel`	Setting the Synchronization Levels for a User's Domains

4.7.1 Viewing User Status

The operations listed in Table 4-13 enable you to view the synchronization status for users.

Table 4-13 Synchronization Status Operations

Operation	Description
`showUserList`	Returns a list of all users and their respective status
`showFailinguserList`	Returns a list of all users that are currently failing to synchronize
`showUserStatus`	Displays the status for a user, including record level status. There is an optional flag that forces the operation to only return failing items.

4.7.2 Creating Connector Users

The addConnectorUser operation adds a new user to a connector and also associates the user with a Hub user. This operation also creates a Hub user for the connector user if one does not exist.

Note:

If you enable synchronization for a user, then you must also create a user for a connector. The Hub user must also enable the connector user to synchronize by setting the updateUserSyncEnableFlag to true. See Section 4.7.3 for information about setting the synchronization level for a user.

Table 4-14 Parameters of the addConnectorUser Operation

Parameter	Value
hubUserName	The name of the Hub user
connectorUserId	The ID of the connector user. For Exchange 2007 users, enter this value in the format of firstname.lastname@mailserver.com.
target	The location where the user's data is stored. For most Exchange users, this value is root. See also Section C.1.5, "PIM Domain Target."
connectorName	The name of the connector

4.7.2.1 Deleting Hub Users

The removeHubUser operation removes a Hub user from the database and all of the connector users associated with the Hub user. To remove a Hub user:

Select the removeHubUser operation.
Define the hubUserName parameter (described in Table 4-14) and then click Invoke.

4.7.3 Configuring User-Level Synchronization

The updateUserSyncEnablementFlag and updateConnectorUserDomainSyncLevel operations set the synchronization configuration for users.

4.7.3.1 Enabling Synchronization for Hub Users

Setting the updateUserSyncEnablementFlag to true enables a user to synchronize for all subsequent synchronization sessions. Setting the operation to false prevents the user from synchronizing. To enable synchronization for a Hub user:

Set the updateUserSyncEnablementFlag.
Define the hubUserName parameter (described in Table 4-14) and then click Invoke.

4.7.3.2 Setting the Synchronization Levels for a User's Domains

The synchronization levels configured for the domains described in Section 4.5.1.1 are affected by the synchronization levels configured for domains on a per-user basis through the updateUserDomainSyncLevel operation. Using this operation, you can alter the synchronization level for a connector user for a given domain.

Note:

The updateUserDomainSyncLevel operation creates a domain context for a user if one does not exist.

The synchronization levels are:

Full
Inbound Only
Outbound Only
None

These levels, when applied to a user, change the final synchronization direction for a domain, as listed in Table 4-15.

Table 4-15 Domain Synchronization Level Directions

Connector Domain Synchronization Direction	User Synchronization Direction	Final Direction
Full	Full	Full
Full	Inbound Only	Inbound Only
Full	Outbound Only	Outbound Only
Inbound Only	Full	Inbound Only
Inbound Only	Inbound Only	Inbound Only
Inbound Only	Outbound Only	None
Outbound Only	Full	Outbound Only
Outbound Only	Inbound Only	None
Outbound Only	Outbound Only	Outbound Only
None	Any synchronization level (Full, Inbound Only, Outbound Only, None)	None
Any synchronization level (Full, Inbound Only, Outbound Only, None)	None	None

To set the synchronization level for a user's connector domains:

Select the updateUserDomainSyncLevel operation.
Select the synchronization level.
Specify the following parameters:
- connectorUserId (described in Table 4-14)
- connectorName
- domainName (described in Table 4-10)
- syncLevel (described in Table 4-10)
Click Invoke.

4.8 Managing Profiles

A profile stores the configuration metadata for a connector. Connectors retrieve their profiles, which are conceptually equivalent to the Windows .ini configuration file, by using the GetConfigurationMetadata interface. Each profile includes one or more sections that contain parameters. Each parameter has a single value. The ProfileRuntimeInfo MBean enables you to manage the profiles for a connector.

4.8.1 Viewing Profiles

The displayAllProfiles and displayProfile operations enable you to view connector profiles.

4.8.1.1 Viewing All Profiles for a Connector

To view a list of all parameters grouped by profile and by section:

Select the displayAllProfiles operation.
Click Invoke.

4.8.1.2 Viewing a Specific Profile

To view a specific profile:

Select the displayProfile operation.
Enter a profile name.
Click Invoke. The parameters appear, grouped by section of the selected profile.

4.8.2 Managing Profile Parameters

The setProfileParameter and removeProfileParameter operations enable you to create, update, and delete profiles.

4.8.2.1 Creating a Profile

To create a profile:

Select the setProfileParameter operation.
Enter the name of the profile.
Enter the name of the section.
Specify the parameters for the profile (name, value, and comment).
Click Invoke.

4.8.2.2 Updating a Profile

To update a profile:

Select the setProfileParameter operation.
Enter the name of profile.
Enter the name of the section.
Update the parameters as needed.
Click Invoke.

4.8.2.3 Deleting a Parameter from a Profile

To remove a parameter from a selected profile:

Select the removeProfileParameter operation.
Specify the name of the parameter, profile, and the section to ensure that you are removing the correct parameter.
Click Invoke.