Examples: User provisioning change files
After you are enabled to use the integration server, and are familiar with file naming and attribute specification requirements, you can create user provisioning change files for uploading information from your on-premises data management system.
Review Creating user provisioning change files before proceeding.
The file header specifies the operation field names as they are defined in the first column of Table 3 in Creating user provisioning change files (case insensitive). The remaining lines define values for the corresponding fields. Each line must end with an appropriate carriage return or line feed character. On Windows, use \r\n (0x0D 0x0A) and on UNIX or Linux, use \n (0xA). While the integration server can process files with either line ending format, use the TEXT transfer format to ensure that proper line endings are sent to and received from the intermediary FTP server.
- Add the relevant field data in the correct CSV field order as
follows; reference Table 3 in Creating user provisioning change files.
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName, language,timeZone,password,altEmailAddress,notesTemplate,notesDN, assignTo,department,jobTitle,country,telephone,mobile,fax,address, suppressInvitation,federationType,
- Use a UTF-8 character set.
- Add an empty value for an optional or non-applicable field by using consecutive commas.
- Encode a zero length string for a field as “”.
- Surround field values with double quotation marks ("") if the
value contains comma or double quotation marks ("") characters, or
contains spaces at the beginning or end of the value. Other field
values can optionally be surrounded by double quotation marks (""):
- Field values can be surrounded double quotation marks ("") regardless of the characters in the field.
- Double quotation marks ("") must be used for field values that include a comma.
- Double quotation marks ("") must be used for field values that have one or more spaces at the beginning or end of the value.
- Encode a double quotation mark ("") character by using a pair of double quotation marks ("") characters, for example ...,"John ""that guy"" Doe", ...
- An update operation that contains an empty field value (for example ,,) leaves the field set to its existing value.
- An update that specifies a zero length string replaces the field value with a zero length string.
- Operation names are not case-sensitive.
- You can omit trailing commas at the end of a statement. For example,
the following two statements yield the same result:
sd@mailinator.com,Add,85180,,Sam,Daryn,en_US,America/New_York sd@mailinator.com,Add,85180,,Sam,Daryn,en_US,America/New_York,,,,,,,,,,,,
- You can omit field names, and commas, at the end of a statement
if they are not required for the operation. For example, if no fields
are needed past TimeZone, values for only the following
fields are sufficient:
emailAddress,Action,SubscriptionId,SubscriptionId2,GivenName,FamilyName,Language,TimeZone
The following image provides an example of a user provisioning change file:
- Add a subscriber with a collaboration subscription.
sd@mailinator.com,Add,85180,,Sam,Daryn,en_US,America/New_York rsf@mailinator.com,Add,,,Randi,Factor,en_US,America/New_York zachjones@us.ibm.com,Add,85181,,Zach,Jones,en_US,America/New_York
- Update person information for a subscriber.
sd@mailinator.com,Update,,,,,zh_CN,Asia/Shanghai rsf@mailinator.com,Update,,,,Jones zachjones@us.ibm.com,Update,,,Zach
- Suspend a subscriber.
sd@mailinator.com,Suspend
- Resume a subscriber.
sd@mailinator.com,Resume
- Assign an IBM
SmartCloud® Notes® subscription
to an existing subscriber who has a collaboration seat.
zachjones@us.ibm.com,AssignSeat,86796,,,,,,,zachjones@us.ibm.com
- Change an existing subscription seat that is held by a subscriber
from one subscription to another, for example from Meetings15 to Meetings20.
sd@mailinator.com,ChangeSeat,85179
- Revoke an existing collaboration seat that is assigned to the
subscriber.
sd@mailinator.com,RevokeSeat,COLLAB
- Revoke a collaboration seat from one subscriber and reassign the
seat content to a different subscriber (for example from sd@mailinator.com to lsuarez@mailinator.com).
sd@mailinator.com,RevokeSeat,COLLAB,,,,,,,,,,lsuarez@mailinator.com
- Remove a subscriber.
sd@mailinator.com,Remove
- Remove a subscriber and reassign their collaboration content to
another subscriber.
sd@mailinator.com,Remove,,,,,,,,,,,lsuarez@mailinator.com
- Add a subscriber with a SmartCloud Notes subscription
only and set a password that the user must change on first use. Note: Always set a one-time password when you add a subscriber; do not send an invitation to an alternate email to set the password.
sdaryn@us.abx.com,Add,86796,,Sam,Daryn,en_US,America/New_York,secret,, StdR85Mail,Sam Daryn/abx/IBM
- Add a subscriber with Meetings and SmartCloud Notes subscriptions
and set a password that the user must change on first use.Note: Always set a one-time password when you add a SmartCloud Notes subscriber; do not send an invitation to an alternate email to set the password.
sdaryn@us.abx.com,Add,85180,86796,Sam,Daryn,en_US,America/New_York,secret,, StdR85Mail,Sam Daryn/abx/IBM
- Rename a subscriber.
lucillesuarez@mailinator.com,Rename,,,,,,,,lusuarez@mailinator.com
- Suppress an invitation.
lusuarez@mailinator.com,Add,85180,,Lu,Suarez,en_US,America/Boston,,,,,,,,,,,,,SUPPRESS_ALL vivhanley@mailinator.com,Add,,,Viv,Hanley,en_US,America/Boston,,,,,,,,,,,,,SUPPRESS_ALL vivhanley@mailinator.com,AssignSeat,85180,,,,,,,,,,,,,,,,,,SUPPRESS_ALL
- Resend an invitation.
lucsuarez@mailinator.com,ResendInvitation vivhanley@mailinator.com,ResendInvitation
- Specify a federation type.
jashaj@mailinator.com,Add,85180,,Jas,Haj,en_US,America/Boston,,,,,,,,,,,,,,MODIFIED_FEDERATED vivhanley@mailinator.com,Update,,,,,,,,,,,,,,,,,,,,FEDERATED
- Using the notesTemplate field, you can specify
a Notes mail template by using
a "name,version,locale,extension_forms_file" format
(the double quotation marks ("") are required), as shown in the following
sample, to specify specific options to use for the named template:
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,language,timeZone, password,altEmailAddress,notesTemplate Csmith@JRIBMTEST.LLC1test.net,add,143422,,Cheryl,Smith,en_US,,passw0rd,,"StdR85Mail,8.5.3,en_US"
Note: There are several variations available when you use the "name,version,locale,extension_forms_file" format.If a locale is not specified, the template that matches the language that is specified for your account’s language preferences is used. This also equates to the language specified in the CSV file’s language field if you are adding the user.emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,language,timeZone, password,altEmailAddress,notesTemplate Csmith@JRIBMTEST.LLC1test.net,add,143422,,Cheryl,Smith,en_US,,passw0rd,,"StdR85Mail,8.5.2"
If the CSV file specifies a different language value than the value specified in the notesTemplate field ("name,version,locale" format), the locale setting specified in the notesTemplate field overrides the CSV file’s language field value. For example, the following user has Spanish (es_ES) specified in the language field, but English is specified for the locale setting in the notesTemplate field, so the English (en_US) template is used:emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,language, timeZone,password,altEmailAddress,notesTemplate,notesDN,assignTo,department,region, regionAdministrated,jobTitle,country,telephone,mobile,fax,address Csmith@JRIBMTEST.LLC1test.net,add,143422,,Cheryl,Smith,es_ES,,passw0rd,,"StdR85Mail,8.5.3,en_US"
If a version is specified, for example, StdR85Mail,8.5.3,en_US as in the previous example, the specified version is used. If the version setting is null or not specified, the most recent version of the named template is used.emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,language, timeZone,password,altEmailAddress,notesTemplate Csmith@JRIBMTEST.LLC1test.net,add,143422,,Cheryl,Smith,en_US,,passw0rd,,"StdR85Mail,,en_US"
If the locale setting is null or not specified and the CSV file’s language field setting is not specified, the language in the account is used.emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,language,timeZone, password,altEmailAddress,notesTemplate Csmith@JRIBMTEST.LLC1test.net,update,,,,,,,,,"StdR85Mail,8.5.2"
This example illustrates how to apply an extension forms file for a new SmartCloud Notes web user, by using the default locale and version for the template that is named StdR9Mail where the extensions form file name is forms9_x.nsf.emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,language,timeZone, password,altEmailAddress,notesTemplate Csmith@JRIBMTEST.LLC1test.net,add,,,,,,,,,"StdR9Mail,,,forms9_x.nsf"
Note: If you are deleting the extension forms file specification, for example in an update operation, omitting the extension forms file name is not sufficient to remove it; you would specify a value of <delete> in the following format:emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,language,timeZone, password,altEmailAddress,notesTemplate Csmith@JRIBMTEST.LLC1test.net,add,,,,,,,,, ",,,<delete>"
Note: For related and supporting information about specifying a mail template, see the notesTemplate description in Creating user provisioning change files. - Add a SmartCloud Notes hybrid
user that is in listed in the Domino® directory.
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,language,timeZone,password jHybrid12@HybridSVTCoA.com,Add,57163,,Jayne,Hybrid12,,,passw0rd
- Assign a SmartCloud Notes seat
to an existing collaboration user.
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,language, timeZone,password,altEmailAddress jhybrid06@hybridsvtcoa.com,Assignseat,57163,,Jayne,Hybrid06,,,,jhybrid06@HybridSVTCoA.com
- Add a SmartCloud Notes hybrid
user and assign a mail template for that user.
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,language,timeZone,password, altEmailAddress,notesTemplate jHybrid11@HybridSVTCoA.com,Add,57163,,Jayne,Hybrid11,,,passw0rd,,callc10727mail
- Assign a SmartCloud Notes seat,
and specify a mail template name, for an existing collaboration user.
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,language,timeZone,password, altEmailAddress,notesTemplate jhybrid06@hybridsvtcoa.com,Assignseat,57163,,Jayne,Hybrid06,,,,jhybrid06@HybridSVTCoA.com,callc10727mail
- Update one or more existing users to use a different mail template.
- Enable an existing user to use a different mail template than
the one they are using currently.
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,language,timeZone, password,altEmailAddress,notesTemplate,notesDN,Department,jobTitle,Country,telephone,mobile,fax,address jHybridNew28@HybridSVTCoA.com,Update,,,Jayne,Hybridnew28,,,,,CALLC10727Mail
- Enable all existing users to use a different mail template than
the one they are using currently.
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,language,timeZone, password,altEmailAddress,notesTemplate,notesDN,Department,jobTitle,Country,telephone,mobile,fax,address maddiemorrie@ktpvmw2k8.swg.usma.abx.com,Update,,,,,,,,,CALLC10727Mail
- Enable an existing user to use a different mail template than
the one they are using currently.
- Update operations If an administrator wants to update a SmartCloud Notes user's givenName or familyName, they must not specify anything in the notesDN field. Specifying a value in such an update operation fails with the message ERROR: Notes Attribute validation failed.
- For example, the following Update operation
would fail:
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,notesDN jHybridNew10@HybridSVTCoA.com,Update,,,Jaynerevised,HybridNew10revised,Jayne HybridNew10/HighAvail
- For example, the following Update operation
would succeed:
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,notesDN jHybridNew10@HybridSVTCoA.com,Update,,,Jaynerevised,HybridNew10revised,
If an administrator wants to update a SmartCloud Notes user's custom template, they must not specify anything in the notesDN field.- For example, the following Update operation
would fail:
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,notesTemplate,notesDN annajones@jroct19.llc1test.net,Update,,,Anna,Jones,E3_2319A,Anna Jones/JR OCT 19
- For example, the following Update operation
would succeed:
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,notesTemplate,notesDN annajones@jroct19.llc1test.net,Update,,,Anna,Jones,E3_2319A
- For example, the following Update operation
would fail:
- Add operations
If an administrator adds a SmartCloud Notes user and specifies a different givenName or familyName than the user's on-premises distinguished name, they must specify the correct distinguished name in the notesDN field.
- For example, the following Add operation would
fail:
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,password,notesDN jHybridNew13@HybridSVTCoA.com,Add,57163,,Jaynerevised,HybridNew13revised,passw0rd
- For example, the following Add operation would
succeed:
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,password,notesDN jHybridNew13@HybridSVTCoA.com,Add,57163,,Jaynerevised,HybridNew13revised,passw0rd,Jayne HybridNew13/HighAvail
- For example, the following Add operation would
fail:
- AssignSeat operationsBehavior for a SmartCloud Notes subscription is as follows:
- If givenName and familyName are null, and notesDN is specified, use the notesDN as the user’s DN.
- If givenName and familyName are specified, and notesDN is null, use the givenName and familyName to construct the DN.
- If givenName and familyName are specified, and notesDN is specified, use the notesDN as the user’s DN and ignore givenName and familyName.
- If givenName and familyName are null, and notesDN is null, use the givenName and familyName from the account as the user’s DN.
- For SmartCloud Notes hybrid users, an entry must exist in the IBM® Domino Directory with the resulting DN.
- For SmartCloud Notes non-hybrid users there must not be an existing entry in the IBM Domino Directory with the resulting DN.
- The user account record is not updated with any values specified by the givenName or familyName fields.
- Revoke a bundled subscription from a user and reassign their collaboration
user data to another user.
sarahdavidson@try.lotuslive.com,RevokeSeat,BUNDLE,,,,,,,,,,jd@mailinator.com
- Assign a bundled subscription to a user whom has no existing seat.
mad@mailinator.com,AssignSeat,91319,,,,,,,meghandavidson@try.lotuslive.com
- Remove subscriber and reassign collaboration content to another
user (only Files and Activities data can be reassigned, all other
cloud applications data and mail data is deleted).
mad@mailinator.com,Remove,,,,,,,,,,,jd@mailinator.com
- Revoke a bundled subscription from a user and reassign collaboration
user data to another user.
smd@try.lotuslive.com,RevokeSeat,BUNDLE,,,,,,,,,,jd@mailinator.com
- Assign anIBM Traveler Traveler
seat to a subscriber for an existing SmartCloud Notes user.
emailAddress,action,subscriptionId jnotes06@notesdomain.com,Assignseat,57163
- Add and provision a user with a SmartCloud Notes subscription
and a Traveler accessory subscription.
smd@try.lotuslive.com,Add,91319,91320,Sarah,Davidson,en_US,America/New_York
- Change the seat assignment of a user who is provisioned in a SmartCloud Notes and
IBM Connections Cloud S2 bundled subscription and Traveler subscription
to SmartCloud Notes.
The Traveler subscription is preserved.
cjd@mailinator.com,ChangeSeat,85180,DELETECOLLAB
- Change the seat assignment of a user who is provisioned in a bundled
subscription and SmartCloud Notes Traveler
subscription to just IBM Connections Cloud 2. The Traveler subscription
is removed.
cjd@mailinator.com,ChangeSeat,85180,DELETEMAIL
- Add a federated user and simultaneously force their automatic
verification and activation by using the Activation option
in an Add operation. This operation has caveats that
require users to be federated and email verification be disabled,
see Creating user provisioning change files for more
information. The following conditions are present in these examples:
emailAddress,action,subscriptionId,subscriptionId2,givenName,familyName,language,timeZone,password,altEmailAddress,Activation,FederationType,notesTemplate,notesDN,assignTo
- The following Add operation adds and automatically
activates the user:
federated_user16@blog.ivthouse.com,Add,,,Federated,User16,,,,,FORCE_ACTIVATION,FEDERATED
- The following Add operation fails with a 1095
(ERROR_INVALID_ACTIVATION_VALUE) error because the Activation value
is not set to FORCE_ACTIVATION:
nonfederated_user12@blog.ivthouse.com,Add,,,Nonfederated,User12,,,,,INVALIDABC,,,,
- The following Add operations fail with a 1096
(ERROR_CANNOT_FORCE_ACTIVATION) error because Activation is
set to FORCE_ACTIVATION but FederationType is
not set to FEDERATED:
nonfederated_user11@blog.ivthouse.com,Add,,,Nonfederated,User11,,,,,FORCE_ACTIVATION,,,,
federated_user17@blog.ivthouse.com,Add,,,Federated,User17,,,,,FORCE_ACTIVATION,NON_FEDERATED,,,
modfederated_user18@blog.ivthouse.com,Add,,,Federated,User18,,,,,FORCE_ACTIVATION,MODIFIED_FEDERATED,,,
- The following Add operation fails with a 1056
(ERROR_FEDERATION_ONLY_PARTIAL) error because the
organization is not configured to allow federated user login:
federated_user6@nonFedCompany.com,Add,,,Federated,User6,,,,,FORCE_ACTIVATION,FEDERATED,,,
- The following Add operation adds and automatically
activates the user: