How to automate custom business operations based on QPP NextGen events?

Introduced in v3.1

You can automate your custom business operations based on QPP NextGen events through webhooks.

Webhooks are automated messages that an application triggers when an event occurs, which third-party services can listen to, to automate all type of custom processes outside the scope of the application.

Webhooks are delivered to the HTTP/HTTPS endpoints that can be hosted externally. This enables external applications/services to react to the events occurred in the application and then provide extensibility based on custom business requirements. For example, extensibility can be automating publishing a document based on an event (such as change in workflow status) or notifying a third-party application about the occurrence of the event.

The following use cases describe how you can extend QPP NextGen functionalities using webhooks:

• Automate publishing on status change
• Send email notification on document (asset) creation

Use Case 1: Automate publishing on status change

When an asset of a specific content type reaches a certain workflow state, you want to publish a PDF of the asset and then store the PDF on the QPP NextGen server.

Let’s use the following parameters for the use case:

• Document/Content Type: Smart Document
• Workflow: Document Publishing
• Status: Publish

The following process describes how to automate publishing on status change using webhooks. The process contains steps for each type of user persona (developer, admin, and end-user) involved to accomplish the task:

Developer

1. A developer creates a service that exposes an endpoint (for example, http://www.somedomain.com/publishonstatuschange) to listen to QPP NextGen events.

2. Defines the process flow to generate PDF outputs and then check-in the outputs into a specific collection by invoking publish API.

3. Registers the endpoint for the event ASSET_WORKFLOW_CHANGED (workflow status change of an asset) through QPP NextGen webhook registration API with following parameters:

    {
        "name": "webhook_name",
        "endpoint": "https://www.somedomain.com/publishonstatuschange", // This is a sample URL. You must specify your own URL.		
        "type": "EVENT",
        "object": "ASSET",
        "changeType": [
            "ASSET_WORKFLOW_CHANGED"
        ],
        "filter": "(Content\\ Type:Smart\\ Document AND Workflow: 'Document\\ Publishing\\ Workflow' AND Status: 'Publish')",
        "version": "1.0",
        "auxData": "metadata"
    }
   

4. QPP NextGen invokes the endpoint when the event ASSET_WORKFLOW_CHANGED occurs and qualifies for the value of the parameter filter as defined in the previous step.

   Note: The endpoint must be accessible to QPP NextGen.

Admin

5. In QPP NextGen, an admin user creates a workflow named Document Publishing and applies it to the content type Smart Document.
6. Adds the following statuses to the workflow Document Publishing:
   • New
   • Edit
   • Review
   • Approved
   • Publish
   • Published
   • Publishing Failed

End user

7. An end-user creates an asset of content type Smart Document and assigns the workflow Document Publishing.
8. When the end-user changes the status to Publish, QPP NextGen triggers the event ASSET_WORKFLOW_CHANGED.

Result: The event ASSET_WORKFLOW_CHANGED triggers the custom business flow (implemented by the developer in step 2), which is to use QPP NextGen APIs to generate the output and check-in the output to the collection on QPP NextGen server.

Use Case 2: Send email notification on asset creation

When an asset of a specific content type is created, you want to send an email notification to all the stakeholders (such as author, editor, reviewer, and so on).

This can be accomplished by allowing third-party services to register their customer handlers to listen to the event for asset creation and then send email notification as per the business use case.

Let’s use the following parameters for the use case:

• Document/Content Type: Smart Document
• Workflow: Document Publishing

The following process describes how to send email notification on asset creation using an add-on service. The process contains steps for each type of user persona (developer and end-user) involved to accomplish the task:

Developer

1. A developer creates a service that exposes an endpoint (for example, http://www.somedomain.com/sendemailonstatuschange) to listen to QPP NextGen events.

2. Defines the process flow to send the email notification.

3. Registers the endpoint for the event ASSET_ADDED (asset creation) through QPP NextGen webhook registration API with following parameters:

    {
        "name": "webhook_name",
        "endpoint": "https://www.somedomain.com/statuschangehandler", // This is a sample URL. You must specify your own URL.				
        "type": "EVENT",
        "object": "ASSET",
        "changeType": [
            "ASSET_ADDED"
        ],
        "version": "1.0",
        "auxData": "metadata"
    }
   

4. QPP NextGen invokes the endpoint when the event ASSET_ADDED occurs (which is triggered when you add an asset to your QPP NextGen server repository).

   Note: The endpoint must be accessible to QPP NextGen.

End user

5. An end-user creates an asset of content type Smart Document.
6. QPP NextGen triggers the event ASSET_ADDED for the asset.

Result: The event ASSET_ADDED triggers the custom business flow (implemented in step 2 by the developer), which is to use QPP NextGen APIs to send email notification.

Sample Code:

Sample code is available to demonstrate the use of webhook service to achieve above use cases. The sample code can be used as a starting point to understand webhook endpoint registration and to implement use cases described above.

Note: Refer to the file Readme.md inside the sample for instructions on configuring and deploying sample code.

Download sample code