Warning This document has not been updated for a while now. It may be out of date.

Last updated: 3 Jan 2023

specialist-publisher: Creating or editing specialist document types

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

Creating a specialist document type

1. Add a schema to govuk-content-schemas

See example PR for adding product_safety_alert. Note: this is a link to a PR in the now-archived content schemas repo. Content schemas have now been moved to publishing api. Please update this document when an example for publishing api is available.

1. Add the format to this list and to this list
2. Add any new field definitions to this file
3. Add examples as instructed. You can copy and paste from another specialist document format, only changing what is necessary (you can leave the body and headers unchanged).

You'll need to generate your own UUIDs for the content_id and signup_content_id fields:

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

4. 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 are often requested to be deployed in "pre-production mode", which is configured in this step (example). pre-production documents are only publishable on development and integration.

Create the model

See CMA cases

Create the view template

CMA cases

3. Configure Search API

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

• CMA case schema (example)
• field definitions

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

• the main ES types list govuk.json
• migrated_formats.yaml
• mapped_document_types.yaml

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

• elasticsearch_presenter.rb
• specialist_presenter.rb

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.

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 and publish

To deploy:

1. Deploy Specialist Publisher and Search API (and govuk-content-schemas if you haven't already).
2. Reindex the govuk Elasticsearch index.

• This takes around 30-45 minutes on Production, or 3-4 hours on Integration.
• NB: 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.

3. Use the "Run rake task" Jenkins job to run publishing_api:publish_finders or publishing_api:publish_finder[your_format_name_based_on_the_schema_file] against the specialist publisher app on a backend machine.

6. 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 govuk-content-schemas, add the new field to the specialist document schema. See this commit for an example. Once approved, this change can be merged and deployed.

2. In specialist-publisher, add the new field to the relevant model, form, and schema files. See this commit for an example.

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

• the relevant schema in the elasticsearch_types directory.
• the elasticsearch_presenter.
• the specialist_presenter.
• the field_definitions file.

4. Follow steps in the Deploy and publish section above, to re-publish the finder and reindex the GOVUK search index.

Adding or amending values for existing fields on a specialist document

1. In govuk-content-schemas, find the field you are amending in the specialist_document schema, and add the new values. See this commit for an example.

NOTE: You will need to run bundle exec rake build_schemas to regenerate schemas after adding the new value(s) - as is done in this commit.

Once approved, this change can be merged and deployed.

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

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

4. Republish the finder, see step 3 in the Deploy and publish section above. You do not need to reindex search :sweat_smile:

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.