|
\[array\]
|
Required. Unnamed array of objects in which each object represents an external document to ingest for indexing.
Data type: Array
```
[
{
"content_pointer": "String",
"document_id": "String",
"principals": {Object},
"properties": {Object}
}
]
```
|
|
\[array\].content\_pointer
|
Identifier for an instance of binary content stored using the [POST /ais/external\_content/storeContent](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/external-content-ingestion-api.md) endpoint. During ingestion, AI Search parses the binary content and adds its searchable content to the indexed record that represents the external document. Parsing removes the stored content object.
**Note:** This identifier should match the **result** response body element returned by the storeContent endpoint.
Data type: String
|
|
\[array\].document\_id
|
Required. Unique identifier for the external document in the external content schema table specified by the **schema\_table\_name** path parameter.
**Note:** When you ingest a document, it overwrites any existing document in the same external content schema table that has the same **document\_id**. If two or more documents in the same ingestion request have the same **document\_id**, the request fails.
Data type: String
|
|
\[array\].principals
|
Object containing key-value pairs that describe the external document's access permissions for externally defined security principals \(users and groups\).
**Note:**
If you omit this parameter for a document, the request succeeds, but AI Search rejects the document with the ingestion feedback message `The principal of the document is missing`.
If this parameter object does not include any key-value pairs that grant access to a document, the request succeeds, but AI Search rejects the document with the ingestion feedback message `The principal of the document is invalid`.
Data type: Object
```
"principals": {
"everyone": Boolean,
"groups.deny": [Array],
"groups.read": [Array],
"none": Boolean,
"users.deny": [Array],
"users.read": [Array]
}
```
Versions supported: Available starting in v2 of the API.
|
|
\[array\].principals.everyone
|
Flag that indicates whether access to the external document is allowed for all users. When this parameter is set to **true**, all ServiceNow AI Platform users can view the indexed record created from the document.
**Note:** If you set both this parameter and **\[array\].principals.none** to **true** for a document, the request succeeds, but AI Search rejects the document with ingestion feedback message `The principal of the document is invalid`. You can only set one of these two parameters to **true** in a request.
Valid values:
- **true**: Allow access to the document for all users. AI Search ignores all **\[array\].principals.groups.\*** and **\[array\].principals.users.\*** parameter settings for the document.
- **false**: Do not allow all users to access the external document. Users can only access the document if **\[array\].principals.none** is set to false and if allowed by the interaction of their user mappings and the **\[array\].principals.groups.\*** and **\[array\].principals.users.\*** parameters.
Data type: Boolean
Default: **true**
Versions supported: Available starting in v2 of the API.
|
|
\[array\].principals.groups.deny
|
Array of strings where each string is the name of an externally defined group that is denied access to the external document. ServiceNow AI Platform users mapped to any of these external groups cannot view the indexed search result record created from the document.
If either **\[array\].principals.everyone** or **\[array\].principals.none** is set to **true**, this parameter has no effect.
This parameter takes precedence over **\[array\].principals.groups.read**. If the same user is mapped to external groups with both read and deny access permissions for a document, AI Search denies that user access to the indexed record.
By default, **\[array\].principals.users.read** takes precedence over this parameter. To reverse this precedence order for an indexed source, see [Change the precedence of user read and group deny permissions for an external content indexed source.](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-administration/defining-access-perms-ext-docs-ais.md).
Data type: Array
Values can be in any format, depending on the names of the externally defined groups specified. Examples include:
```
"groups.deny": [
"hr-admin",
"legal"
]
```
Versions supported: Available starting in v2 of the API.
|
|
\[array\].principals.groups.read
|
Array of strings where each string is the name of an externally defined group that is allowed to access the external document. ServiceNow AI Platform users mapped to any of these external groups can view the indexed search result record created from the document.
If either **\[array\].principals.everyone** or **\[array\].principals.none** is set to **true**, this parameter has no effect.
**\[array\].principals.groups.deny** takes precedence over this parameter. If the same user is mapped to external groups with both read and deny access permissions for a document, AI Search denies that user access to the indexed record.
Data type: Array
Values can be in any format, depending on the names of the externally defined groups specified. Examples include:
```
"groups.read": [
"devops",
"it",
"report-admins"
]
```
Versions supported: Available starting in v2 of the API.
|
|
\[array\].principals.none
|
Boolean option indicating whether access to the external document is denied for all users. When this parameter is set to **true**, only ServiceNow AI Platform users with the ais\_high\_security\_admin elevated privilege role can view the indexed record created from the document.
**Note:** If you set both this parameter and **\[array\].principals.everyone** to **true** for a document, AI Search rejects the document during ingestion with error message `The principal of the document is invalid`. You can only set one of these two parameters to **true** in a request.
Valid values:
- **true**: Deny access to the document for all users except those with the ais\_high\_security\_admin elevated privilege role. AI Search ignores all **\[array\].principals.groups.\*** and **\[array\].principals.users.\*** parameter settings for the document.
- **false**: Do not deny access to the document for all users. Users can access the document if **\[array\].principals.everyone** is set to **true**, or if allowed by the interaction of their user mappings and the **\[array\].principals.groups.read** and **\[array\].principals.users.read** parameters.
Data type: Boolean
Default: **false**
Versions supported: Available starting in v2 of the API.
|
|
\[array\].principals.users.deny
|
Array of strings where each string is the name of an externally defined user that is denied access to the external document. ServiceNow AI Platform users mapped to any of these external users cannot view the indexed search result record created from the document.
If either **\[array\].principals.everyone** or **\[array\].principals.none** is set to **true**, this parameter has no effect.
This parameter takes precedence over **\[array\].principals.users.read**. If the same user is mapped to external users with both read and deny access permissions for a document, AI Search denies that user access to the indexed record.
Data type: Array
Values can be in any format, depending on the names of the externally defined users specified. Examples include:
```
"users.deny": [
"ad\bow-ruggeri",
"abel-tuter@sharepoint"
]
```
Versions supported: Available starting in v2 of the API.
|
|
\[array\].principals.users.read
|
Array of strings where each string is the name of an externally defined user that is allowed to access the external document. ServiceNow AI Platform users mapped to any of these external users can view the indexed search result record created from the document.
If either **\[array\].principals.everyone** or **\[array\].principals.none** is set to **true**, this parameter has no effect.
**\[array\].principals.users.deny** takes precedence over this parameter. If the same user is mapped to external users with both read and deny access permissions for a document, AI Search denies that user access to the indexed record.
By default, this parameter takes precedence over **\[array\].principals.groups.deny**. To reverse this precedence order for an indexed source, see [Change the precedence of user read and group deny permissions for an external content indexed source.](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-administration/defining-access-perms-ext-docs-ais.md).
Data type: Array
Values can be in any format, depending on the names of the externally defined users specified. Examples include:
```
"users.read": [
"ad\abel-tuter",
"beth-anglin@sharepoint"
]
```
Versions supported: Available starting in v2 of the API.
|
|
\[array\].properties
|
Object containing name-value pairs where each pair represents a field name and value to ingest for the document. All field names and values must be specified as strings.
After ingestion, these document field values are accessible through the indexed source defined for the external content schema table specified by the **schema\_table\_name** path parameter. Users can search for these field values in search sources derived from this indexed source.
Data type: Object
Field names can only contain lowercase letters and underscores. Values can include any characters. Value length is limited by the **max\_length** attribute defined for the field in the external content schema table. Examples of field name-value pairs include:
```
"properties": {
"creation_date": "2020-11-03 12:27:43",
"file_size": "10285",
"title": "Introduction",
"url": "file:///myhost/reports/Introduction.pdf"
}
```
|