Promoting Custom Element Changes to Production

If you've built custom element and wish to make changes to them, it is highly recommended that you do so in your staging account and then, after confirming that the changes are functioning, migrate the changes to your production account. This process can be done using the Cloud Elements platform APIs or by using an asset management tool called The Doctor.  This article walks you through the platform APIs you can use to accomplish a migration, as well as the main features of The Doctor.

You can also use the Manage Environments feature to facilitate the import and export of elements, formulas, and VDRs.

Migrating With Platform APIs

To migrate your custom element changes from staging to production you first need to export the recent element JSON changes from your staging environment. You can do this by signing in to your plCloud Elements staging environment and navigating to the API DOCS in the top right corner. From this screen, select Elements and scroll down to the GET /elements/{keyOrId} call.  Use this endpoint to get the element JSON that you will use to update your production element. Next, sign in to your production environment, navigate to the API DOCS page, select ElementsBuilder and scroll down to the PUT /elements/{keyOrId} call. You use the payload you acquired from your staging account to update your production element using this call. It is important to note that if you are the main company account that changes made to your element are inherited by all sub-users in your account.

Migrating Using The Doctor

The Doctor is an asset management tool that was designed to help users migrate elements, formulas, and VDRs across environments. We will touch on some of the core features of The Doctor, but for complete documentation please visit - https://github.com/cloud-elements/the-doctor.

The Doctor can be installed by running `npm install -g ce-util`. After it is installed, you can run `doctor init` to initialize an account.  You will want to do this for the staging environment you are downloading the element from `https://staging.cloud-elements.com` and the production environment you are sending the updated element to `https://api.cloud-elements.com/`.  Assuming that you gave the account nickname "staging" to your staging account and the nickname "production" to your production account you can use The Doctor as follows.  To download your element from staging you can run `doctor download elements staging -n <my-element> -f ~/Workspace/Doctor`, replacing <my-element> with the element key of the element you wish to download.  You can then run `doctor upload elements production -n <my-element> -f ~/Workspace/Doctor` to upload the element to your production environment. Elements that have never been migrated will be created with a POST request, elements that already exist will be updated with a PUT request.