Custom Workflows in the Community Manager developer portal

This document provides information about using custom workflows in the Community Manager developer portal.

Table of Contents

Overview

Workflow defines the sequence of steps that are followed in a business process, through initial actions that trigger the workflow, to additional actions that change the state of the resource, from beginning to end. Major components include conditions (for example, a ticket must be resolved before it can be closed, or, an action can only be completed by a Site Admin) and state (for example, a ticket can have states of Open, Resolved, and Closed).

Defining the workflow for a resource gives you control over the process and allows you to monitor and customize as needed to streamline the business process.

The Akana API Platform allows you to customize the workflow for several key resources, such as API contracts. It also includes examples of custom workflows for some resources.

This document provides information about the resources that follow default workflows, the resources for which you can define custom workflows, and the process you'll need to follow to design, create, test, and implement a custom workflow.

It includes the following main sections:

  • Using Custom Workflows: Overview—the workflows you can customize, how to get started, and how to implement a custom workflow on the platform.
  • Workflow General Reference: Functions, Conditions, and Variables—the technical details about components that are common to all workflows for the Community Manager developer portal.
  • Individual chapters with specific information about the functions, conditions, and variables relating to workflow for a specific resource, such as app version, contract, or discussion.

Note: The Akana API Platform uses OSWorkflow v2.8.0 from OpenSymphony. OSWorkflow is an open-source workflow engine written in Java.

Examples of custom workflow usage

This section includes just a few examples of how you could use workflow definitions to customize process flow in the Akana API Platform:

  • You could build a workflow that customizes the platform's Export functionality so that at the click of a button an authorized user could export platform data to a designated folder, to be picked up by a corresponding Import function in a custom workflow in another build. You could then use this custom workflow feature to automate the transfer of data from a development environment to a QA environment.
  • Tickets: You could customize the ticket workflow so that each new ticket for your API in the platform automatically triggers an email to create a ticket in your own internal trouble ticketing system.
  • Contracts: You might implement a custom workflow so that an app cannot have an active contract in the Live environment with one API until it's ready to run in the Live environment with all the APIs it's using. Note that you would also need to update the site documentation.
  • APIs: You could use a reserved action to determine that when an API is deleted, all existing contracts relating to that API are deleted and a notification is sent out to all users affected by the change.
  • Apps: If an app is deleted, you could use a reserved action to determine what happens to API contracts associated with the app.

Using Custom Workflows: Overview

The ability to customize the platform default workflow for resources gives you great flexibility.

By developing a custom workflow, you can control how resources behave in the system as a result of certain actions.

The basic building blocks of workflow are:

  • Actions. An action element changes a resource from one state to another by accomplishing some activity on the resource. An action element indicates what is happening to the resource. There are two main scenarios:
    • In some cases, the action can extend the default behavior in the platform. For example, you could set up the group membership workflow so that if a group is deleted all members receive a notification.
    • In other cases, a workflow action can replace the default behavior. For example, in the app version workflow, you could redefine the steps that are taken when the @delete action occurs, so that an administrator must approve the deletion. As another example, you could set up the workflow so that when the app certificate is modified (@KeyInfoSaved action), a notification is sent.
  • Steps: A step element indicates the state of a resource and defines the actions that are valid when a resource is in that state.
  • Conditions: A workflow action can be restricted by the results of one or more condition elements. The condition element determines whether or not the action is valid. For example, a condition might test that the user attempting to perform the action has a valid role and is therefore authorized to perform the action.
  • Functions: A function element acts on the resource and changes it in some way; for example, the deleteReview function deletes a review, ending the workflow for that review. The function might have arguments. In a workflow step, functions can be either of the below:
    • Pre-functions: The pre-functions element indicates that the function is executed before entering the step or action.
    • Post-functions: the function is executed after leaving the step or action.

Resources with Customizable Workflow

The platform supports implementation of custom workflows for the following types of resources:

Steps for Implementing a Custom Workflow

At a high level, the steps to implement a custom workflow are listed below. The following sections provide more information on each of these steps.

In some cases, certain actions must be performed by users with a specific role. Roles are shown for each step.

Note: It is best to test a new custom workflow in a sandbox environment before implementing in your Live environment. For more information, see Testing a New Custom Workflow.

  1. Optional: download existing workflow. You can download an existing workflow to use as a starting point for the customization (Admin > Workflows > View > Download). For more information, refer to the platform help.
  2. Create the custom workflow outside the platform. For more information and technical details, refer to The Workflow Definition XML File. (Admin or delegate)
  3. Upload the custom workflow to a sandbox environment. See Uploading a New Custom Workflow below. (Site Admin only)
  4. Assign the new custom workflow as the default for new resources of that type. See Implementing a New Custom Workflow. (Site Admin)
  5. Test the new custom workflow, and resolve any issues as needed until you are sure the new workflow is fully functional and bug-free. For more information, see Testing a New Custom Workflow. (Site Admin, Business Admin, or resource admin)
  6. Update user documentation. The platform's user documentation reflects the default workflow. If you change the workflow, it might render the platform documentation incomplete, incorrect, or both. You must make sure you update the documentation to reflect any changes from the default workflow. (Site Admin or delegate)
  7. When you're sure that everything is functioning correctly, it's time to update the Live environment:
    • Upload the new workflow (Step 3 above).
    • Assign it as the default for the resource type (Step 4 above).
    • If needed, upload the updated documentation (Step 6 above).

Uploading a New Custom Workflow

Roles in custom workflow management are as follows:

  • Uploading a new custom workflow: Site Admin or Business Admin
  • Changing the workflow definition for a specific type of resource: Site Admin

To upload a custom workflow, log in as the Site Admin or Business Admin and go to More > Admin > Workflows. Here you can easily manage custom workflows, including adding, editing, viewing, or deleting.

When you've uploaded the workflow, it isn't effective until you assign it as the default for the resource type. See Implementing a New Custom Workflow below.

For additional instruction, if needed, refer to the platform online help. See Community Manager Developer Portal Help Content Overview.

Testing a New Custom Workflow

Changing the custom workflow for resources on the platform can significantly impact the user experience for all users on the platform. It's very important to test a new workflow thoroughly, making sure it works as planned, before implementing it as the default.

One strategy is to write out various use cases that will be affected by the workflow change, apply the new workflow to one or two custom resources, and then test those resources, using the use cases as a guide. Make sure all state changes and results are as expected.

If you encounter any issues, restore the default workflow and then delete the test workflow from the platform. When corrections are made, upload the corrected version and test again.

Make sure you are completely satisfied that the new workflow runs as expected before making it the default for new resources of the applicable type.

Below is an example of a testing strategy for a new API version workflow.

Example: to validate and test a new API version workflow

  1. Load the workflow into the Community Manager developer portal but do not set it as the default for APIs.
  2. Create a test API.
  3. Specify the new workflow as the default for the test API.
  4. Use the API and verify that:
    • The sequence of state transitions is correct.
    • The actions displayed are correct for the active state.
    • The workflow history is correct (including status).
  5. Depending on the test results:
    • If the workflow needs more work, remove it so that it isn't available for selection in the platform.
    • When you're completely satisfied that the workflow is functioning as intended, set it as the default, if applicable. For more information, refer to Implementing a New Custom Workflow below.

Implementing a New Custom Workflow

Once a new custom workflow has been fully tested and you're sure it's working as expected, you can upload it to the platform and set it as the default for the resource type. Once you do this, all new resources of that type will use the new workflow.

Only the Site Admin can change the workflow definition for a specific type of resource.

Note that existing resources are not affected. For example, if you change the API version workflow, and have existing APIs, they will still use the workflow that was in use when the API was created.

  • To upload a custom workflow: Log in as a Site Admin or Business Admin, go to Administration > Workflows, and then click Add Workflow. Specify Name and Description. In the Object Type drop-down list, make sure you choose the correct type of resource. Navigate to the location of the file and upload it.
  • To change the workflow for a type of resource: Log in as a Site Admin, go to Administration > Settings, and then choose the resource type. Update the workflow definition field, choosing the new workflow from the drop-down list, and then save your changes.

For additional instruction, if needed, refer to the platform online help.

Updating User Documentation

It is the Site Admin's responsibility to update the developer documentation to reflect any custom workflow changes.

When developers are using the platform, they are not aware that the sequence of actions in specific processes is governed by workflow; they only know that they must follow those processes to get the desired results.

The online help for the platform guides developers through step-by-step instructions to complete various activities associated with managing apps, API contracts, tickets, and so on.

If you change the process, you have the responsibility to also update the applicable online help content to give developers the additional information they need to comfortably use the platform. App developers are your target audience, and their user experience is very important.

The Workflow Definition XML file

The workflow process is defined in an XML file that contains:

  • Initial actions (actions that start the workflow)
  • Workflow steps and actions

The basic structure of required elements in a workflow XML document is shown below.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE workflow PUBLIC 
  "-//OpenSymphony Group//DTD OSWorkflow 2.9//EN"
  "http://www.opensymphony.com/osworkflow/workflow_2_9.dtd">
<workflow>
  <initial-actions>
    One or more <action> elements
  </initial-actions>
    <steps>
     One or more <step> elements
  </steps>
</workflow>

Workflow Initial Actions

The first part of the workflow includes definitions of one or more initial actions that trigger it.

Initial actions are predefined reserved words, such as @Create. Initial actions bring the resource into the workflow at the beginning. In Akana API Platform workflows, initial actions always start with the @ sign.

The specific initial actions for each type of workflow are given in the workflow reference section of this document.

The example below shows the initial action @Create used to start the App Version workflow.

<initial-actions>
  <action id="1" name="@Create">
    <results>
      <unconditional-result old-status="Received" status="Setup" step="100" owner="${caller}" />
    </results>
  </action>
</initial-actions>

Workflow Reserved Actions

There are specific actions for each workflow type that are used internally as part of the workflow. These are called reserved actions. Reserved actions are predefined for certain changes that might commonly be made to objects as a result of something else that happens in the system, as distinct from changes that occur as a result of a user's action such as clicking a button. A reserved action is triggered automatically under certain conditions, as defined in the workflow. For example, the app version workflow could be set up so that if the app certificate is updated, an email is sent to your internal system administrator.

The specific initial actions for each type of workflow are given in the workflow reference section of this document.

Within the context of workflow, there are two main purposes for reserved actions:

  1. Limit actions: To specify the conditions under which certain steps can be performed.

    The reserved action is used to verify whether an action is allowed or not, in the current context, before executing. For example, you could specify that an app can have connections in the Live environment only, or in the Sandbox environment only. Reserved actions allow you to define this configurable behavior.

    A common use of this type of reserved actions is to check for authorization. For example, a reserved action could check the user's role to make sure the user is a Site Admin or Business Admin before allowing a specific action.

  2. Extend behavior: To initiate an action internally when something else happens, or to extend what happens as part of another action. This type of reserved action is called an initial-action as covered in the previous section.

    The naming of this type of reserved action generally indicates that an action has occurred. For example, in the app workflow, @KeyInfoRemoved indicates that the application security certificate was removed; in the user workflow, @ChallengeQuestionsAnswered indicates that the user has answered the challenge questions. Because these are defined as reserved actions, the workflow can then be built to trigger additional actions.

    For example, if a group is deleted, the reserved action group.membership.action.group.deleted is invoked. This executes one or more steps to determine what happens with the group members (for example, each is sent a notification). In this scenario, the user doesn't see any buttons or make any choices; when the reserved action is triggered, it executes whatever steps are coded into the workflow.

As an extension of #2, in some cases custom workflow can be used to replace default behavior. However, in most cases custom workflows extend the default behavior rather than replacing it.

There are specific reserved actions for each type of workflow.

This section includes:

  • Reserved Actions: Naming Conventions
  • Reserved Actions: Examples

Reserved Actions: Naming Conventions

The platform uses two main formats for naming of reserved actions, with a couple of exceptions. Naming conventions are as follows:

  • Action name begins with reserved-; for example, under certain conditions the reserved-connect reserved action is sent to the user interface (UI) so that the UI will display a Connect button. If we use this prefix on a reserved action, the UI uses it to customize the behavior, but doesn't show it as an action the user can invoke. It's internally invoked, or the purpose of it is to check whether an action is valid or not. Nobody invokes the reserved action. It indicates, in the current state, whether the action can be performed or not. It is used to customize the behavior, but not to customize the list of actions that the user can invoke. Example:
    • reserved-connect-from-app.Sandbox
  • Action name begins with an @ sign. Internal actions that the user doesn't need to know about, or initialization actions that the product uses for adding an object; for example, when adding a contract or an app, the initial state that the resource is in. Actions that start with an @ sign are never part of the return list of actions when the workflow API is used to get a list of workflow actions that are valid for a resource. They are only used internally. Examples:
    • @app_switch_to_production
    • @Invite
    • @Revise (to revise a contract that is in Activated or Suspended state)
  • Action name is neither of the above, but is defined as a workflow action in the name. There are a few legacy workflow action names in the group membership workflow that do not follow the above naming conventions. They are:
    • group.membership.action.accept
    • group.membership.action.decline
    • group.membership.action.resend
    • group.membership.action.remove
    • group.membership.action.make.admin
    • group.membership.action.make.leader
    • group.membership.action.make.member
    • group.membership.action.group.deleted

For more information, refer to Group Membership Workflow: Reserved Actions.

Reserved Actions: Examples

Below are some examples of reserved actions from actual workflow documents.

<action id="59" name="@modify">
<action id="58" name="@read">
<action id="105" name="@RegeneratedSecret">
<action id="106" name="reserved-allow-cert-upload">
<action id="301" name="reserved-action.unpublish">

Workflow Steps and Actions

The workflow definition file contains one or more steps. Each step has a unique ID and a name.

Each step can contain one or more Action elements, but they are not required.

Actions can be automatic or manual.

The basic structure of an Action element is shown below.

<action id="###" name="Display name of action">
  <results>
    Optional conditional <result> elements
    </unconditional-result old-status="value" status="value" step="###" /> 
  </results>
</action>

Note: A result step value of -1 causes no workflow state transition.

Developing a Custom Workflow: Steps to Consider

In developing your custom workflow, here are some planning steps to consider:

  • Choose the tool you will use to create and modify the XML file.
  • Decide what strategy you will follow to adopt unique numbers for each Step ID and Action ID.
  • Determine how the workflow will terminate.
  • Decide how you will validate and test the workflow.