Documentation for a newer release is available. View Latest

Approvals

This feature allows users to ask for approval before the change is applied to a setting. The change itself can be one of the following:

  • create (i.e. creating a setting with approval requires the approval to be accepted before the setting is actually created)

  • update (i.e. updating an existing setting with approval requires approval to be accepted before the update is applied to the setting)

  • delete (i.e. deleting a setting with approval means that setting will not be deleted until someone approves this change)

API allows to retrieve all pending approvals. Approvals response contains all setting information.

Create Approval

When a user tries to create, update or delete a setting with requiresApproval parameter set to true, an approval request is created.

API Response

The following example shows how Approvals API response looks like for create approval:

{
  "settings" : [ {
    "logicalUniqueKey" : "001-BIC01112XXX", (1)
    "source" : "manual", (2)
    "processingEntity" : "001", (3)
    "activeFromDate" : "2023-01-01T10:00:00.000Z", (4)
    "activeToDate" : "2023-10-01T10:00:00.000Z", (5)
    "status" : "PENDING", (6)
    "version" : 1, (7)
    "payload" : { (8)
      "className" : "com.iconsolutions.ipf.dynamicsettings.v2.bdd.model.DpsSampleSetting",
      "routingBic" : "BIC01112XXX",
      "maxCounter" : 35,
      "maxValue" : 62.25,
      "amount" : 125.123456789,
      "enabled" : true,
      "creationDate" : "2023-06-30T12:00:00.000Z",
      "participantType" : "DIRECT",
      "countryCurrency" : {
        "country" : "GB",
        "currency" : "EUR"
      }
    },
    "createdBy" : "user-01", (9)
    "approvalType" : "CREATE", (10)
    "recordType" : "DpsSampleSetting", (11)
    "createdDate" : "2024-09-07T17:16:46.434Z", (12)
    "diff" : [ ] (13)
  } ]
}
1 logicalUniqueKey - A logical unique key that represents a specific setting within a collection of settings.
2 source - Specifies the origin of the ingested data. Typically, manual indicates data ingestion via direct API invocation, while import signifies ingestion through a file-based process.
3 processingEntity - Identifies the processing entities to which the setting applies. A setting can be associated with multiple processing entities.
4 activeFromDate - Specifies the date and time of when the setting becomes active, after it is approved.
5 activeToDate - Specifies the date and time when the setting is going to be considered inactive, after it is approved.
6 status - Represents the approval status of the setting. For pending approvals, this value is always PENDING. The Approvals API currently supports only fetching pending approvals, so this is the only status available in API responses.
7 version - Indicates the version of the setting. Versioning starts at 1 when the setting is created and increments by 1 with each subsequent change.
8 payload - Contains the actual setting content. Once an approval is granted, this setting applies to its respective collection.
9 createdBy - Specifies the user who creates the setting.
10 approvalType - Defines the type of approval request. Possible values include:

  • CREATE: A request to create a new setting.

  • UPDATE: A request to modify an existing setting.

  • DELETE: A request to remove a setting.
11 recordType - Defines the type of data contained in the payload.
12 createdDate - Specifies the date and time when the approval request is created.
13 diff - Available only for update approvals. It provides a comparison of changes between versions. This field is not present for create or delete approvals

Update Approval

The following example shows how Approvals API response looks like for update approval:

{
  "settings" : [ {
    "logicalUniqueKey" : "001-BIC01112XXX", (1)
    "source" : "manual", (2)
    "processingEntity" : "001", (3)
    "activeFromDate" : "2023-02-01T10:00:00.000Z", <4>,
    "activeToDate" : "2023-10-01T10:00:00.000Z", (5)
    "status" : "PENDING", (6)
    "version" : 1, (7)
    "payload" : { (8)
      "className" : "com.iconsolutions.ipf.dynamicsettings.v2.bdd.model.DpsSampleSetting",
      "routingBic" : "BIC01112XXX",
      "maxCounter" : 36,
      "maxValue" : 63.36,
      "amount" : 126.987654321,
      "enabled" : false,
      "creationDate" : "2023-07-15T14:15:00.000Z",
      "participantType" : "INDIRECT",
      "countryCurrency" : {
        "country" : "RS",
        "currency" : "RSD"
      }
    },
    "createdBy" : "JRGC6", (9)
    "approvalType" : "UPDATE", (10)
    "recordType" : "DpsSampleSetting", (11)
    "createdDate" : "2024-09-07T17:16:49.596Z", (12)
    "diff" : [ { (13)
      "fieldName" : "amount",
      "currentValue" : "125.123456789",
      "futureValue" : "126.987654321"
    }, {
      "fieldName" : "countryCurrency.country",
      "currentValue" : "GB",
      "futureValue" : "RS"
    }, {
      "fieldName" : "countryCurrency.currency",
      "currentValue" : "EUR",
      "futureValue" : "RSD"
    }, {
      "fieldName" : "creationDate",
      "currentValue" : "2023-06-30T12:00:00Z",
      "futureValue" : "2023-07-15T14:15:00Z"
    }, {
      "fieldName" : "enabled",
      "currentValue" : "true",
      "futureValue" : "false"
    }, {
      "fieldName" : "maxCounter",
      "currentValue" : "35",
      "futureValue" : "36"
    }, {
      "fieldName" : "maxValue",
      "currentValue" : "62.25",
      "futureValue" : "63.36"
    }, {
      "fieldName" : "participantType",
      "currentValue" : "DIRECT",
      "futureValue" : "INDIRECT"
    } ]
  } ]
}
1 logicalUniqueKey - A logical unique key that represents a specific setting within a collection of settings.
2 source - Specifies the origin of the ingested data. Typically, manual indicates data ingestion via direct API invocation, while import signifies ingestion through a file-based process.
3 processingEntity - Identifies the processing entities to which the setting applies. A setting can be associated with multiple processing entities.
4 activeFromDate - Specifies the date and time of when the setting becomes active, after it is approved.
5 activeToDate - Specifies the date and time when the setting is going to be considered inactive, after it is approved.
6 status - Represents the approval status of the setting. For pending approvals, this value is always PENDING. The Approvals API currently supports only fetching pending approvals, so this is the only status available in API responses.
7 version - Indicates the version of the setting. Versioning starts at 1 when the setting is created and increments by 1 with each subsequent change.
8 payload - Contains the actual setting content. Once an approval is granted, this setting applies to its respective collection.
9 createdBy - Specifies the user who creates the setting.
10 approvalType - Defines the type of approval request. Possible values include:

  • CREATE: A request to create a new setting.

  • UPDATE: A request to modify an existing setting.

  • DELETE: A request to remove a setting.
11 recordType - Defines the type of data contained in the payload.
12 createdDate - Specifies the date and time when the approval request is created.
13 diff - Available only for update approvals. It provides a comparison of changes between versions. This field is not present for create or delete approvals

Setting diff in update approval

Approval difference is only populated for update requests that require approval, and not create and delete operations.

For each field that is updated, diff collection will contain fieldName, currentValue and futureValue.

Approval diff example response:

{
   "settings":[
      {
         "logicalUniqueKey":"001-BIC01112XXX",
         "source":"manual",
         "processingEntity":"001",
         "activeFromDate":"2023-02-01T10:00:00Z",
         "activeToDate":"2027-02-01T10:00:00Z",
         "status":"ACTIVE_APPROVAL_PENDING",
         "version":1,
         "payload":{
            "className":"com.iconsolutions.ipf.dynamicsettings.v2.bdd.model.DpsSampleSetting",
            "routingBic":"BIC01112XXX",
            "maxCounter":36,
            "maxValue":63.36,
            "amount":126.987654321,
            "enabled":false,
            "creationDate":"2023-07-15T14:15:00Z",
            "participantType":"DIRECT",
            "countryCurrency":{
               "country":"RS",
               "currency":"RSD"
            }
         },
         "createdBy":"admin",
         "createdDate":"2024-10-10T11:38:57.062Z",
         "approvalType":"UPDATE",
         "diff":[
              {
                "fieldName": "maxCounter",
                "currentValue": "35",
                "futureValue": "36"
              },
              {
                "fieldName": "participantType",
                "currentValue": "INDIRECT",
                "futureValue": "DIRECT"
              }
         ]
      }
   ]
}

It is possible to remove field value, by setting it to null, which will be represented in diff collection as:

{
  "diff": [
    {
      "fieldName": "maxCounter",
      "currentValue": "35",
      "futureValue": null
    }
  ]
}

Delete Approval

The following example shows how Approvals API response looks like for delete approval:

"settings" : [ {
"logicalUniqueKey" : "001-BIC01112XXX", (1)
"source" : "manual", (2)
"processingEntity" : "001", (3)
"activeFromDate" : "2023-01-01T10:00:00.000Z", (4)
"activeToDate" : "2023-10-01T10:00:00.000Z", (5)
"status" : "PENDING", (6)
"version" : 1, (7)
"payload" : { (8)
"className" : "com.iconsolutions.ipf.dynamicsettings.v2.bdd.model.DpsSampleSetting",
"routingBic" : "BIC01112XXX",
"maxCounter" : 35,
"maxValue" : 62.25,
"amount" : 125.123456789,
"enabled" : true,
"creationDate" : "2023-06-30T12:00:00.000Z",
"participantType" : "DIRECT",
"countryCurrency" : {
"country" : "GB",
"currency" : "EUR"
}
},
"createdBy" : "user-01", (9)
"approvalType" : "DELETE", (10)
"recordType" : "DpsSampleSetting", (11)
"createdDate" : "2024-09-07T17:16:46.434Z", (12)
"deletedBy": "user-02", (13)
"deletedReason": "not needed" (14)
"diff" : [ ] (15)
} ]
}
1 logicalUniqueKey - A logical unique key that represents a specific setting within a collection of settings.
2 source - Specifies the origin of the ingested data. Typically, manual indicates data ingestion via direct API invocation, while import signifies ingestion through a file-based process.
3 processingEntity - Identifies the processing entities to which the setting applies. A setting can be associated with multiple processing entities.
4 activeFromDate - Specifies the date and time when the setting becomes active.
5 activeToDate - Specifies the date and time when the setting is going to be considered inactive, after it is approved.
6 status - Represents the approval status of the setting. For pending approvals, this value is always PENDING. The Approvals API currently supports only fetching pending approvals, so this is the only status available in API responses.
7 version - Indicates the version of the setting. Versioning starts at 1 when the setting is created and increments by 1 with each subsequent change.
8 payload - Contains the actual setting content. Once an approval is granted, this setting applies to its respective collection.
9 createdBy - Specifies the user who creates the setting.
10 approvalType - Defines the type of approval request. Possible values include:

  • CREATE: A request to create a new setting.

  • UPDATE: A request to modify an existing setting.

  • DELETE: A request to remove a setting.
11 recordType - Defines the type of data contained in the payload.
12 createdDate - Specifies the date and time when the approval request is created.
13 deletedBy - (Optional) Specifies the user who requests the deletion of the setting, applicable only in delete requests.
14 deletedReason - (Optional) Specifies the reason provided for the deletion request.
15 diff - Available only for update approvals. It provides a comparison of changes between versions. This field is not present for create or delete approvals.

Approval Constraints

There are several constrains on approvals:

  1. Only one approval per setting can be active at the time.

  2. Once approval is requested, it can’t be updated until first is either accepted or rejected.

  3. When there is a pending approval for some setting, the setting can’t be updated until the approval is either accepted or rejected.

If any of these constrains are not honored, the API will return the following error:

HTTP Status code Message Description

400

Update setting not allowed

Setting has pending approval.

Get approvals

When a user wants to get all pending approvals, GET /settings-objects/approvals/{settingType} endpoint offers that. Other than path parameter settingType, there is an optional parameter processingEntity that can be used to filter approvals by processing entity value combined with setting type value.

{
   "settings":[
      {
         "logicalUniqueKey":"001-BIC01112XXX",
         "source":"manual",
         "processingEntity":"001",
         "activeFromDate":"2023-01-01T10:00:00Z",
         "activeToDate":"2027-01-01T10:00:00Z",
         "status":"PENDING",
         "version":1,
         "payload":{
            "className":"com.iconsolutions.ipf.dynamicsettings.v2.bdd.model.DpsSampleSetting",
            "routingBic":"BIC01112XXX",
            "maxCounter":35,
            "maxValue":62.25,
            "amount":125.123456789,
            "enabled":true,
            "creationDate":"2023-06-30T12:00:00Z",
            "participantType":"DIRECT",
            "countryCurrency":{
               "country":"GB",
               "currency":"EUR"
            }
         },
         "createdBy":"user-01",
         "createdDate":"2024-10-10T11:38:57.062Z",
         "approvalType":"CREATE",
         "diff":[

         ]
      }
   ]
}

Approve/Reject an Approval

Approve

When a user wants to approve a setting creation, update or deletion, there is the POST /settings-objects/approvals/{settingType}/{settingId}/approve endpoint. The creator of the setting cannot also be the approver.

Here’s an example of the request body for the Approve setting request:

{
  "approvedBy": "approved-by",
  "approvedReason": "approved-reason"
}

The response should be status 200 OK with no response body.

Reject

For rejecting a setting creation, update or deletion, there is the POST /settings-objects/approvals/{settingType}/{settingId}/reject endpoint. The creator of the setting can reject their own request.

Here’s an example of the request body for the Reject setting request:

{
  "rejectedBy": "rejected-by",
  "rejectedReason": "rejected-reason"
}

The response should be status 200 OK with no response body.