Skip to content

Commit 6705fe1

Browse files
Clare Zheng (Shanghai Wicresoft Co Ltd)Clare Zheng (Shanghai Wicresoft Co Ltd)
Clare Zheng (Shanghai Wicresoft Co Ltd)
authored and
Clare Zheng (Shanghai Wicresoft Co Ltd)
committed
Add ServiceNow v2 content
1 parent 5d54915 commit 6705fe1

File tree

6 files changed

+265
-28
lines changed

6 files changed

+265
-28
lines changed

‎articles/data-factory/TOC.yml

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -599,7 +599,11 @@ items:
599599
- name: SAP Table
600600
href: connector-sap-table.md
601601
- name: ServiceNow
602-
href: connector-servicenow.md
602+
items:
603+
- name: ServiceNow
604+
- href: connector-servicenow.md
605+
- name: ServiceNow (legacy)
606+
- href: connector-servicenow-legacy.md
603607
- name: SFTP
604608
href: connector-sftp.md
605609
- name: SharePoint Online List

‎articles/data-factory/connector-servicenow-legacy.md

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
---
2+
title: Copy data from ServiceNow
3+
titleSuffix: Azure Data Factory & Azure Synapse
4+
description: Learn how to copy data from ServiceNow to supported sink data stores by using a copy activity in an Azure Data Factory or Synapse Analytics pipeline.
5+
ms.author: jianleishen
6+
author: jianleishen
7+
ms.service: data-factory
8+
ms.subservice: data-movement
9+
ms.topic: conceptual
10+
ms.custom: synapse
11+
ms.date: 10/20/2023
12+
---
13+
14+
# Copy data from ServiceNow using Azure Data Factory or Synapse Analytics
15+
[!INCLUDE[appliesto-adf-asa-md](includes/appliesto-adf-asa-md.md)]
16+
17+
This article outlines how to use the Copy Activity in Azure Data Factory and Synapse Analytics pipelines to copy data from ServiceNow. It builds on the [copy activity overview](copy-activity-overview.md) article that presents a general overview of copy activity.
18+
19+
>[!IMPORTANT]
20+
>The service has released a new ServiceNow connector which provides better native ServiceNow support, refer to [ServiceNow connector](connector-salesforce.md) article on details.
21+
22+
## Supported capabilities
23+
24+
This ServiceNow connector is supported for the following capabilities:
25+
26+
| Supported capabilities|IR |
27+
|---------| --------|
28+
|[Copy activity](copy-activity-overview.md) (source/-)|① ②|
29+
|[Lookup activity](control-flow-lookup-activity.md)|① ②|
30+
31+
*① Azure integration runtime ② Self-hosted integration runtime*
32+
33+
For a list of data stores that are supported as sources/sinks, see the [Supported data stores](connector-overview.md#supported-data-stores) table.
34+
35+
The service provides a built-in driver to enable connectivity. Therefore you don't need to manually install any driver using this connector.
36+
37+
## Getting started
38+
39+
[!INCLUDE [data-factory-v2-connector-get-started](includes/data-factory-v2-connector-get-started.md)]
40+
41+
## Create a linked service to ServiceNow using UI
42+
43+
Use the following steps to create a linked service to ServiceNow in the Azure portal UI.
44+
45+
1. Browse to the Manage tab in your Azure Data Factory or Synapse workspace and select Linked Services, then click New:
46+
47+
# [Azure Data Factory](#tab/data-factory)
48+
49+
:::image type="content" source="media/doc-common-process/new-linked-service.png" alt-text="Create a new linked service with Azure Data Factory UI.":::
50+
51+
# [Azure Synapse](#tab/synapse-analytics)
52+
53+
:::image type="content" source="media/doc-common-process/new-linked-service-synapse.png" alt-text="Create a new linked service with Azure Synapse UI.":::
54+
55+
2. Search for ServiceNow and select the ServiceNow connector.
56+
57+
:::image type="content" source="media/connector-servicenow-legacy/servicenow-legacy-connector.png" alt-text="Select the ServiceNow connector.":::
58+
59+
1. Configure the service details, test the connection, and create the new linked service.
60+
61+
:::image type="content" source="media/connector-servicenow-legacy/configure-servicenow-legacy-linked-service.png" alt-text="Configure a linked service to ServiceNow.":::
62+
63+
## Connector configuration details
64+
65+
The following sections provide details about properties that are used to define Data Factory entities specific to ServiceNow connector.
66+
67+
## Linked service properties
68+
69+
The following properties are supported for ServiceNow linked service:
70+
71+
| Property | Description | Required |
72+
|:--- |:--- |:--- |
73+
| type | The type property must be set to: **ServiceNow** | Yes |
74+
| endpoint | The endpoint of the ServiceNow server (`http://<instance>.service-now.com`). | Yes |
75+
| authenticationType | The authentication type to use. <br/>Allowed values are: **Basic**, **OAuth2** | Yes |
76+
| username | The user name used to connect to the ServiceNow server for Basic and OAuth2 authentication. | Yes |
77+
| password | The password corresponding to the user name for Basic and OAuth2 authentication. Mark this field as a SecureString to store it securely, or [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). | Yes |
78+
| clientId | The client ID for OAuth2 authentication. | No |
79+
| clientSecret | The client secret for OAuth2 authentication. Mark this field as a SecureString to store it securely, or [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). | No |
80+
| useEncryptedEndpoints | Specifies whether the data source endpoints are encrypted using HTTPS. The default value is true. | No |
81+
| useHostVerification | Specifies whether to require the host name in the server's certificate to match the host name of the server when connecting over TLS. The default value is true. | No |
82+
| usePeerVerification | Specifies whether to verify the identity of the server when connecting over TLS. The default value is true. | No |
83+
84+
**Example:**
85+
86+
```json
87+
{
88+
"name": "ServiceNowLinkedService",
89+
"properties": {
90+
"type": "ServiceNow",
91+
"typeProperties": {
92+
"endpoint" : "http://<instance>.service-now.com",
93+
"authenticationType" : "Basic",
94+
"username" : "<username>",
95+
"password": {
96+
"type": "SecureString",
97+
"value": "<password>"
98+
}
99+
}
100+
}
101+
}
102+
```
103+
104+
## Dataset properties
105+
106+
For a full list of sections and properties available for defining datasets, see the [datasets](concepts-datasets-linked-services.md) article. This section provides a list of properties supported by ServiceNow dataset.
107+
108+
To copy data from ServiceNow, set the type property of the dataset to **ServiceNowObject**. The following properties are supported:
109+
110+
| Property | Description | Required |
111+
|:--- |:--- |:--- |
112+
| type | The type property of the dataset must be set to: **ServiceNowObject** | Yes |
113+
| tableName | Name of the table. | No (if "query" in activity source is specified) |
114+
115+
**Example**
116+
117+
```json
118+
{
119+
"name": "ServiceNowDataset",
120+
"properties": {
121+
"type": "ServiceNowObject",
122+
"typeProperties": {},
123+
"schema": [],
124+
"linkedServiceName": {
125+
"referenceName": "<ServiceNow linked service name>",
126+
"type": "LinkedServiceReference"
127+
}
128+
}
129+
}
130+
```
131+
132+
## Copy activity properties
133+
134+
For a full list of sections and properties available for defining activities, see the [Pipelines](concepts-pipelines-activities.md) article. This section provides a list of properties supported by ServiceNow source.
135+
136+
### ServiceNow as source
137+
138+
To copy data from ServiceNow, set the source type in the copy activity to **ServiceNowSource**. The following properties are supported in the copy activity **source** section:
139+
140+
| Property | Description | Required |
141+
|:--- |:--- |:--- |
142+
| type | The type property of the copy activity source must be set to: **ServiceNowSource** | Yes |
143+
| query | Use the custom SQL query to read data. For example: `"SELECT * FROM Actual.alm_asset"`. | No (if "tableName" in dataset is specified) |
144+
145+
Note the following when specifying the schema and column for ServiceNow in query, and **refer to [Performance tips](#performance-tips) on copy performance implication**.
146+
147+
- **Schema:** specify the schema as `Actual` or `Display` in the ServiceNow query, which you can look at it as the parameter of `sysparm_display_value` as true or false when calling [ServiceNow REST APIs](https://developer.servicenow.com/app.do#!/rest_api_doc?v=jakarta&id=r_AggregateAPI-GET). 
148+
- **Column:** the column name for actual value under `Actual` schema is `[column name]_value`, while for display value under `Display` schema is `[column name]_display_value`. Note the column name need map to the schema being used in the query.
149+
150+
**Sample query:**
151+
`SELECT col_value FROM Actual.alm_asset`
152+
OR 
153+
`SELECT col_display_value FROM Display.alm_asset`
154+
155+
**Example:**
156+
157+
```json
158+
"activities":[
159+
{
160+
"name": "CopyFromServiceNow",
161+
"type": "Copy",
162+
"inputs": [
163+
{
164+
"referenceName": "<ServiceNow input dataset name>",
165+
"type": "DatasetReference"
166+
}
167+
],
168+
"outputs": [
169+
{
170+
"referenceName": "<output dataset name>",
171+
"type": "DatasetReference"
172+
}
173+
],
174+
"typeProperties": {
175+
"source": {
176+
"type": "ServiceNowSource",
177+
"query": "SELECT * FROM Actual.alm_asset"
178+
},
179+
"sink": {
180+
"type": "<sink type>"
181+
}
182+
}
183+
}
184+
]
185+
```
186+
## Performance tips
187+
188+
### Schema to use
189+
190+
ServiceNow has 2 different schemas, one is **"Actual"** which returns actual data, the other is **"Display"** which returns the display values of data.
191+
192+
If you have a filter in your query, use "Actual" schema which has better copy performance. When querying against "Actual" schema, ServiceNow natively support filter when fetching the data to only return the filtered resultset, whereas when querying "Display" schema, ADF retrieve all the data and apply filter internally.
193+
194+
### Index
195+
196+
ServiceNow table index can help improve query performance, refer to [Create a table index](https://docs.servicenow.com/bundle/quebec-platform-administration/page/administer/table-administration/task/t_CreateCustomIndex.html).
197+
198+
## Lookup activity properties
199+
200+
To learn details about the properties, check [Lookup activity](control-flow-lookup-activity.md).
201+
202+
203+
## Related content
204+
For a list of data stores supported as sources and sinks by the copy activity, see [supported data stores](copy-activity-overview.md#supported-data-stores-and-formats).

‎articles/data-factory/connector-servicenow.md

Lines changed: 56 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,19 @@ ms.service: data-factory
88
ms.subservice: data-movement
99
ms.topic: conceptual
1010
ms.custom: synapse
11-
ms.date: 10/20/2023
11+
ms.date: 04/11/2024
1212
---
1313

1414
# Copy data from ServiceNow using Azure Data Factory or Synapse Analytics
15+
1516
[!INCLUDE[appliesto-adf-asa-md](includes/appliesto-adf-asa-md.md)]
1617

1718
This article outlines how to use the Copy Activity in Azure Data Factory and Synapse Analytics pipelines to copy data from ServiceNow. It builds on the [copy activity overview](copy-activity-overview.md) article that presents a general overview of copy activity.
1819

20+
>[!IMPORTANT]
21+
>The new ServiceNow connector provides improved native ServiceNow support. If you are using the legacy ServiceNow connector in your solution, supported as-is for backward compatibility only, refer to [ServiceNow connector (legacy)](connector-servicenow-legacy.md) article.
22+
23+
1924
## Supported capabilities
2025

2126
This ServiceNow connector is supported for the following capabilities:
@@ -29,7 +34,7 @@ This ServiceNow connector is supported for the following capabilities:
2934

3035
For a list of data stores that are supported as sources/sinks, see the [Supported data stores](connector-overview.md#supported-data-stores) table.
3136

32-
The service provides a built-in driver to enable connectivity. Therefore you don't need to manually install any driver using this connector.
37+
The service provides a built-in driver to enable connectivity. Therefore you don't need to manually install any driver using this connector.
3338

3439
## Getting started
3540

@@ -67,24 +72,22 @@ The following properties are supported for ServiceNow linked service:
6772

6873
| Property | Description | Required |
6974
|:--- |:--- |:--- |
70-
| type | The type property must be set to: **ServiceNow** | Yes |
75+
| type | The type property must be set to: **ServiceNowV2** | Yes |
7176
| endpoint | The endpoint of the ServiceNow server (`http://<instance>.service-now.com`). | Yes |
7277
| authenticationType | The authentication type to use. <br/>Allowed values are: **Basic**, **OAuth2** | Yes |
7378
| username | The user name used to connect to the ServiceNow server for Basic and OAuth2 authentication. | Yes |
7479
| password | The password corresponding to the user name for Basic and OAuth2 authentication. Mark this field as a SecureString to store it securely, or [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). | Yes |
75-
| clientId | The client ID for OAuth2 authentication. | No |
76-
| clientSecret | The client secret for OAuth2 authentication. Mark this field as a SecureString to store it securely, or [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). | No |
77-
| useEncryptedEndpoints | Specifies whether the data source endpoints are encrypted using HTTPS. The default value is true. | No |
78-
| useHostVerification | Specifies whether to require the host name in the server's certificate to match the host name of the server when connecting over TLS. The default value is true. | No |
79-
| usePeerVerification | Specifies whether to verify the identity of the server when connecting over TLS. The default value is true. | No |
80+
| clientId | The client ID for OAuth2 authentication. | Yes for OAuth authentication|
81+
| clientSecret | The client secret for OAuth2 authentication. Mark this field as a SecureString to store it securely, or [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). | Yes for OAuth authentication |
82+
| grantType | Specifies the type of OAuth2.0 flow that the client app uses to access token. The default value is password.| Yes for OAuth authentication |
8083

8184
**Example:**
8285

8386
```json
8487
{
8588
"name": "ServiceNowLinkedService",
8689
"properties": {
87-
"type": "ServiceNow",
90+
"type": "ServiceNowV2",
8891
"typeProperties": {
8992
"endpoint" : "http://<instance>.service-now.com",
9093
"authenticationType" : "Basic",
@@ -102,20 +105,20 @@ The following properties are supported for ServiceNow linked service:
102105

103106
For a full list of sections and properties available for defining datasets, see the [datasets](concepts-datasets-linked-services.md) article. This section provides a list of properties supported by ServiceNow dataset.
104107

105-
To copy data from ServiceNow, set the type property of the dataset to **ServiceNowObject**. The following properties are supported:
108+
To copy data from ServiceNow, set the type property of the dataset to **ServiceNowV2Object**. The following properties are supported:
106109

107110
| Property | Description | Required |
108111
|:--- |:--- |:--- |
109-
| type | The type property of the dataset must be set to: **ServiceNowObject** | Yes |
110-
| tableName | Name of the table. | No (if "query" in activity source is specified) |
112+
| type | The type property of the dataset must be set to: **ServiceNowV2Object** | Yes |
113+
| tableName | Name of the table. | No (if "expression" in activity source is specified) |
111114

112115
**Example**
113116

114117
```json
115118
{
116119
"name": "ServiceNowDataset",
117120
"properties": {
118-
"type": "ServiceNowObject",
121+
"type": "ServiceNowV2Object",
119122
"typeProperties": {},
120123
"schema": [],
121124
"linkedServiceName": {
@@ -132,27 +135,25 @@ For a full list of sections and properties available for defining activities, se
132135

133136
### ServiceNow as source
134137

135-
To copy data from ServiceNow, set the source type in the copy activity to **ServiceNowSource**. The following properties are supported in the copy activity **source** section:
138+
To copy data from ServiceNow, set the source type in the copy activity to **ServiceNowV2Source**. The following properties are supported in the copy activity **source** section:
136139

137140
| Property | Description | Required |
138141
|:--- |:--- |:--- |
139-
| type | The type property of the copy activity source must be set to: **ServiceNowSource** | Yes |
140-
| query | Use the custom SQL query to read data. For example: `"SELECT * FROM Actual.alm_asset"`. | No (if "tableName" in dataset is specified) |
142+
| type | The type property of the copy activity source must be set to: **ServiceNowV2Source** | Yes |
143+
| expression| Use the expression to read data. You can configure the expression in **Query builder**. | No (if "tableName" in dataset is specified) |
144+
| *Under `expression`* | | |
145+
| type | The expression type. Values can be Constant (default), Unary, Binary, and Field. | No |
146+
| value | The constant value. | Required when the expression type is Constant or Field |
147+
| operators | The operator value. For more information about available operators, see [Supported operators](#supported-operators).| Required when the expression type is Unary or Binary |
148+
| operands | List of expressions on which operator is applied.| Required when the expression type is Unary or Binary |
141149

142-
Note the following when specifying the schema and column for ServiceNow in query, and **refer to [Performance tips](#performance-tips) on copy performance implication**.
150+
**Query builder** has the same usage as the condition builder in ServiceNow. For instructions on how to use it, see this [article](https://docs.servicenow.com/bundle/vancouver-platform-user-interface/page/use/common-ui-elements/concept/c_ConditionBuilder.html).
143151

144-
- **Schema:** specify the schema as `Actual` or `Display` in the ServiceNow query, which you can look at it as the parameter of `sysparm_display_value` as true or false when calling [ServiceNow REST APIs](https://developer.servicenow.com/app.do#!/rest_api_doc?v=jakarta&id=r_AggregateAPI-GET). 
145-
- **Column:** the column name for actual value under `Actual` schema is `[column name]_value`, while for display value under `Display` schema is `[column name]_display_value`. Note the column name need map to the schema being used in the query.
146-
147-
**Sample query:**
148-
`SELECT col_value FROM Actual.alm_asset`
149-
OR 
150-
`SELECT col_display_value FROM Display.alm_asset`
151152

152153
**Example:**
153154

154155
```json
155-
"activities":[
156+
"activities": [
156157
{
157158
"name": "CopyFromServiceNow",
158159
"type": "Copy",
@@ -170,8 +171,7 @@ OR 
170171
],
171172
"typeProperties": {
172173
"source": {
173-
"type": "ServiceNowSource",
174-
"query": "SELECT * FROM Actual.alm_asset"
174+
"type": "ServiceNowV2Source",
175175
},
176176
"sink": {
177177
"type": "<sink type>"
@@ -180,6 +180,28 @@ OR 
180180
}
181181
]
182182
```
183+
184+
#### Supported operators
185+
186+
The supported operators in **Query builder** are shown in the table below:
187+
188+
| Operator name | Unary/Binary| Values required |
189+
|:--- |:--- |:--- |
190+
| is | Binary | low |
191+
| isnot | Binary | low |
192+
| contains | Binary | low |
193+
| starts with | Binary | low |
194+
| ends with | Binary | low |
195+
| is empty | Unary | NIL |
196+
| is not empty | Unary | NIL |
197+
| before | Binary | Low |
198+
| after | Binary | Low |
199+
| does not contain | Binary | low |
200+
| greater than | Binary | low |
201+
| less than | Binary | low |
202+
| is anything | Unary | NIL |
203+
| between | Binary | Low and High |
204+
183205
## Performance tips
184206

185207
### Schema to use
@@ -196,6 +218,13 @@ ServiceNow table index can help improve query performance, refer to [Create a ta
196218

197219
To learn details about the properties, check [Lookup activity](control-flow-lookup-activity.md).
198220

221+
## Upgrade your ServiceNow linked service
222+
223+
Here are the steps that help you to upgrade your ServiceNow linked service:
224+
225+
1. Create a new linked service by referring to [Linked service properties](linked-service-properties).
226+
2. **Query** in source is changed to **Query builder**, which has the same usage as the condition builder in ServiceNow. Learn how to configure it referring to [ServiceNow as source](#servicenow-as-source) and [Condition builder](https://docs.servicenow.com/bundle/vancouver-platform-user-interface/page/use/common-ui-elements/concept/c_ConditionBuilder.html).
227+
199228

200229
## Related content
201230
For a list of data stores supported as sources and sinks by the copy activity, see [supported data stores](copy-activity-overview.md#supported-data-stores-and-formats).

‎articles/data-factory/media/connector-servicenow-legacy/configure-servicenow-legacy-linked-service.png

37.1 KB
Loading

‎articles/data-factory/media/connector-servicenow-legacy/servicenow-legacy-connector.png

13.6 KB
Loading

‎articles/data-factory/media/connector-servicenow/configure-servicenow-linked-service.png

-5.39 KB
Loading

0 commit comments

Comments
 (0)