Using Historical Context

Sym gives you the ability to retrieve historical event data for a particular user, which may be used to inform runtime decisions.

Overview

When executing code in your impl.py, you may want some additional context about the history of a particular user's access requests. For example, if a user has requested the same resource multiple times in a short time period, you may want to automatically give them access to that resource the next time they request.

A user's historical context can be used in order to inform such a decision. The method get_event_count() exists for this purpose.

Implementation

To retrieve a user's access request history in your impl.py, use user.get_event_count() . The full SDK reference can be found here. Note that there are numerous ways to filter these events and are documented in the SDK.

Note that filter_on will always be used, defaulting to "flow", which indicates that the method will filter using the current Flow's ID. The value can also be changed to "target", which will cause the method to filter by the current Target's ID.

πŸ“˜

Important Note

When used with events APPROVE, ESCALATE, or DEESCALATE, the count will represent the number of times the user has been approved, escalated, or deescalated. Not how many times they have approved or revoked a request. Please refer to the table below.

Terminology

A table of each event name and what the value returned by get_user_count() represents.

Event typeReturned value
REQUESTHow many times this user has requested a flow or target
APPROVEHow many times this user has been approved for a flow or target
DENYHow many times this user has been denied for a flow or target
ESCALATEHow many times this user has been escalated for a flow or target
DEESCALATEHow many times this user has been deescalated or had access revoked for a flow or target.

Examples

The following example will display the request count for the current Target or Flow in the Slack channel called #sym-access.

from sym.sdk.annotations import hook
from sym.sdk.integrations import slack
from sym.sdk.templates import ApprovalTemplateStep


@hook
def after_request(event):
    flow_count = event.user.get_event_count(ApprovalTemplateStep.REQUEST, filter_on="flow")
    target_count = event.user.get_event_count(ApprovalTemplateStep.REQUEST, filter_on="target")
    slack.send_message(slack.channel("#sym-access"), f"User has requested access using this Flow {flow_count} times.")
    slack.send_message(slack.channel("#sym-access"), f"User has requested access to this Target {target_count} times.")

This example will automatically approve a user who has been granted access to the same Target at least once in the past week.

from sym.sdk.annotations import hook
from sym.sdk.templates import ApprovalTemplate, ApprovalTemplateStep


@hook
def after_request(event):
    last_week = datetime.now() - timedelta(days=7)
    if event.user.get_event_count(
        ApprovalTemplateStep.ESCALATE, filter_on="target", since=last_week
    ):
        return ApprovalTemplate.approve()

The following example will send a welcome message to the user the first time they make a request using the current Flow.

from sym.sdk.annotations import hook
from sym.sdk.integrations import slack
from sym.sdk.templates import ApprovalTemplateStep


@hook
def on_request(event):
    flow_welcome_msg = "Thanks for running this Flow for the first time! This Flow can be used to..." 
    if event.user.get_event_count(ApprovalTemplateStep.REQUEST, filter_on="flow") == 1:
        slack.send_message(event.run.actors["prompt"], flow_welcome_msg)