User Interface Elements¶

Click this button to undo the last change you made. You can also press ctrl+z instead.

Click this button to redo the last change you undid. You can also press ctrl+shift+z instead.

Click it to save the current state of the exporter to the database. The button is disabled when there are still errors to correct first (empty mandatory field for example).

Exporter Settings: Name¶

This is a short name that is used when displaying the exporter in other parts of the Evergiving Backend. You should choose a short and distinct name for the exporter. The exporter name is mandatory and must be unique.

Exporter Settings: Description¶

This is an optional description of the exporter.

Exporter Settings: Campaigns¶

Select the campaign in your account. The data shown in the export preview will come from this campaign.

Exporter Settings: Output Type¶

This determines which type of output the exporter generates:

Comma-Separated Values (CSV)
Excel Spreadsheet (XLS)
Salesforce Replication (read more about it)
Extensible Markup Language (XML)
JSON API (read more about it)

Exporter Settings: Override File Extension¶

When set, this overrides the extension used for naming the output
file. The default extensions are csv for CSV files, xls for Excel
Spreadsheet, and xml for XML files.

Exporter Settings: Include Column Headers in Output¶

This setting is only visible when the output type is set to
Comma-separated Values (CSV) or Excel Spreadsheet (XLS). If it is
enabled, the first line of the generated CSV or XLS data will contain
the header names (see Selected Column: Title below). Otherwise,
column headers are omitted during export.

Exporter Settings: CSV Field Separator ¶

This setting is only visible when the output type is set to
Comma-separated Values (CSV). It can be used to configure the
character or string used to separate individual fields in a record
(line). Just as with other text input fields, if the setting begins
and ends with a double quote, it is interpreted as a
JSON string -- in
short, it can contain escape sequences for newlines, tab characters,
unicode characters, and so on.

Exporter Settings: CSV Record Separator ¶

This setting is only visible when the output type is set to
Comma-separated Values (CSV). It can be used to configure the
character or string used to separate records (lines) from each other.
Just as with other text input fields, if the setting begins and ends
with a double quote, it is interpreted as a
JSON string -- in
short, it can contain escape sequences for newlines, tab characters,
unicode characters, and so on.

Selected Column: Title ¶

Use this to set the title (or heading, or name) of the currently
selected column. The title isn't used internally but is always
exported to Excel spreadsheet, and to CSV files if the Include Column
Headers in CSV Output setting is enabled.

The special title (auto) means to set the column title to the name
of the column source (see below) or to JavaScript for columns of
type JavaScript.

Selected Column: Comment ¶

Use this to enter a free-form comment for the currently selected
column. You can use this to document the business logic for
reference. This column can be automatically set by the Import
Header feature (see below).

Selected Column: Hide Column in Output ¶

When enabled, the selected column will not be included in the output.
Hidden columns are shown with a red background in the table preview.

The primary reason for creating a hidden column is so that it can be
used as a source for other columns. This technique allows complex
column contents to be assembled from parts, each of which can be
transformed individually.

Selected Column: Always Quote This Column in CSV Output ¶

This setting is only visible when the output type is set to
Comma-separated Values (CSV). When enabled, CSV fields
corresponding to the selected column will always be quoted, even if
quoting would otherwise be unnecessary (because the data doesn't
contain spaces or any other special character.)

Selected Column: Source ¶

Use this setting to select the data source for this column: it can be
one of the following:

a data source (an attribute of the pledge, the row number, or
the export timestamp)
a column source, in which case the output of another column is
used as the input for this column.
JavaScript. Columns of this type are populated with the return
value of a JavaScript snippet. See section Selected Column:
JavaScript Editor below.

Note that when using columns as input for other columns, it's possible
to create a circular dependency. For example, if you have two
columns A and B with A using B as input and B using A as input, you
will have created a cycle for which valid output cannot be determined.
The schema editor will show "(circular dependency)" in the column
output if this is the case.

Selected Column: Transformations ¶

Unless the column source (see above) is set to JavaScript, you will
see a button labelled Add Transformation. Clicking this button
shows a dropdown menu with a list of transformations, all of which are
described in detail below. Select a transformation to add it to the
list of transformations. Transformations are applied to the source
data in top-down order.

When a transformation doesn't match the data type of the source (for
the first transformation) or the result type of the previous
transformation (for the second and subsequent transformations), the
transformation is shown in red in the drop-down menu to indicate that
it is not applicable. For example, applying the Change Time Zone
transformations makes little sense for anything other than a date/time
value.

You can still apply transformations with mismatching type, but the
results most likely won't be useful. Mismatched transformations have
a red warning sign next to them. Hover over it with your mouse to see
what the problem is.

Note that for high-security source items, such as the full credit card
number, only a limited number of transformations is available.

You can remove unwanted transformations by clicking on the button with
an X in it on the right hand side of the transformation. You can also
reorder transformations using drag-and-drop.

Selected Column: JavaScript Editor ¶

When the column type (see above) is set to JavaScript, you will see
an editor pane. Here you can enter JavaScript code. The code you
enter is interpreted as if wrapped in function (pledge, rowNumber) { ... }. In other words, it can access pledge and rowNumber
variables and is supposed to return a value using the return
keyword. The returned value is used as-is as the column output.

The editor pane is using the CodeMirror component and configured to
use
Sublime Text key bindings.

The editor uses JSHint to validate your
JavaScript code. Any issues it finds will be flagged by a warning
right under the line that contains the problem. If you want, you can
add special JSHint directives to your code as described in their
documentation.

The editor supports autocompletion. Press ctrl+space to complete,
if there is only one possible completion, or bring up a list of
completions otherwise.

Selected Column: Cell Format ¶

This setting is only visible when the output type is set to Excel
Spreadsheet (XLS). It specifies the cell format to apply to all
cells in this column.

It is important to understand the difference between this setting and
transformations such as Format Date and Format Number.
Transformations change the actual values in the column, turning them
into string values. The cell format, on the other hand, leaves the
values untouched. The cell format is only used by Excel when
displaying the values.

For example, if you used the Format Number transformation, you could
no longer use the number in an Excel formula to add some amount to it
(because it would actually be a string, not a number). But using cell
format, the number is still a number and can be used in calculations.

Selected Column: Cell Type ¶

This setting is only visible when the output type is set to Excel
Spreadsheet (XLS) and the column type is Javascript. It specifies
the Excel cell type to use for this column. For non-Javascript
columns, the cell type can be deduced from the source or the last
applied transformation. For JavaScript columns, however, it's
necessary to specify the column type.

Table¶

The table view shows you a live preview of the output, displayed as a
simple table. Any changes you make to the exporter settings or the
column settings are reflected here immediately.

There is always exactly one column selected, shown with a green
header. This is the column that any column settings apply to. Other
than that, the column selection has no direct effect on the output.
You can select a different column by clicking on its header.

To the right of the table there are a number of buttons that can be
used to add a new column (plus sign), to remove the currently selected
column (minus sign), and to move the currently selected column to the
left or the right (arrows).

There are also buttons to copy the current column definition and to
paste a column definition from the clipboard over the currently
selected column. Copy-and-paste works across tabs within the same
browser and across browser sessions.

Finally, there is a button to import a set of column headers from a
CSV file (see below)

Note that there always has to be at least one column in the table,
which means you can't remove a column when it is the only column left.

Importing CSV Headers in Bulk¶

If you want to start off with a set of column names you can use the
Import Header modal dialog. Click the corresponding button to the
right of the table. It will bring up a modal dialog with a text area.
Copy-and-paste your CSV text into this area or drag a CSV file onto
the area. There is a live preview of which column headers would be
imported for the current CSV text.

If the CSV file contains a second row, the contents of that row will
be used to set the comment field for each column. Use this to
import a description of the business logic for each column.

Once you are happy with the headers, click the button labelled
Replace All Column Definitions in the bottom right corner. This
will cause all existing columns to be removed and a new set of columns
to be created, one for each header name extracted from the CSV text.

Like every other action, you can undo this action if you later change
your mind.

Preview¶

The preview shows a live preview of the output when the output type is
set to Comma-separated Values (CSV). Note that there is currently
no preview available for Excel.

Transformations¶

Convert to Uppercase ¶

This transformation takes a string and converts it to upper-case
characters.

Convert to Lowercase ¶

This transformation takes a string and converts it to lower-case
characters.

Convert to Title Case ¶

This transformation takes a string and converts it to title-case,
which means to turn the first letter of each word to upper-case and
other letters to lower-case.

Append String ¶

This transformation takes a string and adds a constant string to the
end of it.

Just as with other text input fields, if the string begins and ends
with a double quote, it is interpreted as a
JSON string -- in
short, it can contain escape sequences for newlines, tab characters,
unicode characters, and so on.

Note that any leading and trailing whitespace characters are stripped
from the string unless it is quoted.

Prepend String ¶

This transformation takes a string and adds a constant string to the
beginning of it.

Just as with other text input fields, if the string begins and ends
with a double quote, it is interpreted as a
JSON string -- in
short, it can contain escape sequences for newlines, tab characters,
unicode characters, and so on.

Note that any leading and trailing whitespace characters are stripped
from the string unless it is quoted.

Append Source ¶

This transformation takes a string and adds a string to the end of it
which is taken from another data source. For example, this allows you
to join a supporter's first and last name.

Map ¶

This transformation lets you apply a mapping to the source value. For
each pair of values in the mapping table displayed when you add this
transformation, if the source value matches the value in the first
column it will be replaced by the value in the second column.

If you enable the default value using the checkbox, a special row is
shown at the beginning of the mapping table. Use it to set a
replacement value that should be used when the source value doesn't
match any of the mappings. If the default value is disabled and there
is no replacement for a source value then it will be left as-is.

Just as with other text input fields, if any string in the mapping
table begins and ends with a double quote it is interpreted as a
JSON string.

Format Number ¶

This transformation takes a number and formats it as a string using
the numeral.js library. See their website for
how the format string is interpreted.

Format Date ¶

This transformation takes a date and formats it as a string using the
moment.js library. See their
documentation for how the
format string is interpreted.

Convert to Time Zone ¶

This transformation takes a date and converts it to the given time
zone. You can either select a constant time zone, or the team's or
account's time zone.

Replace Regexp ¶

This transformation takes a string and applies a
regular expression
to it, then replaces the match with the given string. The replacement
string can include
special replacement patterns.

The meaning of the Global search, Case-insensitive and
Multi-line flags is described in
Advanced Searching with Flags.

Add Days to Date ¶

This transformation takes a date and advances it by the given number
of days. For example, using this transformation with the number 1
sets the date to the following day ("tomorrow") and the number -1 sets
the date to the previous day. It returns the new date.

Advance to Month ¶

This transformation takes a date and advances it until the first day
of the month given by the selected source, incrementing the year by
one if necessary.

The source must yield a number between 1 (for January) and 12 (for
December). Behaviour is currently undefined if the number is outside
this range (no error is raised).

Note that if the date is already on the first of the given month then
it will be left unchanged. Use the Add Days to Date transformation
if this behaviour is not desired.

Advance to Day of Month ¶

This transformation takes a date and advances it until the day of the
month given by the selected source, incrementing the month (and
possibly the year) by one if necessary.

If the given value is too large it will be set to the last day in the
month. For example, if the value is 40 and the month is February in a
leap year, the day of month will be set to the 29^th.

Note that if the date is already on the given day of month then it
will be left unchanged. Use the Add Days to Date transformation if
this behaviour is not desired.

Set Blank unless Source Equals ¶

This transformation looks at a given source and compares it to a given
value. If the source matches the comparison value, the transformation
does nothing. If the source doesn't match the comparison value, the
transformation sets the column blank.

Set Blank if Source Matches ¶

This transformation looks at a given source and tries to match it
against a given regular expression. If the source matches the regular
expression, the transformation sets the current column blank. If it
doesn't match then the transformation does nothing.

Set Blank if Equal to Source ¶

This transformation looks at a given source and compares it to the
value in the current column. If the values are identical, the current
column is set blank. If the values are different then the
transformation does nothing.

Use Source if Blank ¶

This transformation uses the given source if the column source
(perhaps after transformations) is blank.

Set Blank if Source Blank ¶

This transformation sets the current column value to blank if the
given source is blank.

Pad Left ¶

This transformation adds the given padding string at the left side of
the source string until the minimum string length has been reached.

Format Phone Number ¶

This transformation uses Google's
libphonenumber to format
phone numbers. It should be applied to a phone number source.
libphonenumber is pretty smart about handling numbers so there should
be no need for prior massaging of the input phone numbers in any way.
(For example, it's fine if the number contains spaces, dashes or
parentheses.)

Use the Source for Country Code argument to choose the country that
should be used when interpreting the phone number. It defaults to the
country of the supporter's primary address. Note that his is only
used for phone numbers that don't include a country code. The source
selected must contain a
ISO_3166-1 alpha-2
country code, not a country name.

The Format drop-down box lets you select how the phone number should
be formatted. National prints the number as it would be dialed from
another phone in the same country. International prints the number
with international country prefix. E.164 prints the number in the
E.164 standardized format.
Mobile Dialing prints the number as it should be dialed from a
mobile phone. Number type doesn't format the phone number, instead it
outputs the phone number's type as determined by libphonenumber: one of
FIXED_LINE, MOBILE, FIXED_LINE_OR_MOBILE, TOLL_FREE,
PREMIUM_RATE, SHARED_COST, VOIP, PERSONAL_NUMBER, PAGER,
UAN, VOICEMAIL, or UNKNOWN.

If the Filter Invalid checkbox is unchecked, a best effort is made
to format numbers even when they are invalid (e.g. too short). If it
is checked, invalid numbers are instead replaced by a string Invalid: <reason>, where <reason> is one of +INVALID_COUNTRY_CODE, TOO_SHORT,
TOO_LONG, and NOT_A_NUMBER.

What does IS_POSSIBLE mean, you ask? It means that there is nothing
obviously wrong with the number: it's not too short or too long, for
example. But thorough validation checking has determined that it's
not a valid number after all. For example, it could mean that while
at first glance the number is long enough, a number starting with
certain digits needs to be longer.