Working with Configuration Files

Configuration files can be managed and deployed using Configuration Hub by uploading a JSON file which contains configuration data. You can upload up to 10 configuration files. Uploading a configuration file can be used for:

Migration of converted IdentityIQ configurations.
If there are previously exported configurations but there is no access to the tenant.
Migration of configurations between tenants in different domains or regions.
Uploading configurations that were shared by various communities.

Uploading a Configuration File

To upload a configuration file:

On the Configuration Upload page of Configuration Hub, select Upload.

Note

The only supported file that can be uploaded is a .JSON file with a valid sp-config downloaded export file format. The file must be in the same format as the .JSON that is returned by GET /beta/sp-config/export/{id}/download or it can be copied from a draft within Configuration Hub. The format should look like this:

{
    "objects": [
        {
            "jwsHeader": null,
            "jwsSignature": null,
            "version": 1,
            "self": {
                "type": "ROLE",
                "id": "2c9180867fbcdcd9017fbd7745210210",
                "name": "Role 1"
            },
            "object": {
                "id": "2c9180867fbcdcd9017fbd7745210210",
                "name": "Role 1",

                                ...

                "created": "2022-03-24T19:46:24.673Z",
                "modified": "2023-05-03T18:13:05.727Z",
                "description": "Role 1"
            }
        }
    ]
}

Provide a name for the uploaded file.
Either drag and drop the file or select a file to upload it.
Select Submit.

When your configuration file is uploaded, it will appear in the list of uploads and be marked as "Latest".

An uploaded configuration file can be managed as any other backup file in configuration hub. Select Actions on the uploaded file to view the summary, prepare the draft for deployment, or to delete the uploaded file.

You can also substitute attribute values of an uploaded configuration file by using the Object Mapping feature to add rules to the Default mapping set.

Creating a Configuration Draft

A configuration draft captures the differences between the selected backup configuration and the live configurations in your target tenant at the time the draft was prepared.

Notes

Draft creation can be performed from backups which contain up to 30,000 objects. To enable drafts from larger backups, contact SailPoint Support.
You can have up to 10 drafts at a time. Creating a new draft automatically deletes the oldest draft that hasn't been deployed when you reach this limit.

Go to the Configuration Backups page of the Configuration Hub, select Actions on the backup row, and select Prepare Draft for Deployment.

You can also initiate a draft creation from the backup's View Summary overlay.
Specify a Draft Name that describes the intent of this draft. This is especially important if you are not deploying it immediately, as you may be working with multiple drafts at once for different purposes.
Select Create Draft to initiate the comparison. When that completes, the draft is automatically saved and its summary is displayed.

The Draft Summary shows how deploying the draft to your tenant will alter your tenant's configurations.

During the draft creation, Configuration Hub will apply various system rules and logic to handle configuration object dependencies, identify reference issues, and resolve object references. This is done by using the name and type of referenced objects to match and substitute object IDs with the corresponding ID of the object in the target tenant.

Important

If an object only includes the Object ID and not a name, Configuration Hub is not able to identify or resolve the reference issue until the configuration is deployed. If objects are not referenced by ID, manually modify the draft prior to deployment.

Viewing a Draft Summary

The Draft Summary is a presentation of the deployment plan. On the draft summary page, a user can easily view all modifications to the draft and its objects. The following are the columns that signify the changes.

Adds to Live represents objects in the backup that don't exist in the live tenant and will be added to the live tenant configuration settings if the draft is deployed.
Modifies to Live represents live objects that will be changed to match the backup's representation of the same configuration object.
Not in Backup represents objects in the live tenant that don't exist in the backup. This is usually because these objects were created in the live environment after the backup took place.
Reference Issues - This column appears when there are reference issues for an object. The user can view a detailed error message to understand the issue.

Note

Selecting a number in the desired column will open the specific object type tab.

You can also edit your draft objects from this summary.

Note

During a draft creation, if problems are detected in a draft object that will prevent successful deployment, the object and its object type will be marked with Reference Issues. In most cases, this is caused by references to other objects which do not exist in the tenant, such as an owner identity that has been deleted.

The Draft Summary page also allows you to request approval of the modifications on this draft. To request approval of the draft changes, select Request Approval at the top of the page.

Note

By default, requesting approval is disabled. To enable this feature, go to Advanced Settings > Feature Enablement and toggle the Approvals feature to Enabled.

Once selected, provide a summary of the changes in the approval window and select Submit.

Note

Once a draft is submitting for approval, it can no longer be edited while it is waiting for approval.

If additional changes need to be made to the draft an approval request was submitted too early, select Cancel Request to cancel the approval.

Once an approval request is submitted, anyone with the Configuration Hub Admin user level can go to the draft and select either Approve or Deny at the top of the draft page.

Editing a Draft

You can select a specific Object Type to edit and remove objects from the draft that you don't want to deploy to your live tenant. You can also edit object details before deploying.

To edit a draft that was previously, select Actions on the draft row to edit or delete a draft.

Editing a draft begins at the Draft Summary of a draft you just created or of a saved draft.

To remove all configuration objects of any object type from a draft, clear the checkbox on that row of the Draft Summary table. For example, you could remove all Source objects from the draft.
To view or modify the list of the draft's configuration objects for any type, select Edit on that row. Objects are grouped into tabs according to whether they will be added to or modified in the live tenant when deployed.
To remove an individual object from the draft, clear the checkbox on that object's row.
To change details about an object, select Edit on that row, modify its JSON definition, and select Save. The JSON is validated on save to prevent JSON errors.

When editing a draft object, multiple views display:
- Edit View - You can see already made modifications in Changes in Object. You can also edit the object definition in Draft Object and see the changes live in Changes in Object.
- Change Log - Tells you the type of modification as well as the live and draft values.
- Rule Substitution - Lists the attribute value substitutions that are automatically applied to the draft.
- JSON View - Allows you to edit in Draft Object, while showing you what is currently live.
Important
- You cannot edit or remove the id of the object.
- Your edits will only be saved to the draft when you save your changes on the Draft Summary page.
- When you are finished making changes to individual objects, select Back to Draft Summary to return to the summary page.
Select Save Changes.
Notes
- When you save changes to your draft, any objects or object types that you removed from the draft are permanently deleted from it. If you discover you made a mistake, you must create a new draft from the backup and start again.
- The backup itself is never modified by actions you take on the draft.
To cancel your changes without updating the draft, select Discard Changes.

Deploying a Draft

Deploying a draft to your live tenant adds or updates configuration objects in your tenant to match the ones in the draft.

Before deploying a draft, carefully review the new and edited objects within the draft to confirm the correct configuration is being deployed. Follow your organization's change management and approval process when deploying any draft configuration.

Note

Drafts containing up to 5,000 objects can be deployed. To enable deployment of larger drafts, contact SailPoint Support.

Important

Draft deployment does not automatically delete objects from the live tenant. The Not in Backup list is provided as a reference and includes objects that exist in the live tenant, but not in the backup. If necessary, these objects can be manually deleted within your live environment.

Deploying a draft begins at the Draft Summary of a draft you just created or edited, or of a saved draft.

To select a saved draft, go to the Configuration Drafts page of the Configuration Hub, select Actions on the draft row, and select Edit.
Select Deploy Draft to update your tenant's configurations from the draft. Select Deploy to confirm.
When deployment finishes, review the completion status and process details. The details contain the name and ID of each deployed object along with any errors or warnings encountered.
Important

These objects require manual actions after deployment to restore their connections to other configurations.
- Password policies must be manually reconnected to sources. This includes redefining any exception policy filters.
- Service desk integrations must be manually reconnected to virtual appliances.

Promoting a Backup

Promoting a backup means taking a configured backup of a connected source tenant and deploying it to the current target tenant.

To do this, log into the target tenant, select a connected tenant, and follow the steps that are outlined in Deploying a Draft.

Documentation Feedback

Feedback is provided as an informational resource only and does not form part of SailPoint’s official product documentation. SailPoint does not warrant or make any guarantees about the feedback (including without limitation as to its accuracy, relevance, or reliability). All feedback is subject to the terms set forth at https://developer.sailpoint.com/discuss/tos.