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.

/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.

/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.

/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.

/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.

/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.

/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.

/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