Developer Resources

Platform API

The Smartmuni Platform API provides a simple standard way for applications to integrate seamlessly and participate in business processes that span organizations. The Platform API includes information about the web service operations available to developers.

Smart Objects

Smart Objects are the model objects that represent your data in Smartmuni and facilitate the business processes that act on that data.

Object Models

Smart models are object relationship and sequence diagrams to help developers better understand how object interactions support the business processes within Smartmuni.

Tutorials

Smartmuni provides developers with a rich set of tutorials to accelerate the sharing of data between applications. The tutorials describe interface semantics and operation sequences fulfilling specific use cases, such as the creation and management of bonds.

Platform Examples

Download code examples can be that can be used as a starting point for building integrations with the Smartmuni object store.

Smartmuni Platform API Calls

The following table lists Smartmuni Platform API calls, and provides a brief description for each. Click a call name to see syntax, usage, and more information for that call.

Create()

Adds one or more new objects to Smartmuni for your organization.

Delete()

Deletes one or more individual objects from your organization’s data.

Login()

Logs in to the login server and starts a client session.

Logout()

Ends the session of the logged-in user.

Query()

Executes a query against the specified object and returns data that matches the specified criteria.

Retrieve()

Retrieves one or more objects based on the specified object IDs.

Update()

Updates one or more existing objects in your organization’s data.

Smart Objects

The following table lists the primary objects representing core data within Smartmuni.

Agency

An organization, such as a city, county, redevelopment agency or school district, responsible for the oversight and administration of bonds used to fund public projects.

Bond

Represents a General Obligation or Revenue Bond associated with a DebtIssue.

BondDebtSchedule

Represents an single Payment amount necessary to meet principal and interest requirement for a specific Bond payment date.

Contact

Represents an individual associated with an Agency.

Contract

Represents the agreed upon terms for the management, levying and collecting of property taxes for a specific District.

County

Represents a governing body responsible for the collection of property taxes from parcels in a specified geographic region.

DebtIssue

Represents a series of financial obligations (such as bonds) sharing the same lien on revenues and other basic characteristics. A DebtIssue contains a set of DebtSchedule. The Issuer of a DebtIssue is an Agency.

DebtSchedule

An object defining the payment terms (such as Payment Date, Principal Amount, Rate and Interest Amount) for a DebtIssue.

District

Represents a public financing mechanism, such as Community Facilities District (CFD), Assessment District, Special Service Area, Local Improvement District, Landscaping and Lighting District or various types of regional and benefit-area-based fee programs.

Escalator

Represents the terms by which the levy rate increases to adjust for increases in costs associated with a District.

FiscalYear

A period used for calculating annual (“yearly”) levies, generally for the purpose of repaying bonds associated with specific districts.

Folder

Represents a collection of similar Reports, such as Bond Maintenance or District Administration reports.

Fund

Represents an individual account commonly used in Bond contracts relating to the flow of funds. These may include a Debt Service Fund, Mandatory Redemption Fund, Sinking Fund or other similar account type.

Levy

Represents the aggregate tax payments required, indicated by a special tax requirement, for a defined group of parcels in a specific Bond for a particular FiscalYear.

LevyClass

A classification of a Parcel defined by the Official Statement’s rate and method of apportionment. The LevyClass determines the expected maximum levy rate for a Parcel matching the criteria defined in the rate and method.

LevyPermit

An object defining the relationship between a Permit and a Levy for the purposes of identifying when adjustments to Parcel building square feet can be recognized by a given district.

Lien

Represents the tax obligation of a specific Parcel for the repayment of a Bond.

MaxTax

The maximum tax rate that can be charged to a Parcel in a specific District in a given FiscalYear.

Opportunity

Represents a pending deal, such as participation in an RFP or the renewal of an existing contract that has run to term.

Owner

The legal entity responsible for the payment of property taxes for a given Parcel.

OwnerParcel

The relationship between an individual Owner and a Parcel.

Parcel

The land area for which the County Assessor will collect property taxes.

Payment

Represents the payment received for outstanding tax obligations. Payments may be the result of a specific TaxBill issued to the Owner of a Owner or in some cases may be made independant of a TaxBill to prepay tax obligations.

PaymentSchedule

Represents the payment term necessary to meet principal and interest requirement for a specific Lien payment date.

Permit

Represents a unit of work being performed on a Parcel, often affecting the Parcel building square footage which may result in additional taxes being collected.

Profile

A defined set of application permissions that determine what operations, such as creating, updating and deleting objects, can be performed by a User assigned to the Profile.

Property

Represents the specific charasterists of a Parcel participating in a given Levy.

LevyMethod

Represents a grouping that contains the TaxRate for a LevyClass for a particular step of the rate and method.

Report

Represents a single report associated to a specific Folder.

Rule

Represents the criteria in the rate and method of apportionment used to assign a LevyClass to a Parcel.

Task

Represents a single activity assigned to a user, such as the assignment of a LevyClass to a Parcel as part of District or Bond administration.

TaxBill

Represents the summary information of all taxes due for a given period.

TaxBillItem

Represents individual taxes, often related to a specific District that are collected by a County through a TaxBill.

TaxRate

A percentage or fixed amount of the LevyClass assigned maximum levy rate for a given LevyMethod to apply to a Parcel.

TaxRateArea

A geographical area comprised of a unique combination of taxing jurisdictions.

User

Represents a user in Smartmuni for a particular Organization.

UserRole

The primary role the User plays in the system.

Object Models

The following table lists the primary objects representing core data within Smartmuni. Click a call name to see syntax, usage, and more information for that call.

Developer Tutorials

The example below demonstrates the steps required to create a new bond with the requisite relationships in Smartmuni.

Step 1. Login to Smartmuni

Use the login() call to log in to the login server and start a client session. A client application must log in and establish a new sessionbefore making any other API calls.

// Load the WSDL
URL url = new URL("file:/path/to/wsdl/file/smartmuni.wsdl");

// Set the namespace
QName qname = new QName("soap.services.smartmuni.com", "SmartmuniService");

// Create the service
Service service = Service.create(url, qname);

// Get the port
smartmuniService = service.getPort(SmartmuniService.class);

// Get the binding provider
BindingProvider bindingProvider = (BindingProvider)smartmuniService;

// Set the binding to maintain session state
bindingProvider.getRequestContext().put(
	BindingProvider.SESSION_MAINTAIN_PROPERTY, true);

// Login to the system
smartmuniService.login("someusername", "somepassword");
				

Step 2. Create the Bond

Use the create() call to add a Bond object to Smartmuni. The call returns an array containing a new bond id for each new Bond object created. In this case just one.

// Create an instance of the bond object
Bond bond = new Bond();

// Set the bond name
bond.setName("130801-01-XX-05 (Test)");

// Set the bond type
bond.setType(BondType.LIMITED_OBLIGATION_IMPROVEMENT_BOND);

// Set the bond issue date
calendar.setTime(dateFormat.parse("8/1/2013"));
bond.setDatedDate(DatatypeFactory.newInstance().newXMLGregorianCalendar(calendar));

// Set the bond coupon rate
bond.setCouponRate(new BigDecimal("0.0595"));

// Set the bond term
bond.setTerm(new BigDecimal("5"));

// Set the bond project name
bond.setProjectName("Install new solar panals");

// Set the bond project amount
bond.setProjectAmount(new BigDecimal("12345.67"));

// Set the bond capitalized interest amount
bond.setCapitalizedInterestAmount(new BigDecimal("9878.33"));

// Set the bond cost of issuance
bond.setCostOfIssuance(new BigDecimal("10576.74"));

// Set the bond early funding fee (interest)
bond.setEarlyFundingFee(new BigDecimal("123.45"));

// Set the bond par value (principal)
bond.setParValue(new BigDecimal("125320.68"));

// Create a list of bonds objects to pass to the create method
Bond[] bonds = new Bond[];

// Add the bond to the list of objects to create
bonds[0] = bond;

// Create the bond
saveResults = smartmuniService.create(bonds);

// Assign the bond id
bond.setId(saveResults[0].getId());
				

Step 3. Create the Bond Debt Schedule

Use the create() call to add the new BondDebtSchedule objects. It is important to assign the Bond object created in the previous step to the new BondDebtSchedule object prior the create() call. The Bond object is a required field and will establish the relationship between the bond and its debt schedule.

// Create the bond debt schedule
BondDebtSchedule bondDebtSchedule = new BondDebtSchedule();

// Associate the BondDebtSchedule object with the previously created Bond
bondDebtSchedule.setBond(bond);

// Set the interest, principal and payment amounts
bondDebtSchedule.setPrincipalAmount(new BigDecimal("25855.93"));
bondDebtSchedule.setInterestAmount(new BigDecimal("4336.86"));
bondDebtSchedule.setPaymentAmount(new BigDecimal("30222.79"));

// Create a list of bond debt schedule objects to pass to the create method
bondDebtScheduleItems[0] = bondDebtSchedule;

// Create the bond debt schedule
SaveResult[] saveResults = smartmuniService.create(bondDebtScheduleItems);
				

Step 4. Find or Create the Parcel

The taxes collected by parcels are used to repay the bonds. Before we can establish the relationship between the Bond and the Parcel we must first determine if the Parcel already exists in Smartmuni. If not we need to create it.

First we check Smartmuni for an existing Parcel using the query call and the SmartQuery language which is similar to a database query but designed for objects.

// Query for an existing parcel
SmartObject[] smartObjects = smartmuniService.query(
	"Select parcel From Parcel parcel Where (parcel.name = '959382011')");

// If the parcel was found then retrieve it, otherwise create a new parcel 
if (objects.size() > 0) {
	parcel = (Parcel)objects.get(0);
}
				

If no Parcel was found in Smartmuni matching the Tax Parcel Number / Assessor Parcel Number specified in the query then we need to create one.

Since Counties are responsible for the collecting of taxes, we need to specify what County the Parcel belongs to. To do that we must first retrieve a County object from Smartmuni so that we can assign it to the new Parcel before the create() call.

// Create a list of id's to pass to the retrieve method
String[] ids = new String[];

// Add the id for County to the list
ids.add("00119");

SmartObject[] counties = smartmuniService.retrieve("County", ids);

// Get the county object from the list
County county = (County)counties[0];

// Create an instance of the parcel
parcel = new Parcel();
	
// Assign the county to the parcel
parcel.setCounty(county);

// Set the Tax Parcel Number / Assessor Parcel Number
parcel.setName("959382011");
	
// Set the parcel legal description
parcel.setDescription("Lot 99 of Tract No. 12345-6");
				
// Create a list of parcel objects to pass to the create method
SmartObject[] parcels = new SmartObject[];
	
// Add the parcel to the list of objects to create
parcels[0] = parcel;

// Create the parcel
SaveResult[] saveResults = smartmuniService.create(parcels);
	
// Assign the parcel id
parcel.setId(results.get(0).getId());
		

Step 5. Create the Liens

Typically many parcels will be responsible for repaying a Bond. Each Parcel will have a Lien representing their financial obligation to the Bond. Use the create() call to add the new Lien object for each Parcel participating in a Bond.

It is important to assign both the Parcel object and the Bond object to the Lien prior the create() call. Both are required fields and establish the relationship between the Bond and the Parcel.

An identifying name should be given to each Lien that significantly represents the purpose of the lien.

Make sure to update the Lien with the corresponding id returned in the results. We will be adding LienDebtSchedul objects in the next step which requires a Lien object to complete the relationship.


// Create an instance of the lien
Lien lien = new Lien();

// Associate the bond to the lien
lien.setBond(bond);

// Associate the parcel to the lien
lien.setParcel(parcel);

// Set the lien name to the HERP ID
lien.setName("RWR69344C-130618");

// Set the lien amount
lien.setAmount(new BigDecimal("31861.23"));

// Set the lien term
lien.setTerm(new BigDecimal("5"));

// Set the lien rate
lien.setRate(new BigDecimal("0.0595"));

// Create a list of liens objects to pass to the create method
Lien[] liens = new Lien[];

// Add the lien to the list of objects to create
liens[0] = lien;

// Create the lien
SaveResult[] saveResults[] = smartmuniService.create(liens);

// Update the lien with the lien id
lien.setId(saveResults[0].getId());

// Load the WSDL
URL url = new URL("file:/path/to/wsdl/file/smartmuni.wsdl");

// Set the namespace
QName qname = new QName("soap.services.smartmuni.com", "SmartmuniService");

// Create the service
Service service = Service.create(url, qname);

// Get the port
smartmuniService = service.getPort(SmartmuniService.class);

// Get the binding provider
BindingProvider bindingProvider = (BindingProvider)smartmuniService;

// Set the binding to maintain session state
bindingProvider.getRequestContext().put(
	BindingProvider.SESSION_MAINTAIN_PROPERTY, true);

// Login to the system
smartmuniService.login("someusername", "somepassword");
				

// Create an instance of the bond object
Bond bond = new Bond();

// Set the bond name
bond.setName("130801-01-XX-05 (Test)");

// Set the bond type
bond.setType(BondType.LIMITED_OBLIGATION_IMPROVEMENT_BOND);

// Set the bond issue date
calendar.setTime(dateFormat.parse("8/1/2013"));
bond.setDatedDate(DatatypeFactory.newInstance().newXMLGregorianCalendar(calendar));

// Set the bond coupon rate
bond.setCouponRate(new BigDecimal("0.0595"));

// Set the bond term
bond.setTerm(new BigDecimal("5"));

// Set the bond project name
bond.setProjectName("Install new solar panals");

// Set the bond project amount
bond.setProjectAmount(new BigDecimal("12345.67"));

// Set the bond capitalized interest amount
bond.setCapitalizedInterestAmount(new BigDecimal("9878.33"));

// Set the bond cost of issuance
bond.setCostOfIssuance(new BigDecimal("10576.74"));

// Set the bond early funding fee (interest)
bond.setEarlyFundingFee(new BigDecimal("123.45"));

// Set the bond par value (principal)
bond.setParValue(new BigDecimal("125320.68"));

// Create a list of bonds objects to pass to the create method
Bond[] bonds = new Bond[];

// Add the bond to the list of objects to create
bonds[0] = bond;

// Create the bond
saveResults = smartmuniService.create(bonds);

// Assign the bond id
bond.setId(saveResults[0].getId());
				

// Create the bond debt schedule
BondDebtSchedule bondDebtSchedule = new BondDebtSchedule();

// Associate the BondDebtSchedule object with the previously created Bond
bondDebtSchedule.setBond(bond);

// Set the interest, principal and payment amounts
bondDebtSchedule.setPrincipalAmount(new BigDecimal("25855.93"));
bondDebtSchedule.setInterestAmount(new BigDecimal("4336.86"));
bondDebtSchedule.setPaymentAmount(new BigDecimal("30222.79"));

// Create a list of bond debt schedule objects to pass to the create method
bondDebtScheduleItems[0] = bondDebtSchedule;

// Create the bond debt schedule
SaveResult[] saveResults = smartmuniService.create(bondDebtScheduleItems);
				

// Query for an existing parcel
SmartObject[] smartObjects = smartmuniService.query(
	"Select parcel From Parcel parcel Where (parcel.name = '959382011')");

// If the parcel was found then retrieve it, otherwise create a new parcel 
if (objects.size() > 0) {
	parcel = (Parcel)objects.get(0);
}
				

// Create a list of id's to pass to the retrieve method
String[] ids = new String[];

// Add the id for County to the list
ids.add("00119");

SmartObject[] counties = smartmuniService.retrieve("County", ids);

// Get the county object from the list
County county = (County)counties[0];

// Create an instance of the parcel
parcel = new Parcel();
	
// Assign the county to the parcel
parcel.setCounty(county);

// Set the Tax Parcel Number / Assessor Parcel Number
parcel.setName("959382011");
	
// Set the parcel legal description
parcel.setDescription("Lot 99 of Tract No. 12345-6");
				
// Create a list of parcel objects to pass to the create method
SmartObject[] parcels = new SmartObject[];
	
// Add the parcel to the list of objects to create
parcels[0] = parcel;

// Create the parcel
SaveResult[] saveResults = smartmuniService.create(parcels);
	
// Assign the parcel id
parcel.setId(results.get(0).getId());