sfdoc

sfdoc is a Django web app that securely integrates easyDITA with Salesforce to enable automated publishing for documentation writers.

Salesforce

Articles are uploaded as drafts, then published when the bundle changes are approved in sfdoc. If bundles changes are rejected, no action is taken in the Salesforce org (drafts remain). Articles are created and drafts updated as needed. sfdoc treats article URL names as unique IDs for the articles, so if an article changes its URL name it will be seen as a new article. Articles that have been deleted in easyDITA will be archived in the Salesforce org.

Connected app

You will need to create a connected app in the Salesforce org to use for API access. Follow these steps to create the connected app in your Salesforce org:

1. Create a Private Key and Self-Signed Digital Certificate
2. Create a Connected App

Use the client ID and private key when setting up the environment variables.

Org setup

Several custom fields need to be created on the Knowledge article object. See the env section of this project's app.json for details.

Make sure that Knowledge is enabled in the org and that the API user is marked as a Knowledge user.

easyDITA

sfdoc assumes that easyDITA has been configured to use their Notify Pull Publishing feature, where the webhook has been configured to be sent to your sfdoc instance at /publish/webhook/. Publish from the top-level DITA map to ensure that related changes are propagated through the system.

The easyDITA bundle referenced by the webhook must contain HTML files which are create with the DITA Open Toolkit in easyDITA. There are some assumptions about the file naming and contents:

• HTML files must have certain tags and attributes - see html.py for details
• Image filenames must be unique
• Article URL names must be unique

Amazon Web Services S3

S3 is used to host the images for both draft and production stages.

Production images are stored in a flat structure at the root of the bucket. Draft images are stored in a flat structure inside a folder at the root of the bucket (folder name is set as environment variable). Storing the items in a flat structure ensures clear and conside image URLs, but the tradeoff is that all image filenames must be unique, so that images aren't overwritten.

sfdoc uploads linked images to the draft directory, then once the bundle changes are approved they are copied to the production directory (bucket root) and deleted from the draft directory.

Environment variables

sfdoc uses environment variables for configuration, whether the site is run locally or on a server. As a Django app sfdoc supports the standard Django settings.

Further required environment variables are listed in the env section of this project's app.json file.

Run the app locally

Local interactions with any Django app are done using the manage.py file.

Integration tests

You can get a feeling for the flow of the app's data by reading and running the integration tests. These tests destroy data and therefore should never be run on production. Look at "sfdoc/publish/tests/test_integration.py" for more information.

Prerequisites

On Mac OS, brew can install both of these.

• Postgres must be installed and running, with a database created for the app
• Redis must be installed and running

Setup

1. Clone the repository
2. Create a virtual environment with Python 3
3. Activate the virtual environment and install the requirements: $ pip install -r requirements/local.txt
4. Create a .env file with the necessary environment variables (look at env.example and/or app.json) and use it every time you run manage.py by setting the environment variable DJANGO_READ_DOT_ENV_FILE=True.

Setting up .env requires accounts on EasyDITA, S3 and an SF.org with appropriate customizations. Talk to Entsys about all of those.

Django commands

$ python manage.py test             # run tests
$ python manage.py sqlcreate        # get the SQL for creating a database
$ python manage.py migrate          # set up the database
$ python manage.py createsuperuser  # create a superuser
$ python manage.py runserver        # run the app locally

Other commands

$ pytest                            # run pytest directly
$ pytest --profile-svg              # generate a profiling diagram and other files.
$ pytest --cov                      # generate coverage data
$ coverage html                     # generate nice HTML files in "htmlcov" dir

## Deploy to Heroku

Use this button to deploy your own instance of sfdoc to Heroku.

[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)

## Administration

Users must have staff permissions to view the publish app.