WordPress plugin

You will install the plugin, connect it to your SemanticHub account with an API token, and decide what each delivery becomes: a draft or a published post.

The plugin generates nothing on its own. It is a receiver: every fifteen minutes it asks SemanticHub for finished results, stores them in its own queue, and creates posts from them.

This page describes plugin version 0.11.0.

#Install the plugin

1. Upload the SemanticHub plugin under Plugins → Add Plugin → Upload Plugin.
2. Activate it. After a single activation WordPress opens the SemanticHub → Start screen right away.
3. If that screen does not open (for example when you activate several plugins at once), go to SemanticHub → Start in the menu.

You do not enter an API address. It is defined in the plugin code and shown read-only in the settings.

#Connect your account

The Start screen walks through three steps and recalculates their state from the installation every time. Deleting the token moves the screen back to the step that needs attention.

The connection counts as ready only once the capability report has reached at least one goal. Start then disappears from the menu, although the page itself still works at its saved address.

#The capability report

The plugin sends every one of your goals a list of what this specific WordPress installation can assemble: blocks (paragraph, heading, image, list, quote, table, embed, separator), the natively supported seo section, and the plugin version. The block list is the intersection of what the plugin renders with what is actually registered in your installation.

The report is sent automatically: once after activation, then once a day, and whenever you save the token. You can force it from the Start screen or from SemanticHub → Settings → Content compatibility.

Until SemanticHub knows what this installation can render, it generates content for a default block set instead of for your WordPress.

#What happens after a report

• The first report establishes the goal's content contract when the goal does not have one yet — you do not have to configure it by hand.
• Later reports, including the daily repeat with no changes, only record this installation's capabilities. A report never holds delivery back.
• A section the plugin cannot render natively reaches the post in a fallback form, as plain content blocks.
• Once a week you get an email if a manually set contract no longer matches this installation's capabilities or the plugin stopped reporting.

#Where deliveries come from

The plugin pulls content itself — SemanticHub pushes nothing to it, so it needs neither your site address nor an inbound opening.

It only pulls finished texts. A goal that sends raw topics with no generated article has nothing to deliver here: such a delivery is rejected and shows up as failed in SemanticHub. To receive posts in WordPress, the goal must have content generation enabled.

The plugin polls the SemanticHub feed every 15 minutes using a WordPress scheduled task. Each run takes up to 50 results, stores them in the queue, and acknowledges them so they are not sent again. A result that cannot be stored is not acknowledged and arrives in the next poll.

Received results appear under SemanticHub → Content, in the To import, Imported, Dismissed, and Failed tabs. You can publish or dismiss each one. The Fetch now button in settings runs a poll immediately, without waiting for the schedule.

WordPress scheduled tasks are triggered by traffic on the site. On a site with no visitors, a poll may be delayed.

#Publishing defaults

SemanticHub → Settings → Publishing defaults controls four things.

• Default author — the user assigned to created posts. With no choice, the author is the editor who clicked publish. A scheduled poll has nobody logged in, so without a configured author the post is created without a capability check.
• Default category — the category applied to posts created from the queue.
• Require a category from SemanticHub: see Required category.
• Automatic publishing — what a delivery becomes.

Automatic publishing modes:

• Follow the goal setting in SemanticHub (default) — the goal decides. A goal with automatic dispatch enabled produces a published post; every other delivery produces a draft.
• Always draft — the goal setting is ignored and a draft is always created for manual review.
• Always publish — every delivery goes live, including one without the goal flag.

After creating a post the plugin reports its address back to SemanticHub: the public permalink for a published post, and an editor link for a draft or a pending post.

One result is always one post. A new version of the result updates the post created from the first version. The same version fetched twice does not create a copy.

#Required category

In SemanticHub → Settings → Publishing defaults, below the default category, there is a Require a category from SemanticHub checkbox. It is off by default.

The post category is chosen in this order:

1. The category sent from SemanticHub with the delivery, if that category exists in your WordPress.
2. The Default category from the plugin settings.
3. No category. With the requirement off, the post is created without a category set by the plugin.

The plugin reports this installation's category list to SemanticHub, together with whether a category is required. After you change this checkbox, the default category, or the category list, the report goes out on its own about 30 seconds later.

With the requirement on, a delivery with no category and no default category does not create a post:

• the item moves to the Failed tab under SemanticHub → Content;
• the plugin reports the failure to SemanticHub.

Once you set a default category, publish such an item with the Retry button in the Failed tab. If the retry fails again, a notice at the top of the page shows the reason. If the same result arrives again with a category, the plugin publishes it on its own.

The requirement applies to a new post. A new version of a result that updates an existing post goes through without a category and does not change the post's category. After the first publication, the category belongs to your editors.

Any other failure to save a post also moves the item to the Failed tab and is reported to SemanticHub.

#Category from SemanticHub

Once the category list is reported, you can set the category on the SemanticHub side, in one of two places:

• in the goal Action step, in the Receiver fields section, as the default category for every result;
• in a result, on the Delivery tab, in the Receiver fields card. This value replaces the default for that result only. Save it with the Save fields button.

The chosen category travels with the delivery and takes precedence over the Default category from the plugin settings.

#A missing category holds the result

With the requirement on, SemanticHub checks the category before sending. A result without a category does not reach WordPress:

• the result goes back to the Needs approval status with the notice "Delivery on hold: the receiver needs fields filled in";
• the Go to Delivery button takes you to the Receiver fields card.

Fill in the category on the Delivery tab or in the Action step, then click Approve and send. The delivery goes to the same item in the plugin queue, so WordPress gets no second item and no second post.

#A publishing failure is reported back to SemanticHub

The plugin reports every publishing failure. In SemanticHub, the plugin channel on the Delivery tab then shows the Error status with the reason given by WordPress. A result that was missing a category goes back to Needs approval.

The plugin channel has two stages in SemanticHub:

• Sent to plugin: the item waits in the plugin queue, and the post does not exist yet;
• Delivered: the plugin reported the new post and sent back its address.

A channel that has waited for the post report for over a day shows a warning and a Retry button.

#Second language version

The plugin can receive a result in two languages at once. In SemanticHub, in the Action step on the Integration tile, turn on Second language version and pick the language of the source text.

• We translate the title, lead and body at delivery time.
• Both versions arrive together or neither does. A failed translation stops the delivery, and SemanticHub shows it as failed.
• One language is one post. A language pair is two posts linked in Polylang as translations.
• With Polylang active, a single-language post also gets its language set.
• Without Polylang the plugin creates a post only in the source language.

#When it does not work

The Start screen stops on step three. Usually the account has no goal yet. Create a goal in SemanticHub and click Report capabilities and check goals.

"Invalid token (401)". The token was mistyped or deleted in SemanticHub. Generate a new one and save it again. The token field in settings is empty even when a token is stored — submitting an empty value deletes nothing.

"Connection error" with another status. WordPress cannot reach the SemanticHub API. Check that the server has outbound access and that a firewall or security plugin is not blocking outgoing requests.

Nothing arrives although the connection works. Check the last poll time in settings and click Fetch now. If the queue is still empty, the cause is on the goal side: no accepted results, or test mode still enabled.

An item is in the "Failed" tab. With a required category, the usual cause is a delivery with no category and no default category. Set a default category and click Retry. You can also fill in the category in SemanticHub and send the result again: it goes to the same item.

Posts are created as "Pending review" instead of published. The default author lacks the publish_posts capability. Choose another author or publish manually from the Content list.