This topic covers the administration steps to migrate organizations between instances.
Glossary
- Source organization or instance refers to the current organization or instance you are using.
- Target (destination) organization or instance refers to the organization or instance you are moving to.
Migration Steps
1. Lock the Org/Team to prevent changes
2. Export sourceOrg members
a. Update the OrganiazionID with the source Org ID, in the “curl” in Step b.
b. In Postman, use the Import curl option and add the updated curl below.
Note: The curl replaces <Bluescape domain> in the curl URL appropriately.
curl --location 'https://isam.<Bluescape domain>/api/v3/users/exportUserListToEmail' \
--header 'x-bluescape-internal: 1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data '{
"organizationId": "<OrgID>"
}'
c. In the newly opened window in Postman, select the Authorization tab, then in the left panel, select OAuth2 from the dropdown menu.
d. Paste “{{token}}” in the right panel (shown below). You must authenticate to the source instances.
Note: OAuth2 must be set up prior to these steps. API v3 Postman using GraphQL. Another option is to select the bearer token.
e. Select the Body tab and update/verify the Org ID to the ID of the source Org you are pulling the user details on.
f. Select Send. You should receive a message stating that the CSV will be sent to your email shortly.
f. Check your name.admin@bluescape.com email inbox for the export email.
g. Select User List in the email to open and download the file.
3. Split CSV into multiple based on Org Roles
Note: The file must be saved as a CSV.
a. This is a manual process. Split the users pulled in Step 2 by role into different CSV files. You should have 3 files in total.
i. Admin
ii. Member
iii. Visitor
iv. The Owner role is not required as this should be done during the Org creation process.
b. CSV formatting:
- If using the GUI to bulk add users use the below format:
- If using API to bulk add the users, there is no need to update the format. The format is the same format as the one used by the user to export the CSV file in Step 2.
4. Create the target Org if it has not already been created.
Note: There is no support or checks for SSO for import/export.
a. Obtain the source Org ID and pull the metadata via the CLI.
organizations metadata <Input Org ID>.
b. The metadata on the source Org and the target Org must match.
c. Use the “Create the Org” CLI process as a “template” and add the metadata flags to match the source Orgs metadata:
organizations create -i '{"name":"<OrgName>", "metadata": {"<meatadata_name>: <value> ,"<meatadata_name>": <value>},"ownerId":"<UserID>"}'
d. Create the Org using the updated command, including all the metadata from the source Org in Step 4-c.
e. Manually verify that the source and target metadata match with the CLI command:
Organizations metadata <Input Org ID>
5. Add users to the new Org
Note: Only the Org Owner and Admins can add users to the Org.
Steps via GUI:
a. Log on to the instance.
b. On the left sidebar, select the Team/Org.
c. Select the Members tab, and open the Members page.
d. Select Add Member.
e. In the popup box, select Add with CSV.
f. Select upload file and select the CSV file.
g. Monitor the bulk user add status.
Steps via API
Add members to destOrg using GQL mutation BulkAddMember with organizationRoleId for each CSV file.
Note: The target Org needs to be created before this step takes place.
a. To get the organizationRoleId open the CLI on the instance and run the “Roles” command. It should list all the Roles in the instance and their IDs. Note the organization’s role IDs for later in the process. Example:
b. Update the OrganizationID with the target Org ID and the OrganizationRoleID from the target instance noted in the “curl” in Step 4-c to match the role in the CSV file (from Step 2) you plan on using to import the users. For example, if you plan to import the “Admin”, update the OrganizationRoleID with the instance org admin role ID.
c. In the Postman tool. Use the Import option and add the
curl below.Note: The
curl replaces <Bluescape domain> in the curl URL appropriately.curl --location 'https://isam.<Bluescape domain>/graphql'
--header 'Authorization: Bearer <token>'
--form 'operations="{"query": "mutation BulkAddMember($organizationId: ID!, $input: BulkAddMemberInput!, $memberEmailsCsv: BinaryBlob, $memberEmails: [String!]) { bulkAddMember(organizationId: $organizationId, input: $input, memberEmailsCsv: $memberEmailsCsv, memberEmails: $memberEmails) {id, state, progressInfo { succeeded, failed, percentDone, total }, createdAt, updatedAt, ... on BulkAddMemberJob { assetUrl, organization { id }, owner { id }}}}", "variables": {"organizationId": " **<OrgID> **", "input": {"organizationRoleId":" **<OrgroleID>**"}, "memberEmailsCsv": null }}"'
--form 'map="{"memberEmailsCsv":["variables.memberEmailsCsv"]}"'
--form 'memberEmailsCsv=@"/Users/vjayavelkumar/Downloads/oct csv folder/octVisitor.csv"'
d. Follow Step 2-c and verify you’re authenticating to the target instance/Org.
e. Select the Body tab. Then click on the query in the value column. update/verify the Org ID and the Org Role ID to the IDs of the target Org and instance.
f. In the Body tab, click Select File in the value column and select the CSV file from Step 2. Verify you are using the CSV with the role matching Step 3-a.
g. Select send. You should get the below output that provides the ID needed to check the status.
6. Check Job status GQL adminJob query
a. The bulkadd will give a job in the response, which can be used in the curl below to verify the job status within the ‘adminJob’ query for either ‘Success’ or ‘Failed’ outcomes.
b. Use the curl below to get the job status. Update the URL in the curl with the Job ID from the output of Step 5.
Note: The curl replaces <Bluescape domain> in the curl URL appropriately.
curl --location 'https://isam.<Bluescape domain>/api/v3/adminJobs/<jobID>/asset'
--header 'x-feature-self-serve: 1' --header 'x-bluescape-internal: 1'
--header 'Authorization: Bearer <token>' --header 'Cookie: __cf_bm=8Y6ObjddaU4fkuaqjIAOrr0pdw8yHJDfCQkNCU.sCLc-1697640105-0-Ae6GqhIsP+7bg6Y7x4xeFgSR5L5GMTf83uV7A1VuPvV9NPDdHVQ1lvwNOI5SJu91MBBFGNo6+ltbjk9vit7bHpQ='
--data''
c. Follow step 2-c and verify you’re authenticating to the target instance/Org.
d. Select send.
- The ‘Success’ status indicates that the user was successfully added.
- The ‘Failed’ status implies that the user is already a member of the organization, among other possibilities.
e. Check the number of users and compare from the source to the destination to verify they have the same number of users.
f. Also, do a random check to verify that the user accounts were moved correctly.
7. Enable metadata flag setting to export/import
Use the CLI command organizations metadata<Org ID> <Metadata name>=<value> to enable the needed metadata flag setting to export/import for the organization data:
- enableImportExports, - On both the source and target Orgs
- enableImportOrganizations - On the target Org
- enableExportOrganizations – On the source Org
Note: The workspace import is for a scenario where we want just one workspace imported.
- enableImportExports, - On both the source and target Orgs. If not already enabled
- enableExportWorkspaces - On the source Org
- enableImportWorkspaces – On the target Org
Note: Steps 8 – 13 to confirm the URL used in the curl go to https://config.<Bluescape domain>/ and you can locate the pipefitter_url.
8. Set target Orgs for import provisioning
a. Use the curl below to set the provisioning on the target Org. Update the Source OrgID appropriately.
Note: If importing only workspaces, update the “scope” to “workspace”.
Note: The curl replaces <Bluescape domain> in the curl URL appropriately.
curl --location 'https://pipefitter.<Bluescape domain>/graphql'
--header 'x-bluescape-internal: 1'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
--data '{"query":"mutation ($importOrgid:ID!, $scope:ResourceScope!){\n provisionImport(scope: $scope, organizationId: $importOrgid) {\n id\n scope\n status\n createdAt\n createdBy\n importedAt\n organizationId\n exportUrl\n publicKey\n }\n}\n","variables":{"importOrgid":" **<Source OrgID>**","scope":"Organization"}}'
b. Step 2-c and verify you are authenticating to the target instance/Org.
c. Select the Body tab to verify the Source Org ID and scope are correct.
d. Select send. Note: Record and save the public key in the output for use in later steps.
9. Export sourceOrg
a. Use the curl below to export the source Org data. Update the exportOrgID, Password, and publickey; see step 9-c for more details.
Note: The curl replaces <Bluescape domain> in the curl URL appropriately.
curl --location 'https://pipefitter.<Bluescape domain>/graphql'
--header 'x-bluescape-internal: 1'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
--data-raw '{"query":"mutation orgexport($exportOrgid:ID!, $password:String!, $publicKey:String!){\n createOrganizationExport(\n organizationId:$exportOrgid\n exportPassword: $password\n compressHistory:true\n anonymizeHistory: false\n publicKey: $publicKey\n ) {\n exportUrl\n id\n exportedAt\n targetId\n scope\n createdAt\n createdBy\n status\n compressHistory\n publicKey\n anonymizeHistory\n authorizedEmail\n }\n}","variables":{"exportOrgid":" **<ExportOrgID>**","password":" **<Password>**","publicKey":" **<publickey>**"}}'
b. Follow step 2-c and verify you are authenticating to the source instance/Org.
c. Select the Body tab. Update/verify the below in the variable section.
- ExportOrgID
- Password - Create it, and follow security recommendations. This password is used in steps 10 and 11.
- Public key – This is in the output of step 8.
d. Select “send” and note the “ImportID” from the output for steps 10 and 11.
10. Validate export status
a. Use the curl below to check the export status. Update the “Import ID” from the output in step 9.
Note: The curl replaces <Bluescape domain> in the curl URL appropriately.
curl --location 'https://pipefitter.<Bluescape domain>/graphql'
--header 'x-bluescape-internal: 1'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
--data '{"query":"query {\n import(importId: " **<ImportID>** ") {\n id\n scope\n exportUrl\n status\n createdAt\n createdBy\n publicKey\n }\n}\n","variables":{}}'
11. Import to destOrg
Note: The destination needs to have network access to the source for the destination to be able to stream the export to its local file storage. If needed, verify the traffic is allowed through any firewalls.
a. Use the curl below to import the Org data to the target Org. Update the importID, exportURL, and password.
Note: The curl replaces <Bluescape domain> in the curl URL appropriately.
curl --location 'https://pipefitter.<Bluescape domain>/graphql'
--header 'x-bluescape-internal: 1'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
--data-raw '{"query":"mutation StartImport ($importid:ID!, $exportUrl:String!, $password:String!) {\n startImport(\n importId: $importid\n exportUrl: $exportUrl\n exportPassword: $password\n ) {\n id\n status\n organizationId\n publicKey\n exportUrl\n createdAt\n createdBy\n importedAt\n}\n}\n","variables":{"importid":" **<importID>**","exportUrl":" **<ExportURL>**","password":" **<Password>**"}} **'**
b. Follow step 2-c and verify you are authenticating to the source instance/Org.
c. Select the Body tab. Update/verify the below in the variable section.
- Importid – Noted from the output of step 9
- exportUrl – From the output of step 9
- password – Same as in step 9
12. Validate import status
a. Use the curl below to check the export status. Update the “Import ID” from the output in step 11.
Note: The curl replaces <Bluescape domain> in the curl URL appropriately.
curl --location 'https://pipefitter.<Bluescape domain>/graphql'
--header 'x-bluescape-internal: 1'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
--data '{"query":"mutation validateImport($importid:ID!){\n validateImport(importId: $importid) {\n id\n status\n organizationId\n exportUrl\n scope\n createdAt\n createdBy\n importedAt\n publicKey\n }\n}\n","variables":{"importid":" **<ImportID>**"}}'
b. Follow step 2-c and verify you are authenticating to the source instance/Org.
c. Select the Body tab. Update/verify the importid in the variable section.
d. Select send to validate the import.
13. Publish import
a. Use the curl below to publish/update the target Org with the imported Org data.
Note: The curl replaces <Bluescape domain> in the curl URL appropriately.
curl --location 'https://pipefitter.<Bluescape domain>/graphql'
--header 'x-bluescape-internal: 1'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
--data '{"query":"mutation publishImport($importid:ID!){\n publishImport(importId: $importid) {\n id\n scope\n status\n createdAt\n createdBy\n importedAt\n organizationId\n publicKey\n }\n}\n","variables":{"importid":" **<ImportID>**"}}'
b. Follow step 2-c and verify you are authenticating to the source instance/Org.
c. Select the Body tab. Update/verify the importid in the variable section.
d. Select send to publish the import to the target Org.
14. Check the destination Org in the application
15. Disable the metadata flag setting to export/import
a. Use the CLI command "organizations metadata <Org ID> <Metadata name>=<value>" to disable the needed metadata flag setting to export/import for the organization data from step 7.