Sharing with WordPress
This article will show you how to connect Clarify to your WordPress blog as well as how to upload a document.
We recommend using the WP REST API WordPress plugin.
The number one cause of support issues with Clarify center around issues uploading to WordPress using the legacy xmlrpc.php interface that comes with WordPress. Historically there have been security issues with WordPress and xmlrpc interface so many web hosting providers will shut down access to it if the server detects too many requests coming from a particular IP address.
Using this feature requires Clarify 2.0.7 or above and WordPress 4.7 or above.
You should be comfortable with installing and configuring plugins for WordPress.
You will need to download and install two plugins:
1. WP API Categories+Tags
This plugin adds support for assigning tag to a post using a string rather than tag ids. From the Plugins page of your WordPress admin area, search for WP API Categories+Tags.
Alternatively you can locate the plugin at https://wordpress.org/plugins/wp-api-categoriestags/.
2. WordPress REST API - OAuth 1.0a Server
From the Plugins page of your WordPress admin area, search for WordPress REST API - OAuth 1.0a Server.
Alternatively you can locate the plugin at https://wordpress.org/plugins/rest-api-oauth1/.
The only plugin that requires configuration is the OAuth plugin. In the Users menu you will find a new Applications option. Click on it.
Click on Add New
Configure Clarify
Fill in the Consumer Name and Description however you would like. For the Callback, enter the following:
http://127.0.0.1:9998/clarify.app/OAuthLibraryClick Add Consumer when you are done.
Take note of OAuth Credentials for later
After you click Add Consumer will be taken to a screen that shows the OAuth Credentials for the application you just configured. You will need the Client Key and Client Secret when you connect from Clarify to WordPress.
Open Clarify Preferences
Add a WordPress sharing account
From the Share tab click the + button and select WordPress.
Enter your blog URL
Enter the URL to your blog and click Configure.
Enter your key and secret
When you see the following dialog appear enter the Client Key and Client Secret from WordPress and then click Authorize.
Authorize
Next you are taken to your WordPress site in the default web browser. Click the Authorize button to allow Clarify to access your WordPress site in order to upload posts.
After clicking Authorize the WordPress sharing account will be added to Clarify. You can now upload content from Clarify to WordPress.
Clarify ships with one WordPress HTML template that is used when formatting your Clarify document for upload to WordPress. The template does not apply any sort of styling to the content that is uploaded. If you would like to create a custom HTML template that can be used when uploading to WordPress then please refer to the HTML templates manual.
Open Clarify Preferences
Add a WordPress sharing account
From the Share tab click the + button and select WordPress.
Enter your blog URL
Enter the URL to your blog and click Configure.
Enter your blog login credentials
- Enter your username and password.
- Clarify ships with one WordPress HTML template that is used when formatting your Clarify document for upload to WordPress. The template does not apply any sort of styling to the content that is uploaded. If you would like to create a custom HTML template that can be used when uploading to WordPress then please refer to the HTML templates manual.
- Test the connection to make sure you have entered your information correctly.
Uploading to WordPress
Now that you have configured your WordPress sharing account you will see a WordPress icon in the sharing toolbar. Click on it to upload your document to WordPress.
The WordPress upload dialog
You will see this dialog when you upload the document. You can choose the blog, post type, status, and category (if applicable to the selected post type). Any tags you have assigned to the article will be assigned to the post you create in WordPress as well.
Clarify will list all of the available post types in your blog. The default choices allow you to create a Post or a Page. If you have any custom post types they will show up in the menu as well.
After you make your selections click the Upload button. When the upload is complete the URL to the WordPress page will be on the clipboard.
A note about updating images
The next time you upload the Clarify document to WordPress Clarify will replace the existing post. When updating an existing WordPress post Clarify tries to optimize the update process by not uploading images which have already been uploaded. If a step image has been uploaded before then it will not be uploaded again if:
- The image still exists in WordPress and
- The image content has not changed.
If the image needs to be updated the behavior is different depending on whether you are using the xmlrpc.php url or the WP REST API pluging.
When using the WP REST API plugin the existing image on WordPress will be deleted from WordPress and a new image will be uploaded.
When using the xmlrpc.php url the exiting image on WordPress will be updated with the new image.
A couple of things to keep in mind. You should not modify any images that Clarify uploaded within WordPress itself if you plan on using Clarify to update the post later on. If you use a 3rd party WordPress plugin to replace an image in WordPress, Clarify won't know that you did and will not upload the latest image from the Clarify document. In addition, if you use WordPress to edit the image Clarify will not know that you made changes to it.
Troubleshooting
This article provides troubleshooting tips for known issues with posting to WordPress.
Note that these problems are all related to security issues associated with the xmlrpc.php file that ships with WordPress. We are currently working on a solution that uses a new JSON API for WordPress. It requires installing some plugins but so far in our tests does not experience any of the same issues. If you are having trouble posting to WordPress and would like to try the new solution we are working on then send an email to [email protected].
Error 403 Forbidden
If you have iThemes Security installed make sure you don't have it set to deny all xmlrpc.php files. Switch it to only deny pingbacks and try again.
"Unable to reach the Wordpress server", message about your IP address being banned, or a mod_sec.html error
Some web host providers will blacklist an IP address that makes multiple requests to the xmlrpc.php file in a WordPress installation. This is due to the fact that the file has historically been used for nefarious purposes. Since Clarify documents often contain multiple images it is making multiple requests to the xmlrpc.php file on your server and your web hosting service may flag you.
You can contact your hosting provider and ask them to whitelist you so that you can upload to WordPress.
Another potential cause of the "Unable to reach the WordPress server" error could be a WordPress plugin.At least one user has reported issues with using the "EWWW Image Optimizer" plugin. You can try disabling plugins to see if one is causing a problem.
raj
hi, great WP integration. Am I able to password protect the page I upload to WP?
Thanks
Trevor DeVore
@raj - You can't specify any page settings within Clarify to password protect a page. You would need to handle that within WordPress itself.
dr frank
I tried everything mentioned above but no success. I have multiple domains hosted through the same company. One domain works fine connecting with Clarify but the other does not. Unfortunately, the one that I want to connect will not connect. :/
Trevor DeVore
@drfrank - can you send a screenshot of the error you are seeing when trying to connect to [email protected]?
Paul DeL
When I type my wordpress url into the Configure WordPress box and Click Configure, it comes back with "Clarify was unable to find the wp-api or xmlrpc.php endpoints on your server"
Can you help?
Trevor DeVore
@Paul - The HTML of your WordPress template isn't including some data that Clarify is looking for. Try holding down the OPTION key on OS X or ALT key on Windows when you select "WordPress" from the "+" menu. This will bypass the auto discovery feature and allow you to input your WordPress URL directly.
Paul DeL
@Trevor - Thank you, the Option key method worked. But when I try to publish to WordPress, I get this message " An error occurred while uploading the file for step 3: uploading file (418 unused /Users/pauldel/Library/Containers/com.blue"
Trevor DeVore
@Paul - looks like your hosting provider is doing something. Take a look at this web page I found that discusses a 418 error:
https://wordpress.org/support/topic/live-writer-418-unused-server-error
Matthew Baldwin
Hi Trevor. I have clarify working with Wordpress on one machine, but the other machine (same version 2.0.5 build 4) I get the following error. "unable to the wp-api or xmlrpc.php endpoint on the server. I was able to publish on one, but not the other. Strange.
Trevor DeVore
@Matthew - try holding down the Option key (OS X) or Alt key (Windows) when selecting WordPress from the + menu. This will bypass the automatic configuration routine and you can configure WordPress by hand.
Matthew Baldwin
Worked like a champ. Thank you! Clarify is my go to tool!
Lesley
In case it helps anyone else: I couldn't connect until I entered the HTTP version of my domain. My blog defaults to HTTPS so that's what I was entering, and I was getting an "application error".
The HTTP version worked perfectly and posts to Wordpress fine.
TQ
I'm getting an error for a failed handhake after installing API plugins. https://screencast.com/t/cZFgGdz3jws
Trevor DeVore
@tq sorry, the instructions you read are for an update to Clarify that hasn't been released yet. That is why you get the error.
The instructions have been updated to the correct ones for the version you have.
Suentke
Hi there,
is it possible to customize the "The WordPress upload dialog" with specific parameters? In Order to avoid that the user will select a wrong category or something like this?
kind regards
Süntke
Trevor DeVore
@Suentke No, it is not possible to customize the upload dialog.
Süntke
Hi there,
I have a manual theme and I would like to upload the clarify docs in those post. Is that possible? And if so, how can I achieve this?
best regards
Süntke
Trevor DeVore
@Süntke - not in the current version (2.0.11). We just figured out why and have put a fix together. We will post a new version for the public at some point but if you email [email protected] we can send you a link to an update right away.
TKouch
If I am using a theme that supports "courses", will the upload from Clarify to WordPress show "courses" as an option for post type?
If not, will I have problems if I copy/paste the uploaded post to a course? Will this cause issues when I try to re-upload any changes to the document?
Trevor DeVore
@TKouch - the current version of Clarify doesn't support custom post types. If you email [email protected] we can send you a link to an update we are working on that does.
Glenn
I can no longer get the account setup on Wordpress. After putting in the URL I get asked for a key and secret rather than username and password and can't seem to get it sorted. Anyone else had this and how do you get it working. Thanks
Trevor DeVore
@Glenn - The key/secret are related to the WordPress REST API. If you go through the instructions in this article it shows how to configure Clarify to work with the REST API.