This chapter describes how to set up and manage Oracle Communications Contacts Server users, accounts, address books, and contacts.
This section describes how to provision Contacts Server users and contains the following topics:
Contacts Server uses Directory Server to store and retrieve user and resource information and to perform authentication. Contacts Server does not add or modify LDAP data. Contacts Server data (such as address book and contact information) is stored in an SQL database, which can be either MySQL Server or Oracle Database.
By default, Contacts Server automatically creates the necessary entries in the SQL database for users upon their initial Contacts Server login. However, you must also perform some basic LDAP user provisioning for users to be able to access Contacts Server services, and for Contacts Server automatic account creation to work. You can provision Contacts Server users in the Directory Server LDAP by using either Delegated Administrator or LDAP tools.
You must provision Contacts Server users so that Contacts Server can automatically create accounts and users can access Contacts Server services. You must provision users with the following attributes:
An email attribute, such as mail.
A unique ID attribute corresponding to the value of the server configuration parameter, davcore.uriinfo.permanentuniqueid. The default value is davUniqueId. Be sure to also index the attribute used for davcore.uriinfo.permanentuniqueid, as Contacts Server performs searches on it.
To define these attributes, the corresponding object classes must be present in the Directory Server LDAP. The Communications Suite comm_dssetup script adds the necessary object classes. The davEntity object class defines the davUniqueId attribute. If your deployment consists of multiple back-end databases, you must also define the store ID attribute. The nabUser object class defines the default store ID attribute. The default value of the store ID is nabStore.
For more information, see the topic on Contacts Server LDAP object classes and attributes in Communications Suite Schema Reference.
By default, if you provision Contacts Server users for email and unique ID attributes (and the store ID attribute when multiple back-end databases are deployed), users have a status of active. The active status enables users to access Contacts Server services. To deny Contacts Server services to users, you specify a value of either inactive or deleted for the user's nabStatus attribute.
If you have a co-existent deployment of both Contacts Server and Convergence WABP, and are migrating users to Contacts Server, you must update the user's LDAP data once the user is marked for migration and taken offline for migration. You can only migrate the user at that point. Contacts Server uses an LDAP attribute to determine if a user has been migrated. By default, the nabStore attribute is used, but you can choose another attribute if desired. In a single back-end deployment, this attribute must be added with the value of defaultbackend. In a multiple back-end deployment, the value must be the logical back-end ID for the database where the user's data resides after migration. Again, the object class that defines the nabStore attribute is nabUser.
Starting with version 7.0.0.10.0, Oracle Communications Delegated Administrator enables you to provision Contacts Server users. See Delegated Administrator System Administrator's Guide for more information.
Contacts Server uses Access Control Lists (ACLs) that you define to control access to address books. (ACLs are also used to control access to accounts.) An ACL applies to a single address book (or account). An ACL consists of one or more Access Control Entries (ACEs), which are strings that grant a particular level of access such as read-only access or read and write access. ACEs collectively apply to the same address book. Multiple ACE strings can apply to a single address book.
You can also define ACEs for LDAP groups. Groups and users are each represented by a mail address. An access right granted to a group is effective for all members of the group.
Access to address books is denied unless explicitly granted. Some access rights are predefined and cannot be changed. For example, Contacts Server gives users full access to their own address books.
ACEs are specified in the following format:
ace_principal:right
where:
ace_principal can be one of the following values:
@ grants access to all users.
@domain grants access to all users on a specific domain. Example:
@example.com
user@domain grants access to a specific user. Example:
Bob@example.com
group@domain grants access to a set of users who belong to a defined group. Example:
MyGroup@example.com
rights can be one of the following values:
n (none) denies access
r (read) grants read-only access
w (write) grants read and write access
a (all) grants all levels of access
You set Contacts Server access rights by using the davadmin command with the acl property on the command line, or buy using the Convergence client. The acl property is a semicolon-separated list of ACE strings.
ACEs function in the following way:
More specific access rights override less specific access rights. For example, access rights granted to a particular user are more specific than rights granted to a user as member of a group. The user-specific access rights override the access rights granted through group membership.
Access rights granted to all users (using the @ value) are considered least specific.
When a user is a member of multiple groups, that user is given the highest level of access granted by any one of the groups.
Contacts Server access control ignores nesting levels within each group.
When determining group membership for access rights, Contacts Server considers only the users' domain name (DN) defined in the LDAP directory. The DN value may be set in the uniquemember attribute, or set in the memberurl attribute as a URL that resolves to the DN of the group.
This section describes tasks related to managing Contacts Server accounts.
Managing accounts includes:
You manage Contacts Server accounts by using the davadmin command. You authenticate the davadmin command with the application server administrative user name and password to allow to communicate with the server or database. You can use the davadmin passfile operation to store the necessary passwords in an encrypted wallet for use by subsequent davadmin commands. If you do not store passwords in the wallet, then you must enter them by using a no-echo prompt on the command line. See the discussion about passfile operation in Contacts Server System Administrator's Guide for more information.
You can enable or disable, on a system-wide basis, automatic account creation. When automatic account creation is enabled, users' accounts are automatically created for them when they first log in to Contacts Server.
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin config modify -o davcore.autocreate.enableautocreate -v true
To create accounts with default contacts properties automatically when users log in:
Provision users in LDAP with the minimum functionality that Contacts Server requires.
See "Provisioning Contacts Server Overview" for more information.
Use the davadmin config command to set any of the following autocreate parameters to customize your deployment:
davcore.autocreate.displaynameattr
davcore.autocreate.emailnotificationaddressattr
davcore.autocreate.enableemailnotification
For more information about these parameters, see "Contacts Server Configuration Parameters".
Enable account autocreation.
Provide users instructions for logging in to Contacts Server.
Use the davadmin account create command to create Contacts Server accounts. You can specify certain account properties on the command line. You can create accounts one at a time or in batch mode by using the -f file option. When you use -f, you specify a file of accounts that you create. The file format is account:property_list, where property_list is optional and contains a comma separated list of property=value fields.
Users must be already provisioned in the LDAP Directory Server before you can create the Contacts Server account. See "Provisioning Contacts Server Overview" for more information.
Tip:
You can customize accounts by configuring them with specific properties before users initially log in to access Contacts Server.To manually create a single account:
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin account create -a account
Where:
account is the user account.
For example, to create the account john.smith@example.com:
davadmin account create -a john.smith@example.com
See "davadmin account" for more information on creating an account with specific account properties.
Use the davadmin account list command to view all accounts or properties of a specific account.
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin account list
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin account list -a account
Where:
account is the user account.
For example, to list the properties of the account johnsmith@example.com:
davadmin account list -a johnsmith@example.com
Use the davadmin account modify command to manage account email notifications.
When email notification is enabled, Contacts Server sends and email to the account owner when changes to the account are made.
To enable email notification:
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin account modify -a account -y notifemail=1
Where:
account is the user account.
For example, to enable email notifications for the account john.smith@example.com:
davadmin account modify -a john.smith@example.com -y notifemail=1
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin account modify -a account -y notifemail=0
Where:
account is the user account.
For example, to disable email notifications for the account john.smith@example.com:
davadmin account modify -a john.smith@example.com -y notifemail=0
Recipients of email notifications are users who have Contacts Server accounts. You add users as recipients of email notification for an account by specifying the account (email addresses) of the users to add. You remove users as recipients of email notification by specifying the accounts of the users to keep; any existing recipients you do not specify are removed.
Important: When adding recipients, be sure to also specify all existing recipients you want to keep. If you do not, they will be removed.
To add or remove recipients for email notifications for an account:
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command.
davadmin account modify -a account -y notifrecipients="recipient1 recipient2 ..."
Where:
account is the user account.
recipient1 and recipient2 are Contacts Server accounts to receive email notifications.
For example, to add jane.jones and sam.taylor so that they receive email notifications for the account john.smith@example.com:
davadmin account modify -a john.smith@example.com -y notifrecipients="jane.jones@example.com sam.taylor@example.com"
Use the davadmin account delete command to remove accounts.
Note:
The davadmin account delete command removes the account from the Contacts Server database but does not remove the user from the LDAP directory.To delete an account:
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin account delete -a account
Where:
account is the user account.
For example, to delete an account named john.smith@example.com:
davadmin account delete -a john.smith@example.com
For a user to subscribe to another account's address book, you first use the davadmin addressbook modify command to give the subscribing user's account access rights to the other account's address book. The access level must be at least read permission. You then use the davadmin account subscribe command to set up the subscription itself.
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Give the subscribing account access rights to the address book of the other account. Set the access rights in the form of an ACL:
davadmin addressbook modify -a subscribed_to_account -y acl=ace_principal:right
Where:
subscribed_to_account is the user account being subscribed to.
ace_principal is the account that is subscribing to the address book.
right is the ACL being granted to the subscribing account.
See "About Controlling Access to Address Books" for more information on ACI's.
Subscribe to the account's address book:
davadmin account subscribe -a subscribing_account -c URI_of_subscribed_to_account
Where:
subscribing_account is the account making the subscription request.
URI_of_subscribed_to_account is the URI of the account being subscribed to.
For example, to give cal196@example.com read access to cal200@example.com, then to subscribe cal196@example.com to cal200@example.com:
davadmin addressbook modify -a cal200@example.com -y acl=cal196@example.com:r
davadmin account subscribe -a cal196@example.com -c /home/caltest200@example.com/addressbook/
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Remove the permission, in the form of an ACL, from the subscribing-account, by setting it to none (n). See "About Controlling Access to Address Books" for more information on ACLs.
davadmin addressbook modify -a subscribed_to_account -y acl=subscribing_account:n
Where:
subscribed_to_account is the account being subscribed to.
subscribing_account is the account that has subscribed.
Unsubscribe from the account:
davadmin account unsubscribe -a subscribing_account -c URI_of_subscribed_to_account
For example:
davadmin account modify -a caltest200@example.com -y acl=caltest196@example.com:n davadmin account unsubscribe -a cal196@example.com -c /home/caltest200@example.com/addressbook/
Use the davadmin addressbook command to create, list, modify, and delete address books.
Managing address books includes:
Contacts Server automatically creates a user's default address book upon login, when you have set the davcore.autocreate.enableautocreate configuration parameter to true. By default, Contacts Server adds a single person contact entry (PCC) for the user to the default address book. You can create additional address books for users. When creating an address book, you can specify a display name, description, and access control instructions. If you do not supply a display name, it defaults to the address book name supplied for the -n option.
To manually create an address book:
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin addressbook create -a account -n name
Where:
account is the user account.
name is the name of the address book.
For example, to create an address book named socialab for the account john.smith@example.com:
davadmin addressbook create -a john.smith@example.com -n socialab
Use the davadmin addressbook delete command to remove address books from accounts. To remove multiple address books, use the -f filename option. Create filename with the list of address books to be deleted. In this file, do not include any blank lines, otherwise the delete command will fail.
To remove an address book:
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin addressbook delete -a account -n name
Where:
account is the user account.
name is the name of the address book.
For example, to delete an address book named socialab from the account john.smith@example.com:
davadmin addressbook delete -a john.smith@example.com -n socialab
For example, to delete multiple address books specified in the file addressbooktodelete.txt from the account john.smith@example.com:
davadmin addressbook delete -f addressbooktodelete.txt -a john.smith@example.com
Use the davadmin addressbook modify command to modify an address book's display name, description, and ACLs. In addition, you can set or remove one or more ACEs from the ACL.
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin addressbook modify -a account -y property=value
Where:
account is the user account.
property is an address book property to set.
value is the value of the property to set.
You can specify multiple property=value pairs by separating them with a comma. See "davadmin addressbook" for information about the possible properties.
For example, to give john.smith@example.com read (r) access to the account james.jones@example.com:
davadmin addressbook modify -a james.jones@example.com -y acl=john.smith@example.com:r
Use the addressbook list command to display the properties of an address book, including its ACLs, number of contacts, and number of contact groups.
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin addressbook list -a account
Where:
account is the user account.
For example, to list the address books for the account john.smith@example.com:
davadmin addressbook list -a john.smith@example.com
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin addressbook list -a account -n name
Where:
account is the user account.
name is the name of the address book.
For example, to list the properties of an address book named socialab for the account john.smith@example.com:
davadmin addressbook list -a john.smith@example.com -n socialab
Use the davadmin contact command to list contact properties and to delete contacts.
Managing contacts includes:
Use the davadmin contact list command to list contact properties, including vCard information and the address book to which the contact belongs.
To list a contact's properties:
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin contact list -a account
Where:
account is the user account.
For example, to list the properties of contacts belonging to the account john.smith@example.com:
davadmin contact list -a john.smith@example.com
Use the davadmin contact delete command to delete contacts.
To delete a contact:
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin contact delete -a account -c contact
Where:
account is the user account.
contact is the name of the contact to delete.
For example, to delete the contact 1406701074936-0-.vcf from the account john.smith@example.com:
davadmin contact delete -a john.smith@example.com -c 1406701074936-0-.vcf
Contact groups enable users to organize their contacts, making it easier to work with a specific set of people. For example, a user might want to organize contacts by family, work, and soccer team. Use the davadmin ctgroup command to manage contact groups.
Managing groups includes:
You can create multiple contact groups per address book. When you create a contact group, you can also add members to it by using the -M option.
To create a contact group:
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin ctgroup create -a account -n name -g groupname
Where:
account is the user account.
name is the name of the address book.
groupname is the name of the contact group.
For example, to create a contact group named myctgroup in the socialab address book for the account john.smith@example.com:
davadmin ctgroup create -a john.smith@example.com -n socialab -g myctgroup
Use the davadmin ctgroup list command to list an address book's contact groups.
To list contact groups:
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin ctgroup list -a account -n addressbook
Where:
account is the user account.
addressbook is the name of the address book.
For example, to list contact groups for the account john.smith@example.com in the address book socialab:
davadmin ctgroup list -a john.smith@example.com -n socialab
Use the davadmin ctgroup delete command to delete a contact group.
To delete a contact group:
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the davadmin ctgroup list command to list the contact groups, and note the URI of the contact to delete. See "Listing Contact Groups" for more information about listing groups.
Run the following davadmin command:
davadmin ctgroup delete -a account -c contactgroup_uri
Where:
account is the user account.
contactgroup_uri is the contact URI that you retrieved in the previous step.
For example, to delete the contact group 410448708259-29-.vcf from the account johnsmith@example.com:
davadmin ctgroup delete -a john.smith@example.com -c 410448708259-29-.vcf
Use the davadmin ctgroup modify command to modify the contact group name, members, and email addresses of members.
To modify a contact group:
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the davadmin ctgroup list command to list the contact groups, and note the vCard file that identifies the contact group to modify. See "Listing Contact Groups" for information about listing groups. The output will show the full WebDAV URL, for example:
/dav/home/john.smith@example.com/addressbook/1384904616388-1758.vcf
The part that you use in the modify command appears after the "addressbook/" string; in this example, 1384904616388-1758.vcf.
Run the davadmin command to modify the contact group. For example, to add members to a contact group, run the following command:
davadmin ctgroup modify -a account -n name -c contactgroup -M members
Where:
account is the user account.
name is the name of the address book.
contactgroup is the vCard file that identifies the contact group to be modified, which you retrieved in the previous step.
members is a list of comma-separated list of members to add to the contact group.
For example, to add two members to the contact group 1384904616388-1758.vcf in the address book socialab for the account john.smith@example.com:
davadmin ctgroup modify -a john.smith@example.com -n socialab -c 1384904616388-1758-GROUP.vcf, -M 1413320201700-4-.vcf,1413320035573-3-.vcf
Contacts Server enables you to import contact groups from CSV, LDIF, and vCard 3.0 formats. Use the davadmin ctgroup import command to import contact groups to an address book.
Note:
The recommended format is vCard 3.0. Only use CSV if vCard 3.0 is unavailable.To import a contact group:
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the following davadmin command:
davadmin ctgroup import -a account -n name -m path
Where:
account is the user account.
name is the name of the address book.
path specifies the file and its path on the host that contains data to be imported.
For example, to import a contact group to the account john.smith@example.com and the address book socialab using the file /temp/ctgroup/red_team_group.vcf:
davadmin ctgroup import -a john.smith@example.com -n socialab -m /temp/ctgroup/red_team_group.vcf
The sample data for the red_team_group.vcf file is:
BEGIN:VCARD VERSION:3.0 FN:RedTeam KIND:group UID:urn:uuid:cd97370b-63a7-4fbf-9d82-fb2af1ad602c MEMBER:1413320201700-4-.vcf MEMBER:1413320035573-3-.vcf END:VCARD
Contacts Server enables you to export contact groups in vCard 3.0 format. Use the davadmin ctgroup export command to export contact groups. The davadmin ctgroup export command exports only the group vCard and not individual members.
To export a contact group:
Log in to the Contacts Server host as root.
Change to the ContactsServer_home/sbin directory.
Run the davadmin ctgroup list command to list the contact groups, and note the vCard file that identifies the contact group to export. See "Listing Contact Properties" for more information about listing contact information. The output will show the full WebDAV URL, for example:
/dav/home/john.smith@example.com/addressbook/1384904616388-1758.vcf
The part that you use in the export command appears after the "addressbook/" string, in this example, 1384904616388-1758.vcf.
Run the following davadmin command:
davadmin ctgroup export -a account -c contactgroup -x path
Where:
account is the user account.
contactgroup is the vCard file that identifies the contact group to be exported, which you retrieved in the previous step.
path is the file and path that the contact group would be exported to.
For example, to export the contact group1384904616388-1758-GROUP.vcf for the account john.smith@example.com to the file /tmp/export.vcf:
davadmin ctgroup export -a john.smith@example.com -c 1384904616388-1758-GROUP.vcf -x /tmp/export.vcf