API Documentation

MP

The MP object is the central object that programmers will generally direct all of their requests through. It is almost never instantiated directly, but instead through the connect method.

class MP(options)

Arguments:

• options (object) – An object that contains all of the necessary initialization information for the MP object.

client

The SOAP client object

ext

An instance of Extensions() that allows for easily calling extensions written for MPJS. For example:

mp.ext.doSomething();

schema

An instance of Schema(), which you shouldn’t need to interact with. Ever.

connect(options)

Arguments:

• options (object) – An object describing how to connect to MP

Returns:

Promise

prototype.sp(name)

Instantiates and returns a StoredProcedure() object of the given name.

Arguments:

• name (string) – The name of the stored procedure

Returns:

StoredProcedure() object

prototype.fn(name)

Returns a APIFunction() object of the given name. Note that if the requested function name is not defined by the WSDL, an error will be thrown.

Arguments:

• name (string) – The name of the function to fetch

Returns:

APIFunction() object

prototype.table(name)

Fetches a table, as defined by the MP object’s Schema().

Arguments:

• name (string) – The name of the table to fetch

Returns:

Table() object

prototype.save(record[, userId])

Save either a single record or an array of records back to MP. If the record is new (does not have a primary key value), then AddRecord is called, otherwise UpdateRecord is used.

Arguments:

• record (mixed) – Either a Record() object or an array of Record() objects.

Returns:

Promise

prototype.query(table)

Creates a Query() object for the given table and returns it.

Arguments:

• table (mixed) – Either a string of a valid table name or a table object, as returned by prototype.table().

Returns:

Query() object.

prototype.describeFunctions()

Lists the SOAP API functions described by API.

Returns:Array of objects

StoredProcedure

Coordinates executing and returning results from stored procedures. These objects should be created via the main MP() object by calling MP.prototype.sp().

class StoredProcedure(mp, name)

Arguments:

• mp (MP) – An MP object
• name (string) – The name of the stored procedure

mp

The MP() object that this stored procedure belongs to.

name

The stored procedure’s name.

prototype.getName()

Returns:A string representing the name of the stored procedure.

prototype.call(data[, userId])

Execute the stored procedure and return a promise that, when resolved, contains the resulting datasets, if any.

Arguments:

• data (mixed) – Either an object to pass (indirectly) as the request string or an array of objects to pass as request strings. If the latter, executes the stored procedure for each object.
• userId (int) – The user ID the stored procedure should be executed as. Defaults to 1.

Returns:

Promise

prototype.createFunctionCall(data[, userId])

Creates a function call referencing ExecuteStoredProcedure and sets the request string as provided by data.

Arguments:

• data (object) – An object that will be rendered into the request string

Returns:

APIFunctionCall() object

APIFunction

Facilitates calling SOAP functions. These objects should always be created by the MPJS library when a connection is initiated. You should not have to ever create them yourself. Instead, retrieve them by calling MP.prototype.fn().

class APIFunction(mp, name, definition)

Arguments:

• mp (MP) – The MP object
• name (string) – The name of the function
• definition (object) – The definition (input and output) of what the SOAP function expects / returns

mp

name

definition

args

An instance of APIFunctionArguments(), which is used for validating, encoding, and providing defaults for arguments passed to SOAP function calls

prototype.call(data[, userId])

Calls the SOAP function with the parameters specified, returning a promise that resolves with an APIFunctionResponse() upon completion.

Arguments:

• data (mixed) – Either an object providing arguments for the SOAP function or an array of objects. If the latter, the SOAP function will be executed once for each item in the array
• userId (int) – The user ID to execute the function as. Defaults to 1

Returns:

Promise

prototype.createFunctionCall(data[, userId])

Creates and returns an APIFunctionCall() object. This method is called by the call() method.

Arguments:

• data (object) – An object providing arguments for the SOAP function
• userId (int) – The user ID to execute the function as. Defaults to 1

Returns:

APIFunctionCall() object

APIFunctionCall

Basically an interim object that holds an APIFunction() and the arguments that it should be called with.

class APIFunctionCall(fn, values)

Arguments:

• fn (APIFunction) – The function that’s being called
• values (object) – The values / arguments the function should be called with

fn

values

prototype.call()

This is the method that performs the actual call to the SOAP API. It returns a promise that is resolved with whatever is returned by the resulting APIFunctionResponse()‘s getData().

Returns:Promise

APIFunctionResponse

Contains the response from a SOAP function. Helps to facilitate delivery of that content, providing a seemingly more standard interface to the output of the raw function. NOTE: This class is not directly exposed to the public API.

class APIFunctionResponse(fnCall, rawResponse)

Arguments:

• fnCall (APIFunctionCall) – The function call that resulted in the response in question
• rawResponse (object) – An object containing the raw response. Well, if by raw we mean the response as parsed by the “soap” library

fnCall

rawResponse

prototype.getData()

Checks the type of the response. If an “<anyXML>” type result, returns an instance of DataResolver(); otherwise, returns the raw response (mostly).

Returns:Mixed

APIFunctionArguments

This class is really not a public part of the API. Just know that it exists and does magical things. :)

class APIFunctionArguments(fn, definition)

Table

Stores information about a Ministry Platform table, such as columns, and constraints. Can be used to create Record() objects, which reference the parent table.

In the future, the Table object will likely play a greater role in database querying.

class Table(name, displayName, singularName, pageId)

Arguments:

• name (string) – The actual database table name
• displayName (string) – The “pretty” name used to represent the table in the Ministry Platform software
• singularName (string) – The “singular” version of the table name. For example, the “Contacts” table has a singular name of “Contact”
• pageId (int) – The Ministry Platform Page_ID for the table

columns

An array of Column() objects that make up the basic structure of the table

c

An object mapping column names to Column() objects

constraints

An array of Constraint() objects

prototype.column(name)

Fetch a Column() object from table by name

Arguments:

• name (string) – Name of column

Returns:

Column() object

prototype.getColumnNames()

Returns:Array of column names

prototype.getPrimaryKey()

Gets the primary key Column() object. Throws an error if table has no primary key.

Returns:Column() object

prototype.record([data])

Creates a new Record() object based on the current table

Arguments:

• data (object) – Data to intialize the record object with

Returns:

Record() object

Record

Provides an interface for interacting with table-level data from Ministry Platform. Record objects are used to save data to Ministry Platform via the MP.prototype.save() method. They are almost always created by calling the Table.prototype.record() method or via the Query() object results parsing. In other words, you should never have to instantiate a Record manually.

class Record(table)

Arguments:

• table (Table) – The table the record belongs to

table

data

The raw data that has been stored for the record. No touchy!

prototype.getPrimaryKey()

Return the value of the record’s primary key column. If the record belongs to a table that does not have a primary key, an error will be thrown.

Returns:Integer

prototype.setPrimaryKey(value)

Sets the record’s primary key column to the supplied value. If the record belongs to a table that does not have a primary key, an error will be thrown.

Arguments:

• value (int) – Primary key to set

prototype.isNew()

Whether or not the record has been saved to the database. This is determined by checking if the record’s primary key column has been set or not.

Returns:Boolean

prototype.toObject(skipDecode)

Convert the record to a standard JavaScript object. If skipDecode is truthy, the values are not decoded to their proper JavaScript type (normally, primary key will return as an int instead of a string).

Arguments:

• skipDecode (boolean) – Whether or not values should be decoded

Returns:

Object

prototype.toJSON()

Returns JSON-compatible representation of the record. This method simply returns the result of toObject().

Returns:Object

prototype.toRequestData()

Returns a RequestData() representation of this record.

Returns:RequestData() object

prototype.toString()

Returns stringified version of toRequestData().

Returns:String

prototype.update(data)

For each key in data, set column to corresponding value.

Example:

record.update({
   First_Name: 'Tim',
   Last_Name: 'Radke'
});

Arguments:

• data (object) – Object to set data with

Returns:

Self

fromArray(data)

Shorthand for:

new Record(table).update(data);

Arguments:

• data (object) – The data to send to update()

Returns:

Record() object

Column

Tables are made up of columns, so it makes sense that we ought to have a Column object. And so we do. :)

class Column(table, name, args)

table

name

type

The type encoder / decoder for this column.

defaultValue

What the column should default to if no value is provided.

nullable

Whether or not a null value is acceptable

primaryKey

A boolean that indicates whether this column is the table’s primary key

not

An object that contains a bunch of functions for performing queries with the column. These functions are not part of the prototype due to the unfortunate nature of nesting an object in a prototype (its child functions lose access to the correct “this”).

These methods are used like so:

var Contacts = mp.table('Contacts')
  , results = mp.query(Contacts).filter(Contacts.not.eq(4)).all();

eq(v)

Return a Filter() where column <> v.

Arguments:

• v (mixed) – The value to check equality for

Returns:

Filter() object

gt(v)

lt(v)

ge(v)

le(v)

like(v)

prototype.getDefault()

Return an appropriate default for the column.

Returns:Mixed

prototype.eq(v)

Return a Filter() where column == v.

Arguments:

• v (mixed) – The value to check equality for

Returns:

Filter() object

prototype.gt(v)

prototype.lt(v)

prototype.ge(v)

prototype.le(v)

prototype.like(v)

prototype.asc()

Return an OrderBy() with the column in ASC direction.

Returns:OrderBy() object

prototype.desc()

Returns an OrderBy() with the column in DESC direction.

Returns:OrderBy() object

Query

Query objects allow us to build complex Ministry Platform queries on arbitrary tables. They have a handful of query-modifying methods, such as limit(), filter(), and orderBy() that actually return new Query objects with the changes requested. So to be very clear, if you do the following:

var query = mp.query('Contacts')
  , query2 = query.limit(5);

... then:

query === query2;   // false !!

Also it should be noted that you shouldn’t have to instantiate these objects yourself. Instead, grab a new Query object via your application’s main MP object:

var query = mp.query('Contacts');

// or create a query from a Table:

var query = mp.query(mp.table('Contacts'));

class Query(mp, table[, opts])

Arguments:

• mp (MP) – The main MP instance
• table (Table) – The table the query should be based off of
• opts (object) – Query options object

prototype.filter(filter)

Creates a new query with either provided filter/filters.

Arguments:

• filter (mixed) – Either a Filter() object or an array of Filter() objects

Returns:

A new Query() object

prototype.filterBy(filters)

For each key/value in the filters object, creates a new filter and finally returns a new Query object with these filters appended.

Here’s what goes on behind the scenes:

var result = [];

for (var i in filters) {
  if (filters.hasOwnProperty(i)) {
    result.push(this.table.column(i).eq(filters[i]));
  }
}

return modQuery(this, {filters: result});

Arguments:

• filters (object) – The object to make filters from

Returns:

A new Query() object

prototype.orderBy(orderBy)

Creates a new query with the provided orderBy object/objects.

Arguments:

• orderBy (mixed) – Either a OrderBy() object or an array of OrderBy() objects

Returns:

A new Query() object

prototype.limit(n)

Creates a new query with the provided row limit.

Arguments:

• n (int) – The number of rows the query should be limited to

Returns:

A new Query() object

prototype.offset(n)

Creates a new query with the provided offset.

Arguments:

• n (int) – The offset the query should start from

Returns:

A new Query() object

prototype.first()

Creates a new query with limit(1), executes it and returns a promise. The promise is resolved with either a single Record() or, in the event that no results were found, null.

Returns:Promise

prototype.all()

Executes the query and returns a promise. The promise is resolved with an array of Record() objects. The array also has a special first() method, which returns the first item in the array or null, if the array is empty.

Returns:Promise

RequestData

This is another helper class that is generally not publicly visible. As such, I’m not going to document it at this time.

class RequestData(data)

Extensions

class Extensions(mp, extensions)