TABLE OF CONTENTS

• REST API Importer: Unique Features
  • Overview
  • Cross-Project Connections to ManagementStudio
    • Enable Endpoint for Datamining Reports
  • Common Settings
  • Examples
    • Example: Sync Custom Fields from Primary Project to Sub-Project
    • Headers
    • Field Mapping
    • Example: Sync App Blueprints from Primary Project to Sub-Project
    • Headers
    • Field Mapping
    • Example: Sync App Contacts from Primary Project to Sub-Project
    • Example: Sync App Dependencies from Primary Project to Sub-Project
    • Headers
    • Field Mapping
• REST API Importer — Connection Options
  • 1. What this panel is for
    • The other half of the setup lives on the Import tabs
  • 2. Field guide
    • Known REST API Types
    • Auth Endpoint Url
    • Request Type
    • Token Property
    • Headers
    • Add a Secure Header Value
    • JSON Body
    • Process Repsonce Script Block
    • Test Aquire Token
    • Proxy Server for Internet access
  • 3. Choosing a Known REST API Types option
    • 3.1 Auth-Token — I already have a token or API key
    • 3.2 MS Graph-API — I'm reading from Microsoft Graph / Microsoft 365
    • 3.3 Custom — some other system, and you can describe its sign-in call
    • 3.4 Snow
    • 3.5 NextThink
  • 4. A quick worked example
  • 5. Storing secrets properly
  • 6. Proxy Server for Internet access
  • 7. Testing what you configured
  • 8. Known limitations
  • 9. Troubleshooting
  • Further Support

REST API Importer: Unique Features

This article describes features specific to the REST API Importer in ManagementStudio. For information about features common to all importers, refer to the appropriate documentation.

Overview

The REST API Importer allows ManagementStudio to connect to third-party data sources that provide a standard REST API, but do not have an official ManagementStudio connector.

Cross-Project Connections to ManagementStudio

The REST API Importer can be used to connect to the same ManagementStudio instance or to external instances. When cross-project sharing is enabled, this functionality supports copying data between a Primary Project and its Sub-Projects for data that is not shared by default.

When configuring the REST API Importer to connect to ManagementStudio, consult the Endpoint Reports (for PowerBI) article for guidance on constructing REST queries.

Tip: When connecting to the same instance but targeting a different project or module, use the value [importer-auth-token] for the Auth-Token header.

Enable Endpoint for Datamining Reports

To access Datamining Reports via an endpoint, you must enable this setting in the source project.

Common Settings

• Rest Api Endpoint Url
  Format:

  https://<ServerAddress>/<ProjectId>/p/report/Datamining/0/<PrefixedName>/json
  

  • <ServerAddress>: Your ManagementStudio server address
  • <ProjectId>: ID of the Primary Project
  • <PrefixedName>: The prefixed name of the Datamining Report

• Import Multiple Matched Rows

  • Enable this option to allow importing multiple rows after the first match is found.
  • Required for importing lists such as Blueprints and Dependencies.

Examples

Example: Sync Custom Fields from Primary Project to Sub-Project

Headers

Field Mapping

Example: Sync App Blueprints from Primary Project to Sub-Project

Headers

Field Mapping

Ensure you have:

• Enabled Endpoint for Datamining Reports
• Checked Import Multiple Matched Rows

Example: Sync App Contacts from Primary Project to Sub-Project

Syncing contacts does not require the REST API Importer. Contacts can be shared directly as shown in the user interface.

Example: Sync App Dependencies from Primary Project to Sub-Project

Headers

Field Mapping

Ensure you have:

• Enabled Endpoint for Datamining Reports
• Checked Import Multiple Matched Rows

REST API Importer — Connection Options

1. What this panel is for

This panel holds the credentials for the whole REST API Importer. It answers one question:

How do I get a token that proves the importer is allowed to read from this API?

Everything else — the data address, the field mapping, the schedule — assumes this panel has already produced a working token.

There is one set of credentials and every import shares it. Import 1, Import 2, Import 3 and the links import all authenticate through here. If two data sources need different credentials, that normally means two separate REST API Importer entries.

The other half of the setup lives on the Import tabs

Obtaining a token is only half the job. Each Import tab must also be told where to put that token in the request it sends, using a placeholder — text you type into a header value that the importer replaces with the real token when it runs.

Both halves have to be in place:

• Panel configured, but no [Auth-Token] on the Import tab → the request goes out with no credentials and you get an authorisation failure or "no data".
• [Auth-Token] on the Import tab, but this panel misconfigured → the placeholder is filled with nothing, and you get the same authorisation failure.

The placeholder ignores capitalisation and works anywhere inside the value, so Bearer [auth-token] is fine. Put it in a header value, not in a header name.

Reading from ManagementStudio itself rather than a third-party API? Use [importer-auth-token] as the header value. That is the supported way to copy data between a primary project and its sub-projects, and it needs no credentials on this panel at all — see the REST API Importer article on support.managementstudio.com.

2. Field guide

Known REST API Types

A dropdown that says which kind of system you are connecting to. Your choice here decides which of the other fields matter and what belongs in the Headers grid. Walk through every option in section 3.

Available: Clear, Auth-Token, MS Graph-API, Custom, Snow, NextThink.

Nothing else on the panel has any effect until you select a real option here.

Auth Endpoint Url

The web address that hands out the token — not the address of the data you want to import. The data address belongs on the Import tabs.

Used by Custom, Snow and NextThink. Leave it empty for Auth-Token and MS Graph-API; it is ignored there.

Example: https://idp.example.com/oauth2/token

Request Type

Get or Post, and Custom only. It says how the token request should be made. Most token services expect Post.

Token Property

Custom only. Says which part of the token service's reply holds the token, when it isn't where the importer looks by default. For example, if the reply is {"data": {"token": "abc123"}}, you would point this at data.token.

Read the limitation in section 8 before relying on this field.

Headers

A grid of name/value pairs sent with the token request. This is where your credentials go for every option except the Custom style of header authentication. Each row has move-up, move-down and delete buttons; Add New Setting adds a row.

Which names the panel looks for depends on what you chose in Known REST API Types — see section 3. Names to get exactly right: Connector, clientId, clientSecret, username, password and Auth-Token. Upper and lower case doesn't matter; punctuation does (see the warning in 3.1).

Add a Secure Header Value

Adds a header whose value is saved encrypted instead of as readable text. Fill in Header Name and Header Value, press the button, and the value is stored in protected form.

Use this for anything secret — API keys, client secrets, passwords, bearer tokens. An ordinary row in the Headers grid is stored in readable form in the importer's configuration.

Two things to know about encrypted values on screen:

• They display as an italic placeholder, so a field that looks empty may already hold a value.
• The saved row's name gains a $$ marker. You don't type it; the importer adds and strips it for you.

The button refuses with "Adding Header & Value is required." if either box is empty.

JSON Body

Custom only. The body to send with the token request — for example the grant_type=client_credentials text a token service asks for. Leave empty otherwise.

Process Repsonce Script Block

Intended for Custom only: a snippet that reshapes the token service's reply before the importer reads the token from it. Do not use this field at present — see section 8, item 2. It is the most dangerous field on the panel, because it can break authentication even when you leave it empty.

Test Aquire Token

Runs this panel's settings exactly as configured and displays the token it managed to obtain, in a REST API Token result.

• It checks credentials only. It does not contact your data address, check the field mapping, or confirm that [Auth-Token] substitution works on the Import tabs.
• The result shows the token in full on screen. Treat it like a password — don't screenshot it or paste it into a ticket.
• Once it passes, use the Import tab's own test action to check the data call separately (section 7).

Proxy Server for Internet access

Used for the data request on the Import tabs. Section 6 gives the exact behaviour, which is not quite what the labels suggest.

3. Choosing a Known REST API Types option

Work down this list and use the first option that fits your source.

3.1 Auth-Token — I already have a token or API key

The simplest option, and the one to try first. You supply the token; the importer puts it in the request.

Leave Auth Endpoint Url, Request Type, Token Property, JSON Body and Process Repsonce Script Block empty — they are not used.

Then on each Import tab:

⚠️ The header name must be Auth-Token, hyphen included. 

Tokens are held for 30 minutes. A token that expires sooner is still reused until the half hour is up, and a token you rotate can take up to 30 minutes to take effect.

3.2 MS Graph-API — I'm reading from Microsoft Graph / Microsoft 365

Use this for Graph. This option holds no Microsoft credentials of its own — it borrows them from the Azure AD connector already configured in ManagementStudio, so you only point at it.

That value is the name of the Azure AD connector to use; if yours is named differently, enter that name. Every other field on the panel stays empty.

Then on each Import tab:

Before saving, make sure that Azure AD connector is configured and working, with the Graph permissions the endpoint needs (including admin consent).

⚠️ If Test Aquire Token fails here with a Microsoft sign-in error mentioning scope, that is a fault in the shared Azure sign-in component — not in anything you have configured. Report it rather than changing your settings. Until it's resolved, Graph sources can be reached through Custom (3.3).

3.3 Custom — some other system, and you can describe its sign-in call

The only option that uses the whole panel. You describe the token request and the importer makes it for you.

3.4 Snow

clientId and clientSecret are two separate rows. Request Type, Token Property and JSON Body are fixed by the option and need no input. Add the secret with Add a Secure Header Value.

Import tab headers then use Authorization = Bearer [Auth-Token] as usual.

3.5 NextThink

Shaped like Snow, but the credentials travel in a Basic authorisation header and a fixed sign-in scope is requested. That scope cannot be changed from this panel — if your NextThink environment needs a different one, raise it with support.

4. A quick worked example

Reading devices from a vendor API that issues a bearer token you can generate yourself.

Connection Options

Import 1

Then: press Test Aquire Token here → the token appears. Then run Import 1's test → a preview file appears. Both good, so enable the importer.

5. Storing secrets properly

Encrypted values are tied to the project they were entered in, so they can't be copied into another project or environment; re-enter them there instead.

6. Proxy Server for Internet access

The labels here are slightly misleading, so treat this table as the reference:

Because off means bypass, an on-premises API and a cloud API need different settings. A cloud API that must leave through your proxy needs the checkbox on, with an address.

Two more points:

• The token request on this panel does not use these settings. So "sign-in service on the internet, data API internal" is a combination this panel can't express — speak to support.
• MS Graph-API follows the proxy settings of the Azure AD connector it points at, not these fields.

7. Testing what you configured

Work through them in that order. A failure in the first is always a credentials problem. A failure only in the second usually means [Auth-Token] is missing from that Import tab's headers.

8. Known limitations

These are current product limitations, not mistakes in your configuration.

1. The Microsoft Graph sign-in may be rejected over scope (3.2). A Microsoft sign-in error mentioning scope is not your configuration.
2. The proxy settings apply to the data request only (section 6).
3. Tokens are held for 30 minutes (3.1).

9. Troubleshooting

Further Support

For further assistance, visit the ManagementStudio Service Desk to search the knowledge base or raise a new support ticket.