RealEquity can be used to collect and subsequently retrieve statistics for a Case. Statistics is defined as information about e.g. views, unique views or downloads related to the case.
This is not intended as an exhaustive guide. There are additional statistics related end points available in the API, which are not discussed here. The end points discussed here have been singled out as it has been determined that they perform according to expectations in most use case.
Collecting statistics
Using the Add Case Tracking end point
The Add Case Tracking end point can be used to collect basic statistics for a Case, but not retrieve it. Retrieval is performed through another end point.
When using the specific endpoints on a case to add Statistics, the system will automatically create a Basic Statistics IE Base Type of type: dk.realequity.ie.stats.basic.default to hold the added statistics.
The end point is designed to handle the load of instant collection. During normal usage, the API should be called in real time every time a user event, which needs to be counted for statistical purposes, is taking place.
Bulk calls
While it is not necessary to bulk calls to this end point, it is possible, and up to 1000 statistics can be collected in one operation. This is particularly useful during import of statistics from another system.
No Bearer Token, supply Client Id in “x-realequity-clientid” header instead
The Add Case Tracking end point is currently a special case in that it doesn’t require a Bearer token for authorization, although it is stated in the API reference. We’re working on getting this updated.Instead of a Bearer token, you only need to supply a valid Client Id through the “x-realequity-clientid” header. Client Id’s are generated, along with secrets, during the administrative set up of new Partners in RealEquity.
Example usage
The following example is a raw HTTP request and its associated response. For the endpoint path, allowed methods, and params, please consult the API reference.
Request headers and body
POST {{api}}/api/tracking/cases/{{caseId}} HTTP/1.1
x-realequity-clientid: {{clientId}}
Content-Type: application/json
User-Agent: PostmanRuntime/7.28.4
Accept: */*
Cache-Control: no-cache
Postman-Token: 895734ee-c1c4-4e06-a3ec-633bdfaace12
Host: api.prod.realequity.dk
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 263
[
{
ieStatsNamespace: "dk.realequity.ie.stats.basic.default",
statBucketNamespace: "dk.realequity.stat.viewed"
},
{
ieStatsNamespace: "dk.realequity.ie.stats.basic.default",
statBucketNamespace: "dk.realequity.stat.downloaded"
}
]
Let’s start by looking at the request headers. {{api}} represents the URL of the RealEquity environment, which could be either int or prod. The path param {{caseId}} is a guid and represents the unique identifier - in RealEquity - of the Case to which the statistics are posted.
It is important to understand that CaseId is the Id of the Case Datanode in RealEquity, not the human-friendly caseNumber seen by a case worker or an end user, or an Id from Classic. This Id can be retrived through other available end points or from the REID or cbREID fields available in the Classic Datafeed. Finally, {{clientId}} is also a guid, and represents the unique identifier of the Partner posting the statistics on the case. The rest is boilerplate code generated by the HTTP client, in this case Postman.
Now, lets discuss the body. As described in the API reference, the Add Case Tracking end point accepts a list of objects. The objects are Case Tracking Models that can have the following properties:
| Property | Type | Description |
|---|---|---|
| ieStatsNamespace | String (Required) | Namespace of the Basic Statistics IE Base Type. While configurable, the default type is typically used: - dk.realequity.ie.stats.basic.default |
| statBucketNamespace | String (Required) | Namespace of the stat bucket. Two non-configurable options are available: - dk.realequity.stat.viewed, indicating a view, or - dk.realequity.stat.downloaded, indicating a download |
| sessionId | String (Optional) | This can be any string type describing the current users session. This is used by the system to determine, if required, whether or not a collected view or download is unique. |
| occurredByActorId | String (Optional) | If the user is a known RealEquity user, the Id of the Actor can be tracked as a part of the statistics. |
| occurredAt | DateTimeOffset (Optional) | When the event happened. If left out, the current datetime will be used. |
In this particular request example, two simple Case Tracking Models are being posted with nothing but the mandatory properties. The ieStatsNamespace value indicates that we’re posting statistics using the standard configuration available in the system (we haven’t had a reason to configure a custom statistics Information Element). There are two elements, indicating that we’re couting two user events, and the two different statBucketNamespace values indicate that while one event is a view, the other is a download.
What is a stat bucket?
A stat bucket contains all collected statistics of a given type. The namespace of the stat bucket describes the type of statistics in a bucket, i.e. either views or downloads.
Response headers and body
HTTP/1.1 202 Accepted
date: Thu, 30 Dec 2021 11:14:03 GMT
server: istio-envoy
content-length: 0
x-envoy-upstream-service-time: 12
The particular response example returns an empty body, but a HTTP status code 202 Accepted. This indicates that a well formed request was posted using correct headers.
A malformed request, or a request without correct headers, would - depending on the scenario - have returned either a body consisting of an error message string, or of a json document describing validation errors. In either case, the HTTP status code would have been 400 Bad Request.
Retrieving statistics
Statistics, such as the ones collected in the example above, are visisble in the RealEquity user interface immediatly upon collection. However, in some situations, it might be necessary to programmatically retrieve collected statistics in order to present or process them in other systems.
Using the Get Case Statistics In Buckets end point(s)
These end points are ideal when statistics for a relatively limited period of time are retrieved on-the-fly for the purpose of presentation, i.e. to display in a graph. The definitions of the “Get Case Statistics In Buckets” and “Get Case Statistics In Buckets Count” end points are almost identical, but their responses differ in that while the former returns a data set targeted graphical presentation of the distribution of user events over time (i.e. to underpin a graph), the latter basically sums up the same user events and returns an integer.
Example usage
The following example is a raw HTTP request to the “Get Case Statistics In Buckets” end point and its associated response. For the end point path, allowed methods, and params, please consult the [API reference].
Request headers and body
GET {{api}}/api/tenants/{{tenantId}}/resourcegroups/{{resourcegroupId}}/cases/{{caseId}}/statistics/buckets?unique=false&statsIeId=17d8ade9-fbbb-4150-b129-fca12638437a&groupby=day&days=7&statsNamespace=dk.realequity.ie.stats.basic&namespaces=dk.realequity.stat.downloaded HTTP/1.1
Authorization: Bearer {{token}}
User-Agent: PostmanRuntime/7.28.4
Accept: */*
Cache-Control: no-cache
Postman-Token: 6c50670b-1917-4015-b0fc-0e66c0f1a5be
Host: api.prod.realequity.dk
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Looking at the path params, {{api}} again represents the URL of the RealEquity environment, which could be either int or prod. {{tenantId}} represents the unique identifier of the RealEquity Tenant, {{resourcegroupId}} the unique identifier of the RealEquity Resource Group (i.e. store or chain) and {{caseId}} the RealEquity unique identifier of the Case. This time, however, a number of query string params are also supplied. These are listed and described in the table below.
We also see the presence of an Authorization header with a Bearer token, represented by {{token}}, indicating that this end point requires normal authorization. The rest is boilerplate code generated by the HTTP client, in this case Postman. Since we’re not posting anything, the body is empty.
| Param | Type | Description |
|---|---|---|
| statsIeId | Guid (Required) | Id of the Basic Statistics IE Base Type. While configurable, the default type is typically used: - 17d8ade9-fbbb-4150-b129-fca12638437a |
| statsNamespace | String (Required) | Namespace of the Basic Statistics IE Base Type. While configurable, the default type is typically used: - dk.realequity.ie.stats.basic.default |
| namespaces | List (Required) | Namespaces of the stat buckets to be retrieved. If only one stat bucket is to be retrieved, the query string is supplied once (i.e. “&namespaces={{statBucket}}”). If multiple stat buckets are to be retrieved, then it is supplied multiple times (i.e. “&namespaces={{statBucket-1}}&namespaces={{statBucket-2}}”). |
| unique | Boolean (optional) | Determines whether or not only unique statistics are included in the response provided that the sessionId param is being used correctly and consequently in the “Add Case Tracking” end point. |
| groupby | String (optional) | Determines how the statistics are summed up and presented in the response. Options are: - day (default), indicating that user events are summed up per day - week, indicating that user events are summed up per first day of week - month, indicating that user events are summed up per first day of month |
| days | Int (optional) | Determines the period from which to retrieve statistics. Today is always included, meaning that a value of “7” will result in the retrieval of statistics from today, as well as the 7 preceeding days. |
Please note that the use of the “groupby” query string param does not change the response schema. The response will always contain a list of stat buckets with one bucket per day in the period defined by the use of the “days” query string param. If a groupby value of week or month is supplied, all user events within a given week or month will be summed up and shown as if they occurred on the first day of the week or month, respectively.
HTTP/1.1 200 OK
date: Thu, 30 Dec 2021 18:14:12 GMT
content-type: application/json; charset=utf-8
server: istio-envoy
vary: Accept-Encoding
x-envoy-upstream-service-time: 166
Content-Length: 284
{"totalCount":6,"buckets":[{"date":"2021-12-23","count":0},{"date":"2021-12-24","count":0},{"date":"2021-12-25","count":0},{"date":"2021-12-26","count":0},{"date":"2021-12-27","count":0},{"date":"2021-12-28","count":0},{"date":"2021-12-29","count":1},{"date":"2021-12-30","count":5}]}
As can be seen above, the response is a JSON object containing two properties, totalCount (integer) and buckets (array).
Below, the JSON body has been extracted and formatet for a better viewing experience. totalCount sums up the total number of user events within the period as defined by the query string param days described above. buckets contain an object per date in the period. Each object contains the date as a property date of type string and the sum of user events on that date, count, as integer.
{
"totalCount": 6,
"buckets": [
{
"date": "2021-12-23",
"count": 0
},
{
"date": "2021-12-24",
"count": 0
},
{
"date": "2021-12-25",
"count": 0
},
{
"date": "2021-12-26",
"count": 0
},
{
"date": "2021-12-27",
"count": 0
},
{
"date": "2021-12-28",
"count": 0
},
{
"date": "2021-12-29",
"count": 1
},
{
"date": "2021-12-30",
"count": 5
}
]
}
Had the same HTTP request been fired to (…)statistics/buckets/count?(…) instead of (…)statistics/buckets?(…) , i.e. hitting the “Get Case Statistics In Buckets Count” end point mentioned in the beginning of this section, the extracted and JSON formatted body of the response would have been as follows:
{
"count": 6
}
Using the Get Case Statistics end point
This end point is ideal when a large number of statistic records are retrieved for the purpose of further processing. The end point offers a paged, raw extract of all collected user events on a given case. The extracted data can be filtered and processed based on the sessionId, namespace and createdAt properties. sessionId pertains to uniqueness, namespace to the type of user event, and createdAt to the time that the user event occured. Here is a deep link to the API reference for the end point.
If you’re using the “Get Case Statistics” end point, you need to pay special attention to how you obtained your Bearer token. If you obtained your Bearer token without supplying a RealEquity Resource Group id using the rg query string param, your API calls are likely to fail with a “Missing statistics information element” error, since your HTTP client will not have acces to the Information Element configuration on the Resource Group you’re requesting statistics for. Obtain a Bearer Token using the rg param, as described here, to overcome this issue.
Request headers and body
Looking at the path params, {{api}} again represents the URL of the RealEquity environment, which could be either int or prod. {{tenantId}} represents the unique identifier of the RealEquity Tenant, {{resourcegroupId}} the unique identifier of the RealEquity Resource Group (i.e. store or chain) and {{caseId}} the RealEquity unique identifier of the Case.
GET {{api}}/api/tenants/{{tenantId}}/resourcegroups/{{resourcegroupId}}/cases/{{caseId}}/statistics?statsNamespace=dk.realequity.ie.stats.basic.default HTTP/1.1
Authorization: Bearer {{token}}
User-Agent: PostmanRuntime/7.28.4
Accept: */*
Cache-Control: no-cache
Postman-Token: c68a4711-175f-4a42-834e-3204064ce1d5
Host: api.prod.realequity.dk
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
The end point also takes three query string params of which only one has been used in the example above. All three are listed in the table below.
| Param | Type | Description |
|---|---|---|
| statsNamespace | String (Required) | Namespace of the Basic Statistics IE Base Type. While configurable, the default type is typically used: - dk.realequity.ie.stats.basic.default |
| top | Integer | The number of records to retrieve (max 1000). Used for paging purposes. Defaults to 1000. |
| skip | Integer | The first record to retrieve. Used for paging purposes. Defaults to 0. |
Response headers and body
Provided that a correctly obtained Bearer token has been passed along with the request, and the statsNamespace is correct as well, the response will be a JSON array of StatisticsModel objects:
HTTP/1.1 200 OK
date: Mon, 03 Jan 2022 14:18:06 GMT
content-type: application/json; charset=utf-8
server: istio-envoy
vary: Accept-Encoding
x-envoy-upstream-service-time: 25
Content-Length: 3169
[{"sessionId":null,"externalEntityId":null,"entityReferenceId":"bb895e85-8a9e-44e0-a5b0-2ad4204ae88c","entityReferenceNamespace":"dk.realequity.case.sale","namespace":"dk.realequity.stat.viewed","createdById":null,"createdAt":"2021-12-29T15:07:48.6770399+00:00"},{"sessionId":null,"externalEntityId":null,"entityReferenceId":"bb895e85-8a9e-44e0-a5b0-2ad4204ae88c","entityReferenceNamespace":"dk.realequity.case.sale","namespace":"dk.realequity.stat.downloaded","createdById":null,"createdAt":"2021-12-29T15:07:48.6771279+00:00"},{"sessionId":null,"externalEntityId":null,"entityReferenceId":"bb895e85-8a9e-44e0-a5b0-2ad4204ae88c","entityReferenceNamespace":"dk.realequity.case.sale","namespace":"dk.realequity.stat.viewed","createdById":null,"createdAt":"2021-12-30T11:09:55.5882527+00:00"},{"sessionId":null,"externalEntityId":null,"entityReferenceId":"bb895e85-8a9e-44e0-a5b0-2ad4204ae88c","entityReferenceNamespace":"dk.realequity.case.sale","namespace":"dk.realequity.stat.downloaded","createdById":null,"createdAt":"2021-12-30T11:09:55.5883942+00:00"},{"sessionId":null,"externalEntityId":null,"entityReferenceId":"bb895e85-8a9e-44e0-a5b0-2ad4204ae88c","entityReferenceNamespace":"dk.realequity.case.sale","namespace":"dk.realequity.stat.viewed","createdById":null,"createdAt":"2021-12-30T11:10:28.5565701+00:00"},{"sessionId":null,"externalEntityId":null,"entityReferenceId":"bb895e85-8a9e-44e0-a5b0-2ad4204ae88c","entityReferenceNamespace":"dk.realequity.case.sale","namespace":"dk.realequity.stat.downloaded","createdById":null,"createdAt":"2021-12-30T11:10:28.5566491+00:00"},{"sessionId":null,"externalEntityId":null,"entityReferenceId":"bb895e85-8a9e-44e0-a5b0-2ad4204ae88c","entityReferenceNamespace":"dk.realequity.case.sale","namespace":"dk.realequity.stat.viewed","createdById":null,"createdAt":"2021-12-30T11:14:04.9872434+00:00"},{"sessionId":null,"externalEntityId":null,"entityReferenceId":"bb895e85-8a9e-44e0-a5b0-2ad4204ae88c","entityReferenceNamespace":"dk.realequity.case.sale","namespace":"dk.realequity.stat.downloaded","createdById":null,"createdAt":"2021-12-30T11:14:04.9875807+00:00"},{"sessionId":null,"externalEntityId":null,"entityReferenceId":"bb895e85-8a9e-44e0-a5b0-2ad4204ae88c","entityReferenceNamespace":"dk.realequity.case.sale","namespace":"dk.realequity.stat.viewed","createdById":null,"createdAt":"2021-12-30T12:28:20.3893916+00:00"},{"sessionId":null,"externalEntityId":null,"entityReferenceId":"bb895e85-8a9e-44e0-a5b0-2ad4204ae88c","entityReferenceNamespace":"dk.realequity.case.sale","namespace":"dk.realequity.stat.downloaded","createdById":null,"createdAt":"2021-12-30T12:28:20.3894519+00:00"},{"sessionId":null,"externalEntityId":null,"entityReferenceId":"bb895e85-8a9e-44e0-a5b0-2ad4204ae88c","entityReferenceNamespace":"dk.realequity.case.sale","namespace":"dk.realequity.stat.viewed","createdById":null,"createdAt":"2021-12-30T12:49:03.3919918+00:00"},{"sessionId":null,"externalEntityId":null,"entityReferenceId":"bb895e85-8a9e-44e0-a5b0-2ad4204ae88c","entityReferenceNamespace":"dk.realequity.case.sale","namespace":"dk.realequity.stat.downloaded","createdById":null,"createdAt":"2021-12-30T12:49:03.3920749+00:00"}]
In the example below, the first two objects of the reponse above have been extracted and the JSON prettyfied.
[
{
"sessionId": null,
"externalEntityId": null,
"entityReferenceId": "bb895e85-8a9e-44e0-a5b0-2ad4204ae88c",
"entityReferenceNamespace": "dk.realequity.case.sale",
"namespace": "dk.realequity.stat.viewed",
"createdById": null,
"createdAt": "2021-12-29T15:07:48.6770399+00:00"
},
{
"sessionId": null,
"externalEntityId": null,
"entityReferenceId": "bb895e85-8a9e-44e0-a5b0-2ad4204ae88c",
"entityReferenceNamespace": "dk.realequity.case.sale",
"namespace": "dk.realequity.stat.downloaded",
"createdById": null,
"createdAt": "2021-12-29T15:07:48.6771279+00:00"
},
//...additional objects
]
Properties “externalEntityId” and “entityReferenceId” are obsolete
These properties will be removed in a future release.
| Property | Type | Description |
|---|---|---|
| sessionId | Nullable String | Any string type describing the current users session. This is used by the system to determine, if required, whether or not a collected view or download is unique. |
| externalEntityId | Nullable String | Obsolete. |
| entityReferenceId | Nullable String | Obsolete. |
| namespace | Nullable String | Namespace of the type of user event to receive statistics for. Comparable to the namespace of a the stat bucket as described above. |
| createdById | Nullable String | Can be the id of the RealEquity actor in the context of which the user event is being collected. |
| createdAt | DateTime | Date and time the user event was collected. |