Page tree
Skip to end of metadata
Go to start of metadata

This document contains guidelines on how to configure integration between the Ohio SIF agents developed by Pearson Data Solutions (formerly Edustuctures) and the USAS and USPS SOAP services. Starting with USAS SOAP Version 2.5 and USPS SOAP Version 1.4, a special set of services provide integration with EMIS-R SIF vertical reporting requirements. Note that the services only provide SIF vertical reporting, there is no horizontal SIF capabilities provided by the service or SIF agents.

This document assumes you have already reviewed the Ohio SIF Agent documentation from Edustructures and will not contain detailed instructions on how to install or configure the agent. Rather this document will cover the the backend OpenVMS configuration and how the agent interfaces with the SOAP services.

Version Requirements

The current Ohio SIF Agents require the following minimum versions of the SSDT web applications:

  • USAS SOAP Version 2.7-0
  • USPS SOAP Version 1.8-0

The WAR files can be obtained by OECN ITC's from OECN_DOWNLOAD.

These are standard releases of the SOAP Services and the same ones used by the SSDT Web Applications and other software vendors. To prevent version requirement conflicts between EMIS and other vendors, you may wish to install these applications in a separate context then those used by other third parties.

Additional information regarding installation and configuration of the SOAP services can be found at Web Application Technical Documentation Roadmap.

Configuration Requirements

The Ohio SIF Agents for USAS and USPS require three pieces of information in the global and zone specific configuration:

  • Global:
    • SOAP_Service_URL
    • Master Username and password
  • Zone:
    • District code (SETUPENV code)

The following sections discuss these in more detail.

SOAP Service URL

This is the URL where the USAS or USPS SOAP service is installed. This must be full URL to the EMIS service within the respective application service:

For USAS:

http://{server}[:port]/{context}/services/USASEMISWS

For USPS:

http://{server}[:port]/{context}/services/USPSEMISWS

Where {server} is the host name or IP address hosting the service and {context} is the context where the SOAP service is installed.

You may also use "https" if you prefer to encrypt the traffic between the agent and SOAP service.

Verifying SOAP Version

For USAS:

http://{server}[:port]/{context}/services/USASWS?method=getVersion

For USPS:

http://{server}[:port]/{context}/services/USPSWS?method=getVersion


Master Username

Each installation of the Ohio SIF agents for USPS and USAS will need a "master usermame" to access the data on the OpenVMS server. This should be a standard OpenVMS username which has at least OECN_USAS and OECN_USPS, or may have OECN_SYSMAN. It must have at least read-only access to each district's USAS files and read-write access to USPS data.

Write access to the USPS data is necessary to permit the EMIS-R process to assign Local Staff Ids (Z-Ids) to staff without a Credential ID. This process requires at least write access to EMSLID.IDX, USPEMP.IDX and the USPAUD.SEQ file.

For district's using the "Original Method" for "Pay Date Method" in USPCON, the SOAP service will require Write access to ABSDET.IDX. This is due to the way that pay date calculation is deffered and done "on the fly" by underlying USPS routines. This limitation may be removed in a future release.

Each ITC can determine the best option for granting access to the district data files. A single privileged account (e.g. with SYSPRV) might be used or a non-privileged account with ACL's to grant access to files.

The Ohio SIF agents require a single username per agent installation. The above configuration assumes the ITC controls both the ZIS and agent configuration. Therefore, only ITC personnel should have access to the master username and password. If a school district is given direct administrative control over their own agent, then a separate install of the agent should be used with a district-specific username.

District Code

The district code on the zone specific settings must be set to the "SETUPENV" code for the district specified by the zone. In most cases, this will be the same SETUPENV code used by the district to access USAS and USPS Web Application. There should not be a need to create a special SETUPENV entry for use by the EMIS Agent. The only exception might be if it becomes necessary to access an "archived" (prior fiscal year) USAS/USPS database. In that case, a SETUPENV code may be needed to point to the archive.

Depending on how the OECN$SETUP file is defined, you can use the SETUPENV code, and IRN, or NCES code for the district in the Agent's zone settings. However, if you use IRN or NCES code, the code must be unique within the SETUPENV file. SETUPENV's behavior is undefined if there are multiple entries with the same IRN or NCES code.

Note: The SIF Agent console interface make it appear that the agent can use the "Global Settings" for the agent. However, this is not the case. The global settings for the Agent should not contain a district code. Rather, each agent zone must be defined with a specific code.

Trouble Shooting

If the SIF Agents are not able to return data from the SOAP services, it may be a configuration problem with the Agents ability to communicate with the SOAP service, or the configuration of the master username ability to access the district's data. The current versions of the Ohio SIF Agents from Edustructures do not test for some type of errors from the SOAP services, so errors are not logged in the Agent's log files.

Below are several steps you can take to diagnose connection problems with the SOAP service.

  • Login to the USPS Webapp or USAS Webapp using the master username and password being used by the agent to login to the SOAP service. Make sure you can select the district and query for Employee's (USPS) or Budget Accounts (USAS).
  • If you suspect authentication problems, on OpenVMS do:

    $ REPLY/ENABLE=SECURITY

    Attempt a data collection and watch the VMS security audits for login failures or break-in detections.

     

  • Check the OECN$VXS_LOGS. Search the logs for the master username to find the appropriate logs. If a log is not being created for the username, then suspect an authentication problem or a connection problem between the Agent and SOAP service (check the Agent logs for the latter). If a log is created, check for any errors related to setting the environment and protection violations related to access either the programs or data files.
  • No labels