TABLE OF CONTENTS
- Properties of a registration object
- Value
- List
- Repeatable
- Numeric
- Text
- Bool
- Date
- Dropdown
- File
- Get registrations
A registration is the data that a reporter has submitted given the structure of a measure. Given the customizable properties of a measure, the registration contains a graph of answers for the values corresponding to the questions in a measure.
Swagger UI
Below you will find the documentation details for Registrations. To test the endpoint, please go to our Swagger UI page.
Properties of a registration object
| Property | Data Type | Description |
| id | Guid | Id of the registration. |
organizationUnit | string | The organization unit the data belongs to. |
| measureName | string | Name of the measure |
responsibleUser | string | The reporter responsible for reporting the data |
confirmedAt | DateTime? | If the registration is confirmed it contains the timestamp |
| period | string | The period type |
| periodStart | string | Start date of the period |
| periodEnd | string | End date of the period |
| data | object | The data representation. Data structure. |
The period property contains a code and a number. For example "M4": M for month and 4 for April. It is a way of identifying the periodicity if needed. If the measure is configured to be year-to-date, the start date is always the year's start date.
The registration data is a graph object containing the values. The graph's structure is defined by how the measure is set up. It is up to the Controller to configure the measure for the reporter to fill in.
The root object in the data property is always a ListValue, a collection of values.
Value
The base of all value types, contains general information available in all value types.
| Property | Description |
| id | Id of the data. This is unique within each registration. |
| name | System name; it can be set in the measure builder to identify the control. |
| label | The display name shown to the reporter. |
type | The type of the value. Used as a discriminator. |
tags | A list of tags. They can be set in Measure Builder and is the recommended way of identifying a control. |
To identify a subtype of Value the property type is used. All common properties are omitted in the descriptions of each value below.
List
A collection of values. The root object in data is always a list. It can contain other lists. The id and name of a list is always null.
| Property | Description |
| Value | Array of values |
Example
Example of a list with two values.
{
"value": [
{
"type": "numeric",
"value": 4,
"unit": "Trips",
"id": "measure_1",
"name": "measure_1",
"label": "Number of flights",
"tags": []
},
{
"type": "numeric",
"value": 2000,
"unit": "km",
"id": "measure_2",
"name": "measure_2",
"label": "Distance by airplane 2",
"tags": []
}
],
"type": "list"
}Repeatable
A repeatable control in a measure allows the reporter to add and remove rows in Position Green when reporting data. Every row in the repeatable is represented as a list in the data structure.
Property | Description |
| Value | Array of rows |
Example
An example of a registration where the measure contains a repeatable that allows for the reporter to add one or more rows and indicate a source and energy used.
Every row in the repeatable is assigned a unique id but the name of each control will still be the same.
The response looks like this.
{
"value": [
{
"type": "repeatable",
"value": [
{
"value": [
{
"type": "dropdown",
"value": [
{
"name": "Wind"
}
],
"id": "measure_fc2t!!repeatable_q3gn!!15862358690400",
"name": "measure_fc2t",
"label": "Source",
"tags": []
},
{
"type": "numeric",
"value": 65000,
"unit": "kWh",
"id": "measure_dnkl!!repeatable_q3gn!!15862358690400",
"name": "measure_dnkl",
"label": "Energy used",
"tags": []
}
],
"type": "list"
},
{
"value": [
{
"type": "dropdown",
"value": [
{
"name": "Solar"
}
],
"id": "measure_fc2t!!repeatable_q3gn!!15862359182380",
"name": "measure_fc2t",
"label": "Source",
"tags": []
},
{
"type": "numeric",
"value": 250000,
"unit": "kWh",
"id": "measure_dnkl!!repeatable_q3gn!!15862359182380",
"name": "measure_dnkl",
"label": "Energy used",
"tags": []
}
],
"type": "list"
},
{
"value": [
{
"type": "dropdown",
"value": [
{
"name": "Nuclear"
}
],
"id": "measure_fc2t!!repeatable_q3gn!!15862359243871",
"name": "measure_fc2t",
"label": "Source",
"tags": []
},
{
"type": "numeric",
"value": 3000000,
"unit": "kWh",
"id": "measure_dnkl!!repeatable_q3gn!!15862359243871",
"name": "measure_dnkl",
"label": "Energy used",
"tags": []
}
],
"type": "list"
}
],
"id": "repeatable_q3gn",
"name": "repeatable_q3gn"
}
],
"type": "list"
}Numeric
Contains a numeric value and a unit.
| Property | Description |
value | Decimal value |
| unit | The unit of the value |
Example
The value is 9000 and the unit is in kilometers.
{
"type": "numeric",
"value": 9000,
"unit": "km",
"id": "measure_2_copy1",
"name": "measure_2_copy1",
"label": "Distance by train",
"tags": []
}Text
Text value where the reporter fills in a qualitative answer.
| Property | Description |
| value | Text value |
{
"type": "text",
"id": "info",
"name": "info",
"label": "Additional info",
"tags": [],
"value": "Qualitative text response"
}Bool
A bool value where the reporter has chosen between Yes and No when filling in the answers.
| Property | Description |
| value | Boolean value |
Example
{
"type": "bool",
"id": "renewable",
"name": "renewable",
"label": "Is the source renewable?",
"tags": [],
"value": true
}Date
A value that contains a date in ISO 8601, yyyy-mm-dd format.
| Property | Description |
| value | Date in ISO 8601 yyyy-mm-dd format |
Example
{
"type": "date",
"value": "2020-01-24",
"id": "registration_date",
"name": "registration_date",
"label": "Date",
"tags": []
}Dropdown
A dropdown value which contains one or many selected options by a reporter.
| Property | Description |
| Value | An array of SelectedOption |
The dropdown has a configuration setting that indicated if the reporter is allowed to select many values. The dropdown value is always an array in the data structure.
The SelectedOption contains a name and an optional value.
Example
Here is an example of three different values from dropdowns.
- The value contains a JSON encoded string
- The value contains a simple value
- There is no value associated with the selected option
{
"type": "repeatable",
"value": [
{
"value": [
{
"type": "dropdown",
"value": [
{
"name": "Wind",
"value": "{\"renewable\":true}"
}
],
"id": "measure_fc2t!!repeatable_q3gn!!15862358690400",
"name": "measure_fc2t",
"label": "Source",
"tags": []
},
{
"type": "numeric",
"value": 65000,
"unit": "kWh",
"id": "measure_dnkl!!repeatable_q3gn!!15862358690400",
"name": "measure_dnkl",
"label": "Energy used",
"tags": []
}
],
"type": "list"
},
{
"value": [
{
"type": "dropdown",
"value": [
{
"name": "Solar",
"value": "100"
}
],
"id": "measure_fc2t!!repeatable_q3gn!!15862359182380",
"name": "measure_fc2t",
"label": "Source",
"tags": []
},
{
"type": "numeric",
"value": 250000,
"unit": "kWh",
"id": "measure_dnkl!!repeatable_q3gn!!15862359182380",
"name": "measure_dnkl",
"label": "Energy used",
"tags": []
}
],
"type": "list"
},
{
"value": [
{
"type": "dropdown",
"value": [
{
"name": "Nuclear"
}
],
"id": "measure_fc2t!!repeatable_q3gn!!15862359243871",
"name": "measure_fc2t",
"label": "Source",
"tags": []
},
{
"type": "numeric",
"value": 3000000,
"unit": "kWh",
"id": "measure_dnkl!!repeatable_q3gn!!15862359243871",
"name": "measure_dnkl",
"label": "Energy used",
"tags": []
}
],
"type": "list"
}
],
"id": "repeatable_q3gn",
"name": "repeatable_q3gn"
}File
A value that represents uploaded files by the reporter. The reporter can upload one or many files. They contain a name and a link. The name is the file name and the link is an URL path to download the attachment.
Property | Description |
| Value | An array of files (name and link) |
Example
{
"type": "file",
"value": [
{
"name": "Invoice ACME.pdf",
"link": "/attachment/get/3ef994e5-81ee-4958-bb99-3812be0d305a"
},
{
"name": "Invoice FOO.xlsx",
"link": "/attachment/get/ba602707-0055-48b2-b6ed-879eabfa217b"
}
],
"id": "measure_gtby",
"name": "measure_gtby",
"label": "Upload source materials",
"tags": []
}Get registrations
GET https://api.positiongreen.com/v1/registrations
Returns registrations
Query Parameters
| Name | Type | Description |
|---|---|---|
| yearId* | string | Id of the year (Guid) |
| measureIds | array | Measure ids (Guid) |
| orgUnitIds | array | Organization Unit ids (Guid) |
| orgUnitIds | array | Organization Unit ids (Guid) |
| includeChildren | bool | Indicates whether to include children of the provided organization units in the response. (Default = false) |
| measurePrettyIds | array | Pretty ids of measures (string) |
| startDate | string | Start date to get registrations for (yyyy-mm-dd) |
endDate | string | End date to get registrations for (yyyy-mm-dd) |
| first | number | Number of registrations to return. Default = 10. Minimum 1 and Maximum 100. |
| after | string | Cursor to where to continue getting registrations from |
| sortBy | string | 'Period' |
| sortDirection | string | 'Ascending', 'Descending' |
{
"totalCount": 178,
"pageInfo": {
"hasNextPage": true,
"startCursor": "cGFnZTsw",
"endCursor": "cGFnZTs5"
},
"items": [
{
"cursor": "cGFnZTs0MTQ=",
"node": {
"id": "715117fd-a8c5-4cf7-9a4b-8cc7aafee0f4",
"organizationUnit": "Björn Johansson",
"measureName": "Report energy usage",
"responsibleUser": "Björn Johansson",
"data": {
"value": [
{
"type": "repeatable",
"value": [
{
"value": [
{
"type": "dropdown",
"value": [
{
"name": "Wind",
"value": "{\"renewable\":true}"
}
],
"id": "measure_fc2t!!repeatable_q3gn!!15862358690400",
"name": "measure_fc2t",
"label": "Source",
"tags": []
},
{
"type": "numeric",
"value": 65000,
"unit": "kWh",
"id": "measure_dnkl!!repeatable_q3gn!!15862358690400",
"name": "measure_dnkl",
"label": "Energy used",
"tags": []
}
],
"type": "list"
},
{
"value": [
{
"type": "dropdown",
"value": [
{
"name": "Solar",
"value": "100"
}
],
"id": "measure_fc2t!!repeatable_q3gn!!15862359182380",
"name": "measure_fc2t",
"label": "Source",
"tags": []
},
{
"type": "numeric",
"value": 250000,
"unit": "kWh",
"id": "measure_dnkl!!repeatable_q3gn!!15862359182380",
"name": "measure_dnkl",
"label": "Energy used",
"tags": []
}
],
"type": "list"
},
{
"value": [
{
"type": "dropdown",
"value": [
{
"name": "Nuclear"
}
],
"id": "measure_fc2t!!repeatable_q3gn!!15862359243871",
"name": "measure_fc2t",
"label": "Source",
"tags": []
},
{
"type": "numeric",
"value": 3000000,
"unit": "kWh",
"id": "measure_dnkl!!repeatable_q3gn!!15862359243871",
"name": "measure_dnkl",
"label": "Energy used",
"tags": []
}
],
"type": "list"
}
],
"id": "repeatable_q3gn",
"name": "repeatable_q3gn"
},
{
"type": "file",
"value": [
{
"name": "ReportTest.pdf",
"link": "/attachment/get/3ef294e5-81ee-4958-bb99-3812be0d305a"
},
{
"name": "Information.pdf",
"link": "/attachment/get/bb602707-0055-48b2-b6ed-879eabfa217b"
}
],
"id": "measure_gtby",
"name": "measure_gtby",
"label": "Filuppladdning",
"tags": []
}
],
"type": "list"
},
"period": "Y0"
}
}
]
}Querying using startDate and endDate will return registrations where periodEndDate is within the range. Meaning if you filter on startDate '2019-12-01' you will get all registrations where the periodEndDate is later than 2019-12-01. This could be that the measure is configured to be reportedly yearly then the start date of the registration is 2019-01-01 and end date 2019-12-31 (if the year is following a calendar year).
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article