XVault First Line User Guide

How does XVault collect data?

Groupcall XVault uses Groupcall Xporter to interface with source data systems such as school MIS systems.  The link between each individual Xporter and XVault can be

  • SIF Data via Groupcall Dashboard (Dash-SIF)
  • SIF Data via SIF Zone Integration Server (SIF)

In either case the presentation of data to systems querying XVault is still the same, via Web Services or SQL.

Xvault_Data_Collection

 

In both configurations XVault will;

  1. make a request for the objects in the collection template for each school,
    • using the schedule configured, and
  2. await the responses.

How does XVault know what to collect?

XVault supports multiple collection templates.  Each collection template specifies what SIF data objects to collect, when to collect them and whether to also listen for events generated by the source agents.

XVault supports one collection template per SIF Zone – i.e. one collection template per school.

XVault Database

The XVault database should be located on a physically secure server that is appropriately configured to prevent unintended access. Each system accessing the database requires a separate SQL user account with a strong password. Systems reading data from the XVault database should be constrained to a specific view or set of views per accessing system.

Groupcall recommends that the SQL platform or underlying system is encrypted in order to protect data.

XVault Application

The server on which the XVault application is installed on should be physically secured and appropriately configured to prevent unintended access. XVault only permits incoming connections to its Web Services interface and to its web-based management console. XVault will make outgoing connections to https://dashboard.groupcall.com/ and to any SIF Zone Integration Server that it is configured to contact.

Although the XVault application does not store any sensitive data locally (only into the XVault Database), Groupcall recommends that the server or underlying system is encrypted to prevent unintended release of the SQL server credentials or SIF SSL private keys.

XVault SSL Encryption

The XVault application runs on top of Apache Tomcat, the current version of Apache Tomcat is 7.0.

Data transfer is always SSL, therefore to protect the management interface you need only enable SSL encryption for the web service and management console. The management interface only shows what data objects to request and when they last arrived; it doesn't show the data itself.

To enable the appropriate SSL configuration instructions, apply them to Apache Tomcat and restart the Apache service.

XVault SQL Configuration

XVault requires that an SQL database is created, typically called XVault, and that it is assigned an SQL user with owner rights to that database.

The SQL server must be configured to support TCP/IP connections, typically via port 1433/tcp

Upgrading XVault

Due to the nature of most deployments XVault does not currently auto-update.  When you log into the Web Management Interface you will be advised if a newer version is available.  Groupcall recommends that you run the latest version of XVault for all security benefits, bug fixes and access to new features.

To upgrade XVault follow the link in the Web Management Interface and download the install/upgrade tool.

Ensure you back up your database as necessary.

Run the installer/upgrader tool which will stop Apache Tomcat, upgrade XVault then start Apache Tomcat.

Using the XVault Management Console

By default the XVault Web Management Interface is accessible via http://localhost:8080/Groupcall/.

The following sections are shown in the XVault Web Management Interface:

  • Agent – this is where you configure Agent-specific settings for XVault.
  • Zones – lists all configured zones, and the school name if detected.
  • Error log – shows any error messages received or generated by XVault.
  • SIF Log – shows the current SIF activities being carried out by XVault.

 Agent Configuration

The Agent configuration screen allows you to adjust the verbosity of the agent logging, configure Collection Templates and restart the XVault Embedded SIF Agent without restarting XVault entirely.

Adjusting Agent Logging Verbosity

To increase logging information select Debug, under Log Level.  Stop and Start the XVault Agent using the Stop Agent button then clicking again when it turns into the Start Agent button.

The additional logging output will be stored in C:\Program Files\Apache Software Foundation\Tomcat 7.0\Logs\stdout.log

This option generates extensive logging, you should revert to INFO or WARNING as soon as possible and restart the agent.

Restarting the XVault Embedded SIF Agent

The XVault Embedded SIF Agent is used for both SIF and Non-SIF zones.

Click the Stop Agent button and allow up to 30 seconds per configured zone for the embedded agent to stop.  When the button changes to say Start Agent, click Start Agent.

Configure Collection Templates

Please see the separate section entitled Configuring Data Collection.

Zones

Clicking on Zones will show you a list of all configured SIF zones.  Zones where the school name can be autodetected (i.e. where a SchoolInfo object has been collected) will have the school name shown beside them.

Adding a new SIF Zone

Click on Zones to add a new SIF Zone to XVault.  You will need to know the Zone ID and Zone URL from your ZIS operator, and you will need to install Xporter as a data provider in the zone using the same Zone ID and Zone URL.  The Xporter installation will need to be on the MIS server for the school that the zone serves.

  • Enter the Zone ID as the Zone Name
  • UK convention sets the Zone ID using the school LEA+Estab numbers, e.g. 1231234
  • Enter the Zone URL into the Zone URL box
  • Select a template to use the agent settings or custom to select the SIF objects
  • Click Save to save the zone entry

If this is the first zone you have created on XVault then click on Agent and select Start Agent.  If not then data collection on the zone will be automatically started.

Adding a new Non-SIF Zone

New Non-SIF zones are created automatically by XVault when an Xporter installation reports that it is a provider for the XVault agent.

Once the Xporter installation has registered as a provider to the XVault agent the XVault agent will detect this within an hour and automatically create a zone for it, assigning the DashNewProvider template and commence data collection.  If you have followed the recommended configuration then this will result in XVault requesting the SchoolInfo and LearnerSchoolEnrolment objects.  As a result the school name should be shown in XVault shortly after the zone is auto-created.

As part of the feedback loop on new installations you should manually migrate schools over to the correct template, using DashNewProvider as a safety net to detect misconfigured installations and/or accidental providers.

View Zone Status

In the Navigation pane click on the Zone you wish to enquire about.  The zone configuration page will load and show all SIF Objects configured in the assigned Collection Template.

For each SIF Data Object the page will show the Last Sync’d time, which is the last time XVault requested that object from the zone, and the Last Recv’d time, which is the last time data was received.

Update a SIF Data Object on demand

In the Navigation pane click on the Zone you wish to enquire about.  The zone configuration page will load and show all SIF Objects configured in the assigned Collection Template.

Click on the Sync icon for the object you wish to refresh.  XVault will request data from the zone and, hopefully(!), the data will be returned.  Note that depending on infrastructure and transport this can take up to 15 minutes, you can monitor the progress of the request by viewing the SIF Log.

Rebase a Zone

In the Navigation pane click on the Zone you wish to enquire about.  The zone configuration page will load and show all SIF Objects configured in the assigned Collection Template.

Click on the Resync button and confirm.  XVault will delete all data held for the zone and will request all data again from the zone.

Disable or Enable a Zone

In the Navigation pane click on the Zone you wish to enquire about.  The zone configuration page will load and show all SIF Objects configured in the assigned Collection Template.

Untick Is Zone Active to disable the zone and click Save.  This change will take immediate effect and XVault will disconnect from the zone and stop requesting data.  The data already in the XVault Database will be retained.

To re-enable a zone, tick Is Zone Active then click Save.

Delete a Zone

In the Navigation pane click on the Zone you wish to enquire about.  The zone configuration page will load and show all SIF Objects configured in the assigned Collection Template.

Click Delete and confirm.  XVault will delete all data held for the zone and permanently remove it.  If the zone is a Non-SIF zone and you wish to add it back again at a future date then you will need to add it manually.

Error Log

This will show you a collated view of all error messages received via SIF by XVault and any internal errors raised by XVault along with the date on which they occurred and details of the error.

You should check the Error Log periodically and address any issues that arise.  For example you may find error messages indicating that certain SIF objects are not available in a given zone, in which case you should investigate the ACL for that zone and ensure that the Xporter SIF Agent installation for that zone is correctly configured.

The error log is also surfaced in the SQL database so that automated processes can read and monitor it.

SIF Log

The SIF Log shows all current SIF actions along with their associated Zone, SIF Object and unique message identifier.

A message will either show Registration or Deregistration to a zone, or will show a data request being made.  Where a data request is made it will show Requested then Processing then Processed.  A statistic will show how many packets and records were returned.  If a request fails then the error message is shown and also logged to the Error Log.

XVault Data Collection

Configuring a Collection Template

A data collection template is assigned to a zone to detail the SIF objects to be requested and the schedule to carry out those requests.  A collection template also determines whether a zone will listen to any SIF data events created by the Groupcall Xporter SIF Agent.

Selecting the SIF Data Objects to Collect

Click on Agent in the Navigation pane of the XVault Web then scroll to the Collection Template you wish to configure.

All SIF Objects that are allowed on the XVault are listed in the Collection Template.  For each object tick both, either or neither of the two tick boxes accordingly:

  • Can Subscribe – this means that XVault will carry out request/response on this object in any zone where this template is applied.
  • Handle Events – this means that XVault will subscribe to events and process any events created by the Xporter SIF Agent in any zone where this template is applied. For Non-SIF zones, must be selected for SchoolInfo, but is not required for any other objects.

When completed click Save, this will reassign the template to all zones configured to use it.

Data Collection Schedules

Click on Agent in the Navigation pane of the XVault Web then scroll to the Collection Template you wish to configure.

The Sync Time column shows what time XVault will request each SIF object from each zone where this template is applied.  A number of options can be entered, by default XVault is set to request every 24 hours from the time the XVault application started.

  • Periodic collection – enter a number into the Sync Time column, this will be interpreted as the number of hours between queries.  E.g. enter 48 to have data collection every 48 hours.
  • Scheduled collection – enter a time to fire the request message at, e.g. enter 13:00 to have the request message sent to each zone at 1pm.
  • Scheduled randomised collection – enter two times to give a window for requests to happen within, e.g. enter 13:00-15:00 to have the request message sent at a random time between 1pm and 3pm in each zone.  Note the exact time is randomised per zone.
  • Day-specific – enter MONDAY:13:00 to have collection at 1pm on a Monday, or enter MONDAY:13:00-15:00 to have a random collection between 1pm and 3pm on a Monday
  • Monthly - Enter 1st to collect on the 1st day of the month. Comma separate for multiple days, e.g. 1st,5th,20th
  • Multi-day – Enter schedules separated by commas to have collection on multiple days, e.g. MONDAY:13:00-15:00,WEDNESDAY:13:00-15:00,FRIDAY:12:00-14:00

When completed click Save, this will reassign the template to all zones configured to use it.  Collection schedules will only apply where the Can Subscribe box is ticked; this is because it affects the time a request is sent.  XVault cannot determine the time that Xporter SIF Agents process requests and deliver responses, or the time that they generate events.

 

Learner Attendance Collection

The LearnerAttendance SIF data object in XVault collects only today and yesterday’s sessional attendance.  However it is also useful to collect sessional attendance twice a day, once in the morning and once in the afternoon.  For this reason the LearnerAttendance object is defined twice in the default configuration to allow you to set different collection schedules for the LearnerAttendance (e.g. 09:30-10:00) and LearnerAttendance.PM (e.g. 14:30-15:00) objects.

If you require LearnerAttendance to be collected only once a day then collect only LearnerAttendance and enter the schedule to suit your needs.  You can just untick the LearnerAttendance.PM object in this case.

Monitoring Data Collection

Groupcall XVault can report its data collection statistics to Groupcall Dashboard, which can then provide an aggregated view of all data collection zones.  The aggregated view highlights zones where data has not recently been received and allows you to drill in to get additional information about the number of records held and when they were last received.

If you would like to make use of this functionality please contact sales@groupcall.com.

Troubleshooting XVault

Where to Troubleshoot

As part of a complex infrastructure XVault may report errors that are caused by other components in that infrastructure.  When diagnosing any issue you should also investigate the ZIS logs (if present) and the Xporter installation.  For the Xporter installation there is the Xporter First Line User Guide, which can aid diagnosis and resolution of the most common issues.

.net Error when accessing Web Management Console

Groupcall XVault is written in Java, running atop the Apache Tomcat platform.  If you receive a .net error when accessing Tomcat usually indicates that you’re trying to talk to something else other than XVault.  Typically this occurs when testing on a SIMS Workstation PC, where the Tomcat port conflicts with the SIMS Document Server; see the instructions in Appendix Three to resolve this problem.

XVault Navigation bar has no entries

This indicates that the SQL connection required by XVault is not working.  Confirm the credentials by logging into the SQL server using them and confirm that TCP port 1433 on the SQL server (or alternative port) is accessible from the XVault server.

Correct the Configuration.Properties file accordingly then restart Apache Tomcat to apply the changes.

I need to enter a proxy – where do I enter it?

Proxy settings must be entered into Apache Tomcat, which supports separate proxies for HTTP and HTTPS.  Typically the HTTP proxy will be used to access http://www.groupcall.co.uk to check for updates and the HTTPS proxy will be used to connect to https://dashboard.groupcall.com/.

    1. Run the Configure Tomcat tool that was installed with the Apache Tomcat application.
    2. Go to the Java tab
    3. Add these additional lines to the Java Options panel, preserving what is already present.
      • –Dhttp.proxyHost=<proxy server>
      • –Dhttp.proxyPort=<proxy port>
      • –Dhttps.proxyHost=<proxy server>
      • –Dhttps.proxyPort=<proxy port>
      • Click OK then restart Apache Tomcat to apply the settings change.

If you have proxy exclusion requirements then add two lines in this format, adjusting for your IPs:

    • -Dhttp.nonProxyHosts=10.*.*.*|172.16.*.*
    • -Dhttps.nonProxyHosts=10.*.*.*|172.16.*.*

If you require proxy authentication then run the Tomcat service as a user permitted to access the proxy, with local administrative rights.

Getting Additional Diagnostic Information

The XVault application keeps additional logs when running, the verbosity of which can be adjusted via the XVault Web Management Interface.

These logs are located in C:\Program Files\Apache Software Foundation\Tomcat 7.0\Logs.

    • Catalina.log – shows the logs for Apache Tomcat starting the XVault applet.
    • Stdout.log – shows the operational output for XVault

Getting Help

In the unlikely event that you run into a problem with your installation then the organisation you need to contact will depend on where the fault lies.

For ZIS errors, you should initially contact your ZIS operator for advice.

For Groupcall Xporter errors you should contact the partner with first line responsibility for Xporter, they will elevate a case to Groupcall if required.  Your organisation might be the partner with first line responsibility for Xporter.

For Groupcall XVault errors you can contact Groupcall Xporter Support. If you need to raise a case with Groupcall then please provide a zip containing all the Stdout.log files in the Logs folder to aid prompt analysis.

 

 

Next Steps...

If you need any further assistance or get in to any difficulty, then please contact Groupcall Support. If the issue affects Groupcall Partner products you should refer to the support arrangements for that specific Groupcall Partner.

For issues regarding integration with XVault, Groupcall provide consultancy services to assist you in integrating with XVault quickly and efficiently based on your specific needs.  If you’d like to engage these services then please contact your Implementation Consultant or Account Manager.

…And Finally

Have you followed Groupcall on Twitter and Facebook? Stay informed, get the latest news, updates and useful tips on all of our products!