Page tree
Skip to end of metadata
Go to start of metadata

The Webhook modules provides a framework to trigger external processes from different steps in Magnolia. 

Installation

Maven is the easiest way to install the module. Add the following dependency to your bundle:

<dependency>
	<groupId>info.magnolia.workflow</groupId>
	<artifactId>magnolia-webhooks-integration</artifactId>
	<version>${latest.version}</version>
</dependency>

<!-- To use our examples -->
<dependency>
	<groupId>info.magnolia.workflow</groupId>
	<artifactId>magnolia-webhooks-samples</artifactId>
	<version>${latest.version}</version>
</dependency>

Versions

1.0.1Magnolia 6.2.2

Configuration

To declare a webhook, you need to place its yaml configuration file in a module folder named webhooks.

Webhook based on command

Use the CommandBasedWebhookDefinition to delegate the execution of the webhook to a Magnolia command.


class: info.magnolia.workflow.webhook.core.definition.CommandBasedWebhookDefinition
description: Do something after the publication of a page
catalog: default
commandName: dummyCommand
enabled: true #Default: true
asynchronous: true  #Default: true
trigger:
  nodeType: mgnl:page
  actions:
    - PUBLISH

Webhook based on REST client

Use the RestClientBasedWebhookDefinition to delegate the execution of the webhook to a Magnolia Rest Client.

class: info.magnolia.workflow.webhook.integration.definition.RestClientBasedWebhookDefinition
description: Do something after the publication of a page
restClientName: webhookSamplesClient
restCallName: postWithBodyParam
trigger:
  nodeType: mgnl:page
  actions:
    - PUBLISH

Webhook triggers

A webhook can either be triggered on a node type:

...
trigger:
  nodeType: mgnl:page
  actions:
    - PUBLISH

Or on an entire workspace:

...
trigger:
  workspace: website
  actions:
    - PUBLISH

Integration

Extension points

By default, the module extends the following commands by chaining an additional webhook command:

  • Default publish
  • Default unpublish
  • Versioned publish
  • Versioned unpublish

In addition, it extends the reviewForPublication and the reviewForUnpublication workflows by opening different slots.

The following extensions points are available:

  • SUBMIT_PUBLISH: When an editor places a publication request (worklow based publication only)
  • REJECT_PUBLISH: When a publisher rejects a publication request (worklow based publication only)
  • ABORT_PUBLISH: When a publisher aborts a publication request (worklow based publication only)
  • PUBLISH: When a publication request is successfully executed
  • SUBMIT_UNPUBLISH: When an editor places a depublication request (worklow based publication only)
  • REJECT_UNPUBLISH: When a publisher rejects a depublication request (worklow based publication only)
  • ABORT_UNPUBLISH: When a publisher aborts a depublication request (worklow based publication only)
  • UNPUBLISH: When a depublication request is successfully executed

Webhook context

Every webhook will be provided with a context containing the following values:

  • action: The webhook action
  • definition: The webhook definition
  • user: The user
  • workspace: The JCR workspace
  • path: The JCR node path
  • jcrId: The JCR node id
  • data: All the attributes passed to the command or the work item
  • jcrNode: The JCR node
  • workItem: The current workflow work item (worklow based publication only)

Develop your own command

If you do not need any custom command input parameter, you can use directly CommandBasedWebhookDefinition.
Otherwise, start with implementing your own definition:

@Data
public class DummyCommandDefinition extends CommandBasedWebhookDefinition {
    /** Input parameter. */
    private String input;
}

Then define your webhook by using your custom definition.

class: info.magnolia.workflow.webhook.definition.DummyCommandDefinition
description: Do something after the publication of a page
catalog: default
commandName: dummyCommand
input: Hello
trigger:
  nodeType: mgnl:page
  actions:
    - PUBLISH

Finally, implement your custom logic within your custom command. (remember to register your custom command in the system)

public class DummyCommand extends WebhookCommand<DummyCommandDefinition> {
    /** Message manager. */
    private final MessagesManager messagesManager;

    @Inject
    public DummyCommand(MessagesManager messagesManager) {
        this.messagesManager = messagesManager;
    }

    @Override
    public boolean execute(Context context) throws Exception {
        this.messagesManager.sendRoleMessage("superuser",
                new Message(MessageType.INFO, "Dummy command", getDefinition().getInput()));

        return true;
    }
}

Use a REST client

In the webhook definition, you need to provide the restClientName and the related restCallName to execute.

class: info.magnolia.workflow.webhook.integration.definition.RestClientBasedWebhookDefinition
description: Perform a dummy post with query and path param after publication
restClientName: webhookSamplesClient
restCallName: postWithQueryAndPathParam
trigger:
  workspace: website
  actions:
    - SUBMIT_PUBLISH

In the REST client configuration, under thedefaultValuesproperty, you need to provide the value expression allowing the system to match the related context value.defaultValues

baseUrl: http://localhost:8080/.rest/webhook/demo
restCalls:
  postWithQueryAndPathParam:
    method: POST
    entityClass: javax.ws.rs.core.Response
    path: /postWithQueryAndPathParam/{workspace}
    headers:
      Content-Type: "application/json; charset=UTF-8"
    queryParameters:
      path:  "{path}"
    defaultValues:
      workspace: context.mgnlData.repository
      path:  context.mgnlData.path

You can find more examples here.


Create your own extension point

Let's say you have a custom action to add a contact. Here is how to create your own extension point:

public class AddContactAction<D extends ActionDefinition> extends AbstractAction<D> {
    private final WebhookProcessor webhookProcessor;

    @Inject
    public AddContactAction(WebhookProcessor webhookProcessor) {
        this.webhookProcessor = webhookProcessor;
    }

    @Override
    public void execute() throws ActionExecutionException {
        // Create your webhook context
        Context webhookContext = new WebhookContextBuilder()
                .action("ADD_CONTACT")
                .workspace(...)
                .path(...)
                .jcrId(...)
                .user(...)
                .attributes(...)
                .build();

        this.webhookProcessor.execute(this.getJCRNode(), "ADD_CONTACT", webhookContext);

        return true;
    }

}

Then you will have to use that custom action type in the definition of your webhook.

class: info.magnolia.workflow.webhook.definition.DummyCommandDefinition
description: Do something after the publication of a page
catalog: default
commandName: dummyCommand
input: Hello
trigger:
  nodeType: mgnl:page
  actions:
    - ADD_CONTACT


Warnings

  • This module is at INCUBATOR level.

Changelog

  • 1.0.1 - Fix multithread issue
  • Version 1.0 - Initial release of the module.


2 Comments

  1. What is the proper syntax go get the 'workspace' in the Rest client:

    Or is 'mgnlData' an additional context item that is passed?

    1. mgnlData is the map containing the variables used in a workflow process. So if you webhook is triggered by a workflow, you'll get mgnlData injected into the webhook