Using the site commands

You can use the site commands to check the site on your Developer Portal service, and to export and import an entire site configuration.

About

You can use the site commands to check the health of a portal site, rebuild the cache of a site, and display the login link for an admin account of a site. You can also use them to export the configuration settings for an entire Developer Portal site, and import those settings into another site. For example, you could use the export and import commands to replicate the configuration of a test site into a production site.

Important: If you want to import a site export configuration file, the export file must have been created on the same version of API Connect as the version that you want to import to.

Log in as Provider org:
```
apic login --server management_server --realm provider/identity_provider --username provider_username --password provider_password
```
You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):
```
apic identity-providers:list --scope provider --server platform_api_host_name --fields title,realm
```
For example,
```
apic identity-providers:list --scope provider --server platform_api_host_name --fields title,realm 
total_results: 2
results:
  - title: API Manager User Registry
    realm: provider/default-idp-2
  - title: Corporate LDAP user registry
    realm: provider/corporate-ldap
```
The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default API Manager Local User Registry for login as a member of a provider organization is default-idp-2.
For full details of the apic login command, see Logging in to a management server.

For a summary of the general-purpose commands and their use, see Developer Portal CLI commands.
Check the site on your portal service. This command checks the file system, database, and API Manager on your portal site, which might identify platform-related problems on your portal site.
```
apic --mode portaladmin site:check  --server management_server --catalog catalogid/name --org orgid/name --format format_type
```
- management_server is the endpoint URL of the management server (required).
- catalogid/name is the ID or name of the catalog that the site belongs to (required).
- orgid/name is the ID or name of the provider organization that the catalog belongs to (required).
- format_type is the output format. Can be json, yaml, go-template=..., go-template-file=.... Defaults to yaml.

Rebuild the cache of a specific portal site.

apic --mode portaladmin site:cache-rebuild  --server management_server --catalog catalogid/name --org orgid/name

For example:

apic --mode portaladmin site:cache-rebuild --server management_server --org ibm --catalog portal-test
[success] Cache rebuild complete.

Display the state of a portal site associated with a particular organization and catalog. This command is useful as a general health check of the site.

apic --mode portaladmin site:state --server management_server --catalog catalogid/name --org orgid/name --format format_type

apic --mode portaladmin site:state --server my.management.server.com --org ibm --catalog portal-test --format json
{
    "alias": "ibm.portal-test.my.management.server.com",
    "check_state": "OK: 200",
    "content_refresh_required": false,
    "known_to_apim": 1,
    "platform": "platform_devportal_9_x_10_99_99_99_20210922_2000",
    "snapshot_first_requested": "0000-00-00 00:00:00",
    "snapshots_failed_processing_since_last_success": 0,
    "snapshots_requested_since_last_received": 0,
    "state": "INSTALLED",
    "subscribed_to_webhooks": true,
    "url": "my.management.server.com/ibm/portal-test",
    "uuid": "cc0ad766-e372-4988-9d45-744eb8d381de.1cd9dc41-b08d-xyz"
}

Log in to your Developer Portal admin with a link. This command displays a one time login link for the admin account for your Developer Portal site that is specified by the catalog and organization.

 apic --mode portaladmin site:login-link  --server management_server --org ibm --catalog portal-test
sample output:
https://my.portal.server.com/ibm/portal-test/user/reset/1/12345678901/ABCde1f2gH3ijKL-4M_NOPqrs5TU6VWxy7ZABCDEFg7h8/new/login

Export your entire site configuration by using the following site:create-export command. This command creates an export task that returns a .tgz file containing the site configuration. By default, the command polls the status of the task every 10 seconds until the task is finished, at which point the export file is returned. Note that exporting all of your site configuration can take a long time to complete.
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name site:create-export
```
Where:
- --no-poll is an optional flag meaning that the command won't poll the status of the task, but instead just returns the task ID. This task ID can then be used with the site:get-export command to return the export file.
Note: The command continues to poll until the maximum polling time of 15 minutes is reached. At which point you can use the commands site:get_export_status and site:get-export to get the status and, if the task has finished, an artifact.
For example:
```
apic --mode portaladmin --server my_management_server --org my_org --catalog my_catalog site:create-export
201 CREATED - Task ID: vfg6b8utjtw51

Response Code - 202:

Message(s) - 
The status of this task is: QUEUED

Response Code - 202:

Message(s) - 
The status of this task is: RUNNING

Response Code - 202:

Message(s) - 
The status of this task is: RUNNING

Response Code - 200:

Message(s) -
The status of this task is: FINISHED and the artifact can now be streamed

Saving File (Large files may take a while)...
Incoming project saved to site_createExport-20231013154023.tgz
```
The command saves the export file to your running directory. The export .tgz file includes a site-content.tgz file, and a site-config.tgz file. The export file will also include a site-custom-themes.tgz, or a site-custom-modules.tgz file, or both, depending on whether the site contains any custom themes or custom modules.
If you ran the site:create-export command with the --no-poll option, you can use the following commands to manage your site export.
- site:delete-export
  Cancels any currently running site:create-export tasks, and deletes any related artifacts. For example:
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name site:delete-export --task_id task_id
```
  Where task_id is the ID of the export task on the queue.
- site:get-export
  Streams the content of a specific completed export task to a .tgz file. For example:
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name site:get-export --task_id task_id
```
- site:get-export-status
  Returns the status of a specific export task. For example:
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name site:get-export-status --task_id task_id
```

Import your site configuration by using the site:create-import command. This command launches an import polling task that polls the status of the task every 10 seconds until the task is finished, at which point a summary of the import is returned. If the command is run with the --no-poll option, the task doesn't return the status of the task, but just returns the task ID.

Important: If you want to import a site export configuration file, the export file must have been created on the same version of API Connect as the version that you want to import to.

apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name site:create-import export_file_name

Where:

export_file_name is the name of the export file that you want to import. You can import .tgz files that were created by using the site:create-export command.
--no-poll is an optional flag meaning that the command won't poll the status of the task, but instead just returns the task ID. This task ID can then be used with the site:get-import-status command to get the status of the task.

Note: The command continues to poll until the maximum polling time of 15 minutes is reached. At which point you can use the command site:get-import-status to get the status of the task.

In the following example, the export file from Step 6 is imported into a production Developer Portal site on a different server:

apic --mode portaladmin --server my_management_server2 --org my_prod_org --catalog my_prod_catalog site:create-import site_createExport-20231013154023.tgz
Loading File (Large files may take a while)...

201 CREATED - Task ID: 1z8e9zthfkhwdxh2

Response Code - 202:

Message(s) - 
The status of this task is: QUEUED

Response Code - 202:

Message(s) - 
The status of this task is: RUNNING

Response Code - 202:

Message(s) - 
The status of this task is: RUNNING

Response Code - 202:

Message(s) - 
The status of this task is: RUNNING

Response Code - 200:

Message(s) - 
2023-10-11 10:50:05: CLI task (site:import) starting.
2023-10-11 10:50:08: Performing a whole site import
2023-10-11 10:50:08: 1. Importing Site's Configuration
2023-10-11 10:50:41: 2. Importing Site's Content
2023-10-11 10:51:30: [notice] [1/30] - [node.page:1] "Terms of use" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/tsandcs)
 [notice] [2/30] - [node.page:2] "Privacy Policy" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/privacy)
 [notice] [3/30] - [node.faq:3] "Using our APIs" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/node/3)
 [notice] [4/30] - [node.faq:4] "Apps" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/node/4)
 [notice] [5/30] - [node.page:5] "AsyncAPI" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/asyncapi)
 [notice] [6/30] - [node.page:6] "Kafka" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/asyncapi-kafka)
 [notice] [7/30] - [node.page:7] "MQ" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/asyncapi-mq)
 [notice] [8/30] - [node.article:17] "This is an article" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/node/17)
 [notice] [9/30] - [node.article:20] "article 2" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/node/20)
 [notice] [10/30] - [node.page:23] "Basic page 1" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/node/23)
 [notice] [11/30] - [block_content.basic:1] "No Apps Found [en]" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/content/block/1)
 [notice] [12/30] - [block_content.basic:2] "No Apis Found [en]" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/content/block/2)
 [notice] [13/30] - [block_content.basic:3] "No Products Found [en]" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/content/block/3)
 [notice] [14/30] - [block_content.basic:4] "No Blogs Found [en]" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/content/block/4)
 [notice] [15/30] - [block_content.basic:5] "Welcome Banner [en]" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/content/block/5)
 [notice] [16/30] - [block_content.basic:6] "Getting Started [en]" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/content/block/6)
 [notice] [17/30] - [block_content.basic:7] "Get Help [en]" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/content/block/7)
 [notice] [18/30] - [block_content.basic:8] "Forum Sidebar [en]" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/content/block/8)
 [notice] [19/30] - [menu_link_content:1] "Home" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/structure/menu/item/1/edit)
 [notice] [20/30] - [menu_link_content:2] "API Products" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/structure/menu/item/2/edit)
 [notice] [21/30] - [menu_link_content:3] "Apps" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/structure/menu/item/3/edit)
 [notice] [22/30] - [menu_link_content:4] "Forums" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/structure/menu/item/4/edit)
 [notice] [23/30] - [menu_link_content:5] "Sign in" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/structure/menu/item/5/edit)
 [notice] [24/30] - [menu_link_content:6] "Create account" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/structure/menu/item/6/edit)
 [notice] [25/30] - [menu_link_content:7] "Contact" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/structure/menu/item/7/edit)
 [notice] [26/30] - [menu_link_content:8] "Terms and Conditions" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/structure/menu/item/8/edit)
 [notice] [27/30] - [menu_link_content:9] "Privacy Policy" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/structure/menu/item/9/edit)
 [notice] [28/30] - [shortcut.default:1] "Add content" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/config/user-interface/shortcut/link/1)
 [notice] [29/30] - [shortcut.default:2] "All content" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/admin/config/user-interface/shortcut/link/2)
 [notice] [30/30] - [taxonomy_term.forums:1] "General discussion" - Updated (https://portal.ibm.com/apim-portal-org2/test-google/taxonomy/term/1)
2023-10-11 10:52:38: CLI task (site:import) completed successfully.

The message section provides detailed information about the import as the configuration is being imported.

If you ran the site:create-import command with the --no-poll option, you can use the following commands to manage your content import.
- site:delete-import
  Cancels any currently running site:create-import tasks, and deletes any related artifacts. For example:
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name site:delete-import --task_id task_id
```
  Where task_id is the ID of the import task on the queue.
- site:get-import-status
  Returns the status of a specific import task. For example:
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name site:get-import-status --task_id task_id
```