Authoring Platform Version 6+ User Guide

Page tree


In this page:

Authoring projects are managed and configured in the Authoring Platform (AP) underlying workflow instance (Jira), using particular field configurations, issue types, workflows and permissions schemes. The process is outlined here to show the underlying platform dependencies and steps to prepare a project for SNOMED CT content authoring, but managing them for the International Authoring Platform is currently a SNOMED International Technical Team support activity. Please note this is not a detailed definition of the support activity steps or Jira setup requirements - those are available in other Technical Team process documentation.

Jira project ticket

An authoring project is defined by a "project" type ticket in the AP workflow Jira instance which must exist for that project to be seen in the AP projects list (it's not sufficient just to create a Jira project). The instance of Jira used is an AP deployment configuration setting. Once defined there is an association between the project tickets in Jira and their corresponding project content branches in the AP terminology server (Snowstorm for AP 6), which are named to match their associated Jira project key (similarly authoring tasks have an associated branch under their parent project branch which is named to match their task ticket Jira ID). These project keys and task IDs can be seen in the various page addresses when using the AP.

Jira product code

AP project visibility depends on a "product code" (Jira custom field) set in the project ticket. Particular AP deployments are configured to use a particular product code (or list of codes). This allows a single Jira instance to support projects across multiple Authoring Platform deployments if needed.

Use Raise an Issue to request a new project

You can use the Raise an Issue process outlined below to request creation of a new authoring project.
Enter the desired project details in the Raise an Issue form. The more information included the better, but the minimum needed is a new project name (this will be what appears in the AP projects listings) and a brief summary of its purpose. Confirmation of which Authoring Platform, a preferred project key satisfying Jira key conventions, and in particular a reference to any similar existing projects, can significantly simplify and hence speed up the process, although these can also be inferred/defined by the Technical Team if not specified.

Raise an Issue


StepsReferences

Press Raise an Issue to report issues or submit change requests related to AP usability and features.

The Raise an Issue pop-up form is presented. If the form height is larger than your available web browser display height, a vertical scroll bar will appear to allow you to scroll down and see all the form content (the form header title and footer actions remain visible whilst scrolling). The following fields are available:

  • Summary (required, single line text, maximum of 255 characters)
  • Description (multi-line text with markup formatting support for structured text)
  • Attach file (
  • Priority (single choice option list selector)
  • Name (single line text, maximum of 255 characters)
  • Email (single line text, maximum of 255 characters)
  • Include data about your current environment, like the browser and page URL (opt-in checkbox)

The form footer has a Submit action button and a Close link.

Enter the desired details. The more information included the better, but also try to be as concise as possible and ideally keep to one identifiable issue per submission - this will simplify subsequent processing and hence make it quicker to assess, prioritise and investigate further if needed.

The minimum needed is a brief one-line Summary of the issue. Everything below that on the form is optional.

The Description field supports formatting options for structured text. Press the small question mark icon to open a Text Formatting Notation Help pop-up window with guidelines on including advanced formatting (wiki) markup.

You can use the Attach file (Choose Files) field to include a file attachment such as a screenshot.

An indication of the issue impact or urgency can be included using the Priority drop-down selector options. This will be taken into account when assessing the submitted issue but it will be treated as advisory and considered with additional contexts, including capacity and release scheduling - please elaborate any critical dependencies in the Description to help with follow-up prioritisation!

Including your Name and Email will help in identification, tracking and follow-up notifications/discussions.

The opt-in checkbox enables the form to capture details about your current web browser environment. You can press the What is included in the data about my current environment? link to preview those details and help decide whether or not to include them if unsure. Including them can help the technical support teams when troubleshooting defect reports, particularly anything related to screen presentation/layout, but of course it's entirely optional.

Press Submit in the form footer to submit your entered feedback details. A Thank you for your feedback! message will appear for 5 seconds and then the pop-up form will automatically close, returning you to whatever AP context you were in when the Raise an Issue button was pressed.

For the International Authoring Platform this creates a Devops Support (INFRA) ticket, which the Technical Team will assess, prioritise and respond to with appropriate notifications and follow-up actions (your patience is appreciated!).

Alternatively, if you have decided not to raise an issue since opening the form, simply press Close in the form footer to immediately close the pop-up dialogue and return to your AP context.

Close has no second chance!

Be wary there is no guard on the Close action - as soon at it is pressed, any entered information is lost. If you want to preserve anything for a later submission please use your local environment cut/paste tools to capture anything essential first!



What happens after I submit a request for a new project...

The following steps are not done in the Authoring Platform itself, but are included here for information and to complete this overview of how an AP authoring project becomes available

StepsReferences

Create a new project in the Jira workflow instance associated with the Authoring Platform, and associate the project schemes with those needed for content authoring.

Technical Team support activity.
Create a new "project" ticket type in the new project. Ensure that the "product code" matches that configured for the Authoring Platform deployment.Technical Team support activity.
Verify the new project is available in the Authoring Platform (use the Create New Task form to view the available projects list).Technical Team support activity.
Create test task in the new project and perform a search to initialize the project branch in the Terminology Server.Technical Team support activity.
Notify the request originator (INFRA ticket reporter) that the new project is ready for use in the Authoring Platform.Technical Team support activity