Searching for dialogs

How to search for and filter dialogs in Dialogporten

Introduction

This guide shows how to search for dialogs in Dialogporten. The end-user API supports both REST and GraphQL. The service-owner API supports REST search with additional filters that are useful when managing dialogs and end-user context.

Note that the data structure returned in searches differs from the one returned on the details endpoint; more information about the dialog and what access the authorized user has to various parts of it is only available in the details view.

Basic steps (REST, end-user)

1. Authenticate as an end-user
2. Find the parties that the authenticated end-user is authorized to represent
3. Perform a GET request to /api/v1/enduser/dialogs, supplying query parameters according to the table below:

• All parameters of different types are AND-ed, ie. if supplying party and status, only the dialogs of the provided status owned by the provided party will be returned.
• When supporting multiple values for the same parameter, these values are OR-ed, ie. if supplying two status parameters, dialogs having either of those values will be returned.
• org parameters must be service owner codes as defined in the global altinn-orgs.json, eg. digdir or skd.
• party parameters must have one of the following formats
  • urn:altinn:person:identifier-no:<11 digit national identity number>
  • urn:altinn:organization:identifier-no:<9 digit CCR number>
• serviceResource parameters must refer to a resource in the Resource Registry and use the following format:
  • urn:altinn:resource:<identifier>

Returned information

This will return a collection of dialogs, which contains a subset of the information returned on the dialog details endpoint. Depending on search parameters and the access of the authenticated user, this list may be empty.

If any invalid search parameters are supplied, the API will return 400 Bad Request and a response explaining what errors were encountered. This response follows the standard ProblemDetails format.

Pagination

The search API is paginated using continuation tokens, see the limit-parameter above. If there are additional pages to be fetched, the property hasNextPage will be set to true, and the property continuationToken is populated with a value that should be used to fetch the next page. In order to fetch the next page, supply that value as a continuationToken query parameter. This will maintain ordering and avoid missing items or fetching them twice. This should be repeated as long as hasNextPage is true.

Ordering

Ordering can be performed on the following columns:

• ContentUpdatedAt
• CreatedAt
• UpdatedAt
• DueAt

contentupdatedat is the recommended column when ordering dialogs for inbox-style views and for best performance.

If no explicit ordering is supplied, the default order is contentupdatedat_desc.

Examples

These are example values that might be supplied in the OrderBy query parameter.

• contentupdatedat_desc
• createdat
• createdat_asc
• dueat_asc

The current ordering can be found in the collection model, next to the continuationToken and hasNextPage fields. In REST, the ordering is also embedded into continuationToken, so supplying the continuation token alone is sufficient to preserve ordering.

Basic steps (REST, service owner)

1. Authenticate as a service owner
2. Perform a GET request to /api/v1/serviceowner/dialogs, supplying query parameters according to the table below:

The service-owner search endpoint supports the same core dialog filters as the end-user endpoint, and in addition exposes filters for:

• serviceOwnerLabels, where all supplied labels must match
• serviceOwnerLabels with * suffix for prefix matching, for example finance*
• visibleAfter and visibleBefore

If you need to retrieve end-user context revisions and system labels without the full dialog search result, see the system label reference, which documents the dedicated /api/v1/serviceowner/dialogs/endusercontext endpoint.

Basic steps (GraphQL, end-user)

GraphQL exposes the end-user search operation as searchDialogs. A typical flow is:

1. Authenticate as an end-user
2. Use getParties to discover the party URNs you can search on
3. Call searchDialogs

Example:

query SearchDialogs($party: [String!]) {
  searchDialogs(
    input: {
      party: $party
      limit: 20
      orderBy: [{ contentUpdatedAt: DESC }]
    }
  ) {
    items {
      id
      party
      status
      process
      createdAt
      updatedAt
      contentUpdatedAt
      endUserContext {
        revision
        systemLabels
      }
    }
    hasNextPage
    continuationToken
    orderBy {
      createdAt
      updatedAt
      dueAt
      contentUpdatedAt
    }
    errors {
      message
    }
  }
}

The GraphQL input supports the same implemented end-user filters as the REST endpoint, including:

• serviceResource
• party
• status
• process
• systemLabel
• excludeApiOnly
• isContentSeen
• search
• searchLanguageCode

The same underlying validation rules apply as in REST. In particular, at least one of party or serviceResource must be supplied.

Accepted languages

GraphQL uses the same Accept-Language header as the REST API. If supplied, Dialogporten uses that header when selecting and ordering localized content values in the response.

Pagination

GraphQL pagination uses the continuationToken, hasNextPage, and orderBy fields in the payload.

• Re-use the returned continuationToken to fetch the next page
• Re-use the same orderBy when sending the next request
• If continuationToken is set, orderBy must also be set