Customizing scheduled jobs (#154)

Document how to customize how a scheduled job will be invoked. Specifically, how
to make your job only run once, instead of once per connection.

getting-started/scheduled-jobs.md

@@ -0,0 +1,47 @@
+---
+Scheduled Jobs
+---
+
+# Scheduled Jobs
+
+Most of the functions you define within your app are invoked by the ShipEngine
+Platform in response to user actions. However, it is possible to write functions
+that are invoked on a schedule. This is useful for things like
+[bulk import of tracking event data](../../shipping/tracking/#bulk-import).
+
+To have a function in your app run on a regular basis, contact the
+[ShipEngine Connect team](mailtoc:[email protected]) to set up a schedule.
+You will need to specify the name of the function, and how often you want it
+to run.
+
+## Invocations
+
+By default, a job will be invoked at the scheduled time, once per user connection.
+Each separate invocation will be passed the credentials for a single user connection.
+For example, if you have specified that your function should run hourly, and
+there are 100 ShipEngine user's that have established connections to your app,
+we will invoke your function 100 times every hour, or 2400 times a day.
+
+You can override this behavior by defining a function in your app named `ScheduledFunction`.
+The input for the function is an object that includes attributes for `api_code`
+and `name`. It can also include any hardcoded arguments specified when the
+schedule was created. For example, you might create one scheduled job to run
+daily at 11PM, with the hardcoded parameter `"region" = "us"` and another
+scheduled job to run daily at 5PM, with the hardcoded parameter `"region" = "eu"`.
+
+Example input payload:
+```
+{
+  "api_code": "my-connect-app",
+  "name": "downloadUserActivity"
+  "region": "eu"
+}
+```
+
+Your `ScheduledFunction` implementation has to return an array of objects, where
+each object represents the input to a single invocation. At the scheduled time,
+your function will be invoked once for each object in the array, passing the
+object as the input argument to your scheduled function. If you do not want
+the function to be invoked at all at this time, return an empty array (`[]`). If you
+want to fallback to the default behavior (one invocation per user connection),
+return `null`.

shipping/tracking.md

@@ -19,15 +19,20 @@ when a user requests tracking information via a ShipEngine API.
 > Bulk import requires an app to be built for v4+ of Connect. See [Upgrade v2 to v4](/getting-started/v2-v4-upgrade/)
 
 If a carrier provides tracking information via a bulk export mechanism, you can
-implement the ImportTrackingEvents function. It will be invoked on a regular
-schedule by the ShipEngine platform, and a separate call will be made on behalf
-of each seller who has a connection to your carrier. The input does not contain
-any shipment identifiers - only the credentials associated with the connection
-to the carrier. In most cases, the credentials will include information needed
-to connect to an FTP server to download files, but the actual implementation
-can vary depending on what the carrier provides and you may need to add fields
-to your registration form or settings form to collect additional data from
-sellers.
+implement the [ImportTrackingEvents](../reference/operation/ImportTrackingEvents/)
+function. It will be invoked on a regular schedule by the ShipEngine platform.
+By default, a separate call to the function will be made for each connection to your carrier.
+However, if data for all users is included in a single download, you can
+specify that the function is only invoked once per scheduled time
+[customizing the scheduled job](../../getting-started/scheduled-jobs/).
+When a separate call is made for each connection, the credentials associated
+with the connection will be passed as input to the function. In most cases, the
+credentials will include information needed to connect to an FTP server to
+download files, but the actual implementation can vary depending on what the
+carrier provides. You may need to add fields to your registration form or
+settings form to collect additional data from shippers.
+When you override `ScheduledFunction`, you have explicit control over what data
+is sent as input to the `ImportTrackingEvents` function.
 
 Your function must implement a javascript [AsyncGenerator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator).
 The function should download the bulk tracking file provided by the carrier,

sidebars.yaml

@@ -22,6 +22,8 @@ root:
         label: Publish Your App
       - page: getting-started/forms.md
         label: User Input Forms
+      - page: getting-started/scheduled-jobs.md
+        label: Scheduled Jobs
       - page: getting-started/v2-v4-upgrade.md
         label: Upgrade v2 to v4
       - group: OAuth