Using the export-entity commands

You can use the export-entity commands to manage the export of content entities from your Developer Portal site.

About

The Developer Portal is based on the Drupal content management system. In Drupal, a content entity is an item of content data that is intended to be displayed to site users, such as text, images, and HTML markup. Content entities are grouped into entity types, and most of these entity types are also subdivided into entity subtypes, also known as bundles. The export-entity commands enable you to create a predefined list, called an export entity, of all of the content entities that you want to export. You can create multiple export entities, each one containing its own set of assorted entity types. Export entities persist, so you can add content and remove content as required.

If you want to export only one type of content entity, or all of the content entity types, at a time, you can use the content commands; see Using the content commands for more information. You also use these commands when you want to import your entity content.

Procedure

Log in as Provider org as seen in the following example.
```
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 mgmt_endpoint_url --fields title,realm
```
For example,
```
apic identity-providers:list --scope provider --server myserver.com --fields title,realm 
total_results: 2
results:
  - title: API Manager Local 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.
Create an export entity by using the following export-entity:create command. This command creates a container for the entity content that you want to export.
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name export-entity:create --export_entity_name "export_entity_name"
```
Where:
- management_server is the endpoint URL of the management server (required).
- orgid/name is the ID or name of the provider organization that the catalog belongs to (required).
- catalogid/name is the ID or name of the catalog that the site belongs to (required).
- export_entity_name is the name of the export entity that you want to create. Note that this name is not a unique identifier.
The command returns an ID for the newly created export entity. For example:
```
apic --mode portaladmin --server my_management_server --org my_org --catalog my_catalog export-entity:create --export_entity_name "Main Content"
[notice] Created new export entity Main Content, id 5
```
Make a separate note of the ID number that is returned, as you will need this ID for future commands.

List all of the export entities that are available for your site by using the following export-entity:list command.

apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name export-entity:list

The command returns a list of the available export entities, including their ID, and the date and time that they were created. For example:

apic --mode portaladmin --server my_management_server --org my_org --catalog my_catalog export-entity:list
-
  id: '5'
  name: 'Main Content'
  created_time: '2023-09-12 15:05:04'

Add content to an export entity by using the following export-entity:add-content command.

apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name export-entity:add-content --export_entity_id export_entity_id --entity_type entity_type_name --entity_ids entity_ids

Where:

export_entity_id is the ID of the export entity (required).
entity_type_name is the type of content entity that you want to add to the export entity (required). You can use the content:list-types command to find out the type of content entities that are exportable from your site; see Using the content commands.
entity_ids is a comma separated list of the entity IDs that you want to add to the export entity (optional). If you want to add all of the content entities for a particular entity type, you don't need to set any entity IDs.

The following example shows three different types of entity content being added to the export entity 5:

apic --mode portaladmin --server my_management_server --org my_org --catalog my_catalog export-entity:add-content --export_entity_id 5 --entity_type node --entity_ids 1,2
[notice] Successfully added entity type node - "1, 2" to export entity 5

apic --mode portaladmin --server my_management_server --org my_org --catalog my_catalog export-entity:add-content --export_entity_id 5 --entity_type block_content --entity_ids 1,2
[notice] Successfully added entity type block_content - "1, 2" to export entity 5

apic --mode portaladmin --server my_management_server --org my_org --catalog my_catalog export-entity:add-content --export_entity_id 5 --entity_type shortcut --entity_ids 1
[notice] Successfully added entity type shortcut - "1" to export entity 5

Delete content from an export entity by using the following export-entity:remove-content command.
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name export-entity:remove-content --export_entity_id export_entity_id --entity_type entity_type_name --entity_ids entity_ids
```
Where:
- export_entity_id is the ID of the export entity (required).
- entity_type_name is the type of content entity that you want to remove (required).
- entity_ids is a comma separated list of the entity IDs that you want to remove (optional). If you want to remove all of the content entities for a particular entity type, you don't need to set any entity IDs.
For example, to remove entity ID 1 of the content entity type shortcut from the export entity 5, you can run the following command:
```
apic --mode portaladmin --server my_management_server --org my_org --catalog my_catalog export-entity:remove-content --export_entity_id 5 --entity_type shortcut --entity_ids 1
[notice] Successfully removed entity type shortcut - "1" from export entity 5
```

View the content details of an export entity by using the following export-entity:get command. This command returns a list of all of the content entities in a specific export entity ID, and is the entity content that will be exported if the export-entity:launch command is run on that ID.

apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name export-entity:get --export_entity_id export_entity_id

In the following example, export entity 5 contains four different content entities:

apic --mode portaladmin --server my_management_server --org my_org --catalog my_catalog export-entity:get --export_entity_id 5
- bundle: basic
  id: "1"
  title: No Apps Found [en]
  type: block_content
- bundle: page
  id: "1"
  title: Terms of use
  type: node
- bundle: basic
  id: "2"
  title: No Apis Found [en]
  type: block_content
- bundle: page
  id: "2"
  title: Privacy Policy
  type: node

Export your content entities by running the following export-entity:launch command. This command launches an export entity polling task that creates a .tgz file of all of the entities that are contained in a specific export entity. By default, the command polls the status of the task every 30 seconds until the task is finished, at which point the export file is returned. If the command is run with the --no-poll option, the task doesn't return a .tgz file, but just returns the task ID.
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name export-entity:launch --export_entity_id export_entity_id
```
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 export-entity:get-export command to return the export file.
Note: The command continues to poll until the maximum polling time of 25 minutes is reached. At which point you can use the commands export-entity:get_export_status and export-entity:get-export to get the status and, if the task has finished, an artifact.
The export-entity:launch command can be run multiple times, and the content of the export entity updated as required by using the export-entity:add-content and export-entity:remove-content commands.
The following example exports the contents of export entity 5:
```
apic --mode portaladmin --server my_management_server --org my_org --catalog my_catalog export-entity:launch --export_entity_id 5
201 CREATED - TASK ID: saleo5261k5a2y

Response Code - 202:

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

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 export_entity_launchExport-20230912165
  
```
The command saves the export to your running directory. The export .tgz file includes a root.json file that contains an index of all of the entities that are contained in the .tgz file, as well as a content_entity_type.json file for each content entity type exported. The content_entity_type.json file contains all of the information needed to be able to import those entities into a different Developer Portal site.
If you ran the export-entity:launch command with the --no-poll option, you can use the following commands to manage your entity export.
- export-entity:delete-launch-export
  Cancels any currently running export-entity:launch tasks, and deletes any related artifacts. For example:
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name export-entity:delete-launch-export --task_id task_id
```
  Where task_id is the ID of the export task on the queue.
- export-entity:get-launch-export
  Streams the content of a specific completed export-entity:launch task to a .tgz file. For example:
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name export-entity:get-launch-export --task_id task_id
```
- export-entity:get-launch-export-status
  Returns the status of a specific export-entity:launch task. For example:
```
apic --mode portaladmin --server management_server --org orgid/name --catalog catalogid/name export-entity:get-launch-export-status --task_id task_id
```

What to do next

You can import your export entity archive files by using the content commands; see Using the content commands for more information.