com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.

Adding a Subscription

Owned by Former user (Deleted)
Last updated: May 03, 2016
8 min read

If you currently have no subscriptions, you can use the Add Subscription to Resource/Collection link to add a new subscription.

Use the following instructions to add a new subscription in the Management Console.

Steps to add subscriptions

  1. Log in to the Management Console.
  2. In the Configure menu, click Notifications to access the Manage Notifications page.

  3. Click Add Subscription to Resource/Collection to access the Registry Subscription page.

    To be able to see this link, you must first add a subscription (as described in Managing Subscriptions).

Add subscriptions to a resource 

When you click on the Add Subscription to Resource/Collection link mentioned above to add a new subscription, you are forwarded to a dedicated page through which you can subscribe to notifications made on resources and collections of a single or multiple types.

Add subscriptions to a collection

For collections, there is an additional facility of creating Hierarchical Subscriptions if needed. By default, when a user adds a subscription to a collection it only gets added to that collection. Similarly, the user can add a subscription to that collection and its immediate child resources by selecting the option Collection and Children only or to that collection and all of its child resources by selecting the option Collection, Children and Grand Children.

Add Subscription Options 

On the Registry Subscription page, specify the following options:

  • Subscription Path - The path to the Resource/Collection. Click on the ".." button to "Select a Resource/Collection" from the "Resource Tree" browser.
  • Event- The event type of the notification. You may select from the following options:
    • Check LC Item - Represents an event that occurs when an item is checked in a lifecycle checklist
    • Uncheck LC Item - Represents an event that occurs when an item is unchecked in a lifecycle checklist
    • Create Child - Represents the event of creating a resource (or collection) within an existing collection
    • Delete Child - Represents the event of deleting a resource (or collection) within an existing collection
    • Delete - Represents the event of deleting a resource (or collection)
    • Create LC - Represents the event of creating a lifecycle
    • Delete LC - Represents the event of deleting a lifecycle
    • Change LC State - Represents the event of changing a lifecycle state
    • Update - Represents the event of updating a resource or collection

    • LC Approval Needed - Represents an event that fires when lifecycle transition requires user approvals

    • LC Approval Withdrawn - Represents an event that fires when the remove approval form (remove vote) transition event occurs

    • LC Approved  - Represents an event that fires when the approve (vote) transition event occurs

  • Notification- The notification method. You may select:
    • Email- Any valid email address
      • Email - The email address to which notifications should be sent
      • Digest Frequency- How often notifications are sent
        • None (instant)
        • Hourly
        • Daily
        • Weekly
        • Fortnightly
        • Monthly
    • REST - An endpoint accepting HTML or text content
      • Post URL - The URL of the endpoint accepting HTML or text content to which notifications should be sent
    • SOAP - An endpoint accepting notifications as a SOAP message
      • Endpoint - The URL of the endpoint to send a notification as a SOAP message
    • User Profile- A valid user's profile. Notifications will be sent to the email address specified in the user's default profile.
      • Name - The user's name
      • Digest Frequency- How often notifications are sent
        • None (instant)
        • Hourly
        • Daily
        • Weekly
        • Fortnightly (biweekly)
        • Monthly
    • Group Profile- A valid role. Notifications will be sent to all of the users in the specified role.
      • Role - The role's name
      • Digest Frequency- How often notifications are sent
        • None (instant)
        • Hourly
        • Daily
        • Weekly
        • Fortnightly (biweekly)
        • Monthly
    • Management Console - With a valid role Notifications will be sent to work-list of the role.
      • Role - The role's name 
    • JMX -  Notifications will be sent via JMX. Please refer Support for JMX.
  • Hierarchical Subscription Method (for Collections only)
    • Collection only - The subscription will be effected on the selected collection only.
    • Collection and Children only - The subscription will be effected on the selected collection and its immediate child resources only.
    • Collection,Children and Grand Children - The subscription will be effected on the selected collection and its all child resources .

E-mail notifications 

To enable mail configuration, see Configuring Registry to Send Emails.

  1. To enable sending email notifications, configure the mail transport in the axis2.xml file at <GREG_HOME>/repository/conf/axis2. 
  2. You have to provide a valid email address to receive notifications from the subscribed resource. 

  3. When a subscription is added initially, a verification email is sent to the user. When the user clicks the verification URL, the server console opens in a different tab prompting a successfully verified message.

    One Time Email Verification

    When adding subscriptions to different resources defining the same email address as the notification method, for each subscription users receive a verification email with a link to verify the subscription. The subscription gets active only if the user clicks the verification URL. However, if the user starts the server as ./wso2server.sh -Donetime.email.verification=true  the email verification only happens once when the particular email address is used for first time.

    Changing Host Name of URLs in Verification/Notification E-mails

    To change the Host Name of URLs appearing in Verification and Notification e-mails, set the HostName attribute in repository/conf/carbon.xml.

  4. Whenever an event occurs which is in accordance with the subscription type, the user recieves notification emails. 
Rich email notifications

Using email templates, it is possible to enable sending rich email messages as notifications. By default, the administrator or any privileged user can store email templates in the /_system/governance//repository/components/org.wso2.carbon.governance/templates collection. For event specific email templates, the template name must be the event name in lower case. For example, if you want to customize the PublisherResourceUpdated event, the template file should be publisherresourceupdated.html. If you do not want to define event specific email templates, you can add a template called default.html. By default, the message section in the email templates will be replaced with the message generated for the event.

To plug your own template mechanism and modify the message, you can override the default implementation by adding a new custom implementation.

  1. Create a Java project.
  2. Implement the NotificationTemplate interface and override the populateEmailMessage method. There, you can write your own implementation.
  3. Add the compiled .jar file to the WSO2 Governance Registry.  If it’s an OSGi bundle, add it to the <GREG_HOME>/repository/components/dropins folder. If not, add the .jar file to the <GREG_HOME>/repository/compoments/lib folder.

  4. Add the following configuration to the registry.xml file:

    <notificationConfiguration>
  <class>complete class name with package</class>
</notificationConfiguration>

User profile notifications/role profile notifications

  1. User profile notification method can be used to subscribe different users to events of resources. Role profile notification method can be used to subscribe different roles to events of resources so that all the users of that role would get subscribed for notifications.
  2. In both these methods, a user should have a profile and that profile should contain an email address. Notifications are sent as emails to the defined email address in the profile. Refer to Managing User's Profile. 
  3. To use these notification methods, the mail transport configuration should be enabled in axis2.xml at GREG_HOME/repository/conf/axis2/. See here to enable email configuration.

If you have subscribed with the notification method User Profile, you can also browse the user's default profile by clicking on the User Profile link under the Notification tab.

Management console notifications

  1. When using the Management Console notification method, the roles of users are subscribed to events of resources. Notifications are displayed on the worklist tab at the top. The number of notifications received are shown on the tab and when the tab is clicked the list of notifications is displayed.

  2. To enable this notification method, it is necessary to add WorkList configuration to the registry.xml file at the <GREG_HOME>/repository/conf directory. Please refer to this page to enable WorkList configurations.
  3. Once all the options are specified, click the Subscribe button.
 Notifications for a tenant user

Follow the steps below to configure notifications for a tenant user:

  1. Add the necessary worklist configuration in to the tenant registry. This configuration file is located in the tenant registry. 

    1. Log in as a tenant admin user and create a WorkList.xml file under the /_system/config/repository/components/org.wso2.carbon.registry directory with the following content:

      <workList serverURL="https://IP_ADDRESS:PORT/services/t/TENANT_DOMAIN/" remote="true">
       <username>TENANT_USER@TENANT_DOMAIN</username>
       <password>TENANT_PASSWORD</password>
   </workList>

      For example,

      <workList serverURL="https://10.100.0.11:9443/services/t/chandana.com/" remote="true">
       <username>admin@chandana.com</username>
       <password>admin123</password>
   </workList>
  2. Deploy any WorkList related notification tasks in tenant mode. 
    1. Copy the WorkList.zip file located in the <GREG_HOME>/repository/deployment/server/humantasks directory into the <GREG_HOME>/repository/tenants/TENANT_ID/humantasks directory.  
Notifications in a clustered environment

In order to configure console notifications in a clustered environment, follow the instructions below:

  1. The BPS datasource must be configured for each node. In the <GREG_HOME>/repository/conf/datasources/bps-datasources.xml file, a <defaultAutoCommit> entry set to true must be included manually as shown below:

    <datasource>
<name>BPS_DS</name>
<description></description>
<jndiConfig>
<name>bpsds</name>
</jndiConfig>
<definition type="RDBMS">
<configuration>
<url>jdbc:mysql://localhost:3306/bpsdb</url>
<username>regadmin</username>
<password>regadmin</password>
<driverClassName>com.mysql.jdbc.Driver</driverClassName>
<maxActive>50</maxActive>
<maxWait>60000</maxWait>
<defaultAutoCommit>true</defaultAutoCommit>
<testOnBorrow>true</testOnBorrow>
<validationQuery>SELECT 1</validationQuery>
<validationInterval>30000</validationInterval>
</configuration>
</definition>
</datasource>

  2. The following configuration should be added to the <GREG_HOME>/repository/conf/registry-event-broker.xml file and the existing <deliveryManager> section related to InMemoryDeliveryManagerFactory should be commented out.

    <deliveryManager name="deliveryManager"
                  class="org.wso2.carbon.registry.event.core.sharedmemory.SharedMemoryDeliveryManagerFactory">
             <minSpareThreads>25</minSpareThreads>
             <maxThreads>150</maxThreads>
             <maxQueuedRequests>100</maxQueuedRequests>
             <keepAliveTime>1000</keepAliveTime>
             <topicStoragePath>event/topics</topicStoragePath>
             <matchingManager name="matchingManager"
                      class="org.wso2.carbon.registry.event.core.sharedmemory.SharedMemoryMatchingManagerFactory"/>
         </deliveryManager>

Configuring subscriptions to a mounted setup

Follows the steps below to configure a registry based subscription with the mounted setup:

  1. In the <GREG_HOME>/repository/conf/carbon.xml file, define the host name. For example,

    <HostName>governance.wso2.com</HostName> 

  2. Update the host name in the <GREG_HOME>/repository/conf/registry.xml file as well. For example,

    <remoteInstance url="https://governance.wso2.com:9443/registry">
    	<id>instanceid</id>
    	<dbConfig>mounted_registry</dbConfig>
    	<readOnly>false</readOnly>
    	<enableCache>true</enableCache>
    	<registryRoot>/</registryRoot>
    	<cacheId>root@jdbc:mysql://localhost:3306/greg_db</cacheId>
</remoteInstance>

     

    Note: In the above example, the host name is governance.wso2.com and the WSO2 Governance Registry server is running on the default port (without any port offset). If you have configured a port offset, update the 9443 port above accordingly.

List added subscriptions

When a new subscription is added it is displayed on the Notifications list.

Tip

You can also add new subscriptions to a Resource/Collection by browsing that Resource/Collection using the Resource browser and clicking the Add Subscription link in the Subscriptions box that appears in the right-hand side pane of the resource browser. See: Browsing Resources.

Clicking on the Path name takes you to the Browse page containing the details of a Resource/Collection. See: Resources.

If you have login access to the Publisher and Store, then you can view notifications from each of those applications. However, some notifications may have been customized to fit the context of the relevant applications. For more information, see Adding Subscription Notifications in Publisher and Store.

com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.