Project Documentation
- Adam Labus
General information
Available since v. 3.10.*
How many times have you tried to check or create complete project documentation? How many times have you modified the project and forgotten to update the documentation?. Project documentation allows you to generate comprehensive project documentation containing all information such as schema configuration, components, versions, and custom fields, but also everything related to Jira Service Management such as queues, request types, SLAs, etc.
… and you can do it with just one click in Jira
Where can you generate Project documentation
Documentation is available for each project in Project Settings by clicking the Project Documentation link and on the left sidebar of the project
Direct link documentation
Open a new browser tab and paste url
{JIRA_URL}/secure/ExtenderProjectDocumentation.jspa?projectKey={PROJECT_KEY}where:
{PROJECT_KEY} - Project key
Change the documentation view
You can change the documentation view using the configuration in the GUI (just click the icon in the top right corner) where you have an additional option regarding some configuration items.
Additionally, you can save a new view as the default for documentation.
Share documentation with project administrators
Before making this option available, check if users should see the details of this full configuration
When the Share Project Documentation option in Extensions Configuration
{JIRA_URL}/secure/ExtenderExtensions.jspa
is enabled, all users with project administration rights will see a new section in the project settings and will have the ability to view the full project documentation.
Export to Confluence
Available since v. 3.14.*
Directly from the project documentation in Jira, you can export documentation to Confluence.
Click the Export button and select the space/page where you want to export the documentation. After this action, all project information will be in Confluence, so you can easily maintain and search the documentation.
Automation
Project documentation in Confluence can be automated at your discretion so that it is refreshed periodically. Two dedicated APIs enable this functionality by creating or updating a page:
1) Get Confluence content for the project
This API returns the appropriate documentation format for Confluence
Method type - GET
URL: {JIRA_URL}/rest/extender/1.0/documentation/project/PROJECT_KEY
In addition, you can control which sections will be hidden in the API response regarding project documentation; just add a dedicated parameter:
hideIssueTypes=true
hidePriorities=true
hideWorkflows=true
hideAutomation=true
hideWorkflowSchemes=true
hideIssueTypeScreens=true
hideScreenSchemes=true
hideScreens=true
hideOrganizations=true
hideFields=true
hideFieldContextConfigurations=true
hideFieldConfigurationSchemes=true
hideFieldConfigurations=true
hidePermissions=true
hideIssueSecurity=true
hideNotifications=true
hideVersions=true
hideComponents=true
hideRoles=true
hideRequestTypes=true
hideKnowledgeBase=true
hideSLAs=true
hideCalendars=true
hideQueues=true
hideLanguageSupport=true
hideEmailRequests=true
hideCustomerNotifications=true
Example:
Method type - GET
URL: {JIRA_URL}/rest/extender/1.0/documentation/project/PROJECT_KEY?hideEmailRequests=true&hideCustomerNotifications=true
2a) Create a new Confluence page
Method type - POST
URL: {JIRA_URL}/rest/extender/1.0/confluence/createNewPage
{
"applicationId": "APPLICATION_ID"
"content": "CONTENT_FROM_STEP_1"
"pageTitle": "PAGE_TITLE"
"parentPageId": "PARENT_PAGE_ID"
"spaceKey": "SPACE_KEY"
}2b) Update an existing Confluence page
Method type - POST
URL: {JIRA_URL}/rest/extender/1.0/confluence/updatePage
{
"applicationId": "APPLICATION_ID"
"content": "CONTENT_FROM_STEP_1"
"pageTitle": "PAGE_TITLE"
"pageId": "PAGE_ID"
}JavaScript example
Update an existing Confluence page
//Get project content
$.ajax({
"url": "http://my.jira.pl/rest/extender/1.0/documentation/project/ITSM",
"headers": {
"Authorization": "Basic YWRtaW46YWRtaW4="
}
}).done(function (responseContent) {
//Update page
$.ajax({
"method": "POST",
"url": "http://my.jira.pl/rest/extender/1.0/confluence/updatePage",
"headers": {
"Authorization": "Basic YWRtaW46YWRtaW4=",
"Content-Type": "application/json"
},
"data": JSON.stringify({
"applicationId": "76888b66-b3e3-3eb2-bbdc-34d51bd6c884",
"content": responseContent.content,
"pageId": "819203",
"pageTitle": "Test doc 2"
})
}).done(function (response) {
console.log("DONE !!!")
});
});Create a new Confluence page
//Get project content
$.ajax({
"url": "http://my.jira.pl/rest/extender/1.0/documentation/project/ITSM",
"headers": {
"Authorization": "Basic YWRtaW46YWRtaW4="
}
}).done(function (responseContent) {
//Update page
$.ajax({
"method": "POST",
"url": "http://my.jira.pl/rest/extender/1.0/confluence/createNewPage",
"headers": {
"Authorization": "Basic YWRtaW46YWRtaW4=",
"Content-Type": "application/json"
},
"data": JSON.stringify({
"applicationId": "76888b66-b3e3-3eb2-bbdc-34d51bd6c884",
"content": responseContent.content,
"parentPageId": "819203",
"spaceKey": "KB",
"pageTitle": "Test doc 3"
})
}).done(function (response) {
console.log("DONE !!!")
});
});Bash example
Update an existing Confluence page
This example need two files in the same location
ITSM.json
"applicationId":"641cdf33-1a09-3607-84c7-f79ec1b7a6a5",
"pageId":"171737347",
"pageTitle": "Test documentation",updatePage.sh
#!/bin/bash
#Variables
PROJECT_KEY='ITSM'
APP_URL='https://my.jira.pl'
APP_AUTH='Authorization:Basic YWRtaW4yOmFkbWluMg=='
CONTENT_JSON='Content-Type: application/json'
NO_TOKEN='X-Atlassian-Token: no-check'
#Get project cofiguration content
CONTENT=`curl --silent -k -H "$APP_AUTH" -H "$NO_TOKEN" $APP_URL'/rest/extender/1.0/documentation/project/'$PROJECT_KEY | jq '.content'`
#Create temporary file for project
echo { > "$PROJECT_KEY"_temp.json
cat "$PROJECT_KEY".json >> "$PROJECT_KEY"_temp.json
echo \"content\":"$CONTENT" >> "$PROJECT_KEY"_temp.json
echo } >> "$PROJECT_KEY"_temp.json
#Update page
curl -X POST -H "$APP_AUTH" -H "$NO_TOKEN" -H "$CONTENT_JSON" -d @"$PROJECT_KEY"_temp.json $APP_URL'/rest/extender/1.0/confluence/updatePage'
#Remove temporary file
rm -rf "$PROJECT_KEY"_temp.json
Troubleshooting
Problem | Resolution |
|---|---|
When making a REST call to Confluence the console gives the error {"statusCode":413,"message":"Request too large. Requests for this resource can be at most 5242880 bytes"} | |
When a Jira instance makes an HTTP request to a remote server, the request fails with a message similar to Exception in request: java.net.SocketTimeoutException: Read timed out in http POST to ... |
Example documentation
Image
Availability
Available since v. 4.32.0
Split the Workflows section into Workflow Schemes and Workflows
Workflows section now includes workflow documentation (diagram and text)
Exporting “Workflows” section also exports images of workflow diagrams
Added a documentation shortcut icon in project menu (left sidebar)
Available since v. 4.15.0
New parameters have been added to the “Get Confluence content for project” REST API to hide certain sections
Available since v. 3.15.0
New look for the "Documentation view"
Added option to hide documentation section