How To's

Feature

Description

Creating and Executing Flows

Create your tasks in Task Library. OnRamp provides a few common tasks but users can edit or add new tasks. Use the “Upload Tasks” button to add multiple tasks in one go.

Create a Flow:

1. Name - unique name for your Flow. Name should not contain special characters. Also, the name of the Flow is used to track previously created data records. This is used for duplicate detection. If you change the name of the Flow at a later time, then Flow execution will happen as if its executing the first time.

2. Trigger - select an appropriate trigger and configure it. For more info, see this link.

3. Select tasks relevant for your process, and configure them. Note that the project/issue-type (or request-type) combination for the trigger should be different from any of the tasks. This is to avoid recursive loop of task creation.

To execute any Flow configured with a System trigger, click on the Play icon in the Flow tile or the Run Now button.

Authorizing users

Once installed, the OnRamp app is available to Jira admins. Admins can click on the settings (gear icon at the top right corner) to then add additional users. For example, a Jira admin may want to give access to HR partners.

Setting up Triggers

Here are the list of Trigger types currently supported:

1. Issue Type or Request Type - a user creates a new Jira issue or submits a request via the JSM portal. 

2. Workday Employee Hire or Termination - the app runs on a schedule and pulls new employee hires or terminations from Workday. We look at the Workday Transaction Log returned by Get Workers API and filter on Hire Employee or Terminate Employee Business Process type.

3. Workday Contingent Worker Hire or Termination - the app runs on a schedule and pulls new contingent worker hires or terminations from Workday. We look at the Workday Transaction Log returned by Get Workers API and filter on Contract Contingent Worker or End Contingent Worker Contract Business Process type.

4. Workday Custom Report - allows users to configure OnRamp to read from any custom report in Workday. This trigger provides the flexibility to pull any type of data from Workday.

5. BambooHR Hire or Termination - the app runs on a schedule and pulls new hires or terminations from BambooHR.

6. Greenhouse Candidate  - the app runs on a schedule and pulls candidates who have accepted a job from Greenhouse.

7. Personio - the app runs on a schedule and pulls new hires or terminated employees from Personio.

System Triggers are those that connect to target systems to pull data e.g. Workday, BambooHR, Greenhouse.

Creation of child tasks

Once the Flow is created, the OnRamp post function needs to be configured. This post function should be configured on the Trigger issue type’s Workflow, and on a transition of the users choosing. For example, if the post function is configured on “In Progress” transition, then the list of Tasks configured in Flow will get created when the Trigger issue is transitioned to In Progress. 

The idea being, an HR Partner will first review the Trigger issue and once they confirm everything looks good, they can move the issue to In Progress at which time the rest of the New Hire onboarding tasks are created and assignments are set as per the Flow configuration.

When configuring the post function, select “Create Tasks” as the Type of action. 

Limits:

1. Maximum of 150 tasks can be set on a given Flow

2. Description for a task cannot exceed 1000 characters. This size reduces as the number of tasks on a Flow is higher than 50.

Controlling which fields get displayed in child tasks

A Trigger issue contains all of the fields required to process new hire onboarding. This could include some sensitive fields that need not be exposed to the assignees working on the rest of the tasks. 

OnRamp allows users to control what fields get added to Tasks. Use the “Fields to include in tasks” to select the list of fields. Only these fields get added to the Tasks. 

Support for Issue Type and Request Type

OnRamp supports both Issues and Request Types. See this link for differences in the two. Customer who use JSM can leverage their existing JSM configuration including request types, workflows, queues, etc.

Both team and company managed projects are supported at the task level, but Triggers need to be configured in company managed projects. This is because post functions are not supported for team managed projects.

Assigning users to tasks

Tasks can be assigned to users in a couple of ways - static or dynamic. 

Static assignment to a specific user can be done by setting the Assigned To field when configuring a Task.

Dynamic assignments can be done by setting “Get assignee from a task field” to a User Picker field that’s available on the Trigger issue. This allows tasks to be assigned to people who you don’t know when configuring the Flow. For example, assigning tasks to new hire’s manager, to new hires, etc.

Mapping fields for system triggers

When using system triggers (e.g. Workday, BambooHR, Greenhouse), users can select fields to pull from the system when creating the Trigger issue. Use the Configure Mapping section to add your maps.

Open

Users can edit “mapping configuration” text area directly if they prefer. Advanced configuration e.g. filter, update_for_flow, disable_updates, report_name need to be added manually to the text area.

The field set as “key” is used to update existing issues in Jira. Usually employee ID or email can be used as the key. You can disable updates by setting config:disable_updates=true

See Workday and Greenhouse mapping configurations section for more info. For Workday Custom Report, the mapping only lists sample report fields as they will depend on your specific report fields.

Maps can be added as below:

key:workerId=customfield_10121
map:person.legalName.givenName=customfield_10122
map:person.legalName.familyName1=customfield_10123

Or advanced json paths can be specified to traverse complex structures and arrays.

map:jsonpath__workAssignments.*.reportsTo.0.reportsToWorkerName.formattedName__where__workAssignments.*.primaryIndicator_eq_true

map:jsonpath__workAssignments.*.assignedWorkLocations.0.address.cityName__where__workAssignments.*.primaryIndicator_eq_true

Setting Issue Summary field

OnRamp uses the below default format to set summary of the trigger (or parent) issue:

Flowname + ':' + First mapped field value + Second mapped field value

However users can configure custom summary. Add a line to your trigger mapping configuration that starts with ‘summary:’ followed by a comma separated string of punctuation (spaces, dashes) or {customfield_00000} where customfield_00000 is a custom field from your mapping configuration with the value you want included in the summary. See below for an example:

summary:' Developer - ', {customfield_10117}, ' ', {customfield_10065}

The above configuration would translate to a summary like this:

Onboarding Flow: Developer - 21902 John

where ‘Onboarding Flow’ is flow name.

The same summary configuration is also used when creating child issues. Ensure that the customfields in summary are included in the “Fields to include in tasks” field when setting the Create Tasks post function.

Open

Dynamic Tasks Assignments

OnRamp allows you to assign tasks to users dynamically. For instance, tasks can be automatically assigned to the new hire’s manager as part of Onboarding.

To do this, pull the manager email from your HR system (Workday or BambooHR) using below configuration. the “user_select” parameter maps the email to the user field within Jira. “customfield_10158” represents the field in Jira (say, its called New Hire Manager) to which the manager user is mapped.

map:Manager_Email_Address=customfield_10158|user_select

Now set assignee for the task in your Flow to this custom field e.g.

Open

This process can be used to assign tasks to other users as well e.g. assigning task to a mentor or buddy, etc.

Configuring email to new hires

When setting up the Create Tasks post function, users can enable email notification to new hires who don’t yet have a corporate email account. Set the “Send an email to user (e.g. new hire)” to true and set the remaining fields. The email body can optionally include a link to a JSM portal form for the new hire to provide additional information such as laptop preference, laptop shipping address, t-shirt size, etc. 

In order to link the JSM form submission back to the Trigger issue, OnRamp includes variable substitution field called {taskkey} field that can be used in the email body. “taskkey” is populated with the Trigger issue key. Here’s one way to set the JSM portal link in the email body:

https://instance.atlassian.net/servicedesk/customer/portal/3/group/17/create/44?customfield_10151={taskkey}

Where customfield_10151 is the field in the portal form you want to be populated with the taskkey. 

Additional customfields that are part of the Trigger issue can also be used as variable substitutions in the email being sent.

Email Settings

OnRamp supports below email settings. You can set these by clicking on the gear icon on the top right of the Flows page. Then select the “Other Settings” tab.

from_email=should be a valid email address (see “Custom email configuration” row below for more info)

resend_api_key=key from your resend account

Example configurations:

from_email=info@companyname.com
resend_api_key=847543bb-ed06-401c-afe3-3c131ff2edf0

Dashboard configuration

OnRamp provides a convenient dashboard view to display status of all the Flows created. Users can be given access just to the dashboard. To do this, click on the gear icon at the top right in Flows page to open OnRamp Settings. Here you can add users to the “Select dashboard users” field. These users will only be able to see the dashboard and other app functionality (Flows, Tasks, Connections) will be disabled. Note that Jira admins have full access to the app by default.

Open

You can further restrict dashboards by clicking on the gear icon on the top right of the Flows page. Then select the “Other Settings” tab and set below:

dashboard_flows=comma separated list of Flows you want to include in the dashboard, set to "all" to pull all Flows

E.g.:

dashboard_flows=Onboarding Flow, Offboarding Flow, Other Flows

Note that dashboard_flowsfilters based on the project and issue type selected for the Flow’s trigger. If more than one Flow have the same project and issue type, then those Flows will be included in the results.

Custom email configuration

OnRamp sends emails to new hires who don’t yet have a corporate email account. By default, emails are sent from “noreply@onwardb.com” with the ability to specify your company’s name in the “email from” field. However, to use your company’s email address you need to authorize your domain. We currently use http://resend.com for sending outbound emails, and plan to support other vendors (e.g. Twilio) soon. Resend allows sending 3000 emails per month for free. Follow the instructions here to authorize your domain and get an api key. Once you complete the configuration on resend’s site, configure the below two items.

from_email=should be a valid email address

resend_api_key=key from your resend account

HTML support for new hire welcome emails

Support for html formats to create emails like this to welcome new hires.

Open

See this link for an example of how a custom HTML template can be used.

Integrating new hire form submission details

OnRamp supports integrating JSM form submission into the original Jira issue created as part of a Flow. To do this, you need to include the original Jira issue ID as part of the form URL e.g. https://onbees.atlassian.net/servicedesk/customer/portal/3/group/17/create/44?customfield_10151=ORIG-101

where customfield_10151 is the field id of “Select field with task to be linked” (in Update Tasks post function) and ORIG-101 is the issue ID of the original issue created by the trigger.

Open

Then you need to configure the OnRamp post function on the submitted form issue, setting the action to Update Task. This way, the post function executes once the form is submitted (and issue created). The post function uses the taskkey as the key to integrate the data with the Trigger issue.

The URL with the issue ID is automatically created when you use email feature to send an email to the new hire. See this link for more info.

System Trigger change detection

Whenever a scheduled Trigger executes, the Last Successful Run field is used to pull all data from the system since the last time. For example, Workday New Hire trigger pulls all new hires since the last time the app ran successfully. 

When running the trigger for the first time, manually set the Last Successful Run to an appropriate value, e.g. one day ago.

If the trigger errors out then a new field is set in the Trigger configuration called Last Error Run. This field is hidden when any subsequent run is successful.

Job Logs

Detailed logs of all processing is available in the Job Logs tab. Use this for debugging purposes only and not for auditing or any other purpose. Logs older than 30 days are automatically deleted.

System connections

The Connections screen allows users to configure connectivity to systems. Once the required fields are populated, the app saves and automatically runs a connectivity test. If the test is successful, the status is set to Connected. If not, the status is set to Saved.

Sensitive information such as password or tokens are saved but never displayed. 

Error Notifications

You can configure Notifications from the Settings menu (top right of OnRamp page). All errors are logged as new tickets in the project selected. You can then get notifications by adding default watchers/assignees/etc.

Open

Complex Mapping

When an API responds list objects, you can use the below syntax to conditionally find the right list item, and then get the value:

map:OrgUnitDetail.ShortName_where_OrgUnitDetail.OrgLevel.XRefCode_eq_Region=customfield_10079
In this example, OrgUnitDetail is part of a list and the mapping is done for the OrgLevel is equal to “Region”