Skip to content

Home

Jump to bottom
merccat edited this page Sep 15, 2016 · 1 revision

Welcome to the ServiceNowRESTClient wiki!

Overview

The ServiceNow TableAPI Client is designed to provide access to your ServiceNow instance's data through ServiceNow's REST TableAPI in a .Net application. It is written in C#, however once compiled and referenced as a DLL, you could certainly use it in a VB project as well if you were so inclined. JSON Serialization / DeSerialization is done with the Newtonsoft.JSON package and I used System.Net.WebClient for the actual communication.

There are only 4 classes including the client itself. Those classes are ServiceNowRecord, ServiceNowLink, TableAPIClient and RESTResponse.

  • Record (Abstract) - All record types your implementation passes between the client will need to inherit from this base class. Types derived from ServiceNowRecord will simply contain a list of fields which you want to manipulate with the selected table. The properties much match the field names in ServiceNow. sys_id is already included.
  • ResourceLink - A pre-built representation of a standard Link as returned by Service Now that can be included as a property in your record type.
  • RESTResponse<T> - All methods that have a response will package the response in a RestReponse where T is your record type. It is packaged this way so that errors returned by service now can be included separately. NOTE: This is actually a base class, from which there are two classes you'll actually use derived:
  • RESTQueryResponse<T> - The response property is a List
  • RESTSingleResponse<T> - The response property is simply T.
  • TableAPIClient<T> (where T is a ServiceNowRecord) - The actual client. On initialization it uses reflection to build a list of fields for the web request query string which is part of why the field names in your Class derived from ServiceNowRecord need to use the actual field names.

Namespaces

  • ServiceNow - The root namespace of this project, this namespace contains the data classes that get returned.
  • ServiceNow.TableAPI - The TableAPI client itself is held in this namespace.
  • ServiceNow.Interface - Class interfaces for the TableAPI client as well as the RESTResponse types are held here.

Constructors

  • TableAPIClient(String tableName, String instanceName, NetworkCredential credentails)

    • Table name is the name of the table in service now to be accessed.
    • Instance name is the name of your service now instances. ie instanceName.service-now.com
    • Credentials is a System.Net.NetworkCredential (with username/pwd) for the user to be used.

  • TableAPIClient(String tableName, String instanceName, String userName, String pwd)

    • Same as above but simple strings for username and password instead of NetworkCredential.

Public Methods

  • RestSingleResponse<T> GetById (String id)

    • Retrieves a single record contained in the RESTSingleResponse of the type T defined for the table client.
    • Any errors will be fully captured and returned in the ErrorMsg property of the response.
    • id is the sys_id of the record to be retrieved.

  • RestQueryResponse<T> GetByQuery (String query)

    • Retrieves a record set in the response (as a list of T) from the query result (if successful) along with any error messages (if any).
    • query is a standard service-now table query.

  • RestSingleResponse<T> Post(T record)

    • Creates a new record in the table using the fields provided in the record of type T.
    • A RESTResponse containing a single result of T (if successful) for your newly created record, along with any error messages (if any).
    • record is the record of type T (built from the Record base class) to be added to the table in ServiceNow.

  • RestSingleResponse<T> Put(T record)

    • Updates an existing record in the table. Make sure your record has sys_id populated.
    • All fields of T will be sent in the update so make sure they are ALL populated unless you want the field to be emptied. A good practice is to first retrieve the record using GetById, then only edit the fields you want to change before submitting a Put.
    • A RestResponse containing a single result of T with your updated record (if successfull) along with any error messages (if any).
    • record is the record of type T (built from the Record base class) to be added to the table in ServiceNow.

  • Delete(String id)

    • Deletes a record in the active table with the specified id.
    • WARNING: Since there is no return type, you will need to catch any errors externally. The exception message will still include all details including any response from Service Now.

Usage

Note, all operations are dependent upon the user's permissions within your instance of ServiceNow. For example if the user you are using does not have rights to view a selected field, then that field will not be returned.

Example

I tried to make the actual usage of the client as simple and straight forward as possible. The following code is of course assuming you have already included the compiled DLL in your project (or are working from the client code project - avoid that). The example will be working with a few fields from the sys_user table.

Step 1

Create a class derived from Record representing the data structure you want to work with from your table. This can be thought of as our data contract. Note the Newtonsoft JSonproperty elements are required and are to contain the exact field names in ServiceNow. The example below is a simple example to retrieve some user details. Normally we would of course be working with more fields than this, but lets keep it short and sweet: ` using Newtonsoft.Json;

{  
    public class SNUser : Record  
    {  
        [JsonProperty("employee_number")]  
        public string employee_number { get; set; }  
  
        [JsonProperty("first_name")]  
        public string first_name { get; set; }  
  
        [JsonProperty("last_name")]  
        public string last_name { get; set; }  
    }  
}

Notice how there is no mention of the table name here, I'm only concerned about the fields. Also, sys_id isn't included because the base Record already includes that.

Also, note that currently all properties are returned as strings. Why? Well, because everything in a JSON string is a string until you parse it. I'm sure you can add parsers to your record type if needed, but for this case none are needed since everything is a string anyway.

Step 2

Instantiate my client using the record type created above. Note when instantiating the client I will also need to provide my instance name, the table name I want to work with and a set of credentials (either as username and password or System.Net.NetworkCredential).

TableAPIClient<SNUser> UserClient = new TableAPIClient<SNUser>("sys_user", "intance_name", "api_user", "pass");

Step 3

Invoke a method. Lets get a record (assuming we know it's sys_id):

var response = UserClient.GetById("7648c1904a36231701673929d43fd325"); ' ' if(!response.IsError) { SNUser myUser = response.result; }

or for another example, we can query for all active users in a given department (agency) using a standard service now query:

Users = new List<SNUser>(); 

`string query = "u_agency.sys_id=a1924de13f3523140984831f2a6c589c^active=true";  `
`var result = UserClient.GetByQuery(query);  `
  
`if (!result.IsError) { Users = result.result; } `
Clone this wiki locally