Site Development, Update and Optional SIte Migration

This page describes use of wchtools for various WCH site development scenarios. It is not intended to describe WCH site development itself, which appears elsewhere in the WCH documentation, for example:

• https://github.com/ibm-wch/wch-site-application
• https://developer.ibm.com/customer-engagement/docs/wch/developing-your-own-website/
• https://developer.ibm.com/customer-engagement/tutorials/adding-layouts-new-content-type-page-type/
• https://developer.ibm.com/customer-engagement/tutorials/customizing-layouts-components-for-your-site/

Single WCH Tenant Scenario

The least complex configuration and development scenario involves a single WCH tenant used for authoring sites, pages and content, testing drafts via preview, along with local development and testing of web artifacts to support the site(s).

• In this scenario, wchtools may have been used to push an initial update to Oslo and/or to delete Oslo sample pages, but after that, is primarily used to upload web artifacts, either explicitly, or implicitly via the WCH Site Application npm run deploy command.

• For development and testing of web artifact and layout additions/changes prior to pushing those changes to your WCH tenant's hub, you may use the local development server described in the WCH Site Application readme here: https://github.com/ibm-wch/wch-site-application#development-server

• Note, when running npm run deploy as described in the WCH site application documentation, it executes the wchtools push command with a --publish-now option, which overrides publishing schedule(s) if set. If you need your web artifact changes to also wait on a publish schedule, you may need to edit the package.json in the wch-site-application project and remove the --publish-now option from the "deploy" script.

Separate Web Development Tenant from the Authoring/Production tenant

• In a two tenant scenario, the development of web artifacts and layouts (as described in the above WCH layout documentation) may be performed locally and against a web developer tenant, and the authoring and production content, site(s) and pages in a separate authoring/production tenant.

• With such a two tenant scenario, you may choose how those web artifacts are migrated from development to authoring/production in one of the following ways:

1. Keep your WCH site application project in a source control repository, and develop/test the web artifact and layout changes against the web development tenant. When ready, switch tenants to the authoring/production tenant and npm run deploy the same project to the authoring/production tenant.

or

2. Use the WCH site application npm run deploy against the web developer's tenant, but then when ready, do a pull of all web assets, layouts, mappings (and optionally any developer controlled content types) from the developer tenant, and then push those artifacts to the authoring/production tenant.

Migrating Site Artifacts between tenants

While the simplest scenario is the one described first above, where a single tenant is used for developing web artifacts, layouts, authoring content and sites/pages, there are situations that may require multiple tenants, and use of wchtools to migrate artifacts between tenants. The remainder of this doc describes some of the options available for such artifact migration between tenants (eg, from a business partner's tenant, to their client's tenant, or from a web development tenant, to an authoring/production tenant).

The wchtools cli can be used to assist in migration of WCH artifacts and sites from one environment to another.

• Note, when multiple or repeated pulls and pushes across tenant will be made, it is recommended that the same source repository on disk is used, and that the .wchtoolshashes that are generated during the pulls and pushes, be kept around in that repository.

• The generated .wchtoolshashes files for each artifact type (assets, content, sites/pages etc) keep track of what artifacts have been pulled/pushed to/from that folder on disk, for that tenant (by file path and md5 checksum), so that on subsequent pulls/pushes, unchanged files do not need to be updated.

• When making updates to an existing sites, and changing existing layouts, types and web assets, it may be less risky to create new content types, new layouts/mappings and new web artifacts that replace the old, than to make substantial changes to existing types/layouts, where the web developer may not be aware of all existing content, using the existing types/layouts.

Assume the developer has made updates to artifacts locally or in a developer specific WCH tenant and wants to migrate those changes forward to the next environment, there are several commands that can facilitate this action.

Assume the developer has a local working directory with the set of artifacts that he has been working on and which exist in the first (source) environment. The developer may have populated these artifacts in his local working directory using a pull command. For example:

wchtools pull -A --url <env1> --dir <env1dir>

- would  pull All artifact types)

One reason NOT to pull All artifact types from the development tenant, may be to not include test content/pages that the developer was only using to test against, and which are intended for use only in that development tenant.

wchtools pull -w -l -m --url <env1> --dir <env1dir>

- would instead pull only web assets, layouts and mappings, from the source web dev tenant.

Those same artifacts could then just be pushed to the authoring/production tenant, if the user is confident that they are fully tested and ready to be promoted to that environment.

There may be situations though where a comparison between what is in a source repo or export (from dev tenant) and what is in a target authoring/production tenant, should be made, to ensure that those differences match the developers expections

Comparing an export with a target tenant

First, the compare command can be run to compare the artifacts between the local export and the target WCH tenant. For example:

wchtools compare -A --source <env1dir> --target <env2> --write-manifest my_udpates --write-deletions-manifest my_deletions

This will generate 2 manifest files, the my_updates manifest will contain a list of all of the artifacts that are new or changed between the environments. And the my_deletions manifest will contain a list of all of the artifacts that exist in the target environment but have been removed from the source.

Next, after verifying that the differences are as expected, the push command can be run to push these updates into the target environment.

For example:

wchtools push -A --url <env2> --dir <env1dir> --manifest my_updates

Finally, the delete command can optionally be run to remove those artifacts that only exist in the target environment. For example:

wchtools delete --url <env2> --manifest my_deletions --preview

And finally, after previewing the proposed deletions:

wchtools delete --url <env2> --manifest my_deletions

Migrating only specific artifact types

If the developer is working with only a subset of artifacts, perhaps only web assets, layouts and layout mappings, the use of the artifact type specifiers should be consistent throughout the commands described above. So, rather than using -A to pull, compare and push all authoring artifacts, the developer may use -wlm in each of these commands to specify that only managed content assets, web assets and types would be pulled to the local working directory, compared with the target environment and pushed to the target environment.