Comments Workflow

This section provides information about functions, conditions, and variables for the Comments workflow, as well as initial actions and reserved actions.

Table of Contents

Comments Workflow: Initial Actions

The initial actions valid for Akana API Platform workflows relating to comments are:

@AddComment

This is how a comment is introduced into the workflow. If you are customizing the initial behavior when a comment is added, this is where the customization needs to go.

@Audit

An initial action that could be used to initiate a comment for audit purposes.

@Alert

An initial action that could be used to initiate a comment as the result of an alert—for example, SLA or quota alerts.

Comments Workflow: Reserved Actions

The following reserved actions are defined for comments workflows:

@read

Applies to unpublished comments only. This action controls who can read an unpublished comment. When the @read action is available, read permission is available for someone to read the comment in an unpublished state. If @read is not available for a specific user for the current state of the comment, the user cannot see it.

Once the comment is published, all users who have visibility of the resource can see it.

Comments Workflow: Functions

The following functions are available for the comments workflow:

MarkPublished

Marks a comment as published. This might be used in a scenario where the Moderator has determined that the comment meets guidelines, or if comments are not moderated.

Parameters

None.

Examples/Notes/Additional Information

In the example below, when a new comment is added, the workflow checks the platform settings to see if a comment added by an admin is auto-approved, and also checks the role of the user. If both conditions are met, the status is changed from none to Published, and the workflow runs the markPublished function.

<step id="100" name="Route Add New Comment">
  <actions>
    <action id="101" name="Auto Approve Admin Add" auto="TRUE">
      <restrict-to>
        <conditions type="AND">
          <condition type="authorizeByCMRole">
            <arg name="role">SiteAdmin,BusinessAdmin</arg>
          </condition>
        </conditions>
      </restrict-to>
      <results>
        <unconditional-result old-status="none"  status="Published" step="300" owner="${caller}" />
      </results>
      <post-functions>
        <function type="markPublished"/>
      </post-functions>
    </action>

markUnPublished

Marks a comment as not published. This might be used in a moderated scenario where the Moderator has determined that the comment does not meet guidelines.

Parameters

None.

Examples/Notes/Additional Information

In the example below, when a new comment is added, the workflow checks the platform settings to see if a comment added by an admin is auto-approved. If manual approval is needed (action id 102), the status is changed from none to Pending, and the workflow runs the markUnPublished function.

<step id="100" name="Route Add New Comment">
  <actions>
    <action id="101" name="Auto Approve Admin Add" auto="TRUE">
      <restrict-to>
        <conditions type="AND">
          <condition type="authorizeByCMRole">
            <arg name="role">SiteAdmin,BusinessAdmin</arg>
          </condition>
        </conditions>
      </restrict-to>
      <results>
        <unconditional-result old-status="none"  status="Published" step="300" owner="${caller}" />
      </results>
      <post-functions>
        <function type="markPublished"/>
      </post-functions>
    </action>
    <action id="102" name="Manual Approval Needed" auto="TRUE">
      <results>
        <unconditional-result old-status="none" status="Pending" step="200" owner="${caller}" />
      </results>
      <post-functions>
        <function type="markUnPublished"/>
      </post-functions>
    </action>
  </actions>
</step>

deleteComment

Deletes a comment.

Parameters

None.

Examples/Notes/Additional Information

In the example below, an action is taken the delete the comment. The workflow first verifies that the user is authorized. If the condition is met, the status is changed from Published to Finished, and the workflow runs the deleteComment function.

<action id="302" name="comment.action.delete">
  <restrict-to>
    <conditions type="AND">
      <condition type="authorizeByCMRole">
        <arg name="role">SiteAdmin,BusinessAdmin,Author,SubjectAssociatedApiAdmin</arg>
      </condition>
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="Published" status="Finished" step="500" owner="${caller}" />
  </results>
  <post-functions>
    <function type="deleteComment"/>
  </post-functions>
</action>

sendNotification

Triggers the specified notification based on an event relating to a comment. For example, this can be used to trigger a notification email to be sent to API admins when a comment is made on a pending API access request. By default, in the comments workflow, a notification email is sent only to the app developer.

Note: The email isn't sent instantly; it is queued to be sent. It goes to the notifications queue, and the job runs every 60 seconds. There might be a short delay before the user receives the email.

Parameters

Name Description/Values
subjectType Indicates the type of resource the notification relates to. In the context of the comments workflow, the subjectType is board-item.
subjectSubtype

Valid only when subjectType is set to board-item. Indicates the type of resource that was commented on. Valid values are the board item types that can have comments attached to them:

  • For API access requests: ContractRequest
  • For group membership requests: GroupMemberReq
  • For general app or API discussions: Discussion
Role

The role to which the notifications will be sent—only users who hold this role for the type of resource as specified in the subjectType parameter. Valid values:

  • SubjectAdmin
  • SiteAdmin
  • ApiAdmins
  • BusinessAdmin
  • Author
notificationType

The type of notification being sent. Can be any valid notification existing in the platform. For example:

  • com.soa.notification.type.api.post.created (for an API)
  • com.soa.notification.type.app.post.created (for an app)
  • com.soa.notification.type.group.post.created (for a group)
  • com.soa.notification.type.board.post.created (for a board)

Examples/Notes/Additional Information

In the example below, the workflow is set up so that if a comment is made on an API access request, a notification is sent to API Admins. Without this workflow modification, the notification only goes to the app owner.

<action id="101" name="Auto Approve Admin Add" auto="TRUE">
  <restrict-to>
    <conditions type="OR">
      <condition type="authorizeByCMRole">
        <arg name="role">SiteAdmin,BusinessAdmin</arg>
      </condition>
      <condition type="isCommentAutoPublishEnabled"/>
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="none"  status="Published" step="300" owner="${caller}" />
  </results>
  <post-functions>
    <function type="markPublished"/>
    <function type="sendNotification">
      <arg name="subjectType">board-item</arg>
      <arg name="subjectSubtype">ContractRequest</arg>
      <arg name="role">ApiAdmins</arg>
      <arg name="notificationType">com.soa.notification.type.my.post.comment</arg>
    </function>
  </post-functions>
</action>

Comments Workflow: Conditions

The following conditions apply to the comments workflow:

authorizeByCMRole

Tests to see if the workflow user has one or more specific roles in the platform, and is therefore authorized to perform the workflow action; returns Boolean true or false.

Arguments

Name Description/Values
Role

One or more roles that are authorized to perform the workflow action.

Valid values:

  • Author
  • BusinessAdmin
  • SiteAdmin
  • SubjectAssociatedApiAdmin

Examples/Notes/Additional Information

In the example below, when a new comment is added, the workflow checks the platform settings to see if a comment added by an admin is auto-approved, and then checks the role of the user. If the user is a Site Admin or Business Admin, the workflow proceeds. If not, the action is not allowed.

<step id="100" name="Route Add New Comment">
  <actions>
    <action id="101" name="Auto Approve Admin Add" auto="TRUE">
      <restrict-to>
        <conditions type="AND">
          <condition type="authorizeByCMRole">
            <arg name="role">SiteAdmin,BusinessAdmin</arg>
          </condition>

isCommentAutoPublishEnabled

Checks whether a comment can be automatically published; returns true if so. If false, new comments require moderation.

Arguments

None.

Comments Workflow: Variable Resolvers

There are currently no variable resolvers for Akana API Platform workflows relating to comments.