Skip to main content
Kinetic Community

Form

The ArsModels Form class represents a loaded form definition.  An instance of Form is used to make create, retrieve, update, and delete calls to the database.  The Form instance also stores an array of ArsModels Fields instances that are loaded with the form definition.

Form.find

ArsModels::Form.find() is the method used to retrieve and instantiate a new ArsModels Form instance (the actual constructor for this class is not intended for external use). The first argument is the name of the form to load, which is required. The form name is then followed by the options specified below, the required options are in bold.

 

:context The ArsModels Context that will be used to retrieve the form definition
:fields An array of field names or ids that should be loaded with the form definition. If this option is not used all of the fields will be loaded by default.

Instance Methods

ars_form Returns the com.bmc.arsys.api.Form instance that is stored internally with the ArsModels Form.
context Returns the ArsModels Context instance that was used to load the form definition. This Context instance is also used when instance methods of Form are used to make calls to Remedy.
name Returns the name of the form.
fields Returns an array of ArsModels Field instances that were loaded with the form definition. Also note that these are the fields that will be retrieved with entries by default when retrieving entries with this Form instance
field_ids Returns an array of field ids that represent the fields that were loaded with the form definition.
sort_fields Return a hash that maps 
field_for Returns a single the Field instance given a field id or name that was loaded with the form definition.
field_id_for Returns the id of a field given a name that was loaded with the form definition.
schema_type Returns the schema type of the form.
create_entry!

Creates a new record in the form and returns an ArsModels Entry instance representing the record. Below are the options that the create_entry! method takes, the required parameters are in bold.

:field_values

This option takes a hash value that maps field ids or field names to the value they are to be set to. An error will be raised if a field name or id specified is not in the fields array loaded with the Form definition.

:fields

This option takes an array value of field names or ids that specifies which fields should be retrieved with the Entry after creation. The fields loaded with the Form definition will be used by default if this option is not used. An error will be raised if a field name or id specified is not in the fields array loaded with the Form definition.

Create an entry

form.create_entry!(
  :field_values => {
    "First Name" => "Don",
    "Last Name" => "Demo",
    "Login Id" => "ddemo"
})

Create an entry and only return a single field

form.create_entry!(
  :fields => ["Login Id"],
  :field_values => {​
    "First Name" => "Don",
    "Last Name" => "Demo",
    "Login Id" => "ddemo"
})

delete_entries!

Deletes existing records in the form and returns an array of ArsModels Entry instances representing the records.  

There are two modes that delete_entries! can be called with.  It can either be passed a list of entry ids or if the first argument is :all a qualification can be specified to determine which records to delete.  Below are the options that delete_entries! takes.

:conditions This option is used if the first argument is :all.  It takes a String, Array, or Hash.  If a string is given it is simply treated as the Remedy qualification.  If an array is given it will take the first element as the Remedy qualification and the following elements as field identifiers to be inserted into the Remedy qualification.  If a hash is given it will craft a qualification using the keys of the hash as field identifiers and the corresponding values of the hash as values.
:fields This option takes an array value of field names or ids that specifies which fields should be retrieved with the Entry before deletion. The fields loaded with the Form definition will be used by default if this option is not used. An error will be raised if a field name or id specified is not in the fields array loaded with the Form definition.

Delete entries by specifying entry ids.  If multiple ids are given the result of this call will be an array of Entry objects for the deleted records.  If a specified id does not correspond to a record an ArsModels Exception will be present in the array in place of the Entry.  If a single id is given the result of this call will be the corresponding Entry before deletion, and if no entry matches an exception will be raised.

form.delete_entries!("000000000000029", "000000000000030",
  "000000000000031")

Delete entries by a specified qualification.  The result of this call will be an array of Entry objects that matched the qualification before deletion.  If no entries match the qualification an empty array will be returned.

form.delete_entries!(:all,
  :conditions => "'First Name' = \"Don\"")
delete_entry!

Deletes an existing record in the form and returns an ArsModels Entry instance representing the record.  This method takes an entry id as the first parameter.  If the specified entry does not exist an exception will be raised.

The behavior of this method is equivalent to the delete_entries! method described above, see delete_entries! for details and examples.

find_entries

Retrieves existing records in the form and returns an array of ArsModels Entry instances representing the records.

There are two modes that find_entries can be called with.  It can either be passed a list of entry ids or the first argument can specify one of the following modes which will then use a qualification: :single, :all, :first, :last.  Below are the options that find_entries takes.

:conditions This option is used if the first argument is one of the following modes:  :single, :all, :first, or :last.  It takes a String, Array, or Hash.  If a string is given it is simply treated as the Remedy qualification.  If an array is given it will take the first element as the Remedy qualification and the following elements as field identifiers to be inserted into the Remedy qualification.  If a hash is given it will craft a qualification using the keys of the hash as field identifiers and the corresponding values of the hash as values.
:page This option is only used when retrieving records using the conditions option above.  If there is a limit option specified this option determines which page of records to retrieve.
:limit This option is only used when retrieving records using the conditions option above.  This option specifies a maximum number of records to retrieve from Remedy.
:order This option is only used when retrieving records using the conditions option above.  This option specifies sort fields and order for retrieving the records.  It takes an Array or Hash.  If an array is given each element is expected to be a field identifier and it will sort by those fields ascending.  If a hash is given it takes the keys as field identifiers and the values should be either :asc or :desc for ascending or descending respectively.  The form's default sort criteria will be used if this option is not specified.
:fields This option takes an array value of field names or ids that specify which fields should be retrieved with the Entry. The fields loaded with the Form definition will be used by default if this option is not used. An error will be raised if a field name or id specified is not in the fields array loaded with the Form definition.

Find entries by specifying entry ids.  If multiple ids are given the result of this call will be an array of Entry objects for the corresponding records.  If a specified id does not correspond to a record a nil value will be present in the array in place of the Entry.  If a single id is given the result of this call will be the corresponding Entry, if no corresponding record exists a nil value will be returned.

form.find_entries("000000000000029", "000000000000030",
  "000000000000031")

Find single entry by conditions.  If the first argument is :single the :conditions option will be used to retrieve records.  When using the :single argument the result of the call will be an ArsModels Entry if a record matches the qualification otherwise a nil value will be returned.  If multiple records match the qualification an error will be raised

form.find_entries(:single,
  :conditions => "'First Name' =\"Don\"")

Find all entries by conditions.  If the first argument is :all the :conditions option will be used to retrieve records.  When using the :all argument the result of the call will be an array containing an ArsModels Entry object for each matching record.  If no records match the qualification an empty array will be returned.

form.find_entries(:all,
  :conditions => "'Full Name' != $NULL$")

Find first entry by conditions.  If the first argument is :first the :conditions option will be used to retrieve records.  When using the :first argument the result of the call will be an ArsModels Entry if records match the qualification otherwise a nil value will be returned.  The record that sorts first by the default or specified sort criteria will be the one returned.

form.find_entries(:first,
  :conditions => "'Full Name' != $NULL$")

Find last entry by conditions.  If the first argument is :last the :conditions option will be used to retrieve records.  When using the :last argument the result of the call will be an ArsModels Entry if records match the qualification otherwise a nil value will be returned.  The record that sorts last by the default or specified sort criteria will be the one returned.

form.find_entries(:last,
  :conditions => "'Full Name' != $NULL$")

Find entries using limit and page.  If the limit option is used the method will return an array containing ArsModels Entry objects no larger than the limit.  If fewer match the array will be the length of those that match.  If no page option is used or page 1 is specified the records that sort first will be returned.  To retrieve subsequent records the page option is used, note that the page option is indexed from 1 (meaning page 1 will retrieve the first set of records).

form.find_entries(
  :all,
  :conditions => "'Full Name' != $NULL$",
  :limit => 5,
  :page => 1  
)

Find entries using order, sorting by the Full Name descending.

form.find_entries(
  :all,
  :conditions => "'Full Name' != $NULL$",
  :order => {"Full Name" => :desc}
)
find_entry

Retrieves an existing record in the form and returns an ArsModels Entry instance representing the record.  This method takes an entry id as the first parameter.  If the specified entry does not exist nil is returned.

The behavior of this method is equivalent to the find_entries method described above, see find_entries for details and examples.

update_entries!

Updates existing records in the form and returns an array of ArsModels Entry instances representing the records.  This method has two modes: either it is given multiple entry ids as the first parameters or it is given :all as the first parameter and a :conditions option specifies which records to update.

:conditions This option is used if the first argument is :all.  It takes a String, Array, or Hash.  If a string is given it is simply treated as the Remedy qualification.  If an array is given it will take the first element as the Remedy qualification and the following elements as field identifiers to be inserted into the Remedy qualification.  If a hash is given it will craft a qualification using the keys of the hash as field identifiers and the corresponding values of the hash as values.
:field_values This option takes a hash value that maps field ids or field names to the value they are to be set to. An error will be raised if a field name or id specified is not in the fields array loaded with the Form definition.
:fields This option takes an array value of field names or ids that specifies which fields should be retrieved with the Entry after modification. The fields loaded with the Form definition will be used by default if this option is not used. An error will be raised if a field name or id specified is not in the fields array loaded with the Form definition.

Updating by specified entry ids.  If multiple ids are given the result of this call will be an array of Entry objects for the corresponding records.  If a specified id does not correspond to a record a nil value will be present in the array in place of the Entry.  If a single id is given the result of this call will be the corresponding Entry, if no corresponding record exists an error will be raised.

form.update_entries!("000000000000029", "000000000000030", "000000000000031",
  :field_values => {"First Name" => "Bob"})

Updating by conditions.  The result of this call will be an array of Entry objects that matched the qualification before modification.  If no entries match the qualification an empty array will be returned.

form.update_entries!(:all, :conditions => "'First Name' != $NULL$",
  :field_values => {"First Name" => "Bob})
update_entry!

Updates an existing record in the form and returns an ArsModels Entry instance representing the record.  This method takes an entry id as the first parameter.  If the specified entry does not exist nil is returned.

:field_values This option takes a hash value that maps field ids or field names to the value they are to be set to. An error will be raised if a field name or id specified is not in the fields array loaded with the Form definition.
:fields This option takes an array value of field names or ids that specifies which fields should be retrieved with the Entry after modification. The fields loaded with the Form definition will be used by default if this option is not used. An error will be raised if a field name or id specified is not in the fields array loaded with the Form definition.

Updating a record given an entry id.

form.update_entry!("000000000000029",
  :field_values => {"First Name" => "Bob"})