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

  1. API Contract Workflow: Initial Actions
  2. API Contract Workflow: Reserved Actions
  3. API Contract Workflow: Functions
  4. API Contract Workflow: Conditions
  5. 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

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.

Back to top

API Contract Workflow: Reserved Actions

The following reserved actions are defined for API contract workflows:

@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.

Back to top

API Contract Workflow: Functions

The following functions are available for the API contract workflow:

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.

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.

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>

Back to top

API Contract Workflow: Conditions

The following conditions apply to the API contract workflow:

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.

Back to top

API Contract Workflow: Variable Resolvers

The following variables are available for the API contract workflow:

${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.

Back to top