API Version Workflow

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

Note: API version workflow is optional. If no custom workflow is in place, the API version behavior is the default behavior described in the online help for the Community Manager developer portal. See API Administration.

Table of Contents

API Version Workflow: Overview

By default, there is no API version workflow in the platform. In most cases, once an API version is active, it's best not to make changes to it.

However, in some cases, you might want to allow users with certain roles to be able to make specific modifications to an API version. For these scenarios, you can:

  1. Use the custom workflow template provided with this document as a starting point. See API Version Workflow: Custom Workflow Template Examples.
  2. Modify the template using the additional workflow actions, functions, conditions, and variable resolvers given in this document.

API Version Workflow: Initial Actions

The following initial actions are valid for Akana API Platform workflows relating to APIs/API versions:

@Create

Starts the workflow, for a new API version.

For more information, see Workflow Initial Actions.

API Version Workflow: Reserved Actions

If a custom API version workflow is in place, you can add one or more of the reserved actions given below. Note that for a reserved action to be valid, it must be appropriate for the state a workflow is in. For example, by default when an API version is in Active state it can be deleted but cannot be modified; if an API version is in Rejected state it can be submitted for approval.

The following reserved actions are valid for API version workflows:

@Delete

Indicates that the API version can be deleted at this point in the workflow, using the user interface or the platform API.

@Modify

Used to determine whether an API version can be modified or should be read-only. If @Modify is not a valid action, the user interface disables the buttons/links leading to modifying anything about the API version.

The @Modify action is available by default when the API version is in one of the following workflow states:

  • Draft
  • Rejected
  • Pending Approval

Note: @Modify controls permission to modify the entire API version. A user with this permission is authorized to perform all edit activities for the API version, such as adding or changing operations in the API design or modifying other API information such as deployment zones, policy assignments, and endpoints. If @Modify is not present in the workflow, the platform checks for additional workflow actions that give more granular permission to perform a specific action, such as @ModifyPolicies or @ModifyDeployments.

apiversion.action.submit.approval

Used to submit a new or revised API version for approval.

The Business Admin for the organization can submit an API version for approval.

The apiversion.action.submit.approval action is available by default when the API version is in one of the following workflow states:

  • Draft

For an example of a workflow section that includes this action, see updateApiVersionStatus.

apiversion.action.approve

Used to approve a new or revised API version that was submitted for approval.

The apiversion.action.approve action is available by default when the API version is in this workflow state:

  • Pending Approval

The Business Admin for the organization, or the API Approver, can approve or reject an API version.

The example below shows a section of the template workflow showing steps and actions when an API version is pending approval. Valid actions are Approve (apiversion.action.approve) or Reject (apiversion.action.reject). When the action is apiversion.action.approve (third line below), the applicable conditions are applied as shown below.

<step id="300" name="Pending Approval!">
  <actions>
    <action id="301" name="apiversion.action.approve">
      <restrict-to>
        <conditions type="OR">
          <condition type="authorizeByAtmosphereRole">
            <arg name="role">&AtmoRoleBusinessAdmin;</arg>
          </condition>
          <condition type="authorizeByAtmosphereRole">
            <arg name="role">&AtmoRoleAPIApprover;</arg>
          </condition> 
        </conditions>
      </restrict-to>
      <results>
        <unconditional-result old-status="Pending Approval" status="Active" step="400"/>
      </results>
      <post-functions>
        <function type="updateApiVersionStatus">
          <arg name="status">&StateActive;</arg>
        </function>
      </post-functions>
    </action>
    <action id="302" name="apiversion.action.reject">
      <restrict-to>
        <conditions type="OR">
          <condition type="authorizeByAtmosphereRole">
            <arg name="role">&AtmoRoleBusinessAdmin;</arg>
          </condition>
          <condition type="authorizeByAtmosphereRole">
            <arg name="role">&AtmoRoleAPIApprover;</arg>
          </condition> 
        </conditions>
      </restrict-to>
      <results>
        <unconditional-result old-status="Pending Approval" status="Rejected" step="350" owner="${caller}"/>
      </results>
      <post-functions>
        <function type="updateApiVersionStatus">
          <arg name="status">&StateRejected;</arg>
        </function>
      </post-functions>
    </action>
  </actions>
</step>

apiversion.action.reject

Used to reject a new or revised API version that was submitted for approval.

The Business Admin for the organization, or the API Approver, can approve or reject an API version.

The apiversion.action.reject action is available by default when the API version is in this workflow state:

  • Pending Approval

For an example of a workflow section that includes this action, see apiversion.action.approve above.

apiversion.action.resubmit

Used to resubmit a new or revised API version for approval.

Same as apiversion.action.submit.approval above.

The apiversion.action.reject action is available by default when the API version is in this workflow state:

  • Rejected

Additional reserved actions for modifying an API version that's already activated

for your convenience, additional reserved actions are available in case you want to be able to modify one or more properties of an API version after activation. For example, you might need to change a deployment zone or add an implementation. In most cases it's not a good idea to modify an API version, but it might be necessary in some scenarios. By using one or more of these additional reserved actions, you can grant permissions to users with certain roles, to modify one or more specific aspects of an API version.

Note: The reserved actions below are only valid to be assigned when the API workflow state is ACTIVE. In the attached API version template (see API Version Workflow: Custom Workflow Template Examples below), this step: <step id="400" name="Active">.

The following reserved actions are available in this category:

@ModifyPolicies

Valid in version: 2019.1.0 and later

If you want to give users with one or more roles permission to add, modify, or delete the policy assignments for one or more of the implementations for an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

The platform only looks for this workflow action if the @Modify action, which gives broad permission to modify all aspects of the API version, is not present in the custom workflow.

The example below, from the sample custom workflow template at API Version Workflow: Customization Example later in this document, shows use of the @ModifyPolicies reserved action to assign this ability to an API version in Active state.

<action id="402" name="@ModifyPolicies">
  <restrict-to>
    <conditions type="OR">
      <condition type="authorizeByAtmosphereRole">
        <arg name="role">&AtmoRoleBusinessAdmin;</arg>
      </condition>
      <condition type="authorizeByAtmosphereRole">
        <arg name="role">&AtmoRoleApiAdmin;</arg>
      </condition>
      <condition type="authorizeByAtmosphereAction">
        <arg name="Action">Modify</arg>
        <arg name="ResourceType">apiversion</arg>
      </condition> 
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="Active" status="Active" step="400" />
  </results>
</action>

@ModifyDeployments

Valid in version: 2019.1.0 and later

If you want to give users with one or more roles permission to add, modify, or delete deployments for an API version, even when the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

The platform only looks for this workflow action if the @Modify action, which gives broad permission to modify all aspects of the API version, is not present in the custom workflow.

@ModifyDebugOptions

Valid in version: 2019.1.0 and later

If you want to give users with one or more roles permission to modify the debug setting for one or more of the implementations for an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

The platform only looks for this workflow action if the @Modify action, which gives broad permission to modify all aspects of the API version, is not present in the custom workflow.

@ModifyOutboundIdentities

Valid in version: 2019.1.0 and later

If you want to give users with one or more roles permission to modify the outbound identities for an API version, even when the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

The platform only looks for this workflow action if the @Modify action, which gives broad permission to modify all aspects of the API version, is not present in the custom workflow.

@ModifyExtensionProperties

Valid in version: 2019.1.0 and later

If you want to give users with one or more roles permission to modify the extension properties for an API version (when extension properties are in place), even when the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

The platform only looks for this workflow action if the @Modify action, which gives broad permission to modify all aspects of the API version, is not present in the custom workflow.

@DeleteAPIImplementation

Valid in version: 2019.1.0 and later

If you want to give users with one or more roles permission to delete an implementation for an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

The platform only looks for this workflow action if the @Modify action, which gives broad permission to modify all aspects of the API version, is not present in the custom workflow.

@ModifyLegals

Valid in version: 2019.1.0 and later

If you want to give users with one or more roles permission to modify the legal agreement configuration for an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

The platform only looks for this workflow action if the @Modify action, which gives broad permission to modify all aspects of the API version, is not present in the custom workflow.

@AddDeploymentZones

Valid in version: 2019.1.7 and later

If you want to give users with one or more roles permission to add a deployment zone for an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

@ModifyAutoConnectSettings

Valid in version: 2019.1.7 and later

If you want to give users with one or more roles permission to modify the auto-connect setting for an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

@ModifyImplementationInfo

Valid in version: 2019.1.7 and later

If you want to give users with one or more roles permission to modify implementation information for an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

@AddApiImplementation

Valid in version: 2019.1.7 and later

If you want to give users with one or more roles permission to add an implementation to an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

@ModifyApiDetails

Valid in version: 2019.1.7 and later

If you want to give users with one or more roles permission to modify the API details for an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

To modify API details in the Community Manager developer portal: choose your API version and go to Details. In the top section, click Edit.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

@ManageLicenses

Valid in version: 2019.1.7 and later

If you want to give users with one or more roles permission to manage the license settings for an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

To manage licenses in the Community Manager developer portal: choose your API version and go to Details > Manage Licensing.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

@ModifyApiDesign

Valid in version: 2019.1.7 and later

If you want to give users with one or more roles permission to modify the design details for an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action

To modify API design in the Community Manager developer portal: choose your API version and go to Details > Design section > Edit.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

@ModifyOAuthDetails

Valid in version: 2019.1.7 and later

If you want to give users with one or more roles permission to modify the OAuth details for an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

To modify OAuth details in the Community Manager developer portal: choose your API version and go to Details > OAuth Details.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

@ModifyTargetEndpoints

Valid in version: 2019.1.7 and later

If you want to give users with one or more roles permission to modify target endpoints for an implementation of an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

To modify target endpoints in the Community Manager developer portal: choose your API version and go to Implementations > choose implementation > click Modify target endpoints.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

@ProcessEditorModify

Valid in version: 2019.1.7 and later

If you want to give users with one or more roles permission to modify processes on operations that are part of an implementation of an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

To modify a process in the Community Manager developer portal: choose your API version and go to Implementations > choose implementation > go to the Resources section, click arrow and choose Edit Process.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

@ModifyServiceCertificate

Valid in version: 2019.1.7 and later

If you want to give users with one or more roles permission to modify the certificate for an implementation of an API version, even after the API version is activated, you can use this reserved action. You can then specify which roles can perform the action.

To modify the certificate for an API version in the Community Manager developer portal: choose your API version and go to Implementations > choose implementation > go to the Certificate section, and click Edit.

Note: This is provided for your convenience in case you want to modify an API version after it's been activated. In most cases, this is not necessary or recommended.

@DisallowApiAccess

Valid in Version: 2019.1.32 and later

By default, any user who has visibility of an API can request API access via the Access button on the API Overview page.

If needed, you can change this default behavior via custom workflow. You can create and implement a custom API version workflow that uses the reserved action, @DisallowApiAccess, so that users do not have visibility of the Access button.

Using the API custom workflow, you an define users that are not allowed to have visibility to the Access button and define the users that are able to see the Access button using the API workflow. The visibility to the Access button can be controlled by Role, Domain or Actions assigned to the user.

By default, if you are not using custom API workflow, when an API is added to the Community Manager developer portal, it is automatically in Active state. This documentation includes two versions of a custom API workflow doc, for version 2019.1.32 and later (see API Version Workflow: Custom Workflow Template Examples below):

  • Example 1: Shows how visibility of the Access button can be removed for all roles, with specified exceptions. When an API is created using this workflow, the state of the API is Draft (custom behavior).

    In this example, the @DisallowApiAccess Reserved Action is used to disallow API access for all users except those with one of the following roles:

    • APIAccessor: A new custom role defined in Policy Manager; see steps below.
    • AtmoRoleBusinessAdmin: Users with the Business Admin role.
    • AtmoRoleApiAdmin: Users with the API Admin role for the specific API.
    • Modify: Users with a role that includes Modify permission for the API.
  • Example 2: Shows how visibility of the Access button can be removed for users who are added to the DisableAccessForAPI role. When an API is created using this workflow, the state of the API is Active (default behavior).

    In this example, the @DisallowApiAccess Reserved Action is used to disallow API access for all users who have the following role:

    • DisableAccessForAPI: A new custom role defined in Policy Manager; see steps below.

Each template example includes a custom role, which you must create in Policy Manager in Step 1 below. You can use a different role name, but you must modify the workflow to reference the correct role name as covered in Step 1 below.

To implement custom API version workflow to restrict API access using @DisallowApiAccess

Note: The instructions below are written for Example 1. The steps are the same for Example 2, but the role name is different and the approach is slightly different.

  1. Administrator: In Policy Manager, create a custom role with READ permission on both API and API Version. For instructions on creating a new role, see Security Roles and Role Memberships.

    The custom role defined in Example 1 is APIAccessor, as shown below:

    <!ENTITY AtmoRoleApiAccessor "APIAccessor" >

    The custom role defined in Example 2 is DisableAccessForAPI, as shown below:

    <!ENTITY DisableAccessForAPI "DisableAccessForAPI" >

    Note: If you define a different role name, you must update the role name in the custom workflow in Step 2.2 below.

  2. Site Admin: In the Community Manager developer portal, create and assign a custom API version workflow that uses the @DisallowApiAccess reserved action to remove visibility of the Access button and also defines the roles that will be authorized to see and use the Access button:
    1. If you don't have any custom API version workflow already in place, download the sample from the link in this document: see API Version Workflow: Custom Workflow Template Examples below. Make sure you choose a version that supports @DisallowApiAccess, as noted.
    2. Modify the custom workflow as needed. For example:
      • If you are using a different role name, change the role name in the two places where it occurs. The first is shown in Step 1 above, and the second is on the line shown below. The example given here is from Example 1: 
         action id="420" name="@DisallowApiAccess">
      • Un-comment the section that implements the @DisallowApiAccess reserved action as shown above.

        In Example 2, the comment tag is already removed.

    3. Upload the custom workflow to the Community Manager developer portal. For instructions, see Uploading a New Custom Workflow.
    4. Assign the new custom workflow as the default for APIs, in API Settings > API Workflow Definition field. For instructions, see Implementing a New Custom Workflow.
  3. Business Admin: In the Community Manager developer portal, assign the new role to one or more users. For instructions, see How do I assign security roles to users for my organization?

Modifying the template API version workflow

To get the template, see API Version Workflow: Custom Workflow Template Examples below.

f you have custom API version workflow already in place, use the customized sections of this workflow to add to your existing workflow. If you are not making any changes, use one of the templates provided. For Example 1, un-comment the section with action id 420 as shown below. For Example 2, the comment tag is already removed.

The sections below illustrate the different approaches in the two workflow template examples. The first disallows API access for all, then defines exceptions; the second disallows API access for all user with a specific role.

Note: as always, when you implement a new API Version workflow, it is effective for new API versions only. Existing API versions are unaffected.

Example 1

The example below, from the Example 1 custom template example, shows the section that implements the @DisallowApiAccess reserved action to disallow API access. By default, this section is commented out. If you remove the opening and closing comment tags, and then implement the workflow, the Access button is not visible to any users except the specified roles: the new APIAccessor role (fifth line below), Business Admin, API Admin, and users with Modify permission for the specific resource type.

         <!-- action id="420" name="@DisallowApiAccess">
          <restrict-to>
            <conditions type="AND">
              <condition negate="true" type="authorizeByAtmosphereRole">
                <arg name="role">&AtmoRoleApiAccessor;</arg>
              </condition>
              <condition negate="true" type="authorizeByAtmosphereRole">
                <arg name="role">&AtmoRoleBusinessAdmin;</arg>
              </condition>
              <condition negate="true" type="authorizeByAtmosphereRole">
                <arg name="role">&AtmoRoleApiAdmin;</arg>
              </condition>
              <condition negate="true" type="authorizeByAtmosphereAction">
                <arg name="Action">Modify</arg>
                <arg name="ResourceType">apiversion</arg>
              </condition>
            </conditions>
          </restrict-to>
          <results>
            <unconditional-result old-status="Active" status="Active" step="400" />
          </results>
        </action -->

Example 2

The example below, from the Example 2 custom template example, shows the section that implements the @DisallowApiAccess reserved action to disallow API access. With this approach, the Access button is not visible to any users who have been assigned to the new DisableAccessForAPI role.

        <action id="420" name="@DisallowApiAccess">
          <restrict-to>
            <conditions type="AND">
              <condition type="authorizeByAtmosphereRole">
                <arg name="role">&DisableAccessForAPI;</arg>
              </condition>
            </conditions>
          </restrict-to>
          <results>
            <unconditional-result old-status="Active" status="Active" step="400" />
          </results>
        </action>

API Version Workflow: Functions

The following functions are available for the API version workflow:

exportAPIVersion

Used to control workflow actions associated with export of the specified version of the specified API.

Parameters

None.

Examples/Notes/Additional Information

The example below uses this function to export the API version.

<action id="100" name="Export-WF">
  <restrict-to>
    <conditions type="AND">
      <condition type="authorizeByAtmosphereRole">
<arg name="role">ApiAdmin</arg>
      </condition>
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="Ready" status="Ready" step="100" owner="${caller}" />
  </results>
  <post-functions>
    <function type="exportAPIVersion"/>
  </post-functions>
</action>

exportAPIAllVersions

Exports all versions of the specified API.

Parameters

None.

Examples/Notes/Additional Information

The example below uses this function to export all versions of the API.

<action id="101" name="Export-All-Versions-WF">
  <restrict-to>
    <conditions type="AND">
      <condition type="authorizeByAtmosphereRole">
<arg name="role">ApiAdmin</arg>
      </condition>
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="Ready" status="Ready" step="100" owner="${caller}" />
  </results>
  <post-functions>
    <function type="exportAPIAllVersions"/>
  </post-functions>
</action>

markApiVersionDeleted

Valid in version: 2019.1.0 and later

Marks an API version as deleted.

Parameters

None.

Examples/Notes/Additional Information

The example below shows the Delete action in the template custom workflow. Once the conditions have been satisfied, the status is updated from Draft to Deleted and markApiVersionDeleted is implemented as a post-function.

<action id="102" name="@Delete">
  <restrict-to>
    <conditions type="AND">
        <condition type="isApiVersionInDraftState" />
        <conditions type="OR">
          <condition type="authorizeByAtmosphereRole">
            <arg name="role">&AtmoRoleBusinessAdmin;</arg>
          </condition>
          <condition type="authorizeByAtmosphereAction">
            <arg name="Action">Delete</arg>
            <arg name="ResourceType">apiversion</arg>
          </condition>
          <condition type="authorizeByAtmosphereRole">
            <arg name="role">&AtmoRoleApiAdmin;</arg>
          </condition> 
        </conditions>
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="Draft" status="Deleted" step="500" />
  </results>
  <post-functions>
    <function type="markApiVersionDeleted"/>
  </post-functions>
</action>

updateApiVersionStatus

Valid in version: 2019.1.0 and later

Updates the status of an API version, to the value provided in the argument. The new status must be a valid transition from the current status; for example, from Pending Approval to Active.

Parameters

Name Description/Values
status

The new status that the API version is being updated to. Use the valid states defined in the sample (see API Version Workflow: Custom Workflow Template Examples):

  • com.soa.api.state.draft
  • com.soa.api.state.pending_approval
  • com.soa.api.state.rejected
  • com.soa.api.state.active

Examples/Notes/Additional Information

The example below shows the API version workflow when an API version is submitted for approval. The previous status is Draft, and the new status is Pending Approval.

<action id="103" name="apiversion.action.submit.approval">
  <restrict-to>
    <conditions type="AND">
      <condition type="isApiVersionInDraftState" />
      <conditions type="OR">
        <condition type="authorizeByAtmosphereRole">
          <arg name="role">&AtmoRoleBusinessAdmin;</arg>
        </condition>
        <condition type="authorizeByAtmosphereAction">
          <arg name="Action">Modify</arg>
          <arg name="ResourceType">apiversion</arg>
        </condition>
        <condition type="authorizeByAtmosphereRole">
          <arg name="role">&AtmoRoleApiAdmin;</arg>
        </condition> 
      </conditions>
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="Draft" status="Pending Approval" step="300" />
  </results>
  <post-functions>
    <function type="updateApiVersionStatus">
      <arg name="status">&StatePendingApproval;</arg>
    </function>
  </post-functions>
</action>

connectAppsFromPreviousVersion

Valid in version: 2020.1.0 and later

When a new API version is created, connects all apps that are currently contracted to the API, to the new version.

You can use this API workflow function so that when a new version of an existing API is created, all apps that have an existing connection to a previous version of the API are automatically connected to the new version. This makes it easier for apps to migrate to a new version of the API, and can help make it easier to retire older versions of the API.

Parameters

None.

Examples/Notes/Additional Information

The example below shows a workflow step that adds connectAppsFromPreviousVersion as a pre-function when an API version becomes active. This initiates API access for the apps that are connected to the existing API version.

<step id="400" name="Active">
  <pre-functions>
    <function type="connectAppsFromPreviousVersion">
    </function>
  </pre-functions>

API Version Workflow: Conditions

The following condition applies to the API version workflow:

isApiVersionInDraftState

Valid in version: 2019.1.0 and later

Tests to see if the API Version is in Draft state; returns Boolean true or false.

Arguments

None.

Examples/Notes/Additional Information

In the example below, an API version is submitted for approval. The workflow firsts checks that the API version is in Draft state.

<action id="103" name="apiversion.action.submit.approval">
  <restrict-to>
    <conditions type="AND">
      <condition type="isApiVersionInDraftState" />
      <conditions type="OR">
        <condition type="authorizeByAtmosphereRole">
          <arg name="role">&AtmoRoleBusinessAdmin;</arg>
        </condition>
        <condition type="authorizeByAtmosphereAction">
          <arg name="Action">Modify</arg>
          <arg name="ResourceType">apiversion</arg>
        </condition>
        <condition type="authorizeByAtmosphereRole">
          <arg name="role">&&AtmoRoleApiAdmin;</arg>
        </condition> 
      </conditions>
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="Draft" status="Pending Approval" step="300" />
  </results>
  <post-functions>
    <function type="updateApiVersionStatus">
      <arg name="status">&StatePendingApproval;</arg>
    </function>
  </post-functions>
</action>

API Version Workflow: Variable Resolvers

The API version workflow governs the API Version object. There is one variable available for the API version workflow:

${api.dn}

The unique ID for the API that the API version is associated with (APIID).

API Version Workflow: Custom Workflow Template Examples

As a starting point, download one of the following ZIP files, unzip, and review the custom workflow template:

Then, you can modify actions and roles as needed to achieve the results you want.

When you have your custom workload ready, upload it to the Community Manager developer portal and assign it as your default workflow for API versions. For instructions, see To implement a custom API version workflow (Community Manager developer portal documentation).

Note: For all other workflow templates, it's best to go into the Community Manager developer portal (More > Admin > Workflows), and download the version that's there. This workflow is custom, and therefore not available via the Community Manager developer portal, so examples are provided here.

API Version Workflow: Customization Example

This section:

  • Describes a scenario where you might want to use custom workflow to implement custom behavior that includes an API version approval process, so that the API version is in a Draft state until approval is requested.
  • Includes a template that you could use to implement this specific behavior.

Default behavior

Without a custom workflow in place, when a user creates an API in the Community Manager developer portal, it is activated immediately. It becomes searchable (unless marked as Private, and even then, it is marked as Searchable to those who have visibility). Users who can see the API can connect to that API version automatically. By default, there is no approval process for the API; it becomes active immediately.

Custom behavior

Instead of the default behavior, you might want to implement a scenario where when an API is still being designed it is in Draft state, and remains in Draft state until you submit it for approval. In Draft state, you can save the API and go back tomorrow to add more operations or more model objects, or to add or modify other data associated with the API such as policies and deployment zones.

When the API is ready, you can submit it for approval. At that point, the API is in Pending Approval state.

Then, specific users can approve the API. For this template, users with the role of API Approver or Business Admin can approve the API. If the API is approved, it is in Activated state. Alternatively, if the API is rejected, it goes back to Draft state.

Activated state: default behavior

Without custom workflow in place, an API version can be changed at any point by any user with API Admin right for the API, or by a Business Admin.

Activated state: custom template behavior

With this custom workflow template in place, once an API version is in Activated state it cannot be changed. This helps maintain reliability and consistency in a scenario where many apps might be connected to an API version.

However, you might want to implement a scenario where certain actions are allowed. For example, when an API is in Approved state and in production, you would not want to change the API design, but you might want to add a Detailed Auditing policy for monitoring purposes, or add a deployment zone, or add new endpoints. To allow these actions with this custom template workflow, you'd need to add one or more of the reserved actions shown below, and then give users with one or more roles permission to perform that action. For an example, see @ModifyPolicies above.

The actions you can allow even when the API version is in Activated state, with the custom template workflow, are:

The custom workflow template has the built-in flexibility for you to control any of the above actions to a fine level of granularity.