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

This article explains how to execute the importers from the docker host.

Requirements:

You must have:

  • SSDT Utils package installed and up-to-date
  • the district's compose project must be configured for USAS, USPS or both
  • Exports of USAS / USPS
  • If you have previously imported into this project, you MUST delete any existing data and volumes so there are no remaining components.  THIS IS DESTRUCTIVE and will remove all components for the project, so use with extreme caution and make sure you are in the correct project directory.

  • If you are removing JUST one (either usas or usps), you CANNOT use docker-compose down -v as this will take down both instances.  See below for an example on how to remove just one.

    ###To delete all (both usas and usps):
    
    docker-compose down -v
    
    ###  If you only need to remove USAS or USPS, not both.  (in this example USAS):
    docker-compose stop usasapp
    docker-compose stop usasdb
    docker-compose rm usasapp (answer Y)
    docker-compose rm usasdb (answer Y)

    You MUST do the following to find and remove the named volume.  If you have not stopped and removed the associated container first,  you will receive an error message.

    ### VERY IMPORTANT, make sure to find and remove the named volume. Then remove that volume
    docker volume ls ##(to make sure of the volume name)
    ##assume it returns xxxx_usasdata
    docker volume rm xxxx_usasdata

Step-by-step guide

The import scripts below are destructive.  Information stored in the database will be deleted including data, custom configuration options, installed modules etc.  You must not run these scripts in a district which already has data loaded, unless you intend to replace it.  Please note, if you are importing a district's data again, you need to follow the steps outlined in the above Requirements section in order to ensure a clean import.

  1. Navigate to the district's project to run the import
  2. The import scripts require environment variables to define the source and IRN to be imported.  You can use the same values for both USAS and USPS, if the files are in the same location.  Define the following environment variables as follows: 

    export IMP_IRN=999999
    export IMP_URL=ftp://username:password@vmsserver.example.org/
    export IMP_PATH=[.directory] 
  3. To import USAS, do: 

    /ssdt/prod/import-usas.sh

    If you prefer to execute the script in the background then:

    nohup /ssdt/prod/import-usas.sh &
  4. To import USPS, do: 

    /ssdt/prod/import-usps.sh

    If you prefer to execute the script in the background then:

    nohup /ssdt/prod/import-usps.sh &

Explanation

The import scripts assume that the district has been configured with the setup.sh script from /ssdt/prod.  The scripts do the following:

  • will automatically stop and remove any existing database and app containers for the district
  • create a new database container
  • launch the import utility.  This creates a temporary container for the importer and attaches to the database container.  The import process runs in the foreground and will tie up the console until completed
  • after completion, the temporary import container is removed and the app container started

After completion, the directory will contain log file(s) containing the entire import process.  You should review the logs to ensure successful complete and for errors which may need to be reviewed. 

After the import completes, it can time a while before the instance is up (the first time only).  There are adjustments being made and patches applied. Do NOT assume the instance is hung and restart the application; this can cause delays or issues.  Monitor the usxsapp logs while the patches are applying if errors are suspected.

Examples of typical USAS import errors

Examples of typical USPS import errors

Requesting SSDT Assistance Troubleshooting Errors

If the ITC and district cannot resolve import related errors, ITC staff can open a support request with the SSDT. Import logs can be securely transferred to the SSDT using the method described in Securely Send Files to SSDT for Support.

Post Import Recommendations

We recommend you immediately execute a backup after completing the import process. From the district's project directory do:

> /ssdt/scripts/backup-usas.sh

You will also want to review the post import procedures outlined for both USAS and USPS.  These documents can be found the in Appendix section of the online documentation.