Update Activity REST API

The Update Activity REST API is used to approve or reject the currently active Approval task in a specified activity. When IBM PEM is integrated with other components and external systems, the API is used to auto-update the status of configuration requests between PEM Partner Repository and PEM Partner Provisioner.

The API is called by PEM Partner Repository when it receives a provisioning response from PEM Partner Provisioner. For example, PEM Partner Repository sends a provisioning request to PEM Partner Provisioner. If PEM Partner Repository sends a favorable response to PEM Partner Repository, the Update Activity API auto-approves the approval task in the provisioning activity and updates the status of the configuration. Likewise, PEM Partner Repository rejects the approval task when PEM Partner Provisioner sends an error response and reopens tasks in the activity to start them by the partner.

The Update Activity API is called if there is a failure provisioning to Production. PEM Partner Repository uses the Update Activity API to unblock the activity if the provisioning is successful, and reopens all tasks (up to a specified task) if the provisioning fails.

If an activity is in Sponsor Action status, the Update Activity API can reopen the tasks in the activity by rejecting it. When PEM Partner Repository rejects the activity, it sends as rejection comments the error message it received from PEM Partner Provisioner.

Keys

The following keys are available for mapping:
  • Partner Key
  • Participant Activity Key

The Participant Activity key is found in the mapping tree under ActivityContext, as the element named PartnerActivitykey.

Activity designers can map the participant activity key for an activity that is processed by the partner to one of the elements in the request data for a Create Configuration PEM Partner Repository API.

The following keys should be available in a dialog designer mapping tree so that activity designers are able to map the keys to the request data in one of the PEM Partner Repository CREATE configurations:

URL for access

The following URL pattern is used to access the Update Activity REST API:

https://PEMinstanceIP:Port/mrmws/sponsors/<sponsor-context>/partners/<partnerKey>/activities/<participantActivityKey>
Where:
  • <sponsor-context> is the sponsor context URI (short name to identify the company)
  • <partnerKey> is the Partner Key
  • <participantActivityKey> is the Participant Activity Key
Note: The URL can be different based on your deployment option. For more details about the URL, see URL for accessing IBM PEM and APIs.

Input

This API takes the following parameters as input:
  • Sponsor Context
  • Partner Key
  • Participant Activity Key
  • Approve or Reject action
  • Approval or Rejection Comments

Headers

The headers for the API are as follows:
Content-Type: application/xml
Authorization: [Basic Auth data]

Request data

The request data for the API is as follows: 
<update action="APPROVE | REJECT" comments="approving or rejecting task"/>

Sample response data

A sample response pattern is:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><success response="Approved the approval task successfully!"/>

Error response data

The error response data for the API is similar to the following example: 
<error code="400 | ..." description="error text"/>
The API returns an error unless the following conditions are satisfied:
  • A partner exists with the specified Partner Key
  • A participant activity instance exists with the specified Participant Activity Key.
  • The partner activity is in Sponsor Action status.
  • The current task is in Sponsor Action status and is an Approval Task.

The system saves the error message, if the REST API invocation fails, and sends it as part of the Provisioning Response to PEM Partner Repository that includes this error message in the comments for rejecting the activity task.

Processing

When all the validation checks are passed, the API sets the comments and status of the current approval task in the activity according to the specified input. Thereafter, the REST API behavior is the same as if the task was approved or rejected through the user interface.

If exit conditions are defined on the approval task, the conditions are also evaluated. If the exit conditions are not satisfied, the API returns with an error.

Any system tasks run immediately after the approval task. The API returns with success even a system task fails with an error. If the activity is in Not Started status and the first task is an Approval Task, the API returns with an error.

If the approval task processing was restricted to a specific role by the Activity Designer, the sponsor user who is authenticated in the API must have the same assigned role.

The REST API is protected with Basic Authentication.

PEM Partner Provisioner system properties

The following PEM Partner Provisioner system properties store information for the integration with IBM PEM:
  • PEM_REST_URL (for example, https://<ip>:port/mrmws/sponsors/<sponsor-context>)
    Note: The URL can be different based on your deployment option. For more details about the URL, see URL for accessing IBM PEM and APIs.
  • PEM_INTEGRATION_ENABLED; If this property is set to true, PEM Partner Repository invokes the Update Activity API when updating a configuration to a Success or Failure status.

Scenarios

The following table shows the input to the Update Activity REST API for various provisioning scenarios:
Scenario Input to Update Activity API is:
Provisioning to Test environment Success Action=APPROVE, Comment=Provision to Test environment completed successfully
Provisioning to Production environment Success Action=APPROVE, Comment=Provision to Production environment completed successfully
Testing of Test environment Success Action=APPROVE, Comment=Testing of Test environment completed successfully
Testing of Test environment Failure Action=REJECT, Comment=<error message returned by the application's API>