Refreshing Sandboxes for On-Site SugarIdentity-Enabled Instances

Overview

A sandbox is a replica of your Sugar instance that can be used to test version upgrades and application changes without putting your live production instance at risk. For on-site Sugar instances that are enabled for SugarIdentity, you can back up the SugarIdentity settings and restore them after refreshing the sandbox database from your live production instance or a backup. This article covers how to refresh the sandbox environment when using SugarIdentity for your on-site instance.

Steps to Complete

There are two way to refresh your on-site sandbox instance:

• Using SQL Queries (You must be familiar with how to use SQL queries)
• Using the SugarCRM REST API

Using SQL Queries

Use the following steps to refresh your on-site sandbox instance using SQL queries:

1. Run the following SQL query:

   SELECT * FROM config WHERE category = 'idm_mode'; 

2. Export the results of this query as a SQL INSERT statement and save it to a file.
3. Run the following SQL query:
   

   SELECT * FROM `config` WHERE category="FeatureFlags" 

4. Export the results of this query as a SQL INSERT statement and save it to a file.
5. Now, refresh the sandbox database from your production environment or backup.
6. Once the refresh has been completed, run the SQL queries from step 2 followed by step 4 to restore the SugarIdentity settings.

Using the SugarCRM REST API

To refresh the sandbox instance using the SugarCRM REST API, the curl command line tool must be installed. Alternatively, you can use any other tools that can send HTTP requests, if you are familiar with how to use it.

Use the following steps to refresh your on-site sandbox instance using SugarCRM REST API:

1. To authenticate with the SugarCRM REST API, first retrieve an access token by sending a request to the /oauth2/token endpoint:
   Request:
   

   curl --location 'https://example-142.msqa.sugarcrm.com/rest/v11_17/oauth2/token' --form 'client_id="sugar"'  --form 'grant_type="password"'  --form 'username="admin"'  --form 'password="password"' 

   Response:
   

   {"access_token":"0LuUHQ4sSmFS6j4VlmKpEup-mOuyyT0WA1OF1xWsRhDYmrjmovpIk0BRPltpQM1xpa-2EPByZcINNIAKMYZqhICM7KTZYXDE2EXDkiZjXupucGxIw8CYQpja2zCCibywVxEwcGYXf","expires_in":299,"token_type":"bearer","scope":"offline https:\/\/apis.sugarcrm.com\/auth\/crm profile email address phone","refresh_token":"0LuUHQ4sSmFS6j4VlmKpEvl-mMuLxF4ZC2eU5Q6_EyHXh9nn19JdsFAJZVdXcM0hk76pA8FYZdwEMcAcWOdq6KGrzIjoWlXi2FDdmVR2U-ZHSgR3mNG6dojmny_N3a6pfxE5RGU-VOZoxGg7ClicFqq1cGCAAc12DB7br5ske-1XW1N0","refresh_expires_in":1209600,"download_token":"0LuUHQ4sSmFS6j4VlmKpEup-mOuyyT0WA1OF1xWsRhDYmrjmovpIk0BRPltpQM1xpa-2EPByZcINNIAKMYZqhICM7KTZYXDE2EXDkiZjXupucGxIw8CYQpja2zCCibywVxEwcGYXf"} 

2. Once the access token has been obtained, copy the access_token value. You will need this value for authorization in the next step.
3. Use the SugarCRM REST API to send a GET request to the appropriate endpoint to obtain the current SugarIdentity settings. Be sure to include the access token value from step 2 in the authorization header.
   Request:
   

   curl --location 'https://example-142.msqa.sugarcrm.com/rest/v11_17/Administration/config/idm_mode' --header 'Authorization: Bearer <access token from step 2>'  

   Response:
   

   {"idm_mode_allowedSAs":["srn:stage:iam:us-west-2:9999999999:sa:user-sync","srn:stage:iam:us-west-2:9999999999:sa:sugar-connect","srn:stage:iam:us-west-2:9999999999:sa:user-sync-kafka"],"idm_mode_clientId":"clientId","idm_mode_clientSecret":"clientSecret","idm_mode_cloudConsoleRoutes":{"passwordManagement":"authentication\/local","userCreate":"users\/new","userProfile":"users","forgotPassword":"forgot-password"},"idm_mode_cloudConsoleUrl":"https:\/\/console-us-west-2-stage.service.sugarcrm.com","idm_mode_crmOAuthScope":"https:\/\/apis.sugarcrm.com\/auth\/crm","idm_mode_discoveryUrl":"https:\/\/discovery-stage.service.sugarcrm.com","idm_mode_enabled":1,"idm_mode_idpUrl":"https:\/\/login-us-west-2-stage.service.sugarcrm.com","idm_mode_requestedOAuthScopes":["offline","https:\/\/apis.sugarcrm.com\/auth\/crm","profile","email","address","phone"],"idm_mode_stsKeySetId":"keySetId","idm_mode_stsUrl":"https:\/\/sts-stage.service.sugarcrm.com","idm_mode_tid":"tenant","idm_mode":true} 

4. Save the response returned by the API as it contains the current SugarIdentity settings and will be required later to restore the settings after the sandbox refreshes.
5. Use the SugarCRM REST API to send a GET request to the appropriate endpoint to obtain the current SugarIdentity features. Be sure to include the access token value from step 2 in the authorization header.
   Request:
   

   curl --location 'https://example-142.msqa.sugarcrm.com/rest/v11_17/Administration/config/FeatureFlags' --header 'Authorization: Bearer <access token from step 2>' 

6. Save the response returned by the API as it contains the current SugarIdentity features and will be required later to restore the settings after the sandbox refreshes.
7. Refresh the sandbox database by restoring it from the production environment or a backup, as required.
8. After restoring the sandbox database, retrieve a new access token from the /oauth2/token endpoint, as covered in step 1 of this section.
   Note: Changes to passwords stored in SugarIdentity are not synced to the local database, so administrators may need to update their credentials.
9. Copy the new access_token value obtained in step 8. You will need this token for authentication in the next API requests.
10. Use the saved SugarIdentity settings (in step 4) and apply them to the restored sandbox database by sending a POST request to the Administration/config/idm_mode SugarCRM REST API endpoint. Include the new access_token for authentication.
    Request
    

    curl --location 'https://ddolbik-142.msqa.sugarcrm.com/rest/v11_17/Administration/config/idm_mode'  
    
    --header 'Content-Type: application/json'  
    
    --header 'Authorization: Bearer <token from step 7>'  
    
    --data 'Response from, step 4' 

11. Use the saved SugarIdentity features from step 6 and apply them to the restored sandbox database by sending a POST request:
    

    curl --location 'https://example-142.msqa.sugarcrm.com/rest/v11_17/Administration/config/FeatureFlags' -header 'Content-Type: application/json' --header 'Authorization: Bearer <token from step 7>' --data 'Response from, step 6' 

Once these steps are completed, your Sugar instance should be enabled for SugarIdentity and point to your existing sandbox tenant.

Troubleshooting Errors

User Data Discrepancy

Once your sandbox is refreshed from your production instance, if you notice that the user data in the SugarCRM database does not match the current user data in SugarIdentity, please file a case with the Sugar Support team for assistance in syncing your data.

Sugar Login Error

If you see the following error message when logging in to your Sugar account, this indicates that the site_url specified in config.php does not match the Sugar URL used when activating your instance:

• Requested URL does not match any rules

To resolve this error, you will need to update the site_url in the config.php file to match the Sugar URL used when activating SugarIdentity.