Table of contents

Change an organisation's slug

NOTE: for Worldwide Organisations, only Steps 1, 6 and maybe 7 below need to be performed.

The organisation slug is used as a foreign key for organisations across lots of apps. Changing it can be complex and time consuming.

1) Change the organisation’s slug in Whitehall

Create a data migration that uses the DataHygiene::OrganisationReslugger class, see this PR for an example.

2) Update the organisation in the Need API:

  • Pull the new organisation slug from Whitehall using the organisations:import rake task.
  • In the Rails console, update all needs with the new organisation:
  Need.where(organisation_ids: old_slug).each { |n| n.organisation_ids = (n.organisation_ids - [old_slug] + [new_slug]);! }
  • Use Organisation.find(old_slug).destroy to delete the old organisation.
  • Re-index the needs in search via the search:index_needs rake task.

3) Clear the organisation cache in Maslow:

Restart the workers using Fabric:

fab $environment class:backend sdo:'service maslow reload'

4) Update the organisation in Transition/transition-config:

The transition-config repo may contain slugs. Change any references to the old slug:

5) Update the organisation slug in Manuals Publisher


Find out if any manuals are published by this organisation.

Run the following in manuals-publisher Rails console:

ManualRecord.exists?(conditions: { organisation_slug: "old-slug" })

If there are, create a migration to update the slugs. Republish all affected manuals after deploying your change.

6) Update the organisation slug in the GOV.UK Delivery database


Find the original slug in the MongoDB database for GOV.UK Delivery by running the following in a MongoDB console:

use govuk_delivery
db.topics.find({_id: {$regex: new RegExp("old-slug") }})

Then update the topics by inserting the new record and deleting the old one. (An update isn’t possible because MongoDB doesn’t allow updating IDs):

db.topics.find({_id: {$regex: new RegExp("old-slug") }}).forEach(function(doc) {
  var old_id = doc._id;
  doc._id = doc._id.replace(/old-slug/g, "new-slug");
  db.topics.remove({ _id: old_id });

7) Update any best-bet searches in Search Admin

This page is owned by #2ndline and needs to be reviewed