Review Workflow

This section provides information about functions, conditions, and variable resolvers for the review workflow, as well as initial actions and reserved actions.

Table of Contents

Review Workflow: Initial Actions

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

@StartReview

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

Review Workflow: Reserved Actions

The following reserved actions are defined for Akana API Platform workflows relating to reviews:

@read

Applies to unpublished reviews only.

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

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

@modify

Used to determine whether a review can be modified.

@cancel

Used to cancel the review and end the workflow.

Review Workflow: Functions

The following functions are available for Akana API Platform workflows relating to reviews:

markPublished

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

Parameters

None.

Examples/Notes/Additional Information

In the example below, the workflow is set up so that a review added by an administrator is approved automatically. The workflow checks that the user has a role of Site Admin or Business Admin. If so, the status of the review is automatically changed to Published. The markPublished function is invoked as a post-function.

<step id="100" name="Route Add New Review">
  <actions>
    <action id="101" name="Auto Approve Add" auto="TRUE">
      <restrict-to>
        <conditions type="OR">
          <condition type="authorizeByAtmosphereRole">
            <arg name="role">SiteAdmin,BusinessAdmin</arg>
          </condition>
          <condition type="isAutoPublishEnabled"/>
        </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">apiversion</arg>
          <arg name="role">SubjectAdmin</arg>
          <arg name="notificationType">com.soa.notification.type.api.review.created</arg>
        </function>
        <function type="sendNotification">
          <arg name="subjectType">app-version</arg>
          <arg name="role">SubjectAdmin</arg>
          <arg name="notificationType">com.soa.notification.type.app.review.created</arg>
        </function>
      </post-functions>
    </action>

markUnPublished

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

Parameters

None.

Examples/Notes/Additional Information

In the example below, an existing, published review is being cancelled because another review on the same subject by the same user was received. The workflow checks that the action is performed by an authorized user, and then changes the status of the original review from Approved to Pending. The markUnPublished function is invoked as a post-function.

<step id="300" name="Published">
  <pre-functions>
    <function type="cancelOldReviewForTheSubjectBySameUser" />
  </pre-functions>
  <actions>
    <action id="301" name="review.action.unpublish">
      <restrict-to>
        <conditions type="AND">
          <condition type="authorizeByAtmosphereRole">
            <arg name="role">SiteAdmin,BusinessAdmin,Author,SubjectAssociatedApiAdmin</arg>
          </condition>
        </conditions>
      </restrict-to>
      <results>
        <unconditional-result old-status="Approved" status="Pending" step="200" owner="${caller}" />
      </results>
      <post-functions>
        <function type="markUnPublished"/>
      </post-functions>
    </action>

deleteReview

Deletes a review.

Parameters

None.

Examples/Notes/Additional Information

In the example below, the @cancel reserved action is invoked. The workflow first checks that the user is authorized to perform the action. If so, the review is moved from a Published status to a Finished status. As a post-function, the review is deleted.

<action id="303" name="@cancel">
  <restrict-to>
    <conditions type="AND">
      <condition type="authorizeByAtmosphereRole">
        <arg name="role">SiteAdmin,BusinessAdmin,SubjectAssociatedApiAdmin</arg>
      </condition>
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="Published" status="Finished" step="500" owner="${caller}" />
  </results>
  <post-functions>
    <function type="deleteReview"/>
  </post-functions>
</action>

cancelOldReviewForTheSubjectBySameUser

Cancels an existing review. This function is generally used in a scenario where a reviewer submits a second review on the same subject. The subsequent review replaces the earlier one, which is cancelled.

When someone publishes a second review for the same subject, the platform does not modify the existing review that was already published. Instead, a new review is created. At that point, there might be two reviews on the same subject by the same author, one in the Published state and one in the Draft state. When the draft review is published, the previous review is automatically deleted.

The states for both reviews are as follows:

  • First review: published / Second review: draft
  • Second review: published / first review: deleted.

Parameters

None.

Examples/Notes/Additional Information

In the example below, a review is published. As a pre-function, the workflow checks for an old review for the same subject by the same user, and cancels it if found. It first checks that the user is authorized to perform the action, changes the old review status from Approved to Pending, and runs the markUnPublished function.

<step id="300" name="Published">
  <pre-functions>
    <function type="cancelOldReviewForTheSubjectBySameUser" />
  </pre-functions>
  <actions>
    <action id="301" name="review.action.unpublish">
      <restrict-to>
        <conditions type="AND">
          <condition type="authorizeByAtmosphereRole">
            <arg name="role">SiteAdmin,BusinessAdmin,Author,SubjectAssociatedApiAdmin</arg>
          </condition>
        </conditions>
      </restrict-to>
      <results>
        <unconditional-result old-status="Approved" status="Pending" step="200" owner="${caller}" />
      </results>
      <post-functions>
        <function type="markUnPublished"/>
      </post-functions>
    </action>

sendNotification

Triggers the specified notification based on an event relating to a review.

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. Applicable to anywhere a review can be added. Valid values:

  • apiversion
  • app-version
  • group
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:

  • ApiAdmin
  • AppAdmin
notificationType

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

  • com.soa.notification.type.api.review.created (for an API)
  • com.soa.notification.type.app.review.created (for an app)

Examples/Notes/Additional Information

In the example below, the workflow is set up so that a review added by an administrator is approved automatically. When the review is published, a notification is sent to applicable admins. A different notification is sent for an API review versus an app review.

<step id="100" name="Route Add New Review">
  <actions>
    <action id="101" name="Auto Approve Add" auto="TRUE">
      <restrict-to>
        <conditions type="OR">
          <condition type="authorizeByAtmosphereRole">
            <arg name="role">SiteAdmin,BusinessAdmin</arg>
          </condition>
          <condition type="isAutoPublishEnabled"/>
        </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">apiversion</arg>
          <arg name="role">SubjectAdmin</arg>
          <arg name="notificationType">com.soa.notification.type.api.review.created</arg>
        </function>
        <function type="sendNotification">
          <arg name="subjectType">app-version</arg>
          <arg name="role">SubjectAdmin</arg>
          <arg name="notificationType">com.soa.notification.type.app.review.created</arg>
        </function>
      </post-functions>
    </action>

Review Workflow: Conditions

The following conditions apply to the reviews workflow:

isAutoPublishEnabled

Checks the platform settings to determine whether a review can be automatically published; returns true if so. If false, new reviews require moderation.

Review Workflow: Variable Resolvers

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