ServiceNow Component

Since Camel 2.18

Only producer is supported

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

The component supports multiple version of ServiceNow platform with default to Helsinki. Supported version are API Mapping and 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>

URI format

    servicenow://instanceName?[options]

Options

The ServiceNow component supports 16 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

basicPropertyBinding (advanced)

Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities

false

boolean

lazyStartProducer (producer)

Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.

false

boolean

bridgeErrorHandler (consumer)

Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored.

false

boolean

The ServiceNow endpoint is configured using URI syntax:

servicenow:instanceName

with the following path and query parameters:

Path Parameters (1 parameters):

Name Description Default Type

instanceName

Required The ServiceNow instance name

String

Query Parameters (46 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

lazyStartProducer (producer)

Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.

false

boolean

models (producer)

Defines both request and response models

Map

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

Map

resource (producer)

The default resource, can be overridden by header CamelServiceNowResource

String

responseModels (producer)

Defines the response model

Map

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

basicPropertyBinding (advanced)

Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities

false

boolean

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

ProxyAuthorizationPolicy

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

Spring Boot Auto-Configuration

When using Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

<dependency>
  <groupId>org.apache.camel.springboot</groupId>
  <artifactId>camel-servicenow-starter</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>

The component supports 59 options, which are listed below.

Name Description Default Type

camel.component.servicenow.api-url

The ServiceNow REST API url

String

camel.component.servicenow.basic-property-binding

Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities

false

Boolean

camel.component.servicenow.bridge-error-handler

Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored.

false

Boolean

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

The date-time format used for Json serialization/deserialization

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

ProxyAuthorizationPolicy

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.lazy-start-producer

Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.

false

Boolean

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.use-global-ssl-context-parameters

Enable usage of global SSL context parameters.

false

Boolean

camel.component.servicenow.user-name

ServiceNow user account name

String

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

Table 1. API Mapping
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}

Table 2. API Mapping
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}

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