Reading and setting timebox values

A role specifies a collection of rights. A role object contains a field, timebox, that defines the hours and days of the week that a role is either enabled or disabled. Setting the timebox field in a role object defines when a role’s rights are in effect.

You can read and set a role’s timebox field using the Role.ApplicableTimeHexString property. You can modify an existing timebox value one day or one hour at a time using the Role.GetSshRights and Role.SetApplicableHour methods.

To interpret a timebox value, or to set it directly, however, you must know the timebox value format. This appendix explains the format.

Hex string

The timebox value is a 42-character (21-byte) hexadecimal value stored as a string. When the hex value is converted to a binary value, its 168 bits each map to a single hour within the week. If a bit is set to 1, its corresponding hour is enabled for the role. If set to 0, its corresponding hour is disabled.

Hour mapping

Each day of the week takes three bytes (24 bits) to specify how its hours are enabled or disabled. The following tables show how the hours of a day are mapped to the bits within each of a day’s three bytes.

For byte 0 of each day of the week, you can enable or disable the hours a role is available from midnight to 8:00 AM:

Hour Bit

12-1 AM

0 (least-significant bit)

1-2 AM

1

2-3 AM

2

3-4 AM

3

4-5 AM

4

5-6 AM

5

6-7 AM

6

7-8 AM

7 (most-significant bit)

For byte 1 of each day of the week, you can enable or disable the hours a role is available from 8:00 AM to 4:00 PM:

Hour Bit

8-9 AM

0 (least-significant bit)

9-10 AM

1

10-11 AM

2

11-12 AM

3

12-1 PM

4

1-2 PM

5

2-3 PM

6

3-4 PM

7 (most-significant bit)

For byte 2 of each day of the week, you can enable or disable the hours a role is available from 4:00 PM to midnight:

Hour Bit

4-5 PM

0 (least-significant bit)

5-6 PM

1

6-7 PM

2

7-8 PM

3

8-9 PM

4

9-10 PM

5

10-11 PM

6

11-12 PM

7 (most-significant bit)

Day mapping

Each of the seven days in a week have three bytes within the 21-byte timebox value. These bytes are in chronological order from most-significant byte to least-significant byte. (Note that this is the opposite of chronological bit order within each byte, which is LSB to MSB.)

The starting point of a week is 4 PM on Saturday afternoon.

The table below shows how each day’s three bytes (0-2) map to the timebox value’s bytes, listed here in order from most-significant byte to least-significant byte.

Day byte Timebox value byte

Saturday, byte 2

20 (most-significant byte)

Sunday, byte 0

19

Sunday, byte 1

18

Sunday, byte 2

17

Monday, byte 0

16

Monday, byte 1

15

Monday, byte 2

14

Tuesday, byte 0

13

Tuesday, byte 1

12

Tuesday, byte 2

11

Wednesday, byte 0

10

Wednesday, byte 1

9

Wednesday, byte 2

8

Thursday, byte 0

7

Thursday, byte 1

6

Thursday, byte 2

5

Friday, byte 0

4

Friday, byte 1

3

Friday, byte 2

2

Saturday, byte 0

1

Saturday, byte 1

0 (least-significant byte)