AI Search External User Mapping API

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

Table 3. Request body parameters (XML or JSON)

Name	Description
{object}	Required. Unnamed object. Data type: Object { "records": [Array] }
{object}.records	Required. Array of objects in which each object represents a user mapping to import into the specified target table. Data type: Array "records": [ { "external_group": [Array], "external_user": [Array], "mapping_value": "String" } ]
{object}.records.external_group	Array of strings where each string is the name of an externally defined group to set as an alias for the ServiceNow AI Platform user specified by the {object}.records.mapping_value parameter. Data type: Array Values can be in any format, depending on the names of the externally defined groups selected for the user mapping. Examples include: "external_group": [ "itil", "hr-admin", "report-dev" ]
{object}.records.external_user	Array of strings where each string is the name of an externally defined user to set as an alias for the ServiceNow AI Platform user specified by the {object}.records.mapping_value parameter. Data type: Array Values can be in any format, depending on the names of the externally defined user accounts selected for the user mapping. Examples include: "external_user": [ "beth-anglin", "ad\beth.anglin", "beth-anglin@sharepoint" ]
{object}.records.mapping_value	Email field value that uniquely identifies an existing record. All externally defined user and group aliases in the request are mapped to the ServiceNow AI Platform user with this email address. Note: The API treats this parameter as the unique identifier for the user mapping record. If you import another user mapping with the same mapping_value as an existing user mapping record, the new record overwrites the existing record. Data type: String Table: User [sys_user]

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)

Name	Description
error	Object describing the error encountered during processing of the request. Data type: Object "error": { "detail": "String", "message": "String" }
error.detail	Details of the error encountered during processing of the request. Data type: String
error.message	Message for the error encountered during processing of the request. Data type: String
import_set_id	Sys_id for the new record created in the Import Set [sys_import_set] table by a successful request. Data type: String
multi_import_set_id	Sys_id for the new record created in the Multi Import Set [sys_multi_import_set] table by a successful request. Data type: String
result	Result for an unsuccessful request. Includes a message describing the reason for the request failure. Data type: String
status	Status of an unsuccessful request. Valid values: failure Data type: String

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": "[e-mail]",
        "external_user": [
          "ad\beth-anglin",
          "beth.anglin@sharepoint"
        ],
        "external_group": [
          "itil",
          "itil-admin",
          "itil-dev"
        ]
      },
      {
        "mapping_value": "[e-mail]",
        "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"
}

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": "[e-mail]",
        "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"
}