Skip to main content
Version: 2024

Endpoints

License endpoints​

Main administrator

Indicium supports UI and HTTP endpoints for licensing an IAM environment. Users can use these endpoints to update the license information of their IAM environment without needing a UI.

UI endpoints​

The UI page is available at <Indicium URL>/license.

UI endpoint UI endpoint

If Indicium detects that the environment is not registered, it displays the link Register environment. After registering your environment, you can check for an updated license without restarting Indicium.

HTTP endpoints​

The following HTTP endpoints are available:

/license endpoint​

You can use the /license HTTP endpoint to fetch a JSON representation of the current status of the license. Make sure to include an Accept header containing application/json in your GET request to the endpoint:

GET /license
Accept application/json

Example responses

  • The license is unregistered.

    200 OK

    {
      "state": "Unregistered",
      "refresh_on": "2023-06-27T08:54:56.92Z",
      "valid_until": "2023-06-27T09:04:56.92Z",
      "is_updating": false,
      "registration_url": "http://tcp.thinkwise.app/<rest of url>"
    }

  • The license is valid.

    200 OK

    {
      "state": "Valid",
      "refresh_on": "2023-07-27T08:53:51.1337524Z",
      "valid_until": "2023-09-25T08:53:51.1337529Z",
      "is_updating": false
    }

  • The license is stale because the refresh date is in the past.

    200 OK

    {
      "state": "StaleByDate",
      "refresh_on": "2023-07-25T08:53:51.1337524Z",
      "valid_until": "2023-09-25T08:53:51.1337529Z",
      "is_updating": false
    }

  • The license is stale because the IAM contains a model that is not part of the current license.

    200 OK

    {
      "state": "StaleByGuid",
      "refresh_on": "2023-07-27T08:53:51.1337524Z",
      "valid_until": "2023-09-25T08:53:51.1337529Z",
      "is_updating": false
    }

  • The license is expired.

    200 OK
    {
      "state": "Expired",
      "refresh_on": "2023-06-27T08:53:51.1337524Z",
      "valid_until": "2023-07-25T08:53:51.1337529Z",
      "is_updating": false
    }

/license/update endpoint​

You can also trigger the check for an updated license by making a POST request to a /license/update endpoint. Use this together with the Licensing:ScheduleUpdate setting to, for example, disable the hourly update schedule and have a Continuous Integration (CI) environment perform the update at a specific time of the day instead. The procedure for this is as follows:

POST /license/update

Example responses

  • If the update completes within 10 seconds, which it should in most cases, you will receive the same response data as with a GET request to /license, for example:

    200 OK
    {
      "state": "Valid",
      "refresh_on": "2023-08-27T08:53:51.1337524Z",
      "valid_until": "2023-09-25T08:53:51.1337529Z",
      "is_updating": false
    }

  • If the update somehow takes longer than 10 seconds, the client will instead receive a '201 Created' response with a 'Location' header that points to the /license endpoint:

    201 Created
    Location <Indicium>/license

    Now, the client must poll the /license endpoint every so often until it confirms that the is_updating property specifies 'false', to prevent queuing another license update:

    GET /license
    Accept application/json

    • If the client is not done updating, the response will be similar to:

      200 OK
      {
        "state": "Expired",
        "refresh_on": "2023-06-27T08:53:51.1337524Z",
        "valid_until": "2023-07-25T08:53:51.1337529Z",
        "is_updating": true
      }

    • If the client is done updating, the response will be similar to:

      200 OK
      {
        "state": "Valid",
        "refresh_on": "2023-08-27T08:53:51.1337524Z",
        "valid_until": "2023-09-25T08:53:51.1337529Z",
        "is_updating": false
      }

Health check endpoint​

Application administrator

The /health endpoint can be used by monitoring software to periodically check the status of Indicium. This endpoint can be accessed anonymously.

Basic use​

If Indicium has been started successfully and the user accessing it does not have the Developer mode role, the \health endpoint will return one of the following responses:

  • A "Healthy" status indicates that Indicium is running as expected as far as the health checks can determine.

    200 OK
    {
      "status": "Healthy"
    }

  • A "Degraded" status indicates that the connection to the meta source (IAM) works as expected, but one or more application connections are having issues.

    200 OK
    {
      "status": "Degraded"
    }

  • An "Unhealthy" status indicates that Indicium's connection to the meta source is having issues.

    503 Service Unavailable
    {
      "status": "Unhealthy"
    }

Advanced use​

Developer mode

The endpoint returns more information if accessed by a user with the Developer mode role in IAM. For example, a basic result when everything is healthy:

200 OK
{
  "status": "Healthy",
  "reports": {
    "meta_source": {
      "status": "Healthy",
      "description": "Status of the connection to the meta source database.",
      "duration": 78.8475,
      "data": {
        "assembly_version": "0.0.0.0",
        "result_loaded_from_cache": false,
        "sub_reports": {
          "iam_connection": {
            "status": "Healthy",
            "description": "Connection to IAM was successful.",
            "data": {}
          },
          "version": {
            "status": "Healthy",
            "description": "The metasource version of the database and the one that Indicium started with are the same.",
            "data": {
              "expected_version": "2023.2.13",
              "current_version": "2023.2.13"
            }
          },
          "time_difference": {
            "status": "Healthy",
            "description": "The time difference between the server Indicium is running on and the database server must be less than 20 seconds.",
            "data": {}
          }
        }
      }
    },
    "application": {
      "status": "Healthy",
      "description": "Connection status of each application that is currently active in IAM.",
      "duration": 168.6951,
      "data": {
        "sub_reports": {
          "itst": {
            "status": "Healthy",
            "description": "Connection status to the database of application itst.",
            "data": {
              "application_id": 52,
              "application_alias": "itst",
              "model_id": "INDICIUM_INTEGRATION_TEST",
              "model_version": "MAIN",
              "result_loaded_from_cache": false,
              "cache_result_expiration": "2023-09-26T15:48:33.9810801Z"
            }
          },
          "sf": {
            "status": "Healthy",
            "description": "Connection status to the database of application sf.",
            "data": {
              "application_id": 64,
              "application_alias": "sf",
              "model_id": "SQLSERVER_SF",
              "model_version": "2023.2.13",
              "result_loaded_from_cache": false,
              "cache_result_expiration": "2023-09-26T15:48:34.0123615Z"
            }
          }
        }
      }
    }
  }
}

Meta source report​

The meta_source report contains data about the connection to the meta source that has been configured for this Indicium instance.

  • The assembly_version property contains the full product version of Indicium according to the assembly file, for example, "2023.2.13.0-ga9a28b0-0".
  • The agent_id contains the ID that this Indicium instance communicates towards IAM to facilitate agent services such as system flows.
    • It is only present if the Agent:Enabled setting in the Indicium configuration has been set to true.
  • The result_loaded_from_cache property indicates whether or not the current request used a cached result for the entire check.
    • All checks are always performed, even if the endpoint is accessed anonymously.
    • To prevent checks from hitting the database too often, some checks contain a caching mechanism.
    • You can change the duration of the cache time; see the configuration options further below.
  • The sub_reports property contains more information about each sub-check that was done to determine the status of the meta_source check.
    • iam_connection checks if Indicium can still connect to the meta-source database.
    • version checks if the version of the meta-source still matches the one that Indicium found when first starting up.
    • time_difference checks if the time difference between the system clock of the server Indicium is running on does not deviate too much from what the database server reports. If the difference is too great, features such as system flow scheduling might experience issues.
    • If any of these checks report Unhealthy, there is something wrong with Indicium, and it might need to be restarted in order to continue providing service.

Application report​

The application report contains data about the connection status to each currently available application within the meta-source.

  • Each sub-report is about an application of which the connection was checked.
  • The ID of the sub-report is either the application's alias or if the alias is not set, the ID of the application.
  • Each sub-report contains the following data properties:
    • The application_id - the ID of the application that was checked.
    • The application_alias - the alias of the application that was checked.
    • The model_id of the application.
    • The model_version of the application.
    • The result_loaded_from_cache property indicates whether this result was currently loaded from the cache.
    • The cache_result_expiration property contains a UTC timestamp indicating when the cached result expires, and the connection will be checked again.
      • The Healthy and Unhealthy statuses have different cache durations. Both can be changed in the configuration of Indicium; see the configuration example further below.
  • The sub-reports will indicate either a Healthy or Unhealthy status. However, the main status of this report will indicate Degraded in case one of the applications indicates an Unhealthy status. The reason for this is that an application connection failing does not necessarily indicate that the entire Indicium service is running incorrectly. Furthermore, some monitoring software on Azure, for example, will attempt to restart Indicium if the health endpoint returns an HTTP status code outside the 200 range. Since an Unhealthy status returns a 503 Service Unavailable response code, this would be the case. However, a restart probably will not fix the issue in case of an application connection failure. Therefore, we return a Degraded health status instead to indicate that something is still wrong, but the service will not be restarted because a Degraded status also returns a 200 OK HTTP response code.

Configuration options​

Below are the configuration options that are available for the health checks and their default values:

{
  "HealthCheck": {
    "MetaSource": {
      "CacheDurationInSeconds": 60
    },
    "Application": {
      "Enabled": true,
      "Include": [],
      "Exclude": [],
      "CacheDurationInSeconds": {
        "Healthy": 300,
        "Unhealthy": 60
      }
    }
  }
}
  • HealthCheck:MetaSource:CacheDurationInSeconds controls the cache duration of the entire meta source check result.
    • The default value is 60 seconds (1 minute).
  • HealthCheck:Application:Enabled controls whether the application connection check is enabled.
    • The default value is true.
    • If set to false, a report is still added, but it will always return Healthy.
  • HealthCheck:Application:Include can be used to only perform the application connection check on the provided application aliases/IDs.
    • By default, all active applications are included.
    • If you set this value to [ "sf", "example", "96" ], for example, only the connection to these applications will be checked:
      • Alias: sf
      • Alias: example
      • ID: 96
  • HealthCheck:Application:Exclude can be used to exclude certain applications by alias/ID from the check.
    • By default, no applications are excluded
    • Setting this value to [ "example", "96" ], for example, would cause these applications to be excluded from the check.
    • This setting gets applied after Include, so combining the two examples above would result in only the following application connection being checked:
      • Alias: sf
  • HealthCheck:Application:CacheDurationInSeconds:Healthy can be used to control the cache duration of each application connection result that reports a Healthy status.
    • The default value is 300 seconds (5 minutes).
    • The minimum value that can be configured is 10 seconds.
  • HealthCheck:Application:CacheDurationInSeconds:Unhealthy can be used to control the cache duration of each application connection result that reports an Unhealthy status.
    • The default value is 60 seconds (1 minute).
    • The minimum value that can be configured is 10 seconds.

Was this page helpful?