engage_api_clojure

Examples of using the Engage API in Clojure.

Prerequisites

Note that versions in this list are minimums.

Installation prerequisites

Java 15.0.2
Clojure 1.10.2
Leiningen 2.9.5 package manager for Clojure
Git source control manager

Runtime prerequisites

Installing engage_api_clojure

Install this repository by cloning it from GitHub. Here's a typical shell command.

git clone https://github.com/salsalabs/engage_api_clojure.git

When you are done, you'll have a directory named engage_api_clojure. All commands from here on will assume that you're in that directory.

Using engage_api_clojure

Probably the best way to get started with engage_api_clojure is to use the demo module. That shows some good examples of how to require and execute apps using engage_api_clojure.

The demo main is in engage.demo. Here is a sample invocation:

cd ./engage
lein run -m engage.demo.core --help

NAME:
 clj-engage - Demonstrates using the Engage API from Clojure


USAGE:
 clj-engage [global-options] command [command options] [arguments...]

VERSION:
 0.0.1

COMMANDS:
   metrics              Shows the API metrics for your account
   supporter-paginate   Uses generic-paginate to retrieve ~10 supporters
   generic-paginate     Demonstrate typical search
   activity-paginate    Demonstrate searching for activities
   segment-paginate     Demonstrate searching for segments (groups)
   segment-member-pagin Demonstrate searching for segment members
   supporter-paginate   Demonstrate searching for supporters
   supporter-segment-pa Demonstrate searching for segments for a supporter
   email-paginate       Demonstrate searching for emails for email blasts
   yaml-demo            Play with the engage/use-yaml function

GLOBAL OPTIONS:
       --login S  YAML configuration file
   -?, --help

Note that some of the commands have command-specific arguments. For example


cd engage
lein run -m engage.demo --login login_file.yaml activity-search --help

NAME:
 clj-engage activity-paginate - Demonstrate searching for activities

USAGE:
 clj-engage activity-search [command options] [arguments...]

OPTIONS:
       --activityType facebook_ad|fundraise|...|targeted_letter|ticketed_event  :fundraise Select activity type
       --modifiedFrom YYYY-MM-DD    Mon Feb 01 00:00:00 CST 2021  Modified from (YYYY-MM-DD)
       --modifiedTo   YYYY-MM-DD    Sat Feb 01 00:00:00 CST 2025  Modified to (YYYY-MM-DD)
   -?, --help

Configuration file

The demo app requires a YAML configuration file that contains the API tokens. Here's an example:

intToken: your-very-long-engage-integration-api-token
webToken: your-very-long-engage-web-development-token

The file is required. You probably should not leave it anywhere that someone else can read it.

Errors

Errors are typically generated by Java. That means that they include a stack track and can be very messy. If the error is a compile or runtime issue, then the first line of the stack trace is the best place to start.

Engage errors are turned into Java Exceptions. The expection message is the JSON for the list of errors encountered on an API call.

License

Please read the LICENSE file.

Note

This is the preliminary version. Later versions will be structured correctly and just a whole lot easier to use.

Questions? Comments?

If there's an error that's not related to the Engage API, then that's your responsibility to fix. No need to contact Salsa support -- we can't help you.

If there's an with the Engage API, then collect this information:

your organization name
the API token that you're using
the API endpoint that you used
The request payload
The response payload
what you expected to see
what you did see, and
any stack traces that you can collect.

If any of these are more than, say, 5 lines, then please store the long parts in files. Send the collected info, and any attachments, to [email protected]. We'll be glad to help.

salsalabs / engage_api_clojure Goto Github PK