# Drupal

The Drupal connector publishes your Content Studio articles as content on your Drupal site, then updates them from Semactic. It relies only on Drupal core modules: nothing to install.

> [!INFO]
> **On this page:** prepare the Drupal site, connect Semactic, choose where to publish, publish an article, update an article, what is sent to Drupal, disconnect, troubleshooting.

## Prepare your Drupal site

A site administrator does this once.

### Enable the modules
In **Extend**, enable the two core modules **JSON:API** and **HTTP Basic Authentication**.

### Allow writing in JSON:API
In **Configuration**, **Web services**, **JSON:API**, select **Accept all JSON:API create, read, update, and delete operations**. Drupal ships read-only: without this setting, Semactic refuses the connection.

### Create an account for Semactic
Create a dedicated user, for example "semactic", with a role that can:
- create and edit the target content type (for example **Article**);
- use the chosen text format (for example **Full HTML**);
- **Create and edit URL aliases**;
- **Administer node published status** (**Administer content** on older versions).

> [!TIP]
> Use a dedicated account rather than your own: you can block it at any time without touching your own access, and its role decides exactly what Semactic can do. The password is stored encrypted.

## Connect Semactic

The connection is set per market: select the right project and market in the top bar.

### Open the Drupal card
In **Integration**, click **Connect** on the **Drupal** card.

### Enter the site and the account
Enter the **Site URL** (for example `https://www.example.com`), then the **Drupal username** and **Password** of the account created for Semactic. Click **Connect Drupal**.

Semactic immediately checks that the site responds, that the account is recognised and that JSON:API accepts write operations. If one of these checks fails, nothing is saved and a message tells you what to fix (see [Troubleshooting](#troubleshooting)).

## Choose where to publish

Once connected, the **Drupal** card shows the site, the account used and the **Test connection** button. Set the publishing target, then click **Save**:

| Setting | What it does |
|---------|--------------|
| **Content type** (required) | The Drupal content type that receives the articles. **Article** is preselected if it exists, as is the only type of a site that has just one. Otherwise, choose it: without a content type, you cannot publish. |
| **Default status when publishing** | **Unpublished** (the default: the content is created on Drupal but stays hidden from visitors) or **Published**. This status prefills the choice offered the first time an article is published; an update keeps the page's current status. |
| **Body field** | Machine name of the formatted text field that receives the article: `body` on a standard content type. |
| **Text format** | Machine name of the format applied to the article: `full_html` by default, or for example `basic_html`. It must keep headings, lists, links, tables and images, and the account must be allowed to use it. |

## Publish an article

The article must be fully approved. In the editor, open the **Publish** step, then the **Drupal** tab of the **Direct CMS publishing** area.

### Choose the status
In **Drupal status**, choose **Unpublished** to review the page in Drupal before it goes live, or **Published** to make it visible right away.

### Check the URL alias
The **URL alias** is prefilled from the title. A path such as `blog/my-article` works too. The final address is shown below the field.

### Mark the article as published
With the **Published** status, the **Also mark this article as published in Semactic** box is ticked: the article moves to **Published** in Semactic and the **Track** step starts measuring its impact. It is not available for unpublished content, which visitors cannot see.

### Publish or schedule
Click **Publish to Drupal**. To publish later, choose **Schedule**, a date and a time, then **Schedule publication**: the last saved version of the article goes out at the scheduled time.

Once the article is sent, the panel shows **Already on Drupal.**, with a **View the page** link if the content is published, and the button becomes **Update the Drupal page**.

## Update an article

The link between a Semactic article and a Drupal content item is created on the **first publication from Semactic**. So everything depends on where the page comes from.

### Article already published from Semactic

Edit the article in Semactic, then click **Update the Drupal page**: Semactic updates the same Drupal content item, without creating a duplicate.

| What is replaced | What is kept |
|------------------|--------------|
| The title | The Drupal content item itself: same ID, same URL |
| **The whole body** of the article, with the Semactic version | The other fields: main image, tags, meta tags, author, creation date, custom fields |
| The publishing status | |
| The URL alias, only if you change it (it is prefilled with the current alias) | |

There is no merge: Semactic does not send "only what changed", it replaces the whole body.

> [!NOTE]
> The **Drupal status** is prefilled with the page's current status: a live page stays live. Change it only if you want to unpublish the page, or to publish content that is still unpublished.

> [!WARNING]
> Once an article is published from Semactic, make text changes in Semactic. Anything edited directly in the body on Drupal is overwritten at the next update.

Whether Drupal keeps the previous version in the content's **Revisions** tab depends on your Drupal version and on the content type settings. If this history matters to you, check it once on a test article.

If the content was deleted on Drupal, the next update creates a new one, with the alias the article had.

### Page that already existed on Drupal

A page created directly in Drupal, or published before the connector was set up, is not linked to any Semactic article, and you cannot link it for now. Publishing it from Semactic does not update it. Depending on your site's configuration, there are two cases:

- Drupal refuses the publication, because the alias is already taken by the existing page: nothing is published;
- Drupal creates a **duplicate**, with an address close to the original one, such as `/the-same-url-0`.

Neither is what you want.

To optimise an existing page while keeping its URL and history:

1. Rework the text in Content Studio.
2. In the **Publish** step, copy it with **Copy text** or **Download HTML**.
3. Paste it into the existing content on Drupal.
4. Back in Semactic, enter the **Published URL** and click **Mark as published** to start tracking.

> [!TIP]
> In short: use the connector for new articles and for the ones it has already published; update pages that existed before manually in Drupal.

## What is sent to Drupal

- **Title**: the article's H1 title. Your Drupal theme displays the content title, so the H1 is not repeated in the body.
- **Body**: the article HTML, in the body field, with the configured text format.
- **Status**: published or unpublished.
- **URL alias**.

The meta title, meta description, main image and tags are not sent: fill them in in Drupal (for example with the Metatag module for metadata).

## Disconnect or reconnect

**Disconnect** stops direct publishing for this market. Content already published stays on your site, unchanged. Semactic keeps the link between each article and its Drupal content item: if you reconnect the same site with the same content type, updates still change the same content items. With another site or another content type, later publications create new content items.

If the account's password changes, if the account is blocked or if the HTTP Basic Authentication module is disabled, the card shows **Reconnection needed**. Click **Reconnect** and enter the new credentials: for the same site, the content type and settings are kept.

## Troubleshooting

| Message | Likely cause |
|---------|--------------|
| We found no Drupal JSON:API at that address | The URL does not point to the Drupal site, or the JSON:API module is not enabled. |
| This is a Drupal site, but its JSON:API module is not enabled | Enable **JSON:API** in **Extend**. |
| Drupal did not recognise this account | Wrong username or password, or the **HTTP Basic Authentication** module is disabled: without it, Drupal ignores the credentials silently. |
| Your site's JSON:API only accepts read operations | In **Configuration**, **Web services**, **JSON:API**, allow all operations. |
| This Drupal account is not allowed to… | The account's role cannot create or edit this content type. |
| This Drupal account cannot set the published status | Grant **Administer node published status** to the role. |
| This Drupal account cannot set the URL alias | Grant **Create and edit URL aliases** to the role. |
| Drupal refused the text format | The machine name is wrong, or the role does not have the **Use the … text format** permission. |
| The content type has no field with that machine name | Fix the **Body field**. |
| This content type no longer exists on your Drupal site | It was deleted or renamed: choose another one. |
| Another article already uses this URL in Semactic | The Drupal page was created, but another Semactic article already has this URL: the article was not marked as published. |

The **Test connection** button checks at any time that Semactic can reach the site with the stored credentials.
