The updateBylineProperties function allows you to programmatically update the title, icon and tooltip values for confluence:contentBylineItem Forge apps. This function is available in @forge/confluence-bridge version 3.1.0 and above.

This must be used in conjunction with the contentPropertyKey manifest parameter in the byline module. See the contentPropertyKey documentation for more information.

While this function updates the byline properties in the UI, it does not persist the values to the content property. You will need to make a separate call to the content property API to persist these values. This requires the read:page:confluence and write:page:confluence scopes.

This function must be called in an app outside of confluence:contentBylineItem, but rendered on the same page, like:

confluence:backgroundScript
confluence:pageBanner
macro

Function Parameter

The updateBylineProperties function accepts the following parameters:

Name	Type	Description
`propertyKey`	`string`	The key of the content property which stores the `title`, `icon`, and `tooltip` byline properties. This should match the byline module contentPropertyKey in the manifest.
`valueUpdate`	`{ title?: string, icon?: string, tooltip?: string }`	An object containing the updated values of the byline properties. If none is supplied, the app will fallback to using default byline properties.

Example

This example shows how to use updateBylineProperties:

1
2
import { updateBylineProperties } from '@forge/confluence-bridge';
import { requestConfluence } from '@forge/bridge';

// POST request to make contentProperty, e.g.
const bodyData = `{
  "key": "byline-property-unique-key"
}`;

const response = await requestConfluence(`/wiki/api/v2/pages/{page-id}/properties`, {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

// PUT request to update contentProperty with new values
bodyData = `{
  "key": "byline-property-unique-key",
  "value": { "title": "Updated title", "icon": "updated-image.png", "tooltip": "Updated tooltip" },
  "version": {
    "number": 2,
    "message": "updated values"
  }
}`;

const response = await requestConfluence(`/wiki/api/v2/pages/{page-id}/properties/{property-id}`, {
  method: 'PUT',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

// Calling updateBylineProperties to programmatically update the byline properties
const propertyKey = 'byline-property-unique-key'
const valueUpdate = {
    title: 'Updated title',
    icon: 'updated-image.png',
    tooltip: 'Updated tooltip'
};

await updateBylineProperties({ propertyKey, valueUpdate });

Response Type

The updateBylineProperties function return type is Promise.