Switch to Version 2 of the Tenants API

Start using Visier's second version of the tenants API.

Who can use this feature?

  • Embedded Partner API User

Not sure if you have this feature or capability? Reach out to your administrator.

Overview

Visier now offers version 2 (V2) of the tenants API. If you're already using version 1 (V1) endpoints, you can read this article to learn about the differences between V1 and V2, and migrate your existing API setup to use V2. Version 1 endpoints are still supported and unchanged.

In V2, you can now:

  • Programmatically assign a Home analysis to your analytic tenants.
  • Specify whether to merge or replace values when updating the details of an analytic tenant.
  • Specify the property fields to include in the response for GET requests.

To start using the tenants API, see Tenants API.

Version 2 endpoints

The V2 URL is https://{vanity-name}.api.visier.io/v2/admin/tenants/.

The second version of the tenants API supports the following endpoints:

  • Create an analytic tenant POST admin/tenants
  • Update an analytic tenant PUT admin/tenants/{tenantCode}
  • Retrieve an analytic tenant's details GET admin/tenants/{tenantCode}
  • Retrieve a list of all analytic tenants GET admin/tenants

New API setups for tenants API should use V2 endpoints. If existing API setups continue to use V1 endpoints, please note that the V1 endpoints will no longer receive product updates or enhancements.

To start using the version 2 endpoints, adjust your existing API setups to use the new URL and parameters for the above endpoints. For more information, see Tenants API.

Differences between version 1 and version 2

The following changes distinguish V2 from V1:

  • Version 2 no longer requires the model parameter in requests.
  • Versions 2 PUT requests only return fields that were updated in the API call.

Removal of the "model" parameter

In V1, URL-encoded request bodies contained a single key, model, the value of which was a single JSON string containing the entire request data. In V2, model is not used. Instead, URL-encoded requests specify multiple key-value pairs, where each pair is a property of the request data. If you still want to use a single JSON string, you can do so with the application/json content type.

Example: Request body expressed equivalently as URL-encoded key-value pairs and JSON

Key Value
tenantDisplayName "Io"
industryCode 111
Copy 
{
    "tenantDisplayName": "Io",
    "industryCode": 111
}

Returning only fields that were updated

In V2, we improved ease of use and readability by requiring that responses from PUT (update) calls only contain the fields that were specified in the request body. Fields that have no meaningful value, such as empty arrays or strings, are still included in the response for clarity.

Example: Update the industry code of an analytic tenant

Let's say you want to update the industry code of an analytic tenant from 11 to 111. The following request body makes that update:

Copy 
curl -X PUT --url https://jupiter.api.visier.io/v2/admin/tenants/WFF_j1r~i1o
-H "apikey:12345"
-H "Cookie:VisierASIDToken=abc123"
-d {
    "tenantDisplayName":"Io",
    "industryCode": 111,
    "purchasedModules":["Talent_Acquisition","Organization"],
    "updateAction": "REPLACE"
}

In V2, the response body returns as follows:

Copy 
{
    "tenantCode": "WFF_j1r~i1o",
    "tenantDisplayName": "Io",
    "purchasedModules": ["Talent_Acquisition", "Organization"],
    "industryCode": 111,
}

In V1, the response body returns as follows:

Copy 
{
    "tenantCode": "WFF_j1r~i1o",
    "tenantDisplayName": "Io",
    "purchasedModules": ["Talent_Acquisition", "Organization"],
    "industryCode": 111,
    "customProperties": [{
      "key": "property1",
      "value": "value1"
    }],
    "ssoInstanceIssuers": ["myissuer"]
}

In this example, you can see that the V1 response provides additional fields that weren't updated in the API call. In V2, the response is shorter and more relevant to the changes made by the request.

New features in version 2

Tenants API V2 introduces several new features that aren't available in V1:

  • Programmatically assign a Home analysis to your analytic tenants.
  • Specify whether to merge or replace values when updating the details of an analytic tenant.
  • Specify the fields to include in the response.

Assign a Home analysis to tenants

You can now set the Home analysis for your analytic tenants programmatically, allowing you to respond dynamically and at scale to the changing needs of your tenants. The Home analysis is the first analysis that your end users will see in Visier after they log in. For more information about the Home analysis, see Home.

Two parameters in the request body correspond to the Home analysis:

  • homeAnalysisId: The ID of the analysis that you want users to see after they login.
  • homeAnalysisByUserGroup: The specific user groups that are assigned a different Home analysis than the rest of the user base.

Caution: Assigning the Home analysis and retrieving information about tenant Home analyses are time-consuming processes. If you do not need to retrieve Home analysis information, exclude homeAnalysisId and homeAnalysisByUserGroup from the mask property in your request body.

The default and maximum number of tenants to retrieve in the list endpoint GET admin/tenants is set to 400 to prevent server overload.

Merge or replace updated values

In V2, users who are updating values using a PUT endpoint can specify how to handle the update to list values and nested values with a new updateAction parameter.

There are two actions to update values:

  • MERGE: Combine the existing values with the new values. This is the default action.
    • If the values are list values, MERGE adds the new values to the existing values.
    • If the values are nested values, such as part of a JSON object, MERGE only updates the values specified in the request. Existing values associated with the JSON object that aren't specified in the request are not changed.
  • REPLACE: Remove existing values and let the new values take their place.
    • If the values are list values, the new values replace the old values.
    • If the values are nested values, such as part of a JSON object, the new values only replace parameters specified in the request. Existing values associated with the JSON object that aren't specified in the request are not changed.

If updateAction is not defined, MERGE is the default action.

Use "mask" to specify response fields

Users can now specify particular fields to include in the response by adding a comma-separated list of strings to the request body with the mask parameter in GET requests. If mask is defined, the response only includes the fields listed. To prevent ambiguous data, some fields may be included in the response regardless of mask, such as tenantCode.

Only top-level parameters are valid in mask. Nested parameters are included as a whole; individual nested values cannot be specified in mask. However, for list operations, such as GET admin/tenants, parameters specified in mask refer to parameters within the listed objects as though they were also top-level parameters.

Invalid strings are ignored. If mask is not defined, the response for a GET request returns all available fields.

Example: GET request with the mask parameter

Let's say you want to retrieve the details of an analytic tenant, but you're only interested in the tenant display name and their industry code. You can use the mask parameter to specify that you only want those two parameters in the response, as shown next.

Copy 
curl -X GET --url https://jupiter.api.visier.io/v2/admin/tenants/WFF_j1r~i1o \
-H "apikey:12345" \
-H "Cookie:VisierASIDToken=abc123" \
-H "Content-Type: application/json" \
-H "Accepts: */*" \
-d '{
    "mask":"tenantDisplayName,industryCode"
}'

The response body returns as follows:

Copy 
{
    "tenantCode": "WFF_j1r~i1o",
    "tenantDisplayName": "Io",
    "industryCode": 111
}

In this example, the parameters that you wanted, tenantDisplayName and industryCode, are returned in the response along with tenantCode, which is required to provide necessary context for the data. In V1, this endpoint returns more than 12 fields, which is unnecessary if you're only interested in a few specific fields.

Example: GET request with the mask parameter on a list operation

Let's say you want to retrieve the details of 2 analytic tenants, but you're only interested in the tenant display names and their industry codes. You can use the mask parameter to specify that you only want those two fields in the response, as shown next.

Copy 
curl -X GET --url https://jupiter.api.visier.io/v2/admin/tenants?limit=2 \
-H "apikey:12345" \
-H "Cookie:VisierASIDToken=abc123" \
-H "Content-Type: application/json" \
-H "Accepts: */*" \
-d '{
    "mask":"tenantDisplayName,industryCode"
}'

The response body returns as follows:

Copy 
{
    "tenants": [
      {
        "tenantCode": "WFF_j1r~i1o",
        "tenantDisplayName": "Io",
        "industryCode": 111
      },
      {
        "tenantCode": "WFF_j1r~c7o",
        "tenantDisplayName": "Callisto",
        "industryCode": 51
      }
    ]
}

In this example, the tenantDisplayName and industryCode are not top-level properties; they are properties of the objects listed in tenants. However, the mask parameter retrieves nested values in list operations as if they are top-level properties.