Hooks API module

Developer productivity Bundled: DX Core

Issues

Git

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.

Configuration

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.

  1. 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;
        }
    
    }
  2. 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

1.0.0

Initial release.

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Hooks API module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules