Listing issues through Management API

Listing issues through Management API#

This article documents how to list and acknowledge issues through the Management API and how to retry an action that has failed.

Listing issues through Management API#

To use Management API to list issues that have occurred, follow these steps:

Create a GET request to the following endpoint:
```
https://{{INSTANCE}}/api/errors/
```
In the HTTP request header, include the parameter Authorization with one of the following values:
- Token {{KEY}} if you use a key generated with user credentials in Management API.
- Bearer {{KEY}} if you use a key generated in the Adverity user interface.
Send the request.

As a result, you obtain a response containing a list of the issues that have occurred.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --request GET 'https://{{INSTANCE}}/api/errors/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Example of JSON response (cropped to show one issue):

{
   "count": XX,
   "next": null,
   "previous": null,
   "results":
   [
      {
         "id": ERROR_ID,
         "start": "YYYY-MM-DDTHH:MM:SSZ",
         "end": "YYYY-MM-DDTHH:MM:SSZ",
         "duration": "0s",
         "message": "This error occurred.",
         "type_label": "General",
         "extraction_stage_label": "Fetch",
         "error_cause_label": "Authorization invalid",
         "datastream": {
            "id": DATASTREAM_ID,
            "stack_id": STACK_ID,

            "stack": {
               "add_connection_url": "/core/authorization/add/",
               "add_datastream_url": "/core/apidatastream/add/",
               "change_url": "/core/stack/STACK_ID/change/",
               "datalake": "https://YOUR_STACK.adverity.com/api/storage/STORAGE_ID/",
               "destination": DESTINATION_ID,
               "extracts_url": "/core/datastreamextract/?stack_id=STACK_ID",
               "issues_url": "/core/datastreamextractionlog/?ack__exact=0&stack_id=STACK_ID",
               "id": STACK_ID,
               "name": "STACK_NAME",
               "overview_url": "/STACK_SLUG/",
               "parent": "https://YOUR_STACK.datatap.adverity.com/api/stacks/PARENT/",
               "parent_id": PARENT_ID,
               "slug": "STACK_SLUG",
               "url": "https://YOUR_STACK.datatap.adverity.com/api/stacks/STACK_SLUG/",
               "counts": {
                  "connections": XX,
                  "datastreams": ZZ
               },

               "permissions": {
                  "isDatastreamManager": true
               },

               "default_manage_extract_names": true
            },

            "name": "DATASTREAM_NAME",
            "slug": "DATASTREAM_SLUG",
            "app_label": "APP_LABEL",
            "absolute_url": "https://YOUR_STACK.datatap.adverity.com/APP_LABEL/DATASTREAM_ID/DATASTREAM_SLUG/",
            "change_url": "/APP_LABEL/APP_LABELdatastream/DATASTREAM_ID/change/",
            "extracts_url": "/datastream/DATASTREAM_ID/extracts/all",
            "fetch_url": "https://YOUR_STACK.datatap.adverity.com/APP_LABEL/DATASTREAM_ID/DATASTREAM_SLUG/?action=fetch",
            "overview_url": "/STACK_SLUG/DATASTREAM_SLUG-DATASTREAM_ID/",
            "enabled": false,
            "next_run": "Disabled",
            "url": "https://YOUR_STACK.datatap.adverity.com/api/datastreams/DATASTREAM_ID/",
            "datastream_type_id": DATASTREAM_TYPE_ID,
            "logo_url": "/static/images/api/APP_LABEL.svg",
            "extracts_stream_url": "/api/datastreams/DATASTREAM_ID/extracts/streaming/download/",
            "supports_extended_intervals": false,
            "updated": "YYYY-MM-DDTHH:MM:SSZ",
            "creator": "CREATOR_USERNAME"
         },
         "extract": null,
         "ack": false,
         "ack_url": "/api/errors/ERROR_ID/confirm/",
         "retry_url": "/api/errors/ERROR_ID/retry/",
         "mapping_table_change_url": null,
         "mapping_entries_change_url": null,
         "target_column_change_url": null,
         "transformation_config_url": null,
         "url": "https://YOUR_STACK.datatap.adverity.com/api/errors/ERROR_ID/",
         "datastream_insights_url": null
      }
   ]
}

The following table describes the key response fields for error diagnosis:

Field	Description
`message`	The detailed error message.
`type_label`	General error category.
`extraction_stage_label`	The stage at which the failure occurred: `Fetch`, `Enrich`, or `Import`.
`error_cause_label`	The specific cause of the failure, for example `Authorization invalid`, `API server issue`, or `Adverity-side connector error`.
`ack`	Boolean. `false` if the error is unacknowledged, `true` if acknowledged.
`error_resolution_label`	Suggested remediation step for the error.
`occurrences`	Number of times this error has occurred.

Listing issues that have occurred for a specific datastream through Management API#

To use Management API to list issues that have occurred for a specific datastream, follow these steps:

Create a GET request to the following endpoint:

Replace {{DATASTREAM_ID}} with the datastream’s ID.
```
https://{{INSTANCE}}/api/errors/?datastream_id={{DATASTREAM_ID}}
```
In the HTTP request header, include the parameter Authorization with one of the following values:
- Token {{KEY}} if you use a key generated with user credentials in Management API.
- Bearer {{KEY}} if you use a key generated in the Adverity user interface.
Send the request.

As a result, you obtain a response containing a list of the issues that have occurred for this specific datastream.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --request GET 'https://{{INSTANCE}}/api/errors/?datastream_id={{DATASTREAM_ID}}' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Filtering issues by date#

You can filter the issues returned from this endpoint using the following parameters:

Parameter	Value	Description
`datastream_id`	The ID of the datastream.	Use this parameter to list issues for a specific datastream.
`start_from`	Date `YYYY-MM-DD` or timestamp `YYYY-MM-DDT00:00:00Z`	Use this parameter to list issues that started on or after this date or time.
`start_to`	Date `YYYY-MM-DD` or timestamp `YYYY-MM-DDT00:00:00Z`	Use this parameter to list issues that started on or before this date or time.
`ack`	`any`, `false`, or `true`	Filter by acknowledgment status. Use `any` to return all error types (fetch, enrich, and import errors). Use `false` to return only unacknowledged errors. Use `true` to return only acknowledged errors.

For example, to list issues within a given date range, import the following request example as raw text to your HTTP client (such as Postman):

curl --request GET 'https://{{INSTANCE}}/api/errors/?start_from=YYYY-MM-DD&start_to=YYYY-MM-DD' \
--header 'Authorization: Token {{KEY}}'

You can combine the date filter parameters with other filters. For example, to list issues for a specific datastream within a date range:

curl --request GET 'https://{{INSTANCE}}/api/errors/?datastream_id={{DATASTREAM_ID}}&start_from=YYYY-MM-DD&start_to=YYYY-MM-DD' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Acknowledging issues through Management API#

To acknowledge an issue through Management API, follow these steps:

Respond to the issue with ACK_URL.

As a result, the issue will no longer be shown in Adverity’s user interface.

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Retrying a failed action#

To retry a failed action through Management API, follow these steps:

Respond to the issue with RETRY_URL.

As a result, the most recent action will be repeated.

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Listing issues through Management API

Contents

Listing issues through Management API#