Scaffolding REST API code examples
Overview
This page provides some basic examples to help developers start with the Scaffolding REST API code.
The Scaffolding REST API expects the Confluence page and Scaffolding form structure to be created beforehand.
Using the API
To use this API from scratch, there are 3 basic steps.
If you already have the Confluence pages and Scaffolding structure created, then you can go directly to step 3.
Resources
The following Atlassian resources can help you with the following examples.
Example - Import CSV
This example imports the contents of a CSV file (employees.csv) into an existing table on a Scaffolding form.
// Fetching Scaffolding form
restClient.fetchForm(basicAuthCredentials, pageId)
.then(res => {
const form = res.data.find(f => f.macro === 'table-data' && f.name === 'Employees');
const fields = form.rows;
// Read from CSV file
readCsv('./sample_data/employees.csv', (csvData) => {
// Crafting payload
const values = csvData.map(record => {
return fields.map(f => {
// Parse date into acceptable format
if (f.macro === 'date-data') {
return Object.assign({}, f, {value: parseDate(record[f.name])})
}
// `list-data` value must be an array
if (f.macro === 'list-data') {
return Object.assign({}, f, {value: [record[f.name]]})
}
return Object.assign({}, f, {value: record[f.name]})
})
});
// Convert array into object
form.value = values.reduce((acc, val, index) => {
return Object.assign(acc, {[index]: val})
}, {});
// Payload must be an array
const payload = [form];
// Insert data from CSV to Scaffolding table-data form.
restClient.createRecord(basicAuthCredentials, pageId, payload)
.then((res) => console.log('result >>', res))
.catch((err) => console.error('>>', err))
})
})
.catch((err) => console.log('this is error', err));Example - Import product list
In this example:
Data from a CSV file (products.csv) is extracted.
Pages with an existing LiveTemplate (product-details-storage-format.xml) with a Scaffolding form are created.
Then the macro injects data into the Scaffolding forms on each created page.
// Event handler for `row` event.
ev.on('row', (row) => {
const pageTitle = `${row['Product No']} - ${row['Product Name']}`
// Create page within 'TEST' space using constructed page title and live-template macro
restClient.createPageWithTemplate(basicAuthCredentials, template, 'TEST', pageTitle).then(async (res) => {
if (res.statusCode !== 200) {
console.error(">> Fail to create page.")
console.error(`>> Error ${res.statusCode}:`, res.data.message)
return
}
// Get page id for newly created page
const pageId = res.data.id
// Fetch Scaffolding form and construct payload using the form
const payload = await restClient.fetchForm(basicAuthCredentials, pageId)
.then(form => {
return form.data.map(field => {
const value = row[field.name]
return Object.assign(field, {value})
})
})
.catch(err => console.error(err))
// Insert data to the form.
restClient.createRecord(basicAuthCredentials, pageId, payload)
.then((res) => {
console.log(res)
})
.catch((err) => console.error(err))
})
})Example - Upload attachments
This example uploads attachments into an existing Scaffolding form on a page.
// Fetch Scaffolding form
restClient.fetchForm(basicAuthCredentials, pageId)
.then(res => {
const form = res.data.find(f => f.macro === 'table-data' && f.name === 'Applicants');
const fields = form.rows;
// Upload attachment to Confluence page
restClient.uploadAttachment(basicAuthCredentials, pageId, './products.csv', 'reuaae.docx')
.then((res) => {
if (res.statusCode !== 200) {
console.error(">> Fail to upload attachment")
console.error(`>> Error ${res.statusCode}:`, res.data.message)
return
}
// Retrieve the attachment title
const attachmentId = res.data.results[0].title
// Craft a single record to be inserted to table-data
const record = fields.map(f => {
if (f.name === 'Name') {
return Object.assign({}, f, {value: 'Ted Mahsun'});
}
if (f.name === 'Resume') {
return Object.assign({}, f, {value: attachmentId});
}
});
// Craft values for table-data. Only 1 record for this example
const tableDataValues = [record];
form.value = tableDataValues.reduce((acc, value, index) => {
return Object.assign(acc, { [index]: value })
}, {});
// Payload must be in array
const payload = [form];
// Insert data to Scaffolding form
restClient.createRecord(basicAuthCredentials, pageId, payload)
.then(res => console.log('>>', res))
.catch(err => console.error(">> Fail to insert data.", err))
})
.catch((err) => console.error(err))
})
.catch(err => console.error(err));