Requirements

Introduction

Requirements is the term that we use for software statements of "functional user requirements" or "user stories".  Other tools commonly refer to this resource as a Story or Issue or requirement.


#Get-a-Single-Requirement-CSHUJ

#Get-a-Single-Requirement-with-Suggested-Tests-_beps

#-Get-Many-Requirements-7bDN9

#Add-a-Requirement--14G0B

#-Update-a-Requirement---PUT-n-s49

#Delete-a-Requirement--O5CON


Get a Single Requirement

GET https://api.scopemaster.com/api/v1/apps/{App_ID}/requirements/{requirement_ID}   or

GET https://api.scopemaster.com/api/v1/requirements/{requirement_ID}  

example:

GET https://api.scopemaster.com/api/v1/apps/AP9767978/requirements/RQa08b20f03b

Example response 

{ 
	"app_id": "AP72f6ed657b", 
	"id": "RQa08b20f03b",
	"title": "add delivery address", 
	"ref": "US01",
	"body": "As a visitor I want to add my delivery_address", 
        "rtype": 0, 
	"notes": "",
	"external_id": "",
	"created_utc": 1572969724,
	"updated_utc": 1573596283,
	"cfp": 4, 
	"analysis":[
		{
		"phrase": "add delivery_address",				
		"object": "delivery_address",	
		"dms":{ 
			"send new delivery_address data": "E",
  			"check if delivery_address id exists": "R",
  			"write new delivery_address": "W",
 			"return error/confirmation": "X"
 			}
 		}
 	],
	"links_from": [
        	{
          	  "id": "91",
          	  "link_type": "RELATES",
           	 "link_from": "RQ76508350cf",
           	 "link_to": "RQ9932f1ecc4",
          	  "label": "menu click"
        	}
    	],
   	 "links_to": [],
   	 "tags": [
    	    {
       	     	"tag_id": "TGee69b34767",
            	"label": "discuss with customer"
            },
       	   {
           	 "tag_id": "TGd00ec1abc9",
           	 "label": "sprint 1"
        	}
    	]
 }
Field Name Description
app_id Parent (container) app for this requirement.
id id 
title A short title for the requirement.
body The functional part of the user story.  This is what gets analysed to detect functional intent of the requirement.
ref Your own reference id for the user story
notes Any information of the requirement that is NOT the functional description.
rtype A requirement has an rtype integer value as follows:
0 = Functional (default)
1= Non-functional
2=Task
3= Constraint
cfp COSMIC function points, the universal ISO standard for software size measurement.
qscore qscore is the quality score for the individual requirement.
Analysis sub object This is the results of the functional intent detection. 
dms stands for data movements
Entry, Read, Write and eXit  are the four data movements
that are core to the COSMIC sizing methodology. 

Get a Single Requirement using internal or external IDs

If you want to synchronise with an external source, the ScopeMaster project container (app) must contain a valid external_project_id and each requirement must contain an external_id.


GET https://api.scopemaster.com/api/v1/requirement/{container_id}/{requirement_ID}  

where {container_id} can be the ScopeMaster app_id OR the external_project_id (eg. Azure DevOps, or Jira project_id) and {requirement_ID} can be the ScopeMaster requirement_id OR the external_id (eg. Azure DevOps, or Jira issue_id )


Get Many Requirements

GET https://api.scopemaster.com/api/v1/apps/{app_id}/requirements  

example request for all the stories in an app

GET https://api.scopemaster.com/api/v1/apps/AP9767978/requirements 

curl -i -X GET \
   -H "Authorization:Basic Y29saW5AYWxiaW9udGVjaC5jb206azgwd2dzZ2trbzhzOGNzzzA0Y2NrY2swggggd2dvczBnNGM4czhnZw==" \
 'https://api.scopemaster.com/v1/apps/AP72f6ed657b/requirements'

Get a Single Requirement with Suggested Tests

ScopeMaster derives suggested functional tests for any successfully sized functional requirement.

Example Request:

GET https://api.scopemaster.com/api/v1/requirements/{requirement_ID}/suggested_tests  

Example Response:

{
    "app_id": "APac056df2a4",
    "id": "RQ3f894255da",
    "title": "random title 154",
    "ref": "",
    "body": "as a person I can update stuff",
    "notes": "some notes",
    "org_id": "OR30c8746905",
    "external_id": "ext_562",
    "created_utc": 1574019132,
    "updated_utc": 1574019959,
    "analysed_utc": 1574019959,
    "analysed": true,
    "cfp": 3,
    "qscore":56.6,
    "functional_steps_count": 1,
    "analysis": [
        {
            "phrase": "update stuff",
            "object": "stuff",
            "dms": {
                "Send updated stuff": "E",
                "write updates": "W",
                "return error / confirmation": "X"
            }
        }
    ],
    "self": "http://api.scopemaster.com/v1/requirement/RQ3f894255da",
    "suggested_tests": {
        "scenarios": [
            {
                "scenario_name": "POSITIVE: update a valid stuff",
                "phrase": "Update stuff",
                "description": "Use a given valid stuff identifier ",
                "checks": [
                    "1: Check that data is accepted ",
                    "2: Check that the stuff changes have been correctly stored  ",
                    "3: Check that a confirmation message was generated ",
                    "4: Check that subsequent navigation is correct "
                ]
            },
            {
                "scenario_name": "NEGATIVE: update an invalid stuff with a valid identifier",
                "phrase": "Update stuff",
                "description": "Use a valid identifier and an invalid stuff attributes",
                "checks": [
                    "1: Check that correct errors have been returned  ",
                    "2: Check that nothing has been modified",
                    "3: Check that subsequent navigation is correct "
                ]
            }
        ],
        "check_count": 7,
        "scenario_count": 2
    }
}

Get a Single Requirement with Quality Feedback (potential defects)

ScopeMaster requirements quality engine identifies potential defects and quality suggestions that are made available through the API

Example Request:

GET https://api.scopemaster.com/api/v1/requirements/{requirement_ID}/quality  

The qscore is a percentage indication of overall quality of this individual requirement.

quality_messages include positive and negative feedback on this specific requirement.  Each quality_message has four attributes:

  • type:  POSITIVE, NEGATIVE or ADVISORY
  • category:  A short title of the category of defect/message
  • severity: Allowable values are: Critical, High, Medium, Low, Advisory
  • description: A context specific message describing the problem and potential corrective suggestion.

Example Response:

{
    "app_id": "APac056df2a4",
    "id": "RQ3f894255da",
    "title": "random title 154",
    "ref": "",
    "body": "as a person I can update stuff",
    "notes": "some notes",
    "org_id": "OR30c8746905",
    "external_id": "ext_562",
    "created_utc": 1574019132,
    "updated_utc": 1574019959,
    "analysed_utc": 1574019959,
    "analysed": true,
    "cfp": 3,
    "functional_steps_count": 1,
    "qscore":56.6,
    "self": "http://api.scopemaster.com/v1/requirement/RQ3f894255da",
    "quality_messages":[ 	
            {
                "type": "NEGATIVE",
                "category": "Missing",
                "severity": "M",
                "description": "Potentially missing from this set of requirements:Delete stuff"
            },
  	  {
                "type": "NEGATIVE",
                "category": "No Benefits",
                "severity": "M",
                "description": "No business benefits have been provided"
            },

                "type": "ADVISORY",
                "category": "Security OWASP1 Injection",
                "severity": "ADVISORY",
                "description":"Perform security check on input for stuff. #1 OWASP Top 10, 2017" 
            },
 	   {
                "type": "POSITIVE",
                "category": "Sizeable",
                "severity": "M",
                "description": "Successfully sized in COSMIC Function Points"
            }
	]
           
}

Add a Requirement 

Requirements must be added to a pre-existing app_id, the app must have been created first within ScopeMaster, then requirements can be added to it from the API.

POST https://api.scopemaster.com/api/v1/apps/{app_id}/requirements

Your POST must include a json object with these text fields:

Field Description Example
app_id required  AP097981
external_id
required Must be unique to this app. Used for synchronisation.  e.g.  your Jira issue ID. 1234
title
required must be unique to this app
(max 256 chars) 		Profile handling - update
body
required functional part of the user story.  Include the user, the object of interest and what is to be done to it. As an administrator I want to update profiles
ref Optional.  An user friendly id (max 40 chars) AB_1234
notes Optional. Test criteria, business case and
any non-functional information

Example POST request payload:

{
	"title": "As a [site] editor I can save information",
	"ref": "MG-101",
	"body": "As a [site] editor I can save information in a trainers-only section [so that only trainers see it.]",
	"notes": null,
	"external_id": "MG-101",
}

Response returns a copy of the object as per GET requirements/{requirement_id}


Update a Requirement - PUT

You can only modify the following fields only title, body, ref, notes.  The external_id cannot be changed.

PUT https://api.scopemaster.com/api/v1/requirements/{requirement_id}

Example to update the fields of a requirement

PUT https://api.scopemaster.com/api/v1/requirements/RQ9767978/

PUT Payload:

{
   "app_id":"APb632487c49"	,
   "requirement_id":"RQe53d8abb9d"	,
 	 "data":{
  		"title": "123456",
   		 "body": "As an editor I can swing red shoes "
     }
}

Response returns a copy of the object as per GET requirements/{requirement_id}


Delete a Requirement 

If you have permissions to do so.

DELETE https://api.scopemaster.com/api/v1/requirements/{requirement_id}

This will delete all historical edits of the requirement too.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us

Related Articles