Skip to content

Commit

Permalink
Merge pull request #11 from kesavany/master
Browse files Browse the repository at this point in the history 
 Fix to support EI-6.5.0
  • Loading branch information
@keerthu
keerthu authored May 13, 2019
2 parents cec97c9 + 84c5a29 commit 175cb29
Show file tree
Hide file tree
Showing 28 changed files with 2,766 additions and 196 deletions.
30 changes: 25 additions & 5 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,32 @@
# Ignore everything in this directory
target
.classpath
.settings
.project
*.iml
*.iws
*.ipr
.idea
*.class

# Mobile Tools for Java (J2ME)
.mtj.tmp/

# Package Files #
*.jar
*.war
*.ear

# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
hs_err_pid*
# ignore Intellij-IDEA files
*.iml
*.ipr
*.iws
*.classpath
*.settings
*.project
*.idea
.DS_Store

# ignore logs
*.log

# ignore target directories
target/
*.*~
37 changes: 30 additions & 7 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,36 @@
###ServiceNow ESB Connector
### ServiceNow WSO2 EI Connector

The ServiceNow connector allows you to access the ServiceNow REST API through the WSO2 ESB. ServiceNow is a software platform that supports IT service management and automates common business processes.
The ServiceNow [connector](https://docs.wso2.com/display/EI650/Working+with+Connectors) allows you to access the [ServiceNow REST API](https://developer.servicenow.com/app.do#!/rest_api_doc?v=madrid&id=c_TableAPI) through WSO2 EI. ServiceNow is a software platform that supports IT service management and automates common business processes. This software as a service (SaaS) platform contains a number of modular applications that can vary by instance and user.
## Compatibility

###Build
| Connector version | Supported ServiceNow API version | Supported WSO2 ESB/EI version |
| ------------- | ------------- | ------------- |
| [1.0.2](https://github.com/wso2-extensions/esb-connector-servicenow/tree/org.wso2.carbon.connector.servicenow-1.0.2) | v32.0 | EI 6.5.0 |
| [1.0.1](https://github.com/wso2-extensions/esb-connector-servicenow/tree/org.wso2.carbon.connector.servicenow-1.0.1) | v32.0 | ESB 4.9.0, 5.0.0 |

mvn clean install
## Getting started

###How You Can Contribute
#### Download and install the connector

You can create a third party connector and publish in WSO2 Connector Store.
1. Download the connector from the [WSO2 Store](https://store.wso2.com/store/assets/esbconnector/details/74999163-6706-41f6-a564-61479b99918f) by clicking the Download Connector button.
2. Then you can follow this [Documentation](https://docs.wso2.com/display/EI650/Working+with+Connectors+via+the+Management+Console) to add and enable the connector via the Management Console in your EI instance.
3. For more information on using connectors and their operations in your EI configurations, see [Using a Connector](https://docs.wso2.com/display/EI650/Using+a+Connector).
4. If you want to work with connectors via EI tooling, see [Working with Connectors via Tooling](https://docs.wso2.com/display/EI650/Working+with+Connectors+via+Tooling).

https://docs.wso2.com/display/ESBCONNECTORS/Creating+a+Third+Party+Connector+and+Publishing+in+WSO2+Connector+Store
#### Configuring the connector operations

To get started with ServiceNow connector and their operations, see [Configuring ServiceNow Operations](docs/config.md).


## Building From the Source

Follow the steps given below to build the ServiceNow connector from the source code:

1. Get a clone or download the source from [Github](https://github.com/wso2-extensions/esb-connector-servicenow).
2. Run the following Maven command from the `esb-connector-servicenow` directory: `mvn clean install`.
3. The ServiceNow connector zip file is created in the `esb-connector-servicenow/target` directory

## How You Can Contribute

As an open source project, WSO2 extensions welcome contributions from the community.
Check the [issue tracker](https://github.com/wso2-extensions/esb-connector-servicenow/issues) for open issues that interest you. We look forward to receiving your contributions.
141 changes: 141 additions & 0 deletions docs/aggregate.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
# Working with Aggregate API in ServiceNow

The getAggregateRecord operation Allow to compute aggregate statistics about existing table and column data.

**getAggregateRecord**
```xml
<servicenow.getAggregateRecord>
<tableName>{$ctx:tableName}</tableName>
<sysparmAvgFields>{$ctx:sysparmAvgFields}</sysparmAvgFields>
<sysparmMinFields>{$ctx:sysparmMinFields}</sysparmMinFields>
<sysparmMaxFields>{$ctx:sysparmMaxFields}</sysparmMaxFields>
<sysparmCount>{$ctx:sysparmCount}</sysparmCount>
<sysparmSumFields>{$ctx:sysparmSumFields}</sysparmSumFields>
</servicenow.getAggregateRecord>
```

**Properties**
* tableName: Name of the table you want to retrieve a record.
* sysparmAvgFields: A comma-separated list of fields for which to calculate the average value.
* sysparmMinFields: A comma-separated list of fields for which to calculate the minimum value.
* sysparmMaxFields: A comma-separated list of fields for which to calculate the maximum value.
* sysparmCount: You can set this parameter to true for the number of records returned by the query.
* sysparmSumFields: A comma-separated list of fields for which to calculate the sum of the values.

**Sample request**

Following is a sample request that can be handled by the getAggregateRecord operation.

```json
{
"serviceNowInstanceURL":"https://dev17686.service-now.com",
"username":"admin",
"password":"12345",
"tableName":"incident",
"sysparmAvgFields":"category,active",
"sysparmMinFields":"number",
"sysparmMaxFields":"number",
"sysparmCount":"true",
"sysparmSumFields":"priority"
}
```
**Sample response**

Given below is a sample response for the getAggregateRecord operation.

```json
{
"result":{
"stats":{
"count":"89"
}
}
}
```

**Related ServiceNow documentation**

https://developer.servicenow.com/app.do#!/rest_api_doc?v=jakarta&id=r_AggregateAPI-GET

### Sample configuration

Following example illustrates how to connect to ServiceNow with the init operation and getAggregateRecord operation.

1. Create a sample proxy as below :

```xml
<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse"
name="getAggregateRecord"
transports="https,http"
statistics="disable"
trace="disable"
startOnLoad="true">
<target>
<inSequence>
<property name="serviceNowInstanceURL" expression="json-eval($.serviceNowInstanceURL)"/>
<property name="username" expression="json-eval($.username)"/>
<property name="password" expression="json-eval($.password)"/>
<property name="tableName" expression="json-eval($.tableName)"/>
<property name="sysparmAvgFields" expression="json-eval($.sysparmAvgFields)"/>
<property name="sysparmMinFields" expression="json-eval($.sysparmMinFields)"/>
<property name="sysparmMaxFields" expression="json-eval($.sysparmMaxFields)"/>
<property name="sysparmCount" expression="json-eval($.sysparmCount)"/>
<property name="sysparmSumFields" expression="json-eval($.sysparmSumFields)"/>
<servicenow.init>
<serviceNowInstanceURL>{$ctx:serviceNowInstanceURL}</serviceNowInstanceURL>
<username>{$ctx:username}</username>
<password>{$ctx:password}</password>
</servicenow.init>
<servicenow.getAggregateRecord>
<tableName>{$ctx:tableName}</tableName>
<sysparmAvgFields>{$ctx:sysparmAvgFields}</sysparmAvgFields>
<sysparmMinFields>{$ctx:sysparmMinFields}</sysparmMinFields>
<sysparmMaxFields>{$ctx:sysparmMaxFields}</sysparmMaxFields>
<sysparmCount>{$ctx:sysparmCount}</sysparmCount>
<sysparmSumFields>{$ctx:sysparmSumFields}</sysparmSumFields>
</servicenow.getAggregateRecord>
<respond/>
</inSequence>
<outSequence>
<log/>
<send/>
</outSequence>
</target>
<description/>
</proxy>
```

2. Create a JSON file named getAggregateRecord.json and add the configurations given below:

```json
{
"serviceNowInstanceURL":"https://dev17686.service-now.com",
"username":"admin",
"password":"12345",
"tableName":"incident",
"sysparmAvgFields":"category,active",
"sysparmMinFields":"number",
"sysparmMaxFields":"number",
"sysparmCount":"true",
"sysparmSumFields":"priority"
}
```
3. Replace the credentials with your values.

4. Execute the following curl command:

```bash
curl http://localhost:8280/services/getAggregateRecord -H "Content-Type: application/json" -d @getAggregateRecord.json
```
5. ServiceNow returns a JSON response similar to the one shown below:

```json
{
"result":{
"stats":{
"count":"89"
}
}
}
```
74 changes: 74 additions & 0 deletions docs/config.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Configuring Salesforce REST Operations

[[Prerequisites]](#Prerequisites) [[Initializing the connector]](#initializing-the-connector)

## Prerequisites

To use the ServiceNow connector, add the <servicenow.init> element in your configuration before carrying out any other ServiceNow operations.

The ServiceNow API requires all requests to be authenticated as a user. User has to create a own instance with his user credentials. When u create a account in ServiceNow Developer page then you are enable to create your own instance. For more information, see https://developer.servicenow.com/app.do#!/home

### Obtaining user credentials

* **Create a ServiceNow instance using serviceNow developer site and derive the username and password**

1. Using the URL "https://developer.servicenow.com/app.do#!/home" register a ServiceNow account.
2. Login to the created Service-Now account and go to Manage >> Instance and request an instance.
3. Then you will get a username and password for your instance with instance URL. you can change your password by going Action >> Reset admin password.
4. In your instance you will get three types of APIs and some pre defined tables.
### Importing the ServiceNow Certificate

Before you start configuring the connector, import the ServiceNow certificate to your EI client keystore.

* Follow the steps below to import the ServiceNow certificate into the EI client keystore:

1. To view the certificate, log in to your ServiceNow account using your browser (e.g., https://dev62519.service-now.com/), and click the lock on the address bar.
2. Export the certificate to the file system.
3. Import the certificate to the EI client keystore using either the following command or the EI Management Console:
```
keytool -importcert -file <certificate file> -keystore <EI>/repository/resources/security/client-truststore.jks -alias "ServiceNow"
```
4. Restart the server and deploy the ServiceNow configuration.

## Initializing the connector

Add the following <servicenow.init> method in your configuration:

#### init
```xml
<servicenow.init>
<serviceNowInstanceURL>{$ctx:serviceNowInstanceURL}</serviceNowInstanceURL>
<username>{$ctx:username}</username>
<password>{$ctx:password}</password>
</servicenow.init>
```
**Properties**
* serviceNowInstanceURL: The base endpoint URL of the ServiceNow API.
* username : The user Name of the own instance.
* password : The Password of the own instance.

**Sample Request**

Following is a sample REST request that can be handled by the init operation.

```json
{
"serviceNowInstanceURL":"https://dev17686.service-now.com",
"username":"admin",
"password":"12345"
}
```

**Related documentation**

http://wiki.servicenow.com/index.php?title=REST_API#gsc.tab=0

Now that you have connected to ServiceNow, use the information in the following topics to perform various operations with the connector. Also, see [Configuring the ServiceNow Connector Fault Handler Sequence](fault_handler_sequence.md).

[Working with Aggregate API in ServiceNow](aggregate.md)

[Working with Import Set API in ServiceNow](import_set.md)

[Working with Table API in ServiceNow](table.md)
92 changes: 92 additions & 0 deletions docs/fault_handler_sequence.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# Configuring the ServiceNow Fault Handler Sequence

Following is a sample proxy service and fault handler sequence that you can use as a starting point for handling faults when integrating with ServiceNow. You can customize this sample based on your requirement.

**Sample Proxy**
```xml
<proxy xmlns="http://ws.apache.org/ns/synapse" name="ServiceNow_sampleProxy" transports="https,http" statistics="disable" trace="disable" startOnLoad="true">
<target>
<inSequence onError="faultHandlerSeq">
<init>
</init>
<filter source="$axis2:HTTP_SC" regex="^[^2][0-9][0-9]">
<then>
<switch source="$axis2:HTTP_SC">
<case regex="401">
<!--Fill with your Error code value and expression-->
<property name="ERROR_CODE" value=""/>
<property name="ERROR_MESSAGE" value | expression />
</case>
<case regex="422">
<property name="ERROR_CODE" value=""/>
<property name="ERROR_MESSAGE" value | expression/>
</case>
<case regex="404">
<property name="ERROR_CODE" value=""/>
<property name="ERROR_MESSAGE" value | expression/>
</case>
<case regex="403">
<property name="ERROR_CODE" value=""/>
<property name="ERROR_MESSAGE" value | expression/>
</case>
<case regex="400">
<property name="ERROR_CODE" value=""/>
<property name="ERROR_MESSAGE" value | expression/>
</case>
<case regex="500">
<property name="ERROR_CODE" value=""/>
<property name="ERROR_MESSAGE" value | expression/>
</case>
<default>
<property name="ERROR_CODE" expression="$axis2:HTTP_SC"/>
<property name="ERROR_MESSAGE" value | expression/>
</default>
</switch>
<sequence key="faultHandlerSeq" />
</then>
</filter>
<respond />
</inSequence>
<outSequence>
<send></send>
</outSequence>
</target>
</proxy>
```
**faultHandlerSeq**
```xml
<sequence xmlns="http://ws.apache.org/ns/synapse" name="faultHandlerSeq">
<property xmlns:ns="http://org.apache.synapse/xsd" name="contentTypeValue" expression="get-property('transport', 'Content-Type')"></property>
<filter xmlns:ns="http://org.apache.synapse/xsd" xpath="get-property('contentTypeValue') = 'application/json' or get-property('contentTypeValue') = 'text/json'">
<then>
<payloadFactory media-type="json">
<format> {"error_code":"$1", "error_message":"$2"}
</format>
<args>
<arg expression="get-property('ERROR_CODE')" evaluator="xml"></arg>
<arg expression="get-property('ERROR_MESSAGE')" evaluator="xml"></arg>
</args>
</payloadFactory>
<property name="messageType" value="application/json" scope="axis2"></property>
</then>
</filter>
<filter xmlns:ns="http://org.apache.synapse/xsd" xpath="get-property('contentTypeValue') = 'application/xml' or get-property('contentTypeValue') = 'text/xml'">
<then>
<payloadFactory media-type="xml">
<format>
<error_info>
<error_code>$1</error_code>
<error_message>$2</error_message>
</error_info>
</format>
<args>
<arg expression="get-property('ERROR_CODE')" evaluator="xml"></arg>
<arg expression="get-property('ERROR_MESSAGE')" evaluator="xml"></arg>
</args>
</payloadFactory>
<property name="messageType" value="text/xml" scope="axis2"></property>
</then>
</filter>
<respond></respond>
</sequence>
```
Loading

0 comments on commit 175cb29

Please sign in to comment.