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.

Adhere to the following rules when encoding operations in a provisioning change file:
Note: The integration server’s user provisioning change files use a comma-separated values (CSV) format; reference RFC 4180 for more information. Details about this format are available on the web at sites such as Wikipedia.
  • 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:

Comma-separated file with provisioning data

Examples illustrating sample field values for various operation objectives are as follows:
  • 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
When you add or update a SmartCloud Notes hybrid or non-hybrid user's name or mail template by using a provisioning change file; caveats exist for notesDN field usage. This is applicable when a user's givenName or familyName differ in their notesDN settings. Examples are as follows:
  • 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
  • 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
  • AssignSeat operations
    Behavior 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.
Several sample provisioning file entries for bundled subscriptions are provided as follows:
  • 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,,,