Adjustment Schedule API
The purpose of this API is to create, update and delete adjustment schedules and their lines. Note that this API does not support creations, updates or deletes of default time periods. To load adjustment schedules and/or lines using this API, the default time period(s) must be created beforehand. Refer to the Adjustment Schedules page of the Rates chapter in the Configuration Guide for more information on the related model.
Requests
Create An Adjustment Schedule
Use the POST method to create a new adjustment schedule. The payload must be sent to the collection resource of the adjustment schedule API.
| Section "Discoverability" in Concepts describes how to discover a collection resource from the root URI. |
| This API uses HTTP status codes as defined in Response Messages. |
The link to the collection resource for this generic resource is available in the root resource of all Generic HTTP APIs under the name "adjustmentschedules" and may look like this:
POST http://[hostName]:[portNumber]/[api-context-root]/generic/adjustmentschedulesExample payload:
{
"code": "<code>",
"adjustmentType": "<adjustmentType (C or G)>",
"genericAdjustmentEvaluation": "<genericAdjustmentEvaluation (R or A)>",
"amountInterpretation": "<amountInterpretation (C or Y)>",
"enabled": "<enabled (true or false)>",
"scheduleDefinition":
{
"code": "<scheduleDefinitionCode>"
},
"currency":
{
"code": "<currencyCode>"
}
}
| The payloads presented in this section are just examples. Please use the Swagger metadata to find out what all is possible. |
When the POST is successful, the system will return a resource representation of the created adjustment schedule like this:
{
"id": ,
"code": "<code>",
"amountInterpretation": "<amountInterpretation C or Y>",
... more attributes ...
"links": [
{
"href": "http://[hostName]:[portNumber]/[api-context-root]/adjustmentschedules/",
"rel": "self"
}
],
"adjustmentScheduleLineList": [
{
"startDate": "<startDate of default time period 1>",
"links": [
{
"href": "http://[hostName]:[portNumber]/[api-context-root]/generic/adjustmentschedules/\{adjustment schedule id}/adjustmentschedulelines/defaulttimeperiod/\{defaultTimePeriodId 1}",
"rel": "canonical"
},
{
"rel": "oi:definition",/
"href": "http://[hostName]:[portNumber]/[api-context-root]/generic/adjustmentschedules/\{adjustment schedule id}/adjustmentschedulelines/definition"
}]
},
{
"startDate": "<startDate of default time period 2>",
"links": [
{
"href": "http://[hostName]:[portNumber]/[api-context-root]/generic/adjustmentschedules/\{adjustment schedule id}/adjustmentschedulelines/defaulttimeperiod/\{defaultTimePeriodId 2}",
"rel": "canonical"
},
{
"rel": "oi:definition",/
"href": "http://[hostName]:[portNumber]/[api-context-root]}/generic/adjustmentschedules/\{adjustment schedule id}/adjustmentschedulelines/definition"
}]
}
]
}The resource representation has a property "adjustmentScheduleLineList" with links for each defined default time period. Those links can be followed to retrieve, create, update or delete lines for that time period and adjustment schedule. For more details, see sections below.
The "oi:definition" has the usual functionality. Instead of returning the internal datamodel, it however represents the definition of the dimensions of the adjustment schedule. For example, when an adjustment schedule is based on schedule definition MED_COND that has a medicalCondition (alphanumeric) dimension, then the link of type "oi:definition" returns:
{
"MED_COND": {
"type": "object",
"properties": {
"amount": {
"type": "object",
"properties": {
"value": {
"type": "number",
"xml": {
"attribute": true
},
"minimum": -9999999999.99,
"maximum": 9999999999.99
}
}
},
"functionDynamicLogic": {
"$ref": "http://[hostName]:[portNumber]/[api-context-root]/generic/dynamicLogic/definition"
},
"percentage": {
"type": "number",
"xml": {
"attribute": true
},
"minimum": -999.99,
"maximum": 999.99
},
"medicalCondition": {
"type": "string",
"xml": {
"attribute": true
},
"maxLength": 1000
}
}
}
}In general, the definition resource is like this:
{
"type": "object",
"properties": {
"amount": {
"type": "object",
"properties": {
"value": {
"type": "number",
"xml": {
"attribute": true
},
"minimum": -9999999999.99,
"maximum": 9999999999.99
}
}
},
"functionDynamicLogic": {
"$ref": "http://[hostName]:[portNumber]/[api-context-root]/generic/dynamicLogic/definition"
},
"percentage": {
"type": "number",
"xml": {
"attribute": true
},
"minimum": -999.99,
"maximum": 999.99
},
"<amountField>": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"xml": {
"attribute": true
}
},
"valueAmount": {
"type": "number",
"xml": {
"attribute": true
},
"minimum": -9999999999.99,
"maximum": 9999999999.99
}
}
},
"<charField>": {
"type": "string",
"xml": {
"attribute": true
},
"maxLength": 1000
},
"<charFlexCodeField>": {
"type": "string",
"xml": {
"attribute": true
},
"maxLength": 1000,
"x-oi-dyn-flex-link": "<URL>"
},
"<charRangeField>": {
"type": "object",
"properties": {
"valueFrom": {
"type": "string",
"xml": {
"attribute": true
},
"maxLength": 1000
},
"valueTo": {
"type": "string",
"xml": {
"attribute": true
},
"maxLength": 1000
}
}
},
"<dateField>": {
"type": "string",
"format": "date",
"xml": {
"attribute": true
}
},
"<numberField>": {
"type": "number",
"xml": {
"attribute": true
}
}
}
}Retrieve Adjustment Schedules
Existing adjustment schedule(s) can be retrieved using the Query API against the collection resource, using the POST operation.
Example URL:
POST http://[hostName]:[portNumber]/[api-context-root]/generic/adjustmentschedules/search
{
"resource": {
"q": "code.eq('<some code>')"
}
}The resource representation is similar to the one returned after a POST (there are some differences because it is possible to return multiple adjustment schedules at once), including the adjustmentScheduleLineList section with the links to lines.
{
"offset": 0,
"count": 2,
"hasMore": true,
"limit": 50,
"items": [
{
"id": ,
"code": "<code>",
... other adjustment schedule properties, including adjustmentScheduleLineList
},
{...}
]
}
Update an Adjustment Schedule
Updating the adjustment schedule is done with the PUT operation against the singular resource. The singular resource is returned either from a POST or a GET operation. The payload is identical to the payload of the POST operation. The PUT operation returns the updated version of the resource.
Delete an Adjustment Schedule
Use the DELETE operation to delete an adjustment schedule, including all its lines.
Add, Update, and Delete Adjustment Schedule Lines
Operations on adjustment schedule lines are always in the context of a single adjustment schedule and default time period. First one has to retrieve the adjustment schedule resource, for example using a GET operation. From that resource, get the URL of the adjustment schedule lines resource from the "adjustment ScheduleLinesList". Use the entry with the "startDate" matching the default time period to be processed.
Only a collection resource exists for adjustment schedule lines, no singular resource. The collection resource supports POST, PUT and PATCH operations:
-
With POST, a number of adjustment schedule lines can be added to the adjustment schedule. Already existing lines for that schedule are not affected.
-
With PUT, a number of adjustment schedule lines can be sent in as the new set of lines for that resource. Existing lines not in the payload are deleted.
-
With PATCH, one can do individual operations on lines, without the need to send in the full set of lines.
The PUT and PATCH operation use the technical id of the adjustment schedule line to match the payload with existing data.
This is the message format for POST, PUT and PATCH:
{
"adjustmentScheduleLineList":
[{
"amount": {
"value": ""
},
"percentage": "",
"functionDynamicLogic": {
"id": ""
},
"<field name of schedule dimension with type value and datatype other than amount>": "",
"<field name of schedule dimension with type value and datatype amount>": {
"valueAmount" : {
"value": "",
"currency": ""
}
},
"<field name of schedule dimension with type range and datatype other than amount>": {
"valueFrom": "",
"valueTo": ""
},
"<field name of schedule dimension with type range and datatype amount>": {
"valueFromAmount": {
"value": "",
"currency": ""
},
"valueToAmount": {
"value": "",
"currency": ""
}
}
},
{
... other line(s)
}
]
}
POST Payload
Example payload for inserting 2 adjustment schedule lines:
{
"adjustmentScheduleLineList": [{
"percentage": 0,
"medicalCondition": "N"
}
{
"percentage": 20,
"medicalCondition": "Y"
}
]
}
| For details on how values in the request messages are handled, Property Representation and Handling (PUT, POST, PATCH). |
PUT Payload
The payload for PUT is almost identical to the POST payload, the only difference is that the id property must be included for matching payload values to existing adjustment schedule lines.
| If the "id" property is omitted, the line is handled as a new one, instead of an update to an existing one. |
PATCH Payload
The payload for PATCH is almost identical to the POST payload. The differences are that each line must include the "op" to identify the operation to be executed for that line and the id property for replacing or removing an existing line.
This payload will update the amount of a single line:
{
"adjustmentScheduleLineList": [{
"id": "1",
"op": "replace",
"percentage": 21
}
]
}
| See HTTP API PATCH for more details about PATCH and "op". |