Tyler Business Office Integration User Guide

Last Modified on 02/21/2024 3:17 pm CST

Tool Search: Business Office API Credentials, Business Office Synchronization

This integration is currently only available to districts that use Tyler ERP. In the future, an integration may be made available to additional ERP systems.

Tyler ERP clients will need access to the file that is generated in the application temp folder. SaaS clients will typically access this file via an FTP login. If SaaS clients need an FTP login, they can open a support case with SaaS Tyler Systems Management to request access.

Overview

Business Office Integration allows HR systems to transfer and send their collection of staff member data to Infinite Campus. The Business Office Integration User Guide provides all the information on how to use Infinite Campus API for integration and what the outcomes of the integration will be.  

Business Office Integration for HR Systems

Infinite Campus provides an API that is used by HR systems to create Staff Members in Infinite Campus and keep the staff members up to date with the latest information from the HR system. 

The key to the integration of the two systems is to be able to identify the same Staff Member in each system. Both HR systems and Infinite Campus identify Staff Members via a unique alpha-numeric identifier. This identifier is called a "staffNumber". In Infinite Campus this is stored in the Local Staff Number field. Many districts already keep the HR system's staffNumber in sync with the Campus staffNumber. For these districts, there is a minimal amount of work that needs to be accomplished to have a successful HR system integration.

For districts that have not updated Infinite Campus with the HR system's staffNumber, they must update the Local Staff Number for all the Staff in Campus with the staffNumber from their HR system.

Once the integration is complete, the district will no longer able to add/change staff data in Infinite Campus. Infinite Campus makes the data read-only so it cannot be changed. To change any of the data, the change must be made in the HR system which is then responsible for sending the data to Infinite Campus.

Using the API, the HR system can create and update the following information about the Staff member in Infinite Campus:

Demographics

The demographic data includes:

  • Last name
  • First name
  • Middle name
  • Staff number
  • Gender
  • SSN
  • Birthdate
  • Work phone
  • Cell phone
  • Other phone
  • Work email
  • Personal email

Rules:

  • Gender must be a valid Infinite Campus gender (a list is available via the Infinite Campus API).
  • If the lastName, firstName, or middleName are changed during an update, the API end-dates the existing Identity and creates a new Identity. The new Identity is then set as the current Identity.

Employments

Employments include the hire date and the termination date. Since a former staff member may be rehired, multiple employment records can be sent using the API. The employment record includes:

  • Hire date
  • Termination date

As these dates are the dates of record from the HR system, the Infinite Campus API does no further validation of the date. It does not ensure that the termination date is after the hire date or that multiple employment records don't overlap. It is assumed that the HR system already performs such validations before sending the records to Infinite Campus.

District Assignments (a.k.a. Positions)

District Assignments include the staff's responsibilities at each school and are used by Infinite Campus for Reporting and to determine roles and access within Infinite Campus. The position record includes:

  • School number
  • Assignment code (a State defined code that must exist in Infinite Campus; if it does not an error is generated by the API)
  • Title code - This is a description of the position as determined by the district. 
  • Title description (used by the API when creating a new title)
  • Start date 
  • End date

An example record for a Teacher who is working as a Basketball coach would be:

  • schooNumber: 010 (the Infinite Campus school number)
  • assignmentCode: 20 (defined by the State)
  • titleCode: 4A61E262 (defined by district)
  • titleDescription: Varsity Basketball 
  • startDate: 2023-10-01 (the first day of basketball season)
  • endDate: 

Because some HR systems may only have Title codes and others may only have Assignment codes, the API only requires one or the other. However, the best practice would be to send both the title code and assignment code to make the most complete record in Infinite Campus.

As these records are controlled by the HR system, there is little validation performed by the API. The API ensures the School number matches a School number in Infinite Campus and also ensures the Assignment code matches an assignment code in Infinite Campus. It does not ensure that start and end dates are valid, or that assignments between schools are valid. It is assumed the HR system already performs such validations and only sends correct records.

While the Position is optional when creating or updating a Staff member via the API, Infinite Campus MUST have a Position for the Employee before they are considered a Staff member. If the Position information isn't available when the HR system creates the employee, the HR system must make a subsequent call to associate a position with a staff member before considering the staff member complete in Infinite Campus.

Rules

Because there is no matching identifier between the HR system's Positions and the Infinite Campus District Assignment (Employment Assignment), the Infinite Campus API has the following rules:

  • School Number must be a Infinite Campus school (a list of valid school number is available via the Campus API)
  • Assignment Code must be a Infinite Campus Assignment code (a list of valid assignment codes is available via the Infinite Campus API)
  • If the Infinite Campus API can find a match based on School number, Title code and/or Assignment code, and Start date, the End date is updated. If the API finds more that one matching position, all such positions end dates are updated.
  • If the Infinite Campus API can find a match based on School number, Title code and/or Assignment code, and End date, the Start date is updated. If the API finds more that one matching position, all such positions start dates are updated.
  • If the Infinite Campus API cannot find a matching titleCode, it automatically creates a new one in Infinite Campus.

Household Information

Most HR systems are focused on individual employees and are not concerned about how employees are related or what type of Household structure exists. These households and household structures are very important in Infinite Campus. Therefore, the Infinite Campus API allows the HR system to send complete Household information, but it also provides reasonable defaults for values the HR system may not have.

The primary reason for including households in the API is to allow the HR system to send employee address information to Infinite Campus. The address is used in Infinite Campus for various mailings sent to the Staff. Most of the Household fields in the API are not required and defaults are populated in by the API should the HR system not have them. See our Business Office Integration API Documentation link found in your credentials for a complete list of fields and default values.

An example record from an HR system that has no household information and basic address information is as follows:

  • household: 
    • householdLocations 
      • address 
        • fullStreetAddress: 4321 South Lexington Ave SE Apt 45
        • city: Blaine
        • state: MN
        • zip: 55123

Rules

Because of the complex relationships between Staff and Students in Households (e.g., staff that have students, staff members that share students, students that become Staff, etc.), the Infinite Campus API has the following rules:

  • If the staff member is being created, a new Household is created and marked as a "staff household." An existing address is searched for (based on address properties) and used if found. If no matching address can be found, a new address is created in Infinite Campus.
  • If the staff member is being updated and the household is a staff household and they are the only member of the household, the household is updated. An existing address is searched for (based on address properties) and used if found. If no matching address can be found, a new address is created in Infinite Campus.
  • If the staff member is being updated and that staff member is already included in a household along with other members, the household information from the API is ignored. This is to prevent the API from changing the address of any students that are already included in that household.

Addresses

HR systems generally associate addresses with employees and are only concerned that the address is a valid mailing address. If there are two employees that share the same address, they store the same address twice. Infinite Campus takes a different approach to addresses. In Infinite Campus, addresses are associated with household locations and those are associated with households. Staff and students can be members within the same household and therefore can all have the same address. For this and other reasons, Infinite Campus makes a concerted effort to prevent address proliferation.

Ideally, each address within a school district would only exist once in the database and a household location would related to one of those addresses. For example, the street address, "4321 N Lexington Ave. " should only exist in the database once and if two staff members shared that address, they would point to the same address record. Additionally, the Infinite Campus address should be normalized so that variations of an address do not add addresses to Infinite Campus. For example, the address "4321 North Lexington Avenue" should match "4321 N Lexington Ave. " otherwise a new address will be created. Instead, it should use the address that already exists.

To help prevent address proliferation, Infinite Campus breaks the street address down into its various components and the Infinite Campus API reflects those components. If the HR system stores the address similarly and can provide each of the individual properties, then that gives us the best chance of finding a matching address in Infinite Campus.

  • post office box
  • number
  • prefix
  • street
  • tag
  • direction
  • apt
  • city
  • state
  • zip
  • county
  • locationCode (seldom used)
  • tract (seldom used)
  • block (seldom used)

An example record for 4321 South Lexington Ave SE Apt 45, Blaine, MN, 55123 would be:

  • number: 4321
  • prefix: South
  • street: Lexington
  • tag: Ave
  • direction: SE
  • apt: 45
  • city: Blaine
  • state: MN
  • zip: 55123

If the address is a PO Box, you are only allowed to specify the number of the PO Box. If other parts of the address are also included, an error is returned. An example record for a PO Box 54, Blaine, MN, 55123 would be:

  • postOfficeBox: true
  • number: 54
  • city: Blaine
  • state: MN
  • zip: 55123

If Infinite Campus does not find a matching address based on an exact match, it takes the parts of the street address, puts them together, and re-parses the street address. If Infinite Campus still cannot find a matching address, it creates a new Address based on the new parsing and will not necessarily match the original address passed in.

If the HR system does not or cannot break the address into the various properties, it can use:

  • fullStreetAddress

An example record for 4321 South Lexington Ave SE Apt 45, Blaine, MN, 55123 would be:

  • fullStreetAddress: 4321 South Lexington Ave SE Apt 45
  • city: Blaine
  • state: MN
  • zip: 55123

The Infinite Campus API takes the contents of the fullStreetAddress and attempts to parse it into the various address properties and search Infinite Campus for a matching address. If no address is found, it creates a new Address based on the parsing algorithm.

Rules

  • The API only accepts fullStreetAddress or the other street address properties. An error is returned if both are specified.
  • The parsing of the address expects the address to be a typical address format. Example addresses are: "4321 109th Ave Northwest" or "4321 W 109th Ave NW" or "P.O. Box 125" or "12500 South 42nd Gardens Apt 123". This usually appears as a number, followed by an optional direction, followed by a street, followed by another optional direction, followed by an optional apartment, and an optional apartment number.

Infinite Campus HR API Best Practices

Initial Setup

These are the items that only need to be done once:

Clean Infinite Campus Staff Numbers

Local Staff Number in Infinite Campus must match the staff number from the HR system. Ideally, customers that already have Infinite Campus and the HR system already have these matching. There is a report in Infinite Campus that can help find problems with the Local Staff Number in Infinite Campus: System Settings > Business Office Integration > Business Office Synchronization > Check Campus Data.

Gathering Client Credentials

Using the OAuth2 credentials provided in Infinite Campus (System Settings > Business Office Integration > Business Office API Credentials), ensure that you can log in from the HR system. Access to the Infinite Campus API is controlled via OAuth2 credentials. Use the Client ID and Client Secret in the authentication request to receive a token that must be the used on every API call. These credentials, along with our API Swagger documentation, can be found in the Credentials section of Business Office Integration.

FieldDescription

Client ID

Identifier for apps using OAuth 2.0 authentication.
Client SecretSecret known only to the application and authorization server. It protects resources by only granting tokens to authorized requestors.
Token URLA URL to give you access to permissions in Infinite Campus.
Base URLYour Infinite Campus site.
Business Office Integration API DocumentationA link available to the Infinite Campus Swagger documentation for staff integration and synchronization.
Show SecretToggle whether or not every character in the Client Secret is shown.
Generate New SecretThe button used to generate a new secret for authentication.

WARNING: This should ONLY be used if you feel the current secret has been compromised. If you generate a new secret, this new secret must then be used by the HR system to generate a new token. Until that happens all API calls from the HR system will fail.

Create any necessary mapping tables

A few of the properties used in the API require that valid values from Infinite Campus be used. The API includes GET methods to retrieve the values from Infinite Campus. If the HR system has different values for the same data, the HR system will have to map their values to Infinite Campus values. These include:

  • schoolNumber A list of valid schools can be obtained from:
  • gender A list of valid genders can be obtained from:
  • assignmentCode A list of assignmentCodes can be obtained from:
  • titleCode While the API will create the titleCode if no matching titleCode is found in Infinite Campus (as the HR system is the system of record of titleCode), the currently loaded titleCode from Infinite Campus should be used and can be obtained from:

Synchronize Infinite Campus with the HR System

Use the synchronization APIs to update Infinite Campus with all the existing staff in the HR system. For more information on the synchronization process, see the Business Office Staff Synchronization API section of this article.

Day to Day Operation

The Infinite Campus HR API gives you the ability to dynamically create/update Staff information at the same time as the information is created in the HR system.

Creating a new Staff Member

When creating a new staff member in the HR system, search for the staff member in Infinite Campus first. This should be done even after the mass synchronization has taken place. The mass synchronization only updates staff members whose staff numbers match between the systems. It does not ensure that all staff members in Infinite Campus exist in the HR system. There may exist Staff in Infinite Campus that were terminated years ago that have no HR Records. You can perform a staff search using the following call:

If the search returns a matching staff member and the HR system determines this to be the same person, the HR system should update the staff member instead of creating a new staff member. If the HR system determines the data to be incorrect in Infinite Campus, it should stop processing, have the district fix the information in Infinite Campus, and then process it again.

Additionally, it is best to search for an existing address based on the user input and use the address found in Infinite Campus to help prevent address proliferation in Infinite Campus. The address search API is:

This API returns the address properties which can then be used for the staff member to create/update.

Finally, the API call to create the staff member is:

The position properties for creating a staff member are optional. However, a person is not considered a staff member in Infinite Campus until they have position data. It is not required during the creation of the staff member because the creation of a staff member and the assigning of positions are separate functions in some HR systems. See Adding a new Position to an existing Staff Member for more information.

Updating an existing Staff Member

The update API uses the same properties as the creation API, but there are some significant differences.

Infinite Campus stores names in an identity table that is separate from the person table. If a name changes, the API end dates the existing identity, creates a new identity, and sets a start date as the date of the API call.

If position properties are included on the API call, the Infinite Campus API assumes that these are all the positions for the staff member being updated. It will attempt to remove any positions that currently exist on the Staff Member that are not included on the API properties and create the positions included. Usually, removing a position in Infinite Campus is not possible as it is linked to other activities in Infinite Campus. The best practice would be to always include all positions the staff member has ever had on the call and set an end date on any no longer valid. The other alternative would be to leave positions off the update API call, and then use the positions API to update and add positions to a user.

The API call to update a staff member is:

Adding a new Position to an existing Staff Member

Positions must be added to a Staff Member before they are considered Staff in Infinite Campus. If the staff member does not have any positions, they cannot be found when searching for Staff in Infinite Campus. A position requires an Infinite Campus schoolNumber, startDate, and titleCode or assignmentCode. There is no unique identifier to a position, so the API does not fail if you create two positions with the same values. Creating two positions with the same values will make it difficult for the Infinite Campus user to identify one from another.

The API for creating a position is:

Updating an existing Position for a Staff Member

Use caution when updating a position because there is no unique identifier for a position. All that can be updated on a position is either the start date or the end date. The school, assignmentCode, and/or titleCode are used to identify the position to update.

If multiple positions are found that match the properties of the position, all matching positions are updated.

The API for updating a position is:

Special Considerations

An existing Student/Parent in Infinite Campus becomes an Employee

There are times when a Student or Parent gets hired by the district. When this happens, the HR system searches Infinite Campus looking for the person with a matching staff number. The HR system will not find a match and it will use the Infinite Campus API to create a new Staff Member in Infinite Campus. Likewise, the Infinite Campus API will not find a match based on staff number, so it will create a new person in Campus and give them the new staff number. The same person will then exist in Infinite Campus twice, once as the Student/Parent and once as the staff member.

To resolve this, the district can use the Combine Person tool to remove the duplicate person. When using the Combine Person tool, it is important to set the "base person" as the new Staff Member.

Business Office Staff Synchronization API

The Administration and Synchronization tools in Business Office Integration allow districts to sync their staffing information from their HR system to Infinite Campus, mirroring their user information. Infinite Campus must have a unique staff number for every staff member being synced to a staff member in the HR system. This is important because the transfer will be syncing staff members based on their staff numbers matching in both systems. When a staff member is synced to Infinite Campus, their fields become read-only in Infinite Campus. Any further updates must be performed via the API. See Day to Day Operations for more information.

The Synchronization process is intended to only be run once (when the district first decides to integrate the HR system). However, some HR systems will not have implemented the API for Day to Day operations. For those HR systems, the district may decide to run the synchronization process on a regular schedule to help keep the data consistent. The Synchronization process compares all the staff in Infinite Campus and all the staff in the HR system, so it will use considerable resources on the Infinite Campus system. It is recommended to run the synchronization during off hours.

Verifying Infinite Campus Data

The Check Campus Data feature in Synchronization is used prior to starting the synchronization to check for areas of possible trouble during the sync process. This produces a report that is used to verify that each staff number in Infinite Campus is unique, finding any staff with duplicate staff numbers or no staff numbers. After the report has been generated, the district then has to manually change the data in Infinite Campus if there are any discrepancies.

  1. Click Check Campus Data. A report will be generated in a new tab with all staff with duplicate staff numbers and with no staff numbers.
  2. Update all staff numbers in Infinite Campus. 
  3. Repeat these steps until you've run a report that is satisfactory with your data.

Business Office Integration Staff Synchronization

After data has been cleaned and credentials have been gathered, a sync can begin. There are two ways to sync staff: 

File Upload should only be used by preferred HR vendors.

Using the API for Staff Synchronization

Prior to starting a Staff Synchronization, please open and review the Business Office Integration API Documentation link found in your credentials to review Infinite Campus endpoints.

  1. Use the start endpoint with a token to begin the process of syncing in new staff.
  2. Use the transfer endpoint to transfer HR staff to Infinite Campus.
    • The transfer API uses the same schema for the staff member objects as the create and update API. It has the same requirements for the various attributes and the API will fail if any of those requirements are not met. A successful transfer does not guarantee that you will be able to successfully commit the data. The commit will perform additional validation that may fail and need to be fixed.
  3. Use End Transfer to end the sync.
  4. Use validate API:
    • The validate API is intended to return information on the changes that will happen in Infinite Campus when the data is committed. It is intended to present this information for the school to have a complete understanding of what will change in Infinite Campus. The information includes the demographics, district employment, and district assignments that will change. It also includes a list of addresses and staff members that will be added.
    • Can create a report from this data.
    • Returns any conflicts/errors between staff in each system.
    • If you change HR system data, restart the synchronization from step 1.
    • If you change Infinite Campus data, repeat step 4.
  5. Use Commit API.
    • There are two different APIs which can be used to commit the changes: 
      1. Use the following API call if there are a small number of staff members that need to be synced (less than 500). This API will not return until all the staff members have been synced. The advantage of this API is that it will return a list of successfully transferred staff and a list of any failures. The disadvantage is that the API will not return until all staff members have been synced. Since syncing staff members in Infinite Campus can take a significant amount of time, be careful to not lock users out while invoking this API.

      2. Use the following API if there are a large number of staff members that need to be synced (more than 500). This API does not wait for all the staff members to be synced. Instead, it creates and starts a background job in Infinite Campus that updates the staff. The advantage of using this API is that it will return quickly, so there is no fear of HTTP timeouts happening or locking in the HR system when the API is called. The disadvantage of this API is that the results of the synchronization in Infinite Campus are not returned to the HR System. Instead, the customer will have to look in the Business Office Error Log to see any errors. They can use the Business Office Notification tool to receive notifications when a sync is complete.


        After you have used the submitCommitJob API, use the following API to determine the status of the most recent Campus job. Invoke this API as often as needed:

WARNING: Be sure that all your data is valid before proceeding with the Commit step. Once a synchronization has been committed, the data cannot be changed in the Infinite Campus UI. It can only be changed by performing another sync.

BOI Staff Synchronization Tool

  1. Click Start Sync.
  2. Use the transfer endpoint to transfer HR staff to Infinite Campus.
    • If the transfer is being done via file upload, click Transfer Staff Via File Upload.
    • Transfer Staff Via File Upload is only intended to be used by HR systems that have not implemented the API.
  3. Click End Transfer.
  4. Click Validate. This will produce a report that returns any conflicts/errors between staff in each system.
  5. If you change data within the HR system, click Restart Transfer.
  6. If you change Infinite Campus data, click Validate.
  7. Click Commit. The sync is now complete and synced data for all staff members will now be read-only.

WARNING: Be sure that all your data is valid before proceeding with the Commit step. Once synchronization has been committed, the data cannot be changed in the Infinite Campus UI. It can only be changed by performing another sync.

Business Office Error Log

The Business Office Error Log allows users to capture error transactions while using Infinite Campus Business Office Integration. It's a log that shows all of the errors that have occurred when trying to sync HR systems with Infinite Campus. An "Export to PDF" button lets users download the error log. There are five columns: Error Date, Action, Path, Error Message, and Payload.

FieldDescription
Error DateDisplays the date the error occurred.
ActionThe method used to call the endpoint.
PathEndpoint path that the error targeted.
Error MessageDetailed message on the error that occurred.
PayloadButton link to the message request body that was sent in that caused the error.

Business Office Notifications

The Business Office Notifications allows districts that have synced their HR system with Infinite Campus to generate notifications in Campus when an HR system has created a user, updated staff, or updated staff district assignments. There are two different types of notifications: HR-Staff and HR Sync Commit. In order to add staff from the Recipients drop-down, users must have tool rights to District Employment and/or District Assignments. Users who have been notified will receive the notification in their Message Center.

To edit or delete a notification, you need to click an existing notification, and then either change the type or add/remove recipients. If all the recipients are removed, a notification is deleted.

Adding a Notification

  1. Click New.
  2. Select a notification Type.
  3. Add participants by typing their name, username, or selecting them from the drop-down.
  4. Recipients can be removed by clicking the X button next to their name or the larger X button on the right edge of the selection box.
  5. Click Save to enable the notification.

Related Articles

Was this helpful?
Thank you for your feedback!
User Icon

Thank you!

Copyright ©️ 2010-2023 Infinite Campus, Inc. All rights reserved. | Terms of Use | Privacy Policy | infinitecampus.com