This page describes configuring third party products which use the USPS and USAS SOAP services.
The USxS Redesign applications contain a compatibility layer which implements the Classic SOAP services. The goal of the services is to provide vendors using the Classic SOAP API a seamless migration for districts implementing Redesign. However, given the inherent differences between the Classic and Redesign data model, there are some differences in behavior. These are described in the following pages:
Most of these changes are believed to be minor and not affect third party developers using the SOAP APIs. In general, the unsupported methods were developed to support the SSDT's own web applications, which are now obsolete. Any vendor impacted by the changes should contact the SSDT at email@example.com. If possible, we will modify the Redesign services to provide compatibility.
Configuring the Redesign SOAP services endpoints is effectively the same as Classic. Each vendor requires an "endpoint" to reach the service. In Classic, a single ITC endpoint to could be used to access multiple districts. Because Redesign is a single-tenant system, each district will have it's own endpoint.
Assuming the ITC using a separate domain name per district and application (i.e. using nginx-proxy described elsewhere), then each district and application will have a unique domain name. For example, suppose that USPS and USAS for Sampletown Schools instances are running at
*.demo.ssdt.io, then the following table shows the SOAP endpoints:
|Application||Application URL||SOAP Endpoints|
Notice that the path to the services is identical to the Classic ITC endpoints. You may append "?wsdl" to the endpoints to retrieve each services API documents.
In classic, it was common to provide each vendor a OpenVMS username which could access one school district's USAS or USPS data. This user was typically granted a "standard" or "read-only" identifier depending on the type and level of access required by the application.
Under Redesign, the same basic idea applies. In each districts instance, it will be necessary to create a user to be used by the vendor application and appropriate role assigned to the user. A simple solution is to create a username (with password) in the districts instance and then assign one of the standard Redesign roles which simulates the Classic identifiers. For example, if a Classic application required OECN_USPS_RO, then you could grant the STANDARD_READONLY_USER role in USPS-R.
However, because Redesign provides much finer control over access levels, it would be preferable to create specific roles for each application which grants exactly the permissions needed by the application. For example, the MCOECN Kiosk requires read only access to a limited number of objects. Therefore, we recommend that a custom role be created for each application to grant only the permissions required by the application. Using Kiosk as an example, role "KIOSK" would be created with the following permissions:
This grants the Kiosk access to only the objects it uses and restricts it to view (read-only).
USAS-R has a predefined role named EMIS_SIF available with the following permissions:
EMIS SIF Agent Integration
In each district instance of USxS-R, it will be necessary to create a user to be used by the EMIS SIF Agent. For USAS, the EMIS SIF user should be granted the EMIS_SIF role (USAS-R release 7.7.0 and above). For USPS, the EMIS SIF user will need to be granted standard access, STANDARD_USER. The username and password created for the EMIS SIF account will need to be entered into the USxS SIF Agent zone configuration.
A certificate for USxS-R SOAP will need to be added to the SIF agents keystore. Follow the information found in Configuring Agent SSL Keys for adding the certificate to the keystore.
The zone (district) SOAP Connection will need to be updated in the USxS SIF Agent for the SOAP endpoint and EMIS SIF user account. In the SIF Agent console, select the zone to be updated, select Zone Settings from the menu then select SOAP Connection on the left. Enter the district specific SOAP endpoint for EMIS (see above for endpoint examples) into the SOAP URL. Enter the username and password of the EMIS SIF user account that was created.
A district user with permission to System Configuration in USxS-R will be responsible for updating the EMIS configuration data. Both USPS and USAS have an EMIS SOAP Service Connection menu option from System Configuration. This is where the district will indicate which fiscal year data is being collected for.
Configuration of the SOAP endpoint at the zone level requires
- USAS SIF Agent Version 2.0.5 or higher
- USPS SIF Agent Version 2.0.4 or higher
Certificate/TLS issues have been encountered between USxS-R and the EMIS SIF Agents. Many of these issues may be resolved by updating to Java 7, 32 bit on the SIF Agent server.