Workflow General Reference: Functions, Conditions, and Variables

This document serves as a technical reference for creating and maintaining workflow definitions for use with the platform. It includes details about the built-in workflow variables, conditions, and functions for general use with any platform workflow.

Table of Contents

• Functions, Conditions, and Variables
• General Use: Functions
• General Use: Conditions
• General Use: Variable Resolvers

Functions, Conditions, and Variables

The functions, conditions, and variables work together and are the building blocks of your custom workflow.

Each workflow type might have specific functions, conditions, and variables that only work within that type of workflow. In addition, there are general conditions that can be used in any CM custom workflow.

Note: The general use functions, conditions, and variables described in this section are for use with Akana API Platform custom workflows. There is also a set of general use functions, conditions and variables for use specifically with Akana Policy Manager workflows. Those are also valid for Akana API Platform workflows. You will see some of them in use in the examples in this document.

General Use: Functions

Functions are used to add behavior and automation to a workflow.

Below is a generic example of how a function is used in a workflow, and how its arguments are represented:

<function type="functionName">
  <arg name="argName1">arg name 1</arg>
  <arg name="keyName">Key name</arg>
  <arg name="keyValue">Key value</arg>
</function>

The following general use functions are available for workflow in the Akana API Platform:

• setAuthTokenProperty
• removeAuthTokenProperty
• markLoginComplete
• setArgumentValue
• setCookie
• removeCookie

setAuthTokenProperty

Used to specify a custom property for the auth token cookie.

Parameters

Property	Description/Values
PropertyName	The name of a specific property in the auth token cookie.
PropertyValue	The value of a specific property in the auth token cookie.

Examples/Notes/Additional Information

In the example below, the property name 2FAComplete is set to a value of Yes.

<function type="setAuthTokenProperty">
  <arg name="PropertyName">2FAComplete</arg>
  <arg name="PropertyValue">Yes</arg>
</function>

removeAuthTokenProperty

Used to remove a custom property from the auth token cookie.

Parameters

Property	Description/Values
PropertyName	The name of the property.

Examples/Notes/Additional Information

In the example below, the first function removes the existing property and the second one sets a new property, 2FA Complete, with a value of Yes.

<function type="removeAuthTokenProperty">
  <arg name="PropertyName">2FAData</arg>
</function>
<function type="setAuthTokenProperty">
  <arg name="PropertyName">2FAComplete</arg>
  <arg name="PropertyValue">Yes</arg>
</function>

markLoginComplete

Marks the user's login action as fully complete, with no pending login tasks. This is used at the end of the default user workflow, after the user has been guided through all tasks relating to login, such as accepting a legal agreement or specifying the answers to security challenge questions.

Parameters

None.

Examples/Notes/Additional Information

In the example below, the workflow sets the LoginState to LoginComplete and then runs the markLoginComplete function.

<unconditional-result old-status="registered" status="registered" step="450">
  <pre-functions>
    <function type="setProperty">
      <arg name="LoginState">&LoginComplete;</arg>
    </function>
    <!--  invoke send Notification on first time login.  -->
    <function type="markLoginComplete"/>
  </pre-functions>
</unconditional-result>

setArgumentValue

Creates an argument with a specific value. Use this function to make a specific argument available within the workflow execution.

Parameters

Property	Description/Values
ArgName	The name of the argument.
Value	The value of the argument.

setCookie

Sets a cookie with a specific name, value, and expiration date/time.

Parameters

Property	Description/Values
CookieName	The name of the cookie.
CookieValue	The value of the cookie.
CookieExpirationTimeMillis	The expiration time of the cookie, in milliseconds. If not defined, the default is 1500000 (25 minutes).

Examples/Notes/Additional Information

The example below sets the value and expiration time of the D cookie.

<function type="setCookie">
  <arg name="CookieName">D</arg>
  <arg name="CookieValue">akana api platform</arg>
  <arg name="CookieExpirationTimeMillis">31556952000</arg>
</function>

removeCookie

Removes the specified cookie.

Parameters

Property	Description/Values
CookieName	The name of the cookie.

General Use: Conditions

Conditions allow you to:

Select the result of an action Restrict the availability of an action by: Restricting actions: to restrict when an action can be seen or performed. Restricting access: to control service and contract access.

Workflow uses conditions as logical expressions. Conditional functions can take arguments:

<arg>. . .</arg>

For example, the workflow snippet below restricts the workflow action to a specific role. The role specified in the argument is AppAdmin. One or more roles can be specified.

<restrict-to>
  <conditions type="AND">
    <condition type="authorizeByAtmosphereRole">
      <arg name="role">AppAdmin</arg>
    </condition>
  </conditions>
</restrict-to>

Some additional points to note about conditions and how you can use them in custom workflows:

• Conditions can also include nested conditions. You can use a structure of nested conditions to form a complex logical expression.
• You can code a logical NOT as a negative condition: <condition ... negate="TRUE">.

The following general use conditions are available in developing all types of custom workflows on the platform:

• authorizeByAtmosphereRole
• authorizeByAtmosphereAction
• authorizeByDomain
• authorizeByDomainType
• authorizeByEmail
• authorizeByGroupName
• authTokenPropertyExists
• authTokenPropertyMatches
• argumentExists
• argumentValueEquals
• argumentValueMatches
• isSessionInLoginProcess
• cookieExists
• cookieValueEquals
• cookieValueMatches
• actionCommentMatchesRegEx
• actionCommentExists

authorizeByAtmosphereRole

Tests to see if the workflow user has been assigned one or more specified roles in the platform, and is therefore authorized to perform the workflow action; returns Boolean true or false.

Arguments

Name	Description/Values
Role	One or more roles that are authorized to perform the function. Valid values: ApiAdmin ApiInvitedUser AppAdmin SiteAdmin BusinessAdmin Admin (administrator of context object: applies to App, App version, API, API version, and Group)

Examples/Notes/Additional Information

In the example below, the function clones all the contracts a specific app has with APIs, from the Sandbox environment to the Live environment. The <condition> tag uses the authorizeByAtmosphereRole condition to specify that the user attempting to perform this action must be an App Admin (a member of the app team).

<action id="210" name="Submit For Review">
  <restrict-to>
    <conditions type="AND">
      <condition type="authorizeByAtmosphereRole">
        <arg name="role">AppAdmin</arg>
      </condition>
    </conditions>
  </restrict-to>
  <pre-functions>
    <function type="cloneAllAPIContracts">
      <arg name="EnvFrom">Sandbox</arg>
      <arg name="EnvTo">Production</arg>
    </function>
  </pre-functions>
  <results>
    <unconditional-result old-status="Sandbox" status="Review" step="300" owner="${caller}" />
  </results>
</action>

authorizeByAtmosphereAction

Tests to see if the workflow user has permission to perform a specific action on a specific type of resource.

Arguments

Name	Description/Values
Action	The specific action. Valid values: Add
ResourceType	The specific resource. Valid values: app api group

Examples/Notes/Additional Information

In the example below, the workflow tests that the current user has permission to add an API. If the user does not meet the condition, the action is not allowed.

<action id="409" name="@AddAPI">
  <restrict-to>
    <conditions type="AND">
      <condition type="authorizeByAtmosphereAction">
        <arg name="Action">Add</arg>
      <arg name="ResourceType">api</arg>
      </condition>
    </conditions>
  </restrict-to>

authorizeByDomain

Tests to see if the domain of the workflow user matches one of the domains specified, and the user is therefore authorized to perform the workflow action; if so, returns true.

This can be used as a security measure. For example, actions can be limited to one specific domain for security purposes.

Arguments

Name	Description/Values
domain	One or more domains that authorization is restricted to. To include multiple values, you can either include multiple <domain> arguments or list multiple domains on one line, separated by commas. Note: the value for this parameter should be the domain name used in Policy Manager for the applicable identity system. For Policy Manager, use Local Domain as the value.

Examples/Notes/Additional Information

In the example below, this condition specifies that an action is valid only for users on the platform's domain, acmepaymentscorp.

<condition type="authorizeByDomain">
  <arg name="domain">acmepaymentscorp</arg>
</condition>

authorizeByDomainType

Tests to see if the domain type of the workflow user matches one or more specified values. If so, returns true.

This can be used as a security measure to limit platform actions to a specific set of authorized users. For example, a workflow action can be limited to one specific domain type, such as an LDAP domain, for security purposes.

Arguments

Name

Description/Values

DomainType

One or more domain types (Identity System type in Policy Manager, Domain Type in the Community Manager developer portal), that the action is restricted to. To include multiple values, you can either include multiple <DomainType> arguments or list multiple domain types on one line, separated by commas. Valid values: Directory Server (domain type for LDAP) CA SiteMinder (domain type for a CA SiteMinder domain) com.soa.securitydomain.pingfederate.provider (PingFederate domain) com.soa.securitydomain.fb.connector (Facebook Connector domain) com.soa.securitydomain.openidconnect.relyingparty (OpenID Connect Relying Party domain) com.soa.securitydomain.oauth.provider (OAuth Provider domain; not an identity store domain, but supports OAuth/OpenID for other domain users) com.soa.securitydomain.google.connector (Google Connector domain) (deprecated in version: 2020.1.0) SAML Web Browser SSO (SAML Web SSO SP domain)

Examples/Notes/Additional Information

In the example below, this condition specifies that only users on a directory server (LDAP) domain can perform the action.

<condition type="authorizeByDomainType">
  <arg name="DomainType">Directory Server</arg>
</condition>

authorizeByEmail

Tests to see if the email address of the workflow user matches one or more specified values; returns Boolean true or false.

This can be used as a security measure to limit platform actions to a specific set of authorized users. For example, actions can be limited to one specific email domain for security purposes.

Arguments

Name	Description/Values
email	One or more specific email address patterns. To include multiple values, you can either include multiple <email> arguments or list multiple values on one line, separated by commas.

Examples/Notes/Additional Information

In the example below, this condition specifies that only users with email addresses on the platform's domain, acmepaymentscorp.com, can perform the action.

<condition type="authorizeByEmail">
  <arg name="email">.*@acmepaymentscorp.com</arg>
</condition>

authorizeByGroupName

Tests to see if the workflow user is a member of one or more specified platform groups; returns Boolean true or false.

Arguments

Name	Description/Values
Domain	Optional: one or more domains that authorization is restricted to. Only needed if the group is not a group on the Community Manager developer portal; for example, a Policy Manager group. Defaults to Community Manager developer portal groups. To include multiple values, you can either include multiple <domain> arguments or list multiple domains on one line, separated by commas. Note: the value for this parameter should be the domain name used in Policy Manager for the applicable identity system. For Policy Manager groups, use Local Domain as the value.
group	One or more platform groups that authorization is restricted to. By default, a group name is interpreted to mean a platform group. To include multiple values, you can either include multiple <group> arguments or list multiple groups on one line, separated by commas.

Examples/Notes/Additional Information

Example 1: One condition

In the example below, this condition checks that the logged-in user is a member of the EngineeringGroup group on the ldap domain. If the user does not meet the condition, the workflow action the condition is associated with is not allowed.

<condition type="authorizeByGroupName">
  <arg name="group">EngineeringGroup</arg>
  <arg name="domain">ldap</arg>
</condition>

Example 2: Multiple conditions

In the example below, this condition specifies that in order to perform the workflow action, users must meet any one of the following sets of conditions:

• Be a member of one of these two Community Manager developer portal groups: CM_Group1 or CM_Group2
• Be a member of one of these two Policy Manager groups on the local domain: PM_Group1 or PM_Group2
• Be a member of one of these two groups on the LDAP domain: LDAP_Group1 or LDAP_Group2

<restrict-to>
  <conditions type="OR">
    <condition type="authorizeByGroupName">
      <arg name="group">CM_Group1, CM_Group2</arg>
    </condition>
    <condition type="authorizeByGroupName">
      <arg name="group">PM_Group1,PM_Group2</arg> 
      <arg name="domain">Local Domain</arg>
    </condition>
            <condition type="authorizeByGroupName">
      <arg name="group">LDAP_Group1,LDAP_Group2</arg>
      <arg name="domain">ldap</arg>
    </condition>
  </conditions>
</restrict-to>

authTokenPropertyExists

Checks to see if the specified property exists in the user's auth token cookie. Returns true if found.

Arguments

Name	Description/Values
PropertyName	The name of the auth token property being checked.
Message	A custom message designed by custom code or hardcoded into the workflow itself.

Examples/Notes/Additional Information

In the example below, two conditions are checked: first, is the session in login process (applicable when two-factor authentication is in effect and the user has already provided login credentials), and then, if the specific auth token property, 2FAData, is there.

<conditions type="AND">
  <condition type="isSessionInLoginProcess"/>
  <condition type="authTokenPropertyExists">
    <arg name="PropertyName">2FAData</arg>
    <arg name="message">2FA not initiated</arg>
  </condition>

authTokenPropertyMatches

Checks to see if the specified property in the user's auth token cookie matches the specified value. Returns true if so.

Arguments

Name	Description/Values
PropertyName	The name of the auth token property.
PropertyValue	The value of the auth token property being checked.

Examples/Notes/Additional Information

In the example below, the workflow checks if the auth token property is set to 2FAComplete indicating that the two-factor authentication process has completed successfully.

<condition negate="true" type="authTokenPropertyMatches">
  <arg name="PropertyName">2FAComplete</arg>
  <arg name="PropertyValue">Yes</arg>
</condition>

argumentExists

Checks to see if the specified argument exists. Returns true if so.

Arguments

Name	Description/Values
ArgName	The name of the argument.
Message	A message to be generated if the argument exists.

Examples/Notes/Additional Information

In the example below, the custom workflow checks to see if a specific argument exists and, if it does, generates a specific message. The workflow then checks for a different argument and generates a message for that.

<action id="499" name="@ResolveLoginPendingTask">
  <restrict-to>
    <conditions type="AND">
      <condition type="isSessionInLoginProcess"/>
      <condition type="authTokenPropertyExists">
        <arg name="PropertyName">2FAData</arg>
        <arg name="message">2FA not initiated</arg>
      </condition>
      <condition negate="true" type="authTokenPropertyMatches">
          <arg name="PropertyName">2FAComplete</arg>
          <arg name="PropertyValue">Yes</arg>
      </condition>
      <condition type="argumentExists">
        <arg name="ArgName">Action</arg>
        <arg name="message">Action is required</arg>
      </condition>
      <condition type="argumentExists">
        <arg name="ArgName">task.id</arg>
        <arg name="message">Task id is required</arg>
      </condition>
    </conditions>
  </restrict-to>

argumentValueEquals

Checks to see if a specific argument has a specific value. Further actions can then be taken based on the results.

Arguments

Name	Description/Values
ArgName	The name of the argument.
Value	The value of the argument.

Examples/Notes/Additional Information

In the example below, the argumentValueEquals condition is used to check if the value for Action is regenerate. If so (later part of the workflow not shown), the 2FA code is regenerated.

<conditions type="AND">
  <condition type="argumentValueEquals">
    <arg name="ArgName">Action</arg>
    <arg name="Value">regenerate</arg>
  </condition>

argumentValueMatches

Checks to see if a specific argument matches the specified regular expression. Further actions can then be taken based on the results.

Arguments

Property	Description/Values
ArgName	The name of the argument.
RegEx	The regular expression.

isSessionInLoginProcess

Checks that the session is not in a LoginComplete state; if the session is still in the login process, indicating that login is not complete, returns true.

Parameters

None.

Examples/Notes/Additional Information

In the example below, the workflow action is restricted to the conditions specified. The first condition is to check that the session is in the login process. If this condition is not met, the step is not continued.

<action id="449" name="@ResolveLoginPendingTask">
  <restrict-to>
    <conditions type="AND">
      <condition type="isSessionInLoginProcess"/>
      <condition type="authTokenPropertyExists">
        <arg name="PropertyName">2FAData</arg>
        <arg name="message">2FA not initiated</arg>
      </condition>
      <condition negate="true" type="authTokenPropertyMatches">
          <arg name="PropertyName">2FAComplete</arg>
          <arg name="PropertyValue">Yes</arg>
      </condition>

cookieExists

Checks whether the specified cookie exists. Returns true if so.

Arguments

Property	Description/Values
CookieName	The name of the cookie.

Examples/Notes/Additional Information

In the example below, the workflow action is restricted to the conditions specified. The first condition is to check that the cookie does not exist (negate-true on cookieExists). If the cookie does exist, the step is not continued.

<action id="401" name="@Login">
  <results>
    <result old-status="registered" status="registered" step="400">
      <conditions type="AND">
        <condition negate="true" type="cookieExists">
            <arg name="CookieName">D</arg>
        </condition>
        <condition negate="true" type="authTokenPropertyMatches">
            <arg name="PropertyName">2FAComplete</arg>
            <arg name="PropertyValue">Yes</arg>
        </condition>
        <condition negate="true" type="authTokenPropertyMatches">
            <arg name="PropertyName">2FASkipped</arg>
            <arg name="PropertyValue">Yes</arg>
        </condition>
        <condition negate="true" type="authTokenPropertyExists">
            <arg name="PropertyName">2FAData</arg>
        </condition>
      </conditions>

cookieValueEquals

Checks to see if the user's cookie equals the specified value. Returns true if so.

Arguments

Property	Description/Values
CookieName	The name of the cookie.
CookieValue	The value of the cookie.

cookieValueMatches

Checks to see if the user's cookie matches the specified regular expression. Returns true if so.

Arguments

Property	Description/Values
CookieName	The name of the cookie.
Expression	The regular expression

actionCommentMatchesRegEx

Checks to see that the comment that's entered when a workflow action is performed matches the specified regular expression. Returns true if so. If it doesn't match, this condition returns false, and the user is given a message that can prompt the user to enter a valid comment.

When checking for valid actions, when the comment doesn't exist, this condition returns true. However, when performing the action, when the comment exists and doesn't follow the proper format, the condition returns false and returns the specified message.

Parameters

Property	Description/Values
RegEx	The regular expression that the comment is tested against for a match.
FailedMatchMessage	The message that will be returned if the comment that's entered when a workflow action is performed doesn't match the specified regular expression.

Examples/Notes/Additional Information

In the example below, the actionCommentMatchesRegEx condition is used to ensure that when performing a workflow action, the user enters a specific comment that includes the Support Ticket information (RegEx argument). If no comment is entered, the message specified in the FailedMatchMessage argument is displayed to the user.

<conditions type="AND">
  <condition type="actionCommentExists">
    <arg name="CommentMissingMessage">Comment needed with Support Ticket ID</arg>
  </condition>
  <condition type="actionCommentMatchesRegEx">
    <arg name="RegEx">.*Support Ticket*</arg>
    <arg name="FailedMatchMessage">Comment does not include Support Ticket ID</arg>
  </condition>
</conditions>

actionCommentExists

Checks to see that a comment was entered when a workflow action is performed. Returns true if so.

Parameters

Property	Description/Values
CommentMissingMessage	The message that will be returned if a comment is not entered when a workflow action is performed.

Examples/Notes/Additional Information

<conditions type="AND">
  <condition type="actionCommentExists">
    <arg name="CommentMissingMessage">Comment needed with Support Ticket ID</arg>
  </condition>
  <condition type="actionCommentMatchesRegEx">
    <arg name="RegEx">.*KYC.*</arg>
    <arg name="FailedMatchMessage">Comment does not include Support Ticket ID</arg>
  </condition>
</conditions>

General Use: Variable Resolvers

The following variable resolvers are available for all workflows in the Akana API Platform:

• ${workflow.step.name}
• ${workflow.step.id}

${workflow.step.name}

The name for a specific workflow step, as a string in the format =${workflow.step.name}. Allows the workflow to dynamically reference another workflow step, by step name, as shown in the example below.

<result old-status="${workflow.step.name}" status="${workflow.step.name}" step="-1">
  <conditions type="AND">
    <condition type="isLastLoginEmpty"/>
    <condition type="class">
      <arg name="class.name">com.opensymphony.workflow.util.StatusCondition</arg>
      <arg name="status">managed</arg>
    </condition>
  </conditions>
  <post-functions>
    <function type="markUserPermanent"/>
    <function type="addBoardItem">
      <arg name="boardItemTemplateId">com.soa.board.item.user.logged.in.first.time</arg>
      <arg name="visibility">Limited</arg>
      <arg name="type">Discussion</arg>
      <arg name="author">${site.admin.dn}</arg>
      <arg name="targetBoard.apiversion">${connected.apiversion.ids}</arg>
      <arg name="targetBoard.api">${connected.apis.id}</arg>
      <arg name="viewers">${connected.apis.id},${business.dn},${site.admin.dn}</arg>
    </function>
    <function type="sendNotification">
      <arg name="role">ApiAdmins,SiteAdmin,BusinessAdmin</arg>
      <arg name="notificationType">com.soa.notification.type.user.logged.in.first.time</arg>
    </function>
    <function type="markLoginComplete"/>
  </post-functions>
</result>

${workflow.step.id}

The name for a specific workflow step, as a string in the format =${workflow.step.id}. Allows the workflow to dynamically reference another workflow step, by step ID.

Related Topics