Webhooks module

Deprecated Please use the official Webhooks module instead.

Edition

Incubator (services)

Issues

WEBHOOK

Git

Git

Latest

1.0.1

Compatible with Magnolia 6.2.2.

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

This module is at the INCUBATOR level.

Installing with Maven

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

<dependency>
  <groupId>info.magnolia.workflow</groupId>
  <artifactId>magnolia-webhooks-integration</artifactId>
  <version>1.0.1</version>
</dependency>

Usage

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

Configuration

Webhook based on command

1 Use the CommandBasedWebhookDefinition to delegate the execution of the webhook to a Magnolia command. 
class: info.magnolia.workflow.webhook.core.definition.CommandBasedWebhookDefinition (1)
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

1 Use the RestClientBasedWebhookDefinition to delegate the execution of the webhook to a Magnolia Rest Client. 
class: info.magnolia.workflow.webhook.integration.definition.RestClientBasedWebhookDefinition (1)
description: Do something after the publication of a page
restClientName: webhookSamplesClient
restCallName: postWithBodyParam
trigger:
  nodeType: mgnl:page
  actions:
    - PUBLISH

Webhook triggers

Trigger a webhook by:

nodeType
...
trigger:
  nodeType: mgnl:page (1)
  actions:
    - PUBLISH
1 Triggers by nodeType.
workspace
...
trigger:
  workspace: website (1)
  actions:
    - PUBLISH
1 Triggers by an entire workspace.

Integration

This page provides assistance in integrating the Webhooks module.

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.

workflow

Available extension points

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 CommandBasedWebhookDefinition directly. Otherwise, start with implementing your own definition:

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

Define your webhook by 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

Implement custom logic with your custom command

1 Your custom command. 
public class DummyCommand extends WebhookCommand<DummyCommandDefinition> { (1)
    /** 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 (1) and the related restCallName (2) to execute.

class: info.magnolia.workflow.webhook.integration.definition.RestClientBasedWebhookDefinition
description: Perform a dummy post with query and path param after publication
restClientName: webhookSamplesClient (1)
restCallName: postWithQueryAndPathParam (2)
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

Find more examples here.

Create your own extension point

Let’s say you have a custom action to add a contact. You’ll need to create it and add it to your playbook.

  1. Create your custom 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;
    }

}

  2. Add the extension point to your playbook.

    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

Changelog

Version Notes

1.0.1

Fix multithread issue.

1.0

Initial release.
Feedback