Skip to main content
  1. Home
  2. Apps
  3. specialist-publisher
Last updated: 4 Dec 2024

specialist-publisher: Creating, editing and removing specialist document types and finders

To create or edit a new specialist document you will have to make changes to this application, publishing-api and search-api. You will not have to make any changes to frontend applications.

Creating a specialist document type

1. Add a schema to Publishing API

See example PR here

  1. Add the format to allowed document types list.

  2. Add any new field definitions to this file.

    Note: Do not specify the field values as an enum, as we're moving towards a more relaxed schema definition.

  3. Run bundle exec rake build_schemas to regenerate schemas.

When the PR is reviewed and its tests passing, it can be merged and deployed at this point.

2. Create a new specialist document format in Specialist Publisher

Create the schema

See CMA cases.

New formats should be added with target_stack: "draft" so that departments can preview the finder before you publish it.

You'll need to generate your own UUIDs for the content_id (of the finder), and the signup_content_id fields:

$ irb
irb(main):001:0> require "securerandom"
=> true
irb(main):002:0> SecureRandom.uuid
=> "5087e8b6-ee54-40f9-b592-8c2813c7037d"

Create the model

See CMA cases

Create the view template

See CMA cases

3. Configure Search API

Search API needs copies of the schema very similar to the one in Specialist Publisher. See:

You'll also need to add your document format to:

Finally, you'll need to add your custom fields to:

4. Configure the email sign up page

The email sign up page is rendered by Finder Frontend using the configuration in the new schema added to specialist publisher. The schema should specify email_filter_by and email_filter_facets (e.g. cma-cases).

If your email sign up page should have checkboxes (e.g. cma-cases), you will need to edit email-alert-api by adding the new tags to valid_tags.rb.

5. Deploy a finder to the draft stack (for previewing)

To deploy a new finder for previewing:

  1. Ensure the finder target_stack is set to draft
  2. Merge and deploy Publishing API, Specialist Publisher and Search API.
    • Ensure you deploy Publishing API first, to avoid schema validation errors.
    • Also deploy Email Alert API if you have made changes to it.
  3. Run rake SEARCH_INDEX=govuk 'search:update_schema' in Search API.
  4. Publish the finder to the draft stack by running the rake task publishing_api:publish_finders or publishing_api:publish_finder[pluralised_format_name] against the specialist publisher app (rake tasks here).
  5. Wait for department's feedback and approval and agree on a release date

NB: Depending on the finder requirements, you may choose to allow the users to publish documents in preview mode, which would enable them to test the full finder filtering functionality. Changes to the schema requested after documents have been published, could require running a reindex, and there is a risk of loss of data. In order to prevent users from publishing, we could give only basic Signon permissions whilst in preview mode. Signon access to the Specialist Publisher app, only gives the user writer access (they may create, edit, and update, but not publish or unpublish).

6. Publish a finder

To release the finder to the live stack:

  1. Prepare before the agreed release date. Merge PRs and release on agreed date.

  2. Merge and deploy Search API

  3. Reindex the govuk Elasticsearch index.

    • This takes around 30-45 minutes on Production, or 3-4 hours on Integration.
    • Alternatively, run rake SEARCH_INDEX=govuk 'search:update_schema' for a shorter run. Make sure the this is run before any documents are published, otherwise a full reindex will be required.

    Note: reindexing shouldn't really be necessary; Elasticsearch will dynamically create the field mappings the first time a new document of this type is published. In other words, if you publish a new document type, the finder will work and it will return the relevant documents even without a reindex. However, the filters on the finder would not work, as this reindexing job also builds the filters for the finder, so we have to run the job.

  4. Change the target_stack of the finder from draft to live in specialist-publisher json schema config

  5. Merge and deploy Specialist Publisher

  6. Publish the finder by running the rake task publishing_api:publish_finders or publishing_api:publish_finder[your_format_name_based_on_the_schema_file] against the specialist publisher app (rake tasks here).

7. Permissions

Specialist Publisher grants access to the publishing interface for your new document type to the following Signon users:

  • Users that belong to the owner organisation AND have Editor permissions
  • Users that have the permission your_new_document_type_editor, e.g. oim_project_editor

You'll need to create the new permission manually.

Editing a specialist document type

We often receive requests to add new fields to a specialist document or to add new values to existing fields.

Adding a new field to an existing specialist document

  1. In publishing-api:

NOTE: You will need to run bundle exec rake build_schemas to regenerate schemas after adding the new value(s). Do not specify the field values as an enum, as we're moving towards a more relaxed schema definition.

  1. In specialist publisher:
    • Add the new field to the relevant model.
    • Add field to relevant view.
    • Add fields to relevant schema files.

See this commit for an example.

  1. In search-api, add the new field in the following places (see this commit for an example):

To republish the finder:

  1. Deploy Publishing API, Search API.
  2. Run rake SEARCH_INDEX=govuk 'search:update_schema' on Search API. If this errors, you may have to do a full reindex.
  3. Deploy Specialist Publisher, deploy after the Search API schema update / reindex to avoid users publishing new documents with the new field.
  4. Publish the finder by running the rake task publishing_api:publish_finders or publishing_api:publish_finder[your_format_name_based_on_the_schema_file] against the specialist publisher app (rake tasks here).

Adding values for existing fields on a specialist document

  1. In specialist publisher, add the new values to the relevant file in the schema directory. See this commit for an example.

  2. In search-api, amend the value in the relevant schema in the elasticsearch_types directory. See this commit for an example.

To republish the finder:

  1. Deploy Publishing API, Search API, Deploy Specialist Publisher.
  2. Publish the finder by running the rake task publishing_api:publish_finders or publishing_api:publish_finder[your_format_name_based_on_the_schema_file] against the specialist publisher app (rake tasks here).

Editing a specialist finder

The schema files that define a specialist document, are also used to configure that document's specialist finder. See this commit for an example.

Unpublishing a specialist finder

Important: In order to remove a finder, you should ensure there is a clear business requirement in doing so, and that all associated documents have been correctly dealt with - unpublished, redirected, migrated or removed. If the code is not removed from all relevant repositories, there is a chance the finder will be inadvertently republished, for example by republishing all finders. You must therefore make sure the code is removed in order to keep the finder unpublished.

The following steps are required to remove a finder:

  1. Unpublish the finder in all environments using the provided rake task:

    rake unpublish:redirect_finder["uk_market_conformity_assessment_bodies","https://redirection_link.gov.uk"]

  2. Remove usages from publishing-api:

    See example commit.

  3. Remove usages from specialist publisher. See example commit.

  4. Remove usages from search-api. See example commit.

  5. Remove any usages from finder-frontend, if applicable.

  6. Deploy all changes.