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
customerId_sourceId_prv_seqnum.csv
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:
|
- 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.
Provisioning change file operations
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:
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.
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:
|
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:
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:
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 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.
|