Okta Workflows makes it easy to automate identity processes at scale – without writing code. Use if-this-then-that logic, Okta’s pre-built connector library, and the ability to connect to any publicly available API to enable anyone to innovate with Okta. Workflows templates provide flow builders with pre-built, configurable flows for common identity automation use cases. Flogrammers can download and use the templates as-is, or modify them for their organization’s unique needs. In this tutorial, we’ll go through the process of using a template to create a set of flows. For additional information on Okta Workflows, see this page: Okta Workflows
Use Case Overview
Many organizations utilize short term as well as full time employees. Short term employees are sometimes known as contractors as they are usually contracted to perform a specific task over a specified time period. A contractor would usually have a contract expiry date. That is the date at which their current contract is due to expire. Certain people within the organization, like the contractors manager, will need to be notified ahead of the expiry date, so they can potentially renew the employees contract or plan for the employee to leave the organization. It also should be noted that often for legal reasons, an employee on a contract, can not be at the employers place of work, or perform any tasks for their employer, if they do not have a current active contract. I have seen situations in the past where an employees contract expired and they had to leave the worksite for a number of days until a new contract was put in place.
Okta Workflows is the perfect solution to this use case. In this tutorial we will use a pre-configured template to create a number of flows designed to demonstrate this use case.
Workflow Template
Workflows templates provide flow builders with pre-built, configurable flows for common identity automation use cases. These use cases cover both workforce and customer identity. Flogrammers can download and use the templates as-is, or modify them for their organization’s unique needs. Workflows templates are accessible via the home screen in the workflow console.
The template for the above use case is titled Contractor Expiry Notification as shown in the image below.
This workflow template reads a custom attribute on the users Okta profile. This custom attribute holds the users current contract expiry date. Based on a set number of days, a future date is calculated. A list of all users that have a matching contract expiry date is compiled and emailed to a pre-configured list of recipients. This workflow also demonstrates how static configuration values, like days, timezone and email recipients, can be externalized into a workflow table and be read in at runtime. This makes modifications to the workflow simple and easy, where changes only involve updating the respective configuration table.
Template Contents
Here is a summary of the flows and tables included in the template:
Flows
1.0 – Contractor Expiry Notification
This is the main flow and is initiated via a flow schedule. This flow will check to see if any users have a contract expiry date of a set number of days into the future. The exact number of days is set in the configuration table. For any users found, an email will be generated and sent to the configured recipients.
This parent flow will call the following helper flows:
1.1 – Initialize
1.2 – Process Contractor
1.3 – Send Notification Emails
1.1 – Initialize
This helper flow reads configuration data from the configuration table and also initializes the contractor-list table prior to processing. The flow will return configuration values for the number of days, current time zone and email address list, to the parent flow.
1.2 – Process Contractor
This helper flow is called within a loop, once for each user found. The flow formats the user’s first name, last name and email and appends it onto the contractor-list table.
1.3 – Send Notification Emails
This helper flow will process any users that have been stored on the contractor-list table by the previous child flow. If at least one user exists on the contractor-list table, then a HTML formatted email will be sent to the email address list set in the configuration table.
Tables
configuration – This table holds static configuration data
contractor-list – This table is used to dynamically store data processed during the workflow execution
Getting Started Prerequisites
Before you get started, here are the things you’ll need:
- Access to an Okta tenant. Okta Workflows is now enabled in all production and sandbox tenants.
- Access to the tenants profile editor so a custom attribute can be added to the default Okta profile.
- Access to the tenants users, so the custom attribute can be populated.
- Access to an account for Office 365 Mail. This can be substituted with GMail or SendGrid.
Setup Steps
Please follow these step-by-step instructions to set up this workflow.
Step 1 – Create Custom Attribute
Create a custom attribute to hold the respective users contract expiry date. This attribute would normally be updated by an external system, but for this workflow, we will just be updating it manually via the administration console. The workflow expects the date format to be yyyy-MM-dd. The workflow can easily be modified to accomodate any other format.
Within your Okta tenants administration console, under Profile Editor, open the Okta default profile and add the following custom attribute:
Data Type: string
Display name: Contract End Date
Variable name: contractEndDate
Description: Stores the users contract expiry date as yyyy-MM-dd
Note: If you modify the variable name and/or date format, then you will need to update the workflow to match.
Step 2 – Add Template
In this step we will add the template to your workflow instance.
Open the respective template and click the button Add template. This will create a new folder called Contractor Expiry Notification containing four flows and two tables. The folder contents should match the following:
Step 3 – Import Sample Data
In this step we import the sample data.
The sample data for the configuration table can be found on GitHub here: workflows-templates/configurationTableData.csv at master · okta/workflows-templates
I have also included the same sample data below:
key,value,description
days,30,The number of days in the future to check for contract expiry
timezone,America/Los_Angeles,The local timezone. See full list here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
addressList,test.user1@example.com,The email address used to send the notifications to. This can be a list of addresses where each address is delimited with a comma.
Save the data into a file and give it a meaningful name with a csv extension. Open the workflow folder and select Tables and open the configuration table. Then import the sample configuration data and modify where appropriate. The configuration data consists of the following:
- addressList – A comma delimited list of email addresses
- timezone – Your current timezone as per the list here: List of tz database time zones
- days – The number of days into the future that the workflow will calculate the contract expiry date
Note: To further enhance the flow, the static email address list can be replaced by a dynamic lookup within the flow. For example, you could query the respective users profile for the users assigned manager.
Step 4 – Update Flow Connectors
Update the connectors with in the flows. This step involves creating your own connectors (if not already available) and then updating the flows to use your connector instance. The required connectors are the Okta connector for your local Okta tenant and an email connector.
Within the flow titled 1.0 – Contractor Expiry Notification, update the Okta card to use your Okta connector.
Within the flow titled 1.3 – Send Notification Emails, update the Office 365 Mail card to use your Office 365 connector. (Or alternative email connector)
Step 5 – Turn On the Flows
Enable your flows. Within each flow, toggle the flow from Off to On. The toggle switch for each flow should change from grey to blue as per the image below:
Testing the Workflow
Now that the setup is complete, the workflow is now ready for testing.
This is how to test the flow:
- Ensure the configuration table value for addressList contains an address that you can receive emails for testing.
- Set the value of the custom attribute for at least one user. The date format must match the following: yyyy-MM-DD. Set the value to be a set number of days into the future. EG. 30 days. (This value must match the setting on the configuration table for days)
- Initiate the parent flow (1.0 – Contractor Expiry Notification) by clicking the Test button.
- If the flow finds at least one user with a contract expiry date matching the set number of days, then an email will be sent to the configured recipients.
Note: If the test does not produce the expected result, then examine the flow execution in Flow History. This debug tool is an easy way to see what happened during execution.
Here is an example of an email produced where four employees have a contract expiring in 30 days:
