Working With Flow Fields and Data

This guide will help you manage and use both default system and user-supplied field data inside of your Flows.

Overview

A Sym Flow is composed of a series of discrete steps. On and after each step, you can invoke Workflow Handlers to inject custom logic into your Flow. This guide covers best practices for retrieving both user- and system-supplied attributes from your Flow so you can use them in your SDK code.

The event

All Flow data in a Handler is accessed through the event attribute passed into the Handler's signature. See: sym.sdk.event.Event

For example:

@hook
def on_escalate(event):
  # Fetch some values
  email = event.user.email
  flow_slug = event.flow.srn.slug
  urgency = event.payload.fields["urgency"]
  
  message = f"{email} just ran the {flow_slug} flow with {urgency} priority."
  # Do things
  # ...

Types of data

There are two fundamental types of information you'll handle in your SDK code:

  1. System data that describes the Sym resources involved in your workflow, like user and target
  2. Field data as defined in the Flow's Prompt Fields

📘

Externally supplied data is handled differently

Data passed into the SDK from external Targets like AWS Lambda functions are not included in Flow event data, and must be accessed via the get_step_output() helper method.

Working with Flow data

System data

All common system data is accessible through a Handler's event input, and documented in Sym's SDK Docs.

📘

Flow Variables are a powerful way to pass context from your Flow to the Sym SDK

For more information on working with Flow Variables (event.flow.vars), see Using Flow Variables

AttributesReferenceNotes
event.user.email
event.user.first_name
sym.sdk.userBasic information about the requestor.
event.flow.varssym.sdk.flowFlow variables as defined in Terraform. For example, your team's PagerDuty Schedule ID.
event.channelsym.sdk.event.ChannelThe source of an event. Will be one of slack, sdk (the event was initiated via SDK code), or sym (the event was initiated via API).

Field data

Field data refers to anything that comes through the Flow as form-submitted fields. In practice, this means anything you define in your Flow's prompt_fields_json, as well as the Flow's Target.

AttributesReferenceNotes
event.payloads.fields["target"].label
event.payloads.fields["target"].name
event.payload.fields["target"].type
event.payload.fields["target"].settings["<key>"]
sym.sdk.targetAlways present; referenced from prompt fields.

Settings will vary from Flow to Flow.
event.payload.fields["reason"]
event.payload.fields["urgency"]
event.payload.fields["duration"]
sym.sdk.eventApplies to all prompt fields; keyed off name attribute.

Note that duration has some special handling.