confluence-sync

Creates/updates/deletes Confluence pages based on a list of objects containing the page contents. Supports nested pages and attachments upload.

Also supports updating specific pages directly by providing their id.

Read Features for more information about the two sync modes available, "tree", "flat" and "id".

Table of Contents

Requirements

This library requires:

* A Confluence instance.
* The id of the Confluence space where the pages will be created.
* Valid authentication credentials to access the Confluence instance. It uses the confluence.js library internally, so it supports the same authentication methods as it.

$3

> [!WARNING]
> This library has been tested only with Confluence 8.5.x. It may work with other versions, but it has not been tested.

Installation

Install the package using npm:

``bash
npm install @telefonica/confluence-sync
`

Example

Import it and pass to it a list of pages to sync:

`js title="Example"
import { ConfluenceSyncPages } from '@telefonica/confluence-sync';

const confluenceSyncPages = new ConfluenceSyncPages({
url: "https://your.confluence.com",
authentication: {
oauth2: {
accessToken: "your-oauth2-access-token"
}
},
spaceId: "your-space-id",
rootPageId: "12345678"
logLevel: "debug",
dryRun: false,
});

await confluenceSyncPages.sync([
{
title: 'Welcome to the documentation',
content: 'This is the content of the page',
},
{
title: 'Introduction to the documentation',
content: 'This is the content of the page',
ancestors: ['Welcome to the documentation'],
},
{
title: 'How to get started',
content: 'This is the content of the page',
ancestors: ['Welcome to the documentation', 'Introduction to the documentation'],
attachments: {
'image.png': '/path/to/image.png',
},
}
]);
`

Features

It is possible to use three different sync modes, tree, flat and id.

Every mode supports uploading attachments to the pages. The main differences between them are:

$3

In tree mode, the library receives an object defining a tree of Confluence pages, and it creates/deletes/updates the corresponding Confluence pages. All the pages are created under a __root page, which must be also provided__.

Note that the __root page must exist before running the sync process__, and that __all pages not present in the list will be deleted__.

* Creates Confluence pages from a list of pages with their corresponding paths, under a root page.
* Supports nested pages.
* Creates Confluence pages if they don't exist.
* Updates Confluence pages if they already exist.
* Deletes Confluence pages that are not present in the list.

> [!WARNING]
> All pages not present in the list will be deleted.

$3

It is also possible to use a flat mode, where all pages will be always created under a root page, without nested levels. Differences from the tree mode are:

* Creates Confluence pages from a list of pages __always under the root page.__
* It __does not support nested pages__. So, all pages without id will be created/updated under the root page. So, the ancestors property is not supported in this mode.
* It is also possible to provide a Confluence id for each page. In this case, the library will always update the corresponding Confluence page with the id provided, as in the id mode.

$3

If you want to update only specific pages directly by providing their id, you can use the id mode. In this mode, you don't need to provide a root page id. Each page in the list must have an id, and the library will update the corresponding Confluence page having the id provided. Note that __the pages to update must exist in Confluence before running the sync process__.

Attachments

The library will create a new attachment if it doesn't exist, or delete it and create it again if it already exists.

When defining the attachments, you can use paths relative to the process.cwd() or absolute paths.

> [!NOTE]
> Deleting attachments that already exist in Confluence without uploading a new one to replace it is not supported.

How to get a page id in Confluence

To get a page ID in Confluence, you can use the Confluence REST API or follow the next steps:

* Enter to Confluence.
* Go to the page of the space where you want to create the pages.
* Click on the ... button and select Page information.
* Copy the ID of the page from the URL. For example, if the URL is https://confluence.foo.es/pages/viewpage.action?pageId=12345678, the ID of the page is 12345678.

Sync modes in detail

To get an idea of how the library works in each mode, please read the features section. The following sections provide more details about each mode.

$3

This is the default mode of the library. It creates a tree of Confluence pages under a root page, following the hierarchy provided in the list of pages.

* The root page must exist before running the sync process.
* The library assumes that the __Confluence instance is using the default page hierarchy, where pages are organized in spaces__. It creates all the pages under a root page of the space.
* __The pages are identified by their title__. If a page with the same title already exists, it will be updated. If it doesn't exist, it will be created.
* The ancestors of each page should be ordered always from the root page to the page itself.
* For example, if you want to create a page under the page Introduction to the documentation, which is under the page Welcome to the documentation, you should provide the following list of ancestors: ['Welcome to the documentation', 'Introduction to the documentation'].
* So, the first ancestor of each page must be the root page, if not, it will be added automatically.
* Updates Confluence pages if they already exist under the root page.
* __The pages under the root page that are not present in the list will be deleted.__
* __Updating the root page is not supported__.

$3

To enable the flat mode, you have to set the syncMode property of the configuration object to flat. Differences from the tree mode are:

* Creates Confluence pages from a list of pages __always under the root page.__
* It __does not support nested pages__. So, all pages without id will be created/updated under the root page. The ancestors property is not supported in this mode.
* It supports to pass specific ids for the pages. In such case, those pages will be updated directly in Confluence as in the id mode.

> [!CAUTION]
> If all pages in the list have an id, __you should use the id mode instead of the flat mode__.

$3

Use the "id" mode if you want to update only specific pages directly by providing their id. In this mode:

* Each page in the list must have an id, and the library will update the corresponding Confluence page having the id provided.
* You don't have to provide a root page id. If you provide it, it will throw an error.
* Pages can't have ancestors.

Note that __the pages to update must exist in Confluence before running the sync process__.

`js title="Example using the id mode"
import { ConfluenceSyncPages, SyncModes } from '@telefonica/confluence-sync';

const confluenceSyncPages = new ConfluenceSyncPages({
url: "https://my.confluence.es",
authentication: {
oauth2: {
accessToken: "my-oauth2-access-token"
}
},
spaceId: "MY-SPACE",
logLevel: "debug",
dryRun: false,
syncMode: SyncModes.ID,
});

await confluenceSyncPages.sync([
{
id: '34567890',
title: 'Welcome to the documentation',
content: 'This is the content of the page',
},
]);
`

API

$3

The main class of the library. It receives a configuration object with the following properties:

* url: URL of the Confluence instance.
* apiPrefix: Optional prefix for the Confluence API urls. Default is /rest/.
* personalAccessToken: Personal access token to authenticate in Confluence. To be DEPRECATED in future versions. Use the authentication property instead.
* authentication: Authentication options to access Confluence. It supports the following methods:
* oauth2: OAuth2 authentication. It requires:
* accessToken: Access token to authenticate.
* basic: Basic authentication.
* email: Email of the user.
* apiToken: API token to authenticate.
* jwt: JWT authentication.
* issuer: Issuer of the JWT.
* secret: Secret to sign the JWT.
* expiryTimeSeconds: Optional expiry time of the JWT in seconds.
* spaceId: Key of the space where the pages will be created.
* rootPageId: ID of the root page under the pages will be created. It only can be missing if the sync mode is flat and all the pages provided have an id.
* logLevel: One of silly, debug, info, warn, error or silent. Default is silent.
* dryRun: If true, the pages will not be created/updated/deleted, but the library will log the actions that would be performed. Default is false.
* syncMode: One of tree, flat or id.

When an instance is created, it expose next methods:

$3

This method receives a list of pages to sync, and it creates/deletes/updates the corresponding Confluence pages. All the pages are created under a root page, which must be also provided. Note that the root page must exist before running the sync process, and that all pages not present in the list will be deleted.

The list of pages to sync is an array of objects with the following properties:

* id: _(optional)_ ID of the page. Only used if the sync mode is flat.
* title: Title of the page.
* content: Content of the page.
* ancestors: List of ancestors of the page. It must be an array of page ids. Not supported in id mode. If the sync mode is flat, this property is not supported and any page without id will be created under the root page.
* attachments`: Record of images to attach to the page. The key is the name of the image, and the value is the path to the image. The image will be attached to the page with the name provided in the key. The path to the image should be absolute.

$3

This getter returns the logger instance used internally. You may want to use it to attach listeners, write tests, etc.

Contributing

Please read our Contributing Guidelines for details on how to contribute to this project before submitting a pull request.

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.