Using Data Types

Introduction

Time Processing includes a number of data types designed to offer a more robust method of capturing field values.

Data Types

The following are a list of available data types:

Data Type	Description
PICKLIST	A set of values defined by a picklist.
TEXT	A string value with a maximum length of 65,535 bytes.
TIME	A time value represented by HH:MM:SS.mSmSmS. The seconds and milliseconds are optional.
JSON	Allows you to store a JSON value as an object or an array.
BIG_INTEGER	An 8-byte integer value.
DATE	A date value using the format: YYYY-MM-DD.
CODE	Supports Unicode value.
DECIMAL.2	A numeric value that can contain up to 12 digits with 2 after the decimal point.
DECIMAL.3	A numeric value that can contain up to 12 digits with 3 after the decimal point.
DECIMAL.6	A numeric value that can contain up to 15 digits with 6 after the decimal point.
DESCRIPTION	A long text field.
TIMESTAMP	A date/time value using the format YYYY-MM-DD hh:mm:ss.MsMsMs.
TIMESTAMP_WITH_ZONE	A date/time plus time zone value using the format YYYY-MM-DD hh:mm:ss.MsMsMs +zzzz
EXPRESSION	Used to evaluate an expression that generates a value at run time.
INTEGER	A whole number value.
BOOLEAN	True or false value.

Usage Examples

JSON Data Type

By default the dataTypeDefnParameter for a JSON data type is OBJECT, which consists of a key/value pair. For example:

POST https://tps-api.cfapps.sap.hana.ondemand.com/api/v1/pX2f8122a19/apiConnectionDefns

{
    "name": "jsonTypeObject",
    "description": "timeType_LargeInteger",
    "dataTypeDefnId": "JSON",
    "dataTypeDefnParameters":{"type":"OBJECT"},
    "appliesToAllTemplateFlag": false,
    "useInRules": false,
    "mandatoryFlag": true,
    "defaultValue":{"a1":"val1"}
}

To store an array, the dataTypeDefnParameters field is set to ARRAY. For example:

POST https://tps-api.cfapps.sap.hana.ondemand.com/api/v1/pX2f8122a19/apiConnectionDefns

{
    "name": "jsonTypeArray",
    "description": "timeType_LargeInteger",
    "dataTypeDefnId": "JSON",
    "dataTypeDefnParameters":{"type":"ARRAY"},
    "appliesToAllTemplateFlag": false,
    "useInRules": false,
    "mandatoryFlag": true,
    "defaultValue":{"Sunday","Monday"}
}

Decimal Data Types

Decimal data types include a parameter to define the rounding mode of the data type. Rounding modes are used to calculate work time from time events and are defined by the enums endpoint. They include the following:

Enumeration	Description
FLOOR	If there's any decimal number, the whole number is rounded down (EXAMPLE: 1.9 is rounded down to 1).
CEILLING	If there's any decimal number, the whole number is rounded up (EXAMPLE: 1.1 is rounded up to 2).
DOWN	Same as FLOOR.
UP	Same as CEILING.
HALF_EVEN	Rounding mode to round towards the nearest neighbor unless both neighbors are equidistant, in which case, round towards the even neighbor. Behaves like HALF_UP if the digit to the left of the discarded fraction is odd. Behaves like HALF_DOWN if it's even.
HALF_UP	If the first decimal number is five or above, the whole number is rounded up (EXAMPLE: 1.5 is rounded up to 2).
HALF_DOWN	If the first decimal number is five or below, the whole number is rounded down (EXAMPLE: 1.5 is rounded down to 1).

By default, the DECIMAL.2, DECIMAL.3, and DECIMAL.6 data types have a rounding mode of HALF_UP. You can change the default setting by including the dataTypeDefnParameters and supplying a different value for the rounding mode. For example:

POST https://tps-api.cfapps.sap.hana.ondemand.com/api/v1/pX2f8122a19/apiConnectionDefns

{
    "name": "decimalAttr2",
    "label": "Decimal Attribute Scale 2",
    "description" : "decimalAttr scale 2",
    "dataTypeDefnId":"DECIMAL.2",
    "dataTypeDefnParameters":{"roundingMode":"CEILING"},
    "mandatoryFlag":false,
    "appliesToAllTemplateFlag": false,
    "useInRules":false,
    "defaultValue":123489.24156
}

This creates the following record:

{
    "hostId": "31288231fb6e4339d6b8c1e3434c6eff",
    "status": "SUCCESS",
    "perfs": {
        "count": 1,
        "duration": 34,
        "sqlDuration": 24,
        "sqlCount": 1,
        "ruleDuration": 0,
        "ruleCount": 0,
        "methodCount": 0,
        "methodDuration": 0,
        "sqlPerfs": null,
        "methodPerfs": null,
        "duplicates": null
    },
    "content": {
        "attributeDefnId": "z20112422300649857028c83",
        "name": "decimalAttr2",
        "label": "Decimal Attribute Scale 2",
        "description": "decimalAttr scale 2",
        "defaultValue": 123489.25,
        "tenantId": "pX2f8122a19",
        "dataTypeDefnId": "DECIMAL.2",
        "dataTypeDefnParameters": {
            "roundingMode": "CEILING"
        },
        "mandatoryFlag": false,
        "appliesToAllTemplateFlag": false,
        "useInRules": false,
        "createdTime": "2020-11-24 22:30:06.522 +0000",
        "lastModifiedTime": null,
        "createdBy": "padmanabhan.l@sap.com",
        "lastModifiedBy": null,
        "activeFlag": true
    },
    "messages": [],
    "count": 1
}

Notice how the default value has changed from 123489.24156 to 123489.25 because the rounding mode is CEILING. Had it stayed the default value of HALF_UP, it would have been rounded to 123489.24.

Expression Data Type

Because it's not always possible to provide a static default value, the expressions data type allows you to evaluate an expression at run time to populate the value. For example:

POST https://tps-api.cfapps.sap.hana.ondemand.com/api/v1/pX2f8122a19/timeTemplates

{
    "name": "TimeRecordToTimeBundle",
    "label": "Time Record to Time Bundle",
    "description": "This template is Time Record to Time bundle with time pairing rules template",
    "startTimeObject": "TimeRecord",
    "endTimeObject": "TimeBundle",
    "lockVersion": "NO_VER",
    "crossMidnightFlag": true,
    "requiresVerificationFlag": false,
    "bundleFrequency": "DAILY",
    "attributes": {
        "stDailyThreshold": {
            "name": "stDailyThreshold",
            "defaultValue": 8,
            "sequence": 1
        },
        "WorkSchedule": {
            "name": "WorkSchedule",
            "defaultValue": "${resourceDetailWorkSchedule[resourceDetailId eq #resourceDetail.id].workSchedule}",
            "sequence": 2,
            "mandatoryFlag": true
        }
    },
    "events": {},
    "rules": {
        "TIME_RECORD_PROCESSING": [
            {
                "name": "TIME_EVENT_PAIRING_RULE",
                "sequence": 1
            }
        ]
    },
    "timeRecordAttributes": {
        "WorkSchedule": {
            "name": "WorkSchedule",
            "defaultValue": "${resourceDetailWorkSchedule[resourceDetailId eq #resourceDetail.id].workSchedule}",
            "sequence": 1,
            "mandatoryFlag": true
        }
    },
    "timeBundleAttributes": {
        "stDailyThreshold": {
            "name": "stDailyThreshold",
            "defaultValue": 8,
            "sequence": 1
        },
        "WorkSchedule": {
            "name": "WorkSchedule",
            "defaultValue": "${resourceDetailWorkSchedule[resourceDetailId eq #resourceDetail.id].workSchedule}",
            "sequence": 2
        }
    }
}

In the example above, we're trying to get the work schedule for a resource but that information isn't directly available because the value may vary from one resource to the next. The expression allows you to derive the value when the expression is evaluated. At a transaction run time, the resource ID is provided and the workschedule can be derived from that information.

If we add a time event using the template described above, it creates a time record where the WorkSchedule attribute has been rendered using the resource ID from the time event. For example:

{
    "hostId": "31288231fb6e4339d6b8c1e3434c6eff",
    "status": "SUCCESS",
    "perfs": {
        "count": 1,
        "duration": 89,
        "sqlDuration": 57,
        "sqlCount": 7,
        "ruleDuration": 0,
        "ruleCount": 0,
        "methodCount": 0,
        "methodDuration": 0,
        "sqlPerfs": null,
        "methodPerfs": null,
        "duplicates": null
    },
    "content": {
        "timeRecordId": "z2011132219527661818578f",
        "startTimeEventId": "z2011132219440161709178f",
        "endTimeEventId": "z2011132219470851722478f",
        "rawTimeEventId": null,
        "hours": 3.500000,
        "tenantId": "pX2f8122a19",
        "status": "PROCESSED",
        "statusDetail": [],
        "sourceId": "TPS",
        "timeType": "Work",
        "tenantExternalId": null,
        "personId": "z2011131743027655472678f",
        "template": "TimeRecordToTimeBundle",
        "templateLabel": "Time Record to Time Bundle",
        "attributes": {
            "stDailyThreshold": 8,
            "WorkSchedule": "workSchedule[workScheduleId eq 'z2011131740523775365478f']."
        },
        "startTimestamp": "2020-06-04 08:15:00.000 +0000",
        "endTimestamp": "2020-06-04 11:45:00.000 +0000",
        "createdTime": "2020-11-13T22:19:52.964 +0000",
        "lastModifiedTime": "2020-11-13T22:19:53.564 +0000",
        "createdBy": "z2011131740531275383178f",
        "lastModifiedBy": "synthetic-person-object",
        "timeBundleRef": "z2011132219032001636478f"
    },
    "messages": [],
    "count": 1
}