Version 5.2 and later.

1 I. Overview
2 II. Installation
- 2.1 1. Remote publishing within Visual Studio
- 2.2 2. Publish manually
3 III. Setup
- 3.1 1. Configuring the API
- 3.2 2. Creating an API key
4 IV. How to use the API
- 4.1 1. Create a log
- 4.2 2. Read logs
- 4.3 3. Get supported custom fields

I. Overview

The Usage Log API is an API that can be used to store any usage-related logs.

Usage log is now being used as a component in the WebViewer. For information regarding how to set it up in the WebViewer, please refer to: https://signifikant.atlassian.net/wiki/spaces/ASKB/pages/2769354753

II. Installation

Requirements: If it’s your first time installing .NET Core apps on a server, you might want to read this first: https://signifikant.atlassian.net/wiki/x/BQCIqw

They are two ways of installing the API. The first way is using remote publishing in Visual Studio, and the second way is by manually copying files to the IIS directory.

1. Remote publishing within Visual Studio

This is the easy way. If you have access to Visual Studio and the API code, you can simply publish from there.

Open the UsageLog.API project in Visual Studio 2022, then right-click on the project in the Solution Explorer and click on Publish… (see next screenshot)

Screenshot of how to bring up the Publishing options in VS 2022

It should open a new window with the publishing options. Make sure you have the IISProfile.pubxml profile selected and click on Publish (see following screenshot).

Screenshot of how to publish to remote server from publishing options window

If all goes well, you should then be prompted to enter a password:

And that is all! Provided you do not get any error, this means the publishing process succeeded, and the API has been deployed automatically to the remote server’s IIS server.

2. Publish manually

If you cannot publish automatically using the first way, then you will have to do it the manual way.

For this step, you will first need to get the last API release in a folder. To get it, you can either publish from within Visual Studio yourself or ask a developer for a fresh copy. To publish using Visual Studio, simply repeat the same steps as the easy way, but instead of selecting IISProfile.pubxml profile, you need to select FolderProfile.pubxml.

Once you have got your API published to a local folder, you can copy it over to your remote server.

You will have to place it in the wwwroot folder of IIS. Typically, it should be found under “C:\inetpub\wwwroot”.

Once you have copied the API there, the last thing is to rename the API folder to “UsageLogApi”.

Now, IIS should be able to automatically pick up the new site. You will then be able to access it at https://<myserver.com/UsageLogApi/.

III. Setup

1. Configuring the API

All configurations are done in the project appsettings.json file, which you should find at the root of the project directory.

Most of the configuration settings can be left untouched, but there are a few specific ones you need to make sure have the right values. For the purpose of this guide, the appsettings.json file has been truncated to only focus on the parts we want to modify. The file you have on your system should look more or less like this:

[
  "Auth": {
    "Secret": "MY_SECRET", // A secret signature used to validate/invalidate API keys and grant access to the API
    "Issuer": "https://localhost:7178" // The domain the API is deployed at (used for validating API keys)
  },
  "ConnectionStrings": {
    "UsageLogDb": "Server=<MY_SERVER>;Database=UsageLog;Trusted_Connection=True;"
  },
  ...
]

We have two important sections here:

Auth: Used to configure how access to the API is granted. Any use of the API requires the user to provide a specific API key.
- Secret: The secret is different from the API key, it is actually used to generate and sign the key to make sure it is legitimate.
- Issuer: The issuer is the hostname/domain of the server where the API is hosted.
ConnectionStrings: This is the part that is going to interest us the most. The only connection string we have is the one to the UsageLog database, which is where all logs are stored. That connection string can be mostly left as is, but you will need to set your SQL Server host so that the API can successfully connect to the database. Simply replace <MY_SERVER> with your SQL Server host.

And that is all for the setup. You should now be able to run the API and start using it.

2. Creating an API key

To create an API key, you need to generate a valid JWT token and sign it with your Secret (setup in configuration earlier).

Right now, the API does not require specific information or roles, it simply requires a trusted token to function. The token can contain any information, but it requires both an expiration date, and an issuer claim (set to your API base URL).

JWT tokens can be generated easily using https://jwt.io/.

The following screenshot illustrates how to generate an API key:

You have two tabs:

Encoded: What your API key looks like. You will use this long string to configure apps that need to communicate with the UsageLog API.
Decoded: The information stored in the key.

For now, we will switch our focus to the Decoded tab. It is split into three sections. Each section has a distinct color and corresponds to a substring in the encoded key:

Header: Defines the algorithm and token type. You don’t need to bother with that. Just make sure you have the same as in the screenshot.
Payload: Contains data used by the API to validate the key. For the UsageLog API, three properties are required:
- Issued at ("iat"): Start time for the period of validity. You can hover over the timestamp with your mouse to see the date in human-readable format. It should be set to the current time by default, you don’t need to change it.
- Expiration ("exp"): End time for the period of validity. The key will not be considered valid by the API past this date. In normal circumstances, this value should be very close to the start time (about 15 minutes). But, since the API does not have any logic to automatically refresh and issue a new token, we can make an exception and pick a distant date (like 6 months or one year). Just remember that after this time, the key will no longer be valid and you will need a new one.
- Issuer ("iss"): Name of the entity which issues/validates the key. It must match exactly whatever you put in your appsettings.json.
Verify signature: This section is the most important one, as it is the secret is the only thing that differentiate a forged key from an authentic one. Only the trusted authority (UsageLog API) should know the secret.

Once you are all done, you can switch back to the Encoded tab and save your key somewhere. This is the key you will use for your apps.

IV. How to use the API

The API can be easily used to read existing logs, create new ones, or add custom columns to have the ability to log more information.

Using the API might be more straightforward in order to provide information to other systems (e.g. in order to feed BI system).

1. Create a log

Endpoint: POST /api/v1/Logs

Payload: The body of this request must be a valid log model object. Pseudocode representation of the model:

class Log
{
  string message;
  string type;
  CustomEntry[] customEntries; // can be null
}

class CustomEntry
{
  string customFieldKey;
  string value;
  string details; // can be null
}

Example cURL request:

curl --location 'https://test1.signifikant.se/UsageLogApi/api/v1/Logs' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data '{
  "message": "New user connection",
  "type": "Authentication",
  "customEntries": [
    {
      "customFieldKey": "UserId",
      "value": "johndoe123",
      "details": ""
    },
  ]
}'

Description: This request will create a new log with type set to “Authentication” and message “New user connection”. It will also contain additional information about which user authenticated: johndoe123.

2. Read logs

Endpoint: GET /api/v1/Logs

Optional parameters:

startDate*: a string representation of the start date. Any log created prior to this date will not be fetched
endDate*: a string representation of the end date. Any log created after this date will not be fetched
type: a string filter to only get logs that have a specific type. The type is set when creating the log
limit: a number representing the maximum amount of logs that should be fetched

Example cURL request:

Description: This request attempts to fetch the last 2 logs created between January 1, 2000 at 10:30:00 (UTC-4) and July 13, 2023 at 15:30:00 (UTC-4) with type of Presentation.

3. Get supported custom fields

Custom fields are used to extend the normal logs to insert as much custom data as needed. For connection logs, this could be used to store the user ID or for presentation it could be used to store the presentation name. The possibilities are endless.

Endpoint: GET /api/v1/CustomFields

Example cURL request:

Signifikant Knowledge Base

Technical instruction - Usage Log API

I. Overview

II. Installation

1. Remote publishing within Visual Studio

2. Publish manually

III. Setup

1. Configuring the API

2. Creating an API key

IV. How to use the API

1. Create a log

2. Read logs

3. Get supported custom fields