Skip to main content
Liaison

Migrating Decisions from Outcomes to WebAdMIT

  1. Last updated
  2. Save as PDF

Overview

If you'd like to transfer decisions from Liaison Outcomes to WebAdMIT, you can do so using the Outcomes to WebAdMIT data migration process. This process uses a Python script to move decisions data from Outcomes to update decisions in WebAdMIT.

This works by following these steps:

  1. Outcomes exports a CSV file to an SFTP location.
  2. The Python script picks up the CSV file and uses the WebAdMIT API to update decisions in WebAdMIT.
  3.  The script archives the file for data retention and auditing purposes.

Prerequisites

To set up this migration process, you'll need to have the following in place:

  • A Windows server to host the Python script.  Since Outcomes exports data to an SFTP location, this Windows server can be collocated with the SFTP server. To set up the server, you'll need to:
    1. Establish an account with admin rights on the server.
    2. Install Notepad++ on the server to edit the Python script.
    3. Install Python on the server that hosts the script.
    4. Optional: If the SFTP server and the Python script are on two different servers, you'll need a script or batch file to move the data from the SFTP to the script server.
  • Decision parameters in Outcomes should be configured in prelaunch and production.

Setting Up Decisions in Outcomes

To configure decisions in Outcomes, review the Working with Decisions article.

WebAdMIT User Identities

To access the WebAdMIT API, you need an Institution Manager in WebAdMIT that can access data for all departments and programs at the university. You should have an Institution Manager account in the prelaunch and production environments. Once that is in place, complete the following steps in both environments:

  1. Log in to WebAdMIT with the Institution Manager account.
  2. Click Account on the top right to view Account Details.
  3. Click Edit My Account at the top right.
  4. Verify that your account has the correct organization assignments and program assignments.
  5. In the API Key section, click Generate New Key to generate a unique API key for your account.
  6. Click Show Key to view your API Key.
  7. Make note of the API Key, which will be required for the script and retrieving your identity ID.

Retrieving Your User Identity ID

  1. Make the following API call to retrieve your User Identity ID.
  2. Use CURL or POSTMAN to make the below API calls:
  • PRODUCTION
$ curl -n https://api.webadmit.org/api/v1/user_identities \
  -H "x-api-key: <ENTER YOUR API KEY>"
  • PRELAUNCH
$ curl -n https://prelaunch.webadmit.org/api/v1/user_identities \
-H "x-api-key: <ENTER YOUR API KEY>"
  1. Make sure to use the correct API Keys for PRELAUNCH and PRODUCTION.
  2. A successful API call should generate a status code of “200” with the following example response body:           
{
"href": "/api/v1/user_identities",
"user_identities": [
{
"id": 42,
"type": "Admissions User",
"association": "SOPHAS",
"institution": "Demo University",
"organization": "Demo University School of Public Health",
"cycle": "2014 - 2015"
}
]
}
  1. Make note of the number after "id":. Corresponding to the cycle for which you want your applicant decisions updated, this is the identity ID and is needed for prelaunch and production. This “id” is needed to retrieve the Decision IDs in the next section.
  2. If the API call is unsuccessful, then it will return a status code of 401. This means the user is not authorized to gain access to the API. Verify the user’s permissions in WebAdMIT and ensure the user has the correct organization and program assignments.

Retrieving the Decision IDs in WebAdMIT

  1. Make the following API calls to retrieve decision IDs in WebAdMIT.  The examples below are for production WebAdMIT. To use the below code for prelaunch, please use the following base URL: https://prelaunch.webadmit.org
  2. Retrieve the Decision ID by making the following call:
$ curl -n https://api.webadmit.org/api/v1/user_identities/:<ENTER USER_IDENTITY_ID>/decisions/
 -H "x-api-key: <ENTER YOUR API KEY
  1. A successful API call should generate a status code of “200” with the following example response body:           
{
  "href": "/api/v1/user_identities/1/decisions",
  "decisions": [
    {
      "id": 42,
      "name": "Offer Accepted"
    }
  ]
}
  1. Note all the IDs as they are listed one after the other. You will need the IDs to build the export in Outcomes.

Configuring the Outcomes Export

To move any data points from Outcomes to WebAdMIT via SFTP, you must configure an export in Outcomes. Before setting up the export in Outcomes, it is important to have the list of decision IDs, as shown previously. Then:

  1. Create an export in CSV format as outlined in the article Working with Application Exports. The script to move data from Outcomes to WebAdMIT expects a CSV file as an input.
  2. Create the name of the CSV file without a date parameter, as that is something the script will handle as part of the archiving process.
  3. The CSV file should contain column headers.
  4. The script  expects the export fields to be in this order:
    • CASID
    • Program Unique Identifier String
    • Current Decision
  5. For the Current Decision field, you'll create a translation table. Please follow the below instructions to create a translation table for the same:
    1. Login to your Prelaunch or Production Outcomes portal.
    2. Navigate to Settings->Application Review->Decisions.
    3. Make a note of all decision labels.
    4. Now, navigate to Settings->Import\Export->Translation Tables.
    5.  Create a new translation table by clicking the plus sign at the top right.
    6. Name your translation table and set the Input Type and Output Type to Text.
    7. Click  Add New Row under Translations to add the input being the decision name in Outcomes and the output being the corresponding Decision ID in WebAdMIT.
    8. Keep adding new rows for all the decision types you want to bring into WebAdMIT.
    9. Click Save.
  6. Once the translation table has been set up, navigate back to Settings->Import\Export->Exports and click the export you just created.
  7. For the Current Decision column, add the newly created translation table as the field to be translated as.
  8. Click Save.
  9. Note that Decisions can only be updated in WebAdMIT for submitted applications, so you'll need to create an application segment that contains only submitted applications within the decision codes that you want to migrate over.
  10. Navigate to Settings->Application Review->Application Segments.
  11. Click the plus sign at the top right to add a new segment.
  12.  Name your segment and click Add Filter under Conditions.
  13. Click Application Property and the property CAS Date Submitted. Keep dates as Any Dates.

    Creating segment conditions
  14. Click Add Filter and select Group By as the filter.
  15. Add the Outcomes decisions you want to bring over as shown below.

    Adding decisions in group filter
  16. Your Segment conditions should look like the example below.

    Segment conditions added
  17. Click Create Segment to save these conditions as a segment.
  18. Navigate back to Settings->Import\Exports->Exports and click on your export.
  19. Click the plus sign under Schedule to create an export schedule delivering to the configured SFTP.
  20. While setting your new export schedule, make sure to set your filters to find only applications that have a Submitted Date and the applicable decision codes. To do so, select the newly created segment under Include Applications.
  21. Save your export settings.

Python Installation

You'll need to install Python on the server that will be hosting the script. To do so:

  1. Download the software from https://www.python.org/downloads/.
  2. Download the latest release for Windows (based on whether the server is a32 bit or 64 bit).
  3. Once downloaded, run the Python install file as an administrator.
  4. This opens an installation window:

Integration Python installation

  1. Click Customize Installation to display  Optional Features:

Integration Python Install Optional Features

  1. Ensure that pip is selected.
  2. The next page displays advanced installation options:

Integration Python install Advanced Options

  1.  Select the path to install Python and click Install.
  2. Once Python is successfully installed, restart the server.
  3. Once restarted, navigate to your system environment variables to ensure Python is appended to the end of the PATH variable. If it is not, you will need to add it. The path should be the path to the Python executable, such as C:\Users\username\AppData\Local\Programs\Python\Python310

  4. To test that your Python installation was successful and added successfully to your PATH variables, run Command Prompt as an administrator, type python, and hit enter:

Integration Python installation command prompt

  1. If the response is similar to “Python is not recognized as an internal or external command”, then it could mean that the PATH variable is not correctly set up or your Python was not correctly installed.

Editing the Python script

  1. Download the Python script and config.json file from Integration Help Center and place it on the windows server meant to host the script.
  2. On the server, create a folder called OutcomesToWebAdMITDecisions.
  3.  Create a sub-folder called Archive.
  4. Place the Python script and the config.json file in the OutcomesToWebAdMITDecisions folder.
  5. The CSV file from Outcomes must also be dropped in the OutcomesToWebAdMITDecisions folder.
  6. Edit the config.json file in the OutcomesToWebAdMIT folder using Notepad++ or Notepad and make the following changes:
    • Change the Api_key value to your API key for prelaunch or production.
    • Change the url_link value to prelaunch or production url.
    • Change Working_dir to the full directory path of your OutcomesToWebAdMITDecisions folder. Note that the directory separations use  "/".
    • Set File_name to the name of the incoming CSV file from Outcomes.
    • Set Cycle in the following format “2023 - 2024” depending on the cycle you are working with. Note that this value changes each cycle so will need to be updated regularly.
  7. Save the file.

Creating a Python executable

Next, you'll need to create a Python executable that will run the script. To do so:

  1. Open Command Prompt as an administrator.
  2. Run the following command: pip install pyinstaller
    • If you get an error message that  pip is not recognized as an internal or external command, this means your Python installation did not include the pip package.
    • The article How to Install PIP on Windows provides guidance on installing pip.
    • Once installed, type pip –version in Command Prompt to verify if the installation was successful.
    • If pip installation was successful, rerun thepip install pyinstaller command.
  3. Run the following command: pip install requests and ensure the requests module gets installed correctly.
  4. If pyinstaller and requests installation was successful, in Command Prompt, navigate to the OutcomesToWebAdMITDecisions directory.
  5. Type the following command: pyinstaller --onefile main.py and press enter.
  6. This command converts the script into an executable.
  7. The executable is found in the \OutcomesToWebAdMITDecisions\dist\ folder.
  8. Copy the config.json file from the OutcomesToWebAdMITDecisions folder to \OutcomesToWebAdMITDecisions\dist\ folder.

Testing the executable

The following should be completed for prelaunch Outcomes to prelaunch WebAdMIT:

  1. Navigate to the \OutcomesToWebAdMITDecisions\dist\ folder in Windows Explorer and double-click main.exe to open a running Command Prompt window.
  2. If the Command Prompt window closes immediately after opening, then there is an issue with your Python code or the config.json file. In that case, navigate to the OutcomesToWebAdMITDecisions \dist folder and check the main.log file. If this file shows HTTP connection errors, this could mean that your API key, URL, or Cycle is incorrect.
  3. Edit the config.json file to make sure the file name, directory paths, API keys, base URL, and cycle are correct.
  4. Once verified, run the executable again.
  5. If the executable continues to run, this means the JSON file is correct.
  6. Drop a CSV export from Outcomes to the OutcomesToWebAdMITDecisions folder. The file will be picked, processed, and archived by the executable.
  7. Navigate to the Archive folder under OutcomesToWebAdMITDecisions\Archive folder. You will see a timestamped_yourfilename.csv file.
  8. Open the file, and you will see HTTP status codes printed in each row.
  9. Successful loads would have a status code of 200, while unsuccessful loads would have a status code of 404 or 422.
  10. The 404 status code could indicate several issues, including the Decision ID not existing in WebAdMIT, incorrect authentication methods (api_key), or CASID not found in WebAdMIT.
  11. If error 422 is thrown, the applicant has already has a local status associated with their record.
  12. Note that Decision Codes in WebAdMIT can only be updated via API for applicants that do not already have a Local Status associated with them.
  13. If all rows show a 200 for each field, then the next step is to check prelaunch WebAdMIT to ensure the decision data was correctly applied in WebAdMIT.
  14. If all looks good, then close the running executable command prompt window and delete the archived file.

Setting the Python Executable as a Windows Service

To keep the script running indefinitely, the following steps are required to set up the Python executable as a windows service. For this purpose, you'll need to install a tool called NSSM (Non-Sucking Service Manager).

  1. On your web browser on the Windows server meant to host the script, navigate to https://nssm.cc/download
  2. Download the latest release of NSSM which is nssm 2.24.
  3. This should download a zip file called nssm-2.24.zip.
  4. Extract the zip file in the OutcomesToWebAdMITDecisions folder.
  5. Open Command Prompt as an administrator, and within Command Prompt,  navigate to OutcomesToWebAdMITDecisions\nssm-2.24\win64 (or win32, depending on your windows server).
  6. Run the following command by replacing the paths to your python executable and python (.py) file:
    • nssm install "OutcomesToWebAdMITDecisions" "PathTo\OutcomesToWebAdMITDecisions\dist\Decisions.exe" "PathTo\OutcomesToWebAdMITDecisions\Decisions.py"
  7. If the service is successfully installed, it displays the following message in command prompt Service "OutcomesToWebAdMITDecisions" installed successfully!.
  8. Open services.msc in Windows as an admin and locate the OutcomesToWebAdMITDecisions service.
  9. Start the OutcomesToWebAdMITDecisions service.

Testing the OutcomesToWebAdMIT Service

  1. To test the service, navigate to Testing the executable and perform steps 6 to 14.
  2. If the test is successful, then stop the OutcomesToWebAdMITDecisions service in services.msc and make sure to delete the archived file.
  3. After all testing is completed and preparations are being made to move to production then perform the following steps to remove the service:
    • Open Command Prompt as an administrator, and within Command Prompt navigate to OutcomesToWebAdMITDecisions\nssm-2.24\win64 (or win32 depending on your Windows server).
    • Run the following in Command Prompt:nssm remove “OutcomesToWebAdMITDecisions”
    • A dialog box will open to ask if you want to remove the service, click yes, and it should say the service was successfully removed.
    • Open services.msc as an admin and refresh the services to ensure the OutcomesToWebAdMITDecisions service is not in the list of services.

Moving the Script to Production

  1. If all testing has been completed in the prelaunch environments, then it is time to prepare the script for production use.
  2. Navigate to the OutcomesToWebAdMITDecisions folder in Windows Explorer.
  3. Delete the following file and folders:
    • Build folder.
    • Dist folder.
    • Main.spec file.
  4. Edit the config.json file found in the OutcomesToWebAdMITDecisions folder.
  5. In the file, change the  API key, URL, and cycle to production values.
  6. Save the file.
  7. Perform the steps found in Creating a Python executable section.
  8. Perform the steps found in Setting the Python executable as a Windows Service section.
  9. Start the OutcomesToWebAdMITDecisions service.
  10. Have Outcomes production drop a CSV file to the OutcomesToWebAdMIT Decisions folder.
  11. Check the archived file for status codes for a successful load.

Cycle Over Cycle Changes and Special Considerations

Review the following information regarding maintaining this process from cycle to cycle, and other considerations.

Non-Overlapping Cycles
  1. If your cycles do not overlap, it is important to note that Decision IDs in Prelaunch and Production WebAdMIT do change cycle over cycle.
  2. Hence, in preparation for your next cycle, revisit the Retrieving the Decision IDs in WebAdMIT section to grab the new Decision IDs.
  3. Log in to Outcomes and navigate to Settings->Import\Export->Translation tables.
  4. Select the translation table previously used, and update it with the new Decision IDs.
  5. Stop the OutcomesToWebAdMITDecisions service.
  6. Edit the config.json file in your OutcomesToWebAdMITDecisions and \OutcomesToWebAdMITDecisions\dist folders.
  7. If you plan to use the same WebAdMIT user account as the previous cycle, then the only value that needs to change in both config.json files is cycle. Replace the current value for cycle with the new value for cycle.
  8. If you plan to use a completely new WebAdMIT user for the new cycle, change the API Key and cycle in the config.json file.
  9. Save the config.json file in the OutcomesToWebAdMITDecisions and \OutcomesToWebAdMITDecisions\dist folders with the changes.
  10. Start the OutcomesToWebAdMITDecisions service.
Overlapping Cycles
  1. If you have overlapping cycles, you'll need two versions of this script, two versions of the Outcomes export, two translation tables, and two different SFTP folders housing each script, JSON file as well as being the target for the Outcomes export.
  2.  The first script would cater to your previous cycle decisions.
  3. The second needs to be set up by using a new script, a new Outcomes export with a new translation table with Decision IDs for your current cycle.
  4. Remember to stop the service and delete the service for the previous cycle once the overlap period has ended.
Multiple CASs
  1. If you have multiple CASs that need this script in WebAdMIT, then you will need multiple versions of this script, the Outcomes export, and the translation tables. You'll also need different SFTP folders which will house each script and JSON file, and serve as the target for the Outcomes export.
  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Page type
    Topic
    Content Reuse
    Reused Content
    Stage
    Work in Progress
  2. Tags
    This page has no tags.