The AI Search External User Mapping API provides endpoints that enable ingestion of user mapping information from external sources into the ServiceNow® AI Search application's index.

AI Search External User Mapping - POST /ais/external_content/user_mapping/import_multiple/{target_table}

Imports a list of external user mappings into an AI Search user mapping table. Each mapping specifies externally defined user and group aliases for a ServiceNow AI Platform user. AI Search uses these aliases to determine which external document search results the user can view.

To learn how AI Search external content security utilizes external user mappings, see External content security for AI Search.

User and group names in external user mappings should match those specified in security access permissions for external documents ingested via the External Content Ingestion API's POST /ais/external_content/ingestDocument/{schema_table_name} endpoint. For more information on ingesting external documents with security access permissions for externally defined users and groups, see External Content Ingestion API.

To view import histories for external user mapping records imported through this endpoint, navigate to AI Search > External Content > User mapping import history. From a history record, you can view the Import Set [sys_import_set] and Multi Import Set [sys_multi_import_set] records for an import task. Use information from these records to verify that your external user mappings were imported correctly.

URL format

Versioned URL: /api/now/{api_version}/ais/external_content/user_mapping/import_multiple/{target_table}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Table 1. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
target_table
The name of the AI Search user mapping table that you want the imported mappings to appear in. For example, x_snc_sharepoint_user_table.
Note: You must create the target AI Search user mapping table via the AI Search > External Content > Create User Mapping module before using this endpoint. If you specify a user mapping table that does not exist, the request fails.

Data type: String
Table 2. Query parameters
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 4. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Content-Type Data format of the request body. Only supports application/json.
Table 5. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 6. Status codes
Status code Description
201 Successful. The request was successfully processed.
400 Bad Request. A bad request type or malformed request was detected.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Example: cURL request

Import externally defined user and group aliases for ServiceNow AI Platform users Beth Anglin and Abel Tuter into an AI Search user mapping table named x_snc_sharepoint_user_table.

curl -X POST 'https://instance.servicenow.com/api/now/v1/ais/external_content/user_mapping/import_multiple/x_snc_sharepoint_user_table' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'username':'password' \
  -d '{
    "records": [
      {
        "mapping_value": "beth.anglin@example.com",
        "external_user": [
          "ad\beth-anglin",
          "beth.anglin@sharepoint"
        ],
        "external_group": [
          "itil",
          "itil-admin",
          "itil-dev"
        ]
      },
      {
        "mapping_value": "abel.tuter@example.com",
        "external_user": [
          "ad\abel-tuter",
          "abel.tuter@sharepoint"
        ],
        "external_group": [
          "hr",
          "hr-admin",
          "hr-dev"
        ]
      }
    ]
  }'

The response shows the sys_ids for the generated Import Set and Multi Import Set records.

{
  "import_set_id": "6e9ddb629d987010f877878bd9f0e9dd",
  "multi_import_set_id": "269ddb629d987010f877878bd9f0e9de"
}

Example: cURL request

Import invalid request containing an empty mapping record.

curl 'https://instance.servicenow.com/api/now/v1/ais/external_content/user_mapping/import_multiple/u_ext_content_user_mapping' \
  --request POST \
  --user 'username':'password' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "records": [
      {
        "mapping_value": "beth.anglin@example.com",
        "external_user": [
          "ad\beth-anglin",
          "beth.anglin@sharepoint"
        ],
        "external_group": [
          "reports",
          "reports-admin",
          "reports-dev"
        ]
      },
      {}
    ]
  }'

The request fails with status 400 and the response indicates the nature of the failure.

{
  "result": "Error in processing the message"
}