Bulk publish entries and assets

Having the ability to publish entries and assets in bulk on the specified environments can ease the process of content management. And with Contentstack's bulk-publish-entries-assets script, you can automate the process of bulk publishing your entries and assets.

In this guide, we will look at different scenarios of bulk publishing and how to use the bulk-publish-entries-assets script in each scenario.

Note: If you have the Bulk Publish feature enabled for your plan, this script will make use of Bulk APIs. Make sure you keep the bulkPublish and bulkUnpublish flags to true in the config. If it’s not part of your plan, it will publish the items in queue, one at a time.

We will discuss the use of this script in the following scenarios:

Publish the unpublished/draft entries on a particular environment
Publish all assets of a stack on a particular environment
Publish all entries of a stack on a particular environment
Unpublish all entries/assets of a stack from a particular environment
Publish the edits made in entries on a particular environment
Publish entries/assets from one environment to another
Publish localized entries when the non-localized field of the master entry is updated
Update and publish entries when a new field is added to content type
Restore/unpublish entries published through script using logs

Points to Keep in Mind

If Bulk API is part of your plan, each bulk publish API request will publish a maximum of 10 items per request. So, for example, if you publish 100 items using this script, it will make 10 Bulk API requests, and your API count will increment by 10.

If Bulk API is not part of your plan, each item published using this script will be counted as a separate call. So, for example, if you publish 100 items using this script, it will make 100 API requests, and your API count will increment by 100.
Bulk publishing of entries of all locals is not supported yet by the script. However, you can specify the locales as an array (en-us, fr-fr, zh-zh, and so on) against the ‘locale’ parameter in the config file to get them published.

Download the Code and Install Dependencies

Before we start discussing the scenarios and how to use this script, we need to install the required dependencies and make certain changes in the configuration file.

Download the utility code from GitHub.
Once the code is downloaded, open your terminal and move inside the project root directory. Then, run the following command:
```
npm install
```
The above command will install the required node dependencies.

Now open the index.js file which is inside the config folder of the downloaded code, and provide your stack credentials as follows:

module.exports = {
    apikey:'YOUR_STACK_API_KEY',
    apiEndPoint:'https://api.contentstack.io',
    cdnEndPoint:'https://cdn.contentstack.io',
    manageToken:'YOUR_STACK_MANAGEMENT_TOKEN',
}

Note: The above configuration is common for all scenarios. If the Bulk Publish plan is not enabled for your organization, keep bulkPublish and bulkUnpublish flags as false in the config of all cases

Let's now move ahead and discuss the scenarios and how to use this utility.

Case 1 Publish the Unpublished/Draft Entries on a Particular Environment

This is the scenario where you want to publish the unpublished entries or the draft entries on a particular environment.

Open the index.js file which is inside the config folder and provide the necessary details in the following section of the file:

publish_unpublished_env: {
        contentTypes:['test'],                    //list of contentTypes
        sourceEnv : 'staging',                    //sourceEnv
        environments:['staging'],                //target environment
        locale:’en-us’                           //your locale
       bulkPublish:true                    //keep false if the bulk operation is enabled in your plan
    }

After you have added the details and saved the file, run the following command, staying inside the project root directory:
```
npm run publish_unpublish
```

The above command will retrieve all entries of ‘test’ contentType not published in ‘staging’ environment with ‘en-us’ locale and publish it on the destination environment ("staging" in our case).

Case 2 Publish All Assets of a Stack on a Particular Environment

This is a scenario where you want to publish all assets of a particular stack in bulk. To do this, follow the below steps:

Open the index.js file and provide the required details in the following section of the file:

module.exports = {
    publish_assets:{
        environments:['bulktest'],                 //name of the environment
       folderUid:’cs_root                   //UID of the folder, ‘cs_root’ for all assets
bulkPublish: true                                  //keep false if the bulk operation is enabled in your plan
    }
}

Once you have provided the required details in the index.js file, run the following command, staying inside the project root directory:
```
npm run publish_assets
```

The above command will publish all the assets of the stack (the ID of which you provided in the main configuration file at the top).

Case 3 Publish All Entries of a Stack on a Particular Environment

This is a scenario where you want to publish all the entries of the specified content types in a stack.

Open the index.js file and provide the details in the following section of the file:
```
publish_entries:{
  contentTypes:['redirect_rule'],          //list of contentTypes to be published
  locales:['en-us'],                       //list of locales to be considered for mentioned Content types
  environments:['bulktest'],               //destination publish environments
  publishAllContentTypes : false,          //if you want to publish all contentTypes
  bulkPublish: true,
}
```
In the above config, there are two important parameters: bulkPublish and publishAllContentTypes. Keep the value of bulkPublish to true if you want to proceed with bulk publishing on entries, whereas keeping the value of publishAllContentTypes to false unless you want to publish all the entries of all the content types in a stack.
Once you have entered the above details in the config file, run the following command:
```
npm run publish_entries
```

Note: It is recommended to try publishing entries of one content type at a time. In this way, you can avoid the chances of entries failing to get published in bulk.

Case 4 Unpublish all Entries/Assets of a Stack from a Particular Environment

Your content types may have thousands of entries and assets and unpublishing them manually can be a tedious task. Using this script, you can automate the process of unpublishing all entries and assets of the stack that were published on a particular environment.

To do this, open the index.js file and add details in the following section of the file:

bulkUnpublish :{
    filter:{
        environment: 'bulktest',            //source environment
        content_type_uid: '',               //add content type uid to be unpublished,keep blank to consider all
        locale: 'en-us',                    //locale filters
        type:'entry_published,asset_published'   //entries and assets both will be unpublished, remove asset_published if u want to unpublish only entries and vice versa.
    },
    deliveryToken:'' ,                      //delivery token of the  source environment
   bulkUnpublish: true,

  }

Once the details are added, run the following command by staying inside the project root directory:
```
npm run unpublish
```

If you want to unpublish only the entries of specific content type, specify its UID in the content_type_uid filter in the above config. To unpublish only assets, remove entry_published from the type filter or remove asset_published if you want to unpublish only entries.

Case 5 Publish the Edits Made in Entries on a Particular Environment

This is a common scenario where you want to publish the entries, which were recently edited, on a particular environment.

Open the index.js file again and make changes in the following section of the code:
```
publish_edits_on_env: {
   contentTypes:['test','helloworld'],    // array of contentTypes where edits needs to be checked
   sourceEnv : 'production',              //environment where entry edits needs to be checked
   publishEnvironments:['production'],    //publishing environment (usually same as sourceEnv)
   locales:['en-us',],                    // locales of entries where it needs to be checked
   bulkPublish: true,

},
```
In the above config, you need to provide the UID of the content type such as "test", "helloworld", and so on). Source environment is the environment on which the entries were initially published (in our case it is "production"). Publish Environment is the new environment on which the edited entries are to be published (in our case it is "production"). Lastly, provide the locale details (in our case it is "en-us").
After you have provided the details and saved the file, run the following command, staying inside the project directory:
```
npm run publish_edits
```

The above command will publish the edited entries on the target environment that you have specified in the above config file.

Case 6: Publish Entries/Assets from One Environment to Another

This is again one of the common scenarios where you want to publish the content from one environment to a newly created environment or to some other environment.

To do this, open the index.js file and provide the necessary details in the following section of the file:

cross_env_publish:{
     filter: {
      environment: 'bulktest',          //source environment
      content_type_uid: '',             //add content type UID to be published,blank to consider all
      locale: 'en-us',                  //locale filters
      type: 'asset_published,entry_published',    //entries and assets both will be published, remove asset_published if u want to publish only entries and vice versa.
    },
    deliveryToken: '',                 //delivery token of the source environment
    destEnv:[‘’],                      //environment where it needs to be published
    bulkPublish:true
  }

After you have added the details, run the following command, staying inside the project root directory:
```
npm run cross_publish
```

The above command will publish the entries (of the mentioned content types) and assets from the "bulktest" environment to the environment you have mentioned in the config.

Case 7: Publish Localized entries if the Non-localized Field of the Master Entry is Updated

This is a scenario where you want to publish those entries in bulk that had their non-localized field changed. Read more about Non-localized Field.

Open the config.js file and provide the necessary details in the following section of the code:

nonlocalized_field_changes: {
   sourceEnv: 'production',                     //source Environment
   contentTypes: ['testdin'],
   environments: ['production'],                //publishing Environments
   bulkPublish:true
  },

After you have added the details, run the following command, staying inside the project directory:
```
npm run publish_localized
```

The above command will publish the entries (of the specified content types) from the source to the publishing environment.

Case 8: Update and Publish Entries if a New Field is Added to a Content Type

This is one of the most common scenarios in content management. Often, we keep adding a new field in a content type as and when required. And there could be multiple entries in your content types. Publishing all such entries manually can be time-consuming, but with this script, you can automate this task.

To publish such entries of content types in bulk, follow the steps given below:

Open the index.js file and provide the necessary details in the following section of it:

addFields: {
    deleteFields: ['updated_by', 'created_by', 'created_at', 'updated_at', '_version', 'ACL'],
    locales: ['en-us'],
    contentTypes: ['helloworld'],         // list to contentType entries to be updated
    environments: ['test'],               // list of environments where it needs to be published
    defaults: {
      number: null,
      boolean: false,
      isodate: [],
      file: null,
      reference: [],
    },
  bulkpublish:true,
  },

After you have added the details, run the following command, staying inside the project directory:
```
npm run add_fields
```

The above command will publish the entries (of the specified content types that had a field added or updated) on the specified environment.

Note: This script is not applicable to custom and mandatory fields.

Case 9: Restore/unpublish Entries Published Through Script Using Logs

To understand this scenario, consider an example. There are 10 entries in a content type. Out of these 10, 4 entries are published on version 4 and 6 of them were never published.

So if you publish all entries of this content type using the script, let's say entries which were at version 4 will now be published at version 5 and the unpublished ones will be published with version 1.

Now, if you want to undo this operation and restore entries to their previous state, use the following command:

$ npm run revert ${logFilename}

In the above command, logFilename is the success logs of a particular execution (like a log of successful publishing of entries to version 5 and 1 as in the above example).

For example:

npm run revert 1587270350288.bulkPublishEntries.success

Retry Publishing Entries

When you use this script to publish the entries in bulk, there might be a few entries that could not be published due to some reason. The record of such entries is stored in the logs directory with a unique name or identifier ending with .error.

You can retry publishing such entries using the same script with the retryFailed flag along with {logFilename} as shown below:

npm run publish_entries -- -retryFailed ${logFilename}

npm run publish_assets -- -retryFailed ${logFilename}

For example:

npm run publish_entries -- -retryFailed 18003bulkPublishEntries.error

Bulk Publishing of Entries and Assets