Hooks API module

Developer productivity Incubator

Issues

HOOKSAPI

Git

Latest

1.0.0

Compatible with Magnolia 6.2.27.

The Hooks API module 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-hooks-api-integration</artifactId>
  <version>1.0.0</version>
</dependency>

Usage

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

Hook based on command

class: info.magnolia.workflow.hooks.core.definition.CommandBasedHookDefinition (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

1	Use the `CommandBasedHookDefinition` to delegate the execution of the hook to a Magnolia command.

Hook based on REST client

class: info.magnolia.workflow.hooks.integration.definition.RestClientBasedHookDefinition (1)
description: Do something after the publication of a page
restClientName: hookSamplesClient
restCallName: postWithBodyParam
trigger:
  nodeType: mgnl:page
  actions:
    - PUBLISH

1	Use the `RestClientBasedHookDefinition` to delegate the execution of the hook to a Magnolia Rest Client.

Hook triggers

Trigger a hook 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 Hooks API module.

Extension points

By default, the module extends the following commands by chaining an additional hook 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.

Hook context

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

action: The hook action.
definition: The hook 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 CommandBasedHookDefinition directly. Otherwise, start with implementing your own definition:

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

Define your hook by custom definition

class: info.magnolia.workflow.hooks.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

public class DummyCommand extends HookCommand<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;
    }
}

1	Your custom command.

Use a REST client

class: info.magnolia.workflow.hooks.integration.definition.RestClientBasedHookDefinition
description: Perform a dummy post with query and path param after publication
restClientName: hookSamplesClient (1)
restCallName: postWithQueryAndPathParam (2)
trigger:
  workspace: website
  actions:
    - SUBMIT_PUBLISH

1	Provide the `restClientName` to execute.
2	Provide the `restCallName` to execute.

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/hook/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.

Create your custom extension point.

public class AddContactAction<D extends ActionDefinition> extends AbstractAction<D> {
    private final HookProcessor hookProcessor;

    @Inject
    public AddContactAction(HookProcessor hookProcessor) {
        this.hookProcessor = hookProcessor;
    }

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

        this.hookProcessor.execute(this.getJCRNode(), "ADD_CONTACT", hookContext);

        return true;
    }

}

Add the extension point to your playbook.

class: info.magnolia.workflow.hooks.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

Version	Notes
`1.0.0`	Initial release.

1.0.0

Initial release.