Custom Workflows

Add, change, and delete custom workflows for resources on the platforms.

API Platform Version: 8.1 and later

Table of Contents

  1. What is a custom workflow?
  2. Which workflows can I customize?
  3. How do I set up and manage custom workflows?
  4. How do I specify a custom workflow for APIs?
  5. How do I specify a custom workflow for apps?
  6. How do I specify a custom workflow for API contracts?
  7. How do I specify a custom workflow for groups?
  8. How do I specify a custom workflow for tickets?
  9. How do I specify a custom workflow for platform users?
  10. What is the default workflow for API contracts?
  11. What is the default workflow for groups?
  12. What is the default workflow for tickets?
  13. What is the default workflow for platform users?
  14. How do I specify a workflow for two-factor authentication of users?
  15. How do I set up custom workflow to implement 2FA by phone?
  16. How do I specify a custom workflow for reviews?
  17. How do I specify a custom workflow for discussions?
  18. How do I specify a custom workflow for OAuth grants?
  19. I uploaded a custom workflow, but it isn't showing as available. What do I do?
  20. How do I set up an app deletion approval workflow?
  21. Related Topics

What is a custom workflow?

There is a standard workflow for various types of resources on the platform. Some of these are controlled to some degree by options that can be specified in the user interface; for example, an API can be set up so that access requests to a specific environment are granted automatically or must be manually approved. However, other aspects of workflow cannot be modified by users via the user interface; for example, the roles required to modify a ticket.

In some cases, it's possible to replace the default workflow with a custom workflow, at the business level. The Site Admin can upload a customized workflow to the platform, and the Site Admin can modify the site configuration to change the workflow assigned to a specific type of object. For example, you could customize the Ticket workflow so that each new ticket automatically triggers an email to create a ticket in your own internal trouble ticketing system.

The workflow definition guides the sequences of activities associated with resources. Workflow definition includes two important factors:

  • State: the current state of the resource, which determines what actions can be taken. For example, a ticket can only be closed if it is currently open.
  • Role: certain actions are restricted to certain user roles. For example, only the individual who wrote a ticket, or the Administrator for the resource, can close a ticket.

The combination of these two factors, State and Role, guide the resource through its workflow.

Back to top

Which workflows can I customize?

A Site Admin can upload certain custom workflows, in Administration/Workflows; the Site Admin can change the default workflow for certain resources in the applicable Administration/Config page or, in the case of OAuth Grant workflow, in the OAuth Provider domain definition. For directions, see How do I set up and manage custom workflows? below.

Resource Type Set WF in... Default WF?
API Config > APIs No
App Config > Apps No
Connections (API Access Request) Config > Apps Yes
Discussions Config > Discussions Yes
Discussion Comments Config > Discussions Yes
Group Membership Config > Groups Yes
OAuth Grant Domains > OAuth Provider Domain > Branding tab Yes
Review Config > Reviews Yes
Ticket Config > Tickets Yes
User Config > Users Yes

Back to top

How do I set up and manage custom workflows?

In the platform, with regard to workflow, resources fall into three categories:

  • There is a default workflow assigned to the resource, but it can be customized.
  • There is no default workflow assigned, but a custom workflow can be applied.
  • The resource is not governed by workflow.

For a list of resources to which you can apply a custom workflow, see Which workflows can I customize? above.

Once the Site Admin has uploaded a custom workflow, the Site Admin can specify that workflow as the default for the resource type. From that point onwards, the new workflow applies to any new resources of that type.

For example, let's say you customize the Ticket workflow so that each new ticket automatically triggers an email to create a ticket in your own internal trouble ticketing system. New tickets trigger this action; existing tickets are not affected.

To upload a custom workflow:
  1. Log in as the Site Admin.
  2. Go to Administration > Workflows.
  3. Click Add Workflow.
  4. Enter the following values to describe the new workflow:
    • Name
    • Description
    • Object Type—the type of resource the workflow applies to; APIs, Application, API Access Request, Group Membership, or Ticket.
  5. Browse to the location of your custom workflow file and upload it.
  6. Click Finish.

Once you've uploaded the custom workflow, the next step is for the Site Admin to assign the custom workflow to the correct resource type, following the instructions for the applicable object type:

Note: Generally, when you specify a new custom workflow for a resource, it affects all future resources. Existing resources are not affected. In some cases, it's possible to modify the workflow used for an individual resource. For example, the API Admin can modify the workflow that a specific API uses, in the API Details page. The Users workflow is an exception; if it is in place, it affects all users.

To delete a custom workflow:
  1. Log in as the Site Admin.
  2. Go to Administration > Workflows.
  3. Find the workflow on the list and click Delete.
To edit a custom workflow:
  1. Log in as the Site Admin.
  2. Go to Administration > Workflows.
  3. Find the workflow on the list and click Edit.
  4. At the Edit Workflow page, make changes as needed and then click Finish.
To view a custom workflow:
  1. Log in as the Site Admin.
  2. Go to Administration > Workflows.
  3. Find the workflow on the list and click View. The workflow XML file is displayed in a separate window.

Back to top

How do I specify a custom workflow for APIs?

The Site Admin can specify a custom workflow and set that as the default workflow for all future APIs on the platform. When the default workflow is changed, the new workflow applies to all new APIs, but existing APIs are not affected.

Before you can specify the custom workflow as the platform default, you must first create the custom workflow externally and upload it. For instructions, see To upload a custom workflow.

To specify a custom workflow for APIs:
  1. Log in as the Site Admin.
  2. Go to Administration > Settings > APIs.
  3. Under API Workflow Definition, click the drop-down list to choose the custom workflow. Note: If the workflow isn't available for selection, it hasn't yet been uploaded. For instructions, see To upload a custom workflow.
  4. Click Save.

For more information on API settings, refer to To configure API settings.

Back to top

How do I specify a custom workflow for apps?

By default, there is no workflow for apps. However, the Site Admin can specify a custom workflow.

Platform installion includes an out-of-the-box app workflow, appversion-workflow-template1.xml, that implements an approval process for app deletion.

If this workflow is in effect, and an app developer deletes an app version, a deletion request is sent to the Business Admin for approval. The app is inactivated pending approval; at this point, developers cannot make any changes to the app, although the Business Admin can still make changes. When the Business Admin approves the request, the app is fully deleted. If for any reason the Business Admin denies the request, the app is restored to normal operation.

To specify this workflow as the default for apps on the platform, the Site Admin must modify the app configuration settings.

To implement a different custom workflow, the Site Admin must first create the custom workflow externally and upload it. For instructions, see To upload a custom workflow. For information about custom workflows, see Akana API Platform: Custom Workflows on docs.akana.com.

To specify a custom workflow for apps:
  1. Log in as the Site Admin.
  2. Go to Administration > Settings > Apps.
  3. Under App Workflow Definition, click the drop-down list to choose the custom workflow. Note: If the workflow isn't available for selection, it hasn't yet been uploaded. For more information, see To upload a custom workflow.
  4. Click Save.

For more information on app settings, refer to To configure app settings.

Back to top

How do I specify a custom workflow for API contracts?

The Site Admin can specify a custom workflow and set that as the default workflow for all future API contracts on the platform. When the default workflow is changed, the new workflow applies to all new contracts, but existing contracts are not affected.

Before the Site Admin can specify the custom workflow as the platform default, the Site Admin must first create the custom workflow externally and upload it. For instructions, see To upload a custom workflow.

To specify a custom workflow for API contracts:
  1. Log in as the Site Admin.
  2. Go to Administration > Settings > Connections.
  3. Under General App/API Connection Settings, choose Sandbox or Live and click the drop-down list to choose the custom workflow. Note: If the workflow isn't available for selection, it hasn't yet been uploaded. For more information, see To upload a custom workflow.
  4. Click Save.

For more information on applicable settings, refer to To configure app/API connection settings.

Back to top

How do I specify a custom workflow for groups?

The Site Admin can specify a custom workflow and set that as the default workflow for all future groups on the platform. When the default workflow is changed, the new workflow applies to all new groups, but existing groups are not affected.

Before the Site Admin can specify the custom workflow as the platform default, the Site Admin must first create the custom workflow externally and upload it. For instructions, see To upload a custom workflow.

To specify a custom workflow for groups:
  1. Log in as the Site Admin.
  2. Go to Administration > Settings > Groups.
  3. Under Group Membership Workflow, click the drop-down list to choose the custom workflow. Note: If the workflow isn't available for selection, it hasn't yet been uploaded. For more information, see To upload a custom workflow.
  4. Click Save.

For more information on Group settings, refer to To configure group settings.

Back to top

How do I specify a custom workflow for tickets?

The Site Admin can specify a custom workflow and set that as the default workflow for all future tickets on the platform. When the default workflow is changed, the new workflow applies to all new tickets, but existing tickets are not affected.

Before the Site Admin can specify the custom workflow as the platform default, the Site Admin must first create the custom workflow externally and upload it. For instructions, see To upload a custom workflow.

To specify a custom workflow for tickets:
  1. Log in as the Site Admin.
  2. Go to Administration > Settings > Tickets.
  3. Under Ticket Workflow Definition, click the drop-down list to choose the custom workflow. Note: If the workflow isn't available for selection, it hasn't yet been uploaded. For more information, see To upload a custom workflow.
  4. Click Save.

For more information on ticket settings, refer to To configure ticket settings.

Back to top

How do I specify a custom workflow for platform users?

You can use the default out-of-the-box user workflow in combination with user settings and business security settings relating to users, to control user experience on the platform and if needed to restrict what users can do. If you need more flexibility, you can design your own custom workflow.

The Site Admin can specify a custom workflow and set that as the default workflow for all future users on the platform. When the default workflow is changed, the new workflow applies to all new users. In addition, for an API platform upgrade scenario, running the Upgrade CM Models task adds existing users to the new workflow.

Before the Site Admin can specify the custom workflow as the platform default, the Site Admin must first create the custom workflow externally and upload it. For instructions, see To upload a custom workflow. For information about custom workflows, see Akana API Platform: Custom Workflows on docs.akana.com.

To specify a custom workflow for platform users:
  1. Log in as the Site Admin.
  2. Go to Administration > Settings > Users.
  3. Under User Workflow Definition, click the drop-down list to choose the custom workflow. Note: If the workflow isn't available for selection, it hasn't yet been uploaded. For more information, see To upload a custom workflow.
  4. Click Save.

For more information on user settings, refer to How do I configure settings for users?

Back to top

What is the default workflow for API contracts?

The default workflow for API contracts is shown below. This diagram shows all the states an API access contract can be in, and the actions that are valid for each state.

default workflow: API contracts

Back to top

What is the default workflow for groups?

The default workflow for groups is shown below. This applies for all types of groups, including:

  • App teams
  • Independent Groups
  • API Admins
  • API Context Groups
  • Site Admins
  • Business Admins

Note: The workflow below shows the most complex group scenario, where the group has Admins, Leaders, and Members (Independent Group, API Context Group). For other types of groups, all members have Admin rights.

default workflow: groups

Back to top

What is the default workflow for tickets?

The default workflow for tickets is shown below.

default workflow: groups

Back to top

What is the default workflow for platform users?

There is currently a default workflow that applies to all local platform users. Users who log in using a third-party identity provider are not managed by the default workflow.

The default workflow for platform users has a slightly different process depending on the type of user:

  • Self-signup user
  • User invited by a Site Admin

In all cases, the user profile can be modified as needed by the Site Admin.

If the platform settings allow users to modify their profiles, the user can also modify his/her own profile. This is evaluated in the workflow by means of the @ModifyProfile reserved action. If @ModifyProfile is present in the workflow and is applicable to the logged-in user, the user can modify his/her own profile.

The default user workflow checks the platform setting that governs whether users can modify their own profiles (Business Security settings; see How do I configure settings for business security?

The default workflow guides users through the login process, checking whether any or all of the following possible login conditions are currently required:

  1. Must the password be changed? A user invited by a Site Admin logs in with a temporary password and must choose a new password as a first step.
  2. Is there a platform legal agreement in place that was not yet accepted by the user? If yes, the user must accept the legal agreement before proceeding with login.
  3. Must the user provide answers to security challenge questions? This could be the case on first login. There are also other circumstances that might trigger this; for example, the requirement to answer security challenge questions is added, or the number of answers each user must provide is increased.

If one of these is required, the login process required that the user complete that one step. Login is then evaluated again. When all required conditions are met, the user is logged in. If it is the user's first login, the user is then marked as permanent in the database; this ensures that the user is not purged. Temporary user records, such as invitation codes that were issued and not responded to, are periodically purged from the database.

If you want to, you can create a custom workflow for users and set your custom workflow as the default. See How do I specify a custom workflow for platform users? above.

Back to top

How do I specify a workflow for two-factor authentication of users?

The platform includes the capability to use two-factor authentication, requiring that users enter a special one-time-only verification code after logging in, as a second level of security and verification.

By default, the two-factor authentication feature is turned off. However, the platform out-of-the-box installation includes a user workflow that you can use to implement this functionality. The workflow name is: workflow:definition:user:v2.

This user workflow, default-user-workflow-v2.xml, guides the user to enter an authentication code after normal login is complete. The authentication code, passed to the user in an out-of-band process, completes the login process.

The workflow retrieves values set up for two-factor authentication in a platform Settings page controlled by the Site Admin.

To specify the two-factor authentication workflow for users:
  1. Log in as the Site Admin.
  2. Go to Administration > Settings > Users.
  3. Under User Workflow Definition, click the drop-down list and choose workflow:definition:user:v2.
  4. Click Save.

Back to top

How do I set up custom workflow to implement 2FA by phone?

The platform supports two-factor authentication, with workflow functions, conditions, and variables and also platform settings that you can use to enable this functionality.

The out-of-the-box user workflow supports sending the 2FA verification code by email (see How do I specify a workflow for two-factor authentication of users? above). However, with a little customization, you can also build a custom workflow that either:

  • Sends the code via a different delivery mechanism instead of email, such as voice or text
  • Offers multiple options that the user can choose from

In the out-of-the-box platform workflow, workflow:definition:user:v2, you'll see the section that defines the options offered to users. It looks something like the below:

<function type="setTwofaDeliveryOptions">
  <arg name="VoiceSupported">false</arg>
  <arg name="TextSupported">false</arg>
  <arg name="EmailSupported">true</arg>
</function>

By default, it is set to support email only. If you want to support voice, text, or both, set those arguments to true. However, you'll also need to write your own custom code to manage the process of sending the code to the customer by phone (voice or text).

The out-of-the-box workflow manages generating the code and sending it to the user by email with the function below:

<function type="send2FACodeToEmail">
  <arg name="DeliveryTargetAddress">${arg.twofa.delivery.target.address}</arg>
  <arg name="DeliveryMechanism">${arg.DeliveryMechanism}</arg>
  <arg name="2FAData">${arg.2fa.task.data}</arg>
  <arg name="2FAVerificationCode">${arg.verificationCode}</arg>
  <arg name="2FAVerificationCodeValidMinutes">${arg.2fa.verification.code.valid.minutes}</arg>
</function>

You'll need to have something along those lines to send the code by phone (voice or text).

For example, the section of the out-of-the-box workflow below has a suggested template commented out for implementation of a custom function. As it stands, the workflow step generates the code but does not send it.

        <result old-status="${workflow.step.name}" status="${workflow.step.name}" step="-1">
  <conditions type="AND">
    <condition type="argumentValueEquals">
      <arg name="ArgName">Action</arg>
      <arg name="Value">generate</arg>
    </condition>
    <condition type="is2FACodeGenerated"/>
    <condition type="isDeliveryTypeVoice"/>
  </conditions>
  <pre-functions>
    <!-- <function type="send2FACodeToPhone"> custom workflow function
      <arg name="DeliveryTargetAddress">${arg.twofa.delivery.target.address}</arg>
      <arg name="DeliveryMechanism">${arg.DeliveryMechanism}</arg>
      <arg name="userPhoneNumber">${sessionuser.phone.number}</arg>
      <arg name="2FAData">${arg.2fa.task.data}</arg>
      <arg name="2FAVerificationCode">${arg.verificationCode}</arg>
      <arg name="2FAVerificationCodeValidMinutes">${arg.2fa.verification.code.valid.minutes}</arg>
    </function> -->
    <function type="setAuthTokenProperty">
      <arg name="PropertyName">2FAData</arg>
      <arg name="PropertyValue">${arg.2fa.authtoken.property}</arg>
    </function>
    <function type="setPendingTask">
      <arg name="PendingTask">2fa.required</arg>
      <arg name="TaskData">${arg.2fa.task.data}</arg>
    </function>
  </pre-functions>

Back to top

How do I specify a custom workflow for reviews?

The Site Admin can specify a custom workflow and set that as the default workflow for all future reviews on the platform. When the default workflow is changed, the new workflow applies to all new reviews, but existing reviews are not affected.

There is an out-of-the-box custom workflow for reviews. Any other custom workflow must first be created externally and uploaded. For instructions, see To upload a custom workflow.

To specify a custom workflow for reviews:
  1. Log in as the Site Admin.
  2. Go to Administration > Settings > Reviews.
  3. Under Review Workflow Definition, click the drop-down list to choose the custom workflow. Note: If the workflow isn't available for selection, it hasn't yet been uploaded. For more information, see To upload a custom workflow.
  4. Click Save.

Back to top

How do I specify a custom workflow for discussions?

The Site Admin can specify a custom workflow and set that as the default workflow for all future discussions on the platform. When the default workflow is changed, the new workflow applies to all new discussions, but existing discussions are not affected.

Before the Site Admin can specify the custom workflow as the platform default, the Site Admin must first create the custom workflow externally and upload it. For instructions, see To upload a custom workflow.

To specify a custom workflow for discussions:
  1. Log in as the Site Admin.
  2. Go to Administration > Settings > Discussions.
  3. Under Discussion Workflow Definition, click the drop-down list to choose the custom workflow. Note: If the workflow you want isn't available for selection, it hasn't yet been uploaded. For more information, see To upload a custom workflow.
  4. Click Save.

Back to top

How do I specify a custom workflow for OAuth grants?

If you have a custom workflow for OAuth grants, you'll need to specify the custom workflow as the Grant Workflow Definition in your OAuth Provider domain definition (Administration > Domains > Add Domain > OAuth Provider) in the Branding tab (Tab #6).

The custom workflow applies for all APIs that use the OAuth Provider domain definition.

For instructions for setting up the OAuth Provider domain, including the custom workflow, see How do I set up and configure an OAuth Provider domain?

Back to top

I uploaded a custom workflow, but it isn't showing as available. What do I do?

When you go into Administration / Config and choose a resource for which you can use a custom workflow, any custom workflows that have been uploaded to your platform for that resource type should be available on the drop-down list for selection.

If the expected custom workflow is not available for selection, first go to Administration / Config / Workflows and check that the workflow was uploaded.

If you see your workflow on the list, the most likely reason it's not available for selection is that an incorrect resource was specified when uploading the workflow. It's important to specify the correct resource, because only workflows designated for a specific resource—for example, tickets—are available on the Config page for that resource.

To check the resource type, find your workflow on the list and then click Edit. In the Edit Workflow page, change the Object Type specified for the workflow, if needed, and then click Save.

Back to top

How do I set up an app deletion approval workflow?

By default, apps do not follow a workflow. However, if needed, you can assign a custom workflow.

The platform includes a sample workflow definition that provides an example of how to specify app deletion approval. If this workflow is implemented, when an app team member deletes an app, the app is deactivated, and a deletion request is sent to the Business Admin for approval. No changes can be made to the app during this time. If the Business Admin approves the deletion request, the app is deleted; if the Business Admin denies the request, the app is restored to an active state.

You can use the sample as-is or use it as a resource for your own custom workflow.

Name for this sample app workflow: appversion-workflow-template1.

Back to top