Webhook

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

JIRA	WEBHOOK
Git	webhooks

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.1

Magnolia 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.

Page tree