rename all the things

lib/App/Netdisco/Manual/WritingCoreWorkers.pod

@@ -0,0 +1,181 @@
+=head1 NAME
+
+App::Netdisco::Manual::WritingCoreWorkers - Developer Documentation on Core Plugins
+
+=head1 Introduction
+
+L<App::Netdisco>'s plugin system allows users to write I<workers> to gather
+information from network devices using different I<transports> and store
+results in the database.
+
+For example, transports might be SNMP, SSH, or HTTPS. Workers might be
+combining those transports with application protocols such as SNMP, NETCONF
+(OpenConfig with XML), RESTCONF (OpenConfig with JSON), eAPI, or even CLI
+scraping. The combination of transport and protocol is known as a I<driver>.
+
+Workers can be restricted to certain vendor platforms using familiar ACL
+syntax. They are also attached to specific actions in Netdisco's backend
+operation (discover, macsuck, etc).
+
+See L<App::Netdisco::Core::Plugin> for more information about core plugins.
+
+=head1 Developing Workers
+
+A worker is Perl code which is run. Therefore it can do anything you like, but
+typically it will make a connection to a device, gather some data, and store
+it in Netdisco's database.
+
+App::Netdisco plugins must load the L<App::Netdisco::Core::Plugin> module.
+This exports a helper subroutine to register the worker. Here's the
+boilerplate code for our example plugin module:
+
+ package App::Netdisco::Core::Plugin::Discover::Wireless::UniFi;
+ 
+ use Dancer ':syntax';
+ use App::Netdisco::Core::Plugin;
+ 
+ # worker registration code goes here, ** see below **
+ 
+ true;
+
+=head1 Registering a Worker
+
+Use the C<register_core_worker> helper from L<App::Netdisco::Core::Plugin> to
+register a worker:
+
+ register_core_worker( \%workerconf, $coderef );
+
+For example:
+
+ register_core_worker({
+   driver => 'unifiapi',
+ }, sub { "worker code here" });
+
+An explanation of the C<%workerconf> options is below. The C<$coderef> is the
+main body of your worker. Your worker is run in a L<Try::Tiny> statement to
+catch errors, and passed the following arguments:
+
+ $coderef->($device, $workerconf);
+
+The C<$device> is an instance of L<App::Netdisco::DB::Result::Device> (that
+is, an object representation of a row in the database). Note that for early
+discover phases this row may not yet exist in the database. The C<$workerconf>
+hashref is the set of configuration parameters you used to declare the worker
+(documented below).
+
+=head2 Package Naming Convention
+
+The package name used where the worker is declared is significant. Let's look
+at the boilerplate example again:
+
+ package App::Netdisco::Core::Plugin::Discover::Wireless::UniFi;
+
+Workers registered in this package will be run during the I<discover> backend
+action (that is, during a C<discover> job). You can replace C<Discover> with
+other actions such as C<Macsuck>, C<Arpnip>, C<Expire>, and C<Nbtstat>.
+
+The component after the action is known as the I<phase> (C<Wireless> in this
+example), and is the way to override a Netdisco built-in worker, by using the
+same name (plus an entry in C<$workerconf>, see below). Otherwise you can use
+any valid Perl bareword for the phase.
+
+=head2 Required Parameters
+
+You must register workers with a C<driver> parameter.
+
+The C<driver> is a label associated with a group of workers and typically
+refers to the combination of transport and application protocol. Examples
+include C<snmp>, C<netconf>, C<restconf>, C<eapi>, and C<cli>. The convention
+is for driver names to be lowercase. Use the driver name to associate
+authentication configuration settings with the correct workers.
+
+=head2 Optional Parameters
+
+Workers may have C<only> and C<no> parameters configured which use the
+standard ACL syntax described in L<the settings
+guide|App::Netdisco::Manual::Configuration>. The C<only> directive is
+especially useful as it can restrict a worker to a given device platform or
+operating system (for example Cisco IOS XR for the C<restconf> driver).
+
+The C<hook> parameter tells Netdisco the role that your worker plays in the
+backend action. It can have one of three values:
+
+=over 4
+
+=item before
+
+A worker that is essential to the action and run before any other workers
+within the same action. For example at the start of C<discover> we need to
+gather basic parameters and create a C<device> row in the database. The first
+C<before> worker which succeeds will short-circuit any others (see Return
+Code, below).
+
+=item on
+
+This worker is run alongside others with the same phase, and also
+short-curcuits any other workers in the same phase (see Return Code, below).
+
+=item after
+
+This worker is run alongside others with the same phase. All workers are run,
+regardless of their return code.
+
+=back
+
+=head2 Worker Execution and Return Code
+
+Workers are configured as an ordered list. They are grouped by C<action> and
+C<phase> (as in Package Naming Convention, above).
+
+Workers defined in C<extra_core_plugins> are run before those in
+C<core_plugins> so you have an opportunity to override core workers by
+adding them to C<extra_core_plugins> and setting C<hook> to C<on> in the
+worker configuration.
+
+The return code of the worker is ignored for those configured with hook
+C<after>, but is significant for those configured with C<befoe> or C<on>.
+If any worker returns a true value then the group at that phase is
+deemed to have been satisfied and Netdsico will move on to other worker
+plugins.
+
+Remember that a worker is only run if it matches the hardware platform of the
+target device and the user's configuration, and is not also excluded by the
+user's configuration.
+
+=head2 Accessing Transports
+
+From your worker you will want to connect to a device to gather data. This is
+done using a transport protocol session (SNMP, SSH, etc). Transports are
+singleton objects instantiated on demand, so they can be shared among a set of
+workers that are accessing the same device.
+
+See the documentation for each transport to find out how to access it:
+
+=over 4
+
+=item *
+
+L<App::Netdisco::Core::Transport::SNMP>
+
+=item *
+
+L<App::Netdisco::Core::Transport::HTTPS>
+
+=item *
+
+L<App::Netdisco::Core::Transport::SSH>
+
+=back
+
+=head2 Database Connections
+
+The Netdisco database is available via the C<netdisco> schema key, as below.
+You can also use the C<external_databases> configuration item to set up
+connections to other databases.
+
+ # plugin package
+ use Dancer::Plugin::DBIC;
+ schema('netdisco')->resultset('Devices')->search({vendor => 'cisco'});
+
+=cut
+