OnBase Guide - Unity Script - Update Email Address (ICS/HCM)

OnBase Guide - Unity Script - Update

Email Address (ICS/HCM)

Goal: To use a script in Workflow or on a Unity form to

retrieve a student’s or employee’s email addresses from

Campus Solutions or HCM.

Complexity Level: Departmental Workflow Developers,

Departmental Unity Form Developers

12/6/2023

2 
 
Table of Contents 
Background ............................................................................................................... 3 
Email Address Types ................................................................................................. 3 
Campus Solutions .................................................................................................. 3 
HCM ....................................................................................................................... 4 
Prerequisites .............................................................................................................. 4 
Using the Workflow Scripts ........................................................................................ 5 
Using the ICS Workflow Script ............................................................................... 5 
Set Property Values Needed for Script ............................................................... 5 
Run the Script ................................................................................................... 10 
Use the Script Results ...................................................................................... 10 
Using the HCM Workflow Script ........................................................................... 11 
Set Property Values Needed for Script ............................................................. 11 
Run the Script ................................................................................................... 16 
Use the Script Results ...................................................................................... 16 
Troubleshooting Scripts in Workflow .................................................................... 17 
Using the Unity Form Scripts ................................................................................... 18 
Configuring Form Fields ....................................................................................... 18 
Troubleshooting Form Scripts .............................................................................. 19 
Custom Action to Execute Script .......................................................................... 20 
 
   

Background

Scripts are available (one for Workflow, one for Unity forms) to retrieve the email

address for a student from Campus Solutions.

It is a best practice to check for the existence of all input values before running the

script (ex. if you intend to use the Employee ID keyword as an input to get HCM

addresses, check that the Employee ID keyword has a value before attempting the

script).

When using email addresses to send notifications, it is also a good idea to validate

the email address before attempting the notification send (to ensure that whatever

keyword/property value being used as a recipient is a valid email address). More

information about validating email addresses is available for workflow in the

Commonly Used Expressions guide and for Unity forms in Validating Field Values

with RegEx.

Email Address Types

You will need to specify which email type to retrieve from either source. The

available options are:

Campus Solutions

Address Type

Description

BLD

Boulder

CONT

Continuing Ed

CUCS

CU Student Preferred

DENH

UC Denver

FAST

Faculty Staff

ISIR

Financial Aid ISIR

PRCU

Pre CU Enrollment

PRIR

Parent ISIR

PRNT

Parent ISIR

PSCU

Post CU Enrollment

UCCS

HCM

Address Type

BUSN

BNBI

CAMP

DORM

HOME

OTHR

RPTS

UCB

UCCS

UCD

USYS

ALL*

*ALL is not an HCM value. In the workflow script for retrieving email data from HCM,

you can set the email type input property to “ALL” to receive a comma-separated list

of all distinct email addresses for the employee (ex: [email protected],

[email protected]).

Information on inputs and outputs of all Unity scripts are available on the OnBase

Unity Script Inputs and Outputs administrative reporting dashboard in the

Configuration category.

Prerequisites

For Workflow:

You must have OnBase Studio installed and know how to configure a life

cycle. Refer to the OnBase Client Guides for instructions on installation and to

the Workflow MRG for more details as necessary. Contact

[email protected] for assistance if needed.

For Unity Forms:

You must be a member of the Unity form developer user group and be

familiar with creating form templates and configuring custom actions.

Using the Workflow Scripts

When using script in workflow, input values should be set and/or validated, then an

action runs the script to retrieve output values. You can then use the output values

with any of the actions/rules available for properties.

Using the ICS Workflow Script

This script takes a student ID and the email type you provide and outputs the

appropriate email address to a property value, which you can then copy to a

keyword value, or use in another manner.

Certain values are required for the script to retrieve the desired email address:

• Student ID (keyword value)

• UnityScriptResult (property)

• ScriptError (property)

• EmailAddressType (property)

• EmailKWToUpdate (property)

When setting any property values to run a script, be sure to note which property bag

is being used and be consistent with this selection.

Set Property Values Needed for Script

Create an action and choose the Set Multiple Property Values action type.

Click Add at the bottom of the panel at the right side to add a new property value.

Enter the following values to set the UnityScriptResult property:

• Property Name: UnityScriptResult

• Constant Value: Initialized

Then click OK.

Click Add at the bottom of the panel at the right side to add a new property value

and enter the following values to set the ScriptError property:

• Property Name: ScriptError

• Constant Value: [leave blank]

Then click OK.

Click Add at the bottom of the panel at the right side to add a new property value

and enter the following values to set the EmailAddressType property:

• Property Name: EmailAddressType

• Constant Value: [enter desired “Field Value” from chart above]

Then click OK.

Click Add at the bottom of the panel at the right side to add a new property value

and enter the following values to set the EmailKWToUpdate property:

• Property Name: EmailKWToUpdate

• Constant Value: Initialized

Then click OK. Overall, the Set Multiple Property Values action should look like this

when complete:

Run the Script

Create a “Run Unity Script” action. Select “GEN – ICS – Update Email Address”

from the list of available scripts. Check the box to Refresh item after script has

executed.

When the script runs, it will update the EmailKWToUpdate property value with the

student’s email address.

Use the Script Results

After the script runs, you can then copy the EmailKWToUpdate property value to

whatever keyword you wish, or use it with a notification, or use it for anything else

you can do with properties.

Use the “Set Keyword from Property Value” action type to copy the value to a

keyword value.

The property value can also be used as a notification recipient.

NOTE: This requires the property to be stored as a Session property value, so be

sure to configure the property accordingly if this is your intended use.

Using the HCM Workflow Script

This script uses the employee ID. If desired, you can also provide an email address

type. When the script runs, the specified email address is set to a property value,

which you can then copy to a keyword value, or use in another manner.

Certain values are required for the script to retrieve the desired email address:

• Employee ID (keyword value, or if no keyword value exists, the EmployeeID

property value can be used instead)

• EmailAddressType (property, optional input)

• UnityScriptResult (property, output)

• ScriptError (property, output)

• EmailAddress (property, output)

If no email address type is specified, the output will be the person’s preferred email

address.

When setting any property values to run a script, be sure to note which property bag

is being used and be consistent with this selection.

Set Property Values Needed for Script

Create an action and choose the Set Multiple Property Values action type.

Click Add at the bottom of the panel at the right side to add a new property value.

Enter the following values to set the EmailAddress property:

• Property Name: EmailAddress

• Constant Value: [leave blank]

Click Add at the bottom of the panel at the right side to add a new property value

and enter the following values to set the EmailAddressType property (optional):

• Property Name: EmailAddressType

• Constant Value: [enter desired “Field Value” from chart above]

Then click OK.

Click Add at the bottom of the panel at the right side to add a new property value

and enter the following values to set the UnityScriptResult property:

• Property Name: UnityScriptResult

• Constant Value: [leave blank]

Then click OK.

Click Add at the bottom of the panel at the right side to add a new property value

and enter the following values to set the ScriptError property:

• Property Name: ScriptError

• Constant Value: [leave blank]

Then click OK.

Then click OK. Overall, the Set Multiple Property Values action should look like this

when complete:

Run the Script

Create a “Run Unity Script” action. Select “GEN – HCM – Update Email Address”

from the list of available scripts. Check the box to Refresh item after script has

executed.

When the script runs, it will update the EmailAddress property value with the

person’s email address.

Use the Script Results

After the script runs, you can then copy the EmailAddress property value to

whatever keyword you wish, or use it with a notification, or use it for anything else

you can do with properties.

Use the “Set Keyword from Property Value” action type to copy the value to a

keyword value.

The property value can also be used as a notification recipient.

NOTE: This requires the property to be stored as a Session property value, so be

sure to configure the property accordingly if this is your intended use.

Troubleshooting Scripts in Workflow

If you encounter an issue, checking the values of the UnityScriptResult and

ScriptError properties may provide helpful information for determining the cause of

the issue.

You can do this by:

- Logging the property values to a note (please only do so while

testing/troubleshooting)

- Logging the property values to document history (please only do so while

testing/troubleshooting)

- Using On Demand Diagnostics

Using the Unity Form Scripts

These form scripts do not directly update a keyword type but update a form field

which may be mapped to a keyword type or stored as a non-keyword form field. The

correct fields need to be configured, then a custom action runs the script.

Configuring Form Fields

Certain field IDs must be used for the email address scripts to work.

For the Campus Solutions script, you will need:

Value

Field ID

Used as

Student ID

StudentID_pre

Input, required

Email Address

email_address

Output, required

Email Address Type

email_type

Input, required

The email address type field can be hidden. Set a value for the field (default value or

set by custom action) for the field based on the email address types above.

For the HCM Script, you will need:

Value

Field ID

Used as

Employee ID

EmployeeID_pre

Input, required

Email Address

email_addr

Output, required

Email Type

email_addr_type

Input, optional

If no email address type is specified for the HCM script, it will return the employee’s

preferred email address in HCM.

Troubleshooting Form Scripts

If you’d like to include error messages, you can add the following output fields (these

are optional):

Value

Field ID

General Error Message (all

scripts)

error_message

Error Messages for the ICS

email script only

error_message_GENUpdateEmailAddress

Error Messages for the HCM

email script only

error_message_GENHCMGetEmailAddressUNITYFORM

Custom Action to Execute Script

A custom action is required in order to execute a Unity script. Create a custom

action with the desired conditions, then add an action to execute the GEN - ICS -

Update Email Address [UNITY FORM] or GEN - HCM - Update Email Address

[UNITY FORM] script.

At a minimum, you should check for the Student ID and email address type field

being populated if using the ICS script and the Employee ID field being populated if

using the HCM script, but you may wish to add other conditions such as:

• Form is new (to prevent the script running every time the form is viewed after

submission)

• Name fields being populated and valid, through whatever identity validation

you are performing