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

Please note this page should be considered a draft and will likely continue to be updated through the Workflows beta period.

Introduction

There are six steps to install SSDT Workflows, which will be described in further detail in this guide. Directly below is an overview of these steps.

  1. API Key Generation
  2. Environment configuration
  3. USxS Setup
  4. Setup the ssdt-workflows database container
    1. Connect the created network to Nginx (if applicable)
  5. Setup the ssdt-workflows application container
  6. Post Install Procedures

API Key Generation

Generate API Key Pairs using the System → Workflows Integration view. Each application (USAS and USPS) will need to generate a pair of API Keys for workflow integration.

Navigate to the Workflows Integration View 


Click the 'Generate Workflow Integration API Keys' button


This will create a report that will be used later in the environment configuration. The report will have a pair of API Keys and some details on where they will be used in the properties files.

API Keys for USPS <-> SSDT Workflows integration
API Keys will need to be added to properties files in both USPS and SSDT Workflows projects
API Keys for Organization Tucker (Demo) Schools - USPS below

In the SSDT Workflows Project environment properties files...
apiKey=cc97667f-7668-4d79-94a6-e519dc2368cf
remoteApiKey=caaf2f8a-7d58-453c-874a-526edac29e8b


In the USPS Project environment properties files
apiKey=caaf2f8a-7d58-453c-874a-526edac29e8b
remoteApiKey=cc97667f-7668-4d79-94a6-e519dc2368cf


Environment Configuration

Similar to other SSDT applications each entity will require a unique directory on the server where the Workflows application will run. For the remainder of this guide we will assume we are working with a district named Sampletown. There are three properties files used to install and configure the workflows application.

  1. ssdt-workflows-shared.properties - contains properties shared by multiple installation scripts
  2. ssdt-workflows-db.properties - contains properties needed by the database
  3. ssdt-workflows-app.properties - contains properties need by the application

Samples of these properties files have been attached to this page for convenience and they will also be detailed below.

ssdt-workflows-shared.properties
entityId="sampletown"
dbPassword=""
artifactUrl="docker-images.ssdt.io"
artifactUser=""
artifactPassword=""
  • entityId - This will be used by the scripts to construct the name of the database container, application container, docker network and docker volume. It must be unique. It likely makes sense to use the name of the entity, just please keep in mind if you have two similarly named entities you cannot use the same value for entityId for both.
  • dbPassword - This is the password that will be set for the database user that the application and importer use to connect to the database. 
  • adminPassword - This is the password that will be initially set for the admin user in the application. This can be changed in the application, but please note if you change the admin password in the application this property will no longer take effect (it is not reset again when updating the container etc.).
  • artifactUrl - This is the URL used to resolve the docker images needed for the application, database and importapp. The default value of "docker-images.ssdt.io" should be used.
  • artifactUser - This is the user used to authenticate to the SSDT artifact repository (this will be provided to each hosting entity by the SSDT).
  • artifactPassword - This is the password used to authenticate to the SSDT artifact repository (this will be provided to each hosting entity by the SSDT).
ssdt-workflows-db.properties
dbName="workflows-db"
dbVersion="latest"
  • dbName - This will be used to name the database container created by the install-workflows-db.sh script. The name will be composed using ${entityId}-${dbName}. So for our example sampletown-workflows-db. Leaving this set to the default of "workflows-db" makes sense for most use cases.
  • dbVersion - This is the version of the database artifact to use. Leaving this set to "latest" will ensure you are always pulling the most recent version of the SSDT workflows-db docker image
ssdt-workflows-app.properties
appVersion="latest"
adminPassword=""
java_opts="-Xmx1g"
#
# Only set the following env variables if you are using nginx for proxying
#
#virtualHost=""
#vitualPort="8080"
#
# Only set the following env variables if you are planning to use LetsEncrypt
# in conjunction with nginx
#
#letsencryptHost=""
#letsencryptEmail=""
# 
# Only set the following env variables if you need to assign and expose 
# a port on the host for the application. This is typically only needed 
# when using a proxying option other then nginx. Note 8081 is just provided
# as an example. You will need to select the correct port to be used.  
#hostPort="8081:8080"
#USAS Integration Config
usasHost=""
usasPort=""
usasApiKey=""
usasRemoteApiKey=""
# Only add a value if the usas application is not at the root of the server
#usasContext=""

#USPS Integration Config
uspsHost=""
uspsPort=""
uspsApiKey=""
uspsRemoteApiKey=""
# Only add a value if the usps application is not at the root of the server
#uspsContext=""
  • java_opts - This property can be used to pass JVM options to the workflows application container. We are currently recommending a minimum of 1GB be assigned to the container.
  • USAS Integration
    • usasHost - The full URL of the USAS application that workflows will integrate with.
    • usasPort - The port used to connect to the application (likely 443 if using https)
    • usasApiKey - The API Key used by USAS to connect to the workflows application.
      • From the workflows integration report use the property labeled 'apiKey' under the heading In the SSDT Workflows Project environment properties files
    • usasRemoteApiKey - The API Key used by Workflows to connect to the USAS application.
      • From the workflows integration report use the property labeled 'remoteApiKey' under the heading In the SSDT Workflows Project environment properties files
  • USPS Integration
    • uspsHost - The full URL of the USPS application that workflows will integrate with.
    • uspsPort - The port used to connect to the application (likely 443 if using https)
    • uspsApiKey - The API Key used by USPS to connect to the workflows application.
      • From the workflows integration report use the property labeled 'apiKey' under the heading In the SSDT Workflows Project environment properties files
    • uspsRemoteApiKey - The API Key used by Workflows to connect to the USPS application.
      • From the workflows integration report use the property labeled 'remoteApiKey' under the heading In the SSDT Workflows Project environment properties files

USXS Setup

The following environment variables will need to be added to the USXS configurations. This will require a restart of each application

  • WORKFLOWS_HOST - The full URL of the Workflows Application that USXS will integrate with.
  • WORKFLOWS_PORT - The port used to connection to the application (likely 443 if using https)
  • WORKFLOWS_API_KEY - The API Key used by workflows to connect to the USXS application.
    • From the workflows integration report use the property labeled 'apiKey' under the heading In the USXS Project environment properties files
  • WORKFLOWS_REMOTE_API_KEY - The API key used by USXS to connect to the workflows application
    • From the workflows integration report use the property labeled 'remoteApiKey' under the heading In the USXS Project environment properties files

Below is a docker-compose.override.yml example. It lists the new environment variables that are needed to connect to the workflows application.


docker-compose.override example
version: "3.3"
services:
    usasdb:
        image: trainingdb-usas
        environment:
         - DB_NAME=
         - DB_USER=
         - DB_PASS=
    usasapp:
        image: usas-app
        ports:
          - "8280:8080"
        environment:
          - APPLICATION_ADMIN_PASSWORD=
          - APPLICATION_ADMIN_RESET=true
          - JAVA_OPTS=-Xmx4g
          - DB_POOL_MAX=40
          - DB_NAME=
          - DB_HOST=
          - DB_USER=
          - DB_PASS=
          - WORKFLOWS_HOST=
          - WORKFLOWS_PORT=
          - WORKFLOWS_API_KEY=
          - WORKFLOWS_REMOTE_API_KEY=
    uspsdb:
        image: trainingdb-usps
        environment:
         - DB_NAME=
         - DB_USER=
         - DB_PASS=
    uspsapp:
        image: usps-app
        ports:
          - "8281:8080"
        environment:
          - APPLICATION_ADMIN_PASSWORD=
          - APPLICATION_ADMIN_RESET=true
          - JAVA_OPTS=-Xmx4g
          - DB_POOL_MAX=40
          - DB_NAME=
          - DB_HOST=
          - DB_USER=
          - DB_PASS=
          - WORKFLOWS_HOST=
          - WORKFLOWS_PORT=
          - WORKFLOWS_API_KEY=
          - WORKFLOWS_REMOTE_API_KEY=

Once the USXS environment variables are added, both USXS projects will need to be restarted.


Setting Up The Workflows Database

The SSDT has created a script named install-workflows-db.sh that will do the following.

  • Login to the SSDT artifact server
  • Pull the workflows db image
  • Create a docker network specific to the entity's workflows installation
  • Create a named docker volume to contain the database data
  • Create , configure and run the docker container for the workflows db

The script must have the protections set so that it is executable (i.e. chmod u+x) and can be executed using the command below. Please be aware the script must be executed from the directory that contains the .env directory to work properly. 

sudo ./install-workflows-db.sh

Connecting The Created Network to Nginx (If Applicable)

If you are using nginx it will be necessary to connect nginx to the docker network specific to each entity's workflow containers. Creating a docker network for each entity's workflow installation is the most secure and recommended way to configure this per docker documentation. However, the SSDT does have some concerns surrounding if having too many docker networks on a single host and/or connected to the same nginx instance will cause resource and/or performance issues. We will continue to monitor this and ask that you report to us via the service desk if you believe this configuration is causing you issues in your hosting environment.

Below is the command you can use to connect the docker network to nginx (you will need to replace the example network name with the actual name of the created network and replace nginx with the actual nginx container name/id). It is best to do this step prior to setting up the workflow application container so that nginx will automatically detect and proxy the container when it starts. If you do it after the application container already exists it may be necessary to stop and start the workflow application container for nginx to detect it.

docker network connect sampletown-workflows-net nginx

Setting up the Workflows Application

The SSDT has created a script named install-workflows-app.sh that will do the following.

  • Login to the SSDT artifact server
  • Pull the workflows-app image
  • Create the ssdt-workflows-app container and configure it to connect to the appropriate docker network and database along with optionally setting the environment variables need for nginx and letsencrypt and/or exposing an external port on the host (all of this is configured by the setup in the ssdt-workflows-app.properties.
sudo ./install-workflows-app.sh

Post Install Procedures

USAS

  • Navigate to System → Modules
    • Install the Workflows Module
    • Verify the following is also installed
      • Email Notification Services
      • File Transfer Notification Services
      • Http Notification Services
    • Refresh the page to enable the menu items
  • Navigate to System → Configuration
    • Edit the Workflows Configuration
      • Add the full URL of the USAS application
      • Enable the Requisition Approval
      • Save the Workflows Configuration
      • Refresh the page to enable the menu items
    •  Edit the Requisition Approval Configuration
      • Select a due date option
        • This will determine how the grid is highlighted when viewing approval tasks
      • Edit any email options if desired
      • Save the Requisition Approval Configuration
    • If you wish to receive email notifications for approvals, edit the Email Configuration
      • Add the necessary setup for your entity's email server
      • Save the Email Configuration 
  • Navigate to System → Workflows Integration
    • Click the Test Connection button
      • If this is successful, the USAS application is able to communicate with the Workflows application
      • If this is unsuccessful, please verify the API Keys are configured correctly in the properties files.
  • Begin setting up Groups, Group Chains, and User Group Chain access.
  • Requisition Approval is now ready for processing.

USPS

  • Navigate to System → Modules
    • Install the Workflows Module
    • Refresh the page to enable the menu items
  • Navigate to System → Configuration
    • Edit the Workflows Configuration
    • Enable Employee Onboarding
    • Save the Workflows Configuration
    • Refresh the page to enable the menu items
  • Navigate to System → Workflow Integration
    • Click the Test Connection button
      • If this is successful, you are ready to use the employee onboarding workflows
      • If this is unsuccessful, please verify the API Keys are configured correctly in the properties files.


Updating Existing Application Containers

The SSDT has created a script to facilitate the updating of Workflows application containers. Please note this script is fairly basic at the moment and assumes it will be executed interactively from the base directory like the installation and importer scripts. We do plan to enhance this script to help ITCs schedule checking for updates of multiple instances using scheduled nightly jobs. 

The update-workflows-app.sh script will do the following.

  • Login to the SSDT artifact server
  • Pull the ssdt-workflows-app image
  • Stop the ssdt-workflows-app container (if running)
  • Remove the ssdt-workflows-app container if it exists
  • Create the ssdt-workflows-app container (based on the new image if one exists) and configure it to connect to the appropriate docker network and database along with optionally setting the environment variables need for nginx and letsencrypt and/or exposing an external port on the host (all of this is configured by the setup in the ssdt-workflows-app.properties).
sudo /ssdt/prod/update-workflows-app.sh
  • No labels