RamRisk API Manual¶
Version November 2024
Rambøll
Hannemanns Allé 53
DK-2300 København S
T +45 5161 1000
F +45 5161 1001
www.ramboll.dk
For further information, please contact support@ramrisk.com
The newest version of this manual can be downloaded from ramrisk.com
Introduction¶
The RamRisk API gives access to RamRisk data through a simple RESTful service, allowing for application developers to benefit from the platform in any way they want, be it for quick access to responsibilities of users or completely recreating the frontend to suit other business needs.
What you get is the structure and underlying math of the RamRisk system available in its simplest form.
Structure of this document¶
This document is made up of a few topics that are general for the entire API followed by a description of all the available resources. A resource is an object that can be retrieved and/or modified using the API. Examples of resources are Risks, Evaluations, Tags, etc.
Each resource has its own section. Sections for resources can be expected to have the following structure:
- Explanation of the resource and how it fits into the domain
- A table describing each attribute of the resource
- A full example of what the resource could look like
- Descriptions of each API endpoint that has to do with the resource, as well as how to use it
An "endpoint" is a URL location in the API. An endpoint may describe a resource, a list of resources or an action that can be performed on a resource or list of resources.
Versioning and deprecation¶
RamRisk is being continuously developed, which means performance improvements and bugfixes as well as new features are released all the time. Along with those, however, may come changes to the system that may affect the API. In order to minimize problems for API consumers, we make sure to version the service such that we can avoid releasing backwards-incompatible changes that will break consumers' code.
Each version of the API may have an expiry date specified. An API version will be deprecated at latest 6 months before becoming unavailable, giving consumers ample time to adjust their code to the new version.
Currently there are two available versions of the API, version 1 and version 2. The version of the api is specified in the url of the request, where "v1" is included for version 1, and "v2" for version 2.
Example:
- GET /api/v1/projects/
is a request directed at version 1 of the API
- GET /api/v2/projects/
is a request directed at version 2
Unless specified differently in the specific endpoint section, v1 and v2 endpoints will both be available and their results will match. All v1 endpoints have a respective v2 endpoint unless specified differently.
Authentication¶
To get access to the API, the consumer is required to authenticate himself. This is important, so we can check whether the consumer is allowed access and to which projects.
In order to authenticate with the API, the consumer needs to provide basic token authentication, which means the user needs to specify an API token for each request made to the API. The API key is generated from the user profile page once the contract owner (or administrator) has granted the permission to access the API for the contract. In addition, the token can be retrieved by using the API, and providing username and password like in the following example:
>>>>
POST /api/api-token-auth/
Content-Type: application/json
Accept: application/json
{
"username": "bob@example",
"password": "bob123password"
}
<<<<
200 OK
Content-Type: application/json
{
"token": "[...]",
}
The token should be provided in the HTTP header Authorization
and
should be formatted like this Token 383290f1y20359f14701f23
, that is,
the capitalized word "Token" followed by a space, followed by the
token string.
Authorization¶
Once you provide the correct authentication credentials, you can to
access the API endpoints. An important detail is that you may not be
able to access all the same data, that you can access from the
RamRisk website. API access is assigned to users per project, which
means you can only access project data from the projects, where you have
had API access enabled. For example, if you have a project role on
projects A
and B
, and you have only been granted API access on
project A
, then only data from project A
will be available through
the API.
Data resources and discoverability¶
The API resources are structured around the models that are already familiar to RamRisk users, like Risks, Controls, Tags, Evaluations, etc. Each resource is documented in the sections below. All endpoints accept the OPTIONS HTTP verb, which provides information on what can be sent to the endpoint.
As is standard in RESTful APIs, the resource endpoints are divided into
two main groups: collections (/api/v1/projects
) and single objects
(/api/v1/projects/1
). The single objects are represented by a single
JSON object inside curly brackets ({"foo": "bar"}
), which is
simple, but the collections are not simply lists of those.
In order to preserve performance of the API as well as giving the implementers a way to fetch only what is needed, the collection endpoints are paginated. This means that whenever a collection resource is queried, the entire collection will not be fetched; only a page of the collection. The data will be formatted as a JSON object like the following
{
"count": 143, // The amount of objects in the full collection,
"previous": null, // The link to the previous page, if any
"next": "/api/v1/projects?page=2", // The link to the next page, if any
"results": [ // The list of objects in the page
...
]
}
The page size is limited by default to 100 objects. This can be
controlled by specifying the page_size
parameter in the URL. The
parameter page
, together with page_size
, allows full customization
of the pagination options. It is also possible to disable pagination on
request, by setting ?page_size=0
. This will request all the results to
be returned on the same page.
Example:
To return the results number 11 to 20 while querying projects:
GET /api/v1/projects?page=2&page_size=10
Collections of objects returned from most of the entry points can be
sorted to any of the fields. The query parameter that allows sorting is
called ordering
, and it can be used to specify a list of comma
separated fields in respect to which results are ordered. Results can be
ordered both in ascending and descending order. The default order will
be ascending, while for sorting in descending order one needs to prepend
a '-'
in front of the field name.
Example:
To return risks sorted by descending status but ascending title, the request is as follows:
GET /api/v1/projects/1/risks?ordering=-status,title
Resources¶
Project¶
All core information about a project
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the project | |
contract | integer | yes | The id of the contract that has this project | |
title | string | yes | The title of the project | |
date | datetime | yes | The date when the project was created | |
description | string | yes | The description of the project | |
project_id | string | yes | A textual identification of the project | |
project_phase | string | yes | The phase of the project (textual) | |
project_owner | string | yes | The owner of this project | |
project_manager | string | yes | The manager for this project | |
project_type | string | yes | A textual indication of the type of the project | |
project_location | string | yes | A textual indication of the project's location | |
project_office | string | yes | A textual indication of the project's office | |
project_division | string | yes | A textual indication of the project's division | |
budget_price_index | string | yes | The budget price index for the project | |
project_finish | string | yes | A textual indication of the project's finishing date | |
workshop_leader | string | yes | The leader of the workshop (if applicable) | |
workshop_date | string | yes | The date the workshop (if applicable) | |
workshop_participants | string | yes | The participants to the workshop (if applicable) | |
status | integer | yes | The status code for the project * 10 = Open * 20 = Closed |
|
type | integer | yes | The type code for the project * 10 = Project * 20 = Free trial Project * 30 Template |
|
created_at | datetime | yes | The date and time that the project was created | |
created_by | integer | yes | The id of the user that created the project | |
updated_by | integer | yes | The id of the user that last updated the project | |
sys_period | datetime range | yes | The time range in which this revision of the project is valid. An open-ended range marks that this is the current revision |
Example:
{
"id": 1234,
"contract": 123,
"title": "Project Example",
"date": "2018-01-01 12:00:00.00000",
"description": "This is an example for a project.",
"project_id": "PRJ-EXMPL-1234",
"project_phase": "Production phase",
"project_owner": "John Smith",
"project_manager": "Jack Smith",
"project_type": "Example",
"project_location": "Copenhagen, Denmark",
"project_office": "Rambøll Head Office",
"project_division": "Transport",
"budget_price_index": "",
"project_finish": "",
"workshop_leader": "",
"workshop_date": "",
"workshop_participants": "",
"status": 10,
"created_at": "2018-01-01 12:00:00.00000",
"created_by": 1,
"updated_by": 1,
"sys_period": {
"lower": "2018-01-01 12:00:00.00000",
"upper": null
}
}
List projects¶
/api/v1/projects
Gets a list of projects that the user has access to.
Single project¶
/api/v1/projects/{project_id}
Given a specific id, gets information for the specific project.
Project Group¶
All core information about a project group. A project group can either represent a single project, or a folder containing other project groups.
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the project group | |
name | string | yes | The name of the project group | |
ordering | integer | yes | The ordering of the project group | |
project | integer | yes | If the project group is not a folder, the id of the project it represents |
|
parent | integer | yes | If the project group has a parent in the folder structure, the id of the project group that is the parent |
|
user | integer | yes | The id of the user whose project group this is |
Example:
{
"id": 1234,
"name": "Project Folder",
"ordering": 0,
"project": null,
"parent": null,
"user": 1234
}
List project groups¶
/api/v1/projectgroups
Gets a list of project groups that the user has access to.
Single project group¶
/api/v1/projectgroups/{projectgroup_id}
Given a specific id, gets information for the specific project group.
User¶
All core information about a user
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the user | |
username | string | yes | The username for the user | |
string | yes | The email of the user | ||
first_name | string | yes | The first name of the user | |
last_name | string | yes | Middle and surname of the user | |
full_name | string | yes | The user's full name |
Example:
{
"id": 1234,
"username": "bob@example.com",
"email": "bob@example.com",
"first_name": "Bob",
"last_name": "M. Smith",
"full_name": "Bob M. Smith"
}
Get my own user¶
/api/v1/me
Gets your own user. The one that is determined by the provided authentication.
List Users¶
/api/v1/projects/{project_id}/users
Gets users in a project.
UDF Type for project¶
User defined field types are the custom fields which a user can define for a particular project.
A UDF type is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the udf type | |
name | string | no | yes | The name of the user defined field |
type_id | integer | no | yes | The type id of the udf: * TEXT = 10 * NUMBER = 20 * TEXT_LIST = 30 * NUMBER_LIST = 40 * DATE = 70 * DATE_LIST = 80 * LINK = 90 |
object_type_name | string | no | no | If type_id is LINK, specify what is the type of the object. The supported type is "user" |
options | string | no | no | Mandatory for LIST fields, Optional for the other field types populated with options the user can select from |
target_type_name | string | no | yes | Name of the target type, either. "risk" or "control" |
project | integer | yes | no | The id of the project udf is attached to |
Example:
{
"id": 20,
"name": "Nyt felt",
"type_id": 30,
"object_type_name": null,
"options": "Fremragende\nGod\nDårlig\nElendig",
"target_type_name": "risk",
"project": 72
}
List UDF type for a project¶
/api/v1/projects/{project_id}/udf_types
Lists all the user defined field types for a project for all targets i.e risk, control etc.
udf type can be fetched by sending a GET request to the URL, and can be created with a POST request that follows the rules in the structure above.
Single UDF type for a project¶
/api/v1/projects/{project_id}/udf_types/{udf_type_id}
A specific udf type in a project fetched through udf type id
A udf type is fetched with a GET request to the URL, and it can be modified with a PUT request that follows the rules in the structure above.
Risk¶
The risk is the resource that stores all the basic information for a risk. These include description, cause, effect, owner, status, etc. Things like evaluations, confidentiality groups, comments, and controls are their own resources, separate from the risk.
The Risk resource currently exists for v1 and v2. v1 includes a lot of nested structures, while v2 is a simple structure with all the Risk's main fields and related data left out. In cases where you don't need the related data, we recommend using v2, since it will load much faster.
Risk v1 Structure¶
A v1 Risk is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the risk | |
project | integer | yes | The id of the project that the risk belongs to. | |
risk_number | integer | yes | The unique number for the risk within the project | |
title | string | no | no | The title of the risk. |
risk_description | string | no | yes | The main content of the risk. Its description |
cause_description | string | no | no | A description of the risk cause |
effect_description | string | no | no | A description of the risk effect |
notes_description | string | no | no | A text field for containing notes for the risk |
status | integer | no | yes | The status code for the risk * 10 = New * 20 = Open * 30 = Closed * 40 = Discarded |
status_display | string | yes | The text label for the status (new, open, etc.) | |
owner | integer | no | no | The id of the owner of the risk. May be Null |
owner_full_name | string | yes | The full name of the owner (a shortcut) | |
confidential | boolean | yes | Denotes whether the risk is confidential or not | |
tags | Tags | yes | A list of all the tags applied to the risk | |
evaluations | Evaluation list | yes | A list of all the evaluations of the risk | |
worst_risk | MatrixCell | yes | The cell signifying the worst evaluation. This cell is used to determine the "risk level" by examining either the value or the color field, depending on the use case. |
|
worst_risk_eval | integer | yes | The evaluation object ID that has the worst "risk level" between all evaluations of this risk. |
|
created_at | datetime | yes | The date and time that the risk was created | |
created_by | integer | yes | The id of the user that created the risk | |
updated_by | integer | yes | The id of the user that last updated the risk | |
sys_period | datetime range | yes | The time range in which this revision of the risk is valid. An open-ended range marks that this is the current revision |
Example:
{
"id": 28900,
"project": 42,
"risk_number": 6,
"title": "Man hit by falling object",
"risk_description": "Man is hit by a falling object",
"cause_description": "A wire snapped",
"effect_description": "Worker injured",
"notes_description": "Maybe Bob and Alice can look into this issue",
"status": 20,
"status_display": "Open",
"owner": null,
"owner_fullname": "",
"confidential": false,
"tags": [{
"id": 18400,
"project": 42,
"name": "Construction",
"category_name": "Phase",
"ordering": 1,
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 59,
"updated_by": 59,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
}
}],
"evaluations": [{
"id": 42000,
"risk": 28900,
"evaluation_type": 20,
"evaluation_type_display": "present",
"freq_low": 0.05,
"freq_mid": 0.1,
"freq_high": 0.2,
"cons_low": 500.0,
"cons_mid": 1000.0,
"cons_high": 2000.0,
"cell": {...},
"matrix": {...},
"value": 100.0,
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 59,
"updated_by": 59,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
}
}],
"worst_risk": {...},
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 59,
"updated_by": 59,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
}
}
Risk v2 Structure¶
A v2 Risk is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the risk | |
project | integer | yes | The id of the project that the risk belongs to. | |
risk_number | integer | yes | The unique number for the risk within the project | |
title | string | no | no | The title of the risk. |
risk_description | string | no | yes | The main content of the risk. Its description |
cause_description | string | no | no | A description of the risk cause |
effect_description | string | no | no | A description of the risk effect |
notes_description | string | no | no | A text field for containing notes for the risk |
status | integer | no | yes | The status code for the risk * 10 = New * 20 = Open * 30 = Closed * 40 = Discarded |
status_display | string | yes | The text label for the status (new, open, etc.) | |
owner | integer | no | no | The id of the owner of the risk. May be Null |
confidential | boolean | yes | Denotes whether the risk is confidential or not | |
worst_risk | integer | yes | The cell signifying the worst evaluation. This cell is used to determine the "risk level" by examining either the value or the color field, depending on the use case. |
|
created_at | datetime | yes | The date and time that the risk was created | |
created_by | integer | yes | The id of the user that created the risk | |
updated_by | integer | yes | The id of the user that last updated the risk | |
sys_period | datetime range | yes | The time range in which this revision of the risk is valid. An open-ended range marks that this is the current revision |
Example:
{
"id": 28900,
"project": 42,
"risk_number": 6,
"title": "Man hit by falling object",
"risk_description": "Man is hit by a falling object",
"cause_description": "A wire snapped",
"effect_description": "Worker injured",
"notes_description": "Maybe Bob and Alice can look into this issue",
"status": 20,
"status_display": "Open",
"owner": 12,
"confidential": false,
"worst_risk": 337,
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 59,
"updated_by": 59,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
}
}
List risks¶
/api/v1/projects/{project_id}/risks
/api/v2/projects/{project_id}/risks
Since risks are one of the major resources of the application, their path is close to the root. Risks are always accessed under their relevant project.
Risks can be fetched by sending a GET request to the URL, and can be created with a POST request that follows the rules in the structure above.
Single risk¶
/api/v1/projects/{project_id}/risks/{risk_id}
/api/v2/projects/{project_id}/risks/{risk_id}
A specific risk in a project. Please notice that the id
of the risk is
referenced, not the risk_number
.
A risk is fetched with a GET request to the URL, and it can be modified with a PUT request that follows the rules in the structure above.
Attached Controls¶
/api/v1/projects/{project_id}/risks/{risk_id}/controls
Retrieves a list of all the controls that are currently attached to the risk. The controls follow the structure outlined in Control.
This endpoint is read-only.
Attachable Controls¶
/api/v1/projects/{project_id}/risks/{risk_id}/attachable_controls
Retrieves a list of all the controls that are available to be attached to the risk, that is, all controls in the project, that are currently not attached to the risk. The controls follow the structure outlined in Control.
This endpoint is read-only.
Attaching Controls¶
/api/v1/projects/{project_id}/risks/{risk_id}/riskcontrols
In order to attach a control, simply issue a PUT request to the resource URL above containing the following structure:
{
"id": 4
}
Where the id
is the id of the control you wish to attach.
Related Tags¶
/api/v1/projects/{project_id}/risks/{risk_id}/tags
Retrieves a list of all the tags that are related to the risk. The tags follow the structure outlined in Tag. Users can assign tags to the risk with a PUT request to the URL above, specifying a list of tag ids to be attached to the risk. Tags that were previously attached to the risk but are not in the PUT request, will be detached from the risk.
Example of tags to assign to the risk:
{
"tags": [1, 2, 3]
}
RiskTags¶
The structure representing a connection from a tag to a risk.
Structure¶
A RiskTag is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the RiskTag | |
risk | integer | yes | The primary key of the related risk | |
tag | integer | yes | The primary key of the related tag | |
created_at | datetime | yes | The date and time that the RiskTag was created | |
created_by | integer | yes | The id of the user that created the RiskTag | |
updated_by | integer | yes | The id of the user that last updated the RiskTag | |
sys_period | datetime range | yes | The time range in which this revision of the RiskTag is valid. An open-ended range marks that this is the current revision |
Example:
{
"id": 123,
"risk": 34,
"tag": 23,
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 1,
"updated_by": 1,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
}
}
List RiskTags¶
/api/v1/projects/{project_id}/risktags
All RiskTags in a specific project.
RiskTags can be fetched by sending a GET request to the URL.
Single RiskTag¶
/api/v1/projects/{project_id}/risktags/{risktag_id}
A specific RiskTag in a project.
A RiskTag is fetched with a GET request to the URL.
Causalities¶
/api/v1/projects/causalities
A "causality" is an object relating to the cause or effect of a risk. The reason for keeping causes and effects inside of the same resource is a technical one at this point. They are very similarly structured and share a close relationship, so it made sense to keep them close in their abstraction as well.
A single instance of a causality represents either a cause or an effect. Whether it is one or the other is represented by the is_cause flag on the resource.
Structure¶
A Causality is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The primary key of the causality | |
project | integer | yes | The primary key of the related project | |
number | integer | yes | Unique number for the causality inside of its project | |
text | string | no | yes | Text that makes up the content of the causality |
status | integer | no | The status code for the causality * 10 = Possible * 20 = Done * 30 = Discarded |
|
status_display | string | yes | The text label for the status | |
is_cause | boolean | no | yes | Whether it is a cause of effect |
created_at | datetime | yes | The date and time that the causality was created | |
created_by | integer | yes | The id of the user that created the causality | |
updated_by | integer | yes | The id of the user that last updated the causality | |
sys_period | datetime range | yes | The time range in which this revision of the causality is valid. An open-ended range marks that this is the current revision. |
Example:
{
"id": 1,
"project": 2,
"number": 3,
"text": "Wire snaps",
"is_cause": true,
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 3,
"updated_by": 3,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
}
}
List causalities¶
/api/v1/projects/{project_id}/causalities
A GET request to this URL will return a list of all the causalities in
the project specified by risk_id
.
/api/v1/projects/{project_id}/risks/{risk_id}/causalities
A GET request to this URL will return a list of all the causalities on
the risk specified by risk_id
.
Single causality¶
/api/v1/projects/{project_id}/causalities/{causality_id}
Get a single causality specified by causality_id
.
/api/v1/projects/{project_id}/risks/{risk_id}/causalities/{causality_id}
Get a single causality specified by causality_id
, which is attached to
the risk specified by risk_id
.
Causalities can be updated from these URLs.
RiskCausalities¶
The structure representing a connection from a causality to a risk.
Structure¶
A RiskCausality is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the RiskCausality | |
risk | integer | yes | The primary key of the related risk | |
causality | integer | yes | The primary key of the related causality | |
created_at | datetime | yes | The date and time that the RiskCausality was created | |
created_by | integer | yes | The id of the user that created the RiskCausality | |
updated_by | integer | yes | The id of the user that last updated the RiskCausality |
|
sys_period | datetime range | yes | The time range in which this revision of the RiskCausality is valid. An open-ended range marks that this is the current revision |
Example:
{
"id": 123,
"risk": 34,
"causality": 23,
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 1,
"updated_by": 1,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
}
}
List RiskCausality¶
/api/v1/projects/{project_id}/riskcausalities
All RiskCausalities in a specific project.
RiskCausalities can be fetched by sending a GET request to the URL.
Risk comments¶
/api/v1/projects/{project_id}/risks/{risk_id}/comments
All the comments on a given risk listed in descending chronological order.
Structure¶
A Comment is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The primary key of the comment | |
project | integer | yes | The primary key of the related project | |
owner | integer | yes | The primary key of the author | |
owner_short_name | string | yes | E.g. John S. | |
owner_full_name | string | yes | E.g. John Smith | |
owner_email | string | yes | Authors email | |
date | string | yes | Timestamp for the creation of the comment | |
comment | string | no | yes | The actual content of the comment |
risk | integer | yes | The primary key of the related risk | |
created_at | datetime | yes | The date and time that the comment was created | |
created_by | integer | yes | The id of the user that created the comment | |
updated_by | integer | yes | The id of the user that last updated the comment | |
sys_period | datetime range | yes | The time range in which this revision of the comment is valid. An open-ended range marks that this is the current revision |
Example:
{
"id": 1,
"project": 2,
"owner": 3,
"owner_short_name": "John S.",
"owner_full_name": "John Smith",
"owner_email": "john@smith.com",
"date": "2017-01-02 12:45:39.542376",
"comment": "I have ideas for this risk",
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 3,
"updated_by": 3,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
},
"risk": 4
}
List risk comments¶
/api/v1/projects/{project_id}/risks/{risk_id}/comments
A GET request to this URL will return a list of all the comments on the
risk specified by risk_id
. It is also possible to POST a new comment
to the URL above, following the structure outlined in Risk comments.
Single risk comment¶
/api/v1/projects/{project_id}/risks/{risk_id}/comments/{comment_id}
Get a single comment specified by risk_id
. Comments can be updated and
deleted from this URL.
Risk references¶
/api/v1/projects/{project_id}/risks/{risk_id}/references
All the references to or from on a given risk listed in descending chronological order.
Structure¶
See outlined structure in Reference.
List risk references¶
/api/v1/projects/{project_id}/risks/{risk_id}/references
List all references on the risk specified by risk_id
. It is
possible to create a new Reference from this control with a POST request
to the URL above. The data in the request should follow the structure
outlined in Reference.
Single risk reference¶
/api/v1/projects/{project_id}/risks/{risk_id}/references/{reference_id}
Get a single risk reference specified by risk_id
and reference_id
.
Single References can be updated and deleted from the URL above.
Control¶
The control stores information about measures that need to be taken in order to mitigate a risk. A control can be given a deadline and assigned to a user.
Structure¶
A Control is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the Control | |
project | integer | yes | The id of the project that the control belongs to. | |
control_number | integer | yes | no | The unique number for the control within the project. |
description | string | no | yes | The main content of the control |
status | integer | no | no | The status code for the control * 10 = Possible * 20 = Planned * 30 = Ongoing * 40 = Done * 50 = Discarded |
status_display | string | yes | The text label for the status | |
deadline | string | no | no | The date at which the control should have been implemented |
next_deadline | string | yes | When recurrence is enabled, this will display the next deadline defined by the recurrence |
|
assigned_to | number | no | yes | The user responsible for implementing the Control |
assigned_to_full_name | string | yes | The full name of the assigned_to user |
|
urgency | string | yes | A description of how close the deadline is: * "expired" * "close" * "" - empty |
|
has_comments | boolean | yes | Whether the control has comments on it | |
tags | Tags | no | no | A list of all tags applied to the control |
created_at | datetime | yes | The date and time that the control was created | |
created_by | integer | yes | The id of the user that created the control | |
updated_by | integer | yes | The id of the user that last updated the control | |
sys_period | datetime range | yes | The time range in which this revision of the control is valid. An open-ended range marks that this is the current revision |
Example:
{
"project": 42,
"control_number": 6,
"description": "Stronger wire",
"status": 20,
"status_display": "Planned",
"assigned_to": 8,
"assigned_to_fullname": "John Smith",
"deadline": "2017-01-05",
"urgency": "close",
"has_comments": false,
"next_deadline": null,
"tags": [],
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 59,
"updated_by": 59,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
}
}
List controls¶
/api/v1/projects/{project_id}/controls
All controls in a specific project.
Controls can be fetched by sending a GET request to the URL, and can be created with a POST request that follows the rules in the structure above.
Single control¶
/api/v1/projects/{project_id}/controls/{control_id}
A specific control in a project. Please notice that the id
of the
control is referenced, not the control_number
.
A control is fetched with a GET request to the URL, and it can be modified with a PUT request that follows the rules in the structure above.
List attached risks¶
/api/v1/projects/{project_id}/controls/{control_id}/risks
All risks in a specific project attached to a specific control. Risks can be fetched by sending a GET request to the URL.
Related Tags¶
/api/v1/projects/{project_id}/controls/{control_id}/tags
Retrieves a list of all the tags that are related to the control. The tags follow the structure outlined in CATag. Users can assign tags to the control with a PUT request to the URL above, specifying a list of tag ids to be attached to the control. Tags that were previously attached to the control but are not in the PUT request, will be detached from the control.
Example of tags to assign to the control:
{
"tags": [1, 2, 3]
}
Control Recurrence¶
/api/v1/projects/{project_id}/controls/{control_id}/recurrence
The recurrence definition of the control, if any is set. If the control is not recurring, the response will be 404 - not found.
For the case where the control is in fact recurring, the following structure will be given in the response.
Structure¶
Recurrence is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the recurrence definition | |
repr | string | yes | A natural language description of the recurrence | |
control_deadline | string | yes | a shortcut for the date of the control's deadline | |
next_date | string | yes | The new deadline that will follow the current one | |
control | integer | yes | The primary key of the related control | |
scope_type | integer | no | yes | An integer switch determining what the scope of the recurrence is: * 10 = Daily * 20 = Weekly * 30 = Monthly * 40 = Yearly |
day_interval | integer | no | no | The amount of days between occurrences, if using daily scope. |
week_interval | integer | no | no | The number of weeks between occurrences, if using weekly scope. |
week_recur_days | string | no | no | Comma separated list of integers. Each integer represents a weekday on which to recur for weekly scope * 10 = Monday * 20 = Tuesday * 30 = Wednesday * 40 = Thursday * 50 = Friday * 60 = Saturday * 70 = Sunday |
month_date | integer | no | no | The date (1-31) to recur for monthly scope. |
month_interval | integer | no | no | The amount of months between occurrences, if using monthly scope. |
nth_match | integer | no | no | A switch for selecting abstract counting of days in months * 10 = First * 20 = Second * 30 = Third * 40 = Fourth * 50 = Last |
day_of_week | integer | no | no | A switch for selecting specific target days in combination with nth_match * 10 = Monday * 20 = Tuesday * 30 = Wednesday * 40 = Thursday * 50 = Friday * 60 = Saturday * 70 = Sunday * 80 = Workday * 90 = Weekend day * 100 = Day |
year_interval | integer | no | no | The amount of years between occurrences, if using yearly scope |
year_month | integer | no | no | A switch for selecting a month for the yearly scope * 1 = January * 2 = February * 3 = March * 4 = April * 5 = May * 6 = June * 7 = July * 8 = August * 9 = September * 10 = October * 11 = November * 12 = December |
created_at | datetime | yes | The date and time that the recurrence was created | |
created_by | integer | yes | The id of the user that created the recurrence | |
updated_by | integer | yes | The id of the user that last updated the recurrence | |
sys_period | datetime range | yes | The time range in which this revision of the recurrence is valid. An open-ended range marks that this is the current revision |
Example:
{
"id": 3,
"repr": "Every 1st workday of every March of every 3 years",
"control_deadline": "2017-03-01",
"next_date": "2020-03-02",
"control": 42,
"scope_type": 40,
"day_interval": null,
"week_interval": null,
"week_recur_days": null,
"month_date": null,
"month_interval": null,
"nth_match": 10,
"day_of_week": 80,
"year_interval": 3,
"year_month": 3,
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 59,
"updated_by": 59,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
}
}
ControlTags¶
The structure representing a connection from a tag to a control.
Structure¶
A ControlTag is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the ControlTag | |
control | integer | yes | The primary key of the related control | |
tag | integer | yes | The primary key of the related tag | |
created_at | datetime | yes | The date and time that the ControlTag was created | |
created_by | integer | yes | The id of the user that created the ControlTag | |
updated_by | integer | yes | The id of the user that last updated the ControlTag | |
sys_period | datetime range | yes | The time range in which this revision of the ControlTag is valid. An open-ended range marks that this is the current revision |
Example:
{
"id": 123,
"control": 34,
"tag": 23,
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 1,
"updated_by": 1,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
}
}
List ControlTags¶
/api/v1/projects/{project_id}/controltags
All ControlTags in a specific project.
ControlTags can be fetched by sending a GET request to the URL.
Single ControlTag¶
/api/v1/projects/{project_id}/controltags/{controltag_id}
A specific ControlTag in a project.
A ControlTag is fetched with a GET request to the URL.
Control comments¶
/api/v1/projects/{project_id}/controls/{control_id}/comments
All the comments on a given control listed in descending chronological order.
Structure¶
A Comment is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The primary key of the comment | |
project | integer | yes | The primary key of the related project | |
owner | integer | yes | The primary key of the author | |
owner_short_name | string | yes | E.g. John S. | |
owner_full_name | string | yes | E.g. John Smith | |
owner_email | string | yes | Authors email | |
date | string | yes | Timestamp for the creation of the comment | |
comment | string | no | yes | The actual content of the comment |
control | integer | yes | The primary key of the related control | |
created_at | datetime | yes | The date and time that the comment was created | |
created_by | integer | yes | The id of the user that created the comment | |
updated_by | integer | yes | The id of the user that last updated the comment | |
sys_period | datetime range | yes | The time range in which this revision of the comment is valid. An open-ended range marks that this is the current revision |
Example:
{
"id": 1,
"project": 2,
"owner": 3,
"owner_short_name": "John S.",
"owner_full_name": "John Smith",
"owner_email": "john@smith.com",
"date": "2017-01-02 12:45:39.542376",
"comment": "I have ideas for this control",
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 3,
"updated_by": 3,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
},
"control": 4
}
List control comments¶
/api/v1/projects/{project_id}/controls/{control_id}/comments
A GET request to this URL will return a list of all the comments on the
control specified by control_id
. It is also possible to POST a new
comment to the URL above, following the structure outlined in the
Control.
Single control comment¶
/api/v1/projects/{project_id}/controls/{control_id}/comments/{comment_id}
Get a single comment specified by control_id
. Comments can be updated
and deleted from this URL.
Control references¶
/api/v1/projects/{project_id}/control/{control_id}/references
All the references to or from on a given control listed in descending chronological order.
Structure¶
See outlined structure in Reference.
List control references¶
/api/v1/projects/{project_id}/controls/{control_id}/references
List all references on the control specified by control_id
. It
is possible to create a new Reference from this control with a POST
request to the URL above. The data in the request should follow the
structure outlined in Reference.
Single control reference¶
/api/v1/projects/{project_id}/controls/{control_id}/references/{reference_id}
Get a single control reference specified by control_id
and
reference_id
. Single References can be updated and deleted from the
URL above.
RiskControls¶
The structure representing a connection from a control to a risk.
Structure¶
A RiskControl is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the RiskControl | |
project | integer | yes | The id of the project that the RiskControl belongs to. | |
risk | integer | yes | The primary key of the related risk | |
control | integer | yes | The primary key of the related RiskControl | |
created_at | datetime | yes | The date and time that the RiskControl was created | |
created_by | integer | yes | The id of the user that created the RiskControl | |
updated_by | integer | yes | The id of the user that last updated the RiskControl | |
sys_period | datetime range | yes | The time range in which this revision of the RiskControl is valid. An open-ended range marks that this is the current revision |
Example:
{
"id": 123,
"project": 12,
"risk": 34,
"control": 23,
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 1,
"updated_by": 1,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
}
}
List RiskControls¶
/api/v1/projects/{project_id}/riskcontrols
All RiskControls in a specific project.
RiskControls can be fetched by sending a GET request to the URL.
Single RiskControl¶
/api/v1/projects/{project_id}/riskcontrols/{riskcontrol_id}
A specific RiskControl in a project.
A RiskControl is fetched with a GET request to the URL.
ControlCosts¶
The cost of controls referred to a RiskTarget.
Structure¶
A ControlCost is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the ControlCost | |
project | integer | yes | The id of the project that the ControlCost belongs to. | |
risk_target | integer | no | The primary key of the related risk target | |
risk_target_name | string | yes | The name of the related risk target | |
unit | string | yes | The unit of the related risk target | |
control | integer | no | The primary key of the related control | |
value | integer | no | The value of this control cost, expressed in the unit of the risk target |
|
created_at | datetime | yes | The date and time that the control cost was created | |
created_by | integer | yes | The id of the user that created the control cost | |
updated_by | integer | yes | The id of the user that last updated the control cost | |
sys_period | datetime range | yes | The time range in which this revision of the control cost is valid. An open-ended range marks that this is the current revision |
Example:
{
"id": 123,
"project": 12,
"risk_target": 34,
"control": 23,
"type": 10,
"value": 1000,
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 1,
"updated_by": 1,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
}
}
List control costs¶
/api/v1/projects/{project_id}/controlcosts
/api/v1/projects/{project_id}/controls/{control_id}/controlcosts
All control costs in a specific project and/or for a specific control.
Control costs can be fetched by sending a GET request to the URLs. New control costs can be created with a POST request to the URLs.
Single control cost¶
/api/v1/projects/{project_id}/controlcosts/{controlcost_id}
/api/v1/projects/{project_id}/controls/{control_id}/controlcosts/{controlcost_id}
A specific control cost in a project.
A control cost is fetched with a GET request to the URL. A control cost can be updated with a PUT/PATCH request to the URL. A control cost can be deleted with a DELETE request to the URL.
RiskReviews¶
The information regarding who and when reviewed a certain Risk.
Structure¶
A RiskReview is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the RiskReview | |
project | integer | yes | The id of the project that the RiskReview belongs to |
|
risk | integer | yes | The primary key of the related risk | |
reviewed_by | string | yes | The primary key of the User who performed the review | |
reviewed_by_full_name | string | yes | The full name of the User who performed the review | |
modified | date | yes | The date when the last review was performed |
Example:
{
"id": 123,
"project": 111,
"risk": 222,
"reviewed_by": 333,
"reviewed_by_full_name": "John Smith",
"modified": "2017-01-02"
}
Single RiskReview¶
/api/v1/projects/{project_id}/risks/{risk_id}/riskreview
The review of the given Risk.
A review is fetched with a GET request to the URL.
Action¶
The action is a way to break up a control into multiple tasks. The point is that a control may be too big for one person to be responsible for, and thus it is useful to be able to break it up and assign individual tasks to different people.
Structure¶
An Action is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the Action | |
project | integer | yes | The id of the project that the action belongs to. |
|
control | integer | yes | The id of the control that owns the action | |
action_number | integer | yes | no | The unique number for the action within the project. |
description | string | no | yes | The main content of the action |
assigned_to | number | no | no | The user responsible for performing the action |
deadline | string | no | no | The date at which the action should have been performed |
status | integer | no | yes | The status code for the action * 10 = Possible * 20 = Planned * 30 = Ongoing * 40 = Done * 50 = Discarded |
status_display | string | yes | The text label for the status | |
assigned_to_full_name | string | yes | The full name of the "assigned_to" user | |
tags | Tag list | no | no | A list of all tags applied to the action |
created_at | datetime | yes | The date and time that the action was created | |
created_by | integer | yes | The id of the user that created the action | |
updated_by | integer | yes | The id of the user that last updated the action | |
sys_period | datetime range | yes | The time range in which this revision of the action is valid. An open-ended range marks that this is the current revision. |
Example:
{
"project": 42,
"action_number": 6,
"control": 79,
"description": "Stronger wire",
"status": 20,
"status_display": "Planned",
"assigned_to": 8,
"assigned_to_fullname": "John Smith",
"deadline": "2017-01-05",
"has_comments": false,
"next_deadline": null,
"tags": [],
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 59,
"updated_by": 59,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
}
}
List actions¶
/api/v1/projects/{project_id}/actions
All actions in a specific project.
Actions can be fetched by sending a GET request to the URL, and can be created with a POST request that follows the rules in the structure above.
/api/v1/projects/{project_id}/controls/{control_id}/actions
All actions owned by a specific control.
Single action¶
/api/v1/projects/{project_id}/actions/{action_id}
A specific action in a project. Please notice that the id
of the
action is referenced, not the action_number
.
An action is fetched with a GET request to the URL, and it can be modified with a PUT request that follows the rules in the structure above.
Related Tags¶
/api/v1/projects/{project_id}/actions/{action_id}/tags
Retrieves a list of all the CAtags that are related to the action. The tags follow the structure outlined in CATag. Users can assign tags to the risk with a PUT request to the URL above, specifying a list of tag ids to be attached to the action. Tags that were previously attached to the action but are not in the PUT request, will be detached from the action.
Example of tags to assign to the action:
{
"tags": [1, 2, 3]
}
ActionTags¶
The structure representing a connection from a tag to an action.
Structure¶
An ActionTag is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the ActionTag | |
action | integer | yes | The primary key of the related action | |
tag | integer | yes | The primary key of the related tag | |
created_at | datetime | yes | The date and time that the ActionTag was created | |
created_by | integer | yes | The id of the user that created the ActionTag | |
updated_by | integer | yes | The id of the user that last updated the ActionTag | |
sys_period | datetime range | yes | The time range in which this revision of the ActionTag is valid. An open-ended range marks that this is the current revision. |
Example:
{
"id": 123,
"action": 34,
"tag": 23,
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 1,
"updated_by": 1,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
}
}
List ActionTags¶
/api/v1/projects/{project_id}/actiontags
All ActionTags in a specific project.
ActionTags can be fetched by sending a GET request to the URL.
Single ActionTag¶
/api/v1/projects/{project_id}/actiontags/{actiontag_id}
A specific ActionTag in a project.
A ActionTag is fetched with a GET request to the URL.
Action comments¶
/api/v1/projects/{project_id}/actions/{action_id}/comments
All the comments on a given action listed in descending chronological order.
Structure¶
A Comment is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The primary key of the comment | |
project | integer | yes | The primary key of the related project | |
owner | integer | yes | The primary key of the author | |
owner_short_name | string | yes | E.g. John S. | |
owner_full_name | string | yes | E.g. John Smith | |
owner_email | string | yes | Authors email | |
date | string | yes | Timestamp for the creation of the comment | |
comment | string | no | yes | The actual content of the comment |
action | integer | yes | The primary key of the related action | |
created_at | datetime | yes | The date and time that the comment was created | |
created_by | integer | yes | The id of the user that created the comment | |
updated_by | integer | yes | The id of the user that last updated the comment | |
sys_period | datetime range | yes | The time range in which this revision of the comment is valid. An open-ended range marks that this is the current revision |
Example:
{
"id": 1,
"project": 2,
"owner": 3,
"owner_short_name": "John S.",
"owner_full_name": "John Smith",
"owner_email": "john@smith.com",
"date": "2017-01-02 12:45:39.542376",
"comment": "I have ideas for this control",
"created_at": "2017-01-02 12:45:39.542376",
"created_by": 3,
"updated_by": 3,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
},
"action": 4
}
List action comments¶
/api/v1/projects/{project_id}/actions/{action_id}/comments
A GET request to this URL will return a list of all the comments on the
action specified by action_id
. It is also possible to POST a new
comment to the URL above, following the structure outlined in the Action comments.
Single action comment¶
/api/v1/projects/{project_id}/actions/{action_id}/comments/{comment_id}
Get a single comment specified by action_id
. Comments can be updated
and deleted from this URL.
Action references¶
/api/v1/projects/{project_id}/action/{action_id}/references
All the references to or from on a given action listed in descending chronological order.
Structure¶
See outlined structure in Reference.
List action references¶
/api/v1/projects/{project_id}/actions/{action_id}/references
List all references on the action specified by action_id
. It is
possible to create a new Reference from this action with a POST request
to the URL above. The data in the request should follow the structure
outlined in Reference.
Single action reference¶
/api/v1/projects/{project_id}/actions/{action_id}/references/{reference_id}
Get a single action reference specified by action_id
and
reference_id
. Single References can be updated and deleted from the
URL above.
UDF Value¶
A custom value or a value chosen from options for a udf type for a project
List udf value for a project and target¶
/api/v1/projects/{project_id}/risks/{risk_id}/udf_values
or
/api/v1/projects/{project_id}/controls/{control_id}/udf_values
Lists all the user defined field values for a project and for a particular target either risk or control.
udf value can be fetched by sending a GET request to the URL, and can be created with a POST request that follows the rules in the structure above.
The GET request udf value consists of following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
field_type | object | no | yes | The udf type of a udf value |
value | string | no | yes | The value of the udf type. This value can be custom value for a udf type of text, number or date. |
Example:
{
"field_type": {
"id": 20,
"name": "Nyt felt",
"type_id": 30,
"object_type_name": null,
"options": "Fremragende\nGod\nDårlig\nElendig",
"target_type_name": "risk",
"project": 72
},
"value": "God"
}
The POST request udf value consists of following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
field_type | integer | no | yes | The udf type id of a udf value |
| value | string | no | yes | The value of the udf type. This value can be custom value for a udf type | | | | | | of text, number or date. | | | | | | for udf type of options, value should be one of the options |
Example:
{
"field_type": 20,
"value": "God"
}
Evaluation¶
The evaluation describes a single evaluation of a risk on a risk matrix. The evaluation is hence a reference to the Risk that is evaluated, the Matrix on which it is evaluated and the MatrixCell in which the evaluation is residing. Additionally, the evaluation may contain triple point estimations for frequency and consequence. The value of the evaluation is also available directly.
Structure¶
An Evaluation is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the Evaluation | |
risk | integer | yes | The id of the related risk | |
evaluation_type | integer | no | no (defaults to 20) | The type of evaluation: - 10: Gross - 20: Present - 30: Nett |
evaluation_type_display | string | yes | The name of the evaluation_type: gross/present/nett |
|
freq_low | float | no | no | The "low" part of a frequency triple |
freq_mid | float | no | no | The "mid" part of a frequency triple |
freq_high | float | no | no | The "high" part of a frequency triple |
cons_low | float | no | no | The "low" part of a consequence triple |
cons_mid | float | no | no | The "mid" part of a consequence triple |
cons_high | float | no | no | The "high" part of a consequence triple |
cell | MatrixCell | no | no | The cell in which the evaluation lies |
matrix | Matrix | yes | The matrix that is evaluated on | |
value | float | yes | The calculated value of the evaluation. If matrix.explicit_evaluation, this value is calculated by cmean * fmean. If not, it is calculated by frequency.mid * consequence.mid |
|
created_at | datetime | yes | The date and time that the evaluation was created | |
created_by | integer | yes | The id of the user that created the evaluation | |
updated_by | integer | yes | The id of the user that last updated the evaluation | |
sys_period | datetime range | yes | The time range in which this revision of the evaluation | |
is valid. An open-ended range marks that this is |
||||
the current revision. |
List evaluations¶
/api/v1/projects/{project_id}/evaluations
All evaluations in a specific project.
Evaluations can be fetched by sending a GET request to the URL, and can be created with a POST request that follows the rules in the structure above.
Single evaluation¶
/api/v1/projects/{project_id}/evaluations/{evaluation_id}
A specific evaluation in a specific project.
An evaluation is fetched with a GET request to the URL, and it can be modified with a PUT request that follows the rules in the structure above. A DELETE request to the URL will delete the evaluation.
Matrix¶
The matrix describes a matrix for a risk target. The matrix is built from lists of frequency, consequence, and matrix cell objects along with a few other links. For user friendliness, the name and unit of the risk target is provided as read-only fields on the matrix resource.
Structure¶
A Matrix is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the Evaluation | |
project | integer | yes | The id of the project in which the matrix is defined | |
risk_target | integer | yes | The id of the related risk target | |
rows | integer | yes | The number of rows (frequencies) in the matrix | |
columns | integer | yes | The number of columns (consequences) in the matrix | |
is_opportunity | boolean | no | yes | whether or not the matrix is an opportunity matrix |
consequence_display | integer | no | yes | Governs how consequence descriptions are displayed - 10: user defined description - 20: percentiles - 30: absolute values |
frequency_display | integer | no | yes | Governs how frequency descriptions are displayed - 10: user defined description - 20: absolute values |
percentile_low | decimal | no | Lower percentile used for scaling with budget | |
percentile_mid | decimal | no | Middle percentile used for scaling with budget | |
percentile_high | decimal | no | Higher percentile used for scaling with budget | |
explicit_evaluation | boolean | no | yes | Whether or not the matrix is explicitly evaluated |
scale_with_budget | boolean | no | yes | Whether or not to scale consequence classes with budget |
budget | decimal | no | no | The allocated budget for the risk target |
risk_reserve | decimal | no | no | The available risk reserve for the risk target |
frequencies | Frequency list | yes | A list of frequencies for the matrix | |
consequences | Consequence list | yes | A list of consequences for the matrix | |
cells | MatrixCell list | yes | A list of matrix cells for the matrix | |
risk_target_name | string | yes | The name of the risk target for the matrix | |
risk_target_unit | string | yes | The unit of the risk target for the matrix | |
created_at | datetime | yes | The date and time that the action was created | |
created_by | integer | yes | The id of the user that created the matrix | |
updated_by | integer | yes | The id of the user that last updated the matrix | |
sys_period | datetime range | yes | The time range in which this revision of the matrix is valid. An open-ended range marks that this is the current revision. |
List matrices¶
/api/v1/projects/{project_id}/matrices
Matrices in a specific project.
Matrices can be fetched by sending a GET request to the URL.
Single matrix¶
/api/v1/projects/{project_id}/matrices/{matrix_id}
A specific matrix in a specific project.
A matrix is fetched with a GET request to the URL.
List related evaluations¶
/api/v1/projects/{project_id}/matrices/{matrix_id}/evaluations
Evaluations can be fetched by sending a GET request to the URL and can be created with a POST request that follows the rules in the structure outlined in Evaluation.
MatrixCell¶
The MatrixCell describes a single cell in a risk matrix. It describes the row/column coordinate, the value and the color.
Structure¶
A MatrixCell is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the Evaluation | |
matrix | integer | yes | The id of the matrix of the cell | |
row | integer | yes | The row index of the cell (starting from 1) | |
column | integer | yes | The column index of the cell (starting from 1) | |
color | integer | no | yes | The color of the cell: - 0: low (green) - 10: mid-low (yellow) - 20: mid-high (orange) - 30: high (red) |
value | integer | no | yes | The cell value |
created_at | datetime | yes | The date and time that the action was created | |
created_by | integer | yes | The id of the user that created the action | |
updated_by | integer | yes | The id of the user that last updated the action | |
sys_period | datetime range | yes | The time range in which this revision of the action is valid. An open-ended range marks that this i the current revision. |
Frequency¶
The frequency describes the low/mid/high values for a single row in the matrix.
Structure¶
A Frequency is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the Evaluation | |
matrix | integer | yes | The id of the matrix of the frequency | |
name | string | no | yes | The name of the frequency, e.g. "negligible" |
description | string | no | yes | The description of the frequency, e.g. "don't act" |
row | integer | yes | The row index of the frequency (starting from 1) | |
low | float | no | yes | the "low" value for the low/mid/high range |
mid | float | no | yes | the "mid" value for the low/mid/high range |
high | float | no | yes | the "high" value for the low/mid/high range |
created_at | datetime | yes | The date and time that the action was created | |
created_by | integer | yes | The id of the user that created the action | |
updated_by | integer | yes | The id of the user that last updated the action | |
sys_period | datetime range | yes | The time range in which this revision of the action is valid. An open-ended range marks that this is the current revision. |
Consequence¶
The consequence describes the low/mid/high values for a single column in the matrix.
Structure¶
A Consequence is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the Evaluation | |
matrix | integer | yes | The id of the matrix of the consequence | |
name | string | no | yes | The name of the consequence, e.g. "negligible" |
description | string | no | yes | The description of the consequence, e.g. "Low impact" |
column | integer | yes | The column index of the consequence (starting from 1) | |
low | float | no | yes | the "low" value for the low/mid/high range |
mid | float | no | yes | the "mid" value for the low/mid/high range |
high | float | no | yes | the "high" value for the low/mid/high range |
created_at | datetime | yes | The date and time that the action was created | |
created_by | integer | yes | The id of the user that created the action | |
updated_by | integer | yes | The id of the user that last updated the action | |
sys_period | datetime range | yes | The time range in which this revision of the action is valid. An open-ended range marks that this is the current revision. |
Log Entry¶
The log entry is the resource that stores all the basic information for an entry in the log. Log entries register changes such as creation, update and deletion of other entities, and are produced automatically in the system. They are therefore read-only, except for the field "note" which can be updated. Log entries cannot be deleted.
Structure¶
A log entry is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the Entry | |
action | integer | yes | The id of the Action (if applicable) | |
change_description | string | yes | A description of the change | |
changed_by | string | yes | The name of the user that did the change | |
changed_from | string | yes | The value before the change | |
changed_to | string | yes | The value after the change | |
control | integer | yes | The id of the Control (if applicable) | |
date | datetime | yes | The date and time that the entry was created | |
description_switch | integer | yes | The description switch for the entry * 10 = Cause * 20 = Risk * 30 = Effect * 40 = Notes |
|
description_switch_display | string | yes | The label of the description switch | |
evaluation_type | integer | yes | The evaluation type for the entrybr> * 10 = Gross * 20 = Present * 30 = Nett |
|
evaluation_type_display | string | yes | The label of the evaluation type | |
matrix | integer | yes | The id of the matrix (if applicable) | |
note | string | no | yes | The note of the log |
object_description | string | yes | The description of the object for the entry | |
object_identifier | string | yes | The identifier of the object for the entry | |
object_switch | integer | yes | The object being switched in the entry * 10 = Risk * 20 = Control * 30 = Action * 40 = RiskTarget |
|
object_switch_display | string | yes | The label of the object being switched | |
owner | string | yes | The owner of the object in the entry | |
previous_owner | string | yes | The previous owner of object in the entry | |
project | integer | yes | The id of the project in the entry | |
risk | integer | yes | The id of the risk in the entry (if applicable) | |
risk_target | integer | yes | The id of the risk_target in the entry (if applicable) | |
risk_target_name | string | yes | The label of the risk_target in the entry | |
target_description | string | yes | The description of the target in the entry | |
type_switch | integer | yes | The type of switch in the entry * 10 = Title * 20 = Description * 21 = Cause created * 22 = Cause modified * 23 = Effect created * 24 = Effect modified * 25 = Cause attached * 26 = Cause detached * 27 = Effect attached * 28 = Effect detached * 30 = Status * 40 = Owner * 50 = Evaluation * 60 = Tag * 70 = Deadline * 80 = Attachment * 90 = Detachment * 120 = Create reference * 125 = Modify reference * 130 = Delete reference * 140 = Create comment * 150 = Modify comment * 160 = Delete comment * 170 = CAtag * 180 = Control occurrence * 190 = Create recurrence * 200 = Modify recurrence * 210 = Delete recurrence * 220 = Confidentiality * 230 = Control Cost * 240 = Risk Review * 500 = Change in User Defined Field * 501 = Deletion of User Defined Field * 502 = Renamed User Defined Field |
|
type_switch_display | string | yes | The label for the type of switch in the entry | |
user | integer | yes | The id of the user in the entry (if applicable) |
Example:
{
"id": 1071753,
"action": null,
"change_description": "Evaluation changed on risk target Test",
"changed_by": "Bob M. Smith",
"changed_from": "None",
"changed_to": "1.0 (1, 1)",
"control": null,
"date": "2017-01-02 12:45:39.542376Z",
"description_switch": null,
"description_switch_display": null,
"evaluation_type": 20,
"evaluation_type_display": "present",
"matrix": 1234,
"note": null,
"object_description": "Risk description",
"object_identifier": "Risk #1",
"object_switch": 40,
"object_switch_display": "Risk Target",
"owner": null,
"previous_owner": null,
"project": 123,
"risk": 12345,
"risk_target": null,
"risk_target_name": "Test",
"target_description": "Risk description",
"type_switch": 50,
"type_switch_display": "Evaluation",
"user": 1234
}
List entries¶
/api/v1/projects/{project_id}/entries
All entries in a specific project.
Entries can be fetched by sending a GET request to the URL.
Single entry¶
/api/v1/projects/{project_id}/entries/{entry_id}
A specific entry in a project, identified by id.
An entry is fetched with a GET request to the URL and it can be modified with a PUT request that follows the rules in the structure above. Please notice that only the field note can be updated.
Entries related to an Action¶
/api/v1/projects/{project_id}/actions/{action_id}/entries
Retrieves a list of all the entries that are related to the action. The entries follow the structure outlined in Log Entry.
Entries related to a Control¶
/api/v1/projects/{project_id}/controls/{control_id}/entries
Retrieves a list of all the entries that are related to the control. The entries follow the structure outlined in Log Entry.
Entries related to a Risk¶
/api/v1/projects/{project_id}/risks/{risk_id}/entries
Retrieves a list of all the entries that are related to the risk. The entries follow the structure outlined in Log Entry.
Category¶
The category is the resource that stores all the basic information for a category of risk tags.
Structure¶
A category is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the Category | |
created_at | datetime | yes | The date and time that the category was created | |
created_by | integer | yes | The id of the user that created the category | |
name | string | no | yes | The name of the category |
ordering | integer | no | yes | The ordering of the category |
project | integer | yes | The id of the project that the category belongs to. | |
sys_period | datetime range | yes | The time range in which this revision of the category is valid. An open-ended range marks that this is the current revision. |
|
updated_by | integer | yes | The id of the user that last updated the category |
Example:
{
"id": 12,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
},
"created_at": "2017-01-02T12:34:56.123456Z",
"name": "Category Name",
"ordering": 1,
"created_by": 123,
"updated_by": 234,
"project": 12
}
List categories¶
/api/v1/projects/{project_id}/categories
Categories can be fetched by sending a GET request to the URL and can be created with a POST request that follows the rules in the structure above. Note that only Project Admins can create new categories.
Single category¶
/api/v1/projects/{project_id}/categories/{category_id}
A specific category in a project.
A category is fetched with a GET request to the URL and it can be modified with a PUT request that follows the rules in the structure above. A DELETE request to the URL will delete the category and all its tags. Note that only Project Admins can update and delete a Category.
Tag¶
The tag is the resource that stores all the basic information for a risk tag.
Structure¶
A tag is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the tag | |
category | integer | no | yes | The category of the tag |
category_name | string | yes | The category label of the tag | |
created_at | datetime | yes | The date and time that the tag was created | |
created_by | integer | yes | The id of the user that created the tag | |
name | string | no | yes | The name of the tag |
ordering | integer | no | yes | The ordering of the tag |
project | integer | yes | The id of the project that the tag belongs to. | |
sys_period | datetime range | yes | The time range in which this revision of the tag is valid. An open-ended range marks that this is the current revision. |
|
updated_by | integer | yes | The id of the user that last updated the tag |
Example:
{
"id": 12,
"category_name": "Category Name",
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
},
"created_at": "2017-01-02T12:34:56.123456Z",
"name": "Tag Name",
"ordering": 1,
"created_by": 123,
"updated_by": 234,
"project": 12,
"category": 23
}
List tags¶
/api/v1/projects/{project_id}/tags
Tags can be fetched by sending a GET request to the URL and can be created with a POST request that follows the rules in the structure above. Note that only Project Admins can create a new tag.
Single tag¶
/api/v1/projects/{project_id}/tags/{tag_id}
A specific tag in a project, referenced by its id.
A tag is fetched with a GET request to the URL and it can be modified with a PUT request that follows the rules in the structure above. Note that only Project Admins can update a tag.
CACategory¶
The CACategory is the resource that stores all the basic information for a category of control and action tags.
Structure¶
A CACategory is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the CACategory | |
created_at | datetime | yes | The date and time that the CACategory was created | |
created_by | integer | yes | The id of the user that created the CACategory | |
name | string | no | yes | The name of the CACategory |
ordering | integer | no | yes | The ordering of the CACategory |
project | integer | yes | The id of the project that the CACategory belongs to. | |
sys_period | datetime range | yes | The time range in which this revision of the tag is valid. An open-ended range marks that this is the current revision. |
|
updated_by | integer | yes | The id of the user that last updated the CACategory |
Example:
{
"id": 12,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
},
"created_at": "2017-01-02T12:34:56.123456Z",
"name": "CaCategory Name",
"ordering": 1,
"created_by": 123,
"updated_by": 234,
"project": 12
}
List CACategories¶
/api/v1/projects/{project_id}/cacategories
CACategories can be fetched by sending a GET request to the URL and can be created with a POST request that follows the rules in the structure above. Note that only Project Admins can create a new CACategory.
Single CACategory¶
/api/v1/projects/{project_id}/cacategories/{category_id}
A specific CACategory in a project.
A CACategory is fetched with a GET request to the URL and it can be modified with a PUT request that follows the rules in the structure above. A DELETE request to the URL will delete the CACategory and all its related tags. CACategories can be updated and deleted by Project Admins only.
CATag¶
The CATag is the resource that stores all the basic information for a control and action tag.
Structure¶
A CATag is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the CAtag | |
category | integer | no | yes | The category of the CAtag |
category_name | string | yes | The category label of the CAtag | |
created_at | datetime | yes | The date and time that the CAtag was created | |
created_by | integer | yes | The id of the user that created the CAtag | |
name | string | no | yes | The name of the CAtag |
ordering | integer | no | yes | The ordering of the CAtag |
project | integer | yes | The id of the project that the CAtag belongs to. | |
sys_period | datetime range | yes | The time range in which this revision of the tag is valid. An open-ended range marks that this is the current revision. |
|
updated_by | integer | yes | The id of the user that last updated the CAtag |
Example:
{
"id": 12,
"category_name": "Category Name",
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
},
"created_at": "2017-01-02T12:34:56.123456Z",
"name": "Tag Name",
"ordering": 1,
"created_by": 123,
"updated_by": 234,
"project": 12,
"category": 23
}
List CATags¶
/api/v1/projects/{project_id}/catags
CATags can be fetched by sending a GET request to the URL and can be created with a POST request that follows the rules in the structure above. Note that only Project Admins can create a new CATag.
Single CATag¶
/api/v1/projects/{project_id}/catags/{tag_id}
A specific CATag in a project.
A CATag is fetched with a GET request to the URL and it can be modified with a PUT request that follows the rules in the structure above. CATags can also be deleted with a DELETE request to the URL. Note that only Project Admins can update and delete CATags.
Reference¶
The reference is the resource that stores all the basic information for a reference.
Structure¶
A reference is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the reference | |
backwards | boolean | yes | If the reference goes from a specified object (action, control, risk), this will be true, otherwise false. |
|
created_at | datetime | yes | The date and time that the reference was created | |
created_by | integer | yes | The id of the user that created the reference | |
description | string | no | The description of the reference | |
from_action | integer | no | The action id that the reference is referenced from | |
from_control | integer | no | The control id that the reference is referenced from | |
from_risk | integer | no | The risk id that the reference is referenced from | |
project | integer | yes | The id of the project that the reference belongs to | |
project_name | string | yes | The label of the project that the reference belongs to | |
repr | string | yes | A short explanation of the reference | |
sys_period | datetime | yes | The time range in which this revision of the tag is valid. An open-ended range marks that this is the current revision. |
|
to_action | integer | no | The action id that the reference is referencing | |
to_control | integer | no | The control id that the reference is referencing | |
to_file | file | no | The file that the reference is referencing | |
to_link | string | no | The link that the reference is referencing | |
to_project | integer | yes | The project id of the referenced object (action, control or risk) | |
to_project_name | string | yes | The label of the project of the referenced object (action, control or risk) | |
to_risk | integer | no | The risk id that the reference is referencing | |
updated_by | integer | yes | The id of the user that last updated the reference | |
url | string | yes | The URL of the reference |
Note that when creating a new Reference, exactly only one among the fields [to_action]{.title-ref}, [to_control]{.title-ref}, [to_file]{.title-ref}, [to_link]{.title-ref}, [to_risk]{.title-ref} needs to be specified.
Example:
{
"id": 1,
"repr": "Control #1 Controller Title",
"url": "/2/controls/?control_id=1",
"description": "",
"to_project_name": "Ramrisk Project",
"project_name": "Ramrisk Project",
"backwards": true,
"sys_period": {
"lower": "2017-01-02 12:45:39.542376",
"upper": null
},
"created_at": "2017-01-02 12:45:39.542376",
"to_link": null,
"to_file": null,
"created_by": 3,
"updated_by": 4,
"from_risk": null,
"from_control": 1,
"from_action": null,
"to_risk": 3,
"to_control": null,
"to_action": null,
"project": 2,
"to_project": 2
}
Map Features¶
A map feature is a resource that stores all the basic information for a map feature. A map feature is a point on a map that can be used to represent a location of interest, such as a risk or control.
A Map Feature is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
id | integer | yes | The id of the map feature | |
guid | string | yes | A unique GUID value to identify the map feature across several systems | |
title | string | no | yes | The title of the map feature |
description | string | no | yes | The description of the map feature |
latitude | float | no | yes | The latitude of the map feature |
longitude | float | no | yes | The longitude of the map feature |
altitude | float | no | yes | The altitude of the map feature |
rotation | float | no | yes | The rotation of the map feature |
bim_model_type | integer | no | yes | The BIM model type of the map feature |
geometry_object_type | integer | no | yes | The geometry object type of the map feature |
target_object_id | integer | no | yes | The target object id of the map feature |
target_object_type_id | integer | no | yes | The target object type of the map feature |
coordinate_system_id | integer | no | yes | The coordinate system of the map feature |
List MapFeatures¶
/api/v1/projects/{project_id}/mapfeatures
Can be fetched by sending a GET request to the URL and can be created with a POST request that follows the rules in the structure above.
Allows for posting of a new map feature to the project:
{
"title": "Map Feature Title",
"description": "Map Feature Description",
"latitude": 12.345,
"longitude": 12.345,
"altitude": 12.345,
"rotation": 12.345,
"bim_model_type": 1,
"geometry_object_type": 1,
"target_object_id": 1,
"target_object_type_id": 1,
"coordinate_system_id": 1
}
Single MapFeature¶
/api/v1/projects/{project_id}/mapfeatures/{mapfeature_id}
A MapFeature is fetched with a GET request to the URL, and it can be modified with a PUT request that follows the rules in the structure above
List MapFeatures for Risk¶
/api/v1/projects/{project_id}/risk/{risk_id}/mapfeatures?coordinate_system_id={coordinate_system_id}
Returns a list of map features for the given risk in Json format. Specifying the coordinate system id is optional. By default, the map features are turned into the coordinate system of the project. If the coordinate_system_id is specified, then the map features are turned into the specified coordinate system. The options for the coordinate_system_id can be retrieved by issuing an OPTIONS request at the URL.
Example output format:
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 1234,
"guid": "xxxxxxxxxxxxxxxxxxxxx",
"title": "Map Feature Title",
"description": "Map Feature Description",
"latitude": 12.345,
"longitude": 12.345,
"altitude": 12.345,
"rotation": 12.345,
"bim_model_type": 1,
"geometry_object_type": 1,
"target_object_id": 1,
"target_object_type_id": 1,
"coordinate_system_id": 1
}
]
}
Supports the OPTIONS call, in which case a JSON response is provided with the possible values for the fields bim_model_type, geometry_object_type, target_object_type_id, and coordinate_system_id.
Bim model type options:
"bim_model_type": {
"type": "choice",
"required": true,
"read_only": false,
"label": "Bim model type",
"choices": [
{
"value": 10,
"display_name": "Cube"
},
{
"value": 20,
"display_name": "RAM (risk)"
},
{
"value": 30,
"display_name": "Safety (risk)"
},
{
"value": 40,
"display_name": "RAM (control)"
},
{
"value": 50,
"display_name": "Safety (control)"
},
{
"value": 60,
"display_name": "Helmet"
}
]
}
}
Geometry object type options:
"geometry_object_type": {
"type": "choice",
"required": true,
"read_only": false,
"label": "Geometry object type",
"choices": [
{
"value": 10,
"display_name": "Point - single position"
},
{
"value": 20,
"display_name": "LineString - array of positions"
},
{
"value": 30,
"display_name": "MultiPoint - array of positions"
},
{
"value": 40,
"display_name": "Polygon - array of arrays of positions"
},
{
"value": 50,
"display_name": "MultiLineString - array of arrays of positions"
},
{
"value": 60,
"display_name": "MultiPolygon - multidimensional array of positions"
}
]
}
Target object type options:
"target_object_type_id": {
"type": "field",
"required": true,
"read_only": false,
"label": "Target object type id",
"choices": [
{
"display_name": "controls | control",
"value": 25
},
{
"display_name": "hazards | risk",
"value": 16
}
]
}
Coordinate system options:
"coordinate_system": {
"type": "choice",
"required": true,
"read_only": false,
"label": "Coordinate system",
"choices": [
{
"value": 10,
"display_name": "ED50 / UTM zone 32N"
},
{
"value": 20,
"display_name": "ETRS-GK22"
},
{
"value": 30,
"display_name": "ETRS89 / ETRS-GK22FIN"
},
{
"value": 35,
"display_name": "ETRS89 / ETRS-GK23FIN"
},
{
"value": 40,
"display_name": "ETRS89 / ETRS-GK26FIN"
},
{
"value": 45,
"display_name": "ETRS89 / GK23FIN (3877)"
},
{
"value": 50,
"display_name": "ETRS89 / GK24FIN"
},
{
"value": 60,
"display_name": "ETRS89 / GK25FIN"
},
{
"value": 70,
"display_name": "ETRS89 / GK26FIN"
},
{
"value": 80,
"display_name": "ETRS89/TM35FIN"
},
{
"value": 90,
"display_name": "ETRS89 / TM35FIN(N,E)"
},
{
"value": 100,
"display_name": "KKJ"
},
{
"value": 110,
"display_name": "KKJ / Finland Zone 1"
},
{
"value": 120,
"display_name": "KKJ / Finland Zone 2"
},
{
"value": 130,
"display_name": "NTM zone 10"
},
{
"value": 140,
"display_name": "NTM zone 11"
},
{
"value": 150,
"display_name": "Pseudo-Mercator"
},
{
"value": 160,
"display_name": "WGS-84 (GPS system)"
}
]
}
Post a new MapFeature for risk or control¶
To post a new map feature for either a risk or a control object, issue a POST request to the list endpoint for the respective object. The request body should contain the following format:
{
"title": "",
"description": "",
"latitude": null,
"longitude": null,
"altitude": null,
"rotation": null,
"bim_model_type": null,
"geometry_object_type": null,
"target_object_id": null,
"target_object_type_id": null,
"coordinate_system": null
}
List MapFeatures for Control¶
/api/v1/projects/{project_id}/control/{control_id}/mapfeatures
Returns a list of map features for the given control in Json format:
Example output format:
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 1234,
"guid": "xxxxxxxxxxxxxxxxxxxxx",
"title": "Map Feature Title",
"description": "Map Feature Description",
"latitude": 12.345,
"longitude": 12.345,
"altitude": 12.345,
"rotation": 12.345,
"bim_model_type": 1,
"geometry_object_type": 1,
"target_object_id": 1,
"target_object_type_id": 1,
"coordinate_system_id": 1
}
]
}
Meta endpoints¶
While RamRisk provides much of what is necessary for developers to integrate with their own services, there are some cases where a system might need to be able to store information, which does not fit into the data models that are described in this document so far. To accommodate such cases, we have added the concept of META endpoints. These provide a way to store any JSON object desired on specific data models in the system, for easy retrieval later.
Specifically, it is possible to save JSON objects on individual projects, risks, controls, or actions. These JSON objects can be individually retrieved, updated, or deleted, and can additionally be retrieved by their related objects type, e.g. you can retrieve the JSON objects stored for risk #1 in project #1, or you can retrieve all JSON objects from any risk on project #1, etc.
The reason for making the META object available for these four types is that they each help provide access control, restricting access to projects by roles and restricting access to risks/controls/actions by confidentiality settings. The rules that apply to these types also apply to their respective META objects
Another important point when trying to access these endpoints is that you need to specify a custom HTTP header. Since multiple integrated applications or multiple users with different interest may store META objects on the same URLs, it is important to make sure that they don't access/overwrite each others data. To that end, each of the endpoints are masked by an API App ID, which needs to be generated from the contract page. Once an application ID is generated, you will need to provide an HTTP header like "X-APP-ID: \<my_app_id>". If you do not provide such a key, you will be presented with a "BAD REQUEST" response.
Structure¶
A META object is made up of the following parts:
Name | Type | Read-Only | Required | Comment |
---|---|---|---|---|
created_at | datetime | yes | Time of creation of the META object | |
updated_at | datetime | yes | Time of last update to the META object | |
data | JSON | no | no | A JSON object defined by the API user. |
object_id | number | yes | The primary key of the related object. | |
content_type | string | yes | The type of the related object, either. "project", "risk", "control", or "action" |
Example:
{
"id": 28900,
"created_at": "2017-01-02 12:45:39.542376",
"updated_at": "2017-01-02 12:45:39.542376",
"content_type": "risk",
"object_id": 42,
"data": {
"foo": "bar"
}
}
Listing META objects¶
/api/v1/projects/meta
List meta objects for all projects the user has access to.
/api/v1/projects/{project_id}/risks/meta
List meta objects for all risks of the given project.
/api/v1/projects/{project_id}/controls/meta
List meta objects for all controls of the given project.
/api/v1/projects/{project_id}/actions/meta
List meta objects for all controls of the given project.
Single META object¶
/api/v1/projects/{project_id}/meta
Retrieve the META object for the specific project.
/api/v1/projects/{project_id}/risks/{risk_id}/meta
Retrieve the META object for the specific risk.
/api/v1/projects/{project_id}/controls/{control_id}/meta
Retrieve the META object for the specific risk.
/api/v1/projects/{project_id}/actions/{action_id}/meta
Retrieve the META object for the specific risk.
Reporting¶
Report elements can be retrieved through the API. For List elements, the data requested will be provided in JSON format, while in the case of plots and diagrams (Statistics), the response will contain the data necessary to reproduce the figures, still in JSON format. All Report Elements can be provided with filter data, sorting data, and a list of timestamps. Options will be individual for each element. For specifications about options format and structure of the returned information please refer to the following sections.
Filter Structure¶
Each of the following entries will accept a POST request containing a JSON object as a payload, with the following structure:
Version 1¶
Name | Type | Required | Description |
---|---|---|---|
filter | dict | no | A dict of filter options to be applied to the element, as specified in the following section. |
ordering | dict | no | A dict of options specifying the ordering of the results, in the format specified in the following section. |
labels | dict | no | A dict of ids of existing labels (timestamps) |
project_group | integer | yes | The id of the project group containing the data for which to produce a report element |
opts | dict | no | A dict of options for the specific element |
When requesting a report element, all the data that is requested needs to be inside the scope of the project group added to the filter.
Example:
{
"project_group": 123,
"filter": {
"text_search": "Risk"
},
"ordering": {
"actions": ["action_number"],
"controls": ["control_number"],
"risks": ["risk_number"]
},
"labels": {
"label_selection_type": "manual",
"labels": [1, 2]
},
"opts": {}
}
Version 2¶
Name | Type | Required | Description |
---|---|---|---|
filter | dict | no | A dict of filter options to be applied to the element, as specified in the following section. |
ordering | dict | no | A dict of options specifying the ordering of the results, in the format specified in the following section |
timestamps | dict | no | A dict of ids of existing timestamps (labels) |
project_group | integer | yes | The id of the project group containing the data for which to produce a report element |
opts | dict | no | A dict of options for the specific element |
In version 2 of the api, the report filter option for timestamps has been renamed from "labels" to "timestamps". All the other elements remain the same.
Example:
{
"project_group": 123,
"filter": {
"text_search": "Risk"
},
"ordering": {
"actions": ["action_number"],
"controls": ["control_number"],
"risks": ["risk_number"]
},
"timestamps": {
"timestamp_selection_type": "manual",
"timestamps": [1, 2]
},
"opts": {}
}
Filter¶
Each single option of the form option_name
:option_value
specified in
the filter needs to be encapsulated in the following way:
{
"option_name": "option_value"
}
Boolean options (True or False values) can be left out from the filter if not active.
In case of options that contain lists, the option_value will be a list of values needed in the filter.
Names for filter options are:
Area | Name | Type | Required | Description |
---|---|---|---|---|
Risk | text_search | string | Text associated with the risks. Only risks related to this value will be included. The value can be either a number sequence/range, e.g. "1,2,3,5-9" or |
|
filter_status | list | A list of status codes to be applied to a risk. Codes are: * 10: New * 20: Open * 30: Closed * 40: Discarded |
||
owners | list | A list of ids of desired Risk owners | ||
tags | list | A list of ids of desired Risk tags | ||
confidentiality | list | A list specifying whether to filter confidential risks or not confidential or both. If left blank, both types will be included in the result. Accepted values are: * "conf": for confidential * "nonconf": for not confidential |
||
evaluation | list | A list of RiskTarget ids | ||
verbosity_level | int | Level of Risk verbosity (VerbosityLevels) | ||
Control | text_search | string | Text associated with the controls. Only controls related to this value will be included. The value can be either a number sequence/range, e.g. "1,2,3,5-9" or other text, which will search in title and description |
|
unattached_controls | boolean | A boolean specifying whether to include unattached controls in the result | ||
control_apply_risk_filter | boolean | A boolean specifying whether to apply the risk filter to controls | ||
filter_control_status | list | A list of accepted status codes for controls. Codes are: * 10: Possible * 20: Planned * 30: Ongoing * 40: Done * 50: Discarded |
||
control_owners | list | A list of ids of desired Control owners | ||
control_tags | list | A list of ids of tags for the Control | ||
control_costs | list | A list of ids of RiskTargets where the Control has ControlCosts | ||
Action | text_search | string | Text associated with the actions. Only actions related to this value will be included. The value can be either a number sequence/range, e.g. "1,2,3,5-9" or other text, which will search in title and description |
|
action_apply_risk_filter | boolean | A boolean that specifies whether to apply the risk filter to actions | ||
action_apply_control_filter | boolean | A boolean specifying whether to apply the control filter to actions | ||
filter_action_status | list | A list of accepted status codes for actions. Codes are: * 10: Possible * 20: Planned * 30: Ongoing * 40: Done * 50: Discarded |
||
action_owners | list | A list of ids of desired Action owners | ||
action_tags | list | A list of tag ids for the Action |
Ordering¶
Each single ordering option is added to the area they belong. The format is shown below:
{
"actions": ["-option_value", "option_value"],
"risks": ["option_value", "-option_value"]
}
Values should just be strings. Ascending is default ordering. Add -
in
front of option_value to order descending.
Option values can be one or more of the following:
Model | Descending | Option Values |
---|---|---|
Risk | - | risk_number worst_risk__value owner date status title project_title |
Control | - | control_number owner deadline status description project_title |
Action | - | action_number owner deadline status description project_title |
Example:
{
"risks": ["-owner", "risk_number"]
}
This example will order owner in descending order and then risks by risk_number ascending order
Timestamps¶
Each single timestamp (label) ID included in the filter needs to be added to the timestamp list:
Version 1 (v1)¶
{
"labels": [40, 41]
}
Version 2 (v2)¶
{
"timestamps": [40, 41]
}
Additionally, it is possible to request all timestamps to be applied to the report by adding the following option:
Version 1 (v1)¶
{
"label_selection_type": "all"
}
Version 2 (v2)¶
{
"timestamp_selection_type": "all"
}
Timestamp (label) ids can be created, retrieved, updated, and destroyed through the API at the following URLS.
/api/v1/projects/{project_key}/labels
/api/v2/projects/{project_key}/timestamps
GETs a list of timestamps in the project and POSTs a new timestamp (label) to the project.
/api/v1/projects/{project_key}/labels/{id}
/api/v2/projects/{project_key}/timestamps/{id}
GETs, modifies and deletes an individual timestamp (label).
/api/v1/users/{user_key}/labels
/api/v2/users/{user_key}/timestamps
GETs a list of timestamps in the project and POSTs a new timestamp to the user.
/api/v1/users/{user_key}/labels/{id}
/api/v2/users/{user_key}/timestamps/{id}
GETs, modifies and deletes an individual timestamp.
Structure¶
A timestamp (label) is made up of the following parts:
Name | Type | Comment |
---|---|---|
id | integer | The id of the timestamp. |
project | integer | The project of the timestamp (if created in single-project scope). |
user | integer | The user of the timestamp (if created in cross-project scope). |
date | datetime | The date of the timestamp. |
title | string | The title of the timestamp. |
Action List¶
/api/v1/reporting/action_list
Action List report elements can be fetched by POSTing the filter options to the URL above.
Options¶
It is possible to specify the following options for the Action List report element:
Name | Type | Required | Description |
---|---|---|---|
actionlist-max_actions | number | The maximum number of actions to include in the results. | |
actionlist-reference_choice | list | Include references to/from actions if provided. * "to": Include to-references * "from": Include from-references |
Example v1:
{
"project_group": 123,
"filter": {
"action_text_search": "Action"
},
"ordering": {
"actions": ["action_number"]
},
"labels": {
"labels": [1, 2]
},
"opts": {
"actionlist-max_actions": 10
}
}
Example v2:
{
"project_group": 123,
"filter": {
"action_text_search": "Action"
},
"ordering": {
"actions": ["action_number"]
},
"timestamps": {
"timestamps": [1, 2]
},
"opts": {
"actionlist-max_actions": 10
}
}
Barplot¶
/api/v1/reporting/barplots
Barplot report elements can be fetched by POSTing the filter options to the URL above.
Options¶
It is possible to specify the following options for the Barplot report element:
Name | Type | Required | Description |
---|---|---|---|
matrices | list | The ids of the matrices that should be used to create barplot elements. Also valid: * "worst_risk_type" * "best_risk_type" |
|
eval_types | list | A list of accepted evaluation types. Codes are: * 10: Gross * 20: Present * 30: Nett |
Example v1:
{
"project_group": 123,
"filter": {},
"ordering": {},
"labels": {
"labels": [1]
},
"opts": {
"matrices": [1,2,3, "worst_risk_type"],
"eval_types": [10, 20]
}
}
Example v2:
{
"project_group": 123,
"filter": {},
"ordering": {},
"timestamps": {
"timestamps": [1]
},
"opts": {
"matrices": [1,2,3, "worst_risk_type"],
"eval_types": [10, 20]
}
}
Estimated Value of Controls¶
/api/v1/reporting/control_value
Estimated Value of Control report elements can be fetched by POSTing the filter options to the URL above.
Options¶
It is possible to specify the following options for the Estimated Value of Control report element:
Name | Type | Required | Description |
---|---|---|---|
matrices | list | The ids of the matrices that should be used to create the element. | |
subtract_costs | boolean | Whether to include control costs in the element or not. |
Example v1:
{
"project_group": 123,
"filter": {},
"ordering": {},
"labels": {
"labels": [1]
},
"opts": {
"matrices": [1,2,3],
"subtract_costs": true
}
}
Example v2:
{
"project_group": 123,
"filter": {},
"ordering": {},
"timestamps": {
"timestamps": [1]
},
"opts": {
"matrices": [1,2,3],
"subtract_costs": true
}
}
Control List¶
/api/v1/reporting/control_list
Control List report elements can be fetched by POSTing the filter options to the URL above.
Options¶
It is possible to specify the following options for the Control List report element:
Name | Type | Required | Description |
---|---|---|---|
controllist-max_controls | number | The maximum number of controls to include in the results. | |
controllist-reference_choice | list | Include references to/from controls if provided. * "to": Include to-references * "from": Include from-references |
Example:
{
"project_group": 123,
"filter": {
"control_text_search": "Control"
},
"ordering": {
"actions": ["control_number"]
},
"opts": {
"controllist-max_controls": 10
}
}
Matrix¶
/api/v1/reporting/matrix
Matrix report elements can be fetched by POSTing the filter options to the URL above.
Options¶
It is possible to specify the following options for the Matrix report element:
Name | Type | Required | Description |
---|---|---|---|
matrices | list | The ids of the matrices that should be used to create matrix elements.br>Also valid: * "worst_risk_type" * "best_risk_type" |
|
previous_timestamp | boolean | Boolean that indicates whether to include previous timestamps. If set to true, a minimum of 2 labels/timestamps is required. |
|
eval_types | list | A list of accepted evaluation types. Codes are: * 10: Gross * 20: Present * 30: Nett |
|
project_for_layout | int | The project id to base the matrix calculations to. |
Example v1:
{
"project_group": 123,
"filter": {},
"ordering": {},
"labels": {
"labels": [1, 2]
},
"opts": {
"previous_timestamp": true,
"eval_types": [10, 20, 30]
}
}
Example v2:
{
"project_group": 123,
"filter": {},
"ordering": {},
"timestamps": {
"timestamps": [1, 2]
},
"opts": {
"previous_timestamp": true,
"eval_types": [10, 20, 30]
}
}
Ownership Change List¶
/api/v1/reporting/ownership_change
Ownership Change list can be fetched by POSTing the filter options to the URL above.
Options¶
No options for this report element.
Ownership Statistics¶
/api/v1/reporting/ownership
Ownership Statistics report elements can be fetched by POSTing the filter options to the URL above.
Options¶
No options for this report element.
Project Information¶
/api/v1/reporting/project_information
Project Information report elements can be fetched by POSTing the filter options to the URL above.
Options¶
No options for this report element.
Risk List¶
/api/v1/reporting/risk_list
Risk List report elements can be fetched by POSTing the filter options to the URL above.
Options¶
It is possible to specify the following options for the Risk List report element:
Name | Type | Required | Description |
---|---|---|---|
list_type | string | A list of accepted list types. Types are: * normal * new * closed * discarded * increased * decreased |
|
max_risks | number | The maximum number of risks to include in the results | |
risk_targets | string/ integer |
A single matrix id that specifies whether to include evaluations on it. Other values can be: * "none": None * "all_risklevels": All evaluations * "risklevel": Highest Risk Level * "bestrisklevel": Highest Opportunity Level |
|
eval_types | list | A list of accepted evaluation types.br>Codes are: * 10: Gross * 19: Previous * 20: Present * 30: Nett |
|
use_previous | boolean | If true, at least 2 labels/timestamps are required. | |
reference_choice | list | Include references to/from risks if provided. * to: Include to-references * from: Include from-references |
Example:
{
"project_group": 123,
"filter": {
"text_search": "Risk"
},
"ordering": {
"risks": ["risk_number"]
},
"opts": {
"max_risks": 20,
"risk_targets": 1
}
}
S-Curve¶
/api/v1/reporting/scurve
S-Curve report elements can be fetched by POSTing the filter options to the URL above.
Options¶
It is possible to specify the following options for the S-Curve report element:
Name | Type | Required | Description |
---|---|---|---|
matrices | list | The ids of the matrices that should be used to create matrix elements. | |
include_budget | boolean | Boolean that indicates whether to include budget or not. | |
percentiles | list | A list of accepted percentiles. Percentiles are: * 0.05: 5% * 0.10: 10% * 0.15: 15% * 0.20: 20% * 0.25: 25% * 0.30: 30% * 0.35: 35% * 0.40: 40% * 0.45: 45% * 0.50: 50% * 0.55: 55% * 0.60: 60% * 0.65: 65% * 0.70: 70% * 0.75: 75% * 0.80: 80% * 0.85: 85% * 0.90: 90% * 0.95: 95% |
|
eval_types | list | A list of accepted evaluation types. Codes are: * 10: Gross * 20: Present * 30: Nett |
Example:
{
"project_group": 123,
"filter": {},
"ordering": {},
"opts": {
"matrices": [1, 2],
"include_budget": true,
"percentiles": [0.05, 0.20, 0.70],
"eval_types": [10, 20, 30]
}
}
Monte Carlo Simulation¶
/api/v1/reporting/monte_carlo
Monte Carlo Simulation report elements can be fetched by POSTing the filter options to the URL above.
Options¶
It is possible to specify the following options for the Monte Carlo Simulation report element:
Name | Type | Required | Description |
---|---|---|---|
matrices | list | The ids of the matrices that should be used to create matrix elements. | |
percentiles | list | A list of accepted percentiles. Percentiles are: * 0.05: 5% * 0.10: 10% * 0.15: 15% * 0.20: 20% * 0.25: 25% * 0.30: 30% * 0.35: 35% * 0.40: 40% * 0.45: 45% * 0.50: 50% * 0.55: 55% * 0.60: 60% * 0.65: 65% * 0.70: 70% * 0.75: 75% * 0.80: 80% * 0.85: 85% * 0.90: 90% * 0.95: 95% |
|
simulations | integer | How many simulations should be performed. Minimum 1 <=> 10.000 Maximum |
|
eval_types | list | A list of accepted evaluation types. Codes are: * 10: Gross * 20: Present * 30: Nett |
Example¶
{
"project_group": 123,
"filter": {},
"ordering": {},
"opts": {
"matrices": [1, 2],
"percentiles": [0.05, 0.20, 0.70],
"simulations": 2000,
"eval_types": [10, 20, 30]
}
}
Status Statistics¶
/api/v1/reporting/status
Status Statistics report elements can be fetched by POSTing the filter options to the URL above.
Options¶
No options for this report element.
Tornado diagram - top risk contributors¶
/api/v1/reporting/risk_value_contributions
Tornado report elements can be fetched by POSTing the filter options to the URL above.
Options¶
It is possible to specify the following options for the Tornado report element:
Name | Type | Required | Description |
---|---|---|---|
matrices | list | The ids of the matrices that should be used to create tornado elements. | |
max_risks | number | One of accepted numbers. Numbers are: * 5 * 10 * 15 * 20 * 50 |
|
eval_types | list | A list of accepted evaluation types. Codes are: * 10: Gross * 20: Present * 30: Nett |
Example¶
{
"project_group": 123,
"filter": {},
"ordering": {},
"opts": {
"matrices": [1, 2],
"max_risks": 10,
"eval_types": [10, 20, 30]
}
}
Value at Risk¶
/api/v1/reporting/valueatrisks
Value at Risk report elements can be fetched by POSTing the filter options to the URL above.
Options¶
It is possible to specify the following options for the Value at Risk report element:
Name | Type | Required | Description |
---|---|---|---|
matrices | list | The ids of the matrices that should be used to create VaR elements. | |
categories | list | Category ids will be used to stack values, if provided. | |
include_costs | bool | Whether or not to load the Cost of controls into the results. | |
eval_types | list | A list of accepted evaluation types. Codes are: * 10: Gross * 20: Present * 30: Nett |
Example¶
{
"project_group": 123,
"filter": {},
"ordering": {},
"opts": {
"matrices": [1, 2],
"categories": [1],
"eval_types": [10, 20, 30]
}
}
Value at Risk Difference¶
/api/v1/reporting/var_diff
Value at Risk Difference report elements can be fetched by POSTing the filter options to the URL above.
Options¶
It is possible to specify the following options for the Value at Risk Difference report element:
Name | Type | Required | Description |
---|---|---|---|
matrices | list | The ids of the matrices that should be used to create matrix elements. | |
sort | string | One of accepted sort codes. Codes are: * "by_value": By Value * "by_abs_value": By Absolute Value * "by_type": By Type |
|
eval_types | list | A list of accepted evaluation types. Codes are: * 10: Gross * 20: Present * 30: Nett |
Example¶
{
"project_group": 123,
"filter": {},
"ordering": {},
"opts": {
"matrices": [1, 2],
"eval_types": [10, 20, 30]
}
}
Text Field¶
/api/v1/reporting/text_field
Text Field report elements can be fetched by POSTing the filter options to the URL above.
Options¶
It is possible to specify the following options for the Text Field report element:
Name | Type | Required | Description |
---|---|---|---|
text_header | string | A user defined header / title. | |
text_field | string | User defined text for the element. |
Default filter¶
If no filter is provided for the following values, these settings are used.
Fields not mentioned in table below, just default to false/none/empty/nothing.
Name | Type | Default |
---|---|---|
eval_types | integer | 20: Present |
verbosity_level | integer | 1: Limiting |
control_apply_risk_filter | boolean | true |