Pylon plugins

Surface Pylon operations as actions on any collection (create, reply to and close issues)

The Pylon connector ships three plugins that surface Pylon operations as actions on any host collection of your back-end — typically a collection that already carries the Pylon requester’s identity (an email column) or a Pylon issue id (a column like pylon_issue_id).

The Pylon connector is only available for Ruby (gem forest_admin_datasource_pylon).

All three plugins require the Pylon datasource to be registered on your back-end: they need the Datasource instance to reach the Pylon API client.

Usage

Nothing is registered automatically. Opt each plugin in per collection:

# app/lib/forest_admin_rails/create_agent.rb
pylon_datasource = ForestAdminDatasourcePylon::Datasource.new(api_key: ENV['PYLON_API_KEY'])
@agent = ForestAdminAgent::Builder::AgentFactory.instance.add_datasource(pylon_datasource, {})

@agent.collection :Customer do |collection|
  collection.use(
    ForestAdminDatasourcePylon::Plugins::CreateIssueWithNotification,
    datasource: pylon_datasource,
    sender_email: '[e-mail]'
  )
end

@agent.collection :Order do |collection|
  collection.use(
    ForestAdminDatasourcePylon::Plugins::ReplyToIssue,
    datasource: pylon_datasource,
    issue_id_field: 'pylon_issue_id'
  )
  collection.use(
    ForestAdminDatasourcePylon::Plugins::CloseIssue,
    datasource: pylon_datasource,
    issue_id_field: 'pylon_issue_id'
  )
end

All three plugins take the Datasource instance you registered earlier as the required datasource: option, and all refuse to register without a collection — they only work at the collection level. You can attach the same plugin to several collections with different option sets.

Create an issue and notify

A Single-scope action that opens a Pylon issue from the selected host record and delivers its first message to the requester. The host record does not need to be related to Pylon: the requester is identified by an email entered (or pre-filled) in the form, and Pylon creates the contact on the fly when it does not already exist (the action derives the contact’s name from the email’s local part, e.g. [e-mail] → john.doe).

Where a Zendesk notification is a side effect of a public comment, Pylon says it outright: destination_metadata.destination names the channel the issue’s body_html is delivered through, and no metadata at all is what leaves the issue internal.

@agent.collection :Customer do |collection|
  collection.use(
    ForestAdminDatasourcePylon::Plugins::CreateIssueWithNotification,
    datasource: pylon_datasource,
    action_name: 'Open a support issue',
    default_subject: 'Refund for {{record.email}}',
    default_message: '<p>Hi {{record.name}},</p>',
    requester_email_default: ->(record) { record['email'] },
    sender_email: '[e-mail]',
    priority_override: 'high',
    issue_id_field: 'pylon_issue_id'
  )
end

Option	Description
datasource	Required. The ForestAdminDatasourcePylon::Datasource instance.
action_name	Overrides the action label. Defaults to 'Create Pylon issue and notify'.
destination	Channel the first message is delivered through: email (default), slack, in_app_chat, customer_portal, sms or whatsapp. internal is the absence of a delivery rather than a channel: the issue is created and the requester is not contacted. An unknown value is refused at registration.
sender_email	Required when destination is email — POST /issues refuses an email delivery that does not name the address it is sent from. Must be one of the addresses configured in your Pylon email app.
email_ccs / email_bccs	Arrays of addresses copied on the outbound email. Only meaningful on an email delivery.
default_subject	String used to pre-fill the “Subject” field. Supports {{record.<field>}} tokens resolved against the selected record when the form opens.
default_message	String used to pre-fill the “Message” field. Same token syntax; rendered through a RichText widget and shipped as body_html. Token values are HTML-escaped.
email_templates	Array of { title:, content: } hashes. When non-empty, the form becomes a two-page wizard (see below).
requester_email_default	Default for the “Requester email” field. Accepts a String (same {{record.<field>}} tokens) or a record -> email_string Proc evaluated against the selected record when the form opens.
priority_override	One of urgent, high, medium, low. When set, the “Priority” dropdown is removed from the form and this value is forced in the payload. An unknown value is refused at registration.
show_internal_note	When truthy, adds the “Send as internal note” checkbox to the form. Hidden by default — the requester is notified unless this is opt-in.
issue_id_field	Writable column on the host collection that receives the freshly-created issue id. Best-effort: a writeback failure is logged and surfaced in the success message without rolling back the issue, Pylon having no transaction.

The form exposes the following fields:

Field	Type	Notes
Requester email	String	Required. Pre-filled by requester_email_default. The Pylon contact is created on the fly when the address is unknown.
Subject	String	Required. Default supports {{record.<field>}} tokens.
Message	RichText	Required. Sent as the issue’s body_html, and — unless it is an internal note — the message Pylon delivers to the requester. Token values inside the default are HTML-escaped.
Priority	Enum	Optional. Values: urgent, high, medium, low. Removed from the form when priority_override is set.
Send as internal note	Boolean	Hidden by default. Surfaces only when show_internal_note: true. When checked, the issue is created without contacting the requester, whatever destination says — it is the operator’s call on the record they are looking at.

There is no “Type” field, unlike the Zendesk form: POST /issues does not take one, Pylon accepting type on an update only.

Pylon never returns the priority of an issue, so no column carries it: what the operator picks in the form is applied on creation and shown nowhere in Forest afterwards.

Email-templates wizard

When email_templates is set, the form becomes a two-page wizard:

1. Page 1 — Template. A Template field lists each template’s title plus a sentinel "No template" entry.
2. Page 2 — Body. The same fields as above, with the Message recomputed from the page 1 selection.

Picking a template fills the Message with its interpolated content; taking it back ("No template") restores default_message rather than emptying a required field. Typing into Message in between is preserved across re-renders of the same selection.

collection.use(
  ForestAdminDatasourcePylon::Plugins::CreateIssueWithNotification,
  datasource: pylon_datasource,
  sender_email: '[e-mail]',
  email_templates: [
    { title: 'Refund confirmation',
      content: '<p>Hi {{record.first_name}}, your refund has been processed.</p>' },
    { title: 'Shipping delay',
      content: '<p>Hi {{record.first_name}}, we apologise for the delay shipping order #{{record.order_id}}.</p>' }
  ]
)

Template titles must be unique and cannot be "No template": the title is what the enum carries and what the content is looked up by, so a duplicate would send one template’s content under another’s name. Both are refused at registration rather than discovered by whoever sends the wrong message.

The message body is HTML the operator writes and Pylon delivers to the requester, and the requester address is a free-text field. Restrict this action to the roles that should be able to send mail on your organization’s behalf.

Outcome

• A Pylon 4xx reaches the operator as the action’s own error, with Pylon’s message intact — it names what they filled in. Anything else stays a 500.
• On success the message names the issue by its Pylon number, and says whether the requester was notified and through which channel, or that the issue is internal.
• A failed issue_id_field writeback is appended to that success message as a warning; the issue exists either way.

Reply to an issue

A Single-scope action that answers one Pylon issue on the channel the customer used, or posts an internal note on it. A Slack issue gets a Slack reply and an email issue gets an email: Pylon delivers the reply into the conversation of the message the action names, and the action picks that message for you.

@agent.collection :Order do |collection|
  collection.use(
    ForestAdminDatasourcePylon::Plugins::ReplyToIssue,
    datasource: pylon_datasource,
    issue_id_field: 'pylon_issue_id',
    support_emails: ['[e-mail]']
  )
end

Option	Description
datasource	Required. The ForestAdminDatasourcePylon::Datasource instance.
issue_id_field	Column of the host record holding the Pylon issue id. Omit it when the action sits on PylonIssue itself: the issue is then the selected record.
action_name	Overrides the action label. Defaults to 'Reply to Pylon issue'.
allow_internal_note	Defaults to true, which adds the “Reply type” field so the operator can post an internal note instead. Set it to false to offer public replies only.
support_emails	Addresses of your support inboxes. They are never used as email recipients. Set it: until your team has sent an email in a thread, it is the only way the action knows your own addresses.
post_as_operator	Defaults to false. When true, a public reply is signed by the Pylon user matching the Forest user who runs the action. See Who signs the reply.

The form exposes the following fields:

Field	Type	Notes
Reply type	Enum	Public reply or Internal note. Shown only when allow_internal_note is true. Only Internal note is offered when the issue has no customer-visible message.
Channel	String	Read-only. The channel the reply goes through, or the reason a public reply is not possible.
To	String list	Email replies only. Required. Pre-filled from the conversation and editable.
CC	String list	Email replies only. Pre-filled from the conversation and editable.
Message	RichText	Required. Sent as the reply’s body_html. A message left empty in the editor is refused.

Which channel

The channel is the source of the first customer-visible message of the issue, which means any message that is not an internal note. The reply answers the latest customer-visible message on that channel.

• An issue that started on one channel and moved to another is answered on the first one.
• An issue with no customer-visible message, such as one created as an internal note, cannot get a public reply. Only the internal note is offered. With allow_internal_note: false, the Channel field shows the reason and the action refuses to run.

Email recipients

Pylon does not work out the recipients of an email reply, so the form pre-fills To and CC from the latest email on the channel:

• When the customer wrote that email, To is its sender only. The addresses the customer wrote to include your support inbox. The other addresses in its To are not carried over, not even to CC: add them by hand if they should get the reply.
• When your team wrote it, To is the addresses it was sent to.

In both cases, CC is the CC of that email, minus the addresses already in To.

The support_emails and every address your team wrote from in the thread are left out of To and CC. That applies to the pre-fill and to what the operator types: the success message names any typed address that was left out. A reply with no To is refused.

Who signs the reply

By default, the account that owns the API token signs every reply, and the success message says so.

With post_as_operator: true, a public reply is signed by the active Pylon user whose primary or secondary email matches the email of the Forest user who runs the action. If no active user matches, several do, the Forest user has no email, or the Pylon users cannot be read, the reply is refused and nothing is sent. The action never falls back to signing with the token. Internal notes are always signed by the token.

• The column is the authority. With issue_id_field, an operator who can write that column can reply to any Pylon issue on your organization’s behalf, as with CloseIssue.
• post_as_operator trusts emails. The token can sign as any agent of the workspace, and the only link between a Forest user and a Pylon user is a shared email. Keep both user lists consistent, and restrict the action to the roles that should answer customers.

Cost in Pylon requests

• Every form render reads the thread once, with one GET /issues/{id}/messages (120 requests per minute). The form renders when it opens and each time the Reply type changes. Editing the other fields does not render it again.
• A submit adds one read for an internal note and two for a public reply: the agent renders the form again before running the action, and a public reply reads the thread once more so it answers the latest state of the conversation.
• When the action sits on PylonIssue itself, every render and every submit also resolves the selected issue with one GET /issues/{id} (300 requests per minute).
• With post_as_operator, a public reply adds one GET /users.
• The reply itself is one POST /issues/{id}/reply, and an internal note is one POST /issues/{id}/note. Each endpoint allows 30 requests per minute.

Outcome

• A thread that cannot be read is shown as an error in the Channel field, never as an issue without a customer message. Both reply types stay offered, and an internal note does not depend on the thread.
• A Pylon 4xx reaches the operator with Pylon’s own message.
• Any other failure, a timeout included, may happen after Pylon delivered the message. The action says so and asks the operator to check the issue in Pylon before sending it again.
• On success, the message names the issue, the channel or the email recipients, and who signed the reply.

Close an issue

Registers actions that move the selected Pylon issues to a state — closed unless told otherwise. The ids are read either from the primary keys of the selected records (when the action sits on PylonIssue itself) or from a configurable column of the host record, so you can close a Pylon issue straight from a business row that stores pylon_issue_id.

@agent.collection :Order do |collection|
  collection.use(
    ForestAdminDatasourcePylon::Plugins::CloseIssue,
    datasource: pylon_datasource,
    issue_id_field: 'pylon_issue_id'
  )
end

Option	Description
datasource	Required. The ForestAdminDatasourcePylon::Datasource instance.
issue_id_field	Column of the host record holding the Pylon issue id. Omit it when the action sits on PylonIssue itself — the ids are then the selected primary keys.
state	State the issues are moved to. Defaults to 'closed'. Accepts the slug of a custom Pylon status: it is not checked against the built-in ones, which would refuse the very workflow your organization built. Cannot be empty.
scopes	Subset of %i[single bulk]. Defaults to both. Accepts symbols or strings interchangeably.
action_name	Label of the single-record action. Defaults to 'Close Pylon issue'.
bulk_action_name	Label of the bulk action. Defaults to 'Close selected Pylon issues'.

One action is registered per requested scope:

Scope	Default label
single	”Close Pylon issue”
bulk	”Close selected Pylon issues”

Pick a subset to register fewer variants, e.g. scopes: %i[bulk] registers a single bulk action. Registering both under the same name is refused at registration: a collection keys its actions by name, so the second would overwrite the first and answer with the wrong scope.

Registering the plugin twice with two different state values on the same collection is how you offer several transitions — give each variant its own action_name / bulk_action_name.

Which scope bounds it

The state is written straight through the Pylon client rather than through PylonIssue, because the action is registered on the host collection. But the ids were read before that write, through the collection the action sits on, and the agent intersects the operator’s scope into the filter that read them. So what bounds this action is the scope of the host collection:

• Mounted on PylonIssue, a scope or a segment on PylonIssue bounds exactly what it closes.
• Mounted on a business collection with issue_id_field, what bounds it is the records the operator may see there, and the issue ids those records carry. In that form the column is the authority — an operator who can write it can name any Pylon issue — so treat it as one.

Batch behaviour

The batch is capped at 20 issues (MAX_TARGETS), the same budget a filter-driven write gets: Pylon takes one request per issue, so a wider selection is a long run of sequential writes the request may time out on, leaving the issues closed up to that point closed and reporting which ones to nobody. Past the cap the run is refused before its first write, with a message naming the count and the cap — with one exception today. Mounted on PylonIssue with a selection carrying no scope and no segment, the ids are read through the datasource’s own primary-key lookup, which truncates a pageless read at twenty before the cap can see the rest: fifty selected issues close the first twenty and report “20 issues closed”. The two other forms are exact — issue_id_field on a host collection, and any selection a scope or a segment narrows.

The cap counts the issues named, not the records selected: a column of issue ids is not a key, so a hundred host records naming ten issues is a batch of ten (duplicates are collapsed, so no issue is written — or counted — twice).

Within the batch, each id is processed independently: a single issue Pylon refuses (deleted, or outside the token’s scope) does not abort the rest, and the success message names how many were moved and which ones failed. If every id fails, the action surfaces as an error rather than as a partial success.

If no usable id can be read from the selection — an empty issue_id_field, a renamed column, a record the scope hides — the action answers No Pylon issue id found in '<field>'. rather than calling Pylon. A refusal coming from the datasource itself (a scoped selection on PylonIssue naming more issues by id than one page of lookups covers, for instance) travels to the operator with its own message instead: a selection they can see they made must never be reported as “nothing selected”.