API Contract Workflow

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

Table of Contents

• API Contract Workflow: Initial Actions
• API Contract Workflow: Reserved Actions
• API Contract Workflow: Functions
• API Contract Workflow: Conditions
• API Contract Workflow: Variable Resolvers

API Contract Workflow: Initial Actions

The initial actions valid for Akana API Platform workflows relating to API contracts are:

• @Create
• @Revise
• @ImportContract
• @AutoConnectActivate

@Create

When a completely new contract is created (the first contract between a specific app version and a specific API version in a specific environment), the @Create initial action is used to start the workflow for the new contract.

For more information, see Workflow Initial Actions.

@Revise

When an existing contract is revised, a new contract is created that is a revision of the existing contract, and the existing contract remains in place. In this scenario, the @Revise initial action is used to start the workflow for the revised contract. When there is a revised contract in place, any subsequent requests to create a contract for the app/API/environment combination will fail, since only one revised contract is allowed at one time.

@ImportContract

Used to start the workflow for an imported contract.

@AutoConnectActivate

Used to start the workflow for a new contract that's created as a result of an AutoConnect setting.

API Contract Workflow: Reserved Actions

The following reserved actions are defined for API contract workflows:

• @app_switch_to_production
• @AppDeleted
• @ApiDeleted
• @modify
• @Revise
• reserved-connect-from-app.Sandbox
• reserved-connect-from-app.Production

@app_switch_to_production

Used to control workflow actions that occur when an app is switched to Live.

@AppDeleted

Used to control workflow actions that occur when an app is deleted.

@ApiDeleted

Used to control workflow actions that occur when an API is deleted.

@modify

Used to control workflow actions that occur when an app is modified.

@Revise

Used to control workflow actions that occur when an app is revised.

reserved-connect-from-app.Sandbox

Used to control workflow actions that occur when an app connects to an API in the Sandbox environment.

reserved-connect-from-app.Production

Used to control workflow actions that occur when an app connects to an API in the Live environment.

API Contract Workflow: Functions

The following functions are available for the API contract workflow:

• updateAPIContractStatus
• sendNotification
• synchronizeAppVersion
• invokeAppVersionAction
• invokeApiVersionAction
• updateContractActiveStatus
• syncConnectedAppVersionsInOAuthProvider
• verifyAppAccessLimitedToOnlySandboxOrLiveAPIs

updateAPIContractStatus

Updates the status of an API contract. The new status must be a valid transition from the current status.

Parameters

Name	Description/Values
Status	Updates the status of the connection to a new status. Valid values: apicontract.status.approved apicontract.status.pending_approval apicontract.status.config_pending apicontract.status.rejected apicontract.status.resubmitted apicontract.status.activated apicontract.status.cancelled apicontract.status.suspended

Examples/Notes/Additional Information

The example below shows the workflow when requests for API access in the Live environment are auto-approved. The updateAPIContractStatus function is used to update the status.

<action id="102" name="Auto-Approve Production Requests From Production App" auto="TRUE">
  <restrict-to>
    <conditions type="AND">
      <condition type="isAtmosphereProductionApiContract" />
      <condition type="isAtmosphereProductionAutoApprove" />
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="Pending" status="Activated" step="600" owner="${caller}"/>
  </results>
  <post-functions>
    <function type="updateAPIContractStatus">
      <arg name="status">apicontract.status.activated</arg>
    </function>
    <function type="sendNotification">
      <arg name="notificationType">com.soa.notification.type.api.access.requested.both.apiadmin</arg>
      <arg name="role">ApiAdmin</arg>
      <arg name="status">apicontract.status.activated</arg>
    </function>
    <function type="sendNotification">
      <arg name="notificationType">com.soa.notification.type.api.access.requested.production.appteam</arg>
      <arg name="role">AppAdmin</arg>
      <arg name="status">apicontract.status.activated</arg>
    </function>
  </post-functions>
</action>

sendNotification

Triggers the specified notification based on an event relating to an API contract.

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

Note: In some cases, some additional parameters are specific to individual notifications. For example, param.contract.oldstate is specific to a notification that identifies a change of state for a contract. Notification-specific parameters begin with "param." as in this example.

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.api.access.requested.both.apiadmin com.soa.notification.type.api.access.requested.sandbox.appteam com.soa.notification.type.privateapi.membership.status.changed com.soa.notification.type.group.membership.role.changed com.soa.notification.type.appteam.member.invited.team Note: if either the notificationType.production or notificationType.sandbox argument is provided, it is used to load the message template. If not, the notificationType argument is used to load the message template.
notificationType.production	If the connection is for the Live environment, the notificationType.production argument is used to load the message template. If this argument is not provided, the notificationType argument is used for loading the message template.
notificationType.sandbox	If the connection is for the sandbox environment, the notificationType.sandbox argument is used to load the message template. If this argument is not provided, the notificationType argument is used for loading the message template.
Role	The role to which the notifications will be sent; only users who hold this role for the specified API contract. Valid values: ApiAdmin AppAdmin
Any parameter with name prefixed with "param"	Some specific notifications have additional parameters. These parameters always begin with "param". For example, ${contract.oldstate} is used in some cases to indicate the old state of the API contract, in scenarios where the state has changed.

Examples/Notes/Additional Information

In the example below, two notifications are sent when an API access request is auto-approved. Each notification goes to a different group of users as specified in the role argument.

<post-functions>
  <function type="autoApproveAccessRequest">
    <arg name="status">apicontract.status.activated</arg>
  </function>
  <function type="sendNotification">
     <arg name="notificationType">com.soa.notification.type.api.access.requested.both.apiadmin</arg>
     <arg name="role">ApiAdmin</arg>
  </function>
  <function type="sendNotification">
      <arg name="notificationType">com.soa.notification.type.api.access.requested.sandbox.appteam</arg>
      <arg name="role">AppAdmin</arg>
  </function>
</post-functions>

synchronizeAppVersion

If the app version for which the connection is set up is a remote federation member app, this function synchronizes the app identity with its system of record (home instance record). This ensures that the app identity information is up to date for the local tenant.

Parameters

None.

Examples/Notes/Additional Information

In the example below, the app version is synchronized as a last action, after the main function, to make sure the data is up to date before moving on to the next step in the workflow.

<action id="311" name="apicontract.action.sync.app.version">
  <restrict-to>
    <conditions type="AND">
      <condition type="authorizeByAtmosphereRole">
        <arg name="role">ApiAdmin</arg>
      </condition>
      <condition type="isRemoteFedMemberApp"/>
    </conditions>
  </restrict-to>
  <results>
    <unconditional-result old-status="Pending Approval" status="Pending Approval" step="-1"/>
  </results>
  <post-functions>
    <function type="synchronizeAppVersion"/>
  </post-functions>
</action>

invokeAppVersionAction

Invokes the workflow action specified on the app version workflow.

Note: This function is not part of the default contract workflow. It's a custom function that you can use to modify the default behavior in the Community Manager developer portal. For information about using custom workflows, see Custom Workflows in the Community Manager developer portal.

By default, the workflow action is invoked on the app version associated with the connection unless the AppVersionDN argument is provided.

If the AppVersionDN argument is provided, the action is executed on the specified app version.

Parameters

Name	Description/Values
AppVersionDN (optional)	A specified app version the workflow action will be invoked on. If this parameter is not included, the workflow action is invoked on the app version associated with the connection.
ActionName	The workflow action to be invoked.

invokeApiVersionAction

Invokes the workflow action specified on the API version workflow.

Note: This function is not part of the default contract workflow. It's a custom function that you can use to modify the default behavior in the Community Manager developer portal. For information about using custom workflows, see Custom Workflows in the Community Manager developer portal.

By default, the workflow action is invoked on the API version associated with the connection unless the ApiVersionDN argument is provided.

If the ApiVersionDN argument is provided, the action is executed on the specified API version.

Parameters

Name	Description/Values
ApiVersionDN (optional)	A specified API version the workflow action will be invoked on. If this parameter is not included, the workflow action is invoked on the API version associated with the connection.
ActionName	The workflow action to be invoked.

updateContractActiveStatus

Updates the status of an active contract. The new status must be a valid transition from the current status.

Parameters

Name

Description/Values

status

The new status for the contract. Possible values: com.soa.apicontract.inforce: used when the contract is activated. Indicates that the contract is currently in use when the app is invoking the API calls. com.soa.apicontract.archived: used when the contract is cancelled or the app or API version is deleted. Indicates that the contract was in use but is no longer in use. com.soa.apicontract.draft: used when the contract hasn't yet reached the state in which it can be used in runtime requests; for example, pending acceptance.

Examples/Notes/Additional Information

In the example below, the API contract active status is updated to a status of com.soa.apicontract.inforce after the contract is activated.

<action id="2" name="@AutoConnectActivate">
  <results>
    <unconditional-result old-status="Received" status="Activated" step="600" owner="${caller}"/>
  </results>
  <post-functions>
      <function type="updateAPIContractStatus">
        <arg name="status">apicontract.status.activated</arg>
      </function>
      <function type="updateContractActiveStatus">
        <arg name="status">com.soa.apicontract.inforce</arg>
      </function>
      <function type="addAPIContractToHistory"/>
      <function type="sendNotification">
        <arg name="notificationType">com.soa.notification.type.api.access.state.change.apiadmin</arg>
        <arg name="role">ApiAdmin</arg>
        <arg name="param.contract.oldstate">apicontract.status.pending_approval</arg>
      </function>
      <function type="sendNotification">
        <arg name="notificationType">com.soa.notification.type.api.access.activated.production.appteam</arg>
        <arg name="role">AppAdmin</arg>
        <arg name="param.contract.oldstate">${contract.oldstate}</arg>
      </function>
  </post-functions>
</action>

syncConnectedAppVersionsInOAuthProvider

For an app that is contracted with an API, this function takes the App ID and Shared Secret and adds them to the app provisioning table. These values are then picked up by a scheduled job, which runs every 10 minutes (not configurable). The scheduled job synchronizes the values via the Client Registration endpoint, so that client registration stays current.

Certain workflow actions would typically trigger this function in the API Contract workflow, as listed for the Action parameter. For example, a new app version or updated description would trigger this function to make sure that client registration stays current. See examples below.

Parameters

Name	Description/Values
Action	The specific workflow action. Valid values: @ApiDeleted @AppDeleted @AutoConnectActivate @ImportContract apicontract.action.activate apicontract.action.approve Auto-Approve Production Requests From Sandbox auto-approve sandbox requests

Examples/Notes/Additional Information

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

@ApiDeleted:

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

@AppDeleted:

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

@AutoConnectActivate:

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

@ImportContract:

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

apicontract.action.activate:

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

apicontract.action.approve:

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

Auto-Approve Production Requests From Sandbox:

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

auto-approve sandbox requests:

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

verifyAppAccessLimitedToOnlySandboxOrLiveAPIs

Note: This function is not part of the default contract workflow. It's a custom function that you can use to modify the default behavior in the Community Manager developer portal. For information about using custom workflows, see Custom Workflows in the Community Manager developer portal.

For information about setting up a custom workflow in the Community Manager developer portal, see How do I set up and manage custom workflows?

By default, an app version can request a contract with an API in any API environments that are available.

If you want to implement custom behavior so that an app version can only have contracts in one environment, you can use this function. If you add this function into your contract workflow, and then assign the revised workflow as your default, when an app requests a contract with an API in a specific environment (Sandbox or Live), the function checks that the app doesn't already have one or more contracts in a different environment. With this function in place, one app version can have contracts in the Sandbox environment, or in the Live environment, but not both.

Note: The limitation to only allow access in one environment is applied at the app version level, not the app level.

If custom workflow is implemented that includes this function, existing app versions that already have contracts in both environments are not affected.

Parameters

None.

Examples/Notes/Additional Information

An example of one instance of where this function is added into the Contracts workflow is shown below (line 11). In this example, the check is done in a scenario where a manual approval is needed for a Sandbox API, which is controlled by platform API configuration settings. In this scenario, when a contract is requested with an API in the Sandbox environment and manual approval is needed, the function would check that the app version making the request doesn't already have a contract with any API in the Live environment. If you're modifying the workflow, you would need to add the function in as many parts of the workflow as needed to make sure that you get the expected results.

01 <action id="104" name="Manual Approval Needed for Production API" auto="TRUE">
02   <restrict-to>
03     <conditions type="AND">
04       <condition type="isAtmosphereProductionApiContract" />
05     </conditions>
06   </restrict-to>
07    <results>
08     <unconditional-result old-status="Pending" status="Pending Approval" step="300" owner="${caller}"/>
09   </results>
10   <post-functions>
11     <function type="verifyAppAccessLimitedToOnlySandboxOrLiveAPIs" />
12     
13     <function type="updateAPIContractStatus">
14       <arg name="status">&AtmoContractStatusPendingApproval;</arg>
15     </function>
16     <function type="sendNotification">
17         <arg name="notificationType">com.soa.notification.type.api.access.requested.both.apiadmin</arg>
18         <arg name="role">ApiAdmin</arg>
19       <arg name="status">&AtmoContractStatusPendingApproval;</arg>
20     </function>
21     <function type="sendNotification">
22       <arg name="notificationType">com.soa.notification.type.api.access.requested.production.appteam</arg>
23       <arg name="role">AppAdmin</arg>
24       <arg name="status">&AtmoContractStatusPendingApproval;</arg>
25     </function>
26   </post-functions>
27 </action>

API Contract Workflow: Conditions

The following conditions apply to the API contract workflow:

• isAtmosphereApiContract
• isAtmosphereSandboxApiContract
• isAtmosphereProductionApiContract
• isAtmosphereSandboxAutoApprove
• isAtmosphereProductionAutoApprove
• isRemoteFedMemberApp
• apiContractUsesRestrictedScope
• apiVersionSupportsResourceLevelPermissions
• isAPIContractScopeNotEmpty
• checkAppVersionStateMatches
• checkAppVersionFedMemberMatches

isAtmosphereApiContract

Returns true if used in the API contract workflow.

Parameters

None.

isAtmosphereSandboxApiContract

Returns true if the API contract is for the Sandbox environment.

Parameters

None.

isAtmosphereProductionApiContract

Returns true if the API contract is for the Live environment.

Parameters

None.

isAtmosphereSandboxAutoApprove

Returns true if the API contract is with an API version that has connections to the sandbox environment set up to be auto-approved.

Parameters

None.

isAtmosphereProductionAutoApprove

Returns true if the API contract is with an API version that has connections to the Live environment set up to be auto-approved.

Parameters

None.

isRemoteFedMemberApp

Returns true if the API contract is with an app that belongs to a federation member and the federation member is not in the same deployment.

Parameters

None.

apiContractUsesRestrictedScope

Returns true if the API contract is not unrestricted (restricted to one or more licenses/scopes). If the API contract is unrestricted, with full access to the API version, this condition returns false.

Parameters

None.

apiVersionSupportsResourceLevelPermissions

Returns true if the API contract is with an API version that supports resource-level permissions.

Parameters

None.

isAPIContractScopeNotEmpty

Tests to make sure that the contract gives the app access to at least one operation in the API; returns true if the contract doesn't give access to any operations in the app.

Tests whether the API contract is restricted AND either of the following is true:

The API contract does not include any licenses in the scope.

The aggregate of all licenses does not give it access to any of the operations based on how scope mapping is configured (mapping of License > Scope and mapping of Operation > Scope).

Parameters

None.

checkAppVersionStateMatches

Returns true if the app version state is one of the states specified in the State parameter.

Parameters

Name	Description/Values
AppVersionDN (optional)	A specified app version. If AppVersionDN is not defined, it will be the AppVersionID that the API contract is for.
State	A comma-separate list of State values.

checkAppVersionFedMemberMatches

Returns true if the app version belongs to one of the federation members specified.

Parameters

Name	Description/Values
AppVersionDN (optional)	A specified app version. If AppVersionDN is not defined, it will be the AppVersionID that the API contract is for.
FedMemberID	A comma-separated list of federation members.

API Contract Workflow: Variable Resolvers

The following variables are available for the API contract workflow:

• ${contract.api.dn}
• ${contract.api.version.dn}
• ${contract.app.dn}
• ${contract.app.version.dn}
• ${contract.dn}
• ${contract.state}
• ${contract.old.state}

${contract.api.dn}

The API ID for the API version that the contract applies to. Note this is the API ID, not the API Version ID.

${contract.api.version.dn}

The APIVersionID of the API version that the connection is for.

${contract.app.dn}

The AppID of the app version that the connection is for.

${contract.app.version.dn}

The AppVersionID of the app version that the connection is for.

${contract.dn}

The APIContractID of the contract.

${contract.state}

Returns the current state of the API contract.

Note: there are two sets of values relating to contracts; contract state and contract status. Contract state indicates what point in the contract lifecycle the contract is currently in; for example, pending approval, approved, activated. Contract status indicates whether the contract is active, not yet active, or archived, and determines which workflow actions are valid for the contract.

${contract.old.state}

When using the updateContractStatus function, the contract.old.state variable will be set for the subsequent functions/actions to use.

Related Topics