Skip to main content
Kinetic Community

Quick Start

This article covers the basics of using the ArsModels library to work with Remedy data.

Setup

The first step in using ArsModels is creating a Context which stores authentication and server information for making API calls to Remedy.  The second setup step is to load a form definition for the Remedy form we will be working with.  The Form stores information about the fields so we can read and write values from and to Remedy.

Create Context

Here we create an ArsModels Context that will be used to make API calls with ArsModels.

context = ArsModels::Context.new(
  :username => "username",
  :password => "password",
  :server   => "myremedyserver.mycompany.com",
  :port     => 0
)

Load Form

Here we load an ArsModels form definition.  The Form instance will allow us to read and write to that Remedy form.  Note that we pass the context created above to the Form.find call, this context will be stored with the Form instance and used for any of the API calls made with that Form instance.

form = ArsModels::Form.find("KS_SAMPLE_People", :context => context)

Create

Here is an example of creating a record.  Calling the create_entry! method on a previously loaded ArsModels Form will create a record on that form.  In this example we are passing the field_values option a hash that maps field names to values.  The result is returned as an ArsModels Entry object which can be updated and deleted as shown below, see the Entry section below for more functionality.

entry = form.create_entry!(:field_values => {
  "First Name" => "Todd",
  "Last Name" => "Tester"
})

Retrieve

Here are some examples of retrieving records.  Calling the find_entries method on a previously loaded ArsModels Form will retrieve records from that form.  There are two modes for retrieving records that are shown below: single and all.  Records are returned as ArsModels Entry objects which can be updated and deleted as shown below, see the Entry section below for more functionality.

When retrieving records in single mode a single ArsModels Entry object will be returned if a record exists, a nil value will be returned no record exists, and an exception will be raised if multiple records match the conditions.  Note that the mode (single) is passed as the first argument, then we pass the conditions option a String which is our Remedy qualification.

entry = form.find_entries(:single, :conditions => ["'First Name' = \"Todd\""])

When retrieving records in all mode an Array containing ArsModels Entry objects will be returned, if no records match the conditions an empty Array will be returned.  Note that the mode (all) is passed as the first argument, then we pass the conditions option a String which is our Remedy qualification.

entries = form.find_entries(:all, :conditions => ["'First Name' =\"Todd\""])

Update

To update a Remedy record call the update_attributes! method on an ArsModels Entry.  In this example we pass the update_attributes! method a Hash that maps field names to values.

entry.update_attributes!({
  "Company" => "Acme"
})

Delete

To delete a Remedy record call the delete! method on an ArsModels Entry.

entry.delete!

Entry

The type of object that is returned from the create_entry! and find_entries calls is ArsModels Entry.  In addition to updating and deleting via these Entry objects we can also access the values of a field for that record.  Below we access the value of a field using the [] operator and the field name print it out.

puts entry["Company"]