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
email	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