Start typing to search…

Listing your bulk export of failed events jobs

📘

Webhooks v3 bulk export of failed events is a new Identity Cloud feature currently in limited availability. Because the feature isn't in general release, that means that both the product, and this documentation, are subject to change at any time.

To verify that status of your bulk export of failed events jobs, regardless of whether those jobs are active, completed, or cancelled, use the /exports endpoint and the GET method. For example, this API call returns the status of all the jobs launched for subscription ID e26925c7-ca17-4b82-8530-e43158c2d63a:

curl -L -X GET \
'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-
f050fee66aae/webhooks/subscriptions/e26925c7-ca17-4b82-8530-e43158c2d63a/events/exports' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer Yh1cEVzUOy0lZNaBxcGbQRQ6qFaRvW0UBqTD81p76ymSNN73P6eulMZFX2-MkN1h'

In turn, you’ll get back information about all your jobs:

{
  "total": 100,
  "_links": {
    "self": {
      "href": "/e0a70b4f-1eef-4856-bcdb-
f050fee66aae/webhooks/subscriptions/e26925c7-ca17-4b82-8530-e43158c2d63a/events/exports"
    }
  },
  "_embedded": {
    "exports": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "createdAt": "2019-08-24T14:15:22Z",
        "updatedAt": "2019-08-24T14:15:22Z",
        "state": "processing",
        "_links": {
          "self": {
            "href": "/e0a70b4f-1eef-4856-bcdb-
f050fee66aae/webhooks/subscriptions/e26925c7-ca17-4b82-8530-e43158c2d63a/events/exports/497f6eca-6276-4993-bfeb-53cbbbba6f08"
          },
          "exports": {
            "href": "/e0a70b4f-1eef-4856-bcdb-
f050fee66aae/webhooks/subscriptions/e26925c7-ca17-4b82-8530-e43158c2d63a/events/exports"
          }
        }
      }
    ]
  }
}

For the moment, let’s focus on the value of the state property in the preceding response. This property reports one of the following states:

  • processing. The operation is still exporting events. That’s useful information, because the process could take several minutes based on the number of events being exported.
  • succeeded. The job has completed and the events are ready for downloading.
  • canceled. Indicates that you used the DELETE method to cancel the job. Cancelling a job means that there won’t be any events for you to download. However, cancelling the job doesn’t affect those events in any way. For example, suppose you started a job for events A, B, and C, but then cancelled that job before it finished. In that case, events A, B, and C remain marked as unexported, meaning they’ll be included if you start a new job.
  • failed. Indicates that the process could not complete. If a job returns this value you should contact Identity Cloud support.

If you know the job ID you can also return status information just for that job. For example, the following command returns status information for the job with the ID f52ede2f-2b5f-48e9-8e58-ded5f3e741ed:

curl -L -X GET \
'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-
f050fee66aae/webhooks/subscriptions/e26925c7-ca17-4b82-8530-e43158c2d63a/events/exports/f52ede2f-2b5f-48e9-8e58-ded5f3e741e' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer Yh1cEVzUOy0lZNaBxcGbQRQ6qFaRvW0UBqTD81p76ymSNN73P6eulMZFX2-MkN1h'

See Checking the status of a bulk export of failed events job for more information.

Using the If-None-Match header

When you query the status of your jobs the response includes an E-Tag header that looks similar to this:

E-Tag: "e2bf27df4e3ae4a24af8ed31959c60c27058be726c58b141ec535a8771fcaf66"

The ETag (short for “entity-tag”) is a unique identifier for the set of jobs you’re asking about. For simplicity’s sake, suppose your query returns four jobs (A, B, C, and D). This query might be ETagged with the value 000001. Suppose you now have a fifth job (job E), and you again query your list of jobs. Because that list has changed, you’re issued a new ETag: 000002. If you yet another query and if there are additional changes then you’ll be issued a third Etag value.

Why does that matter? Well, let’s assume that you keep track of the ETag values returned after you query your jobs. If you do that, you’ll have a quick and easy way to know whether your jobs are up-to-date. For example, suppose you query your available jobs and the response includes the E-Tag header and the value e2bf27df4e3ae4a24af8ed31959c60c27058be726c58b141ec535a8771fcaf66. Sometime later you want to query the jobs again to see if any new jobs have been created since the last time you checked. To make this task easier, just include the If-None-Match header in your command and set the value of that header to the ETag value received the last time you queried the jobs collection. For example:

curl -L -X GET \
'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-
f050fee66aae/webhooks/subscriptions/e26925c7-ca17-4b82-8530-e43158c2d63a/events/exports/f52ede2f-2b5f-48e9-8e58-ded5f3e741e' \
  -H 'Content-Type: application/json' \
  -H 'If-Not-Match: e2bf27df4e3ae4a24af8ed31959c60c27058be726c58b141ec535a8771fcaf66' \
  -H 'Authorization: Bearer Yh1cEVzUOy0lZNaBxcGbQRQ6qFaRvW0UBqTD81p76ymSNN73P6eulMZFX2-MkN1h'

When your request is received, Webhooks v3 compares the value of the If-Not-Match header to the value generated the last time you ran this query. If the two values differ that means that the collection of jobs has changed (for example, a new job has been added to the collection). In return, your response includes information about all your jobs and a new E-Tag header value.

But what if the two values are identical? That simply means that the collection of jobs hasn’t changed: no new jobs have been added and no older jobs have been removed since your last query. In that case, job information isn’t returned. Instead, the response simply consists of the error code 304 Not Modified, indicating that there’s no reason to resend the information.

Here’s something else that’s useful about Etags. One of the properties returned with your collection of jobs is the state property, which tells you the state (processing, completed, cancelled, failed) for each job. If a job has changed state (for example, an active job is now complete) that change generates in a new ETag value. That means that you’ll get back updated job information: 1) if a job has been added or deleted from the collection or, 2) if a job has changed state.

Two things to keep in mind here. First, ETag values are only returned as part of the API response; there’s no way to retrieve an ETag value after the fact. If you decide to use ETags you’ll need to record those values as your responses come in.

Second, ETags aren’t required. If you’d rather get complete job information each time you call the APIs, even if there haven’t been any changes since your last query, then simply ignore the ETag and don’t include the If-Not-Match header in your operations.

See also