API Administration: Custom Workflow

This document provides information about changes to the default user interface behavior when custom API Version workflow is implemented.

Valid in Version: 2019.1.0 and later

Table of Contents

Overview

The Community Manager developer portal online help documentation describes the default appearance and behavior of the Community Manager developer portal. In the version you're using, there might be some visual differences between what you see in the documentation and what you see in the Community Manager developer portal—for example, in colors and fonts—as a result of customization. These types of differences do not affect the structure of the Community Manager developer portal nor the features and capabilities available to you.

However, there are some factors that might limit the availability of features, such as the menu options to you:

  • Role—The role that's assigned to you. If you read about capabilities that are limited to a specific role, such as Business Admin or Site Admin, and feel that you should have those capabilities, talk to your Site Admin. For more information, see How do roles work?
  • Platform settings—The platform includes some security settings that limit the ability of certain user groups to perform certain actions. For example, there is a setting to determine whether a registered user can add an API. If this setting is disabled, registered users will not see the Add API option.

    If you feel that one or more platform settings should be changed, contact your Site Admin. For more information, see Site Resource Settings.

  • Workflow—Customized workflow might be in place, modifying default behavior. For example, there might be role-based custom workflow that limits your ability to add, modify, or delete API versions. See Role-based API workflow customizations below.

This document focuses on custom workflow and the differences between what you might see in the instance of the Community Manager developer portal that you're using, and the normal user interface behavior as described in this documentation.

Alternatively, you might want to implement custom behavior of this type for your API, to streamline the API development and publication process. Implementing custom workflow is a Site Admin task, but you can coordinate with the Site Admin to get customized workflow in place if it's appropriate for your instance of the Community Manager developer portal.

Role-based API workflow customizations

Valid in Version: 2019.1.0 and later

By default, a user who is an API Admin or Business Admin has full capability to perform all activities relating to a specific API, including adding, modifying, or deleting any aspect of the API (the API design and the API implementations, policy attachments, and so forth).

You can implement a custom API Version workflow that provides much more flexibility to grant, or limit, capabilities at a much more granular level. For example, you could implement custom workflow to:

  1. Introduce a Draft state so that when a new API or API version is created, it's in a Draft state, where it isn't visible, available in the search index, or available for contracts, until it is submitted for approval and approved.
  2. Introduce a two-step process as above, Draft to Activated, or even a three-step approval process, Draft to Approved to Activated.

The API version workflow documentation for the API Platform includes a template custom workflow for #1 above. See API Version Workflow: Customization Example.

With this custom workflow in place, an API version cannot be changed once it's in Activated state. However, the workflow also allows you to define specific functions relating to the API, such as adding or modifying a policy or deployment zone, and to assign specific roles that can perform these functions even after the API is activated. For example, when an API version is activated and potentially has hundreds of APIs connected to it, you would not want to change the operations or payloads but you might want to add a deployment zone, an additional endpoint, or a policy. The custom workflow uses reserved actions, such as @ModifyDeployments, to allow these actions. See API Version Workflow: Reserved Actions.

The example provided is just a template for customization as needed.

Roles that you can use in custom workflow, relating to working with APIs:

  • API Admin
  • Business Admin
  • API Approver

For more information about the roles available in the platform, see What are the default roles for the API platform? (Business Admin help). The Business Admin can also define custom roles.

To implement a custom API version workflow

Note: These Community Manager developer portal tasks much be completed by a Site Admin. If you don't have the ability to complete these actions, ask a Site Admin for assistance.

  1. Start with a workflow that's closest to what you want. For example:
  2. Make a copy of the workflow, with an intuitive name, and customize the new version offline.

    For information about the API version workflow functions, conditions, and variable resolvers, see API Version Workflow.

  3. Upload the new custom workflow to the Community Manager developer portal. For instructions, see To upload a custom workflow.
  4. Assign the new workflow as the default API Version workflow. For instructions, see General API Settings.

    All new API versions that you create will use the new workflow (existing API versions are unchanged).