Settle

This API generates a general structure to perform the settlement of records. The API allows the settlement of a great gamut of record structures, aggregations and settlement operations. Currently two aggregation and settlement operations are implemented, but further settlement and aggregation operations will be implemented in future versions. You can contact our development team through the Issues to ask for new settlement and aggregation operations to fit your use case.

API Specification

An abstraction API with all the settlement functionalities.

Settle

A settlement structure has the following parameters:

  • settleid : <string> - Unique identifier of the settlement structure
  • aggregates : <string > - Variables used as input for the aggregation operation.
  • primaryKey : <string> - Primary key used to aggregate metrics, build the common record and make the settlement.
  • aggregationType [1CDR / mcCounter] : <string > - Aggregation operation. This operation is triggered every time a new record is updated to the system.
  • settlementType [1CDR / none] : <string> - Settlement operation. It is triggered whenever a settlement operation is requested. It takes the status of the common record and generates a settled structure. The aggregation variables are cleared for a new round of settlement.
  • record : <string> - Sample record used to define the structure of records in the settlement structure. Also used as the main variable used to upload records.

Sample structure (Click to expand)

{
  "settleid": "settle",
  "aggregates": "['msg']",
  "aggregationType": "mcCounter",
  "primaryKey": "app",
  "settlementType": "string",
  "record": {}
}


API Methods

SettleAPI methods

Settlement methods (Click to expand)


POST - /settlement/create/

Creates a new settlement structure.

Input

  • settleid : <string> - Unique identifier of the settlement structure
  • aggregates : <string > - Variables used as input for the aggregation operation.
  • primaryKey : <string> - Primary key used to aggregate metrics, build the common record and make the settlement.
  • aggregationType [1CDR / mcCounter] : <string > - Aggregation operation. This operation is triggered every time a new record is updated to the system.
  • settlementType [1CDR / none] : <string> - Settlement operation. It is triggered whenever a settlement operation is requested. It takes the status of the common record and generates a settled structure. The aggregation variables are cleared for a new round of settlement.
  • record : <string> - Sample record used to define the structure of records in the settlement structure. Also used as the main variable used to upload records.

Sample structure (Click to expand)

{
  "record": {
   "app":  "4240e1f7-d287-46a9-8b92-f112510bd9f7",
   "op":  "CREATE",
   "corr":  "AUS-b8727fc3-dfc1-4c37-b6d6-d6897ed10ddd"
  },
  "aggregates": ["op"],
  "aggregationType": "mcCounter",
  "settlementType": "none",
  "settleid": "testing",
  "primaryKey": "app"
 }

Output

  • settlementObject : <json>

Sample structure (Click to expand)

{
  "output": {
    "aggregationMetrics": [
      "op"
    ],
    "aggregationType": "mcCounter",
    "lastSettlement": 1565172714,
    "lastUpdate": {
      "operation": "Create",
      "timestamp": 1565172714,
      "user": "test:org1MSP"
    },
    "primaryKey": "app",
    "settleid": "testing",
    "settlementType": "none"
  }
}


GET - /settlement/{settleId}

Gets the current status of a settlement structure. It shows the current status of aggregates.

Input

  • settleId : <string>

Output

  • newSettlementObject : <json>

Sample structure (Click to expand)

{
    "output": {
        "aggregates": {
            "2344240e1f7-d287-46a9-8b92-f1232342431": {
                "op": "2"
            },
            "4240e1f7-d287-46a9-8b92-f112510bd9f7": {
                "op": "1"
            }
        },
        "aggregationMetrics": [
            "op"
        ],
        "aggregationType": "mcCounter",
        "lastSettlement": 1565172714,
        "lastUpdate": {
            "operation": "Update",
            "timestamp": 1565172892,
            "user": "test:org1MSP"
        },
        "primaryKey": "app",
        "settleid": "testing",
        "settlementType": "none"
    }
}


GET - /settlement/{settleId}/history

Gets the history of changes over a settlement structure according to updated records.

Input

  • settleId : <string>

Output

  • newSettlementObject : <json>

Sample structure (Click to expand)

{
    "output": [
        {
            "aggregates": {
                "2344240e1f7-d287-46a9-8b92-f1232342431": {
                    "op": "2"
                },
                "4240e1f7-d287-46a9-8b92-f112510bd9f7": {
                    "op": "1"
                }
            },
            "aggregationMetrics": [
                "op"
            ],
            "aggregationType": "mcCounter",
            "lastSettlement": 1565172714,
            "lastUpdate": {
                "operation": "Update",
                "timestamp": 1565172892,
                "user": "test:org1MSP"
            },
            "primaryKey": "app",
            "settleid": "testing",
            "settlementType": "none"
        },
        {
            "aggregationMetrics": [
                "op"
            ],
            "aggregationType": "mcCounter",
            "lastSettlement": 1565172714,
            "lastUpdate": {
                "operation": "Create",
                "timestamp": 1565172714,
                "user": "test:org1MSP"
            },
            "primaryKey": "app",
            "settleid": "testing",
            "settlementType": "none"
        }
    ]
}


GET - /settlement/{settleId}/settled

Gets all settlements performed over a specific settleId.

Input

  • settleId : <string>

Output

  • newSettlementObject : <json>

Sample structure (Click to expand)

{
    "output": {
        "aggregates": {
            "2344240e1f7-d287-46a9-8b92-f1232342431": {
                "op": "2"
            },
            "4240e1f7-d287-46a9-8b92-f112510bd9f7": {
                "op": "1"
            }
        },
        "timestamp": 1565186196
    }
}


POST - /settlement/{settleId}/update

It uploads a new record to a settlement structure updating the status of aggregates according to the aggregationType defined for the settling structure.

Input

  • settlementObject : <json>

Sample structure (Click to expand)

{
  "record": [
    {
        "app":  "4240e1f7-d287-46a9-8b92-f112510bd9f7",
        "op":  "CREATE",
        "corr":  "AUS-b8727fc3-dfc1-4c37-b6d6-d6897ed10ddd"
        },
    {
        "app":  "2344240e1f7-d287-46a9-8b92-f1232342431",
        "op":  "CREATE",
        "corr":  "AUS-b8727fc3-dfc1-4c37-b6d6-d6897ed10ddd"
        },
    {
        "app":  "2344240e1f7-d287-46a9-8b92-f1232342431",
        "op":  "DELETE",
        "corr":  "AUS-b8727fc3-dfc1-4c37-b6d6-d6897ed10ddd"
        }
  ]
}

Output

  • newSettlementObject : <json>

Sample structure (Click to expand)

{
  "output": {
    "aggregates": {
      "2344240e1f7-d287-46a9-8b92-f1232342431": {
        "op": "2"
      },
      "4240e1f7-d287-46a9-8b92-f112510bd9f7": {
        "op": "1"
      }
    },
    "aggregationMetrics": [
      "op"
    ],
    "aggregationType": "mcCounter",
    "lastSettlement": 1565172714,
    "lastUpdate": {
      "operation": "Update",
      "timestamp": 1565172892,
      "user": "test:org1MSP"
    },
    "primaryKey": "app",
    "settleid": "testing",
    "settlementType": "none"
  }
}


POST - /settlement/{settleId}/settle

Settles a given settlement structure. It aggregates according to the current status of aggregates and the aggregationType defined for the settlement structure.

Input

  • settleId : <string>

Output

  • newSettlementObject : <json>

Sample structure (Click to expand)

{
    "output": {
        "2344240e1f7-d287-46a9-8b92-f1232342431": {
            "op": "2"
        },
        "4240e1f7-d287-46a9-8b92-f112510bd9f7": {
            "op": "1"
        }
    }
}


POST - /settlement/{settleId}/clear

Clears a settlement structure. It removes the current status of the aggregates. This may be used when unconsistent updates have been performed or errors have been detected in the updating of records.

Input

  • settleId : <string>

Output

  • newSettlementObject : <json>

Sample structure (Click to expand)

{
    "output": {
        "aggregationMetrics": [
            "op"
        ],
        "aggregationType": "mcCounter",
        "lastSettlement": 1565186196,
        "lastUpdate": {
            "operation": "Clear",
            "timestamp": 1565186640,
            "user": "test:org1MSP"
        },
        "primaryKey": "app",
        "settleid": "testing",
        "settlementType": "none"
    }
}


How we run the application

As you could see in the Architecture module, all the applications are running on cloud. Through Kubernetes orchestration system the application deployment, scaling and management is an easy and automated task.

Testing the Application

In postman folder there are the collection and environment to interact and test with the API methods. It is only needed to import them into postman application and know to use the coren-settleapi module

Also you can download the files in the links below:

- Postman collection
- Postman environment

Errors management

Settle API errors are managed through the following JSON:

{
  "error": {
    "code": "HTTP status code",
    "function": "function in which the error was generated",
    "message": "error description"
  }
}