Recently I was sick of needing to update some documentation manually so I wanted to automate it. Fortunately Document360 has an awesome API which makes it really easy to automate this process.
Document360 also has an excellent approach for document authoring where I can check out a page and edit a draft then publish it.
The steps I take are as follows:
- Get the latest version of the article
- Fork the article
- Update the forked page
- Publish this new version of the page.
Document360 API
In Document360 I go to the settings section and choose API tokens.
I then generate an API token for my integration and choose the operations I want it to be able to perform. In this case I need GET/PUT/POST
I then can use my token in the API documentation that the Document360 team have to test the API calls I need. https://apidocs.document360.com/apidocs/get-article
As a side note, the Document360 team generate their API documentation and host it in Document360 using Document360 tools which is pretty cool
Automation with Logic Apps
I then went to Azure and built a helper Logic App which I can reuse to help me update documents in my Document360 project. You can see below where I am calling the Get Article api using the HTTP connector. The key points here are to use your API token as a header.
When I fork the article and update it, each time the version number for the copy of the document I am working on will change so I need to parse the response and you can use the below json schema.
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"version_number": {
"type": "integer"
}
}
}
}
}When I update the document I can pass in a json object with an embedded HTML document which was from the input to my logic app.
{
"title": "@{body('Parse_JSON')?['data']?['title']}",
"content": "@{triggerBody()}",
"hidden": false,
"version_number": @{body('Parse_JSON_-_Forked_Article_Response')?['data']?['version_number']},
"translation_option": "0",
"source": "uat",
"order": 0
}I finally publish the updated document as shown below.
My updated article is now available in my public OR private knowledge base depending which you are using.
Hopefully this shows how easy it is to build your own auto-generated documentation and leverage the document360 platform to host the knowledge base. The Logic App I used is below which might help others.
One point to note, when you do publish an article you will need to log the update against a user, you can simply add an account to Document360 for your automation and use their user id.
Logic App Template
{
"definition": {
"$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
"contentVersion": "1.0.0.0",
"triggers": {
"When_a_HTTP_request_is_received": {
"type": "Request",
"kind": "Http"
}
},
"actions": {
"Response": {
"type": "Response",
"kind": "Http",
"inputs": {
"statusCode": 200
},
"runAfter": {
"Publish_Article": [
"Succeeded"
]
}
},
"Update_Document_in_Document360": {
"type": "Http",
"inputs": {
"uri": "https://apihub.document360.io/v2/Articles/@{variables('article_id')}/en",
"method": "PUT",
"headers": {
"Content-Type": "application/json-patch+json",
"accept": "application/json",
"api_token": "@{parameters('document360_api_key')}"
},
"body": "@outputs('Compose')"
},
"runAfter": {
"Compose": [
"Succeeded"
]
},
"runtimeConfiguration": {
"contentTransfer": {
"transferMode": "Chunked"
}
}
},
"Initialize_variables": {
"type": "InitializeVariable",
"inputs": {
"variables": [
{
"name": "article_id",
"type": "string",
"value": "@{triggerOutputs()?['headers']['article_id']}"
}
]
},
"runAfter": {}
},
"Get_Article": {
"type": "Http",
"inputs": {
"uri": "https://apihub.document360.io/v2/Articles/@{variables('article_id')}/en",
"method": "GET",
"headers": {
"accept": "application/json",
"api_token": "@{parameters('document360_api_key')}"
}
},
"runAfter": {
"Initialize_variables": [
"Succeeded"
]
},
"runtimeConfiguration": {
"contentTransfer": {
"transferMode": "Chunked"
}
}
},
"Parse_JSON": {
"type": "ParseJson",
"inputs": {
"content": "@body('Get_Article')",
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"version_number": {
"type": "integer"
},
"public_version": {
"type": "integer"
},
"latest_version": {
"type": "integer"
},
"status": {
"type": "integer"
},
"order": {
"type": "integer"
}
}
}
}
}
},
"runAfter": {
"Get_Article": [
"Succeeded"
]
}
},
"Fork_Article": {
"type": "Http",
"inputs": {
"uri": "https://apihub.document360.io/v2/Articles/@{variables('article_id')}/fork",
"method": "PUT",
"headers": {
"Content-Type": "application/json-patch+json",
"accept": "application/json",
"api_token": "@{parameters('document360_api_key')}"
},
"body": {
"version_number": "@body('Parse_JSON')?['data']?['version_number']",
"user_id": "@{parameters('document360_user_id')}",
"lang_code": "en"
}
},
"runAfter": {
"Parse_JSON": [
"Succeeded"
]
},
"runtimeConfiguration": {
"contentTransfer": {
"transferMode": "Chunked"
}
}
},
"Compose": {
"type": "Compose",
"inputs": {
"title": "@{body('Parse_JSON')?['data']?['title']}",
"content": "@{triggerBody()}",
"hidden": false,
"version_number": "@body('Parse_JSON_-_Forked_Article_Response')?['data']?['version_number']",
"translation_option": "0",
"source": "uat",
"order": 0
},
"runAfter": {
"Parse_JSON_-_Forked_Article_Response": [
"Succeeded"
]
}
},
"Publish_Article": {
"type": "Http",
"inputs": {
"uri": "https://apihub.document360.io/v2/Articles/@{variables('article_id')}/publish",
"method": "POST",
"headers": {
"Content-Type": "application/json-patch+json",
"accept": "application/json",
"api_token": "@{parameters('document360_api_key')}"
},
"body": {
"version_number": "@body('Parse_JSON_-_Document_Update')?['data']?['version_number']",
"user_id": "@{parameters('document360_user_id')}",
"publish_message": "Publishing from roadmap update logic app: @{workflow()['name']} = @{workflow()['run']['name']}"
}
},
"runAfter": {
"Parse_JSON_-_Document_Update": [
"Succeeded"
]
},
"runtimeConfiguration": {
"contentTransfer": {
"transferMode": "Chunked"
}
}
},
"Parse_JSON_-_Forked_Article_Response": {
"type": "ParseJson",
"inputs": {
"content": "@body('Fork_Article')",
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"version_number": {
"type": "integer"
}
}
}
}
}
},
"runAfter": {
"Fork_Article": [
"Succeeded"
]
}
},
"Parse_JSON_-_Document_Update": {
"type": "ParseJson",
"inputs": {
"content": "@body('Update_Document_in_Document360')",
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"version_number": {
"type": "integer"
}
}
}
}
}
},
"runAfter": {
"Update_Document_in_Document360": [
"Succeeded"
]
}
}
},
"outputs": {},
"parameters": {
"document360_api_key": {
"defaultValue": "[Add Key]",
"type": "String"
},
"document360_user_id": {
"defaultValue": "[Add author user id for automation]",
"type": "String"
},
"$connections": {
"type": "Object",
"defaultValue": {}
}
}
},
"parameters": {
"$connections": {
"type": "Object",
"value": {}
}
}
}
