Class RelationService

See

https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-relation

Hierarchy

  • CommonHttpService
    • RelationService

Constructors

constructor

Methods

createRelationship deleteRelationship findSourcesForTarget findTargetFromSource getRelationship initialize

Constructors

constructor

  • new RelationService(getClientInstance): RelationService
  • Internal

    Create a new instance of the service.

    Parameters

    • getClientInstance: (() => CommonHttpClient)
        • (): CommonHttpClient

        • Returns CommonHttpClient

    Returns RelationService

Methods

createRelationship

  • createRelationship(params): Promise<Relation>

  • Creates a relationship between two entities (user, space, content). The 'favourite' relationship is supported by default, but you can use this method to create any type of relationship between two entities.

    For example, the following method creates a 'sibling' relationship between two pieces of content: PUT /wiki/rest/api/relation/sibling/from/content/123/to/content/456

    Permissions required: Permission to access the Confluence site ('Can use' global permission).

    Parameters

    • params: {
          relationName: string;
          sourceKey: string;
          sourceStatus?: string;
          sourceType: "content" | "user" | "space";
          sourceVersion?: number;
          targetKey: string;
          targetStatus?: string;
          targetType: "content" | "user" | "space";
          targetVersion?: number;
      }
      • relationName: string

        The name of the relationship. This method supports the 'favourite' (i.e. 'save for later') relationship. You can also specify any other value for this parameter to create a custom relationship type.

      • sourceKey: string

        • The identifier for the source entity:

        • If sourceType is user, then specify either current (logged-in user), the user key of the user, or the account ID of the user. Note that the user key has been deprecated in favor of the account ID for this parameter. See the migration guide for details.

        • If sourceType is 'content', then specify the content ID.

        • If sourceType is 'space', then specify the space key.

      • OptionalsourceStatus?: string

        The status of the source. This parameter is only used when the sourceType is 'content'.

      • sourceType: "content" | "user" | "space"

        The source entity type of the relationship. This must be 'user', if the relationName is 'favourite'.

      • OptionalsourceVersion?: number

        The version of the source. This parameter is only used when the sourceType is 'content' and the sourceStatus is 'historical'.

      • targetKey: string

        • The identifier for the target entity:

        • If targetType is user, then specify either current (logged-in user), the user key of the user, or the account ID of the user. Note that the user key has been deprecated in favor of the account ID for this parameter. See the migration guide for details.

        • If targetType is 'content', then specify the content ID.

        • If targetType is 'space', then specify the space key.

      • OptionaltargetStatus?: string

        The status of the target. This parameter is only used when the targetType is 'content'.

      • targetType: "content" | "user" | "space"

        The target entity type of the relationship. This must be 'space' or 'content', if the relationName is 'favourite'.

      • OptionaltargetVersion?: number

        The version of the target. This parameter is only used when the targetType is 'content' and the targetStatus is 'historical'.

    Returns Promise<Relation>

    Returned if the relationship is created.

    Path

    PUT /wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey} @scopes-current write:confluence-content @scopes-beta read:relation:confluence, read:space:confluence, read:user:confluence, read:content:confluence, write:relation:confluence

    See

    https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-relation#api-wiki-rest-api-relation-relationname-from-sourcetype-sourcekey-to-targettype-targetkey-put

deleteRelationship

  • deleteRelationship(params): Promise<void>

  • Deletes a relationship between two entities (user, space, content).

    Permissions required: Permission to access the Confluence site ('Can use' global permission). For favourite relationships, the current user can only delete their own favourite relationships. A space administrator can delete favourite relationships for any user.

    Parameters

    • params: {
          relationName: string;
          sourceKey: string;
          sourceStatus?: string;
          sourceType: "content" | "user" | "space";
          sourceVersion?: number;
          targetKey: string;
          targetStatus?: string;
          targetType: "content" | "user" | "space";
          targetVersion?: number;
      }
      • relationName: string

        The name of the relationship.

      • sourceKey: string

        • The identifier for the source entity:

        • If sourceType is user, then specify either current (logged-in user), the user key of the user, or the account ID of the user. Note that the user key has been deprecated in favor of the account ID for this parameter. See the migration guide for details.

        • If sourceType is 'content', then specify the content ID.

        • If sourceType is 'space', then specify the space key.

      • OptionalsourceStatus?: string

        The status of the source. This parameter is only used when the sourceType is 'content'.

      • sourceType: "content" | "user" | "space"

        The source entity type of the relationship. This must be 'user', if the relationName is 'favourite'.

      • OptionalsourceVersion?: number

        The version of the source. This parameter is only used when the sourceType is 'content' and the sourceStatus is 'historical'.

      • targetKey: string

        • The identifier for the target entity:

        • If targetType is user, then specify either current (logged-in user), the user key of the user, or the account ID of the user. Note that the user key has been deprecated in favor of the account ID for this parameter. See the migration guide for details.

        • If targetType is 'content', then specify the content ID.

        • If targetType is 'space', then specify the space key.

      • OptionaltargetStatus?: string

        The status of the target. This parameter is only used when the targetType is 'content'.

      • targetType: "content" | "user" | "space"

        The target entity type of the relationship. This must be 'space' or 'content', if the relationName is 'favourite'.

      • OptionaltargetVersion?: number

        The version of the target. This parameter is only used when the targetType is 'content' and the targetStatus is 'historical'.

    Returns Promise<void>

    Path

    DELETE /wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey} @scopes-current write:confluence-content @scopes-beta write:relation:confluence

    See

    https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-relation#api-wiki-rest-api-relation-relationname-from-sourcetype-sourcekey-to-targettype-targetkey-delete

findSourcesForTarget

  • findSourcesForTarget(params): Promise<RelationArray>

  • Returns all target entities that have a particular relationship to the source entity. Note, relationships are one way.

    For example, the following method finds all users that have a 'collaborator' relationship to a piece of content with an ID of '1234': GET /wiki/rest/api/relation/collaborator/to/content/1234/from/user Note, 'collaborator' is an example custom relationship type.

    Permissions required: Permission to view both the target entity and source entity.

    Parameters

    • params: {
          expand?: ("source" | "target" | "relationData")[];
          limit?: number;
          relationName: string;
          sourceStatus?: string;
          sourceType: "content" | "user" | "space";
          sourceVersion?: number;
          start?: number;
          targetKey: string;
          targetStatus?: string;
          targetType: "content" | "user" | "space";
          targetVersion?: number;
      }
      • Optionalexpand?: ("source" | "target" | "relationData")[]

        A multi-value parameter indicating which properties of the response object to expand.

        • relationData returns information about the relationship, such as who created it and when it was created.
        • source returns the source entity.
        • target returns the target entity.
      • Optionallimit?: number

        The maximum number of relationships to return per page. Note, this may be restricted by fixed system limits.

      • relationName: string

        The name of the relationship. This method supports relationships created via Create relationship. Note, this method does not support 'like' or 'favourite' relationships.

      • OptionalsourceStatus?: string

        The status of the source. This parameter is only used when the sourceType is 'content'.

      • sourceType: "content" | "user" | "space"

        The source entity type of the relationship.

      • OptionalsourceVersion?: number

        The version of the source. This parameter is only used when the sourceType is 'content' and the sourceStatus is 'historical'.

      • Optionalstart?: number

        The starting index of the returned relationships.

      • targetKey: string

        The identifier for the target entity:

        • If targetType is user, then specify either current (logged-in user), the user key of the user, or the account ID of the user. Note that the user key has been deprecated in favor of the account ID for this parameter. See the migration guide for details.
        • If targetType is 'content', then specify the content ID.
        • If targetType is 'space', then specify the space key.
      • OptionaltargetStatus?: string

        The status of the target. This parameter is only used when the targetType is 'content'.

      • targetType: "content" | "user" | "space"

        The target entity type of the relationship.

      • OptionaltargetVersion?: number

        The version of the target. This parameter is only used when the targetType is 'content' and the targetStatus is 'historical'.

    Returns Promise<RelationArray>

    Returned if the requested relationships are returned.

    Path

    GET /wiki/rest/api/relation/{relationName}/to/{targetType}/{targetKey}/from/{sourceType} @scopes-current read:confluence-content.summary @scopes-beta read:relation:confluence, read:content-details:confluence

    See

    https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-relation#api-wiki-rest-api-relation-relationname-to-targettype-targetkey-from-sourcetype-get

findTargetFromSource

  • findTargetFromSource(params): Promise<RelationArray>

  • Returns all target entities that have a particular relationship to the source entity. Note, relationships are one way.

    For example, the following method finds all content that the current user has an 'ignore' relationship with: GET /wiki/rest/api/relation/ignore/from/user/current/to/content Note, 'ignore' is an example custom relationship type.

    Permissions required: Permission to view both the target entity and source entity.

    Parameters

    • params: {
          expand?: ("source" | "target" | "relationData")[];
          limit?: number;
          relationName: string;
          sourceKey: string;
          sourceStatus?: string;
          sourceType: "content" | "user" | "space";
          sourceVersion?: number;
          start?: number;
          targetStatus?: string;
          targetType: "content" | "user" | "space";
          targetVersion?: number;
      }
      • Optionalexpand?: ("source" | "target" | "relationData")[]

        A multi-value parameter indicating which properties of the response object to expand.

        • relationData returns information about the relationship, such as who created it and when it was created.
        • source returns the source entity.
        • target returns the target entity.
      • Optionallimit?: number

        The maximum number of relationships to return per page. Note, this may be restricted by fixed system limits.

      • relationName: string

        The name of the relationship. This method supports relationships created via Create relationship. Note, this method does not support 'like' or 'favourite' relationships.

      • sourceKey: string

        The identifier for the source entity:

        • If sourceType is user, then specify either current (logged-in user), the user key of the user, or the account ID of the user. Note that the user key has been deprecated in favor of the account ID for this parameter. See the migration guide for details.
        • If sourceType is 'content', then specify the content ID.
        • If sourceType is 'space', then specify the space key.
      • OptionalsourceStatus?: string

        The status of the source. This parameter is only used when the sourceType is 'content'.

      • sourceType: "content" | "user" | "space"

        The source entity type of the relationship.

      • OptionalsourceVersion?: number

        The version of the source. This parameter is only used when the sourceType is 'content' and the sourceStatus is 'historical'.

      • Optionalstart?: number

        The starting index of the returned relationships.

      • OptionaltargetStatus?: string

        The status of the target. This parameter is only used when the targetType is 'content'.

      • targetType: "content" | "user" | "space"

        The target entity type of the relationship.

      • OptionaltargetVersion?: number

        The version of the target. This parameter is only used when the targetType is 'content' and the targetStatus is 'historical'.

    Returns Promise<RelationArray>

    Returned if the requested relationships are returned.

    Path

    GET /wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType} @scopes-current read:confluence-content.summary @scopes-beta read:relation:confluence, read:content-details:confluence

    See

    https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-relation#api-wiki-rest-api-relation-relationname-from-sourcetype-sourcekey-to-targettype-get

getRelationship

  • getRelationship(params): Promise<Relation>

  • Find whether a particular type of relationship exists from a source entity to a target entity. Note, relationships are one way.

    For example, you can use this method to find whether the current user has selected a particular page as a favorite (i.e. 'save for later'): GET /wiki/rest/api/relation/favourite/from/user/current/to/content/123

    Permissions required: Permission to view both the target entity and source entity.

    Parameters

    • params: {
          expand?: ("source" | "target" | "relationData")[];
          relationName: string;
          sourceKey: string;
          sourceStatus?: string;
          sourceType: "content" | "user" | "space";
          sourceVersion?: number;
          targetKey: string;
          targetStatus?: string;
          targetType: "content" | "user" | "space";
          targetVersion?: number;
      }
      • Optionalexpand?: ("source" | "target" | "relationData")[]

        A multi-value parameter indicating which properties of the response object to expand.

        • relationData returns information about the relationship, such as who created it and when it was created.
        • source returns the source entity.
        • target returns the target entity.
      • relationName: string

        The name of the relationship. This method supports the 'favourite' (i.e. 'save for later') relationship as well as any other relationship types created via Create relationship.

      • sourceKey: string

        • The identifier for the source entity:

        • If sourceType is user, then specify either current (logged-in user), the user key of the user, or the account ID of the user. Note that the user key has been deprecated in favor of the account ID for this parameter. See the migration guide for details.

        • If sourceType is 'content', then specify the content ID.

        • If sourceType is 'space', then specify the space key.

      • OptionalsourceStatus?: string

        The status of the source. This parameter is only used when the sourceType is 'content'.

      • sourceType: "content" | "user" | "space"

        The source entity type of the relationship. This must be 'user', if the relationName is 'favourite'.

      • OptionalsourceVersion?: number

        The version of the source. This parameter is only used when the sourceType is 'content' and the sourceStatus is 'historical'.

      • targetKey: string

        The identifier for the target entity:

        • If targetType is user, then specify either current (logged-in user), the user key of the user, or the account ID of the user. Note that the user key has been deprecated in favor of the account ID for this parameter. See the migration guide for details.
        • If targetType is 'content', then specify the content ID.
        • If targetType is 'space', then specify the space key.
      • OptionaltargetStatus?: string

        The status of the target. This parameter is only used when the targetType is 'content'.

      • targetType: "content" | "user" | "space"

        The target entity type of the relationship. This must be 'space' or 'content', if the relationName is 'favourite'.

      • OptionaltargetVersion?: number

        The version of the target. This parameter is only used when the targetType is 'content' and the targetStatus is 'historical'.

    Returns Promise<Relation>

    Returned if the relationship exists.

    Path

    GET /wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey} @scopes-current read:confluence-content.summary @scopes-beta read:relation:confluence, read:content-details:confluence

    See

    https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-relation#api-wiki-rest-api-relation-relationname-from-sourcetype-sourcekey-to-targettype-targetkey-get

Protected Staticinitialize

  • initialize(): void

  • Method to initialize the class. Normally used to set up validation rules.

    Returns void

Settings

Member Visibility

On This Page

Constructors
Methods