Dette dokumentet beskriver REN Kalkyle API. APIet dekker alt som er direkte relatert til kalkylemodulen i REN Prosjekt.

Se REN Prosjekt API for det grunnleggende APIet som alle prosjektmodule-APIer baserer seg på.

For generell informasjon om tilgang, autentisering og bruk av REN API, se Generelt.

Tabell 1. Endringslogg for dokumentet
Dato Beskrivelse

25.01.2019

Første versjon.

05.09.2019

Lagt til priser i katalognoder. I forbindelse med denne endringen ble også katalog-id (catalogId) fjernet fra responsen til katalog endepunktene. Endepunkt for å gjøre oppslag på katalog-id i katalogen er også fjernet.

Oppbygging

REN Kalkyle er en av flere modultyper (også kalt verktøy) som kan knyttes til et REN-prosjekt. REN Kalkyle omfatter REN kostnadskatalog og REN kalkyleverktøy. APIet tilbyr funksjonalitet for å bla i kostnadskatalogen, opprette og tilpasse kalkyler basert på innhold i katalogen, samt beregne kostnader for jobber i fordelingsnettet. I tillegg tilbyr APIet ulike rapporter i JSON-, EXCEL- og PDF-format basert på innholdet i en kalkyle.

For å kunne opprette en kalkyle må det først eksistere et prosjekt som kalkylen kan knyttes til som modul. For hvert prosjekt kan det eksistere én modul av typen kalkyle. For å opprette eller finne prosjekter se REN Prosjekt API.

URL base path

Base path for REN Kalkyle API er https://api.ren.no/public/calculation/rest.

REN kostnadskatalog

REN kostnadskatalog er en oppbygging av budsjettkoder (maler) som igjen er en sammenkobling av arbeid, materiell, ressurser og andre kostnader i en struktur som beskriver de mest vanlige jobbene i fordelingsnettet. Der det er alternative måter å utføre jobben eller alterativer på materiell, vil REN kostnadskatalog inneholde opsjoner (engelsk: options) med mengde 0. Fra REN kostnadskatalog tilbyr APIet funksjonalitet for søking blant og uthenting av disse kodene. Strukturen i budsjettkodene kan benyttes som utgangspunkt for budsjetteringskostnader i en kalkyle.

De fleste endepunktene i APIet for REN kostnadskatalog støtter brukerløs autentisering. Se seksjon Security i den genererte API-dokumentasjonen for detaljer for hvert enkelt REST-endepunkt.

Basis informasjon

REN Kalkyle API benytter anlegg (engelsk: facility), aktivitet (engelsk: activity) og enheter (engelsk: units) ved arbeid mot kostnadskatalogen og kalkylen. Alle kall mot APIet må benytte lovlige verdier av disse egenskapene.

For å se alle gyldige anlegg:

GET https://api.ren.no/public/calculation/rest/facilities (API-dokumentasjon)

For å se alle gyldige aktiviteter:

GET https://api.ren.no/public/calculation/rest/activities (API-dokumentasjon)

For å se alle gyldige enheter:

GET https://api.ren.no/public/calculation/rest/units (API-dokumentasjon)

Revisjoner

REN kostnadskatalog er versjonert med revisjoner. Alle søk mot REN kostnadskatalog må gjøres på en gyldig revisjon. For å søke opp gyldige revisjoner benyttes følgende:

GET https://api.ren.no/public/calculation/rest/revisions (API-dokumentasjon)

For å finne den siste revisjonen benyttes følgende:

GET https://api.ren.no/public/calculation/rest/revisions/latest (API-dokumentasjon)

Nye kalkyler vil automatisk bli knyttet til den siste revisjonen. Når man legger inn innhold i en kalkyle så skjer dette fra den katalogrevisjonen kalkylen er knyttet til.

Katalognoder

REN kostnadskatalog er først og fremst et malverk med en trelignende struktur. Dermed brukes begrepet katalognoder som fellesbetegnelse for budsjettkoder, arbeid, materiell m.m. Se API-dokumentasjonen for katalognoder for detaljer.

For å hente alle katalognoder av en gitt type, uten undernoder og i valgt revisjon, benyttes følgende:

GET https://api.ren.no/public/calculation/rest/catalognodes/by-revision/{revision}/by-type/{type} (API-dokumentasjon)

For eksempel kan man hente alle budsjettkoder (uten undernoder) i siste / eldre revisjon:

GET https://api.ren.no/public/calculation/rest/catalognodes/by-revision/latest/by-type/BUDGET

GET https://api.ren.no/public/calculation/rest/catalognodes/by-revision/{revision}/by-type/BUDGET

Dersom man trenger den fulle trestrukturen til en katalognode med kjent REN-nummer kan man benytte følgende:

GET https://api.ren.no/public/calculation/rest/catalognodes/by-revision/{revision}/by-type/{type}/by-number/{number} (API-dokumentasjon)

Som svar vil man få en struktur som innholder undernoder i full dybde, d.v.s. inkluderer hierarkiske pakker for materiell, arbeid, ressurser og andre kostnader.

For eksempel kan man hente en budsjettkode / arbeid (med undernoder) basert på et kjent REN-nummer:

GET https://api.ren.no/public/calculation/rest/catalognodes/by-revision/latest/by-type/BUDGET/by-number/{number}

GET https://api.ren.no/public/calculation/rest/catalognodes/by-revision/latest/by-type/WORK/by-number/{number}

Det er også mulig å finne katalognoder basert på fritekstsøk og mer avansert filtrering. Se API-dokumentasjonen for detaljer.

Katalognodene vil inneholde enhetspriser for nodetypene arbeid, materiell og annen kost. Pris aggregeres opp i trestrukturen basert på enhetspris for undernoder og mengden av disse. Selskap kan benytte egne priser for ressurser og materiell dersom dette er registrert. For å benytte selskapspriser kreves bruker-autentisering.

REN kalkyleverktøy

En kalkyle er en struktur som beskriver og kostnadsberegner en jobb i fordelingsnettet. En kalkyle er enten av typen REN-kalkyle eller selskapskalkyle. REN-kalkyle vil benytte RENs gjennomsnittspriser for materiell og arbeid. I en selskapskalkyle benyttes selskapets egne priser for materiell og arbeid, der dette er oppgitt.

De fleste endepunktene i APIet for REN kalkyleverktøy krever bruker-autentisering. Se seksjon Security i den genererte API-dokumentasjonen for detaljer for hvert enkelt REST-endepunkt.

Opprettelse av kalkylemodul

Se REN Prosjekt API for hvordan man aktiverer kalkylemodulen i et prosjekt. For å endre kalkyletype (mellom REN-kalkyle og selskapskalkyle) benyttes:

PUT https://api.ren.no/public/calculation/rest/modules/{projectId}/calculationtype/{calculationType} (API-dokumentasjon)

Legge til budsjettkoder kalkylen

For å legge til en budsjettkode i kalkylen benyttes følgende:

PUT https://api.ren.no/public/calculation/rest/calculationnodes/by-projectid/{projectId} (API-dokumentasjon)

Her skal bodyen være en JSON-struktur av typen CatalogNodeAdd. Responsen vil være av typen CalculationNode som inneholder en id som benyttes for videre arbeid med den kalkylenoden. Der det refereres til nodeId er det denne identifikatoren som skal benyttes.

Om man ikke ønsker å inkludere opsjoner i kalkylen kan query-parameteren 'options' settes til false. Husk at opsjoner her betyr noder med mengde 0, som modellerer alternative måter å utføre jobben eller alterativer på materiell. Ved å ekskludere opsjoner vil altså kun noder med standard mengde > 0 bli tatt med.

Her er et eksempel på innlegging av en budsjettkode uten tilpasninger og uten opsjoner:

PUT https://api.ren.no/public/calculation/rest/calculationnodes/by-projectid/12345?options=false

med følgende body:

{
   "number": "G14616",
   "quantity": 3
}

Dersom man ønsker å legge til en tilpasset budsjettkode kan man fjerne noder fra malen eller endre standard mengde. For å fjerne noder i strukturen angis disse med korrekt REN-nummer og exclude=true. Om man ønsker å endre standard mengde på noder i strukturen angis disse med korrekt REN-nummer og quantity=n.

Her er et eksempel på innlegging av en budsjettkode med tilpasninger (sletting og endring av mengde):

PUT https://api.ren.no/public/calculation/rest/calculationnodes/by-projectid/12345

med følgende body:

{
   "number": "G14616",
   "quantity": 3,
   "childNodes":  [
       {
           "number": "A85002",
           "quantity": 4.2
       },
       {
           "number": "P00450",
           "childNodes":  [
               {
                   "number": "A10018",
                   "quantity": 13
               },
               {
                   "number": "A100181",
                   "exclude": "true"
               }
           ]
       }
   ]
}

Legge til og endre fastpriselementer i kalkylen

Fastpriselementer er egendefinerte koder med fast pris som f.eks. kan brukes for rammeavtaler, eller der man ikke finner passende budsjettkoder i kostnadskatalogen. Det er to typer fastpriselementer som kan legges inn i kalkylen: Fastpris, fast enhetspris (engelsk: custom budget, fixed unit cost) og Fastpris, fast totalsum (engelsk: custom budget, fixed total cost).

For å legge til et fastpriselement i kalkylen benyttes følgende:

PUT https://api.ren.no/public/calculation/rest/calculationnodes/custom/by-projectid/{projectId} (API-dokumentasjon)

Her skal bodyen være en JSON-struktur av typen CatalogCustomNodeAdd. Responsen vil være av typen CalculationNode som inneholder en id som benyttes for videre arbeid med kalkylen. Der det refereres til nodeId er det denne identifikatoren som skal benyttes.

Her er et eksempel på innlegging av fastpris med fast enhetspris:

PUT https://api.ren.no/public/calculation/rest/calculationnodes/custom/by-projectid/12345 (API-dokumentasjon)

med følgende body:

{
   "type": "CUSTOMBUDGET_FIXEDUNIT",
   "unit": "km",
   "facilityId": 13,
   "activityId": 1,
   "quantity": 1.2,
   "description": "Fastpris graving av grøft",
   "name": "Fastpris graving",
   "unitCost": 200000
}

Også når man oppdaterer et fastpriselement i kalkylen skal bodyen være en JSON-struktur av typen CatalogCustomNodeAdd:

POST https://api.ren.no/public/calculation/rest/calculationnodes/custom/{nodeId}

Henting av noder i kalkylen

For å hente alle toppnivå-noder (budsjettkoder) i kalkylen:

GET https://api.ren.no/public/calculation/rest/calculationnodes/by-projectid/{projectId} (API-dokumentasjon)

For å hente en spesifikk node, enten en budsjettkode eller en annen node i kalkylen:

GET https://api.ren.no/public/calculation/rest/calculationnodes/{nodeId} (API-dokumentasjon)

Dybden i strukturen man får tilbake er styrt av query-parameteren 'depth'. Ved henting av kalkylenoder kan man altså fritt styre hvor mange nivåer av undernoder man får tilbake.

Sletting av noder i kalkylen

For å slette alle noder i kalkylen:

DELETE https://api.ren.no/public/calculation/rest/calculationnodes/by-projectid/{projectId} (API-dokumentasjon)

For å slette en budsjettkode eller en annen node i kalkylen:

DELETE https://api.ren.no/public/calculation/rest/calculationnodes/{nodeId} (API-dokumentasjon)

Rapporter

For rapportering og uttrekk av data fra kalkylen finnes en rekke REST-endepunkter for JSON-uttrekk samt forhåndsdefinerte PDF- og EXCEL-rapporter.

Mengderapporter

For å hente aggregert mengdeinformasjon for alle støttede nodetyper (arbeid, materiell og annen kost) fra kalkylen i JSON-format:

GET https://api.ren.no/public/calculation/rest/reports/quantity/by-projectid/{projectId}/json (API-dokumentasjon)

For å hente aggregert mengdeinformasjon for en spesifikk nodetype i JSON-format:

GET https://api.ren.no/public/calculation/rest/reports/quantity/by-projectid/{projectId}/by-type/{type}/json (API-dokumentasjon)

For å hente aggregert mengdeinformasjon for en spesifikk nodetype i PDF-format:

GET https://api.ren.no/public/calculation/rest/reports/quantity/by-projectid/{projectId}/by-type/{type}/pdf (API-dokumentasjon)

For å hente aggregert mengdeinformasjon for alle støttede nodetyper i Excel-format:

GET https://api.ren.no/public/calculation/rest/reports/quantity/by-projectid/{projectId}/excel (API-dokumentasjon)

Fordeling av kostnader

For å hente kostnadsfordeling for alle støttede fordelingstyper i JSON-format:

GET https://api.ren.no/public/calculation/rest/reports/distribution/by-projectid/{projectId}/json (API-dokumentasjon)

For å hente kostnadsfordeling for en spesifikk fordelingstype i JSON-format:

GET https://api.ren.no/public/calculation/rest/reports/distribution/by-projectid/{projectId}/by-type/{type}/json (API-dokumentasjon)

Samsvarserklæring

For å hente samsvarserklæring (liste av RENblader) i PDF-format:

GET https://api.ren.no/public/calculation/rest/reports/conformitydeclaration/by-projectid/{projectId}/pdf (API-dokumentasjon)

Prosjektrapport

For å hente prosjektrapport (oppsummering av prosjekt og kalkyle) i PDF-format:

GET https://api.ren.no/public/calculation/rest/reports/summary/by-projectid/{projectId}/pdf (API-dokumentasjon)

API-dokumentasjon

Dokumentasjonen over endepunktene og datastrukturene er generert og skrevet på engelsk. Du kan lese den samt prøve ut endepunktene i REN sin API Browser. Den dokumentasjonen er live-generert og gjenspeiler den versjon som faktisk kjører. Alternativt kan du fortsette å lese en statisk generert versjon her.

Gå til API Browser

Resources

Activity

List all activities
GET /activities
Responses
HTTP Code Description Schema

200

successful operation

< Activity > array
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

oauth2

oauth2-client

prosjektsystem.bruker
Get an activity by ID
GET /activities/{activityId}
Parameters
Type Name Schema

Path

activityId
required

integer (int64)
Responses
HTTP Code Description Schema

200

successful operation

Activity
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

oauth2

oauth2-client

prosjektsystem.bruker

Calculation Module

Get the calculation module for a project
GET /modules/{projectId}
Parameters
Type Name Description Schema

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)
Responses
HTTP Code Description Schema

200

successful operation

CalculationModule
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Change calculation type for project
PUT /modules/{projectId}/calculationtype/{calculationType}
Parameters
Type Name Description Schema

Path

calculationType
required

Determines if costs and prices should follow RENs average price lists or the companies own price lists.

enum (REN, COMPANY)

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)
Responses
HTTP Code Description Schema

default

successful operation

No Content
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker

Calculation Node

List top level calculation nodes for a project
GET /calculationnodes/by-projectid/{projectId}
Parameters
Type Name Description Schema Default

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)

Query

depth
optional

Determines the max tree depth to be returned, counting from the root. Thus, 0 would imply no nodes returned and 1 that only the top level nodes are returned.

integer (int64)

1
Responses
HTTP Code Description Schema

200

successful operation

< CalculationNode > array
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Add a top level budget node to a project
PUT /calculationnodes/by-projectid/{projectId}
Parameters
Type Name Description Schema Default

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)

Query

options
optional

Specifies whether 'options' (child nodes with quantity 0) should be included or not.

boolean

"true"

Body

body
required

CatalogNodeAdd
Responses
HTTP Code Description Schema

200

successful operation

CalculationNode
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Delete all calculation nodes in a project
DELETE /calculationnodes/by-projectid/{projectId}
Description

Delete all calculation nodes. Can e.g. be used as a quick and dirty way to clear all content before re-adding updated structures.

Parameters
Type Name Description Schema

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)
Responses
HTTP Code Description Schema

default

successful operation

No Content
Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Add a top level custom budget node to a project
PUT /calculationnodes/custom/by-projectid/{projectId}
Description

Add a top level custom budget node. Only node types CUSTOMBUDGET_FIXEDTOTAL and CUSTOMBUDGET_FIXEDUNIT can be added with this endpoint.

Parameters
Type Name Description Schema

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)

Body

body
required

CatalogCustomNodeAdd
Responses
HTTP Code Description Schema

200

successful operation

CalculationNode
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Update the properties of a custom budget node
POST /calculationnodes/custom/{nodeId}
Parameters
Type Name Description Schema

Path

nodeId
required

An ID that identifies the node.

string

Body

body
required

CatalogCustomNodeAdd
Responses
HTTP Code Description Schema

default

successful operation

No Content
Consumes

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Get a single calculation node by ID
GET /calculationnodes/{nodeId}
Parameters
Type Name Description Schema Default

Path

nodeId
required

An ID that identifies the node.

string

Query

depth
optional

Determines the maximum child depth to be returned.

integer (int64)

0
Responses
HTTP Code Description Schema

200

successful operation

CalculationNode
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Delete a calculation node
DELETE /calculationnodes/{nodeId}
Parameters
Type Name Description Schema Default

Path

nodeId
required

An ID that identifies the node.

string

Query

deleteChildren
optional

boolean

"false"
Responses
HTTP Code Description Schema

default

successful operation

No Content
Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker

Catalog Node

Get catalog nodes by type
GET /catalognodes/by-revision/{revision}/by-type/{type}
Description

This endpoint will return flat catalog nodes (without children).

Parameters
Type Name Description Schema Default

Path

revision
required

The catalog revision ID, or latest to always select the latest active revision.

string

Path

type
required

The node type. See CatalogNodeType for details.

enum (BUDGET, GROUP, WORK, MATERIALGROUP, MATERIAL, OTHER, RESOURCE)

Query

useCompanyPrices
optional

Enables using the company’s own price lists. For material where the company does not have own prices, REN prices are used. Requires user/password credentials grant.

boolean

"false"
Responses
HTTP Code Description Schema

200

successful operation

< CatalogNode > array
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker

oauth2

oauth2-client

calculation.bruker
Get a catalog node by type and REN number
GET /catalognodes/by-revision/{revision}/by-type/{type}/by-number/{number}
Description

This endpoint will return catalog nodes with full depth children.

Parameters
Type Name Description Schema Default

Path

number
required

The REN number of the node.

string

Path

revision
required

The catalog revision ID, or latest to always select the latest active revision.

string

Path

type
required

The node type. See CatalogNodeType for details.

enum (BUDGET, GROUP, WORK, MATERIALGROUP, MATERIAL, OTHER, RESOURCE)

Query

quantity
optional

Enables overriding the default quantity of 1, as well as providing the correct contextual quantity when lazy-loading nodes deeper down in a hierarchy.

number (double)

1.0

Query

useCompanyPrices
optional

Enables using the company’s own price lists. For material where the company does not have own prices, REN prices are used. Requires user/password credentials grant.

boolean

"false"
Responses
HTTP Code Description Schema

200

successful operation

CatalogNode
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker

oauth2

oauth2-client

calculation.bruker
Search for catalog nodes
GET /catalognodes/by-revision/{revision}/page
Description

Search for catalog nodes, or get all (or filtered) catalog nodes. This endpoint supports pagination, and will return flat catalog nodes (without children).

Parameters
Type Name Description Schema Default

Path

revision
required

The catalog revision ID, or latest to always select the latest active revision.

string

Query

activityId
optional

Filter by activity.

< integer (int64) > array(multi)

Query

count
optional

The page size / maximum number of nodes to return.

integer (int32)

10

Query

facilityId
optional

Filter by facility.

< integer (int64) > array(multi)

Query

favorite
optional

Filter by favorite.

< string > array(multi)

Query

first
optional

Optional offset when using pagination.

integer (int32)

Query

number
optional

Filter by for REN number.

< string > array(multi)

Query

q
optional

Optional query string, composed of one or multiple search words.

string

Query

sort
optional

Optional sorting instructions. The syntax is [-]<property>, where <property> is the name of a catalog node property, and the optional minus implies descending order. See CatalogNode for available properties.

< string > array(multi)

Query

type
optional

Filter by node type. See CatalogNodeType for details.

< enum (BUDGET, GROUP, WORK, MATERIALGROUP, MATERIAL, OTHER, RESOURCE) > array(multi)

Query

unit
optional

Filter by unit.

< string > array(multi)
Responses
HTTP Code Description Schema

200

successful operation

PaginatedCatalogNode
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker

oauth2

oauth2-client

calculation.bruker
Get property summaries
GET /catalognodes/by-revision/{revision}/summary
Description

Get property summaries for all (or filtered) catalog nodes. This endpoint provides aggregated information that is useful when searching for catalog nodes.

Parameters
Type Name Description Schema

Path

revision
required

The catalog revision ID, or latest to always select the active revision.

string

Query

activityId
optional

Filter by activity.

< integer (int64) > array(multi)

Query

facilityId
optional

Filter by facility.

< integer (int64) > array(multi)

Query

favorite
optional

Filter by favorite.

< string > array(multi)

Query

number
optional

Filter by for REN number.

< string > array(multi)

Query

q
optional

Optional query string, composed of one or multiple search words.

string

Query

type
optional

Filter by node type. See CatalogNodeType for details.

< enum (BUDGET, GROUP, WORK, MATERIALGROUP, MATERIAL, OTHER, RESOURCE) > array(multi)

Query

unit
optional

Filter by unit.

< string > array(multi)
Responses
HTTP Code Description Schema

200

successful operation

MultiPropertySummary
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker

oauth2

oauth2-client

calculation.bruker

Facility

List all facilities
GET /facilities
Responses
HTTP Code Description Schema

200

successful operation

< Facility > array
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

oauth2

oauth2-client

prosjektsystem.bruker
Get a facility by ID
GET /facilities/{facilityId}
Parameters
Type Name Schema

Path

facilityId
required

integer (int64)
Responses
HTTP Code Description Schema

200

successful operation

Facility
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

oauth2

oauth2-client

prosjektsystem.bruker

Report

Get a company report summarizing costs per user for a period, in PDF format
GET /reports/company/by-companyid/{companyId}
Description

The company report (norsk: selskapsrapport) is a PDF report summarizing costs per user for a period.

Parameters
Type Name Description Schema Default

Path

companyId
required

A numeric ID that identifies the company.

integer (int64)

Query

fromDate
optional

A string value representing the start of the reporting period. Format DD.MM.YYYY

string

Query

showUserProjects
optional

A boolean if each users projects should be listed explicitly.

boolean

"false"

Query

toDate
optional

A string value representing the end of the reporting period. Format DD.MM.YYYY

string

Query

user
optional

A string value identifying the user. Optional, if omitted all users in the company is included in the report.

string
Responses
HTTP Code Description Schema

default

successful operation

No Content
Produces

  • application/pdf

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Get a conformity declaration report, in PDF format
GET /reports/conformitydeclaration/by-projectid/{projectId}/pdf
Description

The conformity declaration (norsk: samsvarserklæring) is a report listing all RENblads connected to the project.

Parameters
Type Name Description Schema

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)
Responses
HTTP Code Description Schema

default

successful operation

No Content
Produces

  • application/pdf

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Get simple cost distributions by type
GET /reports/distribution/by-projectid/{projectId}/by-type/{type}/json
Description

The endpoint lists a simple cost distribution for a project and a given distribution type.

Parameters
Type Name Description Schema

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)

Path

type
required

The report type for this report. See DistributionReportType for details.

enum (FACILITY, ACTIVITY, COSTTYPE)
Responses
HTTP Code Description Schema

200

successful operation

< ReportDistribution > array
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Get simple cost distributions
GET /reports/distribution/by-projectid/{projectId}/json
Description

The endpoint lists simple cost distributions for a project.

Parameters
Type Name Description Schema

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)
Responses
HTTP Code Description Schema

200

successful operation

< string, < ReportDistribution > array > map
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Get a project description report, in PDF format
GET /reports/projectdescription/by-projectid/{projectId}
Description

The description report (norsk: tiltaksbeskrivelse) is a PDF report listing descriptions for project.

Parameters
Type Name Description Schema Default

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)

Query

custom
optional

Option for including custom (fixed price) nodes.

boolean

"true"

Query

groupByGroups
optional

Option for grouping the report by groups.

boolean

"false"

Query

options
optional

Option for including optional nodes (with quantity 0) in the report.

boolean

"false"
Responses
HTTP Code Description Schema

default

successful operation

No Content
Produces

  • application/pdf

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Get quantities aggregated by REN number, for a cost type
GET /reports/quantity/by-projectid/{projectId}/by-type/{type}/json
Description

This endpoint lists aggregated quantities for all work / material / … (see QuantityReportType) in a project.

Parameters
Type Name Description Schema Default

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)

Path

type
required

The report type. See QuantityReportType for details.

enum (WORK, MATERIAL, RESOURCE, OTHER)

Query

custom
optional

Option for including custom (fixed price) nodes.

boolean

"true"

Query

groupByGroups
optional

Option for grouping the report by groups.

boolean

"false"

Query

groupByLocation
optional

Option for grouping the report by location name.

boolean

"false"

Query

groupLocation
optional

(Deprecated) Option for grouping the report by location name.

boolean

Query

options
optional

Option for including optional nodes (with quantity 0) in the report.

boolean

"false"
Responses
HTTP Code Description Schema

200

successful operation

< ReportQuantity > array
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Get quantities aggregated by REN number, for a cost type, in PDF format
GET /reports/quantity/by-projectid/{projectId}/by-type/{type}/pdf
Description

The aggregated quantities report (norsk: mengderapport) is a report listing all work / material / … (see QuantityReportType) in a project, along with aggregated quantities for each entry.

Parameters
Type Name Description Schema Default

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)

Path

type
required

The report type. See QuantityReportType for details.

enum (WORK, MATERIAL, RESOURCE, OTHER)

Query

custom
optional

Option for including custom (fixed price) nodes.

boolean

"true"

Query

groupByGroups
optional

Option for grouping the report by groups.

boolean

"false"

Query

groupByLocation
optional

Option for grouping the report by location name.

boolean

"false"

Query

groupLocation
optional

(Deprecated) Option for grouping the report by location name.

boolean

Query

options
optional

Option for including optional nodes (with quantity 0) in the report.

boolean

"false"

Query

price
optional

Option for including prices in the report.

boolean

"true"

Query

renblad
optional

Option for including RENblad references in the report.

boolean

"false"
Responses
HTTP Code Description Schema

default

successful operation

No Content
Produces

  • application/pdf

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Get quantities aggregated by REN number, in Excel format
GET /reports/quantity/by-projectid/{projectId}/excel
Description

The aggregated quantities report (norsk: mengderapport) is a report listing all work / material / … (see QuantityReportType) in a project, along with aggregated quantities for each entry. Costs for each type are listed in separate Excel sheets.

Parameters
Type Name Description Schema Default

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)

Query

custom
optional

Option for including custom (fixed price) nodes.

boolean

"true"

Query

description
optional

Option for including description in the report.

boolean

"false"

Query

groupByGroups
optional

Option for grouping the report by groups.

boolean

"false"

Query

groupByLocation
optional

Option for grouping the report by location name.

boolean

"false"

Query

groupLocation
optional

(Deprecated) Option for grouping the report by location name.

boolean

Query

options
optional

Option for including optional nodes (with quantity 0) in the report.

boolean

"false"

Query

renblad
optional

Option for including RENblad references in the report.

boolean

"false"
Responses
HTTP Code Description Schema

default

successful operation

No Content
Produces

  • application/vnd.ms-excel

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Get quantities aggregated by REN number
GET /reports/quantity/by-projectid/{projectId}/json
Description

The aggregated quantities report (norsk: mengderapport) is a report listing all work / material / … (see QuantityReportType) in a project, along with aggregated quantities for each entry.

Parameters
Type Name Description Schema Default

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)

Query

custom
optional

Option for including custom (fixed price) nodes.

boolean

"true"

Query

groupByGroups
optional

Option for grouping the report by groups.

boolean

"false"

Query

groupByLocation
optional

Option for grouping the report by location name.

boolean

"false"

Query

groupLocation
optional

(Deprecated) Option for grouping the report by location name.

boolean

Query

options
optional

Option for including optional nodes (with quantity 0) in the report.

boolean

"false"
Responses
HTTP Code Description Schema

200

successful operation

< string, < ReportQuantity > array > map
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker
Get a project summary report, in PDF format
GET /reports/summary/by-projectid/{projectId}/pdf
Description

The project summary (norsk: prosjektrapport) is a PDF report listing costs for the project, aggregated by cost type, facility and activity.

Parameters
Type Name Description Schema

Path

projectId
required

A numeric ID that identifies the project.

integer (int64)
Responses
HTTP Code Description Schema

default

successful operation

No Content
Produces

  • application/pdf

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker

Revision

List all catalog revisions
GET /revisions
Responses
HTTP Code Description Schema

200

successful operation

< Revision > array
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker

oauth2

oauth2-client

calculation.bruker
Get the latest catalog revision
GET /revisions/latest
Description

At a given time, there will be multiple active revisions. This endpoint will return the latest of those. New projects will automatically use the latest revision, and endpoints that take the revision as parameter will usually accept latest as a synonym for the latest revision at that time.

Responses
HTTP Code Description Schema

200

successful operation

Revision
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker

oauth2

oauth2-client

calculation.bruker
Get a catalog revision by ID
GET /revisions/{revisionId}
Parameters
Type Name Schema

Path

revisionId
required

integer (int64)
Responses
HTTP Code Description Schema

200

successful operation

Revision
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

calculation.bruker

oauth2

oauth2-client

calculation.bruker

Unit

List all units
GET /units
Description

These are all the units that the calculation module supports. Whenever a unit is specified (e.g. when adding a custom calculation node or when searching for catalog nodes), that unit must be one of the units listed here, and must be written in exactly the same manner.

Responses
HTTP Code Description Schema

200

successful operation

< string > array
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

prosjektsystem.bruker

oauth2

oauth2-client

prosjektsystem.bruker

Definitions

Activity

Models an activity (norsk: aktivitet) in cost calculation terms.

Name Description Schema

id
required

A unique numeric identifier.

integer (int64)

name
required

The activity name.

string

CalculationModule

An extension to the general Module type in the Project API. Contains configuration and information about the calculation module within a project.

Name Description Schema

calculationType
required

Determines if costs and prices should follow RENs average price lists or the companies own price lists.

CalculationType

projectId
required

The numeric project identifier, that also identifies the calculation module.

integer (int64)

readOnly
required

Specifies if this calculation module is in read-only state or not.

boolean

revisionId
required

The numeric revision identifier.

integer (int64)

revisionName
required

The revision name.

string

CalculationNode

Models a node in a calculation tree. The top level nodes are always 'budget' nodes, and beneath these there are e.g. material, work and resource nodes. Each node holds some static information plus at least a quantity and a cost. Nodes may also have child nodes.

Name Description Schema

activityId
optional

The activity ID for this node. Supported activities can be queried via the Activity resource. Only applicable to top level budget nodes.

integer (int64)

childNodes
optional

The child nodes, if any. An undefined value does not necessarily imply that this node does not have children. Property hasChildren should be consulted to determine that.

< CalculationNode > array

description
optional

An optional description.

string

facilityId
optional

The facility ID for this node. Supported facilities can be queried via the Facility resource. Only applicable to top level budget nodes.

integer (int64)

hasChildren
required

Reveals if this node has child nodes. If this property has value true, then this node indeed has child nodes, regardless of the value of property childNodes. If childNodes is undefined, then child nodes can be fetched by re-fetching this node with depth greater than 1.

boolean

id
required

A unique string identifier.

string

locationName
optional

An optional location name, primarily used to tag where this node physically belongs.

string

name
required

The name of this calculation node.

string

number
required

The REN number for the catalog node that this calculation node is based on.

string

parentId
optional

The ID of the parent node, if any.

string

quantity
required

The quantity, i.e. how 'much' there should be of this node.

number (double)

totalCost
required

The total cost of this node, considering unit cost and quantity.

number (double)

totalCostRounded
required

The total cost of this node, rounded to integer.

integer (int64)

type
required

The type of calculation node.

CalculationNodeType

unit
required

The unit of this node.

string

unitCost
required

The cost of quantity 1 of this node.

number (double)

CalculationNodeType

Models the type of nodes in a calculation tree. Valid values are:

  • BUDGETGROUP (norsk: Gruppe)

  • BUDGET (norsk: Budsjettkode)

  • CUSTOMBUDGET_FIXEDUNIT (norsk: Fastpris, fast enhetspris)

  • CUSTOMBUDGET_FIXEDTOTAL (norsk: Fastpris, fast totalsum)

  • GROUP (norsk: Pakke)

  • WORK (norsk: Arbeid)

  • MATERIALGROUP (norsk: Materiellpakke)

  • MATERIAL (norsk: Materiellenhet)

  • OTHER (norsk: Annen kost)

  • RESOURCE (norsk: Ressurs)

Type : enum (BUDGETGROUP, BUDGET, CUSTOMBUDGET_FIXEDUNIT, CUSTOMBUDGET_FIXEDTOTAL, GROUP, WORK, MATERIALGROUP, MATERIAL, OTHER, RESOURCE)

CalculationType

Models the budgeting type of a calculation tree. Determines how costs in the project are calculated. Valid values are:

  • REN (norsk: REN kalkyle) implies that standardized 'average' costs will be used.

  • COMPANY (norsk: Selskapskalkyle) implies that the owning company’s own price lists will be used, where applicable. Requires that the owning company actually has up-to-date price lists.

Type : enum (REN, COMPANY)

CatalogCustomNodeAdd

An input-only structure used when adding (or updating) custom nodes to a calculation tree.

Name Description Schema

activityId
required

The activity ID for this node. Supported activities can be queried via the Activity resource.

integer (int64)

description
optional

Optional description for the node.

string

facilityId
required

The facility ID for this node. Supported facilities can be queried via the Facility resource.

integer (int64)

locationName
optional

The optional location name of this node.

string

name
required

A name identifying the node.

string

quantity
required

The quantity of this node.

number (double)

totalCost
optional

The total cost. When the type is CUSTOMBUDGET_FIXEDTOTAL, the total cost is required.

number (double)

type
required

The type of the added node. Only types CUSTOMBUDGET_FIXEDTOTAL and CUSTOMBUDGET_FIXEDUNIT are allowed.

CalculationNodeType

unit
required

The unit for this node. Supported units can be listed via the Unit resource.

string

unitCost
optional

The cost per unit. When the type is CUSTOMBUDGET_FIXEDUNIT, the unit cost is required.

number (double)

CatalogNode

Models a node in a catalog tree. The top level nodes are always 'budget' nodes, and beneath these there are e.g. material, work and resource nodes. These nodes may also have child nodes.

Name Description Schema

activityId
optional

The activity ID for this node. Supported activities can be queried via the Activity resource. Only applicable to top level budget nodes.

integer (int64)

activityName
optional

The activity name for this node. Only applicable to top level budget nodes.

string

baseQuantity
optional

Since catalog nodes can be reused as children under multiple other catalog nodes, the quantity will vary depending on the parent catalog node. Therefore, they have a 'base' quantity, which is related to one unit of its immediate parent. The actual quantity, will then be this 'base' quantity multiplied by the actual parent quantity (which again will depend on the parent’s parent).

number (double)

childNodes
optional

The child nodes, if any. An undefined value does not necessarily imply that this node does not have children. Property hasChildren should be consulted to determine that.

< CatalogNode > array

description
optional

An optional description for this node.

string

facilityId
optional

The facility ID for this node. Supported facilities can be queried via the Facility resource. Only applicable to top level budget nodes.

integer (int64)

facilityName
optional

The facility name for this node. Only applicable to top level budget nodes.

string

hasChildren
required

Reveals if this node has child nodes. If this property has value true, then this node indeed has child nodes, regardless of the value of property childNodes. If childNodes is undefined, then child nodes can be fetched by re-fetching this node with an endpoint that includes child nodes.

boolean

name
required

The name of this node.

string

number
required

The REN number for this node.

string

quantity
optional

The quantity, i.e. how 'much' of this node there is, in the given context.

number (double)

totalCost
required

The total cost of this node, considering unit cost and quantity.

number (double)

totalCostRounded
required

The total cost of this node, rounded to integer.

integer (int64)

type
required

The node type.

CatalogNodeType

unit
required

The unit for this node.

string

unitCost
required

The cost of quantity 1 of this node.

number (double)

CatalogNodeAdd

An input-only structure used when adding catalog nodes to a calculation tree. At a minimum, the top level node must be defined. In addition, the default tree hierarchy under that node can be altered by specifying child nodes. For each child node, the quantity or location name can be changed, or an instruction to exclude that node (and its whole branch) can be given. Use the Catalog Node resource to search for budget nodes that can be added.

Name Description Schema

childNodes
optional

Optional child nodes. Only needs to be defined in case the default child nodes need to be altered.

< CatalogNodeAdd > array

exclude
optional

Can be used to exclude child nodes and whole branches under the added catalog node. Set to true on a child node, to remove that child node.

boolean

locationName
optional

The optional location name of this node.

string

number
required

The REN number pinpointing the catalog node (together with the type). Can be found by browsing the Catalog Node resource.

string

quantity
optional

The quantity of this node. Required for the top level node, and can optionally be specified also for child nodes, to override their quantity.

number (double)

type
optional

The type of the catalog node. Optional as long as the number is unique.

CatalogNodeType

CatalogNodeType

Models the type of nodes in a catalog tree. Valid values are:

  • BUDGET (norsk: Budsjettkode)

  • GROUP (norsk: Pakke)

  • WORK (norsk: Arbeid)

  • MATERIALGROUP (norsk: Materiellpakke)

  • MATERIAL (norsk: Materiellenhet)

  • OTHER (norsk: Annen kost)

  • RESOURCE (norsk: Ressurs)

Type : enum (BUDGET, GROUP, WORK, MATERIALGROUP, MATERIAL, OTHER, RESOURCE)

Comparable

Type : object

DistributionReportType

Models the type of distribution report. Valid values are:

  • FACILITY (norsk: Anlegg)

  • ACTIVITY (norsk: Aktivitet)

  • COSTTYPE (norsk: Kostnadstype)

Type : enum (FACILITY, ACTIVITY, COSTTYPE)

Facility

Models a facility (norsk: anlegg) in the network.

Name Description Schema

id
required

A unique numeric identifier.

integer (int64)

longName
required

The facility name, possibly in a longer format.

string

name
required

The facility name, possibly in an abbreviated format.

string

MultiPropertySummary

Name Schema

counter
optional

QuantityCounter

propertySummaries
optional

< string, PropertySummary > map

staticCounter
optional

QuantityCounter

Paginated

Name Schema

count
optional
read-only

integer (int32)

entities
optional

< object > array

first
optional

integer (int32)

total
optional

integer (int32)

PaginatedCatalogNode

Name Schema

count
optional
read-only

integer (int32)

entities
optional

< CatalogNode > array

first
optional

integer (int32)

total
optional

integer (int32)

PropertySummary

Name Schema

displayName
optional

string

name
optional

string

op
optional

enum (OR, AND)

range
optional

RangeObject

valueSummaries
optional

< PropertyValueSummary > array

PropertyValueSummary

Name Schema

counter
optional

QuantityCounter

displayValue
optional

string

value
optional

object

QuantityCounter

Name Schema

count
optional

integer (int64)

quantity
optional

integer (int64)

QuantityReportType

Models the type of quantity reports (norsk: mengderapport). Valid values are:

  • WORK (norsk: Mengderapport arbeid)

  • MATERIAL (norsk: Mengderapport materiell)

  • RESOURCE (norsk: Mengderapport ressurser)

  • OTHER (norsk: Mengderapport andre kostnader)

Type : enum (WORK, MATERIAL, RESOURCE, OTHER)

Range

Name Schema

displayName
optional

string

from
optional

Comparable

to
optional

Comparable

RangeObject

Name Schema

displayName
optional

string

from
optional

object

to
optional

object

ReportDistribution

A structure for entries in distribution reports.

Name Description Schema

cost
required

The cost / price of this entry.

number (double)

percentage
required

The percentage of how this entry weights in relation to other entries.

number (double)

type
required

The type of distribution.

string

ReportQuantity

A structure for entries in quantity reports.

Name Description Schema

combinedGroupName
optional

The grouping of this entry, as a concatenation of the parent group names.

string

description
optional

An optional description of this entry.

string

id
required

A unique string identifier.

string

locationName
optional

The location name of this entry.

string

name
required

The name of this entry.

string

totalCost
required

The total cost of this entry.

number (double)

totalQuantity
required

The total quantity of this entry.

number (double)

unit
required

The unit of this entry.

string

unitCost
required

The unit cost of this entry.

number (double)

Revision

Information about a catalog revision. At any given time, one single revision will be the latest (active) revision. Older projects might use older revisions, but newly created projects will always be configured to use the latest (active) revision.

Name Description Schema

active
required

Reveals if this revision is active and available for use.

boolean

activeFromDate
optional

string (date-time)

activeToDate
optional

string (date-time)

createdDate
optional

string (date-time)

description
optional

An optional description.

string

id
required

A unique numeric identifier.

integer (int64)

modifiedDate
optional

string (date-time)

name
required

The revision name.

string

Security

oauth2-password

A flow where an end user is required. Endpoints using this flow can provide personal customization and access to personal information.

Type : oauth2
Flow : password
Token URL : https://www.ren.no/auth/realms/www.ren.no/protocol/openid-connect/token

Name Description

calculation.bruker

Implies that role 'calculation.bruker' is required.

prosjektsystem.bruker

Implies that role 'prosjektsystem.bruker' is required.

oauth2-client

A flow where an end user is not involved. Endpoints using this flow will support full automation without any human intervention, but on the other hand cannot provide personal customization or access to personal information.

Type : oauth2
Flow : application
Token URL : https://www.ren.no/auth/realms/www.ren.no/protocol/openid-connect/token

Name Description

calculation.bruker

Implies that role 'calculation.bruker' is required.

prosjektsystem.bruker

Implies that role 'prosjektsystem.bruker' is required.