Chapter 300. ServiceNow Component
Available as of Camel version 2.18
The ServiceNow component provides access to ServiceNow platform through their REST API.
From Camel 2.18.1 the component supports multiple version of ServiceNow platform with default to Helsinki. Supported version are Table 300.1, “API Mapping” and Table 300.2, “API Mapping”
Maven users will need to add the following dependency to their pom.xml for this component:
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-servicenow</artifactId>
<version>${camel-version}</version>
</dependency>300.1. URI format
servicenow://instanceName?[options]
300.2. Options
The ServiceNow component supports 14 options, which are listed below.
| Name | Description | Default | Type |
|---|---|---|---|
| instanceName (advanced) | The ServiceNow instance name | String | |
| configuration (advanced) | The ServiceNow default configuration | ServiceNowConfiguration | |
| apiUrl (producer) | The ServiceNow REST API url | String | |
| userName (security) | ServiceNow user account name | String | |
| password (security) | ServiceNow account password | String | |
| oauthClientId (security) | OAuth2 ClientID | String | |
| oauthClientSecret (security) | OAuth2 ClientSecret | String | |
| oauthTokenUrl (security) | OAuth token Url | String | |
| proxyHost (advanced) | The proxy host name | String | |
| proxyPort (advanced) | The proxy port number | Integer | |
| proxyUserName (security) | Username for proxy authentication | String | |
| proxyPassword (security) | Password for proxy authentication | String | |
| useGlobalSslContext Parameters (security) | Enable usage of global SSL context parameters. | false | boolean |
| resolveProperty Placeholders (advanced) | Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders. | true | boolean |
The ServiceNow endpoint is configured using URI syntax:
servicenow:instanceName
with the following path and query parameters:
300.2.1. Path Parameters (1 parameters):
| Name | Description | Default | Type |
|---|---|---|---|
| instanceName | Required The ServiceNow instance name | String |
300.2.2. Query Parameters (44 parameters):
| Name | Description | Default | Type |
|---|---|---|---|
| display (producer) | Set this parameter to true to return only scorecards where the indicator Display field is selected. Set this parameter to all to return scorecards with any Display field value. This parameter is true by default. | true | String |
| displayValue (producer) | Return the display value (true), actual value (false), or both (all) for reference fields (default: false) | false | String |
| excludeReferenceLink (producer) | True to exclude Table API links for reference fields (default: false) | Boolean | |
| favorites (producer) | Set this parameter to true to return only scorecards that are favorites of the querying user. | Boolean | |
| includeAggregates (producer) | Set this parameter to true to always return all available aggregates for an indicator, including when an aggregate has already been applied. If a value is not specified, this parameter defaults to false and returns no aggregates. | Boolean | |
| includeAvailableAggregates (producer) | Set this parameter to true to return all available aggregates for an indicator when no aggregate has been applied. If a value is not specified, this parameter defaults to false and returns no aggregates. | Boolean | |
| includeAvailableBreakdowns (producer) | Set this parameter to true to return all available breakdowns for an indicator. If a value is not specified, this parameter defaults to false and returns no breakdowns. | Boolean | |
| includeScoreNotes (producer) | Set this parameter to true to return all notes associated with the score. The note element contains the note text as well as the author and timestamp when the note was added. | Boolean | |
| includeScores (producer) | Set this parameter to true to return all scores for a scorecard. If a value is not specified, this parameter defaults to false and returns only the most recent score value. | Boolean | |
| inputDisplayValue (producer) | True to set raw value of input fields (default: false) | Boolean | |
| key (producer) | Set this parameter to true to return only scorecards for key indicators. | Boolean | |
| models (producer) | Defines both request and response models | String | |
| perPage (producer) | Enter the maximum number of scorecards each query can return. By default this value is 10, and the maximum is 100. | 10 | Integer |
| release (producer) | The ServiceNow release to target, default to Helsinki See https://docs.servicenow.com | HELSINKI | ServiceNowRelease |
| requestModels (producer) | Defines the request model | String | |
| resource (producer) | The default resource, can be overridden by header CamelServiceNowResource | String | |
| responseModels (producer) | Defines the response model | String | |
| sortBy (producer) | Specify the value to use when sorting results. By default, queries sort records by value. | String | |
| sortDir (producer) | Specify the sort direction, ascending or descending. By default, queries sort records in descending order. Use sysparm_sortdir=asc to sort in ascending order. | String | |
| suppressAutoSysField (producer) | True to suppress auto generation of system fields (default: false) | Boolean | |
| suppressPaginationHeader (producer) | Set this value to true to remove the Link header from the response. The Link header allows you to request additional pages of data when the number of records matching your query exceeds the query limit | Boolean | |
| table (producer) | The default table, can be overridden by header CamelServiceNowTable | String | |
| target (producer) | Set this parameter to true to return only scorecards that have a target. | Boolean | |
| topLevelOnly (producer) | Gets only those categories whose parent is a catalog. | Boolean | |
| apiVersion (advanced) | The ServiceNow REST API version, default latest | String | |
| dateFormat (advanced) | The date format used for Json serialization/deserialization | yyyy-MM-dd | String |
| dateTimeFormat (advanced) | The date-time format used for Json serialization/deserialization | yyyy-MM-dd HH:mm:ss | String |
| httpClientPolicy (advanced) | To configure http-client | HTTPClientPolicy | |
| mapper (advanced) | Sets Jackson’s ObjectMapper to use for request/reply | ObjectMapper | |
| proxyAuthorizationPolicy (advanced) | To configure proxy authentication | ProxyAuthorization Policy | |
| retrieveTargetRecordOn Import (advanced) | Set this parameter to true to retrieve the target record when using import set api. The import set result is then replaced by the target record | false | Boolean |
| synchronous (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean |
| timeFormat (advanced) | The time format used for Json serialization/deserialization | HH:mm:ss | String |
| proxyHost (proxy) | The proxy host name | String | |
| proxyPort (proxy) | The proxy port number | Integer | |
| apiUrl (security) | The ServiceNow REST API url | String | |
| oauthClientId (security) | OAuth2 ClientID | String | |
| oauthClientSecret (security) | OAuth2 ClientSecret | String | |
| oauthTokenUrl (security) | OAuth token Url | String | |
| password (security) | Required ServiceNow account password, MUST be provided | String | |
| proxyPassword (security) | Password for proxy authentication | String | |
| proxyUserName (security) | Username for proxy authentication | String | |
| sslContextParameters (security) | To configure security using SSLContextParameters. See http://camel.apache.org/camel-configuration-utilities.html | SSLContextParameters | |
| userName (security) | Required ServiceNow user account name, MUST be provided | String |
300.3. Spring Boot Auto-Configuration
The component supports 57 options, which are listed below.
| Name | Description | Default | Type |
|---|---|---|---|
| camel.component.servicenow.api-url | The ServiceNow REST API url | String | |
| camel.component.servicenow.configuration.api-url | The ServiceNow REST API url | String | |
| camel.component.servicenow.configuration.api-version | The ServiceNow REST API version, default latest | String | |
| camel.component.servicenow.configuration.date-format | The date format used for Json serialization/deserialization | yyyy-MM-dd | String |
| camel.component.servicenow.configuration.date-time-format | The date-time format used for Json serialization/deserialization | yyyy-MM-dd HH:mm:ss | String |
| camel.component.servicenow.configuration.display | Set this parameter to true to return only scorecards where the indicator Display field is selected. Set this parameter to all to return scorecards with any Display field value. This parameter is true by default. | true | String |
| camel.component.servicenow.configuration.display-value | Return the display value (true), actual value (false), or both (all) for reference fields (default: false) | false | String |
| camel.component.servicenow.configuration.exclude-reference-link | True to exclude Table API links for reference fields (default: false) | Boolean | |
| camel.component.servicenow.configuration.favorites | Set this parameter to true to return only scorecards that are favorites of the querying user. | Boolean | |
| camel.component.servicenow.configuration.http-client-policy | To configure http-client | HTTPClientPolicy | |
| camel.component.servicenow.configuration.include-aggregates | Set this parameter to true to always return all available aggregates for an indicator, including when an aggregate has already been applied. If a value is not specified, this parameter defaults to false and returns no aggregates. | Boolean | |
| camel.component.servicenow.configuration.include-available-aggregates | Set this parameter to true to return all available aggregates for an indicator when no aggregate has been applied. If a value is not specified, this parameter defaults to false and returns no aggregates. | Boolean | |
| camel.component.servicenow.configuration.include-available-breakdowns | Set this parameter to true to return all available breakdowns for an indicator. If a value is not specified, this parameter defaults to false and returns no breakdowns. | Boolean | |
| camel.component.servicenow.configuration.include-score-notes | Set this parameter to true to return all notes associated with the score. The note element contains the note text as well as the author and timestamp when the note was added. | Boolean | |
| camel.component.servicenow.configuration.include-scores | Set this parameter to true to return all scores for a scorecard. If a value is not specified, this parameter defaults to false and returns only the most recent score value. | Boolean | |
| camel.component.servicenow.configuration.input-display-value | True to set raw value of input fields (default: false) | Boolean | |
| camel.component.servicenow.configuration.key | Set this parameter to true to return only scorecards for key indicators. | Boolean | |
| camel.component.servicenow.configuration.mapper | Sets Jackson’s ObjectMapper to use for request/reply | ObjectMapper | |
| camel.component.servicenow.configuration.models | Defines both request and response models | Map | |
| camel.component.servicenow.configuration.oauth-client-id | OAuth2 ClientID | String | |
| camel.component.servicenow.configuration.oauth-client-secret | OAuth2 ClientSecret | String | |
| camel.component.servicenow.configuration.oauth-token-url | OAuth token Url | String | |
| camel.component.servicenow.configuration.password | ServiceNow account password, MUST be provided | String | |
| camel.component.servicenow.configuration.per-page | Enter the maximum number of scorecards each query can return. By default this value is 10, and the maximum is 100. | 10 | Integer |
| camel.component.servicenow.configuration.proxy-authorization-policy | To configure proxy authentication | ProxyAuthorization Policy | |
| camel.component.servicenow.configuration.proxy-host | The proxy host name | String | |
| camel.component.servicenow.configuration.proxy-password | Password for proxy authentication | String | |
| camel.component.servicenow.configuration.proxy-port | The proxy port number | Integer | |
| camel.component.servicenow.configuration.proxy-user-name | Username for proxy authentication | String | |
| camel.component.servicenow.configuration.release | The ServiceNow release to target, default to Helsinki See https://docs.servicenow.com | ServiceNowRelease | |
| camel.component.servicenow.configuration.request-models | Defines the request model | Map | |
| camel.component.servicenow.configuration.resource | The default resource, can be overridden by header CamelServiceNowResource | String | |
| camel.component.servicenow.configuration.response-models | Defines the response model | Map | |
| camel.component.servicenow.configuration.retrieve-target-record-on-import | Set this parameter to true to retrieve the target record when using import set api. The import set result is then replaced by the target record | false | Boolean |
| camel.component.servicenow.configuration.sort-by | Specify the value to use when sorting results. By default, queries sort records by value. | String | |
| camel.component.servicenow.configuration.sort-dir | Specify the sort direction, ascending or descending. By default, queries sort records in descending order. Use sysparm_sortdir=asc to sort in ascending order. | String | |
| camel.component.servicenow.configuration.ssl-context-parameters | To configure security using SSLContextParameters. See http://camel.apache.org/camel-configuration-utilities.html | SSLContextParameters | |
| camel.component.servicenow.configuration.suppress-auto-sys-field | True to suppress auto generation of system fields (default: false) | Boolean | |
| camel.component.servicenow.configuration.suppress-pagination-header | Set this value to true to remove the Link header from the response. The Link header allows you to request additional pages of data when the number of records matching your query exceeds the query limit | Boolean | |
| camel.component.servicenow.configuration.table | The default table, can be overridden by header CamelServiceNowTable | String | |
| camel.component.servicenow.configuration.target | Set this parameter to true to return only scorecards that have a target. | Boolean | |
| camel.component.servicenow.configuration.time-format | The time format used for Json serialization/deserialization | HH:mm:ss | String |
| camel.component.servicenow.configuration.top-level-only | Gets only those categories whose parent is a catalog. | Boolean | |
| camel.component.servicenow.configuration.user-name | ServiceNow user account name, MUST be provided | String | |
| camel.component.servicenow.enabled | Enable servicenow component | true | Boolean |
| camel.component.servicenow.instance-name | The ServiceNow instance name | String | |
| camel.component.servicenow.oauth-client-id | OAuth2 ClientID | String | |
| camel.component.servicenow.oauth-client-secret | OAuth2 ClientSecret | String | |
| camel.component.servicenow.oauth-token-url | OAuth token Url | String | |
| camel.component.servicenow.password | ServiceNow account password | String | |
| camel.component.servicenow.proxy-host | The proxy host name | String | |
| camel.component.servicenow.proxy-password | Password for proxy authentication | String | |
| camel.component.servicenow.proxy-port | The proxy port number | Integer | |
| camel.component.servicenow.proxy-user-name | Username for proxy authentication | String | |
| camel.component.servicenow.resolve-property-placeholders | Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders. | true | Boolean |
| camel.component.servicenow.use-global-ssl-context-parameters | Enable usage of global SSL context parameters. | false | Boolean |
| camel.component.servicenow.user-name | ServiceNow user account name | String |
300.4. Headers
| Name | Type | ServiceNow API Parameter | Endpoint option | Description |
|---|---|---|---|---|
| CamelServiceNowResource | String | - | - | The resource to access |
| CamelServiceNowAction | String | - | - | The action to perform |
| CamelServiceNowActionSubject | - | - | String | The subject to which the action should be applied |
| CamelServiceNowModel | Class | - | - | The data model |
| CamelServiceNowRequestModel | Class | - | - | The request data model |
| CamelServiceNowResponseModel | Class | - | - | The response data model |
| CamelServiceNowOffsetNext | - | - | - | - |
| CamelServiceNowOffsetPrev | - | - | - | - |
| CamelServiceNowOffsetFirst | - | - | - | - |
| CamelServiceNowOffsetLast | - | - | - | - |
| CamelServiceNowContentType | - | - | - | - |
| CamelServiceNowContentEncoding | - | - | - | - |
| CamelServiceNowContentMeta | - | - | - | - |
| CamelServiceNowSysId | String | sys_id | - | - |
| CamelServiceNowUserSysId | String | user_sysid | - | - |
| CamelServiceNowUserId | String | user_id | - | - |
| CamelServiceNowCartItemId | String | cart_item_id | - | - |
| CamelServiceNowFileName | String | file_name | - | - |
| CamelServiceNowTable | String | table_name | - | - |
| CamelServiceNowTableSysId | String | table_sys_id | - | - |
| CamelServiceNowEncryptionContext | String | encryption_context | - | - |
| CamelServiceNowCategory | String | sysparm_category | - | - |
| CamelServiceNowType | String | sysparm_type | - | - |
| CamelServiceNowCatalog | String | sysparm_catalog | - | - |
| CamelServiceNowQuery | String | sysparm_query | - | - |
| CamelServiceNowDisplayValue | String | sysparm_display_value | displayValue | - |
| CamelServiceNowInputDisplayValue | Boolean | sysparm_input_display_value | inputDisplayValue | - |
| CamelServiceNowExcludeReferenceLink | Boolean | sysparm_exclude_reference_link | excludeReferenceLink | - |
| CamelServiceNowFields | String | sysparm_fields | - | - |
| CamelServiceNowLimit | Integer | sysparm_limit | - | - |
| CamelServiceNowText | String | sysparm_text | - | - |
| CamelServiceNowOffset | Integer | sysparm_offset | - | - |
| CamelServiceNowView | String | sysparm_view | - | - |
| CamelServiceNowSuppressAutoSysField | Boolean | sysparm_suppress_auto_sys_field | suppressAutoSysField | - |
| CamelServiceNowSuppressPaginationHeader | Booleab | sysparm_suppress_pagination_header | suppressPaginationHeader | - |
| CamelServiceNowMinFields | String | sysparm_min_fields | - | - |
| CamelServiceNowMaxFields | String | sysparm_max_fields | - | - |
| CamelServiceNowSumFields | String | sysparm_sum_fields | - | - |
| CamelServiceNowAvgFields | String | sysparm_avg_fields | - | - |
| CamelServiceNowCount | Boolean | sysparm_count | - | - |
| CamelServiceGroupBy | String | sysparm_group_by | - | - |
| CamelServiceOrderBy | String | sysparm_order_by | - | - |
| CamelServiceHaving | String | sysparm_having | - | - |
| CamelServiceNowUUID | String | sysparm_uuid | - | - |
| CamelServiceNowBreakdown | String | sysparm_breakdown | - | - |
| CamelServiceNowIncludeScores | Boolean | sysparm_include_scores | includeScores | - |
| CamelServiceNowIncludeScoreNotes | Boolean | sysparm_include_score_notes | includeScoreNotes | - |
| CamelServiceNowIncludeAggregates | Boolean | sysparm_include_aggregates | includeAggregates | - |
| CamelServiceNowIncludeAvailableBreakdowns | Boolean | sysparm_include_available_breakdowns | includeAvailableBreakdowns | - |
| CamelServiceNowIncludeAvailableAggregates | Boolean | sysparm_include_available_aggregates | includeAvailableAggregates | - |
| CamelServiceNowFavorites | Boolean | sysparm_favorites | favorites | - |
| CamelServiceNowKey | Boolean | sysparm_key | key | - |
| CamelServiceNowTarget | Boolean | sysparm_target | target | - |
| CamelServiceNowDisplay | String | sysparm_display | display | - |
| CamelServiceNowPerPage | Integer | sysparm_per_page | perPage | - |
| CamelServiceNowSortBy | String | sysparm_sortby | sortBy | - |
| CamelServiceNowSortDir | String | sysparm_sortdit | sortDir | - |
| CamelServiceNowContains | String | sysparm_contains | - | - |
| CamelServiceNowTags | String | sysparm_tags | - | - |
| CamelServiceNowPage | String | sysparm_page | - | - |
| CamelServiceNowElementsFilter | String | sysparm_elements_filter | - | - |
| CamelServiceNowBreakdownRelation | String | sysparm_breakdown_relation | - | - |
| CamelServiceNowDataSource | String | sysparm_data_source | - | - |
| CamelServiceNowTopLevelOnly | Boolean | sysparm_top_level_only | topLevelOnly | - |
| CamelServiceNowApiVersion | String | - | - | The REST API version |
| CamelServiceNowResponseMeta | Map | - | - | Meta data provided along with a response |
| CamelServiceNowResource | CamelServiceNowAction | Method | API URI |
|---|---|---|---|
| TABLE | RETRIEVE | GET | /api/now/v1/table/{table_name}/{sys_id} |
| CREATE | POST | /api/now/v1/table/{table_name} | |
| MODIFY | PUT | /api/now/v1/table/{table_name}/{sys_id} | |
| DELETE | DELETE | /api/now/v1/table/{table_name}/{sys_id} | |
| UPDATE | PATCH | /api/now/v1/table/{table_name}/{sys_id} | |
| AGGREGATE | RETRIEVE | GET | /api/now/v1/stats/{table_name} |
| IMPORT | RETRIEVE | GET | /api/now/import/{table_name}/{sys_id} |
| CREATE | POST | /api/now/import/{table_name} |
| CamelServiceNowResource | CamelServiceNowAction | CamelServiceNowActionSubject | Method | API URI |
|---|---|---|---|---|
| TABLE | RETRIEVE | GET | /api/now/v1/table/{table_name}/{sys_id} | |
| CREATE | POST | /api/now/v1/table/{table_name} | ||
| MODIFY | PUT | /api/now/v1/table/{table_name}/{sys_id} | ||
| DELETE | DELETE | /api/now/v1/table/{table_name}/{sys_id} | ||
| UPDATE | PATCH | /api/now/v1/table/{table_name}/{sys_id} | ||
| AGGREGATE | RETRIEVE | GET | /api/now/v1/stats/{table_name} | |
| IMPORT | RETRIEVE | GET | /api/now/import/{table_name}/{sys_id} | |
| CREATE | POST | /api/now/import/{table_name} | ||
| ATTACHMENT | RETRIEVE | GET | /api/now/api/now/attachment/{sys_id} | |
| CONTENT | GET | /api/now/attachment/{sys_id}/file | ||
| UPLOAD | POST | /api/now/api/now/attachment/file | ||
| DELETE | DELETE | /api/now/attachment/{sys_id} | ||
| SCORECARDS | RETRIEVE | PERFORMANCE_ANALYTICS | GET | /api/now/pa/scorecards |
| MISC | RETRIEVE | USER_ROLE_INHERITANCE | GET | /api/global/user_role_inheritance |
| CREATE | IDENTIFY_RECONCILE | POST | /api/now/identifyreconcile | |
| SERVICE_CATALOG | RETRIEVE | GET | /sn_sc/servicecatalog/catalogs/{sys_id} | |
| RETRIEVE | CATEGORIES | GET | /sn_sc/servicecatalog/catalogs/{sys_id}/categories | |
| SERVICE_CATALOG_ITEMS | RETRIEVE | GET | /sn_sc/servicecatalog/items/{sys_id} | |
| RETRIEVE | SUBMIT_GUIDE | POST | /sn_sc/servicecatalog/items/{sys_id}/submit_guide | |
| RETRIEVE | CHECKOUT_GUIDE | POST | /sn_sc/servicecatalog/items/{sys_id}/checkout_guide | |
| CREATE | SUBJECT_CART | POST | /sn_sc/servicecatalog/items/{sys_id}/add_to_cart | |
| CREATE | SUBJECT_PRODUCER | POST | /sn_sc/servicecatalog/items/{sys_id}/submit_producer | |
| SERVICE_CATALOG_CARTS | RETRIEVE | GET | /sn_sc/servicecatalog/cart | |
| RETRIEVE | DELIVERY_ADDRESS | GET | /sn_sc/servicecatalog/cart/delivery_address/{user_id} | |
| RETRIEVE | CHECKOUT | POST | /sn_sc/servicecatalog/cart/checkout | |
| UPDATE | POST | /sn_sc/servicecatalog/cart/{cart_item_id} | ||
| UPDATE | CHECKOUT | POST | /sn_sc/servicecatalog/cart/submit_order | |
| DELETE | DELETE | /sn_sc/servicecatalog/cart/{sys_id}/empty | ||
| SERVICE_CATALOG_CATEGORIES | RETRIEVE | GET | /sn_sc/servicecatalog/categories/{sys_id} |
300.5. Usage examples:
Retrieve 10 Incidents
context.addRoutes(new RouteBuilder() {
public void configure() {
from("direct:servicenow")
.to("servicenow:{{env:SERVICENOW_INSTANCE}}"
+ "?userName={{env:SERVICENOW_USERNAME}}"
+ "&password={{env:SERVICENOW_PASSWORD}}"
+ "&oauthClientId={{env:SERVICENOW_OAUTH2_CLIENT_ID}}"
+ "&oauthClientSecret={{env:SERVICENOW_OAUTH2_CLIENT_SECRET}}"
.to("mock:servicenow");
}
});
FluentProducerTemplate.on(context)
.withHeader(ServiceNowConstants.RESOURCE, "table")
.withHeader(ServiceNowConstants.ACTION, ServiceNowConstants.ACTION_RETRIEVE)
.withHeader(ServiceNowConstants.SYSPARM_LIMIT.getId(), "10")
.withHeader(ServiceNowConstants.TABLE, "incident")
.withHeader(ServiceNowConstants.MODEL, Incident.class)
.to("direct:servicenow")
.send();
