App Version Workflow

There is no default workflow applied to app versions, but the platform supports implementation of custom workflow for app versions.

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

Table of Contents

• App Version Workflow: Initial Actions
• App Version Workflow: Reserved Actions
• App Version Workflow: Functions
• App Version Workflow: Conditions
• App Version Workflow: Variable Resolvers

App Version Workflow: Initial Actions

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

• @Create

@Create

Starts the workflow, for a new app.

For more information, see Workflow Initial Actions.

App Version Workflow: Reserved Actions

The following reserved actions are defined for app version workflows:

• @Modify
• @Delete
• @KeyInfoRemoved
• @KeyInfoSaved
• @RegeneratedSecret
• reserved-allow-cert-upload
• reserved-connect-to-api
• reserved-connect-to-api.Sandbox
• reserved-connect-to-api.Production
• reserved-approve-api-connection.Production
• reserved-cancel-api-connection.Sandbox
• reserved-cancel-api-connection
• @ModifyCert
• @RemoveCert
• @EditApp
• @RegenerateSecret
• @AddVersion
• @EditPublicProfile
• @EditOAuthDetails
• reserved-allow-oauth-auz-details-update
• reserved-action-modify

@Modify

Used to determine whether an app 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 app version.

Note: @Modify controls permission to modify the entire app version. A user with this permission is authorized to perform all edit activities for the app version, such as saving or removing the app certificate/CSR, regenerating the shared secret, adding an app version, or editing the app's public profile. 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.

@Delete

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

If you want the app version to be immediately deleted, you can invoke the deleteAppVersion function for @Delete. However, if you want to set up an approval process, you can instead take the app to a different state. The custom out-of-the-box app workflow, appversion-workflow-template1.xml, uses workflow step 200, Marked For Delete, to initiate a Business Admin approval process. If the Business Admin approves the request, the app is deleted.

@KeyInfoRemoved

Invoked when the certificate/CSR info that was previously added for an app version is removed.

You can use this to trigger additional actions in the workflow; for example, sending notifications or generating Board items.

@KeyInfoSaved

Invoked when the app version's certificate/CSR is added or modified.

You can use this to trigger additional actions in the workflow; for example, sending notifications or generating Board items.

@RegeneratedSecret

Invoked when the app Shared Secret is regenerated.

You can use this to trigger additional actions in the workflow; for example, sending notifications or generating Board items.

reserved-allow-cert-upload

If this reserved action is present in the workflow, certificate upload is allowed.

reserved-connect-to-api

If this reserved action is present in the workflow, an authorized user can initiate a connection to an API in either environment.

reserved-connect-to-api.Sandbox

If this reserved action is present in the workflow, an authorized user can initiate a connection to an API in the Sandbox environment.

reserved-connect-to-api.Production

If this reserved action is present in the workflow, an authorized user can initiate a connection to an API in the Live environment.

reserved-approve-api-connection.Production

If this reserved action is present in the workflow, an authorized user can approve a connection to an API in the Live environment.

reserved-cancel-api-connection.Sandbox

If this reserved action is present in the workflow, an authorized user can approve a connection to an API in the Sandbox environment.

reserved-cancel-api-connection

If this reserved action is present in the workflow, an authorized user can cancel a connection to an API.

@ModifyCert

If you want to give users with one or more roles permission to modify the app certificate, you can use this reserved action. You can then specify which roles can perform the action.

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

@RemoveCert

Invoked when the app's certificate is removed.

If you want to give users with one or more roles permission to remove the app certificate, you can use this reserved action. You can then specify which roles can perform the action.

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

@EditApp

If you want to give users with one or more roles permission to edit the app, you can use this reserved action. You can then specify which roles can perform the action.

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

@RegenerateSecret

If you want to give users with one or more roles permission to regenerate the app's Shared Secret, you can use this reserved action. You can then specify which roles can perform the action.

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

@AddVersion

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

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

@EditPublicProfile

If you want to give users with one or more roles permission to modify the app's public profile, you can use this reserved action. You can then specify which roles can perform the action.

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

@EditOAuthDetails

If you want to give users with one or more roles permission to modify the app's OAuth details, you can use this reserved action. You can then specify which roles can perform the action.

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

reserved-allow-oauth-auz-details-update

Each app has a page where the app developer can specify the app's settings and preferences for OAuth. This page includes an additional section, for advanced Authorization settings, that isn't normally available to app developers. Only Site Admins or Business Admins see the Authorization section at the bottom of the OAuth Profile page.

If you want to allow app developers to modify values in the Authorization section of the App OAuth Profile, you'll need to upload a custom workflow that includes the reserved-allow-oauth-auz-details-update reserved workflow action.

The workflow section below shows how this would look in a custom workflow.

<action id="116" name="reserved-allow-oauth-auz-details-update">
  <restrict-to>
    <conditions type="AND">
      <condition type="authorizeByAtmosphereRole">
        <arg name="role">&AtmoRoleAdmin;</arg>
      </condition>
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="Setup" status="Setup" step="100" owner="${caller}" />
  </results>
</action>

In the default Community Manager developer portal, there is a template, workflow-workflow_definition_appversion-workflow-template1.xml, that you can use to implement this functionality.

reserved-action-modify

Similar to @Modify. This gives the ability to add permission for who can modify the object.

The workflow section below shows how this would look in a custom workflow.

<action id="117" name="reserved-action-modify">
  <restrict-to>
    <conditions type="AND">
      <condition type="authorizeByAtmosphereRole">
        <arg name="role">&AtmoRoleAdmin;</arg>
      </condition>
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="Setup" status="Setup" step="100" owner="${caller}" />
  </results>
  <post-functions>
    <function type="syncAppVersionOAuthClient">
      <arg name="action">Reset</arg>
    </function>
  </post-functions>
</action>

App Version Workflow: Functions

The following functions are available for the app version workflow:

• cloneAllAPIContracts
• activateAllAPIContractsInEnvironment
• cancelAllAPIContractsInEnvironment
• sendNotification
• deleteAppVersion
• addBoardItem
• syncAppVersionOAuthClient
• notifyAppVersionDeleteToOAuthClient

cloneAllAPIContracts

Sets up connections in the target environment with all the API versions that the app version is connected to in the source environment.

Parameters

Name	Description/Values
EnvFrom	Source environment: The environment contracts are being cloned from. Values: Sandbox or Production.
EnvTo	Target environment: The environment contracts are being cloned to. Values: Sandbox or Production.

Examples/Notes/Additional Information

In the example below, this function is used to clone all API contracts from Sandbox to Live (Production).

<pre-functions>
  <function type="cloneAllAPIContracts">
    <arg name="EnvFrom">Sandbox</arg>
    <arg name="EnvTo">Production</arg>
  </function>
</pre-functions>

activateAllAPIContractsInEnvironment

Activates all of an app's connections in the specified environment. For example, for an app with five contracts in the Live environment, this function would activate all of them.

Parameters

Name	Description/Values
Environment	The environment in which all API contracts are being activated. Values: Sandbox or Production.

Examples/Notes/Additional Information

In the example below, this function is used to activate all API contracts in the Live environment.

<pre-functions>
  <function type="activateAllAPIContractsInEnvironment">
    <arg name="Environment">Production</arg>
  </function>
  <function type="cancelAllAPIContractsInEnvironment">
    <arg name="Environment">Sandbox</arg>
  </function>
</pre-functions>

cancelAllAPIContractsInEnvironment

Cancels all of an app's connections in the specified environment.

Parameters

Name	Description/Values
Environment	The environment in which all API contracts are being cancelled. Values: Sandbox or Production.

Examples/Notes/Additional Information

The example below shows the use of activateAllAPIContractsInEnvironment followed by cancelAllAPIContractsInEnvironment to activate all contracts in the Live environment and then cancel all contracts in the Sandbox environment.

<restrict-to>
  <conditions type="AND">
    <condition type="authorizeByAtmosphereRole">
      <arg name="role">AppAdmin</arg>
    </condition>
  </conditions>
</restrict-to>
<pre-functions>
  <function type="activateAllAPIContractsInEnvironment">
    <arg name="Environment">Production</arg>
  </function>
  <function type="cancelAllAPIContractsInEnvironment">
    <arg name="Environment">Sandbox</arg>
  </function>
</pre-functions>

sendNotification

Triggers the specified notification based on an event relating to an app version.

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
notificationType	The type of notification being sent. Can be any valid notification existing in the platform. For example: com.soa.notification.type.app.marked.for.deletion.appteam com.soa.notification.type.app.marked.for.deletion.apiadmin com.soa.notification.type.app.marked.for.deletion.bizadmin
Role	The role to which the notifications will be sent. Valid values: ApiAdmin AppAdmin BusinessAdmin

Examples/Notes/Additional Information

In the example below, three different notifications are sent out, one for each of three different types of users, to notify the users that the app was marked for deletion.

<function type="sendNotification">
  <arg name="notificationType">com.soa.notification.type.app.marked.for.deletion.appteam</arg>
  <arg name="role">AppAdmin</arg>
</function>
<function type="sendNotification">
  <arg name="notificationType">com.soa.notification.type.app.marked.for.deletion.apiadmin</arg>
  <arg name="role">ApiAdmin</arg>
</function>
<function type="sendNotification">
  <arg name="notificationType">com.soa.notification.type.app.marked.for.deletion.bizadmin</arg>
  <arg name="role">BusinessAdmin</arg>
</function>

deleteAppVersion

This function permanently deletes the application version from the database.

It does not add a Board item or notification, but you can add either or both of these as additional functions:

To add a notification, use sendNotification.

To add a Board item, use addBoardItem.

The out-of-the-box app version workflow includes notifications and Board items as additional functions, by default. The deleteAppVersion function itself does not send them.

Note: If you want to add Board items or functions, add them before the deleteAppVersion function is run, so that information needed for the Board item, such as the App Version ID, is still available. Once app version is deleted, the App Version ID is no longer valid.

Parameters

None.

Examples/Notes/Additional Information

In the example below, deleteAppVersion is run as the last pre-function.

<pre-functions>
  <function type="addBoardItem">
    <arg name="boardItemTemplateId">com.soa.board.item.appversion.delete.request.approved</arg>
    <arg name="visibility">Limited</arg>
    <arg name="type">Discussion</arg>
    <arg name="targetBoard.appversion">${app.version.dn}</arg>
    <arg name="targetBoard.appdn">${app.dn}</arg>
    <arg name="targetBoard.appteamgrp">${app.team.group.dn}</arg>
    <arg name="targetBoard.apiversion">${connected.apiversion.ids}</arg>
    <arg name="targetBoard.apiadmin.groups">${connected.apis.admin.groups}</arg>
    <arg name="targetBoard.api">${connected.apis.id}</arg>
    <arg name="viewers">${app.dn},${app.team.group.dn},${connected.apis.id},${business.dn}</arg>
  </function>
  <function type="sendNotification">
    <arg name="notificationType">com.soa.notification.type.app.deletion.request.approved.apiadmin</arg>
    <arg name="role">ApiAdmin</arg>
  </function>
  <function type="sendNotification">
    <arg name="notificationType">com.soa.notification.type.app.deletion.request.approved.appteam</arg>
    <arg name="role">AppAdmin</arg>
  </function>
  <function type="sendNotification">
    <arg name="notificationType">com.soa.notification.type.app.deletion.request.approved.bizadmin</arg>
    <arg name="role">BusinessAdmin</arg>
  </function>
  <function type="deleteAppVersion" />
</pre-functions>

addBoardItem

Adds a Board item to one or more boards for the app.

This function can load a message template and dynamically fill in some values into the template with the help of a parameter resolver. When the workflow action is invoked, a comment is added by the user. The parameter resolver can be used to include this comment in the board item title/description, email message subject/body, and/or a dashboard notification. To use this feature, reference the parameter resolver {action.comment} in the notification template. When the action is performed, this parameter resolver will be replaced by the comment entered by the user performing the workflow action.

Parameters

Name	Description/Values
boardItemTemplateId	The ID of the Board item notification template, from the database, to be used for the Board item title and description. For example: com.soa.board.item.appversion.delete.request.approved
Visibility	The visibility of the Board item. Valid values: Public Limited RegisteredUsers
Type	The Board item type. Currently, the only valid value is Discussion.
targetBoard	Used to specify that one item could be added to multiple boards. For example, the Delete App board item could be added to the app board and also the API boards for connected APIs. It could also be added to other boards, such as the board for each team member. There are two ways to add the targetBoard information (see example below): targetBoard.{parametername}, listing separately each parameter to be added to the target board. targetBoards, plural parameter, with a comma-separated list of Board items to be added.
viewers	Indicates who can view the Board item. For example, providing the App ID as a value indicates that anyone who can administer the app can view the Board item. There are two ways to specify the viewers: viewer.{parametername}, listing separately each applicable ID to indicate that users who have view of that resource have view of the Board item. viewers, plural parameter, with a comma-separated list of Board items to be added. Examples of values: app.team.group.dn: app team connected.apis.id: API Admins for connected APIs business.dn: Business Admins for the business

Examples/Notes/Additional Information

The example below shows adding a Board item as a pre-function, to announce that an app deletion request was approved. In this example, targetBoard is a set of separate arguments.

<pre-functions>
  <function type="addBoardItem">
    <arg name="boardItemTemplateId">com.soa.board.item.appversion.delete.request.approved</arg>
    <arg name="visibility">Limited</arg>
    <arg name="type">Discussion</arg>
    <arg name="targetBoard.appversion">${app.version.dn}</arg>
    <arg name="targetBoard.appdn">${app.dn}</arg>
    <arg name="targetBoard.appteamgrp">${app.team.group.dn}</arg>
    <arg name="targetBoard.apiversion">${connected.apiversion.ids}</arg>
    <arg name="targetBoard.apiadmin.groups">${connected.apis.admin.groups}</arg>
    <arg name="targetBoard.api">${connected.apis.id}</arg>
    <arg name="viewers">${app.dn},${app.team.group.dn},${connected.apis.id},${business.dn}</arg>
  </function>

The example below shows adding a Board item as a post-function, to announce that an app version has been marked for deletion. In this example, the targetBoards parameter is used, with multiple values in a comma-separated list.

<post-functions>
  <function type="addBoardItem">
    <arg name="boardItemTemplateId">com.soa.board.item.appversion.mark.for.delete</arg>
    <arg name="visibility">Limited</arg>
    <arg name="type">Discussion</arg>
    <arg name="targetBoards">${app.version.dn},${app.dn},${app.team.group.dn},${connected.apiversion.ids},
${connected.apis.admin.groups},${connected.apis.id},${app.version.dn},${app.dn}</arg>
    <arg name="viewers">${app.dn},${app.team.group.dn},${connected.apis.id},${business.dn}</arg>
  </function>

syncAppVersionOAuthClient

Adds an app version to the OAuth client via the Client Registration endpoint, so that manual registration is not necessary. Useful for any OAuth provider that supports Client Registration (for example, PingFederate).

Also used to update information for an existing app, so that client registration stays current.

There is no default workflow for Application; in order to implement Client Registration, custom application workflow is needed that includes this function.

Certain workflow actions would typically trigger this function in the app workflow, as listed for the Action parameter. See examples below.

Parameters

Name	Description/Values
Action	The specific workflow action. Valid values: EditOAuthDetails @KeyInfoRemoved @KeyInfoSaved @RegeneratedSecret com.soa.appversion.delete.approve com.soa.appversion.delete.auto reserved-action-modify

Examples/Notes/Additional Information

The examples below show this function used with each of the workflow actions listed above.

@EditOAuthDetails:

<function type="syncAppVersionOAuthClient">
  <arg name="action">Reset</arg>
</function>

@KeyInfoRemoved:

<function type="syncAppVersionOAuthClient">
  <arg name="action">Reset</arg>
</function>

@KeyInfoSaved:

<function type="syncAppVersionOAuthClient">
  <arg name="action">Reset</arg>
</function>

@RegeneratedSecret:

<function type="syncAppVersionOAuthClient">
  <arg name="action">Reset</arg>
</function>

com.soa.appversion.delete.approve:

<function type="syncAppVersionOAuthClient">
  <arg name="action">Delete</arg>
</function>

com.soa.appversion.delete.auto:

<function type="syncAppVersionOAuthClient">
  <arg name="action">Delete</arg>
</function>

reserved-action-modify:

<function type="syncAppVersionOAuthClient">
  <arg name="action">Reset</arg>
</function>

notifyAppVersionDeleteToOAuthClient

Notifies the OAuth client when a registered app or app version is deleted, via the Client Registration endpoint, so that client registration stays current.

There is no default workflow for Application; in order to implement Client Registration, custom application workflow is needed that includes this function.

The following workflow actions would typically trigger this function in the app workflow (see examples below):

• com.soa.appversion.delete.approve
• com.soa.appversion.delete.auto

Parameters

None.

Examples/Notes/Additional Information

The examples below show this function used with each of the workflow actions listed above.

com.soa.appversion.delete.approve:

<function type="notifyAppVersionDeleteToOAuthClient"/>

com.soa.appversion.delete.auto:

<function type="notifyAppVersionDeleteToOAuthClient"/>

App Version Workflow: Conditions

The following conditions apply to the app version workflow:

• isAppTeamMemberUserLeaderOfAnyOtherGroup
• atleastOneValidAPIContractInEnvironment
• allAPIContractsInEnvironmentApproved
• existAPIContractsForAllAPIsInEnvironments

isAppTeamMemberUserLeaderOfAnyOtherGroup

Tests to see if the user is an app team member and is also a leader of at least one other independent group. Returns true if the logged-in user is a leader of any independent group.

Parameters

None.

atleastOneValidAPIContractInEnvironment

Checks that there is at least one contract for the specified app version with the specified API in the specified environment. Returns true if the app is connected to at least one API version in the specified environment (states of Cancelled or ApiDeleted are not valid).

Parameters

Name	Description/Values
Environment	The environment being tested to see if there is a valid contract. For this function, the value will always be Sandbox.

Examples/Notes/Additional Information

In the example below, the action being performed is to cancel an API contract in the Sandbox environment. The workflow first checks that there is at least one valid API contract in the Sandbox environment.

<action id="202" name="reserved-cancel-api-connection.Sandbox">
  <results>
    <result old-status="Sandbox" status="Setup" step="100" owner="${caller}">
      <conditions type="AND">
<condition type="atleastOneValidAPIContractInEnvironment">
  <arg name="Environment">Sandbox</arg>
</condition>
      </conditions>
    </result>
    <unconditional-result old-status="Sandbox" status="Sandbox" step="200" owner="${caller}" />
  </results>
</action>

allAPIContractsInEnvironmentApproved

Checks whether all API contracts in the specified environment are approved. Returns true if all connections in the specified environment are approved.

Arguments

Name	Description/Values
Environment	The environment for which all API contracts are being approved. Values: Sandbox or Production.

Examples/Notes/Additional Information

In the example below, the action being performed is to approve all API contracts in the Live environment.

<action id="301" name="reserved-approve-api-connection.Production">
  <restrict-to>
    <conditions type="AND">
      <condition type="existAPIContractsForAllAPIsInEnvironments">
<arg name="EnvFrom">Sandbox</arg>
<arg name="EnvTo">Production</arg>
      </condition>
      <condition type="allAPIContractsInEnvironmentApproved">
<arg name="Environment">Production</arg>
      </condition>
      <condition type="authorizeByAtmosphereRole">
<arg name="role">BusinessAdmin</arg>
      </condition>
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="Review" status="Approved" step="400" owner="${caller}" />
  </results>
</action>

existAPIContractsForAllAPIsInEnvironments

Checks whether for each contract that exists in one API environment (sandbox or Live) there is a corresponding contract for the other environment. Returns true if the app version is connected to the same API versions in the "EnvTo" environment as in the "EnvFrom" environment.

Arguments

Name	Description/Values
EnvFrom	The environment the API contract is exported from (Sandbox or Production).
EnvTo	The environment the API contract is exported to (Sandbox or Production).

Examples/Notes/Additional Information

In the example below, the action being performed is to approve all API contracts in the Live environment. The workflow first tests that there are contracts in existence, because a contract must exist before it can be approved.

<action id="301" name="reserved-approve-api-connection.Production">
  <restrict-to>
    <conditions type="AND">
      <condition type="existAPIContractsForAllAPIsInEnvironments">
<arg name="EnvFrom">Sandbox</arg>
<arg name="EnvTo">Production</arg>
      </condition>
      <condition type="allAPIContractsInEnvironmentApproved">
<arg name="Environment">Production</arg>
      </condition>
      <condition type="authorizeByAtmosphereRole">
<arg name="role">BusinessAdmin</arg>
      </condition>
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="Review" status="Approved" step="400" owner="${caller}" />
  </results>
</action>

App Version Workflow: Variable Resolvers

The following variable resolvers are available for the app version workflow:

• ${app.dn}
• ${app.team.group.dn}
• ${app.version.dn}
• ${app.version.name}
• ${business.dn}
• ${connected.apis.admin.groups}
• ${connected.apiversion.ids}
• ${connected.apis.id}

${app.dn}

The unique ID for the app, as a string in the format ${app.dn}.

${app.team.group.dn}

The group ID for the app team members, as a string in the format ${app.team.group.dn}.

${app.version.dn}

The unique ID for the app version, as a string in the format ${app.version.dn}.

${app.version.name}

The text name for the app version, as a string in the format ${app.version.name}.

${business.dn}

The unique ID for the business, a string in the format ${business.dn}.

${connected.apis.admin.groups}

The unique IDs for the API Admin groups of any APIs connected to a specific app, in the format ${connected.apis.admin.groups}.

${connected.apiversion.ids}

The unique API Version IDs for all API versions connected to a specific app, in the format ${connected.apiversion.ids}.

${connected.apis.id}

The unique API IDs for all APIs connected to a specific app, in the format ${connected.apis.ids}.

Related Topics