Import, Export and Modify a User Sync Configuration

This tutorial explains how to download (export) an existing User Sync connector configuration, how to upload (import) it back again, and how to modify (if needed) it and upload it back again.

That way you could re-use parts of existing configurations, i.e. on a staging server, without creating everything again by hand.
Normally this only makes sense, if you've added a lot of transformation rules across the config.

In our tutorial, we will show you two solutions. You can use REST API or a cheat code to get access to the JSON configuration file directly.

REST API

Export Configuration - REST

1. Find the User Sync connector ID by clicking on the edit button first, go to Connector Id and Directory, and copy the Connector ID.
   
   

   

   
   
   

cURL

GET the connector configuration. The URL to retrieve the config looks like this, with the connector ID at the end:

You could also directly create a JSON file with the content of the connector configuration. In our example, we will create a JSON file called 'usersync_export.json' in the directory '~/Downloads/'

Postman

1. GET the connector configuration. The URL to retrieve the config looks like this, with the connector ID at the end:

   1. https://<basurl>/rest/samlsso-admin/1.0/usersync/connector/68e7f826-af8d-43f3-b303-4d3a28e83993

   
   

2. Use a local user and password (or API Token) with admin permissions for the Basic Auth. REST doesn't work with SAML.
   
   

Modify Configuration - REST

1. Extract the configuration from the response

   1. not everything in the response from the call above is the configuration, you only need to preserve the configuration node of the JSON response

   2. We recommend pasting the response to a config.json file and opening it in a text editor like Notepad++ or any other editor that highlights opening and closing brackets

   3. the below example shows the part that requires to be extracted, the value of the configuration field, including the curly brackets

      1. some child nodes have been collapsed for better readability
         
         

         

2. Copy that part, paste it to a new file, and edit it as required

   1. in the sample below, I've changed the connector name and added a transformation
      
      

      

Import Configuration - REST

cURL

PUT (import) the edited configuration back to your instance. If you import a modified configuration it is important that your JSON file only contains the configuration node of the connector.

Postman

1. Copy the edited configuration and paste it back to Postman...

   1. ... into the Body tab with the radio button at "raw" and As JSON

   2. change the request method to PUT and press send
      
      

      

      
      
      

   3. you should get a 200 OK Result and see the complete response again 
      
      

      

   4. checking the User Sync connector via the UI after refreshing the page should reflect the changes
      
      

      

JSON

Export Configuration - JSON

1. Open the User Sync connector, you want to export, by clicking on the edit button first.

1. Just type the cheat code 'godmode' to open a new dialog with the JSON-data.

1. Extract the configuration from the response
   

   1. We recommend pasting the response to an us-export.json file and opening it in a text editor like Notepad++ or any other editor that highlights opening and closing brackets

us_json_export_json-file

Modify Configuration - JSON

1. Open the us-export.json file in a text editor like Notepad++ or any other editor that highlights opening and closing brackets.

2. Not everything in the file is the configuration, you only need to preserve the configuration node of the JSON response

3. Edit the file as required

   1. in the sample below, I've changed the connector name and added a transformation

us_json_modify_json-file

Import Configuration - JSON

Create a new connector.

You don't need to start any configuration. Only type the cheat code 'godmode' again.

1. Delete the current configuration, which you see in the current connector configuration dialog.

2. Copy & Paste your saved (or modified) configuration into the dialog.

3. Apply the dialog (just press Close)

4. Save and Return the User Sync Connector configuration.

5. Checking the User Sync connector via the UI after refreshing the page should reflect the changes

Patch a connector configuration

It's possible to update specific parts of the configuration using HTTP PATCH. This can be done either using JSON Merge Patch (RFC 7686) or JSON Patch (RFC 6902).

JSON  Patch

To update specific values, send a JSON patch (see https://jsonpatch.com/) as HTTP Patch with content-type application/json-patch+json

JSON Merge Patch

JSON Merge patch allows to just specify the JSON-fragment that should be changed (see https://datatracker.ietf.org/doc/html/rfc7386). To use this syntax, send the JSON as HTTP Patch with content-type application/merge-patch+json.