forest_admin_datasource_pylon 1.41.0

data/lib/forest_admin_datasource_pylon/plugins/close_issue/messages.rb

@@ -0,0 +1,62 @@
+module ForestAdminDatasourcePylon
+  module Plugins
+    class CloseIssue
+      # What the operator reads once the batch ran. Every id that failed is
+      # named: an action reporting a plain success over a batch it only half
+      # applied is the one thing the panel cannot recover from.
+      module Messages
+        module_function
+
+        def success(succeeded, failed, state)
+          [succeeded_phrase(succeeded, state), failed_phrase(failed)].compact.join(' ')
+        end
+
+        def error(failed, state)
+          return "Failed to #{verb(state)} issue #{failed.first.first}: #{failed.first.last}" if failed.size == 1
+
+          "Failed to #{verb(state)} all #{failed.size} issues. First error: #{failed.first.last}"
+        end
+
+        # Worded around the selection rather than around the run: what the
+        # operator can act on is how many issues they picked, and the cap is
+        # named so the next attempt is a size they can aim for.
+        def too_many(count, state)
+          "This selection names #{count} Pylon issues, more than the #{CloseIssue::MAX_TARGETS} one run of " \
+            'this action covers: Pylon takes one request per issue, and a run stopping halfway would leave ' \
+            "part of the selection #{past_verb(state)} without naming which part. Select fewer issues, and " \
+            'run the action again on the rest.'
+        end
+
+        def no_target(field)
+          return 'No Pylon issue selected.' if field.nil?
+
+          "No Pylon issue id found in '#{field}'."
+        end
+
+        def succeeded_phrase(succeeded, state)
+          return nil if succeeded.empty?
+
+          return "Issue #{succeeded.first} #{past_verb(state)}." if succeeded.size == 1
+
+          "#{succeeded.size} issues #{past_verb(state)}."
+        end
+
+        def failed_phrase(failed)
+          return nil if failed.empty?
+
+          "#{failed.size} failed: #{failed.map(&:first).join(", ")}."
+        end
+
+        # A custom status is named as it is, where the state every organization
+        # has reads as the verb an operator used to fire the action.
+        def verb(state)
+          state == IssueEnums::CLOSED_STATE ? 'close' : "move to #{state}"
+        end
+
+        def past_verb(state)
+          state == IssueEnums::CLOSED_STATE ? 'closed' : "moved to #{state}"
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/plugins/close_issue.rb

@@ -0,0 +1,141 @@
+module ForestAdminDatasourcePylon
+  module Plugins
+    # Moves the selected issues to a state, `closed` unless told otherwise.
+    #
+    # One variant per scope, where the Zendesk plugin builds four: Zendesk has
+    # two terminal statuses to tell apart, Pylon has `closed` and, past it, the
+    # custom status slugs an organization defines — which the `state` option
+    # takes, rather than a second dimension of action names nobody would read.
+    #
+    # The state is written through the client rather than through the
+    # collection: the action is registered on the host collection, which is
+    # rarely PylonIssue, and going through a collection would mean resolving it
+    # from a datasource the plugin was not given.
+    class CloseIssue < ForestAdminDatasourceCustomizer::Plugins::Plugin
+      BaseAction      = ForestAdminDatasourceCustomizer::Decorators::Action::BaseAction
+      ActionScope     = ForestAdminDatasourceCustomizer::Decorators::Action::Types::ActionScope
+      ForestException = ForestAdminDatasourceToolkit::Exceptions::ForestException
+
+      # What one run may write, the budget a filter-driven write already gets:
+      # this writes one PATCH per issue too, sequentially, and the action runs
+      # inside a single HTTP request. Past this the batch is refused before the
+      # first write rather than discovered after the twentieth, where a run cut
+      # short by a timeout leaves part of the selection moved and reports which
+      # part to nobody -- `apply_state` only names it once the loop returns.
+      #
+      # The collection cannot bound this: the action writes through the client,
+      # being registered on the host collection rather than on PylonIssue.
+      MAX_TARGETS = Collections::Writes::MAX_WRITE_REQUESTS
+
+      SCOPE_KEYS = %i[single bulk].freeze
+      SCOPES = { single: ActionScope::SINGLE, bulk: ActionScope::BULK }.freeze
+      NAMES = { single: 'Close Pylon issue', bulk: 'Close selected Pylon issues' }.freeze
+      NAME_OPTIONS = { single: :action_name, bulk: :bulk_action_name }.freeze
+
+      def run(_datasource_customizer, collection_customizer = nil, options = {})
+        opts = options.is_a?(Hash) ? options : {}
+        datasource = opts[:datasource]
+        raise ForestException, 'CloseIssue plugin requires :datasource' unless datasource
+        raise ForestException, 'CloseIssue plugin requires a collection' unless collection_customizer
+
+        state = normalize_state(opts[:state])
+
+        names = normalize_scopes(opts[:scopes]).to_h { |scope_key| [scope_key, name_for(scope_key, opts)] }
+        refuse_colliding_names(names)
+
+        names.each do |scope_key, name|
+          collection_customizer.add_action(name,
+                                           build_action(datasource, SCOPES[scope_key], state, opts[:issue_id_field]))
+        end
+      end
+
+      private
+
+      # Left unchecked against the states Pylon ships: it takes the slug of a
+      # custom status just as well, and refusing one would refuse the very
+      # workflow an organization built.
+      def normalize_state(value)
+        state = value.nil? ? IssueEnums::CLOSED_STATE : value.to_s.strip
+        return state unless state.empty?
+
+        raise ForestException, 'CloseIssue :state cannot be empty.'
+      end
+
+      # Through `to_s`: a value that is neither a string nor a symbol has no
+      # `to_sym`, and raising NoMethodError here would hide the unknown-scope
+      # error that names what was actually passed.
+      def normalize_scopes(value)
+        scopes = Array(value).map { |scope| scope.to_s.to_sym }.uniq
+        scopes = SCOPE_KEYS if scopes.empty?
+        unknown = scopes - SCOPE_KEYS
+        return scopes if unknown.empty?
+
+        raise ForestException,
+              "Unknown CloseIssue scopes: #{unknown.join(", ")}. Allowed: #{SCOPE_KEYS.join(", ")}."
+      end
+
+      # Through `to_s`, like the scopes: an action registers under the name it is
+      # given, and a Symbol reaching the schema breaks the agent rather than the
+      # action -- `GeneratorAction.get_action_slug` calls `strip` on it, and
+      # `GeneratorCollection` sorts the names of a collection's actions, which
+      # raises as soon as a Symbol sits beside a String. It also makes
+      # `:Resolve` and `'Resolve'` the one name they read as.
+      def name_for(scope_key, opts)
+        (opts[NAME_OPTIONS[scope_key]] || NAMES[scope_key]).to_s
+      end
+
+      # `add_action` keys a collection's actions by name, so two variants sharing
+      # one leave the second overwriting the first: the single-record action
+      # disappears from the panel and what stays answers with the other scope --
+      # a bulk action offered on one record, or the reverse. Refused at
+      # registration, like the other configurations this plugin will not perform
+      # quietly.
+      def refuse_colliding_names(names)
+        collision = names.values.tally.find { |_name, count| count > 1 }
+        return if collision.nil?
+
+        raise ForestException,
+              "CloseIssue registers one action per scope, and #{names.keys.join(" and ")} both resolve to " \
+              "'#{collision.first}'. Give :action_name and :bulk_action_name different values, or register " \
+              'a single scope.'
+      end
+
+      def build_action(datasource, scope, state, issue_id_field)
+        BaseAction.new(scope: scope, &executor(datasource, state, issue_id_field))
+      end
+
+      def executor(datasource, state, issue_id_field)
+        lambda do |context, result_builder|
+          ids = IssueTargets.resolve_issue_ids(context, issue_id_field)
+          next result_builder.error(message: Messages.no_target(issue_id_field)) if ids.empty?
+          next result_builder.error(message: Messages.too_many(ids.size, state)) if ids.size > MAX_TARGETS
+
+          succeeded, failed = apply_state(datasource, ids, state)
+          next result_builder.error(message: Messages.error(failed, state)) if succeeded.empty?
+
+          result_builder.success(message: Messages.success(succeeded, failed, state))
+        end
+      end
+
+      # One rescue per id: a single issue Pylon refuses — deleted, or outside
+      # the token's scope — must not cost the operator the rest of a selection,
+      # and what failed is named in the message rather than left to a log.
+      def apply_state(datasource, ids, state)
+        succeeded = []
+        failed = []
+
+        ids.each do |id|
+          datasource.client.update_issue(id, 'state' => state)
+          succeeded << id
+        rescue StandardError => e
+          ForestAdminDatasourcePylon.logger.warn(
+            "[forest_admin_datasource_pylon] failed to move issue #{id} to '#{state}': #{e.class}: #{e.message}"
+          )
+          failed << [id, "#{e.class}: #{e.message}"]
+        end
+
+        [succeeded, failed]
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/plugins/create_issue_with_notification/form_builder.rb

@@ -0,0 +1,173 @@
+require 'cgi'
+
+module ForestAdminDatasourcePylon
+  module Plugins
+    class CreateIssueWithNotification
+      module FormBuilder
+        FieldType = ForestAdminDatasourceCustomizer::Decorators::Action::Types::FieldType
+
+        NO_TEMPLATE = 'No template'.freeze
+        TOKEN_RE = /\{\{\s*record\.([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/
+
+        # Shared with `Payload`, which reads the submitted value back, and with
+        # the executor, which has to neutralise it when the form does not carry
+        # the field at all.
+        INTERNAL_NOTE_LABEL = 'Send as internal note'.freeze
+
+        module_function
+
+        # ActionCollectionDecorator rejects forms that mix Page elements with
+        # non-Page elements, so each mode (flat / wizard) stays homogeneous.
+        def build(opts)
+          body = body_fields(opts)
+          return body if opts[:email_templates].empty?
+
+          [
+            { type: 'Layout', component: 'Page', next_button_label: 'Continue',
+              elements: [template_field(opts[:email_templates])] },
+            { type: 'Layout', component: 'Page', previous_button_label: 'Back',
+              elements: body }
+          ]
+        end
+
+        # No Type field, unlike the Zendesk form: `POST /issues` does not take
+        # one -- Pylon accepts `type` on an update only, which is what
+        # `Issue::UPDATE_ONLY` already says.
+        def body_fields(opts)
+          fields = [requester_field(opts[:requester_email_default]),
+                    subject_field(opts[:default_subject]),
+                    message_field(opts[:default_message], opts[:email_templates])]
+          fields << priority_field unless present?(opts[:priority_override])
+          fields << internal_note_field if opts[:show_internal_note]
+          fields
+        end
+
+        def requester_field(default)
+          { type: FieldType::STRING, label: 'Requester email', is_required: true,
+            description: 'Email of the Pylon requester; the contact is created on the fly when it is unknown. ' \
+                         'Pre-filled from the selected record when available.',
+            default_value: requester_default(default) }
+        end
+
+        def template_field(templates)
+          { type: FieldType::ENUM, label: 'Template', is_required: true,
+            enum_values: [NO_TEMPLATE] + templates.map { |t| t[:title] },
+            default_value: NO_TEMPLATE,
+            description: 'Pick a template to pre-fill the Message on the next page.' }
+        end
+
+        def subject_field(default_subject)
+          { type: FieldType::STRING, label: 'Subject', is_required: true,
+            default_value: template_default(default_subject, escape_html: false) }
+        end
+
+        def message_field(default_message, templates)
+          field = { type: FieldType::STRING, label: 'Message', widget: 'RichText', is_required: true,
+                    description: 'The body of the issue (HTML). Unless it is sent as an internal note, this is ' \
+                                 'the message Pylon delivers to the requester.' }
+          default = template_default(default_message, escape_html: true)
+          return field.merge(default_value: default) if templates.empty?
+
+          # Both keys: `default_value:` fills the first render — drop_default
+          # runs once, the data key sticking after it — where `value:` is
+          # re-evaluated by drop_deferred on every fetch, which is what a
+          # Template change re-fires the message proc through.
+          field.merge(default_value: default, value: message_value(templates, default))
+        end
+
+        # No default: Pylon applies its own when the key is absent, and no
+        # priority is ever read back — the issue payload does not carry one, so
+        # nothing in Forest will show the operator what they picked.
+        def priority_field
+          { type: FieldType::ENUM, label: 'Priority', enum_values: IssueEnums::PRIORITY,
+            description: 'Set on creation only; Pylon does not return the priority of an issue, so it is not ' \
+                         'shown anywhere in Forest afterwards.' }
+        end
+
+        def internal_note_field
+          { type: FieldType::BOOLEAN, label: INTERNAL_NOTE_LABEL,
+            description: 'When checked, the issue is created without contacting the requester.',
+            default_value: false }
+        end
+
+        def requester_default(value)
+          return nil if value.nil?
+          return template_default(value, escape_html: false) if value.is_a?(String)
+
+          lambda do |context|
+            record = fetch_record(context)
+            record.empty? ? nil : value.call(record)
+          rescue StandardError => e
+            ForestAdminDatasourcePylon.logger.warn(
+              "[forest_admin_datasource_pylon] requester_email_default resolver raised: #{e.class}: #{e.message}"
+            )
+            nil
+          end
+        end
+
+        def template_default(template, escape_html:)
+          return nil unless present?(template)
+          return template unless template.match?(TOKEN_RE)
+
+          ->(context) { interpolate(template, fetch_record(context), escape_html: escape_html) }
+        end
+
+        # Returns nil unless Template was just changed, so set_watch_changes
+        # carries over the user's current Message edits between renders.
+        #
+        # Taking a template back restores the configured default rather than
+        # emptying a required field: it is what the operator was handed before
+        # they picked one.
+        def message_value(templates, default)
+          by_title = templates.to_h { |t| [t[:title], t[:content].to_s] }
+          lambda do |context|
+            return nil unless context.field_changed?('Template')
+
+            title = context.get_form_value('Template')
+            return evaluate_default(default, context) if title == NO_TEMPLATE
+
+            interpolated(by_title[title].to_s, context)
+          end
+        end
+
+        # A default carrying tokens is a proc, and one without is the string
+        # itself; no default at all empties the field, as it always did.
+        def evaluate_default(default, context)
+          default.is_a?(Proc) ? default.call(context) : default.to_s
+        end
+
+        def interpolated(content, context)
+          return content unless content.match?(TOKEN_RE)
+
+          interpolate(content, fetch_record(context), escape_html: true)
+        end
+
+        def fetch_record(context)
+          context.get_record([]) || {}
+        rescue StandardError => e
+          ForestAdminDatasourcePylon.logger.warn(
+            "[forest_admin_datasource_pylon] failed to fetch record for token interpolation: #{e.class}: #{e.message}"
+          )
+          {}
+        end
+
+        # The message ships as `body_html` and is delivered as such — an
+        # unescaped `<` or `&` coming from a record value would break the
+        # outbound message or smuggle markup into it.
+        def interpolate(template, record, escape_html:)
+          template.gsub(TOKEN_RE) do
+            key = ::Regexp.last_match(1)
+            value = record[key]
+            next '' if value.nil?
+
+            escape_html ? CGI.escapeHTML(value.to_s) : value.to_s
+          end
+        end
+
+        def present?(value)
+          !value.nil? && value.to_s != ''
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/plugins/create_issue_with_notification/payload.rb

@@ -0,0 +1,72 @@
+module ForestAdminDatasourcePylon
+  module Plugins
+    class CreateIssueWithNotification
+      # What the filled form becomes on the wire, where FormBuilder owns what
+      # the operator fills.
+      module Payload
+        # Only meaningful on an email delivery: Pylon reads the sending address
+        # and the copies off the email app they belong to. The address is
+        # mandatory there — `CreateIssueWithNotification` refuses to register an
+        # email delivery without one.
+        EMAIL_DESTINATION = 'email'.freeze
+
+        module_function
+
+        def build(values, email, opts)
+          payload = {
+            'title' => values['Subject'],
+            'body_html' => values['Message'],
+            # Pylon wants a name alongside the address when it creates the
+            # contact; derive it from the local part. It is ignored when the
+            # contact already exists.
+            'requester_email' => email,
+            'requester_name' => derive_requester_name(email)
+          }
+          priority = opts[:priority_override] || values['Priority']
+          payload['priority'] = priority if present?(priority)
+
+          destination = destination_for(values, opts)
+          payload['destination_metadata'] = metadata(destination, opts) unless internal?(destination)
+          payload
+        end
+
+        # The checkbox wins over the configured destination: it is the
+        # operator's call, made on the record they are looking at.
+        def destination_for(values, opts)
+          truthy?(values[FormBuilder::INTERNAL_NOTE_LABEL]) ? IssueEnums::INTERNAL_DESTINATION : opts[:destination]
+        end
+
+        # An internal issue travels as no metadata at all rather than as
+        # `{destination: 'internal'}`: that is the form the API reference names
+        # for "do not contact the requester", and the one that stays right if
+        # Pylon ever adds a required companion field to a real destination.
+        def internal?(destination)
+          destination == IssueEnums::INTERNAL_DESTINATION
+        end
+
+        def metadata(destination, opts)
+          metadata = { 'destination' => destination }
+          return metadata unless destination == EMAIL_DESTINATION
+
+          metadata['email'] = opts[:sender_email]
+          metadata['email_ccs'] = Array(opts[:email_ccs]) if Array(opts[:email_ccs]).any?
+          metadata['email_bccs'] = Array(opts[:email_bccs]) if Array(opts[:email_bccs]).any?
+          metadata
+        end
+
+        def derive_requester_name(email)
+          local = email.to_s.split('@').first.to_s
+          local.empty? ? email.to_s : local
+        end
+
+        def truthy?(value)
+          value == true || value.to_s.casecmp('true').zero?
+        end
+
+        def present?(value)
+          !value.nil? && value.to_s != ''
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/plugins/create_issue_with_notification.rb

@@ -0,0 +1,175 @@
+module ForestAdminDatasourcePylon
+  module Plugins
+    # Opens a Pylon issue and delivers its first message to the requester.
+    #
+    # Pylon creates the contact on the fly from the form's email, so the action
+    # can be registered on any host collection — no relation to Pylon needed.
+    #
+    # Where Zendesk notifies as 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 `destination_metadata` at
+    # all is what leaves the issue internal. The "Send as internal note"
+    # checkbox is that choice, worded the way the Zendesk plugin words it.
+    #
+    # The form is FormBuilder's, the wire payload is Payload's; what is left
+    # here is the registration, its options, and what the operator reads back.
+    class CreateIssueWithNotification < ForestAdminDatasourceCustomizer::Plugins::Plugin
+      BaseAction      = ForestAdminDatasourceCustomizer::Decorators::Action::BaseAction
+      ActionScope     = ForestAdminDatasourceCustomizer::Decorators::Action::Types::ActionScope
+      ForestException = ForestAdminDatasourceToolkit::Exceptions::ForestException
+
+      NAME = 'Create Pylon issue and notify'.freeze
+
+      def run(_datasource_customizer, collection_customizer = nil, options = {})
+        options = {} unless options.is_a?(Hash)
+        datasource = options[:datasource]
+        raise ForestException, 'CreateIssueWithNotification plugin requires :datasource' unless datasource
+        raise ForestException, 'CreateIssueWithNotification plugin requires a collection' unless collection_customizer
+
+        opts = options.except(:datasource)
+        opts[:email_templates] = normalize_templates(opts[:email_templates])
+        opts[:destination] = normalize_destination(opts[:destination])
+        opts[:priority_override] = normalize_priority(opts[:priority_override])
+        require_sender_email!(opts)
+
+        collection_customizer.add_action(opts[:action_name] || NAME, build_action(datasource, opts))
+      end
+
+      private
+
+      # The title is what the enum carries and what the content is looked up
+      # by, so it has to name one template: a duplicate makes the first
+      # unreachable and would send the other one's content under its name, and
+      # the sentinel of the "pick nothing" option makes the template it names
+      # unpickable. Both are configuration, so both are refused at registration
+      # rather than discovered by whoever sends the wrong message.
+      def normalize_templates(value)
+        templates = Array(value).compact
+        titles = templates.map { |template| template[:title].to_s }
+
+        reserved = titles.include?(FormBuilder::NO_TEMPLATE)
+        raise ForestException, "An email template cannot be titled #{FormBuilder::NO_TEMPLATE.inspect}." if reserved
+
+        duplicated = titles.tally.select { |_title, count| count > 1 }.keys
+        raise ForestException, "Duplicate email template titles: #{duplicated.join(", ")}." if duplicated.any?
+
+        templates
+      end
+
+      def normalize_destination(value)
+        return Payload::EMAIL_DESTINATION if value.nil?
+
+        normalize(value, IssueEnums::DESTINATION, 'destination')
+      end
+
+      # `POST /issues` refuses an email delivery that does not name the address it
+      # is sent from, so the option is mandatory there rather than optional. The
+      # refusal belongs at registration, where it names the option and the agent
+      # will not boot without it, rather than at the first execution, where it
+      # reaches the operator as a Pylon 400 on a form they filled correctly.
+      def require_sender_email!(opts)
+        return unless opts[:destination] == Payload::EMAIL_DESTINATION
+        return if Payload.present?(opts[:sender_email])
+
+        raise ForestException,
+              'CreateIssueWithNotification requires :sender_email when the destination is email. ' \
+              'It must be one of the addresses configured in the Pylon email app.'
+      end
+
+      def normalize_priority(value)
+        return nil unless Payload.present?(value)
+
+        normalize(value, IssueEnums::PRIORITY, 'priority')
+      end
+
+      def normalize(value, allowed, label)
+        normalized = value.to_s
+        return normalized if allowed.include?(normalized)
+
+        raise ForestException,
+              "Unknown CreateIssueWithNotification #{label}: #{normalized}. Allowed: #{allowed.join(", ")}."
+      end
+
+      def build_action(datasource, opts)
+        BaseAction.new(scope: ActionScope::SINGLE, form: FormBuilder.build(opts), &executor(datasource, opts))
+      end
+
+      def executor(datasource, opts)
+        lambda do |context, result_builder|
+          values = submitted_values(context, opts)
+          email  = values['Requester email']
+          next result_builder.error(message: 'Requester email is required.') unless Payload.present?(email)
+
+          issue = create_issue(datasource, Payload.build(values, email, opts))
+          next result_builder.error(message: issue.last) if issue.is_a?(Array)
+
+          writeback = write_back_issue_id(context, opts[:issue_id_field], issue['id'])
+          result_builder.success(message: success_message(issue, values, opts, writeback))
+        end
+      end
+
+      # The form only carries the internal-note checkbox when the option asked
+      # for it, but a form value is not what the form offered: the agent copies
+      # every key the request sent, matched against a field or not. Left as
+      # submitted, the flag would create an internal issue on an action
+      # registered without it — and the requester the plugin exists to notify
+      # would not be. What the form does not show cannot be sent.
+      def submitted_values(context, opts)
+        values = context.form_values
+        return values if opts[:show_internal_note]
+
+        values.merge(FormBuilder::INTERNAL_NOTE_LABEL => false)
+      end
+
+      # A 4xx is Pylon naming what the operator filled in, and reaches them as
+      # the action's own error, message intact: raised, it would leave the agent
+      # to answer 'Unexpected error' — APIError is none of the classes whose
+      # message the translator passes through — and to log nothing either, its
+      # status being under 500. Anything else is Pylon or the network failing,
+      # which no edit of the form would change, and stays the 500 it is.
+      def create_issue(datasource, payload)
+        datasource.client.create_issue(payload)
+      rescue APIError => e
+        raise unless (400..499).cover?(e.status.to_i)
+
+        ForestAdminDatasourcePylon.logger.warn(
+          "[forest_admin_datasource_pylon] Pylon refused the issue creation: #{e.message}"
+        )
+        [:rejected, e.message]
+      end
+
+      # Best-effort: Pylon has no transaction to roll back, and the issue exists
+      # whether or not the host record could be stamped with its id.
+      def write_back_issue_id(context, field, issue_id)
+        return :skipped if field.nil?
+
+        context.collection.update(context.filter, { field => issue_id })
+        :ok
+      rescue StandardError => e
+        ForestAdminDatasourcePylon.logger.warn(
+          "[forest_admin_datasource_pylon] failed to store the issue id in '#{field}': #{e.class}: #{e.message}"
+        )
+        [:failed, "#{e.class}: #{e.message}"]
+      end
+
+      def success_message(issue, values, opts, writeback)
+        base = base_success_message(issue, values, opts)
+        return base unless writeback.is_a?(Array) && writeback.first == :failed
+
+        "#{base} (warning: could not store the issue id on the record: #{writeback.last})"
+      end
+
+      # The number is what an operator recognises an issue by; the id stands in
+      # when Pylon answered without one.
+      def base_success_message(issue, values, opts)
+        reference   = issue['number'] || issue['id']
+        destination = Payload.destination_for(values, opts)
+        if Payload.internal?(destination)
+          return "Issue ##{reference} created (internal, the requester was not contacted)."
+        end
+
+        "Issue ##{reference} created and the requester notified by #{destination.tr("_", " ")}."
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/plugins/issue_targets.rb

@@ -0,0 +1,51 @@
+module ForestAdminDatasourcePylon
+  module Plugins
+    # Which Pylon issues an action was fired on.
+    #
+    # Two shapes, one option: `issue_id_field` names a column of the host
+    # collection holding a Pylon issue id — a business collection keeping the
+    # issue it opened — and, left out, the ids are the primary keys of the
+    # selected records, which is what an action registered on PylonIssue itself
+    # acts on.
+    module IssueTargets
+      module_function
+
+      # A collection whose column was renamed, or a record the scope hides,
+      # answers "no issue selected" through the action's own message rather than
+      # through a stack trace in the panel.
+      #
+      # A ValidationError is the exception: it is the datasource refusing the
+      # selection in words written for the operator — PylonIssue naming more
+      # issues by id than one page of lookups covers, for one — and the agent
+      # surfaces its message as it is. Swallowed, it would reach them as "no
+      # issue selected" about a selection they can see they made, which is the
+      # one thing the message must not say.
+      def resolve_issue_ids(context, field = nil)
+        ids = field.nil? ? primary_key_ids(context) : column_ids(context, field)
+        # Deduplicated: a column of issue ids is not a key, so two selected
+        # records may name the same issue, which would then be written twice and
+        # counted twice in what the action reports back.
+        ids.filter_map do |id|
+          id.to_s unless id.nil? || id.to_s.empty?
+        end.uniq
+      rescue ForestAdminDatasourceToolkit::Exceptions::ValidationError
+        raise
+      rescue StandardError => e
+        source = field ? "from '#{field}'" : 'from the selected records'
+        ForestAdminDatasourcePylon.logger.warn(
+          "[forest_admin_datasource_pylon] failed to resolve the issues to act on #{source}: " \
+          "#{e.class}: #{e.message}"
+        )
+        []
+      end
+
+      def primary_key_ids(context)
+        Array(context.get_record_ids)
+      end
+
+      def column_ids(context, field)
+        context.get_records([field.to_s]).map { |record| record[field.to_s] }
+      end
+    end
+  end
+end