# Sagas (Enhanced Workflow Configuration)

## What is a Saga?

A saga is a small set of code instructions that call different saga methods to complete a variety of tasks, such as send notifications, push data to an LOS, talk to third-party integrations, modify information, etc.&#x20;

* Sagas are event driven
* Sagas can be customized per Partner and per Site.
* Within a Saga, we can call many saga methods in a sequence, including sending a particular notification (email or SMS).
* Right now Sagas can only be created and modified directly in the database by a developer, but coming soon there will be a saga editor in the Customization Hub.

Sagas can be triggered to run when certain events occurs within the platform. With a powerful set of sagas each site's functionality can be highly customized.

Following is a sample saga that finds a loan, finds the associated Agent (LO), pushes the loan to Desktop Underwriter, Encompass LOS and sends a notification to the Agent.&#x20;

```ruby
# Find the Loan
loan = find 'loan', params.loan_id

# Assign to an Agent based on the Purpose Type of the Loan
if loan.purpose_type == 'Purchase'
  agent = find 'agent', { purpose_type: 'Purchase' }
elsif loan.purpose_type == 'Refinance'
  agent = find 'agent', { purpose_type: 'Refinance' }
end

# Push the Loan to DU
du_response = loan_file_push_to_desktop_underwriter loan.id
save_response_to_database du_response

# Push the Loan to Encompass
loan_file_push_to_encompass_api loan.id

# Send custom notification to Agent
send_notification! 'loan_pushed_to_encompass', agent.id, loan.site_id

# Send custom notification to Borrowers introducing them to Agent
primary_applicant = loan.primary_applicant
send_notification! 'agent_assigned', primary_applicant.id, loan.site_id

# Push data to custom endpoint
url = 'https://your-domain.com/endpoint'
http_post url, { body: loan.data }
```

{% hint style="info" %}
The full saga methods reference can [be found here](https://docs.himaxwell.com/~/changes/664/platform-overview/admins-and-tech-support/enterprise-level-admin-management/sagas/saga-methods-reference).
{% endhint %}

**There are 2 types of events that can trigger a saga to run:**

1. Blueprint driven events
2. Backend drive events

## Blueprint Driven Events

When a particular task in a blueprint is completed, the blueprint can specify that a particular saga should be run.&#x20;

{% hint style="warning" %}
Blueprint sagas will only run the first time a task is completed. They will not run if a task is completed a second time.&#x20;
{% endhint %}

Currently this behavior can only be configured by manually editing the Blueprint JSON. But in a coming release the Blueprint editor will allow changing this more easily.

## Backend Driven Events

The backend will run a Saga with a corresponding Saga name when any of the following backend "Objects" are Created or Updated. It requires some understanding of how the backend works to understand which front-end actions will trigger which back-end events.

{% hint style="info" %}
Backend event-driven sagas are also known as "Callback Sagas".
{% endhint %}

### Task Events

* When a task is created or updated, including status change such as a task being completed
* The Sagas that run will be able to check for task attributes such as the task name / type to determine e.g. which notification should be sent.

### Milestone Events

* Whenever a milestone is changed
* This may be unintuitive - when the active milestone changes then both the previously active milestone and the newly active milestone will both be updated. Milestones will be created when the application file is first created, so the “create” event here is not very useful.

### Document Events

* Lender Documents - Documents uploaded by an Agent in the "lender documents" section.
* Sent Documents - Documents uploaded by an Agent in the "sent documents" section.
* Submitted Documents - Documents uploaded by a Borrower OR an Agent in the "submitted documents" section.

### Integration Responses

Any saved response from an integration, e.g.

* Credit Pull
* LOS Loan File Push
* LOS Document Push
* AUS (DU) Run
* Pre-approval Letter Creation
* etc.

### Agent Assignment

* When an agent is assigned to an application file
* When an agent is assigned to a site
* When an agent is assigned to a role

### Workflow Events

Also known as LOS Milestones

Saga Specifications
