Preparing to add a new framework ¶

These are the things a developer currently needs to do to prepare a new framework for applications.

Note

Unless otherwise noted, you should make sure you do ALL these steps in the right order.

1 - Make the content ¶

In the frameworks repository, run the clone-latest-framework.py script. For instance, to create a new framework G-Cloud 12 from G-Cloud 11 run:

./scripts/clone-latest-framework.py --family=g-cloud --iteration=12 --launch-year=2020

This will create a new folder in the frameworks directory based on the previous iteration of that framework.

Each framework iteration has sub-folders for:

questions: all the question content for both supplier declarations and service definitions.
manifests: manifests define the order that questions are presented by the front-end applications.
messages: various framework-specific messages shown during applications, such as important dates.
metadata: information that links two or more frameworks, e.g. which service attributes can be copied between frameworks.
search_mappings: contains a base mapping, used to generate the framework’s OpenSearch mapping for the Search API.

The cloning script provides placeholder dates and URLs that will need to be updated and confirmed with the real content (see below).

Commit the changes and update the version number in package.json. Normally this will be a minor version bump, as it shouldn’t break functionality.

See the README in the frameworks repository for more detail about how these things work.

After cloning the content:

Confirm and update any service or declaration questions with the category team and a content designer before launch. It’s advisable to keep any script-generated dates in the content to a far-future year (e.g. 1st March 2525) until they are confirmed with CCS.
Add in new deadline dates, links to GOV.UK content and home page messages (the cloning script should have put in placeholders for these, currently 2525). This should be approved by a content designer.
Add service questions that shouldn’t be copied between framework iterations (for example, because they have been removed or changed significantly) to questions_to_exclude under metadata/copy_services.yml. Note: For G-Cloud 12 and earlier, this file listed questions_to_copy rather than questions_to_exclude, to explicitly state which questions were copyable. This is now deprecated. See Supplier FE for usage.
Mark any significantly-changed declaration questions as prefill: false in manifests/declaration.yml.
Add any new free text fields for G-Cloud services to the scan-g-cloud-services-for-bad-words.py script.
Update the version number in the frameworks repository’s package.json file (make sure package-lock.json is also updated!).
Pull in the new version of the frameworks package to all the frontend apps. For the Briefs FE, Brief Responses FE and Supplier FE, you will also need to load the content for the new framework in app/main/__init__.py. Update all unit tests that reference the previous framework iteration.
Run framework-applications/generate-questions-csv.py from the scripts repository to export the declaration and service questions as a CSV file, ready to publish for suppliers. These files will normally be published by a framework manager using the admin interface.

2 - Generate service validation schemas and add them to the API ¶

The API needs service validation schemas for each lot on the new framework, to validate requests containing service data.

In the frameworks repository, add the required schema names to the list in schema_generator/validation.py

Then (assuming your API code is checked out in a folder at the same level as your frameworks code) run:

python ./scripts/generate-validation-schemas.py --output-path=../digitalmarketplace-api/json_schemas/

Then commit the freshly-generated schemas into the API.

If there are subsequent changes to questions in the frameworks repo, remember to regenerate the schemas.

3 - Add a supplier declaration validator (optional)¶

Unlike services, supplier declarations are validated in the supplier frontend due to the limitations of JSON schema (specifically that it can’t be used to conditionally validate based on values of keys elsewhere in the JSON).

Frameworks from G-Cloud 8 onwards use a shared validator class to validate frameworks. If no validator is specified for a framework this shared validator will be used by default.

If the new framework requires any custom validation (e.g. dependencies between questions), create a new class in the supplier frontend as follows:

Add the new framework to the validator list in app/main/helpers/validation.py.
Add any new optional and/or dependent declaration questions to the validator (for example, conditional followup questions).

4 - Check application email templates ¶

A number of emails are sent during framework applications. Make sure all the emails below have templates on GOV.UK Notify, and that they have been checked by the framework product manager and a content designer:

The new framework is coming

Applications are open

You have started an application

You have submitted a clarification question

Clarification questions have been updated

Clarification questions are closing today

Applications are closing soon

Applications are closed

You submitted an application / You did not submit an application

Notify successful suppliers of award

Framework is now live

Unsuccessful suppliers will be contacted separately by the category team.

5 - Create any new lots ¶

If the new framework also has new lots, these will have to be created by a database migration (the API does not currently support creating or modifying lots).

If the lots already exist, you can re-use the existing lot slugs when creating your new framework via the API (this is step 1 in the framework lifecycle).

6 - Upload legal documents ¶

The following legal documents need to be uploaded to S3 by a developer.

They should be uploaded to the communications bucket in the <framework_slug>/communications folder. The filenames are important, as the Supplier Frontend checks whether these files are present, and links them in specific places on the supplier’s framework dashboard.

<framework-slug>-invitation.pdf (Invitation to Tender)

<framework-slug>-proposed-call-off.pdf (Call-off Contract)

<framework-slug>-proposed-framework-agreement.pdf (Framework Agreement)

<framework-slug>-reporting-template.xls (MI Reporting template)

The documents need to be prepared by CCS and checked by a GDS content designer for clarity/accessibility, so they may not be availble straightaway. You can add placeholder documents on the Preview S3 bucket (e.g. digitalmarketplace-communications-preview-preview/g-cloud-12/communications) to test that the links are showing correctly, but make sure to only add the signed-off documents to the Production S3 bucket.

Note that the ‘proposed’ call-off contract and framework agreement are just that - proposed. These are not the final documents and will not be public until the framework is awarded (after standstill ends). Suppliers must log into their accounts to view these documents.

Any other framework documents (for example: question export CSVs, changes between iterations) can be uploaded by a framework manager in the Admin. These are stored in a subfolder of the same S3 bucket (e.g. digitalmarketplace-communications-preview-preview/g-cloud-12/communications/updates/communications) and will be displayed in the general ‘communications’ document list in the supplier’s account.

7 - Generate the assessment schemas ¶

Note

This can be done at any time before applications close

Run the generate-assessment-schema.py script in our frameworks repository, to create the pass/fail json schema with which we assess suppliers’ declarations. Pipe the output to the /schemas folder in the scripts repository and commit it.

For example, to generate assessment schema for G-Cloud 12:

./scripts/generate-assessment-schema.py g-cloud-12 > ../digitalmarketplace-scripts/schema/g-cloud-12-assessment-schema.json

If the declaration has new mitigatingFactors questions for discretionary failures, add these to the export-framework-results-reasons.py script in the scripts repository, for inclusion in the pass/fail report (to be sent to CCS).

DOS frameworks used to also have assessment schemas for services, but these are now validated in the API, in the same way as G-Cloud services.

8 - Create a new search mapping (G-Cloud only)¶

Note

This can be done at any time before the framework goes live

Run the generate-search-config.py script from the frameworks repository to generate a search mapping for the new G-Cloud index. This should take the name <doctype>-<framework_slug>, e.g. services-g-cloud-10.
Commit the output to the Search API repository, under digitalmarketplace-search-api/mappings.

9 - Load test ¶

Check that the Digital Marketplace will be able to handle the traffic for this framework by running load tests.

10 - Let’s go!¶

Everything is now set up and ready to create and launch the new framework itself! Follow the steps in Framework lifecycle for developers to get cracking.

Note

Check with the framework’s product manager and/or the comms team before you start the next steps in production, as the creating the framework in the database will display information to users on the home page.