API Connect

 View Only

IBM API Connect: Exporting and Importing Content between your Developer Portal Sites

By Reece Oliver posted Tue October 24, 2023 11:37 AM


Everything in the following blog post pertains to API Connect version Some introductory information on using the Portal Admin CLI can be found at https://www.ibm.com/docs/en/api-connect/10.0.5.x_lts?topic=cli-getting-started-portal-commands if you aren’t fimilar with the process.


Exporting Content

In this tutorial, we will show you how you can export the ‘Terms of Use’ page and the ‘Privacy Policy’ page. You can then apply the same procedure to export other content of your choosing.

  1. Log in to the CLI

apic login --realm provider/default-idp-2 --username <username> --password <password> --server <management-platform-api>

  1. List the Content Types that are exportable on your site

apic --mode portaladmin -s <management-platform-api> -o <org> -c <catalog> content:list-types

You will get a list returned of all the content entity types that are allowed to be exported. If you don’t see a type here, it is because it’s either blocked or is not a content entity type. Each content type can have sub types which are known as bundles. These can be used in the content:list command when you list a certain bundle type of a content entity to find.

  1. Find the content entity or entities you would like to export

apic --mode portaladmin -s <management-platform-api> -o <org> -c <catalog> content:list --entity_type node --bundle page

This command has returned a list of all the content entities of type node that also have a bundle type of page. Now you have the relevant information you can see the two pages in the results and they have an entity ID of 1 and 2

  1. Exporting the two Content Entities

apic --mode portaladmin -s <management-platform-api> -o <org> -c <catalog> content:create-export --entity_type node --entity_ids 1,2

The command will save the export to your running directory. The export will always contain a root.json file which is essentially an index all the entities that are contained in the tgz and then will have <content_type>.json for example in the export that has just been saved we will have a node.json which contains all the information needed to import those entities into another site.

As you can see in the command example above you are only able to export one type of content type at a time but many ids for that type. You can perform an export all but running the above command with --entity_type all. If you want to be to able pick and choose different content types to be contained in your export then please see Creating an Export Entity and launching it.

Misc Commands

content:delete-export If running, cancels a content export task.

content:get-export When ready, streams a content export artifact.

content:get-export-status Returns information about the status of this task.

These command will only be needed if you run content:create-export with the `--no-poll` flag and want to manually do the polling process yourself, but for most uses cases you will just use content:create-export.

Creating an Export Entity and launching it.

Export entities can be used to create a predefined list of entities that you would like to be exported when ran. Multiple export entities can be created, each containing its own unique set of assorted entity types. This means you can mix and match types instead of running the content:create-export command for each type you would like to export. Export entity lists persist and so content can be added and removed from them whenever you feel the need to do so.

  1. Log in to the CLI

apic login --realm provider/default-idp-2 --username <username> --password <password> --server <management-platform-api>

  1. Create an Export Entity

apic --mode portaladmin -s <management-platform-api> -o <org> -c <catalog> export-entity:create --export_entity_name "Main Content"

Here you can see an export entity has been created with the name “Main Content” which has an id of 5. It is important to remeber this ID as this is what you need to refer to your export entity from here on out. You can’t use the name as this is not an unique indentifier.

  1. List Export Entity

apic --mode portaladmin -s <management-platform-api> -o <org> -c <catalog> export-entity:list

You are able to list all the export entities that are avaliable if you were to ever forget the ID. We have also included the created time in this data as you are to create export entities that have the same name so please bear that in mind.

  1. Add Content to an Export Entity

apic --mode portaladmin -s <management-platform-api> -o <org> -c <catalog> export-entity:add-content --export_entity_id 5 --entity_type node --entity_ids 1,2

As you can see i have added three different type of content to my export entity. node, block_content and shortcut. You can also delete content from an export entity when its no longer needed.

apic --mode portaladmin -s <management-platform-api> -o <org> -c <catalog> export-entity:remove-content --export_entity_id 5 --entity_type node --entity_ids 1

  1. View details of an Export Entity

apic --mode portaladmin -s <management-platform-api> -o <org> -c <catalog> export-entity:get --export_entity_id 5

Getting the Export Entity will return all the content entities that have been added to export entities. This is the of entities which will be contained in the export when launched.

  1. Launching an Export Entity

apic --mode portaladmin -s <management-platform-api> -o <org> -c <catalog> export-entity:launch --export_entity_id 5

Launching an export entity will generated a tgz in same format outlined in Exporting Entities in step 5. This export entity can be launch however many times you want and updated with more or less content when needed.

Misc Commands

export-entity:delete-launch-export If running, cancels a export entity launch export task.

export-entity:get-launch-export When ready, streams a content export artifact generated from an export entity.

export-entity:get-launch-export-status Returns information about the status of this task.

These command will only be need if you run export-entity:launch with the `--no-poll` flag and want to manually do the polling process yourself, but for most uses cases you will just use export-entity:launch.

Importing Content

Once you have ran through the tutorial of either Exporting Content or Creating an Export Entity and launching it you will have generated a tgz that you can import into the site of your choosing so as it on or above.

  1. Log in to the CLI

apic login --realm provider/default-idp-2 --username <username> --password <password> --server <management-platform-api>

  1. Create an Import

apic --mode portaladmin -s <management-platform-api> -o <org> -c <catalog> content:create-import <export-tgz>

As you can see we imported the tgz that was generated in step 5 of Creating an Export Entity and launching it. We imported this tgz into a different stack and catalog as you can see by the server and catalog names being different. Once the command has finished you will get a summary of what and how something was imported. There are three types of imports outlined below.

Overridden - There was an entity that existed with the same entity id but not the same uuid and there was also no reference to it in the synchronization table. You will need to take care when importing entities across sites until they are in sync as you could easily lose data. For example if you had a blog post with the ID of 50 that talked about APIs and you want to import this blog into your prod site but you had a blog post on there already with ID 50 but its contents are about your Policies, this data would be overridden with the contents of the blog post about APIs. Once an content entity has been overridden once, the next time you import that same uuid there will be reference to it now so will take the status of Updated next time instead. Overridden can only happen for the same bundle type, for example a blog post wouldn't override a block content entity.

Updated - The same content entity was found and the contents of it was updated updated with what was contained in the export tgz

Created - No content entity of this type was found in this site’s database so a new entiy was created for it and populated with the data contained in the export tgz you imported.

Misc Commands

content:delete-import If running, cancels a content import task.

content:get-import-status Returns information about the status of this task.

These command will only be need if you run content:create-import with the `--no-poll` flag and want to manually do the polling process yourself, but for most uses cases you will just use content:create-import.

Using to the Drupal Admin UI to Import/Export

Everything that has been shown in the steps above can also be performed in the UI if needed. This section won’t have exact steps as its the same process as above but will indicate where everything is located if its desired to do import/export via UI.

Exporting Content

When editing a content entity type and logged in as admin you will see there is now an export tab near the bottom of the page which contains an “Export Entity” button and an “Add to the export” button which a checklist of all your Export Entities you have created. If you only see the “Export Entity” button this is because you haven’t created any Export Entities yet and the how-to on that can be seen further below.

Clicking “Export Entity” will perform a quick export which will export that content entity and any embedded entities that are needed to create it. While clicking “Add to the export” will add the content entity to add of the Export Entities you checked.

Creating and viewing Export/Import Entities

Export entities can be viewed at Content > Content synchronizer > Exports. At this page you are able to see all of the export entities that have been created on your site even if it was done by UI or CLI. You can view what each export contains and even launch the export to generated the export tgz.

Import entities can be viewed at Content > Content synchronizer > Imports. Here you able to create new import entities with names and upload the relevant export tgz to be linked to them. Once created you can launch them for the import process to happen. Once imported it’s highly recommended to delete the import entity as its not wise to keep them around as it would bloat your Portal backups cause them to take more space and take longer to restore.

Further Reading

If you would like to able to use these command via REST API endpoints then you can find the routes and parameters detailed here. https://apic-api.apiconnect.ibmcloud.com/v10/#/APIConnectPortalAdminAPI_100/overview the routes are located under Resource: Content and Resource: Export Entity. For specifics on how you need to call this routes with the correct authentication follow section here https://www.ibm.com/docs/en/api-connect/10.0.5.x_lts?topic=eictsc-exporting-importing-custom-themes-site-configuration-by-using-portal-admin-api#tutorial_portal_cli_no_use_api_scenario1__auth-steps which explains how you can gain a client ID and Secret and a Beaer Token for the REST calls.

#APIConnect #developerportal #portal #drupal #portalcli