the metadata fetcher
[bse.git] / site / util / bse_fetch.pl
1 #!perl -w
2 use strict;
3 use warnings;
4 use FindBin;
5 use lib "$FindBin::Bin/../cgi-bin/modules";
6 use Getopt::Long;
7 use BSE::API qw(bse_init bse_cfg);
8 use BSE::Util::Fetcher;
9
10 our $VERSION = "1.000";
11
12 bse_init("../cgi-bin");
13
14 my $verbose;
15 my $nosave;
16 my $nolog;
17 my $section = "automatic data";
18 GetOptions(
19            "v:i" => \$verbose,
20            "nosave|n" => \$nosave,
21            "nolog" => \$nolog,
22            "section|s=s" => \$section,
23           );
24 if (defined $verbose && $verbose eq '') {
25   $verbose = 1;
26 }
27
28 my $cfg = bse_cfg();
29
30 my @extra;
31 if (@ARGV) {
32   @extra = ( articles => [ @ARGV ] );
33 }
34
35 my $o = BSE::Util::Fetcher->new
36   (
37    cfg => $cfg,
38    verbose => $verbose,
39    save => !$nosave,
40    log => !$nolog,
41    section => $section,
42    @extra,
43   );
44
45 $o->run();
46
47 my $errors = $o->errors;
48 print STDERR "$_->[0]: $_->[1]\n" for @$errors;
49
50 exit 1 if @$errors;
51
52 =head1 NAME
53
54 bse_fetch.pl - fetch data based on article metadata and store as article metadata
55
56 =head1 SYNOPSIS
57
58   perl bse_fetch.pl
59
60 =head1 DESCRIPTION
61
62 The C<bse_fetch.pl> tool, based on configuration stored in the
63 C<[automatic data]> section of the configuration file and on the
64 article metadata that describes, retrieves data from remote sources
65 and stores it in article metadata.
66
67 Since this mechanism accesses external sites it will only function if
68 access control is enabled.
69
70 At the simplest configuring this requires setting one key in
71 C<[automatic data]>:
72
73   [automatic data]
74   data_example=example
75
76 and defining a field for the URL in C<[global article metadata]>:
77
78   [global article metadata]
79   example_url=
80
81   [article metadata example_url]
82   title=Example URL
83   type=string
84   width=60
85
86 If an article has this metadata set, typically via the article editor,
87 a run of C<bse_fetch.pl> will attempt to fetch the URL defined by that
88 metadata.
89
90 The value of the URL metadata must contain at least one non-blank
91 character or it will be silently skipped.
92
93 You can set a C<< url_patternI<suffix> >> to allow the supplied value
94 to be subtituted into a full url, so for example:
95
96   [automatic data]
97   data_example=example
98   url_pattern_example=http://example.com/location/$s/events
99   url_escape_example=1
100
101   [global article metadata]
102   example_url=
103
104   [article metadata example_url]
105   title=Events location ID
106   type=string
107   width=10
108
109 The C<< url_escapeI<suffix> >> key allows the value from the URL field
110 to be URL escaped.  If this field is a full URL or URL fragment you
111 typically don't want this, but if it's some sort of text to be
112 subtituted into a URL it's recommended.
113
114 The final URLs must have one of C<http:>, C<https:> or C<ftp:> scheme.
115 C<file:> URLs are not permitted.
116
117 By default the content retrived must have a JSON content type and must
118 validate as JSON, you can control this with the C<< validateI<suffix>
119 >> and C<< typesI<suffix> >> keys.  The first specifies a regular
120 expression used to validate the returned content type, while the
121 second can be set to C<none> to disable validation of the content
122 itself.
123
124   [automatic downloads]
125   data_example=example
126   ; accept anything
127   types_example=.
128   validate_example=none
129
130 To prevent storage of excessively large content, by default C<<
131 max_lengthI<suffix> >> to 1000000, which you can set lower or higher
132 as needed.  There is no mechanism to support unlimited sizes.
133
134 By default, if a fetch of the data for a particular article fails, any
135 existing stored metadata for that definition is deleted from the
136 article.  You can prevent that by setting C<< on_failI<suffix> >> to
137 C<keep>.
138
139 If a fetch fails, an error is reported in the audit log.
140
141 Success however is silent by default, you can configure success
142 producing an C<info> audit log message by setting C<<
143 on_successI<suffix> >> to C<log>:
144
145   [automatic downloads]
146   data_example=example
147   on_success_example=log
148
149 =head AUTHOR
150
151 Tony Cook <tony@develop-help.com>
152
153 =cut