Creating user provisioning change files

A user provisioning change file is a customer-created CSV text file that contains user provisioning information from your on-premises management system. When you are enabled to use the integration server, you use these text files to upload user provisioning information.

In the enabled integration server environment, when you add a user or change an existing user's configuration, you can manually, or automatically by using a custom agent, create a user provisioning change file to capture those changes. This text file is used to upload user provisioning information.

Required provisioning file name and content formats are described here.

Within your provisioning change files, you can provision users as single collaboration and mail seat subscription or as part of a bundled subscription.

You can also specify accessory subscriptions, including IBM® Traveler, IBM Docs, and Archiving Retention Data Feed.

Provisioning change file naming convention

Provisioning files must be properly named to be recognized and processed. Use the following naming convention when you create a user provisioning change file:

customerId_sourceId_prv_seqnum.csv

Table 1. Provisioning change file naming convention
File name entry type	File name entry description
`customerId`	Specifies the internal numeric identifier that is assigned to the customer. Your customer ID is in the Organization Account: Settings section of the Administration user interface. Use the value that is assigned to your specific customer account for the `customerId` value.
`sourceId`	Specifies the optional name of the authoritative source of the changes. The `sourceId` part of the change file name can remain blank if there is only one source of identity information within the organization. For example, use one `sourceId` when source data is obtained from an IBM Domino® Directory and another when source data is obtained from an Active Directory.
`type`	The user provisioning file type is PRV.
`seqNum`	Specifies the sequence number that is used to order the processing of files; the value must be an integer value 0 - 9223372036854775807. The value must not be less than the value of the last file processed. If the last sequence number that was processed is 9223372036854775807, either successfully or with a failure, the next provisioning file can have a sequence number of 1 or higher. This allows you to reset the last sequence number that is stored on the server. UNIX epoch time is the suggested format. Use the UNIX date and time stamp for the `seqNum` part of the file name. See http://www.epochconverter.com (opens a new window) details. Sequence numbers are relative to the `customerId` and the `sourceId` values. This allows for machine and region independence.
`ext`	Specifies the file extension that indicates the data encoding type; options are as follows: .ldif - LDIF encoding; must be specified for integration change files .csv - Comma-separated values encoding; must be specified for user provisioning change files

Example provisioning change file names are as follows:

30020506_HRDatabase_PRV_1260226223.CSV
30020506_PRV_1260226223.csv

In both examples, the organization's name is represented by the character string 30020506, the files are user provisioning change files, the sequence number is 1260226223, and the file is designated as one whose contents are comma-separated. The first example uses the optional authorization source ID.

Note: Because the sourceId and seqNum values are controlled by each organization, date and time synchronization is not required.

Provisioning change file operations

You can encode various operations in a user provisioning change file.

Note: This table lists operation types; field entries and descriptions are provided in the next table.

Note: If the user is in a HELD state, the integration server rejects their provisioning file content and adds an error message to their associated report file.

Note: Email address specification is not case-sensitive; all email addresses are normalized to lowercase.

Note: Using your organization account page, you can optionally specify that terms of use be automatically accepted for all users.

Table 2. Provisioning change file operation types
Provisioning operation	Description
`Add`	Creates a subscriber record. An `Add` operation sends an email invitation to the subscriber that prompts them to set their own password, accept terms and conditions and access the services to which they've been entitled. The subscriber is provided with a login account and a self-manageable profile. A one-time password can be supplied, which the subscriber must change after first use. Note: Non-federated and Modified federated users must complete registration by using the email invitation process, even if their account is created by using a customer-owned domain. Federated users are automatically processed and do not receive the email invitation.
`Update`	Updates a subscriber's person information such as their email address or mail template. This is the only valid `operation` value when the `type` value is PROFILES.
`Suspend`	Disables a subscriber's ability to log in and use services; it does not remove them or revoke subscriptions that are assigned to them.
`Resume`	Enables a suspended subscriber to log in and use services.
`Remove`	Removes a subscriber and revokes all their entitlements. It also permanently deletes all collaboration content relative to the user's current collaboration subscription or optionally, reassigns it to another subscriber. Note: Reassignment of mail content is not supported. If the user that is being removed has a mail subscription, all content that is associated with that mail subscription is permanently deleted. For more information about data that is removed when an account is removed, see Permanently deleting a user account.
`AssignSeat`	Assigns a subscription seat to the subscriber, provisioning all entitlements as defined within the subscription. A subscription seat entitles the subscriber to use all the features of a specific offering. A subscriber is allowed no more than their mail subscription and 1 collaboration subscription.
`ChangeSeat`	Changes the user's current collaboration subscription seat to a different collaboration subscription seat. Specifies the new collaboration `subscriptionId` and changes the existing subscription to the new subscription. Note: The current and target subscriptions must be compatible. Contact customer support for a list of compatible subscriptions. Use the `DELETECOLLAB` and `DELETEMAIL` keywords when you change an existing user from a bundled subscription to a single seat mail or collaboration subscription.
`RevokeSeat`	Revokes an existing subscribers seat, removing all entitlements that are associated with the subscription. Note: Rather than specify a particular `subscriptionId` value, specify `COLLAB`, `MAIL`, `BUNDLE`, `TRAVELER`, `IBM_DOCS`, or `RETENTION` in the `subscriptionId` field to identify the seat to revoke. Note: See the `AssignTo` field in the following table to optionally delete all collaboration content relative to a subscription or reassign to another. For a collaboration seat subscription, Files and Activities content can be reassigned. All other user data is deleted. Mail content cannot be reassigned.
`Rename`	Changes the `EmailAddress` that uniquely identifies the user and that they use to log in. This operation is available to users that have a collaboration or mail subscription. To rename a user who does not have a hybrid IBM SmartCloud® Notes® subscription, you can change the email address for that user by using the `Rename` operation. While the `Rename` operation is available for a user who has a hybrid SmartCloud Notes subscription, the following sequential step process must be performed for that user: The customer’s on-premises domain administrator changes the user’s email address in the Domino directory. The on-premises Domino directory synchronizes to SmartCloud Notes, which updates the user’s email address in the SmartCloud Notes. The administrator can then specify the `Rename` operation in a provisioning change file by using normal integration server procedures (or perform a rename for the individual user directly in the cloud user account). Note: Operations are first run in the customer’s on-premises Domino directory (Tip: Keep the old email address referenced in the person record `shortname` field.) and then synchronized into SmartCloud Notes before you make changes in the cloud account to ensure continuity in notification email routing. If a user’s email address is changed by using the integration server `Rename` operation (or directly in the cloud account), before the on-premises directory change synchronizes to SmartCloud Notes notification email is not delivered to the new email address because the address is not considered valid in SmartCloud Notes. Note: The `Rename` operation occurs immediately for federated and modified federated users. However, it fails for a federated user if the new email address contains a domain that the customer doesn't own.
`ResendInvitation`	Sends an invitation email to allow a user to activate a subscription for which they are assigned a seat. This is typically used when the original invitation was either not delivered or was lost or deleted. This operation can also be used with an `Add` or `AssignSeat` operation that specifies `SUPPRESS_ALL` in the `SupressInvitation` field. This enables a user to be pre-provisioned (without an invitation sent) and invited to activate their subscription later.
`ChangeStorage`	Specifies the amount of extra storage to be assigned for a user’s base subscription. The `SubscriptionId` field specifies the base collaboration, mail, or bundled subscription the extra storage is associated with. Use the `collabExtraStorage` or `mailExtraStorage` fields to specify the amount of extra storage to be assigned. An available extra storage subscription with enough space to fulfill the requested amount is required.

Provisioning change file operation fields

The first line of the provisioning change file contains required header information; subsequent lines contain field values as described in the following table. When you encode the change file contents, include user-specific field data for the required provisioning operations. Each line must end with the appropriate line feed or carriage return to ensure that line endings are processed correctly during FTP transfer. See Examples: User provisioning change files for details.

Table 3. Provisioning file operation field names and descriptions
Field name	Field value description	Required or optional per operation
`EmailAddress`	Specifies the email address to be used when the user logs in.	This field is required by all operations. The character limit is 254.
`Action`	Specifies the operation to be processed; see preceding table for operation names and descriptions.	This field is required by all operations.
`SubscriptionId`	Specifies the subscription that the user is to be entitled to use. `RevokeSeat` is the only operation that enables you to specify the keyword `COLLAB`, `MAIL`, `BUNDLE`, `TRAVELER`, `IBM_DOCS`, or `RETENTION` to reference a collaboration, mail, bundled, or accessory subscription that is already assigned to the user. `ChangeSeat` is the only operation that takes the subscription keywords `DELETECOLLAB` and `DELETEMAIL` (used when you change from a bundle to a single subscription). Your subscription ID is in the Organization Account: Subscription section of the Administration user interface. Select your subscription name and use the value that is assigned to your subscription for the `SubscriptionId` value.	This field is required by the `AssignSeat` and `ChangeSeat` operations and is optional for the `Add`, `AddStorage`, and `RevokeSeat` operations.
`SubscriptionId2`	Specifies a second internal identifier for the subscription that the user is to be entitled to use on an `Add` operation.	This field is optional for the `Add` and `ChangeSeat` operations. A `Password` or an `AltEmailAddress` entry is required when you change from a seat that is not a SmartCloud Notes seat to one that is.
`GivenName`	Specifies the user''s given name.	This field is required for the `Add` operation and optional for the `Update` operation. The character limit is 120.
`FamilyName`	Specifies the user's surname.	This field is required for the `Add` operation and optional for the `Update` operation. The character limit is 120.
`Language`	Specifies the user's preferred language.	This field is optional for the `Add` and `Update` operations. The character limit is 5. Note: If no language is specified, the company contact language is used. An administrator specifies the company contact language on their My Account Settings page by using the Localization and Language options.
`TimeZone`	Specifies the user's time zone. See `Time zone values for change files` for legal values.	This field is optional for the `Add` and `Update` operations. The character limit is 30.
`Password`	When an account identify is being established, this one-time password value is used. When the user first logs in they are prompted to set a new password. This password filed value must conform to password standards.	This field is optional for the `Add` operation. Note: For an `Add` operation, this field is required for mail subscriptions regardless of the user's federation type. The character limit is 50.
`AltEmailAddress`	This setting has unique meaning for each of the following provisioning operations: `Add` – If specified, an email invitation is sent to this address to complete establishment of an account identity. The user follows the supplied link to establish their account password. This also specifies the address that is used to send notification if a user's account is updated. `AssignSeat` – Specifies the address that is used to send notification if a user's account is updated. `Rename` – Specifies the new email address.	This field is optional for the `Add` operation. Note: For an `Add` operation, this field is required for mail subscriptions regardless of the user's federation type. This field is required for SmartCloud Notes `AssignSeat` operations and for a `Rename` operations. The character limit is 254.
`NotesTemplate`	Specifies the Notes mail template to be assigned to a SmartCloud Notes mail subscriber in either a hybrid or service-only environment. This field is only applicable for operations that reference SmartCloud Notes mail subscriptions. The name that you specify must exactly match the wanted template name, for example StdR85Mail. Note: If multiple mail templates are available, use the following procedure to determine the template name to assign for the operation: Navigate to the Mail Templates page in SmartCloud Notes administration. Select Custom Mail Templates or Standard Mail Templates. Locate the row that matches the name, location, and version for the user that is being provisioned. Specify the wanted mail template name in the provisioning change file: Copy the Name value exactly as it is shown in the Name column followed by a comma. Copy the most recent Version information exactly as it is shown in the Version column followed by a comma. Append your locale information in the format `xx_XX`. For locale information, refer to Language and Country values for change files. In addition, for supported Notes templates an extension forms file provides a custom experience for SmartCloud Notes web users. Apply extension forms files to current users or to new users as you provision them using the `extension_forms_file` option ("`name,version,locale,extension_forms_file`" format). An extension forms file must be approved and uploaded into the service before you can apply it. For more information, see Using extension forms files to customize the look of the web client. For examples of how to specify these optional values, see Examples: User provisioning change files.	This field is optional for the `Add`, `AssignSeat`, and `Update` operations. The character limit is 255.
`NotesDN`	Specifies the Distinguished Name (DN) to be assigned to a SmartCloud Notes mail subscriber. This field is only applicable for operations that reference SmartCloud Notessubscriptions. Note: SmartCloud Notes subscriptions require a unique user name, which is defined as the specified `NotesDN` value. If a `NotesDN` is not specified, one is generated from the specified, and unique, `GivenName` and `FamilyName` values. After a SmartCloud Notes hybrid user is provisioned by using an integration server `Add` and `AssignSeat` operation, their name cannot be changed, either by an integration server `Rename` operation or manually in the cloud user account. The SmartCloud Notes user name would instead need to be changed in the on-premises environment by specifying a different DN value.	This field is optional for the `Add` and `AssignSeat` operations. The character limit is 255.
`NotesMigration`	If this field is set to `true` or `1`, the availability of mail migration data is verified, and mail file migration is initiated in the background. An error is returned if migration data is not available or if an invalid value is specified.	This field is optional for the `Add` and `AssignSeat` operations. Valid values include: `true` `false` `1` `0` The default value is `false`.
`AssignTo`	Specifies the new (target) subscriber to be given the removed or reassigned resources of the source user. Note: Reassignment of resources is only supported for collaboration subscriptions.	This field is optional for the `RevokeSeat` and `Remove` operations. The character limit is 254.
`Department`	Specifies the user's department designation.	This field is optional for the `Add` and `Update` operations. The character limit is 255.
`JobTitle`	Specifies the `Job Title` field value for the user's profile record.	This field is optional for the `Add` and `Update` operations. The character limit is 100.
`Country`	Specifies the `Country` field value for the user's profile record by using ISO 2 character code values.	This field is optional for the `Add` and `Update` operations. The character limit is 2.
`Telephone`	Specifies the `Telephone` field value for the user's profile record.	This field is optional for the `Add` and `Update` operations. The character limit is 20.
`Mobile`	Specifies the `Mobile` field value for the user's profile record.	This field is optional for the `Add` and `Update` operations. The character limit is 20.
`Fax`	Specifies the `Fax` field value for the user's profile record.	This field is optional for the `Add` and `Update` operations. The character limit is 20.
`Address`	Specifies the `Address` field value for the user's profile record.	This field is optional for the `Add` and `Update` operations. The character limit is 254.
`SuppressInvitation`	In combination with a `SUPPRESS_ALL` value, suppresses the sending of an invitation or notification email to the user. A `ResendInvitation` operation can later be used to send an invitation. If the field is not specified, or if the field value is `SUPPRESS_NONE`, the invitation or notification email is sent (default).	This field is optional. This field applies only to the `Add`, `Update`, and `AssignSeat` operations.
`FederationType`	Species the user's federation type. The following values are available: If the organization federation type is Non-federated, use a user `FederationType` value of `NON_FEDERATED`. If the organization federation type is Federated, use a user `FederationType` value of `FEDERATED`. If the organization federation type is Modified, use a user `FederationType` value of `MODIFIED_FEDERATED`. If the organization federation type is Partial, use a user `FederationType` value of `NON_FEDERATED`, `FEDERATED`, or `MODIFIED_FEDERATED`. If the value does not follow these rules, or is an invalid value, the integration server generates an error. If a value is not specified, the company default federation type is used. If the organization federation type is Partial, then `NON_FEDERATED` is used.	This field is optional for the `Add` and `Update` operations.
`CollabExtraStorage`	Specifies the amount of extra storage, in GBs, of the Files quota for the collaboration subscription ID or bundled subscription ID specified in the `subscriptionID` field. Enter an integer greater than or equal to 0.	This field is optional for the `ChangeStorage` operation.
`MailExtraStorage`	Specifies the amount of extra storage, in GBs, of the Mail quota for the mail subscription ID or bundled subscription ID specified in the `subscriptionID` field. Enter an integer greater than or equal to 0.	This field is optional for the `ChangeStorage` operation.
`Activation`	Adds the specified user, forces a positive verification, and activates the user within the same operation. The keyword is `FORCE_ACTIVATION`. This operation is ideal for users who do not have web access for completing activation, such as SmartCloud Notes subscribers. It is available for federated users for whom you want to force a positive verification and automatically complete activation.	This field is optional for the `Add` operation. The operation is only valid if the user is `FEDERATED` and the organization disabled email verification. Verification is forced. Note: Because email verification must be disabled, ensure that the user is a valid member of an email domain that your organization controls.