Chapter 279. ServiceNow Component

Available as of Camel version 2.18

The ServiceNow component provides access to ServiceNow platform through their REST API.

Note

From Camel 2.18.1 the component supports multiple version of ServiceNow platform with default to Helsinki. Supported version are Table 279.1, “API Mapping” and Table 279.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>

279.1. URI format

    servicenow://instanceName?[options]

279.2. Options

The ServiceNow component supports 14 options which are listed below.

NameDescriptionDefaultType

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:

279.2.1. Path Parameters (1 parameters):

NameDescriptionDefaultType

instanceName

Required The ServiceNow instance name

 

String

279.2.2. Query Parameters (44 parameters):

NameDescriptionDefaultType

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

279.3. Headers

NameTypeServiceNow API ParameterEndpoint optionDescription

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

Table 279.1. API Mapping

CamelServiceNowResourceCamelServiceNowActionMethodAPI 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}

Table 279.2. API Mapping

CamelServiceNowResourceCamelServiceNowActionCamelServiceNowActionSubjectMethodAPI 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}

279.4. 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();