REST API

Tibigen Digital Repository

Version 3.52
Table of Content
1. General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1
1.1. String Identifier. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1
1.1.1. Timecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1
1.1.2. Datetime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1
1.1.3. UUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1
1.2. Unified response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  2
1.2.1. Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  2
1.2.2. Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  2
1.2.3. Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3
1.3. Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3
1.3.1. Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3
1.3.2. Value List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3
1.4. Languages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
1.4.1. Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
1.4.2. Language List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
1.4.3. List languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5
1.4.4. Get default language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5
1.4.5. Add language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5
1.4.6. Update language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  6
1.4.7. Delete language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  7
1.5. Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  8
1.5.1. Label. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  8
1.5.2. Label List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  8
1.6. Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  8
1.6.1. Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9
1.6.2. Lock List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10
1.6.3. List locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10
1.6.4. Get lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  11
1.6.5. Add lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  12
1.6.6. Delete lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  12
1.7. Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  13
1.7.1. Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  18
1.7.2. Property List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  18
1.7.3. List Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  18
1.7.4. Get Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  19
1.7.5. Add Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  20
 1.7.6. Update Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  20
1.7.7. Delete Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  21
1.8. Uniform Resource Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  22
1.8.1. URI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  22
1.8.2. URI List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  22
2. Authentication and Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  22
2.1. Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  23
2.1.1. Access Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  23
2.1.2. Create token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  24
2.1.3. Delete token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  24
2.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  25
2.2.1. Role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  25
2.2.2. Role List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  25
2.2.3. List roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  26
2.2.4. Get role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  26
2.2.5. Add role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  27
2.2.6. Update role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  27
2.2.7. Delete role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  28
2.2.8. List permissions of role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  29
2.2.9. Add permission to role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  30
2.3. Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  30
2.3.1. User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  30
2.3.2. User Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  32
2.3.3. User List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  32
2.3.4. List users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  32
2.3.5. Get user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  33
2.3.6. Add user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  33
2.3.7. Update user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  34
2.3.8. Delete user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  35
2.3.9. List roles of user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  35
2.3.10. Attach role to user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  36
2.3.11. Detach role from user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  36
2.3.12. List permissions of user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  37
2.4. Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  37
2.4.1. Permission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  38
2.4.2. Permission List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  38
2.4.3. Get permission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  38
2.4.4. Delete permission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  39
 2.4.5. List requirements of permission. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  40
2.4.6. Add requirement to permission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  40
2.5. Permission Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  41
2.5.1. Permission Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  42
2.5.2. Permission Requirement List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  43
2.5.3. Delete requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  43
3. Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  44
3.1. Dictionaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  44
3.1.1. Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  45
3.1.2. Dictionary List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  46
3.1.3. Term . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  46
3.1.4. Term List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  46
3.1.5. Term Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  47
3.1.6. List dictionaries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  47
3.1.7. Get dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  48
3.1.8. Add dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  49
3.1.9. Update dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  50
3.1.10. Delete dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  51
3.1.11. Add term to dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  52
3.1.12. Update term . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  53
3.1.13. Delete term . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  53
3.2. Metadata Entry Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  54
3.2.1. Item Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  54
3.2.2. Item Type List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  56
3.2.3. Group Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  56
3.2.4. Group Type List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  57
3.2.5. Field Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  58
3.2.6. Virtual Field Formula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  63
3.2.7. Formula Source Field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  65
3.2.8. Field Type List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  65
3.2.9. List item types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  66
3.2.10. Get item type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  67
3.2.11. Add item type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  68
3.2.12. Update item type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  68
3.2.13. Delete item type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  69
3.2.14. List group types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  70
3.2.15. Get group type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  71
3.2.16. Add group type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  71
 3.2.17. Update group type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  72
3.2.18. Delete group type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  73
3.2.19. List field types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  74
3.2.20. Get field type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  75
3.2.21. Add field type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  76
3.2.22. Update field type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  77
3.2.23. Delete field type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  79
3.3. Metadata Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  80
3.3.1. Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  80
3.3.2. Schema List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  81
3.3.3. Title Formula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  81
3.3.4. Title Formula Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  82
3.3.5. Metadata Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  83
3.3.6. List schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  83
3.3.7. Get schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  84
3.3.8. Add schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  85
3.3.9. Update schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  86
3.3.10. Delete schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  88
3.3.11. List types in schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  88
3.4. Metadata Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  89
3.4.1. Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  90
3.4.2. Item List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  92
3.4.3. Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  93
3.4.4. Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  94
3.4.5. Archival Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  95
3.4.6. Item in CSV representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  96
3.4.7. Item in Microsoft Excel representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  96
3.4.8. Permission Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  96
3.4.9. List items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  98
3.4.10. Get item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  99
3.4.11. Get children items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  100
3.4.12. Add item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  101
3.4.13. Update item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  103
3.4.14. List assets of item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  106
3.4.15. Add asset to item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  106
3.4.16. Get media for item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  107
3.4.17. Get archival item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  108
3.4.18. Add EDL to item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  109
 3.4.19. Get EDL associated with item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  110
3.5. Metadata Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  110
3.5.1. Metadata Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  111
3.5.2. Metadata Collection Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  111
3.5.3. Metadata Collection List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  112
3.5.4. List collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  112
3.5.5. Get collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  113
3.5.6. Add collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  114
3.5.7. Update collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  114
3.5.8. Delete collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  115
3.5.9. Add item to collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  116
3.5.10. Delete item from collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  117
4. Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  117
4.1. Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  118
4.1.1. Facet List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  120
4.1.2. Suggestion List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  120
4.1.3. Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  121
4.1.4. Create collection from search results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  122
4.1.5. Get facets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  123
4.1.6. Get suggestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  124
4.2. Saved Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  125
4.2.1. Saved Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  125
4.2.2. Saved Query List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  125
4.2.3. List saved queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  126
4.2.4. Get saved query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  126
4.2.5. Save search query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  127
4.2.6. Delete saved query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  128
4.3. Grouping Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  128
4.3.1. Grouping Criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  129
4.3.2. Grouping Criterion List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  130
4.3.3. List grouping criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  130
4.3.4. Get grouping criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  131
4.3.5. Add grouping criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  132
4.3.6. Update grouping criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  132
4.3.7. Delete grouping criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  133
4.4. Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  134
4.4.1. Reindex item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  134
4.4.2. Delete item from index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  135
5. Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  135
5.1. Asset Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  136
5.1.1. Asset Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  136
5.1.2. Asset Type List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  138
5.1.3. List asset types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  138
5.1.4. Get asset type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  139
5.1.5. Add asset type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  140
5.1.6. Update asset type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  140
5.1.7. Delete asset type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  141
5.2. Assets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  142
5.2.1. Asset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  142
5.2.2. Asset List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  144
5.2.3. Get asset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  144
5.2.4. Update asset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  145
5.2.5. Delete asset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  146
5.2.6. List files of asset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  146
5.2.7. List URIs of files in asset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  147
5.2.8. List assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  148
5.2.9. Add file to asset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  149
5.3. Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  150
5.3.1. File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  150
5.3.2. File List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  151
5.3.3. Get file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  152
5.3.4. Get URI to file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  153
5.3.5. Update file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  154
5.3.6. Delete file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  155
5.3.7. List instances of file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  155
5.3.8. Get optimal instance of file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  156
5.3.9. Add instance of file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  157
5.4. File Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  158
5.4.1. File Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  158
5.4.2. File Instance List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  159
5.4.3. List file instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  159
5.4.4. Get file instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  160
5.4.5. Update file instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  161
5.4.6. Delete file instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  162
5.5. EDLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  163
5.5.1. EDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  163
 5.5.2. EDL List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  164
5.5.3. Clip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  164
5.5.4. Get EDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  165
5.5.5. Update EDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  166
5.5.6. Delete EDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  166
5.5.7. List of EDLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  167
6. Storages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  168
6.1. Storage Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  168
6.1.1. Storage Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  168
6.1.2. Storage Group List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  170
6.1.3. List storage groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  172
6.1.4. Get storage group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  172
6.1.5. Add storage group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  173
6.1.6. Update storage group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  173
6.1.7. Delete storage group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  174
6.1.8. List storages in storage group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  175
6.1.9. Add storage to group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  175
6.2. Storages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  176
6.2.1. Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  176
6.2.2. Storage List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  178
6.2.3. Storage Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  178
6.2.4. Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  179
6.2.5. Sequence Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  179
6.2.6. Sequence Error List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  180
6.2.7. List storages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  180
6.2.8. Get storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  181
6.2.9. Get optimal storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  181
6.2.10. Update storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  182
6.2.11. Delete storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  183
6.2.12. List accesses to storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  184
6.2.13. Get optimal access to storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  185
6.2.14. Add access to storage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  185
6.2.15. List file instances on storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  186
6.2.16. List content on storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  187
6.2.17. Check sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  188
6.3. Storage Accesses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  190
6.3.1. Storage Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  190
6.3.2. Storage Access List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  191
 6.3.3. Protocol List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  191
6.3.4. Update access to storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  192
6.3.5. Delete access to storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  193
6.3.6. List available protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  193
7. Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  194
7.1. Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  195
7.1.1. Process Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  195
7.1.2. Process Param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  196
7.1.3. Execution Result List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  196
7.1.4. Execution Result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  197
7.1.5. Execute process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  197
7.1.6. Execute process on collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  198
7.1.7. List available processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  199
7.2. Embedded Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  200
7.2.1. Clear Index Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  200
7.2.2. Rebuild Index Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  200
7.2.3. Synchronize Index Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  201
7.2.4. Archive Item Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  201
7.2.5. Restore Item Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  202
7.2.6. Create Language Version Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  202
7.2.7. Synchronize LDAP User Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  203
7.2.8. Synchronize LDAP Users Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  203
7.3. Process Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  204
7.4. Job Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  205
7.4.1. Job Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  205
7.4.2. Job Queue List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  207
7.4.3. List job queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  208
7.4.4. Get job queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  210
7.4.5. Update job queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  211
7.4.6. Delete job queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  212
7.5. Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  212
7.5.1. Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  213
7.5.2. Job List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  215
7.5.3. Job Asset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  216
7.5.4. Job Asset List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  217
7.5.5. Get job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  217
7.5.6. Get job input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  218
7.5.7. Get job output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  219
 7.5.8. Update job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  220
7.6. Job Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  221
7.6.1. Callback Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  221
7.6.2. Check Access Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  222
7.6.3. Check Space Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  222
7.6.4. Clear Directory Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  223
7.6.5. Copy Files Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  223
7.6.6. Delete File Copies Job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  224
7.6.7. Delete Files Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  225
7.6.8. Delete Item Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  226
7.6.9. Delete Outdated Files Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  226
7.6.10. Edit Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  227
7.6.11. Export Job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  228
7.6.12. Generate Descriptor Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  229
7.6.13. Image Convert Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  230
7.6.14. Import Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  232
7.6.15. Notify About Nearly Outdated Files Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  233
7.6.16. Rename File Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  233
7.6.17. Resolve Path Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  234
7.6.18. Retrieve Technical Metadata Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  234
7.6.19. Search Video Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  235
7.6.20. Select Specification Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  236
7.6.21. Set Field Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  237
7.6.22. Transcode Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  238
7.6.23. TSM Archive Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  241
7.6.24. TSM Archive Complex Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  241
7.6.25. TSM Delete Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  243
7.6.26. TSM Insert Tapes Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  244
7.6.27. TSM Remove Tapes Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  244
7.6.28. TSM Retrieve Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  245
7.6.29. TSM Synchronize Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  246
7.6.30. Unzip Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  246
7.6.31. Validate Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  247
7.6.32. Zip Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  247
7.7. Workers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  248
7.7.1. Worker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  249
7.7.2. Worker List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  251
7.7.3. Capability List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  252
 7.7.4. List workers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  252
7.7.5. List capabilities of all workers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  253
7.7.6. Register worker. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  253
7.7.7. Unregister worker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  254
7.8. Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  255
7.8.1. Route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  255
7.8.2. Route List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  256
7.8.3. List routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  256
7.8.4. Get route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  256
7.8.5. Add route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  257
7.8.6. Update route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  258
7.8.7. Delete route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  258
7.9. Worker REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  259
7.9.1. List Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  259
7.9.2. Get Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  260
7.9.3. Get Job Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  260
7.9.4. Start Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  261
7.9.5. Change Job Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  261
7.9.6. Stop Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  262
7.9.7. Get Worker State. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  263
7.9.8. Shutdown Worker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  263
8. Transcoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  263
8.1. FFmpeg Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  264
8.1.1. FFmpeg Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  264
8.1.2. FFmpeg Profile List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  266
8.1.3. FFmpeg Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  266
8.1.4. FFmpeg Audio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  267
8.1.5. FFmpeg Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  268
8.1.6. FFmpeg Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  268
8.1.7. List FFmpeg profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  269
8.1.8. Get FFmpeg profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  270
8.1.9. Add FFmpeg profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  270
8.1.10. Update FFmpeg profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  271
8.1.11. Delete FFmpeg profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  272
8.2. ProMedia Carbon Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  272
8.2.1. ProMedia Carbon Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  272
8.2.2. ProMedia Carbon Profile List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  274
8.2.3. List ProMedia Carbon profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  275
 8.2.4. Get ProMedia Carbon profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  276
8.2.5. Add ProMedia Carbon profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  276
8.2.6. Update ProMedia Carbon profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  277
8.2.7. Delete ProMedia Carbon profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  278
8.3. ImageMagick Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  278
8.3.1. ImageMagick Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  279
8.3.2. ImageMagick Profile List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  280
8.3.3. List ImageMagick profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  280
8.3.4. Get ImageMagick profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  281
8.3.5. Add ImageMagick profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  281
8.3.6. Update ImageMagick profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  282
8.3.7. Delete ImageMagick profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  283
8.4. Transcoding Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  283
8.4.1. Transcoding Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  284
8.4.2. Transcoding Specification List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  285
8.4.3. Transcoding Specification Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  286
8.4.4. Transcoding Specification Source Video. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  287
8.4.5. Transcoding Specification Source Audio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  287
8.4.6. Transcoding Specification Source Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  288
8.4.7. Transcoding Specification Profile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  288
8.4.8. Transcoding Specification Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  289
8.4.9. List transcoding specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  289
8.4.10. Get transcoding specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  290
8.4.11. Add transcoding specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  290
8.4.12. Update transcoding specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  291
8.4.13. Delete transcoding specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  292
9. Archiving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  292
9.1. Archive Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  293
9.1.1. Archive Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  293
9.1.2. Archive Policy List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  294
9.1.3. List archive policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  294
9.1.4. Get archive policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  295
9.1.5. Add archive policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  296
9.1.6. Update archive policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  296
9.1.7. Delete archive policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  297
9.2. TSM Volumes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  298
9.2.1. TSM Volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  298
9.2.2. TSM Volume List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  300
 9.2.3. List TSM volumes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  300
9.2.4. Get TSM volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  301
9.2.5. Add TSM volume. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  301
9.2.6. Update TSM volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  302
9.2.7. Delete TSM volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  303
9.3. TSM Storage pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  303
9.3.1. TSM Storage Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  303
9.3.2. TSM Storage Pool List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  304
9.3.3. List TSM storage pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  305
9.3.4. Get TSM storage pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  306
9.3.5. Add TSM storage pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  306
9.3.6. Update TSM storage pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  307
9.3.7. Delete TSM storage pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  308
9.4. TSM Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  309
9.4.1. TSM Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  309
9.4.2. TSM Process List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  309
9.4.3. List TSM processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  310
10. Data Retention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  310
10.1. Retention Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  310
10.1.1. Retention Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  310
10.1.2. Retention Policies List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  311
10.1.3. List Retention Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  312
10.1.4. Get Retention Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  313
10.1.5. Add Retention Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  313
10.1.6. Update Retention Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  314
10.1.7. Delete Retention Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  315
11. Single Sign On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  315
11.1. Single Sign On flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  315
11.2. Single Logout flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  316
11.3. Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  316
11.3.1. SSO Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  316
11.3.2. SSO Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  317
11.3.3. SSO landing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  317
11.3.4. SAML services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  318
 Tibigen Digital Repository - REST API

1. General
This is official Tibigen Digital Repository REST API documentation. The document describes all web-
services, data formats and authentication methods needed to integrate with Tibigen Digital Repository.

A significant part of functionality provided by TDR GUI is internally implemented using this REST API.

The REST API uses mostly XML format for data representation.

1.1. String Identifier

Many objects in the system have string identifiers. These string identifiers must comply to naming
rules. A valid string identifier has to match regular expression ^\w+$. This means that the identifier
must be at least 1 character long and contain only characters from a to z (upper or lower case),
underscore (_) or digits from 0 to 9.

These are examples of valid string identifiers: title_1, TVSeries.

1.1.1. Timecode
Timecode represents single point in video or audio time-line. The timecode syntax is as in image
below:

Figure 1. Timecode format

1.1.2. Datetime
Datetime represents local date and time on machine where TDR is installed. The datetime syntax is as
in image below:

Figure 2. Datetime format

1.1.3. UUID
A universally unique identifier (UUID) is an identifier standard used in software construction. A UUID
is simply a 128-bit value, i.e. de305d54-75b4-431b-adb2-eb6b9e546014. More information about UUID

1
 Tibigen Digital Repository - REST API

can be found at https://en.wikipedia.org/wiki/Universally_unique_identifier.

1.2. Unified response

A valid HTTP response from REST API application always contains Response object in body of this
response. The response object represents either results of successful operation or description of
failure.

REST API can provide error description in selected language. For now, English and Polish are
supported.

1.2.1. Response
Example of successful response representation

<response status="SUCCESS">
    <language default="true">EN</language>
</response>

Example of failed response representation

<response status="FAILED">
    <error code="AuthenticationFailedException">
        <description lang="en">Authentication failed.</description>
    </error>
</response>

Table 1. Response properties

Name Type Description

status string One of:

- SUCCESS - handling of request succeed, response contains
result (if expected),
- FAILED - handling of request failed, response contains
error.

1.2.2. Error
Example of representation

<error code="AuthenticationFailedException">
    <description lang="en">Authentication failed.</description>
</error>

2
 Tibigen Digital Repository - REST API

Table 2. Error properties

Name Type Description

code string A language-agnostic name of this error.

description Description An internationalized description of this error.

1.2.3. Description
Example of representation

<description lang="en">Authentication failed.</description>

Table 3. Description properties

Name Type Description

lang string A name of the language in which description is provided.

xml value string The error description.

1.3. Values
Value object is a very simple object able to contain single value and its name. Values are used across
entire system when simple data need to be returned from web-service call, e.g. id of newly created
object.

Values can be packed into lists which are represented as Value List objects. Value lists are used where
multiple but simple values need to be returned.

1.3.1. Value
Example of representation

<value name="test_name">test_value</value>

Table 4. Value properties

Name Type Description

name string The name of this value object.

xml value string The value of this value object.

1.3.2. Value List

Value list is a container of Value objects.

3
 Tibigen Digital Repository - REST API

Example of representation

<value-list>
    <value name="test_name">test_value</value>
</value-list>

1.4. Languages
A language object represents a single language in the system. The object stores two letter code of
represented language and it is used in multiple places in the system where multi-language content
occurs, for example in metadata or dictionaries modules.

At the same time, only one language can be default. This means that when somebody requests multi-
language data and does not provide language in which these data should be returned, system will
return data in default language.

Default language is defined during the installation phase, and can be later changed. However,
changing language is a very demanding operation - all data in new default language must exist in the
system. As an example, let say we have dictionary with label in EN. EN is our default language. When
we want other defined language, e.g. PL to be default, our previously mentioned dictionary must have
PL label and PL version of all the terms.

1.4.1. Language
Example of representation

<language default="true">EN</language>

Table 5. Language properties

Name Type Description

default boolean If true, this language is default system language.

xml value string The two letter code of this language as in ISO 639.

1.4.2. Language List

A language list is a container of Language objects.

4
 Tibigen Digital Repository - REST API

Example of representation

<languages>
    <language default="true">EN</language>
    <language default="false">PL</language>
</languages>

1.4.3. List languages

List languages. The list contains languages names and information which language is default.

Request

GET /languages

Authorization
This request does not require authentication.

Response
If successful, the response status code is 200 OK and body contains Language List object wrapped in
Response object.

1.4.4. Get default language

Get default language.

Request

GET /languages/default

Authorization
This request does not require authentication.

Response
If successful, the response status code is 200 OK and body contains Language object wrapped in
Response object.

1.4.5. Add language

Add language.

5
 Tibigen Digital Repository - REST API

Request

POST /languages

In the request body, supply a Language object with at least required properties.

Authorization
This request requires authorization with permission manage.language.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

LanguageAlreadyExistsExcep 409 This language already exists.

tion InvalidLanguageNameException

1.4.6. Update language

Update language’s default property. This way, a new default language can be set.

Request

PUT /languages/{name}

Path parameters

Name Type Description

name string A name of the language to set as default.

In the request body, supply a Language object with default property set to true.

Authorization
This request requires authorization with permission manage.language.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

6
 Tibigen Digital Repository - REST API

Errors

Error code Status Description

code

DefaultLanguageDataMissing 400 Cannot set this language to default because there are objects
Exception in the system not having representations in this language.

LanguageNotFoundException 404 Cannot find language with given name.

OperationLockedException 409 Operation of changing default language is currently

running. Second operation cannot be executed.

1.4.7. Delete language

Delete language. All data in this language have to be deleted first, otherwise operation will fail.

Default language cannot be deleted.

Request

DELETE /languages/{name}

Path parameters

Name Type Description

name string A name of the language to delete.

Authorization
This request requires authorization with permission manage.language.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

LanguageNotFoundException 404 Cannot find language with given name.

DeleteDefaultLanguageNotAll 400 Default language cannot be deleted.

owedException

LanguageInUseException 400 Other system components use this language and therefore
language cannot be deleted.

7
 Tibigen Digital Repository - REST API

1.5. Labels
Many objects in TDR have name property. This property contains user-defined name that helps with
identification of the objects. However, restrictions imposed on these names (see String Identifier) do
not allow user to create user-friendly descriptions. Other useful feature, which is not possible with
name property is to give objects names in different languages. The name property can contain only
one value, so only one language representation of the name can be stored. To solve above problems,
TDR introduces objects called labels.

Labels allow users to store in the system any textual value as a description of the object. Single object is
able to have multiple labels, each in different language. For the moment, objects like dictionaries,
metadata entry types and grouping criteria support this mechanism.

1.5.1. Label
Example of representation

<label id="1" lang="EN" value="Duration">Video duration in minutes.</label>

Table 6. Label properties

Name Type Description

id integer An identifier of this label.

lang string A name of the language of this label.

value string A name or shorter description of object to which label is

attached.

xml value string A longer description of object to which label is attached. For
now, only metadata entry types use this property.

1.5.2. Label List

A label list is collection of Label objects.

Example of representation

<labels>
    <label id="1" lang="EN" value="Duration">Video duration in minutes.</label>
    <label id="2" lang="PL" value="Czas trwania">Czas trwania wideo w minutach.</label>
</labels>

1.6. Locks
A lock object is used to explicitly block operations on objects in TDR. Every lock has object-type and

8
 Tibigen Digital Repository - REST API

object-id properties that clearly identify locked object.

There are two type of locks: READ_WRITE and WRITE. Each of them forbid different operation on
locked objects. Single locked object can have multiple WRITE locks. These locks block write operation
(mostly update and delete). If object has WRITE lock, this probably means that some other component
is using that object. READ_WRITE locks, in turn, can occur only once on locked objects. They are
blocking all operations on target object so any other component cannot use it. READ_WRITE locks are
mostly used when some object is being deleted and deletion process is not an immediate operation.

Every component that creates lock is obliged to remove that lock after it will stop using locked object.
In case where component does not delete locks, system will automatically reclaim locked object by
expiring the locks which block it. For this purpose, every lock in the system has so-called lifetime. The
lock’s lifetime is a time interval between lock’s creation and lock’s expiration and depends on the type
of object that it blocks:

• FILE and SERVICE - infinite lifetime, these locks will never expire,

• JOB_DAEMON - one week lifetime,

• ITEM and DICTIONARY - one day lifetime.

1.6.1. Lock
Example of representation

<lock id="1"
      lock-type="READ_WRITE"
      object-type="FILE"
      object-id="1"
      inserted="2015-12-04 14:28:30"
      user="admin" />

Table 7. Lock properties

Name Type Description

id integer The identifier of this lock.

lock-type string The type of the lock. One of:

- READ_WRITE - forbids read and write on locked object,
- WRITE - forbids write on locked object, reads are allowed.
Required.

9
 Tibigen Digital Repository - REST API

Name Type Description

object-type string The type of locked object. One of:

- FILE - used to lock file instances,
- ITEM - used to lock metadata items,
- DICTIONARY - used to lock dictionaries,
- JOB_DAEMON - used internally by Job Daemon to eliminate concurrent
access to job queues,
- SERVICE - used to synchronize web-service calls in cases when web-service
cannot run in parallel.
Required.

object-id string The identifier of locked object e.g. metadata item UUID, file instance id.
Required.

user string A login of the user who created this lock.

inserted datetime The time when lock has been created.

expire-date datetime The time when lock will expire.

1.6.2. Lock List

A lock list is a container of Lock objects.

Example of representation

<locks total="2">
    <lock id="1" lock-type="READ_WRITE" object-id="1" object-type="FILE" inserted="2015-12-04
14:28:30"
          user="admin"/>
    <lock id="2" lock-type="WRITE" object-id="2" object-type="FILE" inserted="2015-12-04
14:29:49"
          user="admin"/>
</locks>

Table 8. Lock List properties

Name Type Description

total integer A number of locks possible to get, regardless of pagination.

1.6.3. List locks

Get list of locks. Resulting list can be filtered by user, lock type, object type and id (query parameters
can be combined together).

10
 Tibigen Digital Repository - REST API

Request

GET /locks?user={user}&lock-type={type}&object-type={type}&object-
id={id}&page={page}&size={size}

Query parameters

Name Type Description

user string If specified, locks created by this user will be returned.

lock-type string If specified, locks of this type will be returned.

object-type string If specified, locks on this type of objects will be returned.

object-id string If specified, locks on object with this id will be returned.

page integer The number of page of results to return. If not specified,

returns all locks.

size integer The size of the page of results. Default value is 10.

Authorization
This request requires authentication.

Response
If successful, the response status code is 200 OK and body contains Lock List wrapped in Response
object.

1.6.4. Get lock

Get single lock by id.

Request

GET /locks/{id}

Path parameters

Name Type Description

id integer An identifier of lock to get.

11
 Tibigen Digital Repository - REST API

Authorization
This request requires authentication.

Response
If successful, the response status code is 200 OK and body contains Lock object wrapped in Response
object.

Errors

Error code Status code Description

LockNotFoundException 404 Cannot find lock with given id.

1.6.5. Add lock

Add lock on given object. The object can have multiple WRITE locks and only one READ_WRITE lock.

Request

POST /locks

In the request body, supply a Lock object with at least required properties.

Authorization
This request requires authentication.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly
created lock, wrapped in Response object.

Errors

Error code Status Description

code

InvalidLockObjectException 400 The object-type or object-id is not specified.

InvalidLockTypeException 400 The lock-type is not specified.

LockAlreadyExistsException 409 The READ_WRITE lock already exists on this object.

1.6.6. Delete lock

Delete lock.

12
 Tibigen Digital Repository - REST API

Request

DELETE /locks/{id}

Path parameters

Name Type Description

id integer An identifier of lock to delete.

Authorization
If creator of the lock tries to delete it, only authentication is required. Otherwise, request requires
authorization with permission manage.lock.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

LockNotFoundException 404 Cannot find lock with given id.

1.7. Properties
Properties are simple mechanism for storing key-value configuration options for different components
of the system. Each property contains a name and a value. Furthermore, you can mark the chosen
properties as protected, which means that additional permission will be needed to view these
properties.

Currently, properties are used for storing:

• credentials and addresses to a separate system components,

• configuration of e-mail notifications,

• configuration of various processes.

Other system, integrating with TDR, can use this API to store relevant configuration. This ease
configuration, providing single place with all possible options to change. A great example of system,
that stores its configuration in properties and uses other parts of REST API is TDR GUI.

Example of available properties

13
 Tibigen Digital Repository - REST API

<properties>
  <property name="solr.url" protected="false" value="http://localhost:8983/solr"/>
  <property name="job-daemon.url" protected="false" value="http://localhost:8080/job-
daemon"/>
  <property name="file.accept_delete" protected="true" value="true"/>
  <property name="meta.accept_delete" protected="true" value="true"/>
  <property name="job-daemon.notifications.statuses" protected="false" value=
"FAILED,WAITING_FOR_APPROVAL"/>
  <property name="gui.gallery.images" protected="false" value="Klatki kluczowe,Plakaty,Logo
"/>
  <property name="meta.schema_order.metadata_item" protected="false" value=
"film;series;person"/>
  <property name="search.fold_to_ascii" protected="false" value="false"/>
  <property name="mail.password" protected="true" value="password"/>
  <property name="mail.default.recipent" protected="true" value=
"[email protected],[email protected],[email protected]"/>
  <property name="mail.default.recipent.lang" protected="true" value="PL"/>
  <property name="mail.send" protected="true" value="true"/>
  <property name="mail.smtp.host" protected="true" value="smtp.tibigen.com"/>
  <property name="mail.smtp.port" protected="true" value="465"/>
  <property name="mail.user" protected="true" value="mail_user"/>
  <property name="mail.user.address" protected="true" value="[email protected]"/>
  <property name="tsm.library.name" protected="false" value="TS3310"/>
  <property name="tsm.password" protected="true" value="admin"/>
  <property name="tsm.device_class" protected="false" value="LTOCLASS"/>
  <property name="tsm.storage.pool.disk" protected="false" value="SEQ_DISK"/>
  <property name="tsm.user" protected="true" value="admin"/>
  <property name="job-daemon.job-types" protected="false" value="CHECK_ACCESS
,CLEAR_DIRECTORY ,COPY_FILES,DELETE ,DELETE_ITEM,DUMMY_JOB,EXPORT
,GENERATE_DESCRIPTOR,IMAGE_CONVERT ,IMPORT ,RENAME_FILE
,RESOLVE_PATH,RETRIEVE_TECHNICAL_METADATA ,SEARCH_VIDEO
,SELECT_SPECIFICATION,SET_FIELD
,SPACE_CHECKER,STORAGE_CLEANER,TRANSCODE,TRANSFER,TSM_ARCHIVE ,TSM_DELETE
,TSM_INSERT_TAPES,TSM_REMOVE_TAPES ,TSM_RETRIEVE ,TSM_SYNCHRONIZE,UNZIP
,VALIDATE ,ZIP"/>
  <property name="search.perspective" protected="false" value=
"teaser|attr.file_type,attr.item_type,field.teaser_title;series|attr.file_type,attr.item_type,field.s
eries_title,field.series_creator,field.series_peremiere,field.series_genre;season|attr.file_type,at
tr.item_type,field.season_title;episode|attr.item_type,field.episode_title;movie|attr.file_type,at
tr.item_type,field.movie_title,field.movie_year_of_production;"/>

14
 Tibigen Digital Repository - REST API

  <property name="ldap" protected="false" value="true"/>

  <property name="ldap.user.dn" protected="false" value=
"CN=TDR,CN=Users,DC=tibigen,DC=local"/>
  <property name="ldap.user.password" protected="true" value="Java4Ever"/>
  <property name="ldap.url" protected="false" value="ldap://10.0.0.212:3268"/>
  <property name="ldap.base" protected="false" value="DC=tibigen,DC=local"/>
  <property name="ldap.login.attribute" protected="false" value="userPrincipalName"/>
  <property name="ldap.groups" protected="false" value="Administratorzy;Redakcja;onet"/>
  <property name="file.exclude" protected="false" value="\..*:dsa\.mp4"/>
  <property name="notify.retention.days" protected="false" value="7"/>
</properties>

Table 9. Available properties

Name Protecte Type Description

d

file.accept_delete true boolean If true, file deleting processes will require additional
acceptance. Default value is false.

file.asset.pathLevel false integer This property defines layout of assets directories on

storages. Levels from 0 to 3 are allowed. Level 0 will lay out
files in year directories, level 1 adds to hierarchy month
directories, level 2 day directories and finally level 3 creates
directories for each hour in the day.
Examples of paths for asset with id 1:
level 0: /2016/fg_1
level 1: /2016/03/fg_1
level 2: /2016/03/11/fg_1
level 3: /2016/03/11/10/fg_1
Default level is 2.

file.exclude false string List of files, separated by :, defining files and directories,
which will be ignored during Import process and List
content on storage. Java regular expressions should be used
as excluded file name.

jd.housekeeping false boolean If true, job daemon will be automatically deleting finished
queues after time period configured withing
jd.housekeeping.age_in_days. Default value is true.

jd.housekeeping.ag false integer Number of days after which job daemon will automatically
e_in_days delete finished queue. Default value is 30.

jd.housekeeping.tri false string The cron expression specifying time of housekeeping.

gger Default value is 0 0 0 * * ? * which is every day on midnight.

jd.worker.reconnec false integer Number of reconnects after which non unresponsive worker
t_limit will be unregistered. Default value is 5.

15
 Tibigen Digital Repository - REST API

Name Protecte Type Description

d

jd.dispatcher.scan_ false integer Number of milliseconds between scanning of queue

interval database. Default value is 10000.

jd.dispatcher.max_ false integer Maximum number of processes scanned by Process

processes_to_scan Dispatcher in every scan_interval. Default value is 1000.
There is no limit, if set to 0.

meta.accept_delete true boolean If true, item deleting process will require additional
acceptance. Default value is false.

job- false string List of job statuses which will trigger e-mail notifications.
daemon.notificatio Statuses are separated by commas. Available statuses are: -
ns.statuses FINISHED - jobs finished without errors,
- FAILED - failed jobs,
- WAITING_FOR_APPROVAL - jobs waiting for acceptance,

job-daemon.url false string HTTP address to TDR Job Daemon.

gui.gallery.images false string List of names of asset types, which defines order of asset
types in gallery. Names are separated by commas. To know
more about gallery, see User Guide documentation.

ldap false boolean If true, system will be using ldap as second source for
authentication.

ldap.base false string Base distinguished name (DN) for LDAP search.

ldap.groups false string List of names of LDAP groups, which members can
authenticate in TDR. For each group will be created role
with the same name. Group’s names are separated by
semicolons.

ldap.login.attribute false string Name of LDAP attribute, which will be used for querying
LDAP users.

ldap.url false string Address of LDAP server. Preferred port is 3268 (for querying
in global catalog) as current implementation does not
support LDAP Referrals.

ldap.user.dn false string LDAP user distinguished name (DN), which will be used to
synchronize users and roles with LDAP server.

ldap.user.password true passwor LDAP user password, which will be used to synchronize
d users and roles with LDAP server.

mail.default.recipe true string E-mails of receivers of notifications. E-mails are separated

nt by commas.

mail.default.recipe true string Language of e-mail notifications.

nt.lang

16
 Tibigen Digital Repository - REST API

Name Protecte Type Description

d

mail.user true string Login to e-mail account used by system to send notifications
to the e-mail addresses defined in property
mail.default.recipent.

mail.password true string Password to e-mail account used by system to send

notifications to the e-mail addresses defined in property
mail.default.recipent.

mail.user.address true string Sender address in e-mail notifications.

mail.send true boolean If true, system will be sending e-mail notifications.

mail.smtp.host true string Host of SMTP server used by system for e-mail notifications.

mail.smtp.port true integer Port of SMTP server used by system for e-mail notifications.

meta.schema_orde false string List of names of item types, which defines order of item
r.metadata_item types in menu Add item in GUI. Names are separated by
semicolons. More information can be found in User Guide
documentation.

notify.retention.da false integer System TDR will be sending e-mail notifications about items
ys containing files that will be outdated in given time in days. If
number of days is set to '0', notification will not be send.

search.fold_to_ascii false boolean If true, system will replace polish diacritics to most similar
equivalents from ASCII encoding in search suggestions.

search.perspective false string Configuration of fields displayed in search results in GUI.

Each item type can have separate list of attributes and fields
which will be visible in search results. The definition for
single item type should begin with item type name, followed
by a vertical bar |, followed by list of attributes and fields,
that should appear in search result block, separated by
commas ,. Each field should be specified as prefix field. and
a name of the field type. Each item attribue should be
specified as prefix attr. and a name of the attribute. The
definition ends with semicolon ;.
Multiple definitions are allowed. Example
teaser|attr.item_type,field.teaser_title;
person|attr.item_type,field.person_firstname,field.person_la
stname;

solr.url false string HTTP address to Solr server.

tsm.device_class false string Device class of tapes in TSM. Used while creating new
storage pool.

tsm.library.name false string Tape library name in TSM.

tsm.password true string Password for administrator account in TSM server.

17
 Tibigen Digital Repository - REST API

Name Protecte Type Description

d

tsm.storage.pool.di false string Name of disk storage pool in TSM.

sk

tsm.user true string Login for administrator account in TSM server.

1.7.1. Property
Example of representation

<property name="solr.url" protected="false" value="http://localhost:8983/solr"/>

Table 10. Property properties

Name Type Description

name string The name of this property. Required.

protected boolean If true, permission for viewing protected properties will be

required to view this property.

value string The value of this property.

1.7.2. Property List

A property list is a container of Property objects.

Example of representation

<properties>
<property name="solr.url" protected="false" value="http://localhost:8983/solr"/>
</properties>

1.7.3. List Properties

Get list of properties.

Request

GET /properties?protected={protected}

Query parameters

18
 Tibigen Digital Repository - REST API

Name Type Description

protected boolean If specified to true or false, returns protected or non-protected

properties respectively.

Authorization
This request requires authorization with permission view.config.

If parameter protected is true or is not specified, then authorization with permission

view.config.protected is required. Otherwise, required permission is view.config.basic.

Response
If successful, the response status code is 200 OK and body contains Property List object wrapped in
Response object.

1.7.4. Get Property

Get property.

Request

GET /properties/{property-name}

Path parameters

Name Type Description

property-name string The name of property.

Authorization
If property is protected, authorization with permission view.config.protected is required. Otherwise,
required permission is view.config.basic.

Response
If successful, the response status code is 200 OK and body contains Property object wrapped in
Response object.

Errors

Error code Status Description

code

PropertyNotFoundException 404 Cannot find property with given name.

19
 Tibigen Digital Repository - REST API

1.7.5. Add Property

Add new property.

Request

POST /properties

In the request body, supply a Property object with at least required properties.

Authorization
This request requires authorization with permission manage.config.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

InvalidPropertyException 400 The name of property is not specified or is empty. The value
of property is not specified.

PropertyAlreadyExistsExcepti 409 Property with the same name is already in the system.
on

1.7.6. Update Property

Update property.

Request

PUT /properties/{property-name}

Path parameters

Name Type Description

property-name string The name of property.

In the request body, supply a Property object with updated properties.

20
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission manage.config.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

InvalidPropertyException 400 The name of property is not specified or is empty. The value
of property is not specified.

PropertyNotFoundException 404 Cannot find property with given name.

1.7.7. Delete Property

Delete property.

Request

DELETE /properties/{property-name}

Path parameters

Name Type Description

property-name string The name of property.

Authorization
This request requires authorization with permission manage.config.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

PropertyNotFoundException 404 Cannot find property with given name.

21
 Tibigen Digital Repository - REST API

1.8. Uniform Resource Identifier

Uniform Resource Identifier (URI) is a string of characters used to identify a resource. Such
identification enables interaction with representations of the resource over a network, typically the
World Wide Web, using specific protocols. More information can be found at
https://en.wikipedia.org/wiki/Uniform_Resource_Identifier. In terms of TDR, URI is used to identify file
instances and usually exists within URI object.

1.8.1. URI
Example of representation

<uri>http://10.0.0.43:81/u01/tdr/files/KeyFrames/2015/11/27/fg_66/images/snowboard_0.jpg</ur
i>

Table 11. URI properties

Name Type Description

xml value string The value of this URI object.

1.8.2. URI List

URI list is a container of URI objects.

Example of representation

<uri-list>
    <uri>http://10.0.0.43:81/u01/tdr/files/KeyFrames/2015/11/27/fg_66/images/snowboard_0.jpg</
uri>
</uri-list>

2. Authentication and Authorization

User, in TDR, can be authenticated in two different ways: by password credentials and by token. The
first way - by password credentials - is simple method that requires client to send HTTP Basic
Authorization header with user login and password encoded as described in RFC 2617. Using that
authentication method, client have to send authorization header with every request. Due to the
simplicity, this method is great for development and maintenance purposes, but is discouraged in
over-internet integrations. If the user credentials from authorization header will be compromised, the
attacker will gain access to the REST API until password change.

The second authentication method use token to give temporary access to REST API. Firstly, token need
to be generated by authenticating via password credentials. Then, user can use this token in
Authorization header to authenticate itself in the system. After some time (more details in Tokens)

22
 Tibigen Digital Repository - REST API

token will expire and to continue using REST API, user have to request for new token.

TDR stores password credentials in own database, which is default source for authentication.
Additionally TDR supports LDAP protocol and can use external LDAP server as second source for
authentication. In this case every LDAP user, that is member of configured LDAP group, can
successfully authenticate in TDR. System, in LDAP synchronization process, adds roles based on
configured LDAP groups and assigns LDAP users this this roles.

REST API uses role based authorization mechanism. The roles contain permissions, that define what
functions of TDR can be executed by users having these roles. Permission can be dynamically added
and removed from roles. Multiple users can have multiple roles and multiple roles can be attached to
multiple users. If one user has multiple roles, he/she effectively has sum of all permissions contained
in individual roles.

Due to the extensive customization options of TDR content, REST API introduced additional level in
authorization mechanism - permission requirements. In most cases, permission gives access to some
set of functionality. This access can be narrowed down by adding requirements to it. If user wants to
access object in the system, the requirement is checked for that object and when requirement is met,
permission will be granted. For more information about permission requirements see Permission
Requirements.

2.1. Tokens
Tokens in REST API take part in authentication process. For now, there is only one type of token -
access token which, when generated, gives ability to authenticate for a limited period of time without
revealing a password. The access token is closely attached to the user for whom token was generated.

To generate token, client must authenticate via password credentials (login and password) to endpoint
POST /tokens. In return, system will send Access Token object that contains token string and a number
of seconds, after which this token will no longer be valid. The token can be used by the client, which
generated it, for subsequent requests to minimize exchange of plain text password through the
network or can be passed to another, potentially insecure client.

To authenticate via token, client has to send Authorization header with value Bearer TOKEN, where
TOKEN is previously acquired access token string e.g.:

Authorization: Bearer 55417b4f-c643-43b9-b4df-38be5d5c5bad

Access via the token can be revoked by deleting that token.

2.1.1. Access Token

23
 Tibigen Digital Repository - REST API

Example of representation

<access-token expires-in="86400">55417b4f-c643-43b9-b4df-38be5d5c5bad</access-token>

Table 12. Access Token properties

Name Type Description

expires-in integer The time of life of this token in

seconds.

xml value string The value of this token.

2.1.2. Create token

Create new access token. In REST API, tokens expire after 86400 seconds which is 24 hours.

Request

POST /tokens

Authorization
This request requires authentication via login and password credentials.

Response
If successful, the response status code is 200 OK and body contains Access Token object wrapped in
Response object.

Errors

Error code Status code Description

AuthenticationFailedExceptio 401 Failed to authenticate via given login and

n password.

2.1.3. Delete token

Delete the token used for authentication in this request. After this operation, authentication via the
token will fail.

Request

DELETE /tokens

24
 Tibigen Digital Repository - REST API

Headers

Name Type Description

Authorization string A value of this header should contain Bearer TOKEN where
TOKEN is token to delete.

Authorization
This request requires authentication via token.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

2.2. Roles
The role object represents some set of system functionality, that can be dynamically modified by
adding or removing role’s permissions. The system comes with two predefined roles: admin and
system. These roles contain every possible permission and are attached to corresponding predefined
users.

2.2.1. Role
Example of representation

<role name="super-admin"
        description="super admin role"
        version="0"
        prototype="admin" />

Property Type Description

name string The name of this role. Required.

description string The description of this role.

version integer A version of this role for optimistic locking purposes.

prototype string A name of a prototype role. The prototype role can be specified
on role creation - newly created role will have all permissions
copied from the prototype role.

2.2.2. Role List

The role list is a container of role objects.

25
 Tibigen Digital Repository - REST API

Example of representation

<roles>
    <role name="admin" description="default admin role" version="0"/>
    <role name="test" description="test role" version="3"/>
</roles>

2.2.3. List roles

Get list of roles.

Request

GET /roles

Authorization
This request requires authentication only.

Response
If successful, the response status code is 200 OK and body contains Role List object wrapped in
Response object.

2.2.4. Get role

Get single role.

Request

GET /roles/{name}

Path parameters

Name Type Description

name string A name of the role to get.

Authorization
This request requires authentication only.

26
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains Role object wrapped in Response
object.

Errors

Error code Status code Description

RoleNotFoundException 404 Cannot find role with given name.

2.2.5. Add role

Add new role.

Request

POST /roles

In the request body, supply a Role object with at least required properties.

Authorization
This request requires authorization with permission manage.permission.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status code Description

InvalidRoleNameException 400 A name of the role is empty or contains forbidden

characters.

RoleAlreadyExistsException 409 A role with given name already exists.

RoleNotFoundException 404 Cannot find the prototype role.

2.2.6. Update role

Update role’s properties. The only property that can be changed is description.

Request

27
 Tibigen Digital Repository - REST API

PUT /roles/{name}

Path parameters

Name Type Description

name string A name of the role to update.

In the request body, supply a Role object with updated properties. A name property cannot be updated
and therefore is ignored.

Authorization
This request requires authorization with permission manage.permission.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status code Description

RoleNotFoundException 404 Cannot find role with given name.

OptimisticLockingException 409 The role’s version does not match current version.
Someone already modified the role.

2.2.7. Delete role

Detach the role from all users and delete it.

Request

DELETE /roles/{name}

Path parameters

Name Type Description

name string A name of the role to delete.

Authorization
This request requires authorization with permission manage.permission.

28
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status code Description

RoleNotFoundException 404 Cannot find role with given name.

2.2.8. List permissions of role

List permissions of role.

Request

GET /roles/{name}/permissions?detailed={detailed}

Path parameters

Name Type Description

name string A name of the role which permissions should be returned.

Query parameters

Name Type Description

detailed boolean If true, web-service returns detailed representation of each

permission in a list. Default value is false.

Authorization
This request requires authentication only.

Response
If successful, the response status code is 200 OK and body contains Permission List object wrapped in
Response object.

Errors

Error code Status code Description

RoleNotFoundException 404 Cannot find role with given name.

29
 Tibigen Digital Repository - REST API

2.2.9. Add permission to role

Add permission to role.

Request

POST /roles/{name}/permissions

Path parameters

Name Type Description

name string A name of the role to which permission will be added.

In the request body, supply a Permission object with at least required properties.

Authorization
This request requires authorization with permission manage.permission.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly
created permission wrapped in Response object.

Errors

Error code Status code Description

RoleNotFoundException 404 Cannot find role of given name.

PermissionAlreadyExistsExce 409 The role already contains given permission.

ption

2.3. Users
A user object represents person or system which communicates with REST API. The user object has
basic personal data properties and properties related to authentication mechanism such as password.
Each user can have multiple roles, which define what user can do in the system.

In many places, TDR refers to the user using its login i.e. in a property created-by of Job Queue object.

2.3.1. User

30
 Tibigen Digital Repository - REST API

Example of simple representation

<user login="john" />

Example of detailed representation

<user
    login="john"
    password="secret"
    first-name="John"
    last-name="Doe"
    email="[email protected]"
    created="2013-11-09 23:14:48"
    last-active="2015-08-18 10:15:54"
    blocked="false"
    ldap="false"
    version="1">
    <properties>
        <property name="search.results" value="10"/>
    </properties>
</user>

Table 13. User properties

Property Type Description

login string The unique identifier of this user. The login must conform to
regex [a-zA-Z][\\w]+. Required.

password string The password of this user. Required only on creation.

first-name string The first name of this user.

last-name string The last name of this user.

email string An email address, which will be used to send notifications from
TDR. Required.

created datetime The time when this user was created.

last-active datetime The last time of user authentication.

version integer A version of this user for optimistic locking purposes.

blocked boolean If true, user cannot authenticate in TDR.

ldap boolean If true, user is synchronized from LDAP server.

31
 Tibigen Digital Repository - REST API

Property Type Description

roles Role List A list of roles to which this user belongs. See Role object.

properties Property List A list of user specific configuration properties. See User Property
object.

2.3.2. User Property

The user properties gives you ability to attach some specific data to user. There are no predefined
properties in REST API. It is up to the client to add any property and use it for custom purpose.

Example of representation

<property name="search.results" value="10"/>

Table 14. User Property properties

Property Type Description

name string The name of this property. Required.

value string The value of this property. Required.

2.3.3. User List

The user list object is container of User objects.

Example of representation

<users>
    <user login="john"/>
</users>

2.3.4. List users

Get list of users.

Request

GET /users?page={page}&size={size}&detailed={detailed}

Query parameters

32
 Tibigen Digital Repository - REST API

Name Type Description

page integer The number of page of results to return. If not specified, web-service
returns all users.

size integer The size of the page of results. Default value is 10.

detailed boolean If true, web-service returns detailed representation of each user in a list.
Default value is false.

Authorization
If detailed query parameter is true, this request requires authorization with permission view.user.
Otherwise, authorization with list.user is required.

Response
If successful, the response status code is 200 OK and body contains User List object wrapped in
Response object.

2.3.5. Get user

Get user. Returned representation, for security reasons, does not contain password property. There is
no way to retrieve user’s password through REST API.

Response

GET /users/{login}

Path parameters

Name Type Description

login string A login of the user to get.

Authorization
This request requires authorization with permission view.user.

Response
If successful, the response status code is 200 OK and body contains User object wrapped in Response
object.

2.3.6. Add user

Add new user. The user’s password is hashed before saving to database and is not stored in plain text.

33
 Tibigen Digital Repository - REST API

Request

POST /users

In the request body, supply a User object with at least required properties.

Authorization
This request requires authorization with permission add.user.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status code Description

InvalidUserLoginException 400 The user’s login is not set or does not conform to regex
[a-zA-Z][\\w]+.

2.3.7. Update user

Update user.

Request

PUT /users/{login}

Path parameters

Name Type Description

login string A login of the user to update.

In the request body, supply a User object with updated properties.

The password property can be omitted, if client does not want to update user’s password.

Authorization
This request requires authorization with permission update.user.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

34
 Tibigen Digital Repository - REST API

2.3.8. Delete user

Delete user.

Request

DELETE /users/{login}

Path parameters

Name Type Description

login string A login of the user to delete.

Authorization
This request requires authorization with permission delete.user.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

2.3.9. List roles of user

Get list of roles assigned to the user.

Request

GET /users/{login}/roles

Path parameters

Name Type Description

login string A login of the user whose roles should be returned.

Authorization
This request requires authorization with permission view.user.

Response
If successful, the response status code is 200 OK and body contains Role List object wrapped by
Response object.

35
 Tibigen Digital Repository - REST API

2.3.10. Attach role to user

Attach role to the user. This operation gives user all permission that role has.

Request

POST /users/{login}/roles

Path parameters

Name Type Description

login string A login of the user who will receive new role.

In the request body, supply Role object with name property.

Authorization
This request requires authorization with permission update.user.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

2.3.11. Detach role from user

Detach role from the user. After this operation, the user will lose all the permissions that detached role
has.

Request

DELETE /users/{login}/roles/{role-name}

Path parameters

Name Type Description

login string A login of the user from whom role will be detached.

role-name string A name of the role to detach.

Authorization
This request requires authorization with permission update.user.

36
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains empty Response object.

2.3.12. List permissions of user

Get list of user’s permissions - a union of sets of permissions from each role attached to the user.

Request

GET /users/{login}/permissions?detailed={detailed}

Path parameters

Name Type Description

login string A login of the user whose permission should be returned.

Query parameters

Name Type Description

detailed boolean If true, web-service returns detailed representation for each

permission object.

Authorization
This request requires authorization with permission view.user.

Response
If successful, the response status code is 200 OK and body contains Permission List object wrapped in
Response object.

2.4. Permissions
A permission defines action that can be executed on one object or set of objects over REST API. The
type of action and information about object are coded into permission’s name. The name may consist
of three segments separated by dots:

<action>.<object-type>.<object-id>

<object-id> can be ommited if permission applies to all objects of given type. The permission can be
also generalized by setting <action> to *, and therefore applied to all actions on given type. The name
of the permission is context specific and thus is described in Authorization sections of individual web-

37
 Tibigen Digital Repository - REST API

services when appropriate.

2.4.1. Permission
Example of simple representation

<permission id="1"
            name="manage.field.title"
            created="2015-12-04 15:35:31" />

Example of detailed representation

<permission id="1"
            name="manage.field.title"
            created="2015-12-04 15:35:31">
    <permission-requirements />
</permission>

Table 15. Permission properties

Name Type Description

id integer The unique identifier of this permission.

name string The name of this permission.

created datetime The time of permission creation.

permission-requirements Permission A list of permission requirements.

Requirement List

2.4.2. Permission List

A permission list is a container of Permission objects.

Example of representation

<permissions>
    <permission id="1"
                name="manage.group.permission_group"
                created="2015-12-04 15:35:31" />
</permissions>

2.4.3. Get permission

Get detailed representation of permission object.

38
 Tibigen Digital Repository - REST API

Request

GET /permissions/{id}

Path parameters

Name Type Description

id integer An unique identifier of permission to get.

Authorization
This request requires authentication only.

Response
If successful, the response status code is 200 OK and body contains Permission object wrapped in
Response object.

Errors

Error code Status code Description

PermissionNotFoundExceptio 404 Cannot find permission with given id.

n

2.4.4. Delete permission

Delete permission.

Request

DELETE /permissions/{id}

Path parameters

Name Type Description

id integer An unique identifier of permission to delete.

Authorization
This request requires authorization with permission manage.permission.

39
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status code Description

PermissionNotFoundExceptio 404 Cannot find permission with given id.

n

2.4.5. List requirements of permission

Get list of permission’s requirements.

Request

GET /permissions/{id}/requirements

Path parameters

Name Type Description

id integer An unique identifier of permission which requirements should be

returned.

Authorization
This request requires authentication only.

Response
If successful, the response status code is 200 OK and body contains Permission Requirement List object
wrapped in Response object.

Errors

Error code Status code Description

PermissionNotFoundExceptio 404 Cannot find permission with given id.

n

2.4.6. Add requirement to permission

Add new requirement to permission.

40
 Tibigen Digital Repository - REST API

Request

POST /permissions/{id}/requirements

Path parameters

Name Type Description

id integer An unique identifier of permission, to which requirement will be

added.

In the request body, supply a Permission Requirement object with at least required properties.

Authorization
This request requires authorization with permission manage.permission.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly
created requirement wrapped in Response object.

Errors

Error code Status code Description

InvalidPermissionRequirementException 400 Requirement entity type or entity id is

not specified or empty.

PermissionNotFoundException 404 Cannot find permission with given id.

PermissionRequirementAlreadyExistsExcepti 409 Given permission already has such a

on requirement.

2.5. Permission Requirements

Permission requirement contains condition that have to be met in order to grant permission having
this requirement. For example, a permission may exist allowing to view metadata item, but only if one
of the item’s field has specific value. Other example of permission requirement is to gain access only to
files of specific type e.g. high resolution videos.

An algorithm of granting permission to specific object is as follows:

1. User wants to view some object of specific type and id. The action in this case is view.

2. System loads roles of that user and from these roles retrieves all permissions.

3. System iterates over permissions and if it finds permission with requirements, it tries to verify that

41
 Tibigen Digital Repository - REST API

requirement using verification mechanism specific for the context of web-service call. The
verification mechanism are described later.

4. When all permissions are verified, system checks if there is at least one permission giving access to
view previously mentioned object. If found, permission is granted.

There are several requirement verification mechanism:

1. Asset Type Requirement Verifier - verifies requirements concerning only the files and is used
mostly in web-services operation on files.

2. Metadata Content Based Requirement Verifier - verifies requirements concerning only metadata
entries i.e. items, groups and fields.

3. Process Requirement Verifier - verifies requirements concerning processes and objects on which
those processes operate on. Used in web-services managing processes and jobs.

In descriptions of web-services that verify permissions, the concrete verification mechanism is

mentioned.

2.5.1. Permission Requirement

Example of representation

<permission-requirement id="1"
                        required-entity-type="field"
                        required-entity-id="status"
                        required-value="open"
                        inverted="false" />

Table 16. Permission Requirement properties

Name Type Description

id integer The unique identifier of permission requirement.

required-entity-type string The type part of entity selector that selects entities for
requirement verification. A value of this property depends on
requirement verification mechanism used:
- for Asset Type Requirement Verifier allowed value is asset
which checks asset types,
- for Metadata Content Based Requirement Verifier allowed
values are item-attribute which checks metadata item attribute
and field which checks field value,
- for Process Requirement Verifier allowed values are asset which
checks type of asset participating in process and item which
checks type of item participating in process.
Required.

42
 Tibigen Digital Repository - REST API

Name Type Description

required-entity-id string The id part of entity selector that selects entities for requirement
verification. A value of this property depends on required-entity-
type and can be for example concrete asset type id, field value,
item attribute value or item type. Required.

required-value string The expected value of selected entity. If any of the selected
entities have this value, permission requirement is considered as
met. If this value is not specified, requirement is met if at least
one entity was selected.

inverted boolean If true, inverts result of required-value condition check. Default

value is false.

2.5.2. Permission Requirement List

A permission requirement list is a container of Permission Requirement objects.

Example of representation

<permission-requirements>
    <permission-requirement id="1"
                        required-entity-type="field"
                        required-entity-id="status"
                        required-value="open"
                        inverted="false" />
</permission-requirements>

2.5.3. Delete requirement

Delete permission requirement.

Request

DELETE /requirements/{id}

Path parameters

Name Type Description

id integer An unique identifier of permission requirement to delete.

43
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission manage.permission.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

PermissionRequirementNotF 404 Cannot find permission requirement with given id.

oundException

3. Metadata
In TDR, to add textual data you need to create an item, which is set of metadata based on schema
configured in the system. Schema defines internal structure of item and external relationships
between items. Structure of item can consist of fields and groups, where field contains single value and
group can contain fields and other groups. This means that item can represent any hierarchical
metadata. Furthermore, system allows to create hierarchy of items based on parent-child relationships
defined in schema. Each item can have only one parent item and unlimited number of children items.

Items, groups and fields can have various properties, which are included in their metadata types.
These types can be treated as classes in Object Oriented Programming. For example, a field type
defines whether field is multi-value or not.

Fields are the most important part of metadata because they include actual data. TDR supports couple
of data kinds in the field, such as: textual value, reference to item or reference to term in dictionary
which is supported as a common data structure. The system allows to define any number of
dictionaries and freely use them in fields.

Apart from item hierarchy, the system allows also to create collections of items, which can be used to
execute batch processes on multiple items such as deleting of items or exporting of files from items.

3.1. Dictionaries
A dictionary object represents dictionary data structure which can contain any number of terms. The
dictionaries can be used later in metadata schemas to limit set of possible field values.

Dictionaries are multilingual structures and therefore can contain terms in any language defined in
TDR.

44
 Tibigen Digital Repository - REST API

3.1.1. Dictionary
Example of simple representation

<dictionary uuid="7012f478-82cf-4165-bd9e-1a9a389c6f7e"
            name="countries" />

Example of detailed representation

<dictionary uuid="7012f478-82cf-4165-bd9e-1a9a389c6f7e"
            name="countries"
            auto-sorted="true"
            version="1">
    <labels>
        <label id="1" lang="EN">Countries</label>
        <label id="2" lang="PL">Kraje</label>
    </labels>
    <terms>
        <term uuid="d655d035-a44b-4336-abcc-885db4a78f03">
            <entry id="1" lang="EN" value="Poland">Republic of Poland</entry>
            <entry id="2" lang="PL" value="Polska">Rzeczpospolita Polska</entry>
        </term>
    </terms>
</dictionary>

Table 17. Dictionary properties

Name Type Description

uuid uuid The unique identifier of this dictionary.

name string The name of this dictionary. Required.

auto-sorted boolean If true, system will sort terms in natural order. The sorting
occur only if client will be retrieving dictionary in one
specific language version. Default value is false.

version integer A version of this dictionary for optimistic locking purposes.

labels Label List A list of dictionary labels. Required label in default

language.

terms Term List A list of terms.

45
 Tibigen Digital Repository - REST API

3.1.2. Dictionary List

A dictionary list is a container of Dictionary objects.

Example of representation

<dictionaries total="138">
    <dictionary name="countries" uuid="eb357001-0ec7-4990-8017-be5c458971cc"/>
</dictionaries>

Table 18. Dictionary List properties

Name Type Description

total integer Total number of dictionaries in TDR.

3.1.3. Term
A term object is an abstract representation of word. Technically speaking, term is a container of Term
Entry objects, which represent actual word in specific languages.

Example of representation

<term uuid="d655d035-a44b-4336-abcc-885db4a78f03">
    <entry id="1" lang="EN" value="Poland">Republic of Poland</entry>
    <entry id="2" lang="PL" value="Polska">Rzeczpospolita Polska</entry>
</term>

Table 19. Term properties

Name Type Description

uuid uuid A unique identifier of term.

entries Term Entry list A list of term entries.

3.1.4. Term List

A term list is container of Term objects.

46
 Tibigen Digital Repository - REST API

Example of representation

<terms>
    <term uuid="d655d035-a44b-4336-abcc-885db4a78f03">
        <entry id="1" lang="EN" value="Poland">Republic of Poland</entry>
        <entry id="2" lang="PL" value="Polska">Rzeczpospolita Polska</entry>
    </term>
</terms>

3.1.5. Term Entry

A term entry object represents actual word in specific language. The term entry stores usually shorter
value and longer description of this value.

Example of representation

<entry id="1" lang="EN" value="Poland">Republic of Poland</entry>

Table 20. Term Entry properties

Name Type Description

id integer The unique identifier of this term entry.

lang string The language of this entry. Required.

value string The value of this term entry. Required.

xml value string The description of this term entry.

3.1.6. List dictionaries

Return list of dictionaries.

Request

GET /dictionaries?name={name}&page={page}&size={size}&detailed={detailed}

Query parameters

Name Type Description

name string If specified, returns only dictionaries with specified name. Due to the
fact that the name of the dictionary is unique, returned list will always
contain zero or one element.

47
 Tibigen Digital Repository - REST API

Name Type Description

page integer The number of page of results to return. If not specified, web-service
returns all dictionaries.

size integer The size of the page of results. Default value is 10.

detailed boolean If false, returns Dictionary objects containing DictionaryLabel objects.

Otherwise full structure of dictionaries is returned e.g. Dictionary,
DictionaryLabel, Term, TermEntry objects.

Authorization
This request requires authorization with permission list.dictionary.

Response
If successful, the response status code is 200 OK and body contains Dictionary List object wrapped in
Response object.

3.1.7. Get dictionary

Get dictionary. The dictionary can be retrieved in all languages in a single request or in a specific
language.

Request

GET /dictionaries/{uuid}

Path parameters

Name Type Description

uuid uuid A unique identifier of dictionary to get.

Headers

Name Type Description

Content-Language string A name of the language defined in TDR, in which dictionary

should be returned. If not specified, dictionary with terms in
all available languages will be returned.

Authorization
This request requires authorization with permission view.dictionary.UUID where UUID is UUID of the
dictionary to get.

48
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains Dictionary object wrapped in
Response object.

Errors

Error code Status Description

code

DictionaryNotFoundExceptio 404 Cannot find dictionary with given UUID.

n

3.1.8. Add dictionary

Add new dictionary.

Request

POST /dictionaries

In the request body, supply a Dictionary object with at least required properties.

Authorization
This request requires authorization with permission add.dictionary.

Response
If successful, the response status code is 200 OK and body contains Value object with UUID of newly
added dictionary wrapped in Response object.

Errors

Error code Status Description

code

InvalidDictionaryNameExcep 400 The name of the dictionary is not specified or is empty.

tion

DuplicatedLabelException 400 There are labels in the same language.

InvalidLabelLanguageExcepti 400 Label language is invalid.

on

InvalidLabelTextException 400 Label text is not specified.

DuplicatedTermEntryExcepti 400 There are multiple term entries in the same language.
on

49
 Tibigen Digital Repository - REST API

Error code Status Description

code

InvalidTermEntryLanguageE 400 Term entry language is invalid.

xception

InvalidTermEntryValueExcep 400 Term entry value is not specified.

tion

DuplicatedTermException 400 There are at least two terms with equal value.

LabelNotFoundException 404 There is no label in system default language.

TermEntryNotFoundExceptio 404 There is a term without term entry in default system

n language.

DictionaryAlreadyExistsExce 409 Dictionary with given name already exists.

ption

3.1.9. Update dictionary

Update dictionary. If any term changes, system will execute background task which will update all
values of metadata fields referencing changed dictionary term.

Request

PUT /dictionaries/{uuid}

Path parameters

Name Type Description

uuid uuid A unique identifier of dictionary to update.

In the request body, supply a Dictionary object with updated properties.

Authorization
This request requires authorization with permission update.dictionary.UUID where UUID is UUID of
the dictionary to update.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

50
 Tibigen Digital Repository - REST API

Error code Status Description

code

InvalidDictionaryNameException 400 The name of the dictionary is not specified or is

empty.

DuplicatedLabelException 400 There are labels in the same language.

InvalidLabelLanguageException 400 Label language is invalid.

InvalidLabelTextException 400 Label text is not specified.

DuplicatedTermEntryException 400 There are multiple term entries in the same

language.

InvalidTermEntryLanguageException 400 Term entry language is invalid.

InvalidTermEntryValueException 400 Term entry value is not specified.

DuplicatedTermException 400 There are at least two terms with equal value.

LabelNotFoundException 404 There is no label in system default language.

TermEntryNotFoundException 404 There is a term without term entry in default

system language.

DictionaryNotFoundException 404 Cannot find dictionary with given UUID.

OptimisticLockingException 409 Other user just updated this version of dictionary.

3.1.10. Delete dictionary

Delete dictionary. All contained terms and term entries will also be deleted.

Request

DELETE /dictionaries/{uuid}

Path parameters

Name Type Description

uuid uuid A unique identifier of dictionary to delete.

Authorization
This request requires authorization with permission delete.dictionary.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

51
 Tibigen Digital Repository - REST API

Errors

Error code Status Description

code

DictionaryInUseException 400 There are metadata field types that reference this dictionary
and therefore dictionary cannot be deleted.

DictionaryNotFoundExceptio 404 Cannot find dictionary with given UUID.

n

3.1.11. Add term to dictionary

Add new term to dictionary.

Request

POST /dictionaries/{uuid}/terms

Path parameters

Name Type Description

uuid uuid A unique identifier of dictionary which receives new term.

In the request body, supply a Term object with at least required properties.

Authorization
This request requires authorization with permission update.dictionary.UUID where UUID is UUID of
dictionary to update.

Response
If successful, the response status code is 200 OK and body contains Value object with UUID of newly
created term wrapped in Response object.

Errors

Error code Status Description

code

DuplicatedTermEntryExcepti 400 There are multiple term entries in the same language.
on

DictionaryNotFoundExceptio 404 Cannot find dictionary with given UUID.

n

52
 Tibigen Digital Repository - REST API

Error code Status Description

code

TermEntryNotFoundExceptio 404 A term does not contain entry in system default language.
n

3.1.12. Update term

Update term. In the background system will execute task that will find and update all values of
metadata fields referencing changed term.

Request

PUT /terms/{uuid}

Path parameters

Name Type Description

uuid uuid A unique identifier of term to update.

In the request body, supply a Term object with updated properties.

Authorization
This request requires authorization with permission update.dictionary.UUID where UUID is UUID of
dictionary containing term to update.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

DuplicatedTermEntryException 400 There are multiple term entries in the same

language.

TermEntryNotFoundException 404 A term does not contain entry in system

default language.

TermNotFoundException 404 Cannot find term with given UUID.

3.1.13. Delete term

Delete term. All contained term entries will also be deleted.

53
 Tibigen Digital Repository - REST API

Request

DELETE /terms/{uuid}

Path parameters

Name Type Description

uuid uuid A unique identifier of term to delete.

Authorization
This request requires authorization with permission update.dictionary.UUID where UUID is UUID of
the dictionary that contains term to delete.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

DictionaryLockedException 400 The dictionary which contains term to delete is already in

use and therefore cannot be updated.

TermNotFoundException 404 Cannot find term with given UUID.

3.2. Metadata Entry Types

Metadata entry types define behavior and capabilities of individual entries of metadata in TDR i.e.
items, groups and fields.

3.2.1. Item Type

Example of simple representation

<item-type name="programme"
            family="METADATA_ITEM"
            indexed="true"
            repeatable="false"
            root-item="true"
            sequence="false"
            version="0" />

54
 Tibigen Digital Repository - REST API

Example of detailed representation

<item-type name="programme"
            family="METADATA_ITEM"
            indexed="true"
            repeatable="false"
            root-item="true"
            sequence="false"
            version="0">
    <labels>
        <label lang="EN" value="Programme" />
    </labels>
</item-type>

The detailed representation of item type additionally contains list of labels.

Table 21. Item Type properties

Name Type Description

name string A name of this item type. The name is string identifier and thus has to
comply to naming convention described in String Identifier. Also, the
name has to be unique among other item types. Required.

family string A family of item type. Allowed values are:

- FILE_ITEM - items based on this type store technical metadata
describing files. User cannot create items of these types manually.
Creation is done automatically as a result of various processes. File
items are always based on schemas predefined in TDR.
- METADATA_ITEM - items based on this type stores metadata about
business entities introduced by users e.g. persons, institutions, films.
Default value is METADATA_ITEM.

indexed boolean If true, item of this type will be indexed by search engine and can be
then searched. Default value is true.

repeatable boolean If true, only single item of this type can occur under its parent. Default
value is false.

root-item boolean If true, item of this type can be root or any other item in metadata tree.
Otherwise, item cannot be root - has to have parent item. Default value
is false.

sequence boolean If true, item of this type can be attached to specific timecode interval in
a video or audio timeline. Technically speaking, system allows to set
item’s timecode-start and timecode-stop properties. Default value is
false.

55
 Tibigen Digital Repository - REST API

Name Type Description

version integer A version of this item type for optimistic locking purposes.

labels Label List A list of labels in languages defined in TDR. TDR requires at least one
label in system default language. If label is not specified, system will
generate default label, identical to item type name.

3.2.2. Item Type List

An item type list is container of Item Type objects.

Example of representation

<item-types>
    <item-type name="programme"
                family="METADATA_ITEM"
                indexed="true"
                repeatable="false"
                root-item="true"
                sequence="false"
                version="0" />
</item-types>

3.2.3. Group Type

Example of simple representation

<group-type name="prog_directors"
            repeatable="false"
            sequence="false"
            version="0" />

56
 Tibigen Digital Repository - REST API

Example of detailed representation

<group-type name="prog_directors"
            repeatable="false"
            sequence="false"
            version="0">
    <labels>
        <label lang="EN" value="Directors" />
    </labels>
</group-type>

Table 22. Group Type properties

Name Type Description

name string A name of this group type. The name is string identifier and
thus has to comply to naming convention described in String
Identifier. Also, the name has to be unique among other
group types. Required.

repeatable boolean If true, the container object (item or other group) can
contain multiple groups of this type. Default value is false.

sequence boolean If true, group of this type can be attached to specific

timecode interval in a video or audio timeline. Technically
speaking, system allows to set group’s timecode-start and
timecode-stop properties. Default value is false.

version integer A version of this group type for optimistic locking purposes.

labels Label List A list of labels in languages defined in TDR. TDR requires at
least one label in system default language. If label is not
specified, system will generate default label, identical to
group type name.

3.2.4. Group Type List

A group type list is container of Group Type objects.

57
 Tibigen Digital Repository - REST API

Example of representation

<group-types>
    <group-type name="prog_directors"
                repeatable="false"
                sequence="false"
                version="0" />
</group-types>

3.2.5. Field Type

A field type object defines common properties for all fields based on that type. The field type allows to
specify parameters related to field occurrence in an item like field repeatability or requirement. Some
properties activate various mechanisms related to field processing such as sorting or indexing. Other
properties affect validation logic adding, for example regular expression that every field value has to
match.

Field types have been classified into couple of groups called families. Currently, there are six families:

• VALUE_FIELD - fields of this family are the simplest field types in the system. They do not have
complicated logic associated with them. They just store textual value, which can be validated with
provided regular expression or primitive type.

• DICTIONARY_FIELD - fields of this family store references to terms contained in dictionaries.

• MANUAL_REFERENCE_FIELD - fields of this family store references to other items. These

references are set manually by user.

• AUTO_REFERENCE_FIELD - fields of this family are similar to MANUAL_REFERENCE_FIELD, except

that references to items are set automatically by the system. To find correct items, system uses
supplied by the user search query.

• USER_REFERENCE_FIELD - fields of this family are similar to MANUAL_REFERENCE_FIELD, except

they allow to reference any user of the system.

• VIRTUAL_FIELD - the most advanced field type family. Values for fields of this family are created
automatically based on supplied formula. They are virtual, because they are not stored in the
system, but instead created only when item is being retrieved. This family is commonly used in
cases where some information exists in one item and is also relevant to other item. Administrative
user can configure virtual field to copy that value from one item to another, and thus free other
users from having to view two separate items. To learn more about virtual field capabilities, see
Virtual Field Formula.

For the purpose of this documentation, following naming convention is used: field types having
VALUE_FIELD family are simply called value field types, field types having DICTIONARY_FIELD family
are called dictionary field types and so on.

58
 Tibigen Digital Repository - REST API

Example of simple representation of value field type

<field-type name="prog_title"
            family="VALUE_FIELD"
            indexed="true"
            merge="false"
            primitive-type="STRING"
            pattern="[A-Z]"
            repeatable="true"
            required="true"
            sequence="false"
            sorted="false"
            translatable="true"
            unique="false"
            version="0" />

Example of detailed representation of value field type

<field-type name="prog_title"
            family="VALUE_FIELD"
            indexed="true"
            merge="false"
            primitive-type="STRING"
            pattern="[A-Z]"
            repeatable="true"
            required="true"
            sequence="false"
            sorted="false"
            translatable="true"
            unique="false"
            version="0">
    <labels>
        <label lang="EN" value="Title" />
    </labels>
</field-type>

Detailed representation for field types of all families adds labels to the simple representation. In case
of virtual field types, also virtual field formula is added.

Table 23. Field Type properties common for all families

59
 Tibigen Digital Repository - REST API

Name Type Description

name string A name of this field type. The name is string identifier and
thus has to comply to naming convention described in String
Identifier. Also, the name has to be unique among other field
types. Required.

family string One of:

- VALUE_FIELD - field containing any text value,
- DICTIONARY_FIELD - field containing reference to
dictionary term,
- MANUAL_REFERENCE_FIELD - field containing manually
selected reference to item,
- AUTO_REFERENCE_FIELD - field containing reference to
item, selected automatically based on supplied search query.
- USER_REFERENCE_FIELD - field containing manually
selected user reference,
- VIRTUAL_FIELD - field containing value created based on
formula.
Default value is VALUE_FIELD.

required boolean If true, at least one field of this type must occur in item.
Default value is false.

repeatable boolean The flag that indicates if fields based on this type can be
repeatable (if metadata tree can have multiple instances of
the same field type). Default value is false.

sorted boolean If true and multiple fields of this type exist in item, fields
will be sorted by value in natural order. Default value is
false.

indexed boolean If true, fields of this type will be indexed by search engine
and then can be searched. Default value is true.

version integer A version of this field type for optimistic locking purposes.
Starting value is 0.

sequence boolean If true, field of this type can be attached to specific timecode
interval in a video or audio timeline. Technically speaking,
system allows to set field’s timecode-start and timecode-stop
properties. Default value is false.

unique boolean If true, each value of field of this type must be unique among
other fields of this type in the entire system. Default value is
false.

labels Label List A list of labels in different languages.

merge boolean Deprecated property.

Table 24. Value Field Type properties

60
 Tibigen Digital Repository - REST API

Name Type Description

translatable boolean A flag that indicates if field value has different

representation in different languages. For example value 43,
which can indicate duration in seconds, has exactly the
same representation in most languages, so translatable flag
should be set to false. That information is later used within
Create Language Version Process - non translatable field
values are copied "as is" to the new language version.

pattern string A regular expression that will be used to validate values of

fields based on this field type. System will return error, if
field value does not match given regular expression.

primitive-type string Defines what type of data will be stored in the field value.
That information is later used in TDR to optimize certain
operations. Allowed values are:
- STRING - string value e.g. sample value,
- INT - integer value e.g. 43,
- DOUBLE - floating point number e.g. 43.789,
- DATE - date in format yyyy-MM-dd e.g. 2015-12-10,
- DATE_TIME - date and time in format yyyy-MM-dd
HH:mm:ss e.g. 2015-12-10 15:05:20.
Default value is STRING.

Example of representation of dictionary field type

<field-type name="prog_channel"
            family="DICTIONARY_FIELD"
            dictionary="7012f478-82cf-4165-bd9e-1a9a389c6f7e"
            indexed="true"
            repeatable="false"
            required="true"
            sequence="false"
            sorted="false"
            unique="false"
            version="0" />

Table 25. Dictionary Field Type properties

Name Type Description

dictionary uuid An UUID of dictionary which terms will be valid values of

fields based on this field type.

61
 Tibigen Digital Repository - REST API

Example of representation of manual reference field type

<field-type name="prog_guest"
            family="MANUAL_REFERENCE_FIELD"
            query="attr.item_type:person"
            indexed="true"
            repeatable="true"
            required="false"
            sequence="true"
            sorted="false"
            unique="false"
            version="0" />

Example of representation of auto reference field type

<field-type name="prog_guest"
            family="AUTO_REFERENCE_FIELD"
            query="attr.item_type:(person) AND attr.reference:{this.uuid}"
            indexed="true"
            repeatable="true"
            required="false"
            sequence="true"
            sorted="false"
            unique="false"
            version="0" />

Table 26. Auto and Manual Reference Field Type properties

Name Type Description

query string A search query that conforms to query syntax described in

Queries. Query set in auto reference field types may contain
additional placeholder {this.uuid}, that will be replaced
before query execution. The replacement is UUID of item in
which field of this type resides.

62
 Tibigen Digital Repository - REST API

Example of representation of user reference field type

<field-type name="prog_editor"
            family="USER_REFERENCE_FIELD"
            indexed="true"
            repeatable="true"
            required="false"
            sequence="true"
            sorted="false"
            unique="false"
            version="0" />

Example of detailed representation of virtual field type

<field-type name="prog_video_format"
            family="VIRTUAL_FIELD"
            indexed="true"
            repeatable="false"
            required="false"
            sequence="false"
            sorted="false"
            unique="false"
            version="0" >
    <formula field-source="DEFAULT_CHILD" operation="COPY">
      <field-type name="file_video_format" pattern=".*"/>
    </formula>
    <labels>
      <label lang="PL" value="Video Format"/>
    </labels>
</field-type>

Table 27. Virtual Field Type properties

Name Type Description

formula Virtual Field A formula defining method of creating virtual fields.

Formula

3.2.6. Virtual Field Formula

When item is retrieved from REST API, the system looks for virtual field types defined in that item’s
schema. If any of the field types exist, system will process formulas contained in that virtual field types

63
 Tibigen Digital Repository - REST API

and enrich the item with new fields. The purpose of a virtual field formula object is to provide
instruction for virtual field processor, needed for creation of virtual fields.

The following algorithm is used when creating fields from virtual field types:

1. Virtual field processor searches for source fields in item/items designated by field-source property.
It can be parent item, children items or default child. The types of fields that are looked for, are
defined with Formula Source Field objects.

2. If designated items do not exist or non of the source fields were found, virtual field processor will
end its job.

3. If at least one source field was found, virtual field processor depending on operation property
executes next step.

a. If operation is COPY, processor for each source field will create virtual field having identical
value (or fragment of that value if pattern has been specified) and reference as source field.

b. If operation is JOIN, processor will retrieve all source field’s values (optionally cropping them
with pattern) and will join them together. The values will be separated by string defined in
separator property. Next, processor will create new virtual field type with value being that
concatenation.

c. If operation is ADD, processor will parse all source field’s values as numbers (or fragments of
them matching pattern) and will add them together. Next, processor will create virtual field
with value being that sum.

After creation, each virtual field is inserted into item in place where its type resides in schema.

Example of representation

<formula field-source="DEFAULT_CHILD" operation="COPY">

    <field-type name="file_video_format" pattern=".*"/>
</formula>

Table 28. Virtual Field Formula properties

Name Type Description

field-source string A field source designates item in which formula processor

will be searching for fields to process. One of:
- PARENT - parent item will be searched,
- CHILDREN - all of the children will be searched,
- DEFAULT_CHILD - default child will be searched.
Required.

64
 Tibigen Digital Repository - REST API

Name Type Description

operation string An operation to execute on source fields in order to create

virtual field. One of:
- COPY - copy values and references of source fields,
- JOIN - join values of source fields using separator specified
in separator property,
- ADD - parse values of source fields as numbers and add
them together. If field value is not a number, processor will
omit that value.
Required.

separator string A string used to separate multiple field values, if exist.

Default is empty string.

field-types Formula Source A list of objects designating what type of fields virtual field
Field list processor should look for. At least one required.

3.2.7. Formula Source Field

Formula source field object tells virtual field processor which type of fields should look for in source
items. It optionally provides regular expression pattern used to extract specific fragment of field’s
value.

Example of representation

<field-type name="file_video_format" pattern=".*"/>

Table 29. Formula Source Field properties

Name Type Description

name string A name of the field type to find. Required.

pattern string A pattern which will be used on found field value in order to
extract only specific part of the field value.

3.2.8. Field Type List

A field type list is container of Field Type objects.

65
 Tibigen Digital Repository - REST API

Example of representation

<field-types>
    <field-type name="prog_title"
                family="VALUE_FIELD"
                indexed="true"
                merge="false"
                primitive-type="STRING"
                pattern="[A-Z]"
                repeatable="true"
                required="true"
                sequence="false"
                sorted="false"
                translatable="true"
                unique="false"
                version="0" />
</field-types>

3.2.9. List item types

List item types.

Request

GET /metadata-item-
types?root={root}&family={family}&indexed={indexed}&detailed={detailed}

Query parameters

Name Type Description

root boolean If true, returns root item types. If false, returns non-root
item types.

family string If specifed, returns item types with this family.

indexed boolean If true, returns indexed item types. If false, returns non-
indexed item types.

detailed boolean If true, returns detailed representation of each item type in a

list. Default value is false.

66
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission view.schema.

Response
If successful, the response status code is 200 OK and body contains Item Type List object wrapped in
Response object.

3.2.10. Get item type

Get item type.

Request

GET /metadata-item-types/{name}&detailed={detailed}

Path parameters

Name Type Description

name string A name of the item type to get.

Query parameters

Name Type Description

detailed boolean If true, web-service returns detailed representation of the

item type. Default value is false.

Authorization
This request requires authorization with permission view.schema.

Response
If successful, the response status code is 200 OK and body contains Item Type object wrapped in
Response object.

Errors

Error code Status Description

code

ItemTypeNotFoundException 404 Cannot find item type with given name.

67
 Tibigen Digital Repository - REST API

3.2.11. Add item type

Add item type.

Request

POST /metadata-item-types

In the request body, supply a Item Type object with at least required properties.

Authorization
This request requires authorization with permission manage.schema.

Response
If successful, the response status code is 200 OK and body contains Value object wrapped in Response
object.

Errors

Error code Status Description

code

InvalidItemTypeNameExcepti 400 A name of the item type is invalid. The name must conform
on to rules described in String Identifier.

InvalidItemTypeFamilyExcep 400 The specified family of item type is invalid.

tion

DuplicatedLabelException 400 There are labels in the same language.

InvalidLabelTextException 400 Label text is not specified.

InvalidLabelLanguageExcepti 400 Label language is not specified.

on

LabelNotFoundException 404 There is not label in default system language.

LanguageNotFoundException 404 Language specified in label does not exist in the system.

ItemTypeAlreadyExistsExcept 409 Item type with given name already exists.

ion

OptimisticLockingException 409 Other user just updated this version of item type.

3.2.12. Update item type

Update item type.

68
 Tibigen Digital Repository - REST API

Request

PUT /metadata-item-types/{name}

Path parameters

Name Type Description

name string A name of the item type to update.

In the request body, supply an Item Type object with updated properties.

Authorization
This request requires authorization with permission manage.schema.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

InvalidItemTypeNameExcepti 400 A name of the item type is invalid. The name must conform
on to rules described in String Identifier.

InvalidItemTypeFamilyExcep 400 The specified family of item type is invalid.

tion

DuplicatedLabelException 400 There are labels in the same language.

InvalidLabelTextException 400 Label text is not specified.

InvalidLabelLanguageExcepti 400 Label language is not specified.

on

LabelNotFoundException 404 There is not label in default system language.

LanguageNotFoundException 404 Language specified in label does not exist in the system.

ItemTypeNotFoundException 404 Cannot find item type with given name.

OptimisticLockingException 409 Other user just updated this version of item type.

3.2.13. Delete item type

Delete item type.

69
 Tibigen Digital Repository - REST API

Request

DELETE /metadata-item-types/{name}

Path parameters

Name Type Description

name string A name of the item type to delete.

Authorization
This request requires authorization with permission manage.schema.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

ItemTypeInUseException 400 The item type is used by other components and therefore
cannot be deleted.

ItemTypeNotFoundException 404 Cannot find item type with given name.

3.2.14. List group types

Get a list of group types.

Request

GET /metadata-group-types&detailed={detailed}

Query parameters

Name Type Description

detailed boolean If true, web-service returns detailed representation of each

group type in a list. Default value is false.

Authorization
This request requires authorization with permission view.schema.

70
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains Group Type List object wrapped in
Response object.

3.2.15. Get group type

Get group type.

Request

GET /metadata-group-types/{name}&detailed={detailed}

Path parameters

Name Type Description

name string A name of the group type to get.

Query parameters

Name Type Description

detailed boolean If true, web-service returns detailed representation of the

group type. Default value is false.

Authorization
This request requires authorization with permission view.schema.

Response
If successful, the response status code is 200 OK and body contains Group Type object wrapped in
Response object.

Errors

Error code Status Description

code

GroupTypeNotFoundExceptio 404 Cannot find group type with given name.

n

3.2.16. Add group type

Add group type.

71
 Tibigen Digital Repository - REST API

Request

POST /metadata-group-types

In the request body, supply a Group Type object with at least required properties.

Authorization
This request requires authorization with permission manage.schema.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly added
group type wrapped in Response object.

Errors

Error code Status Description

code

InvalidGroupTypeNameExce 400 A name of the group type is invalid. The name must conform
ption to regex ^[a-zA-Z_0-9]+$.

InvalidLabelTextException 400 Label text is not specified.

InvalidLabelLanguageExcepti 400 Label language is not specified.

on

DuplicatedLabelException 400 There are multiple labels in the same language.

LabelNotFoundException 404 There is no label in default system language.

GroupTypeAlreadyExistsExce 409 Group type with given name already exists.

ption

OptimisticLockingException 409 Other user just updated this version of group type.

3.2.17. Update group type

Update group type.

Request

PUT /metadata-group-types/{name}

Path parameters

72
 Tibigen Digital Repository - REST API

Name Type Description

name string A name of group type to update.

In the request body, supply a Group Type object with updated properties.

Authorization
This request requires authorization with permission manage.schema.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

InvalidGroupTypeNameExce 400 A name of the group type is invalid. The name must conform
ption to regex ^[a-zA-Z_0-9]+$.

InvalidLabelTextException 400 Label text is not specified.

InvalidLabelLanguageExcepti 400 Label language is not specified.

on

DuplicatedLabelException 400 There are multiple labels in the same language.

LabelNotFoundException 404 There is no label in default system language.

GroupTypeNotFoundExceptio 404 Cannot find group type with given name.

n

OptimisticLockingException 409 Other user just updated this version of group type.

3.2.18. Delete group type

Delete group type.

Request

DELETE /metadata-group-types/{name}

Path parameters

Name Type Description

name string A name of group type to delete.

73
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission manage.schema.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

GroupTypeNotFoundExceptio 404 Cannot find group type with given name.

n

GroupTypeInUseException 400 The group type is used by other components and therefore
cannot be deleted.

3.2.19. List field types

List field types.

Request

GET /metadata-field-types?family={family}&referenced-field-
type={type}&page={page}&size={size}&detailed={detailed}

Query parameters

Name Type Description

family string If virtual and referenced-field-type is specified, web-service

returns list of the virtual field types using in their formulas
field type specified as references-field-type.

referenced-field-type string The name of the field type which is used in formulas of
virtual field types.

page integer The number of page of results to return. If not specified,

web-service returns all field types.

size integer The size of the page of results. Default value is 10.

detailed boolean If true and family and referenced-field-type are not

specified, web-service returns detailed representation of
each field type in a list. Otherwise simple representation is
returned. Default value is false.

74
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission view.schema.

Response
If successful, the response status code is 200 OK and body contains Field Type List object wrapped in
Response object.

3.2.20. Get field type

Get field type.

Request

GET /metadata-field-types/{name}?detailed={detailed}

Path parameters

Name Type Description

name string A name of the field type to get.

Query parameters

Name Type Description

detailed boolean If true, web-service returns detailed representation of the

field type. Default value is false.

Authorization
This request requires authorization with permission view.schema.

Response
If successful, the response status code is 200 OK and body contains Field Type object wrapped in
Response object.

Errors

Error code Status Description

code

FieldTypeNotFoundException 404 Cannot find field type with given name.

75
 Tibigen Digital Repository - REST API

3.2.21. Add field type

Add new field type.

Request

POST /metadata-field-types

In the request body, supply a Field Type object at least with required properties.

Authorization
This request requires authorization with permission manage.schema.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly added
field type, wrapped in Response object.

Errors

Error code Status Description

code

InvalidFieldTypeFamilyExcep 400 Family is not given or is invalid.

tion

InvalidFieldTypeNameExcept 400 A name of the field type is invalid. The name must conform
ion to rules described in String Identifier.

DuplicatedLabelException 400 There are labels in the same language.

InvalidFieldTypeSearchQuer 400 Search query is not specified in case of auto and manual
yException reference fields.

InvalidFieldTypeDictionaryU 400 Dictionary UUID is not specified in case of dictionary field.

uidException

InvalidUuidFormatException 400 Invalid UUID format of dictionary UUID or

InvalidFieldTypeDefaultValu 400 In case of manual reference field, UUID of item reference is

eException empty. In case of dictionary field, specified term is not in the
dictionary.

InvalidFieldTypePrimitiveExc 400 Primitive type is not specified or is invalid in case of value

eption field.

InvalidFieldTypeDefaultValu 400 There is too many default values. Only value field allows to
eNumberException define multiple default values.

76
 Tibigen Digital Repository - REST API

Error code Status Description

code

DuplicatedDefaultValuesExce 400 There are multiple default values for the same language in
ption case of value field.

InvalidRegexException 400 Regular expression has invalid format in case of value field.

InvalidFormulaFieldSourceE 400 Field source is not specified or is invalid.

xception

InvalidFormulaOperationExc 400 Operation in formula of virtual field is not specified or is

eption invalid.

InvalidFormulaSourceFieldsE 400 None of the source fields have been specified.

xception

RecursiveFormulaDetectedEx 400 Formula contains field type of this field in case of virtual
ception field.

LabelNotFoundException 404 There is no label in default system language.

DictionaryNotFoundExceptio 404 Dictionary referenced by dictionary field does not exist.

n

FieldTypeNotFoundException 404 One of the field types used in formula of virtual field does
not exist.

ItemNotFoundException 404 Item references in default value of manual reference field

does not exist.

FieldTypeAlreadyExistsExcep 409 Field type with given name already exists.

tion

3.2.22. Update field type

Update field type.

Request

PUT /metadata-field-types/{name}

Path parameters

Name Type Description

name string A name of the field type to update.

In the request body, supply a Field Type object with updated properties.

77
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission manage.schema.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

InvalidFieldTypeFamilyException 400 Family is not given or is invalid.

InvalidFieldTypeNameException 400 A name of the field type is invalid. The name

must conform to rules described in String
Identifier.

DuplicatedLabelException 400 There are labels in the same language.

InvalidFieldTypeSearchQueryException 400 Search query is not specified in case of auto

and manual reference fields.

InvalidFieldTypeDictionaryUuidException 400 Dictionary UUID is not specified in case of

dictionary field.

InvalidUuidFormatException 400 Invalid UUID format of dictionary UUID or

InvalidFieldTypeDefaultValueException 400 In case of manual reference field, UUID of

item reference is empty. In case of dictionary
field, specified term is not in the dictionary.

InvalidFieldTypePrimitiveException 400 Primitive type is not specified or is invalid in

case of value field.

InvalidFieldTypeDefaultValueNumberExcept 400 There is too many default values. Only value

ion field allows to define multiple default values.

DuplicatedDefaultValuesException 400 There are multiple default values for the

same language in case of value field.

InvalidRegexException 400 Regular expression has invalid format in

case of value field.

InvalidFormulaFieldSourceException 400 Field source is not specified or is invalid.

InvalidFormulaOperationException 400 Operation in formula of virtual field is not

specified or is invalid.

InvalidFormulaSourceFieldsException 400 None of the source fields have been

specified.

78
 Tibigen Digital Repository - REST API

Error code Status Description

code

RecursiveFormulaDetectedException 400 Formula contains field type of this field in

case of virtual field.

LabelNotFoundException 404 There is no label in default system language.

DictionaryNotFoundException 404 Dictionary referenced by dictionary field

does not exist.

FieldTypeNotFoundException 404 Cannot find field type with given name. In

case of virtual field, one of the field types
used in formula of does not exist.

ItemNotFoundException 404 Item references in default value of manual

reference field does not exist.

3.2.23. Delete field type

Delete field type.

Request

POST /metadata-field-types/{name}

Path parameters

Name Type Description

name string A name of the field type to delete.

Authorization
This request requires authorization with permission manage.schema.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

FieldTypeInUseException 400 The field type is used by other components and therefore
cannot be deleted.

FieldTypeNotFoundException 404 Cannot find field type with given name.

79
 Tibigen Digital Repository - REST API

3.3. Metadata Schemas

Metadata schema object binds together item, group and field types to create template for metadata
items. Schema contains structure of metadata and relationship between individual metadata entry
types. One schema must correspond to single item type. There is no way to define multiple schemas for
it. When new item is added, system validates that item in context of its schema.

Schema can be modified during a lifetime of the system. When new metadata entry type will be added
to schema, system will allow for entries of that type in items. On the other hand, when metadata entry
will be deleted from schema, all metadata entries of that type will remain intact. However, at the next
item update, system will do not let for that operation until all obsolete metadata entries will be
removed. This behavior let user to migrate data that are no longer consistent with the schema.

Metadata schema also has so-called title formula which is used during metadata item creation or
update to recreate item’s title. For more details, see Title Formula.

3.3.1. Schema
Example of simple representation

<schema name="tv_series" version="0"/>

Example of detailed representation

<schema name="tv_series" version="0">

    <children>
        <item-type name="episode"/>
    </children>
    <item-type name="programme">
        <field-type name="title"/>
        <group-type name="rating">
            <field-type name="rating_system"/>
            <field-type name="rating_value"/>
        </group-type>
    </item-type>
    <title-formula value="{1}">
        <parameter field-type="title" separator=" "/>
    </title-formula>
</schema>

Table 30. Schema properties

80
 Tibigen Digital Repository - REST API

Name Type Description

name string The name of this schema. Required.

version integer A version of this schema for optimistic locking purposes.

children Item Type list A list of item types, which can be children of item type that
this schema defines.

item-type Item Type Item type defined by this schema. Required.

title-formula Title Formula The definition of title formula for this schema. If not
specified, default title formula will be generated i.e. default
title formula will generate title identical to schema name.

3.3.2. Schema List

A schema list is container of Schema objects.

Example of representation

<schemas>
    <schema name="tv_series" version="0" />
</schemas>

3.3.3. Title Formula

Each item in TDR has its own title. The title is built automatically on item addition and item update
based on a title formula. The title formula describes how to create title using static template with
placeholders, that at the moment of title creation, are replaced with actual values of metadata fields.

A value property defines above mentioned static template. This template can contain any character
besides curly braces {}, which indicate the beginning and the end of placeholder parameter. The
placeholder parameters are numbered starting from 1 and can occur in any order.

To bind actual field to the placeholder, a parameter should be defined. A field-type property of the
parameter points to the type of field, that will be used to resolve template. When there will be multiple
fields of this type in item, all values will be separated with separator defined in separator property and
concatenated to create final replacement of placeholder.

The order in which parameters are defined is important and should correspond to numbering of
placeholders in template.

Example
Lets assume we have a title formula:

81
 Tibigen Digital Repository - REST API

<title-formula value="The {1} {2}">

    <parameter field-type="title" separator=" "/>
    <parameter field-type="subtitle" separator=", "/>
</title-formula>

When we add following item:

<item>
    <field type="title">Foo</field>
    <field type="subtitle">Bar1</field>
    <field type="subtitle">Bar2</field>
</item>

this item will receive title The Foo Bar1, Bar2.

Example of representation

<title-formula value="{1} - TV Series">

    <parameter field-type="title" separator=" "/>
</title-formula>

Table 31. Title Formula properties

Name Type Description

value string The static title template, which can contain any number of
placeholders in form of {N}, where N is a sequential number
of parameter starting from 1.

parameters Title Formula A list of parameters which bind placeholders with field
Parameter list types.

3.3.4. Title Formula Parameter

A title formula parameter is used to bind placeholder in the title formula template to the values of field
in item.

Example of representation

<parameter field-type="title" separator=" "/>

Table 32. Title Formula Parameter properties

82
 Tibigen Digital Repository - REST API

Name Type Description

field-type string A type of field that will be searched in item in order to get its
value and replace placeholder.

separator string A string which will separate multiple values of field, in case
of property field-type pointing to repeatable field type.

3.3.5. Metadata Types

A metadata types object is list containing different metadata entry types i.e. item types, group types,
field types.

Example of representation

<metadata-types>
    <field-type family="VALUE_FIELD" indexed="true" merge="false" name="prog_actor"
pattern=""
                primitive-type="STRING" repeatable="true" required="false" sequence="false"
sorted="false"
                translatable="false" unique="false" version="2"/>

    <group-type name="prog_actors" repeatable="true" sequence="false" version="1"/>

    <item-type family="METADATA_ITEM" indexed="true" name="programme" repeatable=

"false" root-item="true"
                   sequence="false" version="0"/>
</metadata-types>

Table 33. Metadata Types properties

Name Type Description

field-types Field Type list A list of field type objects.

group-types Group Type list A list of group type objects.

item-types Item Type list A list of item type objects.

3.3.6. List schemas

Return list of all schemas. Schemas are ordered by name.

Request

83
 Tibigen Digital Repository - REST API

GET /metadata-schemas?item-type={type}&item-type-family={family}&item-type-
root={root}&page={page}&size={size}&detailed={detailed}

Query parameters

Name Type Description

item-type string If specified, returns schema for given item type. An item
type can have only one schema, and thus returned list will
always contain zero or one element.

item-type-family string If specified, returns schemas for item types having given
family. Allowed values are METADATA_ITEM and
FILE_ITEM.

item-type-root boolean If specified, returns schemas for item types being root item
types.

page integer The number of page of results to return. If not specified,

returns all schemas.

size integer The size of the page of results. Default value is 10.

detailed boolean If false, returns simple representation of schemas.

Otherwise returns full representations of schemas e.g.
schemas with all entries and title formulas with all
parameters.

Authorization
This request requires authorization with permission view.schema.

Response
If successful, the response status code is 200 OK and body contains Schema List object wrapped in
Response object.

3.3.7. Get schema

Get schema.

Request

GET /metadata-schemas/{name}

84
 Tibigen Digital Repository - REST API

Path parameters

Name Type Description

name string A name of the schema to get.

Authorization
This request requires authorization with permission view.schema.

Response
If successful, the response status code is 200 OK and body contains Schema object wrapped in
Response object.

Errors

Error code Status Description

code

SchemaNotFoundException 404 Cannot find schema with given name.

3.3.8. Add schema

Add schema.

Request

POST /metadata-schemas

In the request body, supply a Schema object with at least required properties.

Authorization
This request requires authorization with permission manage.schema.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly added
schema wrapped in Response object.

Errors

85
 Tibigen Digital Repository - REST API

Error code Status Description

code

AssociatedSchemaAlreadyExi 400 Schema for that item type already exists.

stsException

InvalidSchemaNameExceptio 400 The name of the schema is empty or not specified.

n

InvalidSchemaItemTypeExce 400 The root item type not specified.

ption

InvalidSchemaRootEntryExce 400 A specified root entry type is not item type.

ption

SchemaRelationshipNotAllow 400 Schema contains forbidden relation e.g. group type contains
edException item type.

InvalidTitleFormulaValueExc 400 The value of title formula is invalid.

eption

InvalidTitleFormulaParamete 400 The title formula value contains more placeholders than
rNumberException number of parameters specified.

InvalidTitleFormulaFieldTyp 400 The title formula is using entry types which do not occur in
eException schema.

InvalidItemTypeException 400 A name of item type is empty or not specified.

InvalidGroupTypeException 400 A name of group type is empty or not specified.

InvalidFieldTypeException 400 A name of field type is empty or not specified.

SchemaNotFoundByItemType 404 The schema references to schema that cannot be found.

Exception

ItemTypeNotFoundException 404 Cannot find item type defined in schema.

GroupTypeNotFoundExceptio 404 Cannot find group type defined in schema.

n

FieldTypeNotFoundException 404 Cannot find field type defined in schema.

SchemaAlreadyExistsExcepti 409 Schema with given name already exists.

on

3.3.9. Update schema

Update schema.

Request

PUT /metadata-schema/{name}

86
 Tibigen Digital Repository - REST API

Path parameters

Name Type Description

name string A name of the schema to update.

In the request body, supply a Schema object with updated properties.

Authorization
This request requires authorization with permission manage.schema.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

AssociatedSchemaAlreadyExi 400 Schema for that item type already exists.

stsException

InvalidSchemaNameExceptio 400 The name of the schema is empty or not specified.

n

InvalidSchemaItemTypeExce 400 The root item type not specified.

ption

InvalidSchemaRootEntryExce 400 A specified root entry type is not item type.

ption

SchemaRelationshipNotAllow 400 Schema contains forbidden relation e.g. group type contains
edException item type.

InvalidTitleFormulaValueExc 400 The value of title formula is invalid.

eption

InvalidTitleFormulaParamete 400 The title formula value contains more placeholders than
rNumberException number of parameters specified.

InvalidTitleFormulaFieldTyp 400 The title formula is using entry types which do not occur in
eException schema.

InvalidItemTypeException 400 A name of item type is empty or not specified.

InvalidGroupTypeException 400 A name of group type is empty or not specified.

InvalidFieldTypeException 400 A name of field type is empty or not specified.

SchemaNotFoundByItemType 404 The schema references to schema that cannot be found.

Exception

87
 Tibigen Digital Repository - REST API

Error code Status Description

code

ItemTypeNotFoundException 404 Cannot find item type defined in schema.

GroupTypeNotFoundExceptio 404 Cannot find group type defined in schema.

n

FieldTypeNotFoundException 404 Cannot find field type defined in schema.

SchemaNotFoundException 404 Cannot find schema with given name.

OptimisticLockingException 409 Other user just updated this version of schema.

3.3.10. Delete schema

Delete schema. Schema cannot be delete if items based on that schema exist.

Request

DELETE /metadata-schemas/{name}

Path parameters

Name Type Description

name string A name of the schema to delete.

Authorization
This request requires authorization with permission manage.schema.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

ReferencingSchemasExistExc 400 Other schemas referencing the schema, and therefore the
eption schema cannot be deleted.

SchemaNotFoundException 404 Cannot find schema with given name.

3.3.11. List types in schema

Get a list of all metadata entry types present in schema i.e. root item type, children item types, group

88
 Tibigen Digital Repository - REST API

and field types.

Request

GET /metadata-schemas/{name}/types

Path parameters

Name Type Description

name string A name of the schema which types will be returned.

Query parameters

Name Type Description

detailed boolean If true, returns detailed representation of each metadata

entry type in a list. Default value is false.

Authorization
This request requires authorization with permission view.schema.

Response
If successful, the response status code is 200 OK and body contains Metadata Types object wrapped in
Response object.

Errors

Error code Status Description

code

META_SCHEMA_NOT_FOUND 200 Cannot find schema with given name.

3.4. Metadata Entries

In TDR, user can build hierarchy of items. Each item can have its own parent and any number of
children. One of the children can be marked as default child, which can be used in various processes
operating on that item hierarchy. Inside the item, there is other hierarchy consisting of groups and
fields. Fields can store actal value or reference to other items or dictionary’s terms. There is also
possibility to configure virtual field which automatically build its value from other fields. TDR supports
multi-language data. Items can have multiple representations in languages defined in the system.

In TDR, user can attach files to items through asset objects. Also, selected items can be indexed for
searching purposes. Each item includes basic information about time of creation and modification and

89
 Tibigen Digital Repository - REST API

also logins of users which performed these operations. Items have unique identifiers (UUIDs). These
UUIDs can be assigned by user or generated automatically upon creation. Each item has title created
by the system based on title formula defined in schema.

3.4.1. Item
Example of simple representation

<item created="2015-07-24 11:33:48"

        creator="admin"
        default-item="false"
        files-attached="false"
        index-valid="true"
        language="PL"
        last-modified-by="admin"
        modified="2015-07-24 11:33:48"
        root-uuid="dd7d9923-2b08-416f-bfe3-9d1b5787fa07"
        schema-version="51"
        title="News"
        type="programme"
        type-version="0"
        uuid="dd7d9923-2b08-416f-bfe3-9d1b5787fa07"
        retention-policy="17dca7e3-5bff-4524-a69b-f163abafb343"
        version="0" />

Example of detailed representation

<item created="2015-07-24 11:33:48"

        creator="admin"
        default-item="false"
        files-attached="false"
        index-valid="true"
        language="PL"
        last-modified-by="admin"
        modified="2015-07-24 11:33:48"
        root-uuid="dd7d9923-2b08-416f-bfe3-9d1b5787fa07"
        schema-version="51"
        title="News"
        type="programme"
        type-version="0"
        uuid="dd7d9923-2b08-416f-bfe3-9d1b5787fa07"

90
 Tibigen Digital Repository - REST API

        retention-policy="17dca7e3-5bff-4524-a69b-f163abafb343"
        version="0" >
    <field created="2015-07-24 11:33:48"
            language="PL"
            modified="2015-07-24 11:33:48"
            owner-item="291aa91c-9f13-46e2-bcfc-c66471703edf"
            reference="7623f849-6f76-4469-8bb6-1a64fbfe9267"
            type="prog_title"
            type-version="0"
            uuid="34834695-bac1-4385-82b4-943d5208af3b"
            version="0">News</field>
    <group language="PL"
            type="prog_length"
            type-version="0"
            uuid="3481014e-c861-437a-bc34-6cea4da8262e"
            version="0">
        <field created="2016-01-25 10:54:44"
                language="PL" modified="2016-01-25 10:54:44"
                owner-item="291aa91c-9f13-46e2-bcfc-c66471703edf"
                type="prog_length_units"
                type-version="0"
                uuid="a1666883-88fa-4df5-8922-969ea68f272e"
                version="0">minutes</field>
        <field created="2016-01-25 10:54:44"
                language="PL"
                modified="2016-01-25 10:54:44"
                owner-item="291aa91c-9f13-46e2-bcfc-c66471703edf"
                type="prog_length_value"
                type-version="0"
                uuid="ea281148-6017-4066-8345-0225e2d3087d"
                version="0">12</field>
    </group>
</item>

Table 34. Item properties

Name Type Description

created datetime A time when this item was created.

creator string A login of the user who created this item.

91
 Tibigen Digital Repository - REST API

Name Type Description

default-item boolean A flag designating if this item is default item among its
siblings. By default first added child item becomes default.

files-attached boolean If true, item has attached one or more Assets.

index-valid boolean If true, item has created valid index in search engine and
therefore can appear in search results.

language string A name of the language of this item.

last-modified-by string A login of the user who for the last time modified this item.

modified datetime A time when this item was modified for the last time.

root-uuid uuid An UUID of root item in metadata tree.

schema-version integer A version of schema based on which this item has been
created or updated.

title string A title of this item generated based on title formula

contained in it’s schema.

type string A name of the type of this item. Required.

type-version integer A version of type based on which this item has been created
or updated.

uuid uuid An UUID of this item. If not specified, will be generated upon
creation.

retention-policy uuid An UUID of Retention Policy. Only Retention Policies of

LOCAL type can be set.

version integer A version of this item. Used for optimistic locking purposes.

3.4.2. Item List

An item list is container of Item objects.

92
 Tibigen Digital Repository - REST API

Example of representation

<items>
    <item created="2015-07-24 11:33:48"
            creator="admin"
            default-item="false"
            files-attached="false"
            index-valid="true"
            language="PL"
            last-modified-by="admin"
            modified="2015-07-24 11:33:48"
            root-uuid="dd7d9923-2b08-416f-bfe3-9d1b5787fa07"
            schema-version="51"
            title="News"
            type="programme"
            type-version="0"
            uuid="dd7d9923-2b08-416f-bfe3-9d1b5787fa07"
            retention-policy="17dca7e3-5bff-4524-a69b-f163abafb343"
            version="0" />
</items>

3.4.3. Group

93
 Tibigen Digital Repository - REST API

Example of representation

<group language="PL"
        type="prog_length"
        type-version="0"
        uuid="3481014e-c861-437a-bc34-6cea4da8262e"
        version="0">
    <field created="2016-01-25 10:54:44"
            language="PL" modified="2016-01-25 10:54:44"
            owner-item="291aa91c-9f13-46e2-bcfc-c66471703edf"
            type="prog_length_units"
            type-version="0"
            uuid="a1666883-88fa-4df5-8922-969ea68f272e"
            version="0">minutes</field>
    <field created="2016-01-25 10:54:44"
            language="PL"
            modified="2016-01-25 10:54:44"
            owner-item="291aa91c-9f13-46e2-bcfc-c66471703edf"
            type="prog_length_value"
            type-version="0"
            uuid="ea281148-6017-4066-8345-0225e2d3087d"
            version="0">12</field>
</group>

Table 35. Group properties

Name Type Description

language string A language of this group.

type string A name of the type of this group. Required.

type-version integer A version of type based on which this group has been
created or updated.

uuid uuid A UUID of this group.

version integer A version of this group. Used for optimistic locking purposes.

3.4.4. Field

94
 Tibigen Digital Repository - REST API

Example of representation

<field created="2016-01-25 10:54:44"

        language="PL" modified="2016-01-25 10:54:44"
        owner-item="291aa91c-9f13-46e2-bcfc-c66471703edf"
        type="prog_length_units"
        type-version="0"
        uuid="a1666883-88fa-4df5-8922-969ea68f272e"
        version="0">minutes</field>

Table 36. Field properties

Name Type Description

created datetime A time when this field was created.

language string A name of the language of this field.

modified datetime A time when this field was modified for the last time.

owner-item uuid An UUID of item which contains this field.

type string A name of the type of this field. Required.

type-version integer A version of type based on which this field has been created
or modified.

uuid uuid An UUID of this field.

version integer A version of this field. Used for optimistic locking purposes.

reference uuid An UUID of referenced object.

xml value string A value of this field.

3.4.5. Archival Item

95
 Tibigen Digital Repository - REST API

Example of representation

<archival-item created="2015-11-12 15:54:29"

                creator="admin"
                default-item="false"
                language="PL"
                last-modified-by="admin"
                modified="2015-12-18 13:57:24"
                root-uuid="1a85ca52-d164-4881-adfd-2e1c7ae99215"
                schema-version="58"
                title="News"
                type="programme"
                type-version="0"
                uuid="1a85ca52-d164-4881-adfd-2e1c7ae99215"
                version="0" />

All properties of archival item have the same meaning as for the item. The modified and last-modified-
by properties contain time when item has been archived and login of user who archived that item.

3.4.6. Item in CSV representation

Will be documented in future.

3.4.7. Item in Microsoft Excel representation

Will be documented in future.

3.4.8. Permission Checking

Get Item

Authorization of item operations is based on hierarchical permissions which includes permissions to

fields, groups and item. This means that item can be get in full form with all fields and groups or only
with subset of fields and groups limited by permissions.

Service checks three types of permissions:

• for item it is view.item.ITEM_TYPE, where ITEM_TYPE is a name of type of item, which we want to
get,

• for groups it is view.group.GROUP_TYPE, where GROUP_TYPE is a name of type of group which is

used in schema for this item.

• for fields it is view.field.FIELD_TYPE, where FIELD_TYPE is a name of type of field which is used in
schema for this item.

96
 Tibigen Digital Repository - REST API

For each of above permissions, service verifies field permission requirements using Metadata Content
Based Requirement Verifier. For example, some field from item can be get only if other field has value
specified in permission requirement. For more information, see Permission Requirements.

Determining the content of the resulting item is based on several principles:

• if there is permission to view item, then returned item will include its all descendants (fields and
groups),

• if there is permission to view field, then returned item will include this field and its all ancestors
(groups and item),

• if there is permission to view group, then returned item will include this group with all of its
descendants (fields and groups), and also its ancestors (groups and item),

• if there is no permission to view item or any field or any group in this item, then service won’t
return the item.

To explain exactly how permissions work for items we will use example of item with schema
presented below:

• item:movie

◦ field:title

◦ group:cast

▪ field:actor

▪ field:role

For this schema there are few possible scenarios based on above principles:

• if there is only permission view.item.movie, then returned item will include field title and whole
group cast with both fields: actor and role,

• if there is only permission view.group.cast, then returned item will include whole group cast with
both fields: actor and role,

• if there is only permission view.field.title, then returned item will include only one field title,

• if there is only permission view.field.actor, then returned item will include group cast, but with
only one field actor.

• if there is permission view.field.title and view.field.actor, then returned item will include field title
and group cast, but with only one field actor.

• if there is no permission for item of type movie or any field or group in schema movie, then error
will be returned.

Create and Update Item

Authorization in case of create and update operation on metadata entries works similar to rules
described in Get Item section. Operations like adding, updating and deleting individual fields and

97
 Tibigen Digital Repository - REST API

groups are authorized with common permission action - manage. For example, user will need
manage.field.title permission to update field title. For item, action manage is not appropriate, because
item cannot be deleted (item is always archived in TDR with Archive Item Process). To create or update
item, permission with action save is needed. When user want to add, change or delete LOCAL
Retention Policy in item, permission with action manage-retention is needed.

Summarizing, services check four types of permissions:

• for item it is save.item.ITEM_TYPE, where ITEM_TYPE is a name of type of item, which we want to
create or update,

• for add, change or delete retention policy in item it is manage-retention.item.ITEM_TYPE, where

ITEM_TYPE is a name of type of item, which we want to create or update,

• for groups it is manage.group.GROUP_TYPE, where GROUP_TYPE is a name of type of group which

we want to create, update or delete,

• for fields it is manage.field.FIELD_TYPE, where FIELD_TYPE is a name of type of field which we

want to create, update or delete.

As in case of item retrieval, Metadata Content Based Requirement Verifier is used to verify permission
requirements in scope of metadata entries. So, it is possible to, for example, reject update of the field, if
some other field has unexpected value.

These are principles used for authorizing of create, update and delete operations:

• if there is permission to save item, then item can be created or update and all fields and groups
contained in the item can be created, updated or deleted,

• if there is permission to manage field, then field with all its group ancestors can be created,
updated and deleted. In this case, item which contains this field can be created or updated,

• if there is permission to manage group, then group with all its group ancestors and descendants
can be created, updated and deleted. In this case, item which contains this group can be created or
updated,

• if there is no permission to save item or manage any field or any group in this item, then service
will return error.

Create, update and delete operations are aware of view permissions. In a situation where there is no
view permission for given entry, any operation on that entry will be rejected.

3.4.9. List items

Get list of items. The list can be filtered by types of fields/groups contained in item or by item type. Due
to the amount of data that can be returned by the service, query parameter page is required.

Request

98
 Tibigen Digital Repository - REST API

GET /metadata-items?field-type={type}&group-
type={type}&type={type}&page={page}&size={size}

Query parameters

Name Type Description

field-type string If specified, only items having this type of fields will be
returned.

group-type string If specified, only items having this type of groups will be
returned.

type string If true, only items having this type will be returned.

page integer The number of page of results to return. If not specified,

returns all matching items. Required.

size integer The size of the page of results. Default value is 10.

The query params field-type, group-type and type cannot be combined together.

Authorization
This request requires authorization with permission list.item.

Response
If successful, the response status code is 200 OK and body contains Item List object wrapped in
Response object.

Errors

Error code Status Description

code

InvalidQueryParamException 400 Query parameter page is not specified.

3.4.10. Get item

Get item.

Request

GET /metadata-items/{uuid}?detailed={detailed}

99
 Tibigen Digital Repository - REST API

Path parameters

Name Type Description

uuid uuid An UUID of the item to get.

Headers

Name Type Description

Accept-Language string A language of item to get.

Accept string Media type of item representation to get. Default is

application/xml. Other media types are also supported:
- text/csv - described in Item in CSV representation
- application/vnd.openxmlformats-
officedocument.spreadsheetml.sheet - known as Microsoft
Excel format, described in Item in Microsoft Excel
representation

Query parameters

Name Type Description

detailed boolean If true, returns detailed representation of item. Default value

is true.

Authorization
Authorization of item operations is described in [Permission Checking for Metadata].

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

ItemLangVersionNotFoundEx 404 Cannot find language version of item with given UUID.
ception

3.4.11. Get children items

Get simple representation of children items.

100
 Tibigen Digital Repository - REST API

Request

GET /metadata-items/{uuid}/children

Path parameters

Name Type Description

uuid uuid An UUID of item which children will be returned.

Headers

Name Type Description

Accept-Language string A language of item which children will be returned. Default

value is system default language.

Query parameters

Name Type Description

type string If specified, only children having this type will be returned.

Authorization
Authorization of this request is based on rule: if user has permission to view an item, he is also
permitted to view the item’s children in simple representations. Therefore, this request requires
authorization the same as Get item service.

Response
If successful, the response status code is 200 OK and body contains Item List object wrapped in
Response object.

Errors

Error code Status Description

code

ItemLangVersionNotFoundEx 404 Cannot find language version of item with given UUID.
ception

3.4.12. Add item

Add item in default system language. To create item in other language, use process Create Language
Version Process.

101
 Tibigen Digital Repository - REST API

Request

POST /metadata-items

Headers

Name Type Description

Content-Type string Media type of item representation to add. Default is

application/xml. Other media types are also supported:
- text/csv - described in Item in CSV representation
- application/vnd.openxmlformats-
officedocument.spreadsheetml.sheet - known as Microsoft
Excel format, described in Item in Microsoft Excel
representation

In the request body, supply an Item object with at least required properties.

Authorization
Authorization of item operations is described in Permission Checking.

Response
If successful, the response status code is 200 OK and body contains Value object with UUID of newly
added item, wrapped in Response object.

Errors

Error code Status Description

code

InvalidItemTypeException 400 A type of item is not specified.

InvalidGroupTypeException 400 A type of group is not specified.

InvalidFieldTypeException 400 A type of field is not specified.

InvalidTimecodeIntervalExce 400 Cannot set timecode interval wider than interval of parent
ption entry.

TimecodeNotAllowedExcepti 400 Cannot bind item/group/field to timecode interval. The

on item/group/field type have sequence property set to false.

DefaultItemAlreadyExistsExc 400 One of the siblings of added item is already default.

eption

RepeatableItemNotAllowedE 400 Sibling with the same type already exists. Type of this item
xception has repeatable property set to false.

102
 Tibigen Digital Repository - REST API

Error code Status Description

code

ParentItemExpectedExceptio 400 Cannot add item as root item. Type of this item has root-item
n property set to false.

ItemNotMatchSchemaExcepti 400 Item does not match its schema.

on

RequiredFieldMissingExcepti 400 Cannot find required field.

on

InvalidParentItemException 400 Schema of parent item does not allow to add this type of
children.

RepeatableGroupNotAllowed 400 Sibling with the same type already exists. Type of this group
Exception has repeatable property set to false.

FieldRegexMatchingExceptio 400 Field’s value does not match to regular expression defined in
n its type.

InvalidTermReferenceExcepti 400 Field is a dictionary field and its reference leads to term that
on not exists.

InvalidUuidFormatException 400 UUID used in reference has invalid format.

InvalidFieldReferenceExcepti 400 Field reference is not set.

on

ReferencedItemNotFoundExc 400 Field is a manual reference field and its reference leads to
eption item that not exists.

RepeatableFieldNotAllowedE 400 This field’s sibling with the same type already exists. Type of
xception this field has repeatable property set to false.

UniqueFieldAlreadyExistsExc 400 Other field of that type and the same value already exists in
eption the system. Type of this field has unique property set to true.

ItemTypeNotFoundException 404 Cannot find specified item type.

GroupTypeNotFoundExceptio 404 Cannot find specified group type.

n

FieldTypeNotFoundException 404 Cannot find specified field type.

ItemLangVersionNotFoundEx 404 Cannot find item specified as parent of this item.

ception

ItemLangVersionAlreadyExis 409 Item with given UUID and language already exists.
tsException

3.4.13. Update item

Update item.

103
 Tibigen Digital Repository - REST API

Request

PUT /metadata-items/{uuid}

Path parameters

Name Type Description

uuid uuid An UUID of item to update.

Headers

Name Type Description

Content-Language string The language of item to update. Default language is system default
language.

Content-Type string Media type of item representation to update. Default is

application/xml. Other media types are also supported:
- text/csv - described in Item in CSV representation
- application/vnd.openxmlformats-
officedocument.spreadsheetml.sheet - known as Microsoft Excel
format, described in Item in Microsoft Excel representation

In the request body, supply an Item object with updated properties.

Authorization
Authorization of item operations is described in Permission Checking.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

InvalidHeaderException 400 Content-Language header is not set.

InvalidItemTypeException 400 A type of item is not specified.

InvalidGroupTypeException 400 A type of group is not specified.

InvalidFieldTypeException 400 A type of field is not specified.

InvalidTimecodeIntervalExce 400 Cannot set timecode interval wider than interval of parent
ption entry.

104
 Tibigen Digital Repository - REST API

Error code Status Description

code

TimecodeNotAllowedExcepti 400 Cannot bind item/group/field to timecode interval. The

on item/group/field type have sequence property set to false.

DefaultItemAlreadyExistsExc 400 One of the siblings of added item is already default.

eption

RepeatableItemNotAllowedE 400 Sibling with the same type already exists. Type of this item
xception has repeatable property set to false.

ParentItemExpectedExceptio 400 Cannot add item as root item. Type of this item has root-item
n property set to false.

ItemNotMatchSchemaExcepti 400 Item does not match its schema.

on

RequiredFieldMissingExcepti 400 Cannot find required field.

on

InvalidParentItemException 400 Schema of parent item does not allow to add this type of
children.

RepeatableGroupNotAllowed 400 Sibling with the same type already exists. Type of this group
Exception has repeatable property set to false.

FieldRegexMatchingExceptio 400 Field’s value does not match to regular expression defined in
n its type.

InvalidTermReferenceExcepti 400 Field is a dictionary field and its reference leads to term that
on not exists.

InvalidUuidFormatException 400 UUID used in reference has invalid format.

InvalidFieldReferenceExcepti 400 Field reference is not set.

on

ReferencedItemNotFoundExc 400 Field is a manual reference field and its reference leads to
eption item that not exists.

RepeatableFieldNotAllowedE 400 This field’s sibling with the same type already exists. Type of
xception this field has repeatable property set to false.

UniqueFieldAlreadyExistsExc 400 Other field of that type and the same value already exists in
eption the system. Type of this field has unique property set to true.

ItemTypeNotFoundException 404 Cannot find specified item type.

GroupTypeNotFoundExceptio 404 Cannot find specified group type.

n

FieldTypeNotFoundException 404 Cannot find specified field type.

105
 Tibigen Digital Repository - REST API

Error code Status Description

code

ItemLangVersionNotFoundEx 404 Cannot find given item or item specified as parent of this
ception item.

OptimisticLockingException 409 Versions do not match. Other request already modified this
version of item.

3.4.14. List assets of item

Get list of assets attached to item.

Request

GET /metadata-items/{uuid}/assets?type-id={id}

Path parameters

Name Type Description

uuid uuid An identifier of item which assets will be returned.

Query parameters

Name Type Description

type-id integer Asset type id. If specified, only assets of this type will be
returned.

Authorization
This request requires authorization with permission view-files.item.ITEM_TYPE, where ITEM_TYPE is
name of type of the item, which has assets attached. Web service verifies asset type permission
requirements. Web service filters output list of assets and returns only that assets that user can view.

Response
If successful, the response status code is 200 OK and body contains Asset List object wrapped in
Response object.

3.4.15. Add asset to item

Add asset to item.

106
 Tibigen Digital Repository - REST API

Request

POST /metadata-items/{uuid}/assets

Path parameters

Name Type Description

uuid uuid An UUID of item to which asset will be added.

In the request body, supply a Asset object with at least required properties.

Authorization
This request requires authorization with permission manage-files.item.ITEM_TYPE where ITEM_TYPE
is name of the type of item to which asset will be added.

This service verifies asset type permission requirements. For more information see Permission
Requirement.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly
created asset, wrapped in Response object.

Errors

Error code Status Description

code

InvalidAssetTypeException 400 Asset type is not specified.

AssetTypeNotFoundExceptio 404 Cannot find given asset type.

n

3.4.16. Get media for item

Find first asset storing given media type, attached to given item or one of its descendants being on
default path. The notion default path refers to path in metadata tree consisting of default items on each
level of the tree. This web-service can be used, for example to locate video clip that is not necessarily
attached to given item, but may be attached to its default child. In that case, media-type path
parameter should be set to VIDEO.

Request

107
 Tibigen Digital Repository - REST API

GET /metadata-items/{uuid}/media/{media-type}

Path parameters

Name Type Description

uuid uuid An UUID of item for which media will be returned.

media-type string A media type of asset to find. The same as in Asset Type.

Authorization
This request requires authorization with permission view-files.item.ITEM_TYPE, where ITEM_TYPE is a
name of the type of item for which media should be returned.

Response
If successful, the response status code is 200 OK and body contains Asset object, wrapped in Response
object.

Errors

Error code Status Description

code

InvalidQueryParamException 400 Invalid media-type query parameter.

ItemNotFoundException 404 Cannot find item with given id.

MediaAssetNotFoundExcepti 404 There is not asset able to store given media type attached to
on given item or its descendants.

3.4.17. Get archival item

Get archival item. Currently, there is no method to acquire full list of archived items, so UUID has to be
known from some other source, for example job’s input.

Request

GET /metadata-archival-items/{uuid}

Path parameters

Name Type Description

uuid uuid An UUID of archival item to get.

108
 Tibigen Digital Repository - REST API

Headers

Name Type Description

Accept-Language string A language of archival item.

Authorization
This request requires authorization with permission list.item.

Response
If successful, the response status code is 200 OK and body contains Archival Item object, wrapped in
Response object.

3.4.18. Add EDL to item

Add EDL to item.

Request

POST /metadata-items/{uuid}/edl

Path parameters

Name Type Description

uuid uuid An UUID of item to which EDL will be added.

In the request body, supply a EDL object with at least required properties.

Authorization
This request requires authorization with permission manage-edl.item.ITEM_TYPE where ITEM_TYPE is
name of the type of item to which asset will be added.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly
created asset, wrapped in Response object.

Errors

Error code Status Description

code

ItemNotFoundException 404 Cannot find given item.

109
 Tibigen Digital Repository - REST API

Error code Status Description

code

EdlForItemAlreadyExistsExcepti 409 EDL for given item already exists.

on

EdlAlreadyExistsException 409 EDL with given UUID already exists.

3.4.19. Get EDL associated with item

Get EDL associated with item.

Request

GET /metadata-items/{uuid}/edl

Path parameters

Name Type Description

uuid uuid An identifier of item which EDL will be returned.

Authorization
This request requires authorization with permission view-edl.item.ITEM_TYPE, where ITEM_TYPE is
name of type of the item, which has EDL attached.

Response
If successful, the response status code is 200 OK and body contains EDL object wrapped in Response
object.

Errors

Error code Status Description

code

ItemNotFoundException 404 Cannot find given item.

EdlForItemNotFoundException 404 EDL for given item not exists.

3.5. Metadata Collections

Metadata collection objects are collections of items. The collections support pagination mechanism as
other lists in REST API. When created, collections are bind to their creators and by default are private.
To share collection with other users, creator or other privileged user has to change access to that
collection to public. Public collections are visible and can be modified by other users that have

110
 Tibigen Digital Repository - REST API

permissions to do so. At this moment, there is no possibility to share collection with specific user or
group of users. The collection has to be shared to all users, or kept as private.

Metadata collections preserve order of items added to them.

Metadata collections are core components in REST API and can be used in combination with other
services to execute batch actions on items.

3.5.1. Metadata Collection

Example of representation

<collection id="1"
            name="Sample collection"
            access="PRIVATE"
            creator="admin"
            last-modified-by="admin"
            total-entries="1" >
    <item>a99a1455-fbbe-4594-ba95-cf32ef69ecd1</item>
</collection>

Table 37. Metadata Collection properties

Name Type Description

id integer The unique identifier of this collection.

name string The name of this collection. Required.

access string One of:

- PRIVATE - collection visible to creator,
- PUBLIC - collection visible to other users.
Default value is PRIVATE.

creator string A login of the user who created collection.

last-modified-by string A login of the user who modified collection for the last time.

total-entries integer The number of all items in this collection.

items Metadata A list of collection entries.

Collection Entry list

3.5.2. Metadata Collection Entry

Metadata collection entry object stores reference to item (UUID).

111
 Tibigen Digital Repository - REST API

Example of representation

<item>a99a1455-fbbe-4594-ba95-cf32ef69ecd1</item>

Table 38. Metadata Collection Entry properties

Name Type Properties

xml value uuid The UUID of refered item.

3.5.3. Metadata Collection List

Metadata collection list is a container of Metadata Collection objects.

Example of representation

<collections total="1">
    <collection access="PRIVATE" creator="admin" id="1" last-modified-by="admin" name=
"Sample collection"/>
</collections>

Table 39. Metadata Collection List properties

Name Type Properties

total integer A total number of collections in TDR.

3.5.4. List collections

List collections.

Request

GET /metadata-collections?access={access}&page={page}&size={size}

Query parameters

Name Type Description

access string If specified, only collections with given access will be

returned.

page integer The number of page of results to return. If not specified,

service returns all matching collections.

size integer The size of the page of results. Default value is 10.

112
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission view.collection.own.

Response
If successful, the response status code is 200 OK and body contains Metadata Collection Entry object
wrapped in Response object.

3.5.5. Get collection

Get collection.

Request

GET /metadata-collections/{id}?page={page}&size={size}

Path parameters

Name Type Description

id integer An identifier of collection to get.

Query parameters

Name Type Description

page integer The number of page of collection entries to return. If not

specified, service returns collection with all entries.

size integer The size of the page of collection entries. Default value is 10.

Authorization
If creator of collection tries to get it or collection is public, authorization with permission
view.collection.own is required. Otherwise, required permission is view.collection.other-private.

Response
If successful, the response status code is 200 OK and body contains Metadata Collection object wrapped
in Response object.

Errors

113
 Tibigen Digital Repository - REST API

Error code Status Description

code

MetadataCollectionNotFound 404 Cannot find collection with given id.

Exception

3.5.6. Add collection

Add collection.

Request

POST /metadata-collections

In the request body, supply a Metadata Collection object with at least required properties.

Authorization
This request requires authorization with permission manage.collection.own.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly
created collection, wrapped in Response object.

Errors

Error code Status Description

code

DuplicatedItemInCollectionE 400 Multiple entries contain references to the same item.

xception

InvalidItemReferenceExcepti 400 One of the entries has empty reference.

on

ItemNotFoundException 404 Cannot find item with given reference.

3.5.7. Update collection

Update name and access of collection. This service does not allow you to change actual collection
entries. Use Add item to collection and Delete item from collection services instead.

Request

PUT /metadata-collections/{id}

114
 Tibigen Digital Repository - REST API

Path parameters

Name Type Description

id integer An identifier of collection to update.

In the request body, supply a Metadata Collection object with updated properties. The entries are
ignored and can be omitted in order to save some data transfer.

Authorization
If creator of the collection tries to update it or collection is public, authorization with permission
manage.collection.own is required. Otherwise, required permission is manage.collection.other-private.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

MetadataCollectionNotFound 404 Cannot find collection with given id.

Exception

3.5.8. Delete collection

Delete collection.

Request

DELETE /metadata-collections/{id}

Path parameters

Name Type Description

id integer An identifier of the collection to delete.

Authorization
If creator of the collection tries to delete it or collection is public, authorization with permission
manage.collection.own is required. Otherwise, required permission is manage.collection.other-private.

115
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status code Description

MetadataCollection 404 Cannot find collection with given id.

NotFoundExceptio
n

3.5.9. Add item to collection

Add item at the end of collection.

Request

POST /metadata-collections/{id}/items

Path parameters

Name Type Description

id integer An identifier of collection, to which item will be added.

In the request body, supply a Metadata Collection Entry object with UUID of item to add.

Authorization
If creator of the collection tries to add new item or collection is public, authorization with permission
manage.collection.own is required. Otherwise, required permission is manage.collection.other-private.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

InvalidItemReferenceExcepti 400 Collection entry has empty reference.

on

DuplicatedItemInCollectionE 400 Collection already contains this item.

xception

116
 Tibigen Digital Repository - REST API

Error code Status Description

code

ItemNotFoundException 404 Cannot find item with referenced UUID.

MetadataCollectionNotFound 404 Cannot find collection with given id.

Exception

3.5.10. Delete item from collection

Delete item from collection.

Request

DELETE /metadata-collections/{id}/items/{uuid}

Path parameters

Name Type Description

id integer An identifier of the collection, from which item will be

deleted.

uuid uuid An UUID of the item to delete from collection.

Authorization
If creator of the collection tries to delete item from it or collection is public, authorization with
permission manage.collection.own is required. Otherwise, required permission is
manage.collection.other-private.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

MetadataCollectionNotFound 404 Cannot find collection with given id.

Exception

4. Search
TDR search API allows users to effectively search through all metadata items added to the system. It
provides an extensive query syntax which allows to construct multiple conditions on item’s attributes

117
 Tibigen Digital Repository - REST API

and fields using different equality and join operators. Range queries and queries containing wildcards
are also possible. The query syntax and possible query operations are explained in Queries.

Queries can be easily saved for later use. Each user in TDR can have its own saved queries.
Furthermore, there is a possibility to save search result to a Metadata Collection object. This allows
users to flexibly define sets of metadata items, that will be later processed in some way in the system.

Besides saved queries, system allows to group multiple query conditions on metadata fields into
grouping criteria. Then, grouping criteria can be used in queries to simplify and increase readability of
queries in the user interface. Grouping criteria are described in Grouping Criteria.

The search API also provides faceting and suggestions for metadata fields and attributes.

4.1. Queries
TDR allows to create complex queries with multiple conditions and operators. It supports filter caching
mechanism which boost performance of certain queries. The search results can be sorted by metadata
item’s attributes and fields. There is also possibility to get suggestions for fields.

Query Syntax

TDR uses Solr as an internal index server and therefore query syntax is similar to Solr. However, there
are few changes that adapts query syntax to metadata model used in TDR.

A query consists of conditions in form of:

attr|field|group.<name>:<value>

where attr, field and group specify a kind of data from metadata item that will be searched. attr is item
attribute, field is field contained in item, group is grouping criteria. If none of these will be specified,
an attr will be assumed. A <name> parameter further clarify what exactly attribute, field or grouping
criteria will be searched. After a colon, a search value need to be passed, for example:

field.title:Foo

will match items containing field title with value Foo. The searched value can contain wildcard
character in any place on the value (at the beginning, in the middle or at the end), replacing any
number of characters:

field.title:*oo

The above query matches title fields with values Foo, Goo, Bamboo and so on. If searched value
consists of multiple keywords separated by whitespaces, it should be enclosed with double quotes:

118
 Tibigen Digital Repository - REST API

field.title:"Foo Bar"

Conditions can be joined together with AND and OR operators (upper case only). To define order in
which conditions are resolved, curved brackets should be used. Query syntax supports range queries:

field.length:[2 TO 4]

The above query matches all fields named length having values 2, 3 or 4. TDR reuses Solr’s date time
format which looks like below:

attr.created:2015-01-02T09\:03\:25.543Z

As colons (:) are special characters in query (they are separating field name and field value), they need
to be escaped when used in field value. In the date format millisecond part is optional and can be
removed. Below query is also valid:

attr.created:2015-01-02T09\:03\:25Z

The date time can also be used in range queries.

These are valid attributes of metadata item that can be searched: lang, item_type, created, uuid,
modified, root_uuid, title, created_by, hierarchy, modified_by, item_type_label, file_type. Field names
corresponds to field type names defined in TDR. Groups are named just like defined grouping criteria.

Sort Syntax

The content of sort query parameter contains:

attr|field.<value> [<direction>]

where attr and field have the same meaning as in a query syntax - value can be metadata item’s
attribute name or field name. The direction is sort ordering which can be asc for ascending ordering
and desc for descending ordering. When direction is not specified, default value is asc.

Multiple sort orderings can be separated by commas, i.e:

field.title asc,attr.created desc

Filter Query Caching

119
 Tibigen Digital Repository - REST API

To boost your queries performance, logical query to the system should be split into two sub-queries:
query and filter query. All items that match filter query will be cached by search engine. If user will
execute another query with exactly the same filter query, there will be cache hit and results will be
immediately returned from the cache instead of searching them in an index.

Filter query should only be used for static or rarely changing conditions. All frequently changing filters
should be applied directly to plain query.

4.1.1. Facet List

A facet list contains facets that are the most common values in given field in order of occurrence.

Example of representation

<facets>
    <facet>2013</facet>
    <facet>2014</facet>
    <facet>2010</facet>
    <facet>2015</facet>
    <facet>2011</facet>
    <facet>2012</facet>
    <facet>1986</facet>
    <facet>2005</facet>
    <facet>2007</facet>
</facets>

4.1.2. Suggestion List

A suggestion list contains possible values for given fields. The algorithm of suggesting values for
multiple fields is as follows:

1. For each field find list of values with the biggest number of occurrences.

2. Concatenate these lists to create one common list of suggestions.

3. Sort common list by number of occurrences in descending order.

4. Get maximum 10 suggestions from the beginning of the list.

120
 Tibigen Digital Repository - REST API

Example of representation

<suggestions>
    <suggestion word="2014"/>
    <suggestion word="2013"/>
    <suggestion word="2015"/>
    <suggestion word="2011"/>
    <suggestion word="2012"/>
    <suggestion word="2010"/>
    <suggestion word="2009"/>
    <suggestion word="2008"/>
    <suggestion word="2007"/>
    <suggestion word="2006"/>
</suggestions>

4.1.3. Search
Get results of search.

Request

GET /search?q={query}&fq={filter-query}&sort={sort}&start={start}&rows={rows}&fl={field-
list}

Query parameters

Name Type Description

q string A query that restricts items returned by filter query. Format

of the query is described in Queries.

fq string A query that restricts set of all items. Then, items can be
narrowed down be q parameter. Results of this query are
internally cached to boost search performance. Format of
the query is described in Queries.

sort string A comma separated list of sort orderings. A format of these

orderings is described in Queries.

start integer The first result to return. If not specified, results will be
returned beginning from result 0.

rows integer The number of results to returned. Default value is 10.

121
 Tibigen Digital Repository - REST API

Name Type Description

fl string A comma separated list of item’s field and attributes to

return.

The query params: q, fq and sort have to be properly URL encoded.

Authorization
This request requires authorization with permission query.index.

Response
If successful, the response status code is 200 OK and body contains Item List wrapped in Response
object.

Errors

Error code Status Description

code

InvalidQueryException 400 The specified queries have invalid format.

4.1.4. Create collection from search results

Create collection from search results. This service works as search but instead of returning item list,
saves it to a collection.

Request

POST /search?q={query}&fq={filter-query}

Query parameters

Name Type Description

q string A query that restricts items returned by filter query. Format

of the query is described in Queries.

fq string A query that restricts set of all items. Then, items can be
narrowed down by q parameter. Results of this query are
internally cached to boost search performance. Format of
the query is described in Queries.

The q and fq parameters have to be properly URL encoded.

122
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permissions query.index and manage.collection.own.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly
created collection, wrapped in Response object.

Errors

Error code Status Description

code

InvalidQueryException 400 The specified queries have invalid format.

4.1.5. Get facets

Get list of facets. Facets provides list of the most common values in specified field.

Request

GET /search/facets?q={query}&fq={filter-query}&limit={limit}&field={field}&prefix={prefix}

Query parameters

Name Type Description

q string A query that restricts items returned by filter query. Format

of the query is described in Queries section. Results of this
query are basis for facet calculations.

fq string A query that restricts set of all items. Then, items can be
narrowed down be q parameter. Results of this query are
internally cached to boost search performance. Format of
the query is described in Queries section.

limit integer This parameter indicates maximum number of facet counts

to return. A negative value means unlimited.

field string This parameter allows you to specify an item’s field or

attribute which should be treated as a facet. It will iterate
over each value in the field or attribute and generate a facet
count using that value as constraint. A format of this
parameter is similar to that used in queries: `attr

field.<name>`. More prefix string

details in Queries
section.

123
 Tibigen Digital Repository - REST API

The query parameters: q and fq have to be properly URL encoded.

Authorization
This request requires authorization with permission query.index.

Response
If successful, the response status code is 200 OK and body contains Facet List wrapped in Response
object.

Errors

Error code Status Description

code

InvalidQueryException 400 The specified queries have invalid format.

4.1.6. Get suggestions

Return list of suggestions for given item’s attribute of field. Suggestions are created based on values of
those attributes or fields, currently stored in the system. These web-service is able to provide
suggestions for multiple attributes/fields at once.

Request

GET /search/suggestions?prefix={prefix}&fields={fields}&language={language}

Query parameters

Name Type Description

prefix string Only suggestions starting with this prefix will be returned.

fields string A comma separated list of fields or attributes for which

suggestions will be returned, for example
attr.title,field.prog_original_title. For item’s attributes use
prefix attr. and attribute name. For fields user prefix field.
and name of the field type.

language string Only suggestions in given language will be returned. If

language is null, suggestions will be returned in default
language.

Authorization
This request requires authorization with permission query.index.

124
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains Suggestion List wrapped in
Response object.

4.2. Saved Queries

Every query executed through search web-service can be persisted for later use. Saved Query
represents such a query. As described in Search, query can be fragmented into two sub-queries (query
and filter query) to boost search performance. Saved Query object supports that fragmentation.

Saved queries must be attached to the user by specifying user property.

4.2.1. Saved Query

Example of simple representation

<saved-query id="1"
             name="All episodes produced after 2000" />

Example of detailed representation

<saved-query id="1"
             name="All episodes produced after 2000"
             query="attr.item_type:episode AND attr.hierarchy:&quot;true&quot;"
             filter-query="field.year_of_production:[2000 TO *]"
             user="admin" />

Table 40. Saved Query properties

Name Type Description

id integer An identifier of this saved query.

name string A name of this saved query.

query string A search query. See more in Queries.

filter-query string A filter query. See more in Queries.

user string A login of the user who owns this saved query.

4.2.2. Saved Query List

A saved query list is a container of Saved Query objects.

125
 Tibigen Digital Repository - REST API

Example of representation

<saved-queries>
    <saved-query id="1" name="All episodes produced after 2000" />
</saved-queries>

4.2.3. List saved queries

List saved queries attached to given user.

Request

GET /saved-queries?login={login}&page={page}&size={size}

Query parameters

Name Type Description

login string A login of the user who owns saved queries.

page integer The number of page of results to return. If not specified,

returns all saved queries.

size integer The size of page of results. Default value is 10.

Authorization
If user tries to get saved queries for himself, only authentication is required. Otherwise, request
requires authorization with permission view.saved-query.

Response
If successful, the response status code is 200 OK and body contains Saved Query List object wrapped in
Response object.

4.2.4. Get saved query

Get saved query.

Request

GET /saved-queries/{id}

126
 Tibigen Digital Repository - REST API

Path parameters

Name Type Description

id integer An identifier of saved query to get.

Authorization
If creator of saved query tries to get it, only authentication is required. Otherwise, request requires
authorization with permission view.saved-query.

Response
If successful, the response status code is 200 OK and body contains Saved Query object wrapped in
Response object.

Errors

Error code Status Description

code

SavedQueryNotFoundExcepti 404 Cannot find saved query with given id.

on

4.2.5. Save search query

Save search query for later use.

Request

POST /saved-queries

In the request body, supply a Saved Query object with at least required properties.

Authorization
This request requires authentication.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly crated
saved query, wrapped in Response object.

Errors

127
 Tibigen Digital Repository - REST API

Error code Status Description

code

InvalidSavedQueryNameExce 400 The name of saved query is invalid.

ption

InvalidSavedQueryException 400 The query is not specified.

InvalidSavedQueryUserExcep 400 The user is not specified.

tion

SavedQueryAlreadyExistsExc 409 Saved query with given name and user already exists.
eption

4.2.6. Delete saved query

Delete saved query.

Request

DELETE /saved-queries/{id}

Path parameters

Name Type Description

id integer An identifier of saved query to delete.

Authorization
If creator of this saved query tries to delete it, only authentication is required. Otherwise, request
requires authorization with permission manage.saved-query.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

SavedQueryNotFoundExcepti 404 Cannot find saved query with given id.

on

4.3. Grouping Criteria

Grouping criteria are used to group multiple conditions on metadata fields into single expression. A

128
 Tibigen Digital Repository - REST API

common usage for grouping criteria is when multiple fields exist in an item and contain similar
information, for example different kinds of titles. If users frequently search in all of these titles, the
grouping criterion should be created to simplify that process. Let’s take a look at an example.

Let’s assume that we have item with following schema:

item: feature_film
    field: original_title
    field: english_title
    field: serie_title

In order to search for items like above by values of all title fields, user has to create query similar to
this below:

field.original_title:foo* OR field.english_title:foo* OR field.serie_title:foo*

If all conditions have equal right operands (e.g. foo*), a new grouping criterion can be created. Let’s
name it titles. After that we can use this grouping criterion in later queries:

group.titles:foo*

A grouping criteria names must stick to the String Identifier rules.

4.3.1. Grouping Criterion

Example of simple representation

<grouping-criterion id="1" name="titles"/>

129
 Tibigen Digital Repository - REST API

Example of detailed representation

<grouping-criterion id="1" name="titles">

    <field-types>
        <field-type>prog_title</field-type>
        <field-type>prog_subtitle</field-type>
    </field-types>
    <labels>
        <label lang="EN" value="Titles"/>
    </labels>
</grouping-criterion>

Table 41. Grouping Criterion properties

Name Type Description

id integer An identifier of this grouping criterion.

name string A name of this grouping criterion. Required.

field-types list A list of field type names which this grouping criterion
contains. Required.

labels Label list A list of labels.

4.3.2. Grouping Criterion List

A grouping criterion list is a container of Grouping Criterion objects.

Example of representation

<grouping-criteria>
    <grouping-criterion id="1" name="titles"/>
    <grouping-criterion id="2" name="people"/>
</grouping-criteria>

4.3.3. List grouping criteria

List grouping criteria.

Request

GET /grouping-criteria?detailed={detailed}

130
 Tibigen Digital Repository - REST API

Query parameters

Name Type Description

detailed boolean If true, returns detailed representation of each grouping

criterion in a list. Default value is false.

Authorization
This request requires authorization with permission query.index.

Response
If successful, the response status code is 200 OK and body contains Grouping Criterion List wrapped in
Response object.

4.3.4. Get grouping criterion

Get grouping criterion.

Request

GET /grouping-criteria/{id}?detailed={detailed}

Path parameters

Name Type Description

id integer An identifier of grouping criterion to get.

Query parameters

Name Type Description

detailed boolean If true, returns detailed representation of grouping criterion.

Default value is true.

Authorization
This request requires authorization with permission query.index.

Response
If successful, the response status code is 200 OK and body contains Grouping Criterion object wrapped
in Response object.

131
 Tibigen Digital Repository - REST API

Errors

Error code Status Description

code

GroupingCriterionNotFoundE 400 Cannot find grouping criterion with given id.

xception

4.3.5. Add grouping criterion

Add grouping criterion.

Request

POST /grouping-criteria

In the request body, supply a Grouping Criterion object with at least required properties.

If label is not specified, service will generate default label identical to criterion’s name.

Authorization
This request requires authorization with permission manage.grouping-criterion.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly
created grouping criterion, wrapped in Response object.

Errors

Error code Status Description

code

InvalidCriterionNameExcepti 400 The name of the criterion is empty or not specified.

on

InvalidCriterionFieldTypesEx 400 There are no field types specified in criterion.

ception

4.3.6. Update grouping criterion

Update grouping criterion.

Request

132
 Tibigen Digital Repository - REST API

PUT /grouping-criteria/{id}

Path parameters

Name Type Description

id integer An identifier of grouping criterion to update.

In the request body, supply a Grouping Criterion object with updated properties.

Authorization
This request requires authorization with permission manage.grouping-criterion.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

InvalidCriterionNameExcepti 400 The name of the criterion is empty or not specified.

on

InvalidCriterionFieldTypesEx 400 There are no field types specified in criterion.

ception

GroupingCriterionNotFoundE 404 Cannot find grouping criterion with given id.

xception

4.3.7. Delete grouping criterion

Delete grouping criterion.

Request

DELETE /grouping-criteria/{id}

Path parameters

Name Type Description

id integer An identifier of grouping criterion to delete.

133
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission manage.grouping-criterion.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

GroupingCriterionNotFoundE 404 Cannot find grouping criterion with given id.

xception

4.4. Indexes
TDR, while indexing metadata items, creates separate index for each language defined in the system.
Besides Rebuild Index Process, Synchronize Index Process and Clear Index Process processes, REST API
provides web-services for item-level index management. There is web-service which allows to reindex
individual items. The indexing procedure is the same as in Rebuild Index process. Other web-service
gives possibility to delete index for individual item.

4.4.1. Reindex item

Create new index document for given item and replace the one that already exists in the index.

Request

PUT /search-indexes/{name}/documents/{uuid}

Path parameters

Name Type Description

name string A name of the index which contains document to replace.

The name is equal to name of the language, in which data
are stored in this particular index.

uuid uuid An UUID of item which document will be replaced.

Authorization
This request requires authorization with permission manage.index.

134
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains empty Response object.

4.4.2. Delete item from index

Delete document corresponding to given item from the index.

Request

DELETE /search-indexes/{name}/documents/{uuid}

Path parameters

Name Type Description

name string A name of the index which contains document to delete. The
name is equal to name of the language, in which data are
stored in this particular index.

uuid uuid An UUID of item which document will be deleted from

index.

Authorization
This request requires authorization with permission manage.index.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

5. Files
TDR system is able to track files imported to its internal storages. It uses three-level hierarchy to record
information about files and theirs locations.

At the top of hierarchy is the most general unit - an asset. Asset stores multiple files that have common
feature. For example, video represented in a file system as individual frames will be single asset in
TDR. Assets cannot exist without metadata item to which there are attached. The relationship, from the
perspective of item, is one to many, which means that single item can have multiple assets attached
and asset can be attached to only one metadata item.

Each asset is created based on some asset type. The asset type, represented by Asset Type object,
delivers information needed to properly handle files inside an asset. It describes structure of the files
(single file, directory), assigns media type to them (used for selecting adequate file viewer and
technical metadata retrival) and stores file name validation rules in form of regular expressions. Any

135
 Tibigen Digital Repository - REST API

number of assets having the same asset type can be attached to item. However, one of these assets can
be selected as default. This information is later used in some processes to properly locate source files
attached to given item.

The middle level in hierarchy is file. File object represents abstract file which is not related to any
storage location. It stores information about file name, size and check sum - things that should not
change during migration of file from storage to storage. Each file can have multiple instances which
are represented by File Instance objects, the lowest of three-level hierarchy. Instances point to exact
locations where file is stored on the file system or on storage pool in tape library. Instance tracking is
required to deliver hierarchical storage management features.

5.1. Asset Types

Asset type stores parameters defining content and possible usage of files contained in asset of this type.
The media-type property tells TDR what can be done with files in asset: audio and video files can be
played in TDR player, DCP files are automatically scanned for metadata as in Digital Cinema Naming
Convention, keyframes are displayed in gallery and so on. The structure property tells import
mechanism how to import file to internal storage. There is also possibility to define extensions and
regular expressions for file name validation.

Asset types can be freely added or removed by authorized user. An example layout consists of High
Resolution Video, Low Resolution Video and Key Frame asset types.

5.1.1. Asset Type

Example of simple representation

<asset-type id="1"
            name="Low Res"
            media-type="VIDEO"
            metadata-reader="MEDIA_INFO"
            structure="SINGLE" />

136
 Tibigen Digital Repository - REST API

Example of detailed representation

<asset-type id="1"
            name="Low Res"
            media-type="VIDEO"
            metadata-reader="MEDIA_INFO"
            structure="SINGLE" >
    <extensions>
        <extension>mp4</extension>
    </extensions>
    <regular-expressions>
        <regular-expression>^lowres_.*[.]\w+$</regular-expression>
    </regular-expressions>
</asset-type>

Table 42. Asset Type properties

Name Type Description

id integer The identifier of this asset type.

name string The name of this asset type. Required.

media-type string An indicator that tells what can be done with this type of assets in TDR.
Possible values are:
- AUDIO - asset can be played in audio player,
- VIDEO - asset can be played in video player,
- VIDEO_DESCRIPTOR - asset keeps video index for video search
purposes,
- KEYFRAMES - images represent content of video file,
- DCP - Digital Cinema Package. When importing, TDR uses special
module for grabbing technical metadata from package name,
- NOT_SUPPORTED - asset with this media-type are just stored. No
special action are performed.
Required.

metadata-reader string The tool that will be used to retrieve technical metadata for each asset
of that type. Supported values are:
- MEDIA_INFO - MediaInfo software. Good for multimedia files.
- IMAGE_MAGICK - Identify software from Image Magick package.
Good for graphical files.
- DCP - embedded Digital Cinema Package name reader.

137
 Tibigen Digital Repository - REST API

Name Type Description

structure string Describes representation of asset in file system. Possible values are:
- SINGLE - single file,
- SEQUENCE - sequence of files where order matters. This kind of
structure can be seen on videos represented as a set of subsequent
frames,
- PACKAGE - deprecated,
- FOLDER - single folder with any content.
Required.

extensions list A list of allowed extensions for validation purposes. Each extension
must conform to regular expression ^\w{2,6}$.

regular- list A list of regular expressions validating file name (with extension).
expressions

5.1.2. Asset Type List

Asset type list is a container of Asset Type objects.

Example of representation

<asset-types>
    <asset-type id="1"
            name="Low Res"
            media-type="VIDEO"
            metadata-reader="MEDIA_INFO"
            structure="SINGLE" />
</asset-types>

5.1.3. List asset types

Get list of asset types.

Request

GET /asset-types?media-type={type}&detailed={detailed}

Query parameters

Name Type Description

media-type string If specified, only asset types having this media type will be
returned.

138
 Tibigen Digital Repository - REST API

Name Type Description

detailed boolean If true, returns detailed representation of each asset type in

a list. Default value is false.

Authorization
This request requires authorization with permission view.asset.

Response
If successful, the response status code is 200 OK and body contains Asset Type List wrapped in
Response object.

5.1.4. Get asset type

Get asset type.

Request

GET /asset-types/{id}

Path parameters

Name Type Description

id integer An identifier of asset type to get.

Query parameters

Name Type Description

detailed boolean If true, returns detailed representation of asset type. Default

value is true.

Authorization
This request requires authorization with permission view.asset.

Response
If successful, the response status code is 200 OK and body contains Asset Type wrapped in Response
object.

Errors

139
 Tibigen Digital Repository - REST API

Error code Status Description

code

AssetTypeNotFoundExceptio 404 Cannot find asset type with given id.

n

5.1.5. Add asset type

Add asset type.

Request

POST /asset-types

In the request body, supply an Asset Type object with at least required properties.

Authorization
This request requires authorization with permission manage.asset.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly
created asset type, wrapped in Response object.

Errors

Error code Status Description

code

InvalidAssetTypeNameExcept 400 Name is not specified or is invalid.

ion

InvalidAssetTypeStructureEx 400 Structure is not specified or is invalid.

ception

InvalidAssetTypeExtensionEx 400 One of the file extensions does not match regular expression
ception ^\w{2,6}$.

InvalidAssetTypeRegexExcept 400 One of the regular expressions is invalid.

ion

5.1.6. Update asset type

Update asset type.

140
 Tibigen Digital Repository - REST API

Request

PUT /asset-types/{id}

Path parameters

Name Type Description

id integer An identifier of type to update.

In the request body, supply an Asset Type object with updated properties.

Authorization
This request requires authorization with permission manage.asset.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

InvalidAssetTypeNameExcept 400 Name is not specified or is invalid.

ion

InvalidAssetTypeStructureEx 400 Structure is not specified or is different than before update.

ception Structure cannot be updated.

InvalidAssetTypeExtensionEx 400 One of the file extensions does not match regular expression
ception ^\w{2,6}$.

InvalidAssetTypeRegexExcept 400 One of the regular expressions is invalid.

ion

AssetTypeNotFoundExceptio 404 Cannot find asset type with given id.

n

5.1.7. Delete asset type

Delete asset type.

Request

DELETE /asset-types/{id}

141
 Tibigen Digital Repository - REST API

Path parameters

Name Type Description

id integer An identifier of asset type to delete.

Authorization
This request requires authorization with permission manage.asset.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

AssetTypeUsedByFilesExcepti 400 Files of this type exist.

on

AssetTypeUsedByAssetsExcep 400 Assets of this type exist.

tion

5.2. Assets
Asset is group of files linked with common feature. Each asset in TDR is created based on Asset Type
and has to be attached to metadata item. Under metadata item, only one asset from assets of common
types can be marked as default.

5.2.1. Asset

142
 Tibigen Digital Repository - REST API

Example of representation

<asset id="1"
        name="stream"
        type-id="2"
        item-uuid="a99a1455-fbbe-4594-ba95-cf32ef69ecd1"
        technical-metadata-uuid="e50badc5-0c19-4c7b-903f-854a9e8dc4d9"
        size="2399937876"
        date-path="2015/05/05/fg_1/"
        inserted="2015-05-05 11:27:01"
        default="true"
        last-accessed="2015-12-15 14:46:28"
        />

Table 43. Asset properties

Name Type Description

id integer The identifier of this asset.

name string The name of this asset.

type-id string The id of asset type. Required.

item-uuid uuid The UUID of item to which asset is attached.

technical- uuid The UUID of item that contains technical metadata

metadata-uuid describing this asset.

size integer Deprecated

date-path string The path of this asset on file system. Asset is represented in
file system as directory.

inserted datetime The time when asset was created.

last-accessed datetime The time when this asset had been used for the last time. On
asset update current time is set.

default boolean If true, this asset is default.

source-video-asset- integer Identifier of video source asset used to create this asset in
id transcoding process.

source-audio-asset- integer Identifier of audio source asset used to create this asset in
id transcoding process.

source-image-asset- integer Identifier of image source asset used to create this asset in
id transcoding process.

143
 Tibigen Digital Repository - REST API

5.2.2. Asset List

Asset list is a container of Asset objects.

Example of representation

<assets total="10">
    <asset id="1" name="stream" type-id="2" item-uuid="a99a1455-fbbe-4594-ba95-
cf32ef69ecd1"
           technical-metadata-uuid="e50badc5-0c19-4c7b-903f-854a9e8dc4d9" size="2399937876"
           date-path="2015/05/05/fg_1/" inserted="2015-05-05 11:27:01" last-accessed="2015-12-15
14:46:28" default="true"/>
</assets>

Table 44. Asset list properties

Name Type Description

total integer A total number of assets.

5.2.3. Get asset

Get asset.

Request

GET /assets/{id}?detailed={detailed}

Path parameters

Name Type Description

id integer An identifier of asset to get.

Query parameters

Name Type Description

detailed boolean If true, returns detailed representation of asset. Default

value is false.

Authorization
This request requires authorization with permission view-files.item.ITEM_TYPE, where ITEM_TYPE is a
name of type of item to which asset is attached. Web service verifies asset type requirements.

144
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains Asset object, wrapped in Response
object.

Errors

Error code Status Description

code

AssetNotFoundException 404 Cannot find asset with given id.

5.2.4. Update asset

Update asset.

Request

PUT /assets/{id}

Path parameters

Name Type Description

id integer An identifier of asset to update.

In the request body, supply an Asset object with updated properties.

Authorization
This request requires authorization with permission manage-files.item.ITEM_TYPE, where ITEM_TYPE
is a name of type of item, to which asset is attached.

This service verifies asset type permission requirements using Asset Type Requirement Verifier. For
more information, see Permission Requirements.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

InvalidAssetItemUuidExcepti 400 Item UUID is not specified.

on

145
 Tibigen Digital Repository - REST API

Error code Status Description

code

AssetNotFoundException 404 Cannot find asset with given id.

ItemNotFoundException 404 Cannot find item with given UUID.

5.2.5. Delete asset

Delete asset.

Request

DELETE /assets/{id}

Path parameters

Name Type Description

id integer An identifier of asset to delete.

Authorization
This request requires authorization with permission manage-files.item.ITEM_TYPE, where ITEM_TYPE
is a name of type of item to which asset is attached.

This service verifies asset type permission requirements using Asset Type Requirement Verifier. For
more information, see Permission Requirements.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

AssetNotEmptyException 400 Asset contains files and cannot be deleted.

TechnicalMetadataExistExcep 400 Asset has technical metadata item attached and cannot be
tion deleted.

AssetNotFoundException 404 Cannot find asset with given id.

5.2.6. List files of asset

Get list of files attached to asset.

146
 Tibigen Digital Repository - REST API

Request

GET /assets/{id}/files?directory={directory}&detailed={detailed}&page={page}&size={size}

Path parameters

Name Type Description

id integer An identifier of asset which files will be returned.

Query parameters

Name Type Description

directory boolean If true, directories will be returned. If false, files will be

returned. Otherwise, directories and files will be returned.

page integer The number of page of results to return. If not specified,

returns all files.

size integer The size of the page of results. Default value is 10.

detailed boolean If true, returns detailed representation of each file in a list.

Default value is false.

Authorization
This request requires authorization with permission view-files.item.ITEM_TYPE, where ITEM_TYPE is a
name of type of item to which asset is attached. Web service verifies asset type requirements.

Response
If successful, the response status code is 200 OK and body contains File List object, wrapped in
Response object.

5.2.7. List URIs of files in asset

List URIs of files in asset.

Request

GET /assets/{id}/files/uris?protocol={protocol}

Path parameters

147
 Tibigen Digital Repository - REST API

Name Type Description

id integer An identifier of asset with files which URIs will be returned.

Query parameters

Name Type Description

protocol string The protocol for which URIs should be built. Available
protocols can be retrieved using List available protocols.

Authorization
This request requires authorization with permission download-files.item.ITEM_TYPE, where
ITEM_TYPE is a name of type of item to which asset is attached.

This service verifies asset type permission requirements using Asset Type Requirement Verifier. For
more information, see Permission Requirements.

Response
If successful, the response status code is 200 OK and body contains URI List object wrapped in
Response object.

Errors

Error code Status Description

code

InvalidQueryParamException 400 Protocol is invalid.

AssetNotFoundException 404 Cannot find asset with given id.

5.2.8. List assets

List assets.

Request

GET /assets?storage-id={storage-id}&asset-type-id={asset-type-id}&with-copies={with-
copies}&sort={sort}&direction={direction}&page={page}&size={size}&detailed={detailed}

Query parameters

148
 Tibigen Digital Repository - REST API

Name Type Description

storage-id integer The id of storage where exists asset’s file instances

REQUIRED.

asset-type-id integer The id of asset type. Can be set multiple times. REQUIRED.

with-copies boolean When true returns assets that have at least one file with at
last two file instances. Default value false.

sort string The asset parameter, that will be used to sort results.

direction string Direction of sorting. Allowed values asc (ascending) and desc
(descending). Default value desc.

page integer The number of page of results to return. Default value 0.

size integer The size of the page of results. Default value is 10.

detailed boolean If true, returns detailed representation of asset. Default

value is false.

Authorization
This request requires authorization with permission view.file.

Response
If successful, the response status code is 200 OK and body contains Asset List object, wrapped in
Response object.

Errors

Error code Status Description

code

InvalidQueryParamException 400 Missing storage-id or asset-type-id parameter.

5.2.9. Add file to asset

Add file to asset.

Request

POST /assets/{id}/files

Path parameters

149
 Tibigen Digital Repository - REST API

Name Type Description

id integer An identifier of asset to which file will be added.

In the request body, supply a File object with at least required properties.

Authorization
This request requires authorization with permission manage-files.item.ITEM_TYPE, where ITEM_TYPE
is a name of type of item to which asset is attached.

This service verifies asset type permission requirements using Asset Type Requirement Verifier. For
more information, see Permission Requirements.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly added
file, wrapped in Response object.

Errors

Error code Status Description

code

AssetNotFoundException 404 Cannot find asset with given id.

5.3. Files
File object represents abstract file which is not related to any store location. It stores information
about file name, size and check sum - things that should not change during migration of files from
storage to storage.

5.3.1. File

150
 Tibigen Digital Repository - REST API

Example of representation

<file id="1"
      access-path="2015/05/05/fg_1/stream.ts"
      original-path="2015/05/05/fg_1/stream.ts"
      asset-id="1"
      asset-type-id="1"
      directory="false"
      inserted="2015-05-05 11:27:03"
      md5="3a5ff29d4f73c0ee91c545b5700d9190"
      size="2399937876" >
    <file-instance file-id="1" growing="false" id="1" inserted="2015-05-05 11:27:03"
                       last-checked="2015-05-05 11:28:29"
                       name="2015/05/05/fg_1/stream.ts" size="2399937876"
                       storage-id="1" storage-name="High-res Video Storage" />
</file>

Table 45. File properties

Name Type Description

id integer An identifier of this file.

access-path string The abstract path of this file.

original-path string Deprecated. The same as access-path.

asset-id integer An id of the asset which contains this file.

asset-type-id integer An id of type of asset which contains this file.

directory boolean If true, this file represents directory.

inserted datetime The time when this file had been created.

md5 string The MD5 control sum of physical file on a file system.

size integer The size of physical file on a file system.

file-instances File Instance list A list of instances of this file.

5.3.2. File List

File list object is a container of File objects.

151
 Tibigen Digital Repository - REST API

Example of representation

<files total="1">
    <file id="1"
          access-path="2015/05/05/fg_1/stream.ts"
          original-path="2015/05/05/fg_1/stream.ts"
          asset-id="1"
          asset-type-id="1"
          directory="false"
          inserted="2015-05-05 11:27:03"
          md5="3a5ff29d4f73c0ee91c545b5700d9190"
          size="2399937876" />
</files>

Table 46. File List properties

Name Type Description

total integer A total number of files possible to get.

5.3.3. Get file

Get file.

Request

GET /files/{id}

Path parameters

Name Type Description

id integer An identifier of file to get.

Authorization
This request requires authorization with permission view-files.item.ITEM_TYPE, where ITEM_TYPE is a
name of type of item to which file is attached (through asset).

This service verifies asset type permission requirements using Asset Type Requirement Verifier. For
more information, see Permission Requirements.

152
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains File object wrapped in Response
object.

Errors

Error code Status Description

code

FileNotFoundException 404 Cannot find file with given id.

5.3.4. Get URI to file

Get URI to file.

Request

GET /files/{id}/uris

Path parameters

Name Type Description

id integer An identifier of file which URI will be returned.

Query parameters

Name Type Description

protocol string The protocol for which URI should be built. Available
protocols can be retrieved using List available protocols.

Authorization
This request requires authorization with permission download-files.item.ITEM_TYPE, where
ITEM_TYPE is a name of type of item to which file is attached (through asset).

This service verifies asset type permission requirements using Asset Type Requirement Verifier. For
more information, see Permission Requirements.

Response
If successful, the response status code is 200 OK and body contains URI object wrapped in Response
object.

153
 Tibigen Digital Repository - REST API

Errors

Error code Status Description

code

FileUnreachableException 400 File is unreachable through specified protocol.

FileNotFoundException 404 Cannot find file with given id.

5.3.5. Update file

Update file.

Request

PUT /files/{id}

Path parameters

Name Type Description

id integer An unique identifier of file to update.

In the request body, supply a File object with updated properties.

Authorization
This request requires authorization with permission manage-files.item.ITEM_TYPE, where ITEM_TYPE
is a name of type of item to which file is attached (through asset).

This service verifies asset type permission requirements using Asset Type Requirement Verifier. For
more information, see Permission Requirements.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

FileNotFoundException 404 Cannot find file with given id.

InvalidFileAccessPathExcepti 400 The access-path property was not specified.

on

CannotChangeAssetException 400 Cannot change asset to which file is attached.

154
 Tibigen Digital Repository - REST API

5.3.6. Delete file

Delete file.

Request

DELETE /files/{id}

Path parameters

Name Type Description

id integer An identifier of file to delete.

Authorization
This request requires authorization with permission manage-files.item.ITEM_TYPE, where ITEM_TYPE
is a name of type of item to which file is attached (through asset).

This service verifies asset type permission requirements using Asset Type Requirement Verifier. For
more information, see Permission Requirements.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

FileInstancesExistException 400 Instances of this file exist.

FileNotFoundException 404 Cannot find file with given id.

5.3.7. List instances of file

Get a list of instances of file.

Request

GET /files/{id}/instances?detailed={detailed}

Path parameters

155
 Tibigen Digital Repository - REST API

Name Type Description

id integer An identifier of file which instances will be returned.

Query parameters

Name Type Description

detailed boolean If true, returns detailed representation of each file instance

in a list. Default value is false.

Authorization
This request requires authorization with permission view-files.item.ITEM_TYPE, where ITEM_TYPE is a
name of type of item to which file is attached (through asset).

This service verifies asset type permission requirements using Asset Type Requirement Verifier. For
more information, see Permission Requirements.

Response
If successful, the response status code is 200 OK and body contains File Instance List wrapped in
Response object.

Errors

Error code Status Description

code

FileNotFoundException 404 Cannot find file with given id.

5.3.8. Get optimal instance of file

Get optimal instance of file. The optimal instance is that instance which requires the shortest time to
access it. This instance usually cannot be within tape library or other slow access device. Selecting
optimal instance consists of steps:

• Get all instances for chosen file.

• Select instances which are not archived in tape library.

• Select instance which is on storage with highest priority.

Request

GET /files/{id}/instances/optimal

156
 Tibigen Digital Repository - REST API

Path parameters

Name Type Description

id integer An identifier of file which optimal instance will be returned.

Authorization
This request requires authorization with permission view-files.item.ITEM_TYPE, where ITEM_TYPE is a
name of type of item to which file is attached (through asset).

This service verifies asset type permission requirements using Asset Type Requirement Verifier. For
more information, see Permission Requirements.

Response
If successful, the response status code is 200 OK and body contains detailed representation of File
Instance object wrapped in Response object.

Errors

Error code Status Description

code

OptimalFileInstanceNotFoun 404 There is no optimal file instance.

dException

5.3.9. Add instance of file

Add instance of file.

Request

POST /files/{id}/instances

Path parameters

Name Type Description

id integer An identifier of file to which instance will be added.

In the request body, supply a File Instance object with at least required properties.

Authorization
This request requires authorization with permission manage-files.item.ITEM_TYPE, where ITEM_TYPE
is a name of type of item to which file is attached (through asset).

157
 Tibigen Digital Repository - REST API

This service verifies asset type permission requirements using Asset Type Requirement Verifier. For
more information, see Permission Requirements.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly added
file instance, wrapped in Response object.

Errors

Error code Status Description

code

FileNotFoundException 404 Cannot find file with given id.

5.4. File Instances

File instance contains information about location where file is stored. In case when file is stored on
internal storage, a storage-id property relates to target storage. If file is stored on tape library, a
storage-pool-id is set to id of storage pool on that tape library.

File instances are registered by TDR before they appear on target storage. This allows to work on
growing files. The growing property informs about actual state of instance creation.

5.4.1. File Instance

Example of representation

<file-instance id="1938320"
                name="2015/05/05/fg_906879/TVN_24_20150501031500-20150501034500.ts"
                file-id="1938320"
                growing="false"
                size="2399937876"
                inserted="2015-05-05 11:27:03"
                last-checked="2015-05-05 11:28:29"
                storage-id="24"
                library="TSM"
                storage-name="High-res Video Storage /u08" />

Table 47. File Instance properties

Name Type Description

id integer The identifier of this file instance.

name string The name of this file instance.

158
 Tibigen Digital Repository - REST API

Name Type Description

file-id integer The id of file of this instance.

growing boolean If true, file on file system, represented by this file instance, is
currently being written. Default value is false.

size integer Deprecated.

inserted datetime The time when file instance had been created.

last-checked datetime The time when file instance had been checked for the last
time.

storage-id integer The id of the storage on which file instance is stored.

storage-name string The name of the storage on which file instance is stored.

storage-pool-id integer The id of storage pool on which file instance is archived.

library integer The type of library on which file instance is archived.

5.4.2. File Instance List

File instance list object is a container of File Instance objects.

Example of representations

<file-instances>
    <file-instance id="1"
                    name="2015/05/05/fg_1/video.mp4"
                    file-id="1"
                    growing="false"
                    size="2399937876"
                    inserted="2015-05-05 11:27:03"
                    last-checked="2015-05-05 11:28:29"
                    storage-id="1"
                    library="TSM"
                    storage-name="High-res Video Storage" />
</file-instances>

5.4.3. List file instances

Get a list of file instances.

Request

159
 Tibigen Digital Repository - REST API

GET /file-instances?growing={growing}&detailed={detailed}&page={page}&size={size}

Query parameters

Name Type Description

growing boolean If present, filters file instance list by growing property.

page integer The number of page of results to return. If not specified,

returns all file instances.

size integer The size of the page of results. Default value is 10.

detailed boolean If true, returns detailed representation of each file instance

in a list. Default value is false.

Authorization
This request requires authorization with permission view.file.

Response
If successful, the response status code is 200 OK and body contains File Instance List wrapped in
Response object.

5.4.4. Get file instance

Get detailed representation of file instance.

Request

GET /file-instances/{id}

Path parameters

Name Type Description

id integer An identifier of file instance to get.

Authorization
This request requires authorization with permission view-files.item.ITEM_TYPE, where ITEM_TYPE is a
name of type of item to which file instance is attached (through asset and file). Web service verifies
asset type requirements.

160
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains detailed representation File
Instance object wrapped in Response object.

Errors

Error code Status Description

code

FileInstanceNotFoundExcepti 404 Cannot find file instance with given id.

on

5.4.5. Update file instance

Update file instance.

Request

PUT /file-instances/{id}

Path parameters

Name Type Description

id integer An identifier of instance to update.

In the request body, supply a File Instance object with updated properties.

Authorization
This request requires authorization with permission manage-files.item.ITEM_TYPE, where ITEM_TYPE
is a name of type of item to which file instance is attached (through asset and file).

This service verifies asset type permission requirements using Asset Type Requirement Verifier. For
more information, see Permission Requirements.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

161
 Tibigen Digital Repository - REST API

Error code Status Description

code

InvalidFileInstancePathExcep 400 Path of file instance is empty or not specified.

tion

FileInstanceNotFoundExcepti 404 Cannot find file instance with given id.

on

5.4.6. Delete file instance

Delete file instance.

Request

DELETE /file-instances/{id}

Path parameters

Name Type Description

id integer An identifier of file instance to delete.

Authorization
This request requires authorization with permission manage-files.item.ITEM_TYPE, where ITEM_TYPE
is a name of type of item to which file instance is attached (through asset and file).

This service verifies asset type permission requirements using Asset Type Requirement Verifier. For
more information, see Permission Requirements.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

SubInstancesExistException 400 If instance to delete is directory and other instances exist in

that directory.

FileInstanceNotFoundExcepti 404 Cannot find file instance with given id.

on

162
 Tibigen Digital Repository - REST API

5.5. EDLs
EDL is an entity representing Edition Decision List. EDLs can be used in integration with various NLE.
Each EDL has to be attached to metadata item. Only one EDL can be assigned to single metadata item.

5.5.1. EDL
Example of representation

<edl uuid="97414fb4-4478-43a6-91d9-acb7a8ad96af"
     fps="29.97"
     width="1920"
     height="1080"
     version="2"
     item-uuid="15105deb-702c-4b89-b1c1-02dc5ac153ce"
     creator="admin"
     modified-by="admin"
     created="2017-01-24 13:07:33"
     modified="2017-01-24 13:08:34">
  <clips>
     <clip uuid="2c09da06-82f3-495d-8768-1b850947179d"
           item-uuid="15105deb-702c-4b89-b1c1-02dc5ac153ce"
           asset-id="261"
           source-tcin="00:00:22:27"
           source-tcout="00:00:38:11"
           target-tcin="00:00:14:18"
           target-tcout="00:00:30:02"/>
     <clip uuid="1c450d7a-dfd8-4d6a-a773-9e743e04084f"
           item-uuid="42df506d-824e-46a5-b8e5-1f5290f145aa"
           asset-id="265"
           source-tcin="00:00:50:09"
           source-tcout="00:00:58:05"
           target-tcin="00:00:45:15"
           target-tcout="00:00:53:11"/>
  </clips>
</edl>

Table 48. EDL properties

Name Type Description

uuid uuid The identifier of this EDL.

163
 Tibigen Digital Repository - REST API

Name Type Description

fps double FPS (Frames Per Second) value for this EDL. Required

width integer Width of this EDL.

height integer Height of this EDL.

version integer A version of this EDL.

item-uuid uuid UUID of the item, which owns this EDL. Required

creator string A login of the user who created this item.

modified-by string A login of the user who lately modified this item.

created datetime A time when this item was created.

modified datetime A time when this item was lately modified.

clips Clip A list of clips of this EDL.

5.5.2. EDL List

EDL list is a container of EDL objects.

Example of representation

<edls total="8">
    <edl uuid="e2fbc099-a6c6-457c-94f4-613fc2d68f4d"/>
    <edl uuid="6c491f16-c2b1-4e92-b4f1-df56a957cf7f"/>
    <edl uuid="f0d48f10-ead5-42bb-ad97-916300a6b9db"/>
</edls>

Table 49. EDL properties

Name Type Description

total integer A total number of EDL’s.

5.5.3. Clip

164
 Tibigen Digital Repository - REST API

Example of representation

<clip uuid="2c09da06-82f3-495d-8768-1b850947179d"
      item-uuid="15105deb-702c-4b89-b1c1-02dc5ac153ce"
      asset-id="261"
      source-tcin="00:00:22:27"
      source-tcout="00:00:38:11"
      target-tcin="00:00:14:18"
      target-tcout="00:00:30:02"/>

Table 50. Clip properties

Name Type Description

uuid integer The identifier of this clip.

item-uuid uuid UUID of item used as a source of this clip. Required

asset-id integer Identifier of asset used as a source of this clip.

source-tcin timecode Beginning of the part of source clip used in EDL. Required

source-tcout timecode End of the part of source clip used in EDL. Required

target-tcin timecode Position in EDL, where the beginning of the clip is placed.
Required

target-tcout timecode Position in EDL, where the end of the clip is placed.
Required

5.5.4. Get EDL

Get EDL.

Request

GET /edls/{uuid}

Path parameters

Name Type Description

uuid uuid An identifier of EDL to get.

Authorization
This request requires authorization with permission view-edl.item.ITEM_TYPE, where ITEM_TYPE is a
name of type of item to which EDL is attached.

165
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains EDL object, wrapped in Response
object.

Errors

Error code Status Description

code

EdlNotFoundException 404 Cannot find EDL with given uuid.

5.5.5. Update EDL

Update EDL.

Request

PUT /edls/{uuid}

Path parameters

Name Type Description

uuid uuid An identifier of EDL to update.

Authorization
This request requires authorization with permission manage-edl.item.ITEM_TYPE, where ITEM_TYPE
is a name of type of item to which EDL is attached.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

EdlNotFoundException 404 Cannot find EDL with given uuid.

5.5.6. Delete EDL

Delete EDL.

166
 Tibigen Digital Repository - REST API

Request

DELETE /edls/{uuid}

Path parameters

Name Type Description

uuid uuid An identifier of EDL to delete.

Authorization
This request requires authorization with permission manage-edl.item.ITEM_TYPE, where ITEM_TYPE
is a name of type of item to which EDL is attached.

Response
If successful, the response status code is 200 OK and contains empty Response object.

Errors

Error code Status Description

code

EdlNotFoundException 404 Cannot find EDL with given uuid.

5.5.7. List of EDLs

Get list of EDLs.

Request

GET /edls&detailed={detailed}&page={page}&size={size}

Query parameters

Name Type Description

page integer The number of page of results to return. If not specified,

returns all EDLs.

size integer The size of the page of results. Default value is 10.

detailed boolean If true, returns detailed representation of each EDL in a list.

Default value is false.

167
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission view-edls.item.ITEM_TYPE, where ITEM_TYPE is a
name of type of item to which EDL is attached.

Response
If successful, the response status code is 200 OK and body contains EDL List object, wrapped in
Response object.

6. Storages
TDR defines hierarchical, three-level object structure which is used to describe data storage space in
the system. A Storage object specifies logical space on which files will be stored. Each storage has to be
part of Storage Group. Groups define boundaries in which storages operate. One group can be IMPORT
group containing storages with files intended for importing to the system. Other group can be EXPORT
group with storages being places where files exported from the system will be saved. There is also
INTERNAL group consisting of all storages containing files currently residing inside the system. The
last and special storage group type is REPORT which is used to bind together storages containing
reports generated with the system. The other function of the storage group is to specify what kind of
file types can be written on storages contained in that group.

Due to the fact that storages are abstract objects representing some logical space for data and do not
contain information needed to physically access to them, an additional objects were added - Storage
Access objects. Storage access represents method of accessing storage to which it is attached on. Single
storage can have multiple access methods, mostly varying in access protocol. When system needs to
access to storage and storage has multiple access method, system will try to select optimal access in
context which is currently working on.

6.1. Storage Groups

Storage group is used to associate asset types with storages that belong to the group. These relations
are used by file processes, to decide where system should store files of given types. Each storage group
has type which is used by the system to decide how to use storages from given group. Each storage
group can contain unlimited number of storages.

6.1.1. Storage Group

Example of simple representation

<storage-group id="1"
                name="High-res Video"
                type="INTERNAL" />

168
 Tibigen Digital Repository - REST API

Example of detailed representation

<storage-group id="1"
                name="High-res Video"
                type="INTERNAL">
    <asset-types>
        <asset-type id="1"
                    name="Raw Stream"
                    media-type="NOT_SUPPORTED"
                    metadata-reader="MEDIA_INFO"
                    structure="SINGLE" />
    </asset-types>
    <storages>
        <storage id="1"
                 name="High-res Video /u01"
                 updated="2015-07-16 01:26:19"
                 size="644245094400"
                 used-space="90831074068"
                 low-watermark="0"
                 high-watermark="0"
                 priority="76"
                 permission="READWRITE"
                 path="/u01/rc/resources/HighRes/" >
            <storage-accesses>
                <storage-access id="1"
                                protocol="LOCAL"
                                path="/u01/rc/resources/HighRes"
                                host="10.0.0.71"
                                priority="50"
                                available="false" />
            </storage-accesses>
        </storage>
    </storages>
</storage-group>

Table 51. Storage Group properties

Name Type Description

id integer The identifier of this storage group.

169
 Tibigen Digital Repository - REST API

Name Type Description

name string The name of the storage group.

type string The type of storages in group. One of:

- IMPORT - storages of this type define places where files will
be stored in order to import them to the system,
- EXPORT - storages of this type define places where files will
be stored after exporting them from the system,
- INTERNAL - storages of this type define internal file space
for files stored inside the system,
- REPORT - similar to export storages, this storages contain
all kind of reports.

asset-types Asset Type List A list of asset types which this storage group can store.

storages Storage List A list of storages in this group.

6.1.2. Storage Group List

A storage group list is a container of Storage Group objects.

Example of simple representation

<storage-groups>
    <storage-group id="1" name="Import Group" type="IMPORT"/>
    <storage-group id="2" name="High-res Video Group" type="INTERNAL"/>
</storage-groups>

170
 Tibigen Digital Repository - REST API

Example of detailed representation

<storage-groups>
    <storage-group id="1" name="Import Group" type="IMPORT">
        <storages>
            <storage id="1" name="Import" updated="2015-12-16 01:00:01" size="1099511627776"
                     used-space="33607671858" low-watermark="0" high-watermark="0" priority="100"
                     permission="READWRITE" path="/u01/rc/resources/Import/">
                <storage-accesses>
                    <storage-access id="1" protocol="LOCAL" path="/u01/rc/resources/Import" host=
"10.0.0.71" port=""
                                    login="" password="" priority="50" available="true"/>
                </storage-accesses>
            </storage>
        </storages>
    </storage-group>
    <storage-group id="2" name="High-res Video Group" type="INTERNAL">
        <asset-types>
            <asset-type id="2" media-type="NOT_SUPPORTED" name="Raw Stream" metadata-
reader="MEDIA_INFO"
                            structure="SINGLE"/>
        </asset-types>
        <storages>
            <storage id="2" name="High-res Video Storage /u01" updated="2015-07-16 01:09:43"
size="37383395344384"
                         used-space="34697601958984" low-watermark="60" high-watermark="90"
priority="80"
                         permission="READWRITE" path="/u01/rc/resources/HiResVideo/">
                <storage-accesses>
                    <storage-access id="36" protocol="LOCAL" path="/u01/rc/resources/HiResVideo"
host="10.0.0.71"
                                        port="" login="" password="" priority="50" available="false"/>
                </storage-accesses>
            </storage>
        </storages>
    </storage-group>
</storage-groups>

171
 Tibigen Digital Repository - REST API

6.1.3. List storage groups

List storage groups.

Request

GET /storage-groups

Query parameters

Name Type Description

detailed boolean If true, returns detailed representation of each storage

group in a list. Default value is false.

Authorization
This request requires authorization with permission view.storage.

Response
If successful, the response status code is 200 OK and body contains Storage Group List object wrapped
in Response object.

6.1.4. Get storage group

Get storage group.

Request

GET /storage-groups/{id}

Path parameters

Name Type Description

id integer An identifier of storage group to get.

Authorization
This request requires authorization with permission view.storage.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

172
 Tibigen Digital Repository - REST API

Errors

Error code Status Description

code

StorageGroupNotFoundExcep 404 Cannot find storage group with given id.

tion

6.1.5. Add storage group

Add storage group.

Request

POST /storage-groups

In the request body, supply a Storage Group object with at least required properties.

Authorization
This request requires authorization with permission manage.storage.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly
created storage group, wrapped in Response object.

Errors

Error code Status Description

code

InvalidStorageGroupNameEx 400 Name of this storage group was empty or not specified.
ception

InvalidStorageGroupTypeExc 400 Type of this storage group was not specified.

eption

6.1.6. Update storage group

Update storage group.

Request

PUT /storage-groups/{id}

173
 Tibigen Digital Repository - REST API

Path parameters

Name Type Description

id integer An identifier of storage group to update.

In the request body, supply a Storage Group object with updated properties.

Authorization
This request requires authorization with permission manage.storage.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

StorageGroupNotFoundExcep 404 Cannot find storage group with given id.

tion

6.1.7. Delete storage group

Delete storage group.

Request

DELETE /storage-groups/{id}

Path parameters

Name Type Description

id integer An identifier of storage group to delete.

Authorization
This request requires authorization with permission manage.storage.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

174
 Tibigen Digital Repository - REST API

Errors

Error code Status Description

code

StoragesExistException 400 Storage group contains storages and therefore cannot be

deleted.

StorageGroupNotFoundExcep 404 Cannot find storage group with given id.

tion

6.1.8. List storages in storage group

Get list of storages in storage group.

Request

GET /storage-groups/{id}/storages

Path parameters

Name Type Description

id integer An identifier of storage group which storages will be

returned.

Authorization
This request requires authorization with permission view.storage.

Response
If successful, the response status code is 200 OK and body contains Storage List wrapped in Response
object.

6.1.9. Add storage to group

Add storage to group.

Request

POST /storage-groups/{id}/storages

Path parameters

175
 Tibigen Digital Repository - REST API

Name Type Description

id integer An identifier of storage group to which storage will be

added.

In the request body, supply a Storage object with at least required properties.

Authorization
This request requires authorization with permission manage.storage.

Response
If successful, the response status code is 200 OK and body contains Value object wrapped in Response
object.

Errors

Error code Status Description

code

InvalidStorageNameExceptio 400 Storage name is empty or not specified.

n

InvalidStorageWatermarksEx 400 Storage watermarks are out of range or not specified.

ception

InvalidStoragePermissionExc 400 Storage permission is not specified.

eption

InvalidStoragePriorityExcepti 400 Storage priority is out of range or not specified.

on

6.2. Storages
Storage is a virtual file space. It can be either a local directory, as well as a remote directory accessible
through one of supported protocols, such as: FTP, FTPS, CIFS or HTTP.

6.2.1. Storage
Storage is a virtual file space. It can be either a local directory, as well as a remote directory accessible
through one of supported protocols, such as: FTP, FTPS, CIFS or HTTP.

176
 Tibigen Digital Repository - REST API

Example of simple representation

<storage id="1"
         name="High-res Video Storage /u01"
         updated="2015-07-16 01:09:43"
         size="37383395344384"
         used-space="34697601958984"
         low-watermark="60"
         high-watermark="90"
         priority="80"
         permission="READWRITE"
         path="/u01/rc/resources/HiResVideo/" />

Example of detailed representation

<storage id="1"
         name="High-res Video Storage /u01"
         updated="2015-07-16 01:09:43"
         size="37383395344384"
         used-space="34697601958984"
         low-watermark="60"
         high-watermark="90"
         priority="80"
         permission="READWRITE"
         path="/u01/rc/resources/HiResVideo/" >
    <storage-accesses>
        <storage-access id="36" protocol="LOCAL" path="/u01/rc/resources/HiResVideo" host=
"10.0.0.71"
                        port="" login="" password="" priority="50" available="false"/>
    </storage-accesses>
</storage>

Table 52. Storage properties

Name Type Description

id integer The identifier of this storage.

name string The name of this storage.

updated datetime The time when storage was updated for the last time.

size integer The size of this storage in bytes.

177
 Tibigen Digital Repository - REST API

Name Type Description

used-space integer The size of files currently stored in this storage in bytes.

low-watermark integer Indicates permissible usage of this storage in percents. For

now, this property is not used.

high-watermark integer Indicates maximum usage of this storage in percents. For

now, this property is not used.

priority integer A value between 1 and 100 used for selecting optimal
storage. The higher the value, the storage is more promoted
to be optimal.

permission string The permission of operation allowed on this storage. One of:
- READWRITE - read and write operation are allowed,
- READONLY - read operation are allowed,
- DENY - read and write operation are forbidden. The storage
is disabled.

path string Deprecated.

storage-access Storage Access List A list of accesses to this storage.

6.2.2. Storage List

Storage list is a container of Storage objects.

Example of representation

<storages>
    <storage id="1" name="High-res Video Storage /u01" updated="2015-12-16 01:00:01" size=
"28587302322176"
             used-space="95510965964" low-watermark="60" high-watermark="90" priority="100"
permission="READWRITE"
             path="/u01/rc/resources/HiResVideo/" />
</storages>

6.2.3. Storage Content

Storage content object contains list of paths to directories and files located on specific storage and
directory. In other words, it’s a directory listing.

178
 Tibigen Digital Repository - REST API

Example of representation

<storage-content total="2">
    <path directory="true">test_directory</path>
    <path directory="false">test_file.mp4</path>
</storage-content>

Table 53. Storage Content properties

Name Type Description

total integer A total number of paths possible

to get, regardless of pagination.

paths Path list A list of paths on the storage.

6.2.4. Path
Path object represents single path (to file or directory) on storage.

Example of representation

<path directory="true">test_directory</path>

Table 54. Path properties

Name Type Description

directory boolean If true, path leads to directory.

xml value string A name of file or directory.

6.2.5. Sequence Error

Sequence error object is created when sequence checking operation find error in sequence. The object
contains details about that error like cause and affected files.

Example of representation

<sequence-error from="file_3.txt" to="file_5.txt" type="MISSING"/>

Table 55. Sequence Error properties

Name Type Description

from string In case of MISSING error, contains name of the first file in
missing sequence. In case of INVALID_SIZE error, contains
name of the file with invalid size.

179
 Tibigen Digital Repository - REST API

Name Type Description

to string Present only if MISSING error occurs and contains name of

the last file in missing sequence.

type string The error type. One of:

- SEQUENCE_NOT_FOUND - sequence of files not found. This
type of error excludes other error (listed below),
- MISSING - indicates files missing in sequence. Properties
from and to will be set respectively to names of the first
missing and the last missing files in the sequence. If there is
only one file missing, from and to will contain the same
value.
- INVALID_SIZE - indicates file that has size different than
other files in sequence.

6.2.6. Sequence Error List

Sequence error list object is a container of Sequence Error objects.

Example of representation

<sequence-errors>
    <sequence-error from="file_3.txt" to="file_5.txt" type="MISSING"/>
    <sequence-error from="file_1.txt" type="INVALID_SIZE"/>
</sequence-errors>

6.2.7. List storages

Get list of storages.

Request

GET /storages

Query parameters

Name Type Description

group-type string If specified, storages from groups with this type will be
returned.

Authorization
This request requires authorization with permission list.storage.

180
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains Storage List object wrapped in
Response object.

6.2.8. Get storage

Get storage.

Request

GET /storages/{id}

Path parameters

Name Type Description

id integer An identifier of storage to get.

Authorization
This request requires authorization with permission view.storage.

Response
If successful, the response status code is 200 OK and body contains Storage object wrapped in Response
object.

Errors

Error code Status Description

code

StorageNotFoundException 404 Cannot find storage with given id.

6.2.9. Get optimal storage

Get optimal storage.

Request

GET /storages/optimal

181
 Tibigen Digital Repository - REST API

Query parameters

Name Type Description

asset-type-id integer Only storages able to store this asset type will be found.
Required.

min-free-space integer Only storages having at least this free space will be found.
Required.

protocol string If specified, only storages having access method through this
protocol will be found.

Authorization
This request requires authorization with permission view.storage.

Response
If successful, the response status code is 200 OK and body contains Storage object wrapped in Response
object.

Errors

Error code Status Description

code

OptimalStorageNotFoundExc 404 Cannot find storage which meets the required conditions:
eption - belongs to storage group associated with given asset-type-
id
- has size of used space
- has at least one active access method
- has free space >= min-free-space

OptimalStorageWithRequired 404 Cannot find storage which meets the required conditions:
AccessNotFoundException - belongs to storage group associated with given asset-type-
id
- has size of used space
- has at least one active access method
- has free space >= min-free-space
- has access method for given protocol

6.2.10. Update storage

Update storage.

Request

182
 Tibigen Digital Repository - REST API

PUT /storages/{id}

Path parameters

Name Type Description

id integer An identifier of storage to update.

In the request body, supply a Storage object with updated properties.

Authorization
This request requires authorization with permission manage.storage.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

InvalidStorageSizeException 400 Cannot reduce storage size below current usage level.

InvalidStorageNameExceptio 400 Storage name is empty or not specified.

n

InvalidStorageWatermarksEx 400 Storage watermarks are out of range or not specified.

ception

InvalidStoragePermissionExc 400 Storage permission is not specified.

eption

InvalidStoragePriorityExcepti 400 Storage priority is out of range or not specified.

on

6.2.11. Delete storage

Delete storage.

Request

DELETE /storages/{id}

183
 Tibigen Digital Repository - REST API

Path parameters

Name Type Description

id integer An identifier of storage to delete.

Authorization
This request requires authorization with permission manage.storage.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

StorageNotEmptyException 400 Instances of files exist on this storage and therefore storage
cannot be deleted.

StorageAccessesExistExceptio 400 Accesses to this storage exist and therefore storage cannot
n be deleted.

StorageNotFoundException 404 Cannot find storage with given id.

6.2.12. List accesses to storage

List accesses to storage.

Request

GET /storages/{id}/accesses

Path parameters

Name Type Description

id integer An identifier of storage to which access will be returned.

Query parameters

Name Type Description

protocol integer Only accesses having this protocol will be returned.

184
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission view.storage.

Response
If successful, the response status code is 200 OK and body contains Storage Access List object wrapped
in Response object.

6.2.13. Get optimal access to storage

Get optimal access to storage.

Request

GET /storages/{id}/accesses/optimal

Path parameters

Name Type Description

id integer An identifier of storage to which optimal access will be

returned.

Authorization
This request requires authorization with permission view.storage.

Response
If successful, the response status code is 200 OK and body contains Storage Access object wrapped in
Response object.

Errors

Error code Status Description

code

OptimalStorageAccessNotFou 404 Cannot find optimal access to storage.

ndException

6.2.14. Add access to storage

Add access to storage.

185
 Tibigen Digital Repository - REST API

Request

POST /storages/{id}/accesses

Path parameters

Name Type Description

id integer An identifier of storage to which access will be added.

In the request body, supply a Storage Access object with at least required properties.

Authorization
This request requires authorization with permission manage.storage.

Response
If successful, the response status code is 200 OK and body contains Value object wrapped in Response
object.

Errors

Error code Status Description

code

InvalidStorageAccessHostExc 400 The host is invalid.

eption

InvalidStorageAccessPriority 400 The priority is not between 1 and 100 or is not specified.
Exception

InvalidStorageAccessTypeExc 400 The protocol is not specified.

eption

InvalidStorageAccessPathExc 400 The path is not specified or is empty.

eption

6.2.15. List file instances on storage

List file instances on storage.

Request

GET /storages/{id}/file-instances

186
 Tibigen Digital Repository - REST API

Path parameters

Name Type Description

id integer An identifier of storage from which file instances will be

returned.

Authorization
This request requires authorization with permission view.file.

Response
If successful, the response status code is 200 OK and body contains File Instance List object wrapped in
Response object.

6.2.16. List content on storage

List content on storage filtered by property file.exclude.

Request

GET /storages/{id}/content

Path parameters

Name Type Description

id integer An identifier of storage to list.

Query parameters

Name Type Description

uri string If id parameter has value undefined, uri should contain all
information needed to establish connection with remote
storage and list it. Otherwise, web-service uses path part of
the URI for navigation and one of the storage accesses for
establishing connection to storage defined in the system.

page integer The number of page of results to return. If not specified,

returns entire content.

size integer The size of the page of results. Default value is 10.

Authorization
This request requires authorization with permission explore.storage.

187
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains Storage Content object wrapped in
Response object.

Errors

Error code Status Description

code

UriListingException 400 Failed to list storages. This can be related to file permissions
or URI given in query parameter leads to non-existing
resource.

OperationNotPermittedExcep 403 Due to security reasons, web-service does not allow to list
tion URIs beginning with file://

OptimalStorageAccessNotFou 404 Cannot find optimal access to connect to storage.

ndException

6.2.17. Check sequence

Check sequence of files in chosen directory. The file sequence is list of files where order matters. Web-
service provides two mechanisms for checking sequence:

• name validation - checks if all names of the files have equal length and contain sequential number
at the end of name (excluding extension). Files have to follow sequence beginning with the smallest
sequential number found and increasing by one with every subsequent file. Any file with
inconsistent name will be reported within MISSING errors.

• size validation - checks if all files have equal sizes. Any file with inconsistent size will be reported
within INVALID_SIZE error. If more than half files have different sizes, then validation will exit
with error SEQUENCE_NOT_FOUND.

By default, both modes are used while checking sequence. Concrete mode can be selected by specifying
what type of errors web-service should return (type query parameter).

Example of valid sequence of files

Movie_reel1_0010001.dpx
Movie_reel1_0010002.dpx
Movie_reel1_0010003.dpx
Movie_reel1_0010004.dpx

188
 Tibigen Digital Repository - REST API

Example of invalid sequence of files

Movie_reel1_0000001.dpx
Movie_reel1_0000002.dpx
Movie_reel1_0000003.dpx
Movie_reel1_0010000.dpx

Request

GET /storages/{id}/content/sequence/errors?path={path}&type={type}

Path parameters

Name Type Description

id integer An identifier of storage on which sequence will be checked.

Query parameters

Name Type Description

path string A path to directory with sequence of files.

type string If specified, returns errors of given type. Possible values are:
- SEQUENCE_NOT_FOUND - indicates that there is no
sequence in given directory,
- MISSING - indicates files missing in sequence,
- INVALID_SIZE - indicates file that has size different than
other files in sequence.

Authorization
This request requires authorization with permission explore.storage.

Response
If successful, the response status code is 200 OK and body contains Sequence Error List wrapped in
Response object.

Errors

189
 Tibigen Digital Repository - REST API

Error code Status Description

code

OptimalStorageAccessNotFou 404 Cannot find optimal access to storage which contains

ndException sequence of files to check.

6.3. Storage Accesses

Storage Access object contains information needed to connect to storage such as host, port, protocol of
connection, path and credentials. For now, supported protocols are FTP, FTPS, HTTP, CIFS and LOCAL,
which represents access to local file system. However, HTTP is implemented as reading protocols. Due
to the fact, that at one time multiple storage accesses can exist for single storage, system uses priority
property to distinguish which storage is better. The operation in known as selecting optimal storage
access and the following algorithm is used:

1. Get all storage accesses that are available.

2. Get storage accesses having best protocol. Protocols are ordered as follows (from best to worst):
LOCAL, CIFS, FTP, FTPS, HTTP.

3. If there are multiple storage accesses with the same protocol, select these with the highest priority.

4. If there are multiple storage accesses with the same priority, return any of them.

To not allow system to select random storage access, as in the last step of above algorithm, user should
remember to always set different priority for different storage accesses.

6.3.1. Storage Access

Example of representation

<storage-access id="2"
                protocol="LOCAL"
                path="/u01/rc/resources/HiResVideo"
                host="10.0.0.71"
                port=""
                login=""
                password=""
                priority="50"
                available="true" />

Table 56. Storage Access properties

Name Type Description

id integer The identifier of this storage access.

190
 Tibigen Digital Repository - REST API

Name Type Description

protocol string The name of the protocol that will be used to connect with
storage service. One of:
- LOCAL - the storage is accessible as path on local file
system, allows reads and writes,
- UNC - SMB/CIFS protocol, allows reads and writes,
- FTP - FTP protocol, allows reads and writes,
- FTPS - FTP over SSL protocol, allows reads and writes,
- HTTP - HTTP protocol, allows reads.
Required.

path string The path to the storage. Required.

host string The hostname or IP address of host with storage service.

port integer The port of storage service.

login string The login to storage service.

password string The password to storage service.

priority integer The value between 1 and 100 used for selecting optimal
access to storage. The higher the value, the access is more
promoted to be optimal. Required.

available boolean If true, system was able to successfully connect to this

storage service in the last [Check Access Process] process.

6.3.2. Storage Access List

Storage access list object is a container of Storage Access objects.

Example of representation

<storage-accesses>
    <storage-access id="2" protocol="LOCAL" path="/u01/rc/resources/HiResVideo" host=
"10.0.0.71" port="" login=""
                    password="" priority="50" available="true"/>
</storage-accesses>

6.3.3. Protocol List

Protocol list includes all available protocols for storage accesses in TDR.

191
 Tibigen Digital Repository - REST API

Example of representation

<protocols>
    <protocol>LOCAL</protocol>
    <protocol>UNC</protocol>
    <protocol>FTP</protocol>
    <protocol>FTPS</protocol>
    <protocol>HTTP</protocol>
</protocols>

6.3.4. Update access to storage

Update access to storage.

Request

PUT /storage-accesses/{id}

Path parameters

Name Type Description

id integer An identifier of storage access to update.

In the request body, supply a Storage Access object with updated properties.

Authorization
This request requires authorization with permission manage.storage.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

InvalidStorageAccessHostExc 400 The host is invalid.

eption

InvalidStorageAccessPriority 400 The priority is not between 1 and 100 or is not specified.
Exception

192
 Tibigen Digital Repository - REST API

Error code Status Description

code

InvalidStorageAccessTypeExc 400 The protocol is not specified.

eption

InvalidStorageAccessPathExc 400 The path is not specified or is empty.

eption

StorageAccessNotFoundExce 404 Cannot find storage access with given id.

ption

6.3.5. Delete access to storage

Delete access to storage.

Request

DELETE /storage-accesses/{id}

Path parameters

Name Type Description

id integer An identifier of storage access to delete.

Authorization
This request requires authorization with permission manage.storage.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

6.3.6. List available protocols

List available protocols.

Request

GET /storage-accesses/protocols

Authorization
This request requires authentication.

193
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains Protocol List object wrapped in
Response object.

7. Processes
Tibigen Digital Repository has infrastructure specially designed to execute simple instant processes as
well as long-term heavy tasks. Some of the available processes are embedded into the system and
therefore cannot be changed. However, most of the processes are based on processes definitions - XML
like files containing jobs to execute within the process. That format allows you to rearrange jobs or add
completely new jobs to the processes.

The processes interface is divided into multiple levels depending on levels of abstractions. The
processes web-services are on the top-level of API. They allow you to execute single process as well as
multiple processes operating on items from common metadata collection. Processes are identified by
name. User, in web-servies call, can provide required and optional parameters needed to execute that
process.

After successful web-service call, system tries to find process with given name. There are two places
were processes are defined. First is a set of processes embedded in the application code. This
processes, when executed, run within TDR process in operating system. The other place is a directory
with process definitions. By default, directory is located under /etc/tdr/queues and contains definitions
in .vm files which are Apache Velocity template files. You can learn more about process definition
syntax in section Process Definitions. Processes known as embedded processes are invoked
immediately after web-service call. On the other hand, processes created from definitions are
scheduled in Job Daemon to later execution.

Second level of processes API abstraction focuses on queues and jobs. These web-services allow to
monitor and manage job queue executions. Job queues are containers of jobs. By default, jobs
contained in queues are executed sequentially, but nothing stands in the way to modify that behavior
and introduce parallel job execution. When all of the jobs inside job queue had been executed, the
queue will be considered as executed too. Job Daemon can execute finite number of jobs at one time,
so it is possibility to prioritize execution order on job queue level by manipulating job queue’s priority.

There are also other services on that abstraction level - services used to manage workers and
execution routes. Workers play important role in jobs ecosystem because they are responsible for
actual execution of specific jobs. Workers are separate application installed on different nodes. They
are communicating with Job Daemon - Job Daemon delegates them jobs to do, workers respond with
execution state. A worker configuration gives you possibility to very accurately define responsibility of
that worker by specifying worker’s capabilities. Capabilities are nothing more than job types that
worker can execute. Along with the system, we provides standard worker implementation that knows
how to execute generic TDR jobs. However, other workers can be created and registered in Job
Daemon to serve more specific, custom tasks.

Capabilities provide elastic approach to workers responsibility configuration, but when more fine-

194
 Tibigen Digital Repository - REST API

grained control is needed, routes are solution for that problem. By defining route, user creates
additional contract that Job Daemon must comply during determination of what worker should do
next job. For example, route can tell that all jobs having specific input with specific value have to be
executed on worker installed on host NODE1. User can manage routes in runtime - routes will be
immediately taken into account.

At the lowest level of abstraction, the concrete job types are placed. Job type tells what operations
should be executed as the job runs. For example, there are job types like COPY_FILES or UNZIP which
do various operation on file system - in this case copying of files and unpacking a ZIP packages. More
sophisticated operation are also available like IMPORT which knows how to copy files to TDR internal
storages and register them in the system. Each job type available in current version of system is
described in Job Types section.

7.1. Processes
In TDR, there are two types of processes. The first type is embedded processes which when started,
execute in the same operating system process as TDR application. There are limited set of these
processes implemented in the application. They cannot be changed. On the other side, there are
processes based on a definition files. These processes are actually job queues parameterized with
process parameters. User can freely modify definition files. Definition based processes are scheduled
by TDR in Job Daemon to later execution as queues. When Job Daemon has suitable resources to
execute queues, it will handle over individual jobs from queue to proper workers. Definition based
processes may contain heavy tasks, so they are executed in separate operation system processes
(worker processes), possibly on other machines.

The API allows you to execute single process - embedded or definition based - from the API perspective
this is transparent. There is also possible to execute the same process as many times as number of
items in metadata collection. The only requirement is process to have itemUuid parameter, so that
system could automatically set that parameter for each collection entry. The last web-service in
processes API allows you to get all processes names that system currently knows.

7.1.1. Process Request

A process request object contains all information needed to execute specific process, which is a process
name and process parameters. If collection-id property is specified and request is send to
/processes/batch endpoint, system will execute separate process for all items contained in metadata
collection.

Each process request, besides parameters defined by the user, receives implicit parameters. One of
that parameters is user which value is login of the user who sent process request. Other implicit
parameter is itemUuid and it is provided by the system for each metadata collection’s item when
process is executed on collection.

Multiple parameters with the same names are supported.

195
 Tibigen Digital Repository - REST API

Example of representation

<process name="export" collection-id="1">

    <process-param name="targetStorageId" value="2"/>
</process>

Table 57. Process Request properties

Name Type Description

name string A name of the process to execute. This is a name of file with
process definition or name of embedded process. Required.

collection-id integer An id of metadata collection. For each item on the collection,

new instance of process will be executed. Required only for
requests send to /processes/batch endpoint.

process-params Process Param list A list of process parameters.

7.1.2. Process Param

A process param object represents single parameter of the process.

Example of representation

<process-param name="targetStorageId" value="2"/>

Table 58. Process Param properties

Name Type Description

name string A name of the process parameter. Required.

value string A value of the process parameter. Required.

7.1.3. Execution Result List

An execution result list contains Execution Result objects.

Example of representation

<execution-results>
    <execution-result item-uuid="9718d3d0-bbb9-47c0-bfcc-6cae50e1a8a8" value="1"/>
    <execution-result item-uuid="17de1126-81d9-48ae-970a-7f044ec50647" error=
"AuthorizationFailedException"/>
</execution-results>

196
 Tibigen Digital Repository - REST API

7.1.4. Execution Result

Execution Result object contains status of process execution for single item. If the execution succeed,
result will contain value property with scheduled queue id. Otherwise, an error property will be
present with error code.

Example of representation of Execution Result after successful process schedule.

<execution-result item-uuid="9718d3d0-bbb9-47c0-bfcc-6cae50e1a8a8" value="1"/>

Example of representation of Execution Result after error.

<execution-result item-uuid="17de1126-81d9-48ae-970a-7f044ec50647" error=

"AuthorizationFailedException"/>

Table 59. Execution Result properties

Name Type Description

item-uuid uuid An UUID of item from the metadata collection for which
process was executed.

value integer An id of scheduled job queue or 0 if user executed

embedded process.

error string A code of an error that occurred during process execution.

7.1.5. Execute process

The following web-service allows to execute single process. User has to provide process name and at
least required process parameters.

In web-service call, system tries to locate process of given name. It searches set of embedded processes
and if no process was found, searches processes definition.

The web-service returns id of scheduled queue or 0 in case of embedded process, which executes
immediately.

Request

POST /processes/single

In the request body, supply a Process Request object with at least process name and required process
parameters.

197
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission execute.process.PROCESS_NAME, where
PROCESS_NAME is a name of the process which should be executed.

This request verifies process permission requirements.

Response
If successful, the response status code is 200 OK and body contains Value object wrapped in Response
object. This value object contains id of scheduled job queue or if process executed immediately as
embedded process, value 0.

Errors

Error code Status Description

code

ProcessNotFoundException 404 Cannot find process with given name.

ProcessParameterNotFoundE 404 One of the required process parameter is not specified.

xception

InvalidProcessException 500 Process found but its definition (in /etc/tdr/queues) is

invalid.

7.1.6. Execute process on collection

Execute process on each item from metadata collection. Executed process has to be process operating
on item (it has to have itemUuid parameter).

Request

POST /processes/batch

Query parameters

Name Type Description

detailed boolean If true, returns detailed representation of execution results.

Default value is false.

In the request body, supply a Process Request object with at least required properties and process
parameters. In order to locate valid collection, process request object has to have collection-id property
specified.

198
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission execute.process.PROCESS_NAME, where
PROCESS_NAME is a name of the process which should be executed.

This request verifies process permission requirements individually for each item in collection.

Response
If successful, the response status code is 200 OK and body contains Execution Result List object
wrapped in Response object. This execution result list contains ids of scheduled job queues or error
messages if scheduling failed.

Errors

Error code Status Description

code

MetadataCollectionNotFound 404 Cannot find metadata collection with given id.

Exception

ProcessNotFoundException 404 Cannot find process with given name.

ProcessParameterNotFoundE 404 One of the required process parameter is not specified.

xception

InvalidProcessException 500 Process found but its definition (in /etc/tdr/queues) is

invalid.

7.1.7. List available processes

List available processes names. The list contains embedded processes as well as definition based
processes.

Request

GET /processes

Authorization
This request requires authentication.

Response
If successful, the response status code is 200 OK and body contains Value List object wrapped in
Response object. Value List object contains names of all processes currently known to the system.

199
 Tibigen Digital Repository - REST API

7.2. Embedded Processes

This section describes processes embedded in TDR. They are core processes that cannot be changed.

7.2.1. Clear Index Process

TDR uses Solr for indexing of textual data. Each language defined in TDR is represented in Solr as
separate index (core). The process responsibility is to clear indexes for all languages defined in TDR. To
achieve this, process executes delete query "*:*" on Solr server.

This process should be executed before Rebuild Index Process in order to rebuild index from scratch.

The process reads solr.url TDR configuration property to access to Solr server.

Name
clear_index

Parameters
This process does not take any parameters.

7.2.2. Rebuild Index Process

This process is responsible for rebuilding indexes for all languages defined in TDR. It uses solr.url TDR
configuration property to establish a connection to Solr server.

The only data that process indexes is metadata items and theirs content. Due to the fact that Solr is
document database and documents have flat structure, indexing process need to transform tree-
structured data to valid Solr format. The transformation is called flattening and it involves removing
all groups from metadata item so that all fields can be direct children of item. Moreover, process
indexes items in two forms - with and without hierarchy. An item indexed with hierarchy appears in
Solr as document containing all fields for that item and all fields from its ancestors and descendants.
The second form - item without hierarchy - appears as item with fields form this item only.

These two forms allow to more flexible queries. You should always specify an attr.hierarchy condition
in your queries. The attr.hierarchy attribute is boolean attribute which tells search engine what type of
indexed item to retrieve - with hierarchy (true) or without (false). If you do not pass attr.hierarchy
condition, search engine will return doubled results, which can be confusing.

When indexing process finishes transforming item and has the document in Solr format, it will replace
existing document is Solr server. The important note here is Rebuild Index Process does not remove
documents from Solr when theirs counterpart items are no longer in TDR. To get that behavior, you
need first execute process Clear Index Process.

At the beginning, process invalidates indexes for all metadata items. This can be observed by checking
index-valid item property. After that, web-service running the process returns. The actual indexing is
done in the background and it gradually sets index-valid properties to true.

200
 Tibigen Digital Repository - REST API

Items based on types with indexed property set to false, are not added to Solr, but their index-valid
properties are managed the same way as indexed items. So, after successful index rebuild all items
should have index-valid set to true.

Name
rebuild_index

Parameters
This process does not take any parameters.

7.2.3. Synchronize Index Process

Synchronize Index process rebuilds indexes of items, which have index-valid equal to false. The
indexing operation is identical to that executed in Rebuild Index Process, except that synchronization
does not invalidate indexes for all items but uses this information to update indexes.

Name
synchronize_index

Parameters
Process does not take any parameters.

7.2.4. Archive Item Process

Archive Item process is responsible for removing metadata items. In TDR there is not possible to
completely delete items from the system. To hide item from search results and other system
operations, user can archive it. The metadata item, after archiving, transforms to archival item and it
is stored in special tables in database. Archival items can be later restored if needed using Restore Item
Process.

When user launch archive item process, system will remove given item and all its descendants from
search indexes.

Name
archive_item

Parameters

Name Type Description

itemUuid uuid An UUID of item to archive. Required.

201
 Tibigen Digital Repository - REST API

7.2.5. Restore Item Process

Restore Item process moves back archival metadata item to ordinary items set. During that operation,
the process will restore given item and it’s ancestors if that ancestors have also been archived. The
process does not restore children items.

After successful restore, given item and its ancestors will be visible in search results and can be used
as parameters for other processes.

Name
restore_item

Parameters

Name Type Description

itemUuid uuid An UUID of item to restore.

itemRootUuid uuid A root UUID of tree of items to restore.

7.2.6. Create Language Version Process

This process is responsible for creating new language version of given item and copying fields, which
values or references are language-agnostic. In order to create new language version of item, version in
default system language must exist.

In detail, process reads item in default language version (a template item) and creates new item with
the same UUID and language given for the new version. The newly created item contains equal content
as it’s template - groups and fields are also copied. Next step is to remove language dependant field
values, which affect all value field having translatable set to true in their types.

Since adding new language version, system will manage both or more of them. After updating one of
the versions, system will automatically apply changes on other language versions.

Name
create_language_version

Parameters

Name Type Description

itemUuid uuid An UUID of item for which new language version will be
created. Required.

itemLanguage string A name of the language of new language version. Required.

202
 Tibigen Digital Repository - REST API

7.2.7. Synchronize LDAP User Process

This process is responsible for synchronizing LDAP user with TDR. It is executed every time, when user
is authenticated in TDR with LDAP server. When User is synchronizing first time it will be created in
TDR as user entity with ldap field set to true. User will be created only if it is member of configured
LDAP groups (ldap.groups system configuration parameter). If user is not member of any configured
LDAP group it will be deleted from TDR. Every configured LDAP group, that user is member, will be
assigned to that user as role. Roles that not exist in TDR will be created with the same name as
configured LDAP groups.

List of synchronized user fields

User field LDAP attribute

login Configuration property ldap.login.attribute. Default value sAMAccountName.

Required

first-name givenName

last-name sn

email mail Required

roles memberOf (only configured LDAP groups) Required

Name
ldap_synchronize_user

Parameters

Name Type Description

login string Login of user to synchronize with LDAP. User must be LDAP
user. Required.

7.2.8. Synchronize LDAP Users Process

This process is responsible for synchronizing LDAP users and groups stored in TDR. Every configured
LDAP group (ldap.groups system configuration parameter) will be created in TDR as role with the same
name as group. Only new roles are added, existing are never removed.

Synchronization of users will be done with Synchronize LDAP User Process. It will be executed for
each user that has ldap field set to true.

Name
ldap_synchronize_user

203
 Tibigen Digital Repository - REST API

Parameters
Process does not take any parameters.

7.3. Process Definitions

This is a sample definition of the process:

<job-queue created-by="$required_user[0]" #if($optional_priority[0]) priority=

"$optional_priority[0]" #end>
    <job name="transcoder" type="TRANSCODE">
        <input>
            <asset name="itemUuid" rel="item" value="$required_itemUuid[0]"/>
#foreach($id in $required_specificationId)
            <asset name="specificationId" value="$id"/>
#end
#if($optional_overrideOutput[0])
            <asset name="overrideOutput" value="$optional_overrideOutput[0]"/>
#end
        </input>
    </job>
    <job type="EXPORT">
        <input>
            <asset name="targetStorageId" value="$required_targetStorageId[0]"/>
#if($optional_targetDirectory[0])
            <asset name="targetDirectory" value="$optional_targetDirectory[0]"/>
#end
            <asset name="fileAbstractId" ref="transcoder.fileAbstractId"/>
        </input>
    </job>
</job-queue>

The file content conforms to syntax rules of Apache Velocity template engine. To learn about powerful
features which Velocity have, you should visit its documentation at http://velocity.apache.org/.
Following description focuses only on features commonly used while writing process definition for
TDR.

Above example defines process which is job queue consisting two jobs: TRANSCODE and EXPORT. For
now, this file contains special Velocity directives like #if or #foreach, but after processing it will be a
valid XML file representing Job Queue object. Names starting with dollar sign $ are also special
identifiers for Velocity - they are variables. While processing, Apache Velocity reads variables from

204
 Tibigen Digital Repository - REST API

context passed to processing and based on values of these variables executes directives.

In TDR process definition, context variables are always arrays, to support multi-value process
parameters. Therefore, in the example if single value is needed, variables are accessed by index.
Additionally, TDR introduced logic that validates variables presence. Variables can be required or
optional - this must be specified before variable names. All variables defined in process definition will
be parameters of that process. #if directive inserts its body to final file only if variable in parenthesis is
true. #foreach directive repeats its body for each variable present in an array.

7.4. Job Queues

Job queue groups jobs into logical unit that realizes common goal. In TDR, queues always have to be
created - you cannot schedule single job without queue. By default, jobs contained in queue are
executed sequentially, but by manipulating job’s sequence property is it possible to make jobs to
execute in parallel.

There are two type of job queues in TDR: single and cyclic. Single queues are added directly to main
execution queue and are executed only once. On the other hand, cyclic queues can be executed
multiple time. They are like templates for the single queues. TDR creates single queues based on cyclic
queue at intervals defined by cron-expression property.

TDR orders queues by theirs priority property. Jobs from queues with bigger priority will be executed
earlier.

7.4.1. Job Queue

205
 Tibigen Digital Repository - REST API

Example of representation

<job-queue id="2731"
           type="SINGLE"
           name="Check access"
           status="FINISHED"
           priority="50"
           cron-expression="
           created="2016-01-26 13:40:00"
           created-by="admin"
           updated="2016-01-26 13:40:00">
    <job id="2741"
         type="CHECK_ACCESS"
         status="FINISHED"
         progress="100"
         sequence="0"
         approved="true"
         worker-id="12"
         scheduled="2016-01-26 13:40:00"
         started="2016-01-26 13:40:08"
         finished="2016-01-26 13:40:08"
         queue-id="2731">
        <message/>
    </job>
</job-queue>

Table 60. Job properties

Name Type Description

id integer An identifier of job queue.

type string A type of job queue. Required. Possible values are:

- SINGLE - job queue will be executed only once,
- CYCLIC - job queue will be executed periodically based on
cron-expression parameter.

name string A name of job queue.

priority integer The execution priority of job queue. Queues with higher
priority will be executed before other queues with lower
priorities. Priority can by any number between 1 and 100.

206
 Tibigen Digital Repository - REST API

Name Type Description

status string A current state of job queue. Possible values are:

- WAITING - job queue waits for execution,
- RUNNING - job queue is executing right now,
- PAUSING - job queue is executing pausing sequence in
order to pause,
- PAUSED - job queue is paused,
- EXPIRED - job queue waited too long to execute and finally
expired. This will occur if one of the jobs contained in job
queue expires,
- FINISHED - job queue finished successfully,
- FAILED - job queue finished with failures,
- RESUMING - job queue is executing resuming sequence in
order to continue running,
- STOPPING - job queue is executing stopping sequence in
order to stop running.

created datetime A time when job queue was created.

created-by datetime A login of the user, who created this job queue.

updated datetime A last time when job queue was updated.

cron-expression string The Cron expression.

7.4.2. Job Queue List

A job queue list object is a container of Job Queue objects.

207
 Tibigen Digital Repository - REST API

Example of representation

<job-queues total="1632">
    <job-queue id="2731"
               type="SINGLE"
               name="Check access"
               status="FINISHED"
               priority="50"
               created="2016-01-26 13:40:00"
               created-by="admin"
               updated="2016-01-26 13:40:00">
        <job id="2741"
             type="CHECK_ACCESS"
             status="FINISHED"
             progress="100"
             sequence="0"
             approved="true"
             worker-id="12"
             scheduled="2016-01-26 13:40:00"
             started="2016-01-26 13:40:08"
             finished="2016-01-26 13:40:08"
             queue-id="2731">
            <message/>
        </job>
    </job-queue>
<job-queues>

7.4.3. List job queues

List job queues. This web-service has advanced filtering features described below.

Single query param filter syntax:

<object-name>.<field-name>=[<operator>:]<field-value>[,<field-value>]…
where:

• <object-name> can be queue or job,

• <field-name> can be name of the one of the object’s property as described in a table bellow,

• <operator> can be one of the operators: EQ (equal), NE (not equal), LE (less than or equal), GE
(greater than or equal); operator is optional; default operator is EQ,

• <field-value> value of field, can be multiple values separated by commas, the values are implicitly
joined with OR operator.

208
 Tibigen Digital Repository - REST API

For example, to search for queues with jobs started after 2015-01-01 00:00:00 you should pass such a
query param: job.started=GE:2015-01-01 00:00:00.

The query params allow to fiter by queue or job properties. If job property field has been used, web-
service still returns job queues, but only these containing jobs matching filter criteria. Query params
can be repeated for the same field - all occurrences will be joined with AND logical operator.

Request

GET /queues?queue.id={id}
           &queue.name={name}
           &queue.status={status}
           &queue.type={type}
           &queue.created={created}
           &queue.created-by={user}
           &queue.last-modified-by={user}
           &queue.priority={priority}
           &job.id={id}
           &job.type={type}
           &job.status={status}
           &job.scheduled={date}
           &job.started={date}
           &job.expired={date}
           &job.finished={date}
           &job.approved={approved}
           &job.worker-id={id}
           &page={page}
           &size={size}

Query parameters

Name Type Description

queue.id integer The identifier of job queue.

queue.name string The name of job queue.

queue.status string The current status of job queue.

queue.type string The type of job queue.

queue.created datetime The time when job queue was created.

queue.created-by string A login of the user, who created job queue.

209
 Tibigen Digital Repository - REST API

Name Type Description

queue.last-modified-by string A login of the user who updated job queue for the last time.

queue.priority integer The execution priority of job queue.

job.id integer The identifier of job.

job.type string The type of job.

job.status string The current status of job.

job.scheduled datetime The time when job was scheduled (created).

job.started datetime The time when job was sent to worker.

job.expired datetime The time when job will expire.

job.finished datetime The time when job finished either with success or failure.

job.approved datetime The approval status of job.

worker-id integer An identifier of the worker which is executing or finished

execution of job.

page integer The number of page of results to return. If not specified,

returns all job queues.

size integer The size of the page of results. Default value is 10.

Authorization
This request requires authorization with permission view.process.

Response
If successful, the response status code is 200 OK and body contains Job Queue List object wrapped in
Response object.

7.4.4. Get job queue

Get job queue with all jobs contained in it. Jobs will be returned without inputs and outputs, they have
to be get separately.

Request

GET /queues/{id}

Path parameters

210
 Tibigen Digital Repository - REST API

Name Type Description

id integer An identifier of queue to get.

Authorization
This request requires authorization with permission view.process.

Response
If successful, the response status code is 200 OK and body contains Job object wrapped in Response
object.

Errors

Error code Status Description

code

JobDaemonException 404 Cannot find job queue with given id.

7.4.5. Update job queue

Update job queue. For now, the only possible property to change is queue’s priority. You don’t have to
send entire job queue object. Besides priority, all other properties are ignored.

Request

PUT /queues/{id}

Path parameters

Name Type Description

id integer An identifier of job queue to update.

In the request body, supply a Job Queue object with updated priority property.

Authorization
This request requires authorization with permission manage.process.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

211
 Tibigen Digital Repository - REST API

Errors

Error code Status Description

code

JobDaemonException 400 Some of the job queue properties are invalid.

JobDaemonException 404 Cannot find job queue with given id.

7.4.6. Delete job queue

Delete job queue. The queue can be deleted only if it has one of the statuses: WAITING, FINISHED,
FAILED, EXPIRED.

Request

DELETE /queues/{id}

Path parameters

Name Type Description

id integer An identifier of job queue to delete.

Authorization
This request requires authorization with permission manage.process.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

JobDaemonException 404 Cannot find job queue with given id.

JobDaemonException 403 Job queue is running and therefore queue cannot be deleted.

7.5. Jobs
Job represents consistent operation which is executed on various resources of TDR. The kind of this
operation is designated by type property. Job has its own lifecycle, which is managed by Job Daemon
component. After scheduling, the job waits for execution. Job can be executed only if suitable worker
exists.

212
 Tibigen Digital Repository - REST API

7.5.1. Job
Example of representation

<job id="1"
     type="IMPORT"
     name="importer"
     status="FINISHED"
     progress="100"
     sequence="0"
     approved="true"
     worker-id="323"
     scheduled="2015-12-04 12:03:51"
     started="2015-12-04 13:47:12"
     finished="2015-12-04 13:47:28"
     queue-id="518647">
     <message></message>
</job>

Table 61. Job properties

Name Type Description

id integer An identifier of job.

type string A type of job. See more in Job Types. Required.

name string A name of job. Required, if jobs after this job in queue
reference this job’s outputs.

status string A current state of job. Possible values are:

- WAITING - job waits for execution,
- RUNNING - job is executing right now,
- PAUSING - job is executing pausing sequence in order to
pause,
- PAUSED - job is paused,
- EXPIRED - job waited too long to execute and finally
expired. This can occur if expired property has been set,
- FINISHED - job finished successfully,
- FAILED - job finished with failures,
- RESUMING - job is executing resuming sequence in order to
continue running,
- STOPPING - job is executing stopping sequence in order to
stop running.

progress integer A percentage number designating how many work has been
already executed.

213
 Tibigen Digital Repository - REST API

Name Type Description

sequence integer A number starting from 0 representing order in which jobs

will be executed in queue. If multiple jobs have equal
sequence, these jobs will be executed in parallel.

approved boolean Must be true in order to start executing job. Default value is
true.

worker-id integer An identifier of worker which is executing or finished

execution of this job.

scheduled datetime A time when job was added to job daemon.

started datetime A time when job was sent to worker for execution.

expired datetime A time after which job will expire and will never run.

finished datetime A time when job successfully finished or ended with failure.

queue-id integer An identifier of queue to which this job belongs.

message string A message that can contain runtime information, warning

and errors.

214
 Tibigen Digital Repository - REST API

Figure 3. Possible transitions of job status

7.5.2. Job List

A job list object is a container of Job objects.

215
 Tibigen Digital Repository - REST API

Example of representation

<jobs>
    <job id="1"
         type="IMPORT"
         name="importer"
         status="FINISHED"
         progress="100"
         sequence="0"
         approved="true"
         worker-id="323"
         scheduled="2015-12-04 12:03:51"
         started="2015-12-04 13:47:12"
         finished="2015-12-04 13:47:28"
         queue-id="518647">
         <message></message>
    </job>
</jobs>

7.5.3. Job Asset

Job assets are objects that can be inputs and outputs of jobs. If you want to pass simple string value to
job, you can use value property of job asset. Also, input job asset gives possibility to connect to other
job asset, which is output of preceding job in a job queue. This relationship can be established by using
ref property.

Example of representation of asset with value

<asset index="0"
       name="targetItemUuid"
       rel="item"
       value="076c4fc8-a1b3-40b9-befd-772a91d1ffe5" />

Example of representation of asset with reference

<asset index="0"
       name="targetItemUuid"
       rel="item"
       ref="itemCreator.uuid" />

Table 62. Job Asset properties

216
 Tibigen Digital Repository - REST API

Name Type Description

name string A name of the asset.

index integer A number indicating order of assets with the same name.

value string A value of this job asset.

ref string A reference to one of preceding job’s output property. The

reference is constructed in the following manner:
<preceding-job-name>.<output-name>, which is preceding
job name (the preceding job must first be named), a dot
character and preceding job’s output asset name.

rel string Describing kind of information contained in value or ref

properties. The only possible value for now is item, which
indicates that above properties contain or reference to item
uuid.
This property can be used to build additional logic above
value or ref. For example some UI can make UUID with
rel="item" a clickable link, which will open item with that
UUID.

7.5.4. Job Asset List

A job asset list object is a container of Job Asset objects.

Example of representation

<assets>
    <asset index="0" name="sourceStorageId" value="1"/>
    <asset index="0" name="targetItemUuid" rel="item" value="076c4fc8-a1b3-40b9-befd-
772a91d1ffe5"/>
    <asset index="0" name="fileTypeId" value="2"/>
    <asset index="0" name="inputFile" value="video.mpeg"/>
    <asset index="0" name="deleteInputFiles" value="false"/>
    <asset index="0" name="fileGroupName" value="video"/>
</assets>

7.5.5. Get job

Get job. Job’s inputs and outputs have to be retrieved separately.

Request

GET /jobs/{id}

217
 Tibigen Digital Repository - REST API

Path parameters

Name Type Description

id integer An identifier of job to get.

Authorization
This request requires authorization with permission view.process.

Response
If successful, the response status code is 200 OK and body contains Job object wrapped in Response
object.

Errors

Error code Status Description

code

JobDaemonException 404 Cannot find job with given id.

7.5.6. Get job input

Get job input.

Request

GET /jobs/{id}/input?page={page}&size={size}

Path parameters

Name Type Description

id integer An identifier of job which input will be returned.

Query parameters

Name Type Description

page integer The number of page of results to return. If not specified,

returns all assets.

size integer The size of the page of results. If not specified, returns all
assets.

218
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission view.process.

Response
If successful, the response status code is 200 OK and body contains Job Asset List object wrapped in
Response object.

Errors

Error code Status Description

code

JobDaemonException 404 Cannot find job with given id.

7.5.7. Get job output

Get job output.

Request

GET /jobs/{id}/output?page={page}&size={size}

Path parameters

Name Type Description

id integer An identifier of job which output will be returned.

Query parameters

Name Type Description

page integer The number of page of results to return. If not specified,

returns all assets.

size integer The size of the page of results. If not specified, returns all
assets.

Authorization
This request requires authorization with permission view.process.

Response
If successful, the response status code is 200 OK and body contains Job Asset List object wrapped in

219
 Tibigen Digital Repository - REST API

Response object.

Errors

Error code Status Description

code

JobDaemonException 404 Cannot find job with given id.

7.5.8. Update job

Update job. The only properties which should be changed from the perspective of person who manages
job execution are status and approved. In this case, you don’t have to send entire job object. Properties
other that mentioned earlier are ignored.

For status property, valid values depend on current job status. The job’s status transition diagram is
depicted in Job section. Furthermore, possible statuses to set are limited to those values:

• PAUSING - to pause the job,

• RESUMING - to resume the job,

• STOPPING - to stop the job,

• WAITING - to restart the job.

The other usage of this web-service is to allow workers to inform TDR about completed jobs. Worker,
which want to complete the job, have to send job object with status property having values FINISHED
or FAILED and message and output properties if present.

Request

PUT /jobs/{id}

Path parameters

Name Type Description

id integer An identifier of job to update.

In the request body, supply a Job object with updated properties.

Authorization
If user tries to change approved property, authorization with permission
accept.process.PROCESS_NAME is required, where PROCESS_NAME is a name of job queue which
contains job to update. In this situation, service verifies process permission requirements.

220
 Tibigen Digital Repository - REST API

Otherwise, this request requires authorization with permission manage.process. The permission
requirements are not verified.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

JobDaemonException 404 Cannot find job with given id.

JobDaemonException 403 Transition to given job status cannot be done.

7.6. Job Types

There are multiple predefined job types in TDR. Job types are capabilities that workers provide. Job
type describes very specific operation or set of operations done be workers, required to accomplish
specific goal. There are job types that do simple tasks on file system or more complex job types that use
the REST API to alter TDR state. Job types can be dynamically added by registering custom-developed
workers.

7.6.1. Callback Job

Callback Job requests address specified in url input. Every request will be made with POST method.
Optionally adds to requested address query parameters with values of itemUuid, assetId, fileId or
instanceId inputs. Job finish successfully when requested service returns 200 HTTP status code,
otherwise it will fail.

Type
CALLBACK

Inputs

Name Type Description

url string Url address of service that will be requested. REQUIRED

itemUuid uuid If specified, callback will be requested with itemUuid query

parameter.

assetId integer If specified, callback will be requested with assetId query

parameter.

fileId integer If specified, callback will be requested with fileId query

parameter.

221
 Tibigen Digital Repository - REST API

Name Type Description

instanceId integer If specified, callback will be requested with instanceId query

parameter.

7.6.2. Check Access Job

Check Access Job verifies access methods of all storages. Job tries to connect to storages by each access
method. When connection will be established with success, job marks storage access as available, and
otherwise as unavailable.

Check Access Job by default is configured in cyclic queue that runs every 10 minutes. That frequent
checking is needed for valid determination of optimal storage for other processes.

Type
CHECK_ACCESS

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

Outputs
This job does not produce any output.

7.6.3. Check Space Job

Check Space Job calculate used space on each storage in TDR. It adds sizes of all files in the storage and
updates storage’s used-space property.

Type
CHECK_SPACE

Inputs

222
 Tibigen Digital Repository - REST API

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

Outputs
This job does not produce any output.

7.6.4. Clear Directory Job

Clear Directory Job deletes all files in specified directory.

Type
CLEAR_DIRECTORY

Inputs

Name Type Description

directory string A path to directory which will be cleared. Required.

Outputs
This job does not produce any output.

7.6.5. Copy Files Job

Copy Files Job copies files specified in its input to given output directory. If files with the same names
already exist in output directory, it will override that files.

Type
COPY_FILES

Inputs

Name Type Description

inputFile string A path to file to copy. Can be specified multiple times.

Required.

outputDirectory string A path to directory to which files will be copied. Required.

223
 Tibigen Digital Repository - REST API

Outputs
This job does not produce any output.

7.6.6. Delete File Copies Job

Delete File Copies Job finds storages of INTERNAL type that usage exceed high watermark and execute
delete process with file instances of given asset type, stored on that storage. Only instances of files that
have instances on library are chosen. In the first place, instances of asset with the oldest last access
time are chosen. Processes are executed until calculated usage of storage is equal or lower than its low
watermark.

Type
DELETE_FILE_COPIES

Inputs

Name Type Description

assetTypeId integer List of ids of asset types that copies should be deleted.

Outputs

Name Type Description

success string For each storage with exceed high watermark this output
will be set. Format of this output is as follows: Release space
on storage with id <storage id> and name <storage name>..

success string For each executed delete process this output will be set.
Format of this output is as follows: Execute delete process
with id <process id>. Files to delete <number of instances>
with size <summary size of instances>..

success string For each storage with enough copies to release usage to low
watermark this output will be set. Format of this output is as
follows: Released space on storage with id <storage id> and
name <storage name>. Usage <calculated storage usage>
Low watermark <storage low watermark>..

warning string For each storage with not enough copies to release usage to
low watermark this output will be set. Format of this output
is as follows: Cannot release space to low watermark
<storage low watermark> on storage with id <storage id>
and name <storage name>. Storage usage after files will be
deleted <calculated storage usage>..

224
 Tibigen Digital Repository - REST API

7.6.7. Delete Files Job

Delete Files Job detaches from item and deletes physical representation of files previously imported to
TDR. Different inputs allow to specify which files should be deleted.

By setting itemUuid and optionally assetTypeId, you can specify that this job will delete all assets
attached to item or assets with given asset type. Another way is to specify concrete asset id. There is
also possibility to delete specific files and specific instances of files.

Type
DELETE

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

itemUuid uuid If specified, files attached to that item will be deleted. The
deletion can be narrowed down to specific asset type by
setting assetTypeId input.

assetTypeId integer If specified, narrows down types of files to delete from given
item.

assetId integer Id of asset to delete. All files contained in that asset will also
be deleted.

fileId integer Id of file to delete. Can be specified multiple times.

fileInstanceId integer Id of file instance to delete. Can be specified multiple times.

force boolean Forces removal of the files, even if in growing state or

locked. In this case also all locks will be removed.

Outputs

Name Type Description

success string For each deleted file this output will be set. Format of this
output is as follows: Deleted file path: <path>, where <path>
is absolute path of deleted file.

225
 Tibigen Digital Repository - REST API

Name Type Description

error string For each failure of file deletion this output will be set.
Format of this output is as follows: Could not delete file. File
path: <path>, where <path> is path of file which cannot be
deleted.

7.6.8. Delete Item Job

Delete Item Job deletes given item or its specific language version from TDR. If entire item is deleted,
all files attached to that item will also be deleted.

Type
DELETE_ITEM

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

itemUuid uuid An UUID of item to delete. Required.

itemLanguage string If specified, only this language version of item will be

deleted.

Outputs
This job does not produce any output.

7.6.9. Delete Outdated Files Job

Delete Outdated Files Job execute delete and tsm_delete processes for assets that are outdated by
retention policies. Asset is outdated when it’s owner item is older (by item created property) than
retention policy period. Asset’s owner item type has to have indexed property set to true otherwise it
won’t be found by this job.

Type
DELETE_OUTDATED_FILES

226
 Tibigen Digital Repository - REST API

Outputs

Name Type Description

success string For each executed deleting process this output will be set.
Format of this output is as follows: Execute delete process
with id <proces id> for asset with id <asset id>..

success string For each executed deleting archived files process this output
will be set. Format of this output is as follows: Execute tsm
delete process with id <proces id> for asset with id <asset
id>..

7.6.10. Edit Items

Edit Items Job edit metadata items in given collection. Only items in given type are modified. Only
given given attribute or field type fields are modified. One of inputs fieldType or attributeName is
required. Supported attributes: retention-policy.

Job can perform three operation types:

• new - add new field when field does not exist (create groups if it is necessary). For repeatable field
types, creates new field, when field with given value does not exist. If there is multiple groups
where field can be added, it adds field in each group.

• override - remove all fields of given field type and add field with given value. If there is multiple
groups where field can be added, it adds field in each group.

• condition - modify field only when condition determinated by condition value and condition
operator is satisfied.

Type
EDIT_ITEMS

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

collectionId long A id of collection that contains items for edit. Required.

227
 Tibigen Digital Repository - REST API

Name Type Description

itemType string An item type name to edit. Items of other types will be
skipped. Required.

fieldType string A field type name to edit.

attributeName string A attribute name to edit.

language string A language of edited items. Should be provided when

modified field is translatable. Default value is default
language.

operationType string An operation type. Available operation types: "new",

"override" or "condition". Required.

conditionOperator string A condition operator of condition operation type. Available

operators: "equals" or "not_equals".

conditionValue string A condition value of condition operation type.

value string A new field value. For reference fields types value should be
valid uuid. Required.

7.6.11. Export Job

Export job copies files specified by itemUuid, assetTypeId, assetId or fileId inputs to target storage. Job
gives possibility to choose destination directory on target storage and allows to decide if copy
operation should override existing files. Also, you can set name of target file, if only one file is
exported.

Type
EXPORT

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

assetId integer Id of asset which will be exported.

fileId integer Id of file which will be exported. Can be specified multiple

times.

228
 Tibigen Digital Repository - REST API

Name Type Description

itemUuid uuid An UUID of item. If specified, files attached to that item will
be exported. The list of files to export from item can be
narrowed down by specifying assetTypeId property.

assetTypeId integer Id of asset type to export. If specified, narrows down list of

all files to export from item.

targetStorageId integer An id of target storage on which files will be copied.

Required.

targetDirectory string A path to directory on target storage to which files will be

copied. If directory does not exist, job will create that
directory. Default value is storage’s root directory /.

outputName string A name of the output file, if only one file is exported. Specify
output name without file extension - file extension will be
copied from original file name. If not specified, job is using
original file name.

lockWaitingTimeo integer The maximum number of minutes to wait in order to set

utInMinutes WRITE lock on file instances to export. Default value is 1440
which is 24 hours.

replaceExisting boolean If true, all files, existing on target storage and having names
exactly the same as exported files, will be overridden.

createTargetFolder boolean If true, export job will create additional folder, on target
storage, with the name of source Item title, where all
exported files will be placed. The default value is false.

Outputs
This job does not produce any output.

7.6.12. Generate Descriptor Job

Generate Descriptor Job computes video descriptor file, which contains metainformation about spatial
content of video file. This descriptor is optimized for video searching. It can be compared to index file
in case of textual data.

Job generates video descriptor using Video Analyzer software and attaches it to item designated with
itemUuid input.

Type
GENERATE_DESCRIPTOR

229
 Tibigen Digital Repository - REST API

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

mediainfoPath string A path to MediaInfo software which will be used to generate

technical metadata of video descriptor file. Required.

videoAnalyzerPath string A path to Video Analyzer software which will be used to

generate video descriptor. Required.

videoAnalyzerThre integer The number of threads generating video descriptor.

ads

descriptorAssetTyp integer An id of asset type representing video descriptor in TDR.

eId Required.

itemUuid uuid An UUID of item with source video file attached to it.
Required.

sourceAssetTypeId integer An id of asset type representing source video e.g. low res
asset type. Required.

Outputs

Name Type Description

descriptorAssetId integer An id of asset which contains video descriptor.

descriptorFileInsta integer An id of file instance which represents physical file with

nceId video descriptor.

7.6.13. Image Convert Job

Image Convert Job converts images to different formats using ImageMagick software. The conversion
uses parameters passed in transcoding specification to produce target file. After conversion, file is
registered in TDR and attached to item, from which source file was obtained.

Type
IMAGE_CONVERT

230
 Tibigen Digital Repository - REST API

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

lockWaitingTimeo integer A number of minutes after which job will stop trying to lock
utInMinutes source file instances to write. Default value is 1440 which is
24 hours.

imageMagickPath string A path to ImageMagick convert software which will be used

to convert images. Required.

mediainfoPath string A path to MediaInfo software which will be used to generate

technical metadata of target file. Required.

imageMagickIdenti string A path to ImageMagick identify software which will be used

fyPath to generate technical metadata of target image file.

itemUuid uuid An UUID of item to which source file is attached. Required.

assetId integer An id of asset which contains source file.

assetName string A name of asset which will be created in order to store

target file.

targetStorageId integer If specified, conversion result will be stored on this storage.

Otherwise, job will try to find optimal storage for that
purpose.

specificationId integer An id of transcoding specification, which will be used to

locate source file instance and target asset type for
conversion. Can be specified multiple times - single
specification is single conversion.

Outputs

Name Type Description

itemUuid uuid An UUID of item to which job attached results of

conversions. Same as itemUuid input.

fileId integer An id of file which stores results of conversion. Can occur

multiple times - one file per one conversion.

231
 Tibigen Digital Repository - REST API

7.6.14. Import Job

Import Job copies files from specified location to TDR’s internal storage and attaches them to specified
target item. It is possible to attach files to existing asset or delegate creation of new asset to the job.

There are two ways to pass source location: through sourceStorageId and inputFile or inputUri inputs.
The first way assumes that source storage, which id is given in sourceStorageId input, already exists in
TDR and has valid access methods. By specifying that storage id and relative path to file or directory on
that storages, you identify resources to import. Other way gives possibility to connect through
supported protocol to remote location like FTP server. This is done by specifying inputUri input.

If input path leads to directory, this directory and all nested files and directories will be attached to
single asset.

Before copying files, job registers asset (if new is created), files and their instances. Registered
instances have growing properties set to true.

For all assets job will generate technical metadata item and attach it to target item as child.

Type
IMPORT

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

mediainfoPath string A path to MediaInfo software which will be used to generate

technical metadata of imported files. Required.

imageMagickIdenti string A path to ImageMagick identify software which will be used

fyPath to generate technical metadata of imported image files.

sourceStorageId integer An id of IMPORT storage which contains files to import. Path

specified in inputFile is related to that storage. Ignored if
inputUri is specified.

inputFile string A path of file or directory to import, relative to source

storage. Ignored if inputUri is specified.

targetItemUuid uuid An UUID of item to which imported files will be attached

(through asset).

232
 Tibigen Digital Repository - REST API

Name Type Description

deleteInputFiles boolean If true, source files will be deleted from source storage after
successful import.

assetName string Optional name of created asset. If not specified, new asset
will get name equal to name of given asset type in
assetTypeId input.

assetId integer An id of existing asset to which file will be attached. If not

specified, new asset will be created.

assetTypeId integer An id of new asset’s type.

lockWaitingTimeo integer A maximum time to wait in minutes for target item, if item
utInMinutes has READ_WRITE lock.

inputUri string A URI identifying file or directory to import. Specify instead

of sourceStorageId and inputFile.

failedPath string An relative path, within the sourceStorage where input file
will be moved in case of failure of IMPORT job.

Outputs

Name Type Description

targetItemUuid uuid An UUID of item to which imported files were attached.

Same as targetItemUuid input.

assetId integer An id of asset that was created to store imported files.

7.6.15. Notify About Nearly Outdated Files Job

Notify About Nearly Outdated Files Job sends e-mails with subject containing retention policy name
and body with list of items (item title in default language and item UUID) that contains files that will be
outdated in number of days set by configuration property notify.retention.days.

Type
NOTIFY_ABOUT_NEARLY_OUTDATED_FILES

7.6.16. Rename File Job

Rename File Job changes name of file or directory. Job copies extension from old name if exists.

Type
RENAME_FILE

233
 Tibigen Digital Repository - REST API

Inputs

Name Type Description

inputFile string URI to file or directory to rename. Required.

newName string A new name without extension. Extension will be copied

from old name. Required.

Outputs
This job does not produce any output.

7.6.17. Resolve Path Job

Resolve Path Job creates absolute local path to file located in given storage.

Type
RESOLVE_PATH

Inputs

Name Type Description

relativePath string Path relative to storage. Required.

storageName string A name of the storage.

storageId integer An id of the storage.

One of the properties: storageName, storageId has to be specified.

Outputs

Name Type Description

absolutePath string Absolute path on storage i.e. storage local path + relative
path.

7.6.18. Retrieve Technical Metadata Job

Retrieve Technical Metadata Job reads technical metadata of files contained in given asset and create
item with these metadata. Then, job attaches this technical metadata item as a child to item which
owns given asset. Asset can be specified explicitly using assetId input or some criteria can be provided
to select multiple assets. These criteria are item UUID and optionally ids of asset types.

If technical metadata item is already attached to given asset, job will delete this item and create new
one.

234
 Tibigen Digital Repository - REST API

Currently, TDR supports three mechanisms to read metadata of multimedia files:

• MediaInfo software, good for all multimedia files,

• Identify software from Image Magick package, good for image files,

• DCP embedded reader, that extracts technical metadata from Digital Cinema Package name
following the rules of Digital Cinema Naming Convention.

An appropriate mechanism can be set in AssetType object.

Type
RETRIEVE_TECHNICAL_METADATA

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

mediainfoPath string A path to the MediaInfo software that will be used to read
technical metadata.

imageMagickIdenti string A path to ImageMagick Identify software which will be used

fyPath to read technical metadata from image files.

assetId integer An id of asset to which technical metadata will be assigned.

itemUuid uuid An UUID of item which contains assets, which technical

metadata should be created or updated.

assetTypeId integer An id of asset type. Can be specified in combination with

itemUuid to create or update technical metadata only for
assets of given asset type. Can be specified multiple times.

Outputs
Job does not produce any output.

7.6.19. Search Video Job

Search Video Job finds video files attached to items specified in indexItem inputs similar to video
attached to item specified in queryItem. The matching operation is not done directly on video files but
on video descriptors - specialized index files containing spatial information about video clip.

235
 Tibigen Digital Repository - REST API

At the beginning, job locates video descriptor file attached to queryItem. Then, it narrows down
duration of query video with start and stop timecodes, specified in startTimecode and stopTimecode
inputs respectively. After that, for each index item, job finds video descriptor attached to it and
matches this descriptor with query video descriptor.

When matching for all index items complete, job saves result of matching in special item of type
video_search_results and attaches this item to query item as child.

Type
SEARCH_VIDEO

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

queryItem uuid An UUID of item which contains query video and

corresponding video descriptor file. Fragment of this video
descriptor (designated by start and stop timecodes) will be
query in video search mechanism. Required.

startTimecode timecode A timecode that designates beginning of the query fragment

in query video. Required.

stopTimecode timecode A timecode that designates end of the query fragment in

query video. Required.

indexItem uuid A list of UUID of items that will be searched (video search
mechanism will try to match video descriptors attached to
these items with query video descriptor). Required.

Outputs
Job does not produce output.

7.6.20. Select Specification Job

Select Specification Job selects specification based on given item type. If item type equals unit_a, id of
specification given in audioSpecificationId will be copied to specificationId output. If item type equals
unit_av, id of specification given in videoSpecificationId will be copied to specificationId output.
Otherwise, no output will be produced.

236
 Tibigen Digital Repository - REST API

Type
SELECT_SPECIFICATION

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

itemUuid uuid An UUID of item which type will be tested. Required.

audioSpecificationI integer An id of specification which will be set to output if item type

d equals unit_a. Required.

videoSpecificationI integer An id of specification which will be set to output if item type

d equals unit_av. Required.

Outputs

Name Type Description

specificationId integer An id of selected specification.

7.6.21. Set Field Job

Set Field Job updates value and reference of field of type specified in fieldType input within item with
uuid as in itemUuid input. If multiple fieldType inputs are specified, job will find fields of these types
and will set equal values and references to them. If field is not found, job will create new field of given
type (only if item schema allows to that relationship).

Job only works on fields attached directly to item (item is parent entry for fields in metadata tree).
Fields contained in groups cannot be updated by this job.

Type
SET_FIELD

Inputs

237
 Tibigen Digital Repository - REST API

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

itemUuid uuid An UUID of item that directly contains fields to update.

Required.

value string A value which will be set in field. If not specified, old value
will be left.

reference string A reference which will be set in field. If not specified, old
reference will be left.

fieldType string A name of type of field to update. Required.

Outputs
Job does not produce output.

7.6.22. Transcode Job

Transcode Job executes and monitor transcoding process in external transcoding software. Currently
supported transcoders are ProMedia Carbon and FFmpeg. Integration with ProMedia Carbon is based
on communication with server through network. For FFmpeg, job spawns child process on machine
where worker executing that job is deployed.

Transcode Job provides common interface for both transcoders. This interface is mainly based on
transcoding specification, which is instruction how to locate source files for transcoding operation and
where to save transcoding results. Transcoding specifications also have references to transcoding
profiles, which are transcoder specific. All options that can be specified in transcoding profiles are
described in sections FFmpeg Profiles and ProMedia Carbon Profiles.

Type
TRANSCODE

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

238
 Tibigen Digital Repository - REST API

Name Type Description

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

itemUUid uuid An UUID of item which has attached source file for
transcoding and to which target file will be attached.
Required.

mediainfoPath string A path to MediaInfo software. MediaInfo is used for

gathering technical information about transcoding target
file. Required.

imageMagickIdenti string A path to ImageMagick identify software which will be used

fyPath for gathering technical information about transcoding target
image file.

specificationId integer An id of transcoding specification. Can be specified multiple

times if multiple transcoding operation should occur.
Required.

videoAssetId integer An id of asset which should replace default video asset

resulting from transcoding specification.

audioAssetId integer An id of asset which should replace default audio asset

resulting from transcoding specification.

imageAssetId integer An id of asset which should replace default image asset

resulting from transcoding specification.

ffmpegThreads integer A number of threads which FFmpeg will used to transcode

files. Job will pass this as option -threads to FFmpeg.

ffmpegPath string A path to FFmpeg software. If not specified, job assumes that
FFmpeg is in system PATH variable.

ffprobePath string A path to FFprobe software. If not specified, job assumes

that FFprobe is in system PATH variable.

carbonHost string A hostname or IP address of ProMedia Carbon software.

carbonPort integer A port of ProMedia Carbon software.

lockWaitingTimeo integer A number of minutes to wait for possibility to read source

utInMinutes file instances.

targetStorageId integer By default, job tries to find optimal storage to save

transcoding target file. If this input is specified, job will omit
that procedure and save transcoding target file directly to
storage of given id.

239
 Tibigen Digital Repository - REST API

Name Type Description

assetId integer An id of asset which overrides video, audio or image source

of transcoding specification. Asset overrides source only if
asset resulting from transcoding specification has exactly
the same asset type.

Inputs for transcoding profiles

Below, are listed inputs that can override parameters from ProMedia Carbon Profile and FFmpeg
Profile.

Name Type Description

startTimeCode timecode The start-timecode property from ProMedia Carbon Profile

and FFmpeg Profile.

stopTimeCode timecode The stop-timecode property from ProMedia Carbon Profile

and FFmpeg Profile.

format string The format property from ProMedia Carbon Profile or the
format property from FFmpeg Profile.

imageCount integer The image-count property from ProMedia Carbon Profile or

the count property from FFmpeg Image.

outputNameTempl string The output-name property from ProMedia Carbon Profile or

ate the output-name property from FFmpeg Profile.

overrideOutput boolean The override-output property from ProMedia Carbon Profile

or the override-output property from FFmpeg Profile.

videoFps float The video-fps property from ProMedia Carbon Profile or the
fps property from FFmpeg Video.

imageInterval integer The interval property from ProMedia Carbon Profile or the
interval property from FFmpeg Image.

imageWidth integer The image-width property from ProMedia Carbon Profile or

the width property from FFmpeg Image.

imageHeight integer The image-height property from ProMedia Carbon Profile or

the height property from FFmpeg Image.

videoWidth integer The video-width property from ProMedia Carbon Profile or

the width property from FFmpeg Video.

videoHeight integer The video-height property from ProMedia Carbon Profile or

the height property from FFmpeg Video.

skipFirstFrame boolean The skip-first-frame property from ProMedia Carbon Profile

or the skip-first-frame property from FFmpeg Image.

240
 Tibigen Digital Repository - REST API

Outputs

Name Type Description

fileId integer An id of file that is transcoding target. Can occur multiple

times.

7.6.23. TSM Archive Job

The purpose of TSM Archive Job is to execute and monitor process of archiving files on magnetic tapes
using Tivoli Storage Manager software (TSM). Job requires prerequisite configuration to be done on
TSM.

For each successfully archived file in TSM, job will register new file instance which is attached to TSM
archive.

Integration with TSM uses TSM client program: dsmc. This programs have to be available in PATH
environment variable.

Type
TSM_ARCHIVE

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

itemUuid uuid An UUID of item which has attached files to archive.

Required.

lockWaitingTimeo integer A number of minutes to wait for possibility to read file

utInMinutes instances scheduled to archive. Default value is 1440 which
is 24 hours.

Outputs
Job does not produce output.

7.6.24. TSM Archive Complex Job

The purpose of TSM Archive Job is to execute and monitor process of archiving files on magnetic tapes
using Tivoli Storage Manager software (TSM). Job requires prerequisite configuration to be done on
TSM.

TSM Archive Complex Job archives files attached to items based on archive policies. Archive policies
contain properties that define how archiving process should be launched and which files should be

241
 Tibigen Digital Repository - REST API

included in that process. User can define archive policies using web-services described in Archive
Policies section.

The first step that job executes is to find archive policy for item passed as itemUuid input. Archive
policy is matched by item type. If there are no policy with given item type, job will finish with success
and the message property will contain appropriate warning. Next step is to locate files attached to
given item. Archive policy allows to specify files-from-descendants property. When it is set to true, files
attached to both given item and its descendants will be selected to archive.

When list of files to archive has been created, job need to locate tape storage pool which will be the
target of archive operation. Storage pools in TSM are logical groups of volumes, in this case magnetic
tapes. To locate proper tape storage pool, job reads storage-pool-name property from archive policy. If
it is defined, that storage pool will be used. Otherwise, job will create new storage pool with generated
name. The important note here: upon creation of new storage pool, TSM asks for device class. Job
responds with device class specified in tsm.device_class TDR property. Web-services able to set and
update this property are described in Properties section.

Job assumes that TSM in the first place archives files to disk storage pool, which acts as a cache. Then,
files are migrated to next storage pool, which is always tape storage pool. Before archiving, job will
make sure that disk storage pool is empty e.g. all files from previous archive process have been
successfully migrated to tapes. When job detects some files on disk storage pool, it will immediately fail
with appropriate error message. When this happens, manual TSM administrator intervention will be
required.

After selecting proper tape storage pool, job sets this storage pool as a next storage pool in TSM and at
the end of the archive process job sets back empty next storage pool. Depending on the size of all files
selected to archive, TSM can spawn automatic migration process, which copies data from disk storage
pool to tape storage pool. If this does not happen, job will spawn that process anyway. Then it waits for
migration process to complete. After that, archive process can be considered as finished.

Above workflow will be repeated for each copy, as configured in number-of-copies property in archive
policy.

For each successfully archived file in TSM, job will register new file instance which is attached to target
storage pool.

Integration with TSM uses two programs included within TSM installation: dsmc and dsmadmc. These
programs have to be available in PATH environment variable. Additionally, dsmadmc requires user
and password to admin account in TSM and library name to certain commands. Job will read these
configuration properties from TDR configuration from properties named tsm.user, tsm.password and
tsm.library.name respectively.

Type
TSM_ARCHIVE_COMPLEX

242
 Tibigen Digital Repository - REST API

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

itemUuid uuid An UUID of item which has attached files to archive.

Required.

lockWaitingTimeo integer A number of minutes to wait for possibility to read file

utInMinutes instances scheduled to archive. Default value is 1440 which
is 24 hours.

Outputs
Job does not produce output.

7.6.25. TSM Delete Job

TSM Delete Job deletes files archived on tapes from TSM database.

Type
TSM_DELETE

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

uuidId integer If specified, all assets and files attached to item with given
UUID will be deleted from TSM.

assetId integer An id of asset which files should be deleted from TSM.

243
 Tibigen Digital Repository - REST API

Outputs
Job does not produce output.

7.6.26. TSM Insert Tapes Job

TSM Insert Tapes Job performs insert tapes process which consists of two steps: checkin and optional
labeling.

In order to properly manage tapes, TDR requires all operations of inserting tapes to be executed
through this job. The job launches in TSM checkin process which moves tapes inserted to I/O slot to
library internal slots. If tapes are inserted for the first time, job will launch additional label process.

Type
TSM_INSERT_TAPES

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

Outputs
Job does not produce output.

7.6.27. TSM Remove Tapes Job

TSM Remove Tapes Job instructs Tivoli Storage Manager to remove tapes from tape library. Input
storagePoolId specifies tape storage pool with all tapes to remove.

Type
TSM_REMOVE_TAPES

Imports

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

244
 Tibigen Digital Repository - REST API

Name Type Description

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

storagePoolId integer An id of storage pool from which all tapes should be ejected
from library. Required.

location string A name of the location in which ejected tapes will be stored.
This information is only for user purposes. Required.

Outputs
Job does not produce output.

7.6.28. TSM Retrieve Job

TSM Retrieve Job retrieves files archived on tapes and saves them on local storage.

Type
TSM_RETRIEVE

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

itemUuid uuid An UUID of item which files should be retrieved from tapes.

assetId integer An id of asset which files should be retrieved from tapes.

fileId integer An id of file which should be retrieved from tapes. Can be

specified multiple times.

One of these inputs have to be specified: itemUuid, assetId or fileId.

Outputs
Job does not produce output.

245
 Tibigen Digital Repository - REST API

7.6.29. TSM Synchronize Job

TSM Synchronize Job synchronizes information about volums and storage pools from Tivoli Storage
Manager to TDR.

Type
TSM_SYNCHRONIZE

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

Outputs
Job does not produce output.

7.6.30. Unzip Job

Unzip Job unpacks ZIP package to specified directory.

Type
UNZIP

Inputs

Name Type Descriptor

inputFile string A path to ZIP package. Required.

outputDirectory string A path to output directory where files from ZIP package will
be saved. Required.

createOutputDirect boolean If true and output directory does not exist, job will create
ory entire directory structure as needed. Default value is false.

Outputs

246
 Tibigen Digital Repository - REST API

Name Type Description

outputFile string An absolute path to file extracted from ZIP package. This
output is repeated for each file in ZIP package.

7.6.31. Validate Job

Validate Job checks health of files tracked by TDR. It can detect that one of the file instances does not
exist, has invalid size or check sum. Job produces output with all error found during validation.

Type
VALIDATE

Inputs

Name Type Description

tdrApiUrl string An url to TDR REST API. For example

http://localhost:8080/tdr-api. Required.

tdrApiLogin string A login of the user on whose behalf the job will be executed.
Required.

tdrApiPassword string A password of the user on whose behalf the job will be
executed. Required.

instancesCount integer A number of file instances to check beginning from

instances with oldest date of checking. Required.

Outputs

Name Type Description

Error string An error found by validation process. Can occur multiple

times. Possible errors are:
- File <FILE_ID> has not calculated size in file system.
- File <FILE_ID> has not calculated md5 sum.
- File <FILE_INSTANCE_PATH> does not exist on storage.
- File <FILE_INSTANCE_PATH> has different size than it has
in file system.
- File <FILE_INSTANCE_PATH> has different md5sum than it
has in file system.

7.6.32. Zip Job

Zip Job pack files and directories specified as inputFile inputs. If ZIP package already exists, job will
add new files to it and will replace existing.

247
 Tibigen Digital Repository - REST API

Type
ZIP

Inputs

Name Type Description

inputFile string A path to file or directory which will be packed to ZIP

package. Can be specified multiple times for different paths.
Required.

outputFile string A path to output ZIP package. Required.

Outputs
Job does not produce output.

7.7. Workers
The main purpose of creating Job Daemon - workers architecture was to distribute load generated by
heavy tasks across multiple machines.

Workers in TDR are responsible for executing jobs. Before worker can do that, it needs to register to
Job Daemon which is manager software for all workers operating in the system. After successful
register, Job Daemon tracks workers and dispatches jobs to them. The communication between Job
Daemon and worker in both directions leverages REST API, so both Job Daemon and worker are HTTP
servers and clients.

This chapter and its subsections describes REST API on Job Daemon side. To learn more about worker’s
REST API, you should see Worker REST API chapter.

While registering, worker sends to Job Daemon list of all job types that it can handle. That list is known
as capabilities list. Job Daemon saves that information and uses it for proper dispatching of jobs.

When at least one worker is registered in Job Daemon, Job Daemon can start sending jobs to workers,
of course if workers capable to that jobs exist. To select the most suitable worker for the job, Job
Daemon uses worker election algorithm for that purpose, which performs following steps:

1. Job Daemon’s dispatcher selects workers having required capability to do awaiting job.

2. Dispatcher reads the routes (Routes). If non of them exist, dispatcher will skip this step. Otherwise,
dispatcher tries to match routes to the job. When some of the routes match, only the workers being
target of these routes participate in further election.

3. Dispatcher removes all workers matching following criteria: worker’s thread-pool is full, worker is
unstaged, worker has status NOT_RESPONDING.

4. Dispatcher sorts workers by host load - better worker has lower host load.

248
 Tibigen Digital Repository - REST API

5. Dispatcher tries to send job to worker being first on the list. If connection cannot be established or
worker returned error, dispatcher gets next worker on the list and tries to send job to them.

After the worker receives the job, it uses idle thread from thread pool to execute the job. During
execute, job provides percentage progress. This progress is checked periodically by Job Daemon along
with worker state. When the job execution ends, whether with success or failure, worker informs Job
Daemon about that event, sending it status and outputs produced by the job.

TDR provides default implementation of worker, that is capable of doing job types needed for proper
operation of the system. Integrators can build theirs own custom workers as long as they conform to
REST API described in this chapter and in Worker REST API.

7.7.1. Worker
Example of representation

<worker id="1">
    <capabilities>
        <capability>SCHEDULE_RECORDING</capability>
        <capability>LOAD_SUBTITLES</capability>
    </capabilities>
    <cores>2</cores>
    <host>localhost</host>
    <host-load>0.14</host-load>
    <last-updated>2015-12-23 14:43:52</last-updated>
    <name>custom-worker</name>
    <not-responding-times>0</not-responding-times>
    <os>Linux</os>
    <port>9012</port>
    <registered>2015-12-18 09:18:01</registered>
    <running-threads>0</running-threads>
    <status>OK</status>
    <thread-pool>10</thread-pool>
    <unstaged>false</unstaged>
    <version>3.0</version>
</worker>

Table 63. Worker properties

Name Type Description

id integer An id of worker given in registration process.

249
 Tibigen Digital Repository - REST API

Name Type Description

capabilities Capability List A list of job types that this worker can handle. Required at
least one capability.

cores integer A number of CPU cores available on host where worker is

installed. Required.

host string A hostname or ip addres of host where worker is installed.

Required.

host-load float A load on host where worker is installed. For Windows

machines this is always 0.

last-updated datetime A time when Job Daemon for the last time successfully asked
for worker state.

name string A user-defined name of the worker.

not-responding- integer A number of failed communication attempts with worker.

times When Job Daemon eventually reconnects, this counter will
be reset to 0.

os string A name of the operation system where worker is installed.

port string A number of port on which worker is listening. Required.

registered datetime A time when worker registered itself in Job Daemon.

running-threads integer A number of threads that are currently working on jobs.

This number is equal to number of currently executed jobs.

status string A worker status. Possible values are:

- OK - worker is operational and Job Daemon successfully
communicates with it,
- NOT_RESPONDING - status is set when Job Daemon failed
to communicate with worker. The next communication
attempts increments not-responding-times counter. When
this counter goes to maximum configured marker, the
worker will be automatically unregistered from Job
Daemon. Required.

thread-pool integer A number of possible threads able to execute jobs. If

running-threads and thread-pool will be equal, worker is
full and cannot accept new jobs for execution. Required.

250
 Tibigen Digital Repository - REST API

Name Type Description

unstaged boolean If true, Job Daemon will not dispatch new jobs to this
worker, but jobs which are already running on this worker,
will be properly tracked until finished. Otherwise, worker
behave normally accepting new jobs dispatched by Job
Daemon.

The unstaged mode is useful when you want to stop worker

but you don’t want to lose current job progress. Setting this
property to true, will let worker gracefully end all its jobs
and when the running-threads will reach 0, you can safely
shutdown worker.
Required.

version string A version of worker executable. Required.

7.7.2. Worker List

A worker list object is a container of Worker objects.

251
 Tibigen Digital Repository - REST API

Example of representation

<workers>
    <worker id="1">
        <capabilities>
            <capability>SCHEDULE_RECORDING</capability>
            <capability>LOAD_SUBTITLES</capability>
        </capabilities>
        <cores>2</cores>
        <host>localhost</host>
        <host-load>0.14</host-load>
        <last-updated>2015-12-23 14:43:52</last-updated>
        <name>custom-worker</name>
        <not-responding-times>0</not-responding-times>
        <os>Linux</os>
        <port>9012</port>
        <registered>2015-12-18 09:18:01</registered>
        <running-threads>0</running-threads>
        <status>OK</status>
        <thread-pool>10</thread-pool>
        <unstaged>false</unstaged>
        <version>3.0</version>
    </worker>
</workers>

7.7.3. Capability List

Capability list contains job types that Job Daemon or specific worker can handle.

Example of representation

<capabilities>
    <capability>DELETE_ITEM</capability>
    <capability>EXPORT</capability>
    <capability>IMPORT</capability>
</capabilities>

7.7.4. List workers

List workers registered in Job Daemon.

252
 Tibigen Digital Repository - REST API

Request

GET /workers

Authorization
This request requires authorization with permission view.worker.

Response
If successful, the response status code is 200 OK and body contains Worker List object wrapped in
Response object.

7.7.5. List capabilities of all workers

List capabilities known to Job Daemon. The capability set is a sum of capabilities of individual
workeres.

Request

GET /workers/capabilities

Authorization
This request requires authorization with permission view.worker.

Response
If successful, the response status code is 200 OK and body contains Capability List object wrapped in
Response object.

7.7.6. Register worker

Register worker in Job Daemon. Job Daemon periodically check health of the worker by getting its
state. Only registered workers can receive jobs to execute.

Request

POST /workers

In the request body, supply a Worker object with at least required properties.

253
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission manage.worker.

Response
If successful, the response status code is 200 OK and body contains Value object with id of registered
worker, wrapped in Response object.

Errors

Error code Status Description

code

JobDaemonException 400 Some of the worker properties are invalid.

JobDaemonException 409 Worker with the same host and port is already registered.

7.7.7. Unregister worker

Unregister worker from Job Daemon. Every job which is in the RUNNING state at the moment of
unregistering will be restarted (it’s status will be changed to WAITING, so other worker can handle
that job).

Request

DELETE /workers/{id}

Path parameters

Name Type Description

id integer An identifier of worker to unregister.

Authorization
This request requires authorization with permission manage.worker.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

254
 Tibigen Digital Repository - REST API

Error code Status Description

code

JobDaemonException 404 Cannot find worker with given id.

7.8. Routes
Routes allow user to specify which jobs should be executed by which workers. A route object contains
properties used for matching jobs (condition-on, expected-name, expected-value) and properties
designating target worker (worker-host, worker-port). Matching is done for every new job added after
the route was applied. If job is matched, Job Daemon automatically dispatches it to target worker.
When multiple routes matches single job, a worker election algorithm takes over control.

Routes can be added at runtime and will be used to routing immediately after addition.

7.8.1. Route
Example of representation

<route id="1"
       condition-on="INPUT"
       expected-name="sourceStorageId"
       expected-value="1"
       worker-host="localhost"
       worker-port="9013"
       created="2015-07-23 08:52:41"
       creator="admin" />

Table 64. Route properties

Name Type Description

id integer An identifier of this route.

condition-on string Indicates job’s property on which condition will be checked.

Currently supported values:
- INPUT - condition will be checked on job input.
Required.

expected-name string A name of expected job input. Required.

expected-value string A value of expected job input. Required.

worker-host string The host of worker to which matched jobs will be routed.
Required.

worker-port integer The port of worker to which matched jobs will be routed.
Required.

255
 Tibigen Digital Repository - REST API

Name Type Description

created datetime The time when route was created.

creator string A login of the user who created this route.

7.8.2. Route List

A route list object is a collection of Route objects.

Example of representation

<routes>
    <route id="1"
           condition-on="INPUT"
           expected-name="sourceStorageId"
           expected-value="1"
           worker-host="localhost"
           worker-port="9013"
           created="2015-07-23 08:52:41"
           creator="admin" />
</routes>

7.8.3. List routes

List all routes added to Job Daemon.

Request

GET /routes

Authorization
This request requires authorization with permission view.route.

Response
If successful, the response status code is 200 OK and body contains Route List object wrapped in
Response object.

7.8.4. Get route

Get route.

256
 Tibigen Digital Repository - REST API

Request

GET /routes/{id}

Path parameters

Name Type Description

id integer An identifier of route to get.

Authorization
This request requires authorization with permission view.route.

Response
If successful, the response status code is 200 OK and body contains Route object wrapped in Response
object.

Errors

Error code Status Description

code

JobDaemonException 404 Cannot find route with given id.

7.8.5. Add route

Add route and immediatelly start using this route for job dispatching.

Request

POST /routes

In the request body, supply a Route object with at least required properties.

Authorization
This request requires authorization with permission manage.route.

Response
If successful, the response status code is 200 OK and body contains Value object with id of newly
created route, wrapped in Response object.

257
 Tibigen Digital Repository - REST API

Errors

Error code Status Description

code

JobDaemonException 400 Some of the route properties are invalid.

7.8.6. Update route

Update route and immediately start using changed properties for job dispatching.

Request

PUT /routes/{id}

Path parameters

Name Type Description

id integer An identifier of route to update.

In the request body, supply a Route object with updated properties.

Authorization
This request requires authorization with permission manage.route.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

JobDaemonException 400 Some of the route properties are invalid.

7.8.7. Delete route

Delete route and stop using it for job dispatching.

Request

DELETE /routes/{id}

258
 Tibigen Digital Repository - REST API

Path parameters

Name Type Description

id integer An identifier of route to delete.

Authorization
This request requires authorization with permission manage.route.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

JobDaemonException 404 Cannot find route with given id.

7.9. Worker REST API

This chapter describes web-service contract API that each TDR worker have to implement. This API
leverages REST architecture and has to be available at /worker root URL. For example, to retrieve
worker state, Job Daemon will send GET request to address:
<worker-host>:<worker-port>/worker/state.

The API is composed of two domains: jobs and worker state. Jobs domain allows to add and manage
jobs in worker. Worker state domain, on the other hand, provides web-services to retrieve worker’s
state and shutdown worker.

Worker API operates on the same objects as TDR API e.g. Job, Job List, Job Asset, Job Asset List and
Worker. For now, API cannot be secured with authentication method.

7.9.1. List Jobs

Get list of all jobs being executed by worker.

Request

GET /jobs

Response
If successful, the response status code is 200 OK and body contains Job List object.

259
 Tibigen Digital Repository - REST API

7.9.2. Get Job

Get job.

Request

GET /jobs/{id}

Path parameters

Name Type Description

id integer An id of the job to get.

Response
If successful, the response status code is 200 OK and body contains Job object.

Errors

Status code Description

404 Cannot find job with given id.

500 Other internal error.

7.9.3. Get Job Input

Get job input.

Request

GET /jobs/{id}/input

Path parameters

Name Type Description

id integer An id of the job, which input should be returned.

Response
If successful, the response status code is 200 OK and body contains Job Asset List object.

260
 Tibigen Digital Repository - REST API

Errors

Status code Description

404 Cannot find job with given id.

500 Other internal error.

7.9.4. Start Job

Start job. Worker uses one of its threads from the thread pool to execute job. Job is executed
immediately and web-service returns.

Request

POST /jobs

In the request body, Job Daemon will supply a Job object with following properties: id, type, input.

Response
If successful, the response status code is 204 No Content and body is empty.

Errors

Status code Description

400 Worker is not capable to do this type of jobs or job with this id is already being
executed.

429 Maximum number of jobs exceeded. Worker cannot execute another job.

500 Other internal error.

7.9.5. Change Job Status

Change status of the job - pause or resume job.

Request

PUT /jobs/{id}

Path parameters

261
 Tibigen Digital Repository - REST API

Name Type Description

id integer An id of the job which status will be changed.

In the request body, Job Daemon will supply a Job object with status property.

Response
If successful, the response status code is 204 No Content and body is empty.

Errors

Status code Description

400 Status cannot be changed to given status.

404 Cannot find job with given id.

500 Other internal error.

7.9.6. Stop Job

Stop job being executed by worker.

Request

DELETE /jobs/{id}

Path parameters

Name Type Description

id integer An id of the job to stop.

Response
If successful, the response status code is 204 No Content and body is empty.

Errors

Status code Description

404 Cannot find job with given id.

500 Other internal error.

262
 Tibigen Digital Repository - REST API

7.9.7. Get Worker State

Get worker state.

Request

GET /state

Response
If successful, the response status code is 200 OK and body contains Worker object.

7.9.8. Shutdown Worker

Stop all jobs being executed and shutdown worker process.

Request

POST /shutdown

Response
If successful, the response status code is 204 No Content and body is empty.

8. Transcoding
Transcoding is a process that allows to change one file format to another. A typical use case of
transcoding is to generate low resolution video or key frames from the video in high quality.

Transcoding is implemented as a process that can be executed by each user. More information about
transcoding process in section Transcode Job.

To execute transcoding process, system requires external transcoding software. TDR integrates with
three available transcoders:

• ProMedia Carbon - for transcoding audio/video files.

• FFmpeg - for transcoding audio/video files.

• ImageMagick - from converting image files.

Transcoding configuration requires two elements:

• Transcoding profile - contains a set of transcoding parameters such as format and file name, or
fps and codec for video. For each supported transcoder is a separate type of profile. You can find
more information about profiles in sections ProMedia Carbon Profiles, FFmpeg Profiles,

263
 Tibigen Digital Repository - REST API

ImageMagick Profiles.

• Transcoding specification - contains rules allowing automatically select inputs, defines output,
transcoder and profile for transcoding process. More information in section Transcoding
Specifications.

8.1. FFmpeg Profiles

Profiles for FFmpeg transcoder.

8.1.1. FFmpeg Profile

Example of simple representation

<ffmpeg-profile id="1" name="Generowanie klatek kluczowych - FFmpeg"/>

264
 Tibigen Digital Repository - REST API

Example of detailed representation

<ffmpeg-profile id="1" name="Generowanie klatek kluczowych - FFmpeg">

    <video>
        <codec>libx264</codec>
        <bitrate>1500000</bitrate>
        <width>460</width>
        <height>320</height>
        <gop>1</gop>
        <fps>25</fps>
        <color-space>yuv420p</color-space>
    </video>
    <audio>
        <codec>libvo_aacenc</codec>
        <bitrate>196608</bitrate>
        <channels>2</channels>
    </audio>
    <image>
        <count>10</count>
        <interval>30</interval>
        <skip-first-frame>false</skip-first-frame>
        <width>460</width>
        <height>320</height>
    </image>
    <filter>
        <overlay>
            <x>10</x>
            <y>10</y>
        </overlay>
        <deinterlacing>false</deinterlacing>
    </filter>
    <format>jpg</format>
    <override-output>false</override-output>
    <output-name>frame</output-name>
    <start-timecode>00:00:00:00</start-timecode>
    <stop-timecode>00:11:11:11</stop-timecode>
</ffmpeg-profile>

Table 65. FFmpeg profile properties

265
 Tibigen Digital Repository - REST API

Name Type Description

id integer The identifier of this FFmpeg profile.

name string The name of this FFmpeg profile. Required.

video FFmpeg Video Video parameters.

audio FFmpeg Audio Audio parameters.

image FFmpeg Image Image parameters.

filter FFmpeg Filter Filter parameters.

format string File format of output file generated by FFmpeg. With '*' will
take source file format.. *Required*.

override-output string If true, system will override file with the same name as
output file in output location. Default value is false.

output-name string Name of output file generated by transcoding process.

Required

start-timecode timecode Start of target video represented as timecode from source

video. Format of timecode is hh:mm:ss:ff.

stop-timecode timecode Stop of target video represented as timecode from source

video. Format of timecode is hh:mm:ss:ff.

8.1.2. FFmpeg Profile List

A FFmpeg profile list is a container of FFmpeg profile objects.

Example of representation

<ffmpeg-profiles>
    <ffmpeg-profile id="1" name="Generowanie klatek kluczowych - FFmpeg"/>
</ffmpeg-profiles>

8.1.3. FFmpeg Video

FFmpeg video object contains parameters for target video.

266
 Tibigen Digital Repository - REST API

Example of representation

<video>
    <codec>libx264</codec>
    <bitrate>1500000</bitrate>
    <width>460</width>
    <height>320</height>
    <gop>1</gop>
    <fps>25</fps>
    <color-space>yuv420p</color-space>
</video>

Table 66. FFmpeg video properties

Name Type Description

codec string Codec of target video.

bitrate integer Bitrate of target video.

width integer Width (in pixels) of target video.

height integer Height (in pixels) of target video.

gop integer GOP of target video.

fps integer FPS of target video.

color space string Color space (FFmpeg pixel format) of target video.

8.1.4. FFmpeg Audio

FFmpeg audio object contains parameters for target audio.

Example of representation

<audio>
    <codec>libvo_aacenc</codec>
    <bitrate>196608</bitrate>
    <channels>2</channels>
</audio>

Table 67. FFmpeg audio properties

Name Type Description

codec string Codec of target audio.

267
 Tibigen Digital Repository - REST API

Name Type Description

bitrate integer Bitrate of target audio.

channels integer Number of channels in target audio.

8.1.5. FFmpeg Image

FFmpeg image object contains parameters for target image.

Example of representation

<image>
    <count>10</count>
    <interval>30</interval>
    <skip-first-frame>false</skip-first-frame>
    <width>460</width>
    <height>320</height>
</image>

Table 68. FFmpeg image properties

Name Type Description

count integer Number of key frames that will be generated from the video.

interval integer Time interval (in seconds) between generated key frames. If
count parameter is specified, then this option is not used by
transcoding process.

skip-first-frame boolean If true, system will skip the first key frame of the generated
key frames. This option does not affect the overall number
of key frames. If a defined number of frames is 10, then after
selecting this option it still will be 10 frames. The system in
this case will generate 11 key frames and skips first frame.
This option is particularly useful in cases, when video begins
with a fade-in.

width integer Width (in pixels) of generated key frames.

height integer Height (in pixels) of generated key frames.

8.1.6. FFmpeg Filter

FFmpeg filter object contains configuration parameters for overlay and deinterlacing filters.

268
 Tibigen Digital Repository - REST API

Example of representation

<filter>
    <overlay>
        <x>10</x>
        <y>10</y>
    </overlay>
    <deinterlacing>false</deinterlacing>
</filter>

Table 69. FFmpeg image properties

Name Type Description

overlay x integer Distance (in pixels) from left side of video where logo will be
placed.

overlay y integer Distance (in pixels) from top side of video where logo will be
placed.

deinterlacing boolean If true, ffmpeg will be executed with yadif=0:-1:0 filter.

8.1.7. List FFmpeg profiles

Get list of representations of FFmpeg profiles.

Request

GET /profiles/ffmpeg?page={page}&size={size}

Query parameters

Name Type Description

page integer The number of page of results to return. If not specified, web-service
returns all FFmpeg profiles.

size integer The size of the page of results. Default value is 10.

Authorization
This request requires authorization with permission view.transcoding.

Response
If successful, the response status code is 200 OK and body contains FFmpeg Profile List object wrapped

269
 Tibigen Digital Repository - REST API

in Response object.

8.1.8. Get FFmpeg profile

Get FFmpeg profile.

Request

GET /profiles/ffmpeg/{id}

Path parameters

Name Type Description

id integer A unique identifier of FFmpeg profile.

Authorization
This request requires authorization with permission view.transcoding.

Response
If successful, the response status code is 200 OK and body contains FFmpeg Profile object wrapped in
Response object.

Errors

Error code Status Description

code

TranscodingProfileNotFound 404 Cannot find FFmpeg profile with given id.

Exception

8.1.9. Add FFmpeg profile

Add new FFmpeg profile.

Request

POST /profiles/ffmpeg

In the request body, supply a FFmpeg Profile object with at least required properties.

270
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission manage.transcoding.

Response
If successful, the response status code is 200 OK and body contains Value object with ID on newly
added FFmpeg profile wrapped in Response object.

Errors

Error code Status Description

code

InvalidTranscodingProfilePro 400 Format or output name is not specified or is empty.

pertyException

8.1.10. Update FFmpeg profile

Update FFmpeg profile.

Request

PUT /profiles/ffmpeg/{id}

Path parameters

Name Type Description

id integer A unique identifier of FFmpeg profile.

In the request body, supply a FFmpeg Profile object with updated properties.

Authorization
This request requires authorization with permission manage.transcoding.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

271
 Tibigen Digital Repository - REST API

Error code Status Description

code

InvalidTranscodingProfilePro 400 Format or output name is not specified or is empty.

pertyException

TranscodingProfileNotFound 404 Cannot find FFmpeg profile with given id.

Exception

8.1.11. Delete FFmpeg profile

Delete FFmpeg profile.

Request

DELETE /profiles/ffmpeg/{id}

Path parameters

Name Type Description

id integer A unique identifier of FFmpeg profile.

Authorization
This request requires authorization with permission manage.transcoding.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

TranscodingProfileNotFound 404 Cannot find FFmpeg profile with given id.

Exception

8.2. ProMedia Carbon Profiles

Profiles for ProMedia Carbon transcoder.

8.2.1. ProMedia Carbon Profile

272
 Tibigen Digital Repository - REST API

Example of representation

<carbon-profile format="jpg"
                guid="9E0F23AB-F324-4473-848D-70D8596C5E3D"
                id="2"
                image-count="20"
                name="Generowanie klatek kluczowych"
                output-name="%s"
                override-output="false"
                skip-first-frame="true"
                timing-mode="0"
                video-fps="25"
                interval="5"
                image-height="320"
                image-width="460">
<filter>9E0F23AB-F324-4473-848D-70D8596C5E3D</filter>
<start-timecode>00:00:00:00</start-timecode>
<stop-timecode>00:11:11:11</stop-timecode>
<video-width>460</video-width>
<video-height>320</video-height>
</carbon-profile>

Table 70. ProMedia Carbon profile properties

Name Type Description

id integer The identifier of this ProMedia Carbon profile.

name string The name of this ProMedia Carbon profile. Required.

guid string A unique identifier of ProMedia Carbon preset. Preset

contains parameters for transcoding and it is stored in a file
on ProMedia Carbon server. Required.

format string File format of output file generated by ProMedia Carbon.

Required.

image-count integer Number of key frames that will be generated from the video.
If interval parameter is specified, then this option is not
used by transcoding process.

output-name string This parameter is used by system to generate output file

name. It can include any text and symbol %s, which will be
replaced by source file name, i.e. %s_preview. Required.

273
 Tibigen Digital Repository - REST API

Name Type Description

override-output boolean If true, system will override file with the same name as
output file in output location. Default value is false.

skip-first-frame boolean If true, system will skip the first key frame of the generated
key frames. This option does not affect the overall number
of key frames. If a defined number of frames is 10, then after
selecting this option it still will be 10 frames. The system in
this case will generate 11 key frames and skips first frame.
This option is particularly useful in cases, when video begins
with a fade-in.

timing-mode integer ProMedia Carbon timing mode.

video-fps integer FPS of target video.

interval integer Time interval (in seconds) between generated key frames.

image-height integer Height (in pixels) of generated key frames.

image-width integer Width (in pixels) of generated key frames.

filter string A unique identifier of ProMedia Carbon filter.

start-timecode timecode Start of target video represented as timecode from source

video. Format of timecode is hh:mm:ss:ff.

stop-timecode timecode Stop of target video represented as timecode from source

video. Format of timecode is hh:mm:ss:ff.

video-width integer Width (in pixels) of generated video.

video-height integer Height (in pixels) of generated video.

8.2.2. ProMedia Carbon Profile List

A ProMedia Carbon profile list is a container of ProMedia Carbon profile objects.

274
 Tibigen Digital Repository - REST API

Example of representation

<carbon-profile-list>
<carbon-profile format="jpg"
                    guid="9E0F23AB-F324-4473-848D-70D8596C5E3D"
                    id="2"
                    image-count="20"
                    name="Generowanie klatek kluczowych"
                    output-name="%s"
                    override-output="false"
                    skip-first-frame="true"
                    timing-mode="0"
                    video-fps="25"
                    interval="5"
                    image-height="320"
                    image-width="460">
<filter>9E0F23AB-F324-4473-848D-70D8596C5E3D</filter>
<start-timecode>00:00:00:00</start-timecode>
<stop-timecode>00:11:11:11</stop-timecode>
<video-width>460</video-width>
<video-height>320</video-height>
</carbon-profile>
</carbon-profile-list>

8.2.3. List ProMedia Carbon profiles

Get list of representations of ProMedia Carbon profiles.

Request

GET /profiles/carbon?page={page}&size={size}

Query parameters

Name Type Description

page integer The number of page of results to return. If not specified, web-service
returns all ProMedia Carbon profiles.

size integer The size of the page of results. Default value is 10.

275
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission view.transcoding.

Response
If successful, the response status code is 200 OK and body contains ProMedia Carbon Profile List object
wrapped in Response object.

8.2.4. Get ProMedia Carbon profile

Get ProMedia Carbon profile.

Request

GET /profiles/carbon/{id}

Path parameters

Name Type Description

id integer A unique identifier of ProMedia Carbon profile.

Authorization
This request requires authorization with permission view.transcoding.

Response
If successful, the response status code is 200 OK and body contains ProMedia Carbon Profile object
wrapped in Response object.

Errors

Error code Status Description

code

TranscodingProfileNotFound 404 Cannot find ProMedia Carbon profile with given id.
Exception

8.2.5. Add ProMedia Carbon profile

Add new ProMedia Carbon profile.

Request

276
 Tibigen Digital Repository - REST API

POST /profiles/carbon

In the request body, supply a ProMedia Carbon Profile object with at least required properties.

Authorization
This request requires authorization with permission manage.transcoding.

Response
If successful, the response status code is 200 OK and body contains Value object with ID on newly
added ProMedia Carbon profile wrapped in Response object.

Errors

Error code Status Description

code

InvalidTranscodingProfilePro 400 Guid, format or output name is not specified or is empty.

pertyException

8.2.6. Update ProMedia Carbon profile

Update ProMedia Carbon profile.

Request

PUT /profiles/carbon/{id}

Path parameters

Name Type Description

id integer A unique identifier of ProMedia Carbon profile.

In the request body, supply a ProMedia Carbon Profile object with updated properties.

Authorization
This request requires authorization with permission manage.transcoding.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

277
 Tibigen Digital Repository - REST API

Errors

Error code Status Description

code

InvalidTranscodingProfilePro 400 Guid, format or output name is not specified or is empty.

pertyException

TranscodingProfileNotFound 404 Cannot find ProMedia Carbon profile with given id.
Exception

8.2.7. Delete ProMedia Carbon profile

Delete ProMedia Carbon profile.

Request

DELETE /profiles/carbon/{id}

Path parameters

Name Type Description

id integer A unique identifier of ProMedia Carbon profile.

Authorization
This request requires authorization with permission manage.transcoding.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

TranscodingProfileNotFound 404 Cannot find ProMedia Carbon profile with given id.
Exception

8.3. ImageMagick Profiles

Profiles for ImageMagick converter.

278
 Tibigen Digital Repository - REST API

8.3.1. ImageMagick Profile

Example of simple representation

<image-magick-profile id="1" name="Image Preview Quality"/>

Example of detailed representation

<image-magick-profile id="1"
                      name="Image Preview Quality"
                      output-format="jpg"
                      output-name-template="%s"
                      quality="90"
                      resize-width="460"
                      resize-height="320"
                      logo-path="/etc/tdr/logo.png"
                      logo-x="10"
                      logo-y="10"
                      dpi="10x10"
                      gravity="NORTH_WEST"
                      preserve-print-size="false"/>

Table 71. ImageMagick Profile properties

Name Type Description

id integer The identifier of this ImageMagick profile.

name string The name of this ImageMagick profile. Required.

output-format string File format of output file generated by ImageMagick.

Required.

output-name- string This parameter is used by system to generate output file

template name. It can include any text and symbol %s, which will be
replaced by source file name, i.e. %s_preview. Required

quality integer Compression level for formats: JPEG,MIFF,PNG. Quality can

be any number from 1 to 100. If number is higher then
compression level is lower.

resize-width integer Width (in pixels) of generated image.

resize-height integer Height (in pixels) of generated image.

logo-path string Local path on TDR server to logo file.

279
 Tibigen Digital Repository - REST API

Name Type Description

logo-x integer Distance (in pixels) from left side of image where logo will
be placed.

logo-y integer Distance (in pixels) from top side of image where logo will
be placed.

dpi string DPI of output image.

gravity string Defines image corner or border from which distance

specified by logo-x and logo-y will be calculated. Possible
values are: NORTH_WEST, NORTH, NORTH_EAST, WEST,
CENTER, EAST, SOUTH_WEST, SOUTH, SOUTH_EAST.

preserve-print-size boolean If true, system will calculate image width and height
depending on DPI change to preserve print size. Property
'resize-width' and 'resize-height' can not be set.

8.3.2. ImageMagick Profile List

An ImageMagick profile list is a container of ImageMagick Profile objects.

Example of representation

<image-magick-profiles>
<image-magick-profile id="1" name="Image Preview Quality"/>
</image-magick-profiles>

8.3.3. List ImageMagick profiles

Get list of simple representations of ImageMagick profiles.

Request

GET /profiles/imagemagick?page={page}&size={size}

Query parameters

Name Type Description

page integer The number of page of results to return. If not specified, web-service
returns all ImageMagick profiles.

size integer The size of the page of results. Default value is 10.

280
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission view.transcoding.

Response
If successful, the response status code is 200 OK and body contains ImageMagick Profile List object
wrapped in Response object.

8.3.4. Get ImageMagick profile

Get ImageMagick profile.

Request

GET /profiles/imagemagick/{id}

Path parameters

Name Type Description

id integer A unique identifier of ImageMagick profile to get.

Authorization
This request requires authorization with permission view.transcoding.

Response
If successful, the response status code is 200 OK and body contains ImageMagick Profile object
wrapped in Response object.

Errors

Error code Status Description

code

TranscodingProfileNotFound 404 Cannot find ImageMagick profile with given id.

Exception

8.3.5. Add ImageMagick profile

Add new ImageMagick profile.

Request

281
 Tibigen Digital Repository - REST API

POST /profiles/imagemagick

In the request body, supply a ImageMagick Profile object with at least required properties.

Authorization
This request requires authorization with permission manage.transcoding.

Response
If successful, the response status code is 200 OK and body contains Value object with ID of newly added
ImageMagick profile wrapped in Response object.

Errors

Error code Status Description

code

InvalidTranscodingProfilePro 400 Quality is lower than 1 or higher than 100. Format is not
pertyException specified or is empty. Name is not specified or is empty.

8.3.6. Update ImageMagick profile

Update ImageMagick profile.

Request

PUT /profiles/imagemagick/{id}

Path parameters

Name Type Description

id integer A unique identifier of ImageMagick profile to update.

In the request body, supply a ImageMagick Profile object with updated properties.

Authorization
This request requires authorization with permission manage.transcoding.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

282
 Tibigen Digital Repository - REST API

Errors

Error code Status Description

code

InvalidTranscodingProfilePro 400 Quality is lower than 1 or higher than 100. Format is not
pertyException specified or is empty. Name is not specified or is empty.

TranscodingProfileNotFound 404 Cannot find ImageMagick profile with given id.

Exception

8.3.7. Delete ImageMagick profile

Delete ImageMagick profile.

Request

DELETE /profiles/imagemagick/{id}

Path parameters

Name Type Description

id integer A unique identifier of ImageMagick profile to delete.

Authorization
This request requires authorization with permission manage.transcoding.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

TranscodingProfileNotFound 404 Cannot find ImageMagick profile with given id.

Exception

8.4. Transcoding Specifications

Transcoding specification is a recipe for transcoding, which includes three configuration sections:

• source asset types,

• transcoder and profile used for transcoding,

283
 Tibigen Digital Repository - REST API

• target asset type.

8.4.1. Transcoding Specification

Example of representation

<transcoding-specification id="1" operation="CONVERT_VIDEO">

    <name>Key Frames Generation</name>
    <source>
        <video>
            <asset-type-id>1</asset-type-id>
        </video>
        <audio>
            <asset-type-id>2</asset-type-id>
        </audio>
        <image>
            <asset-type-id>3</asset-type-id>
        </image>
    </source>
    <profile transcoder="PROMEDIA_CARBON">
        <id>2</id>
    </profile>
    <target>
        <asset-type-id>4</asset-type-id>
    </target>
</transcoding-specification>

Table 72. Transcoding Specification properties

Name Type Description

id integer The unique identifier of this transcoding specification.

284
 Tibigen Digital Repository - REST API

Name Type Description

operation string Defines what operation will be performed during

transcoding. One of:
- CONVERT_VIDEO - converts input video into another video,
- CONVERT_AUDIO - converts input audio into another
audio,
- REPLACE_AUDIO_IN_VIDEO - replaces audio track in given
video with given audio,
- GENERATE_KEYFRAMES - generates set of images from
video,
- CONVERT_IMAGE - converts input image into another
image,
- COPY - copy input file into another file with copy codec.
Can be used to get part of media file without quality loss.
Avaliable only for FFmpeg transcoder.
Required.

name string The name of this transcoding specification.

source Transcoding Source asset types for transcoding process.

Specification
Source

profile Transcoding Transcoding profile configuration.

Specification
Profile

target Transcoding Target asset type for generated file.

Specification
Target

8.4.2. Transcoding Specification List

A transcoding specification list is a container of Transcoding Specification objects.

285
 Tibigen Digital Repository - REST API

Example of representation

<transcoding-specifications>
    <transcoding-specification id="1">
        <name>Key Frames Generation</name>
        <source>
            <video>
                <asset-type-id>1</asset-type-id>
            </video>
        </source>
        <profile transcoder="PROMEDIA_CARBON">
            <id>2</id>
        </profile>
        <target>
            <asset-type-id>2</asset-type-id>
        </target>
    </transcoding-specification>
</transcoding-specifications>

8.4.3. Transcoding Specification Source

Transcoding specification source object groups sources for all transcoder inputs. The inputs can be
video, audio or image inputs and are described by individual objects.

Example of representation

<source>
    <video>
        <asset-type-id>1</asset-type-id>
    </video>
    <audio>
        <asset-type-id>2</asset-type-id>
    </audio>
    <image>
        <asset-type-id>3</asset-type-id>
    </image>
</source>

Table 73. Transcoding Specification Source properties

286
 Tibigen Digital Repository - REST API

Name Type Description

video Transcoding Video source asset type for transcoding process.

Specification
Source Video

audio Transcoding Audio source asset type for transcoding process.

Specification
Source Audio

image Transcoding Image source asset type for transcoding process.

Specification
Source Image

8.4.4. Transcoding Specification Source Video

Transcoding specification source video object contains information needed to select file for video
transcoder input.

Example of representation

<video>
    <asset-type-id>1</asset-type-id>
</video>

Table 74. Transcoding Specification Source Video properties

Name Type Description

asset-type-id integer The unique identifier of asset type which will be used to find
source video file.

8.4.5. Transcoding Specification Source Audio

Transcoding specification source audio object contains information needed to select file for audio
transcoder input.

Example of representation

<audio>
    <asset-type-id>2</asset-type-id>
</audio>

Table 75. Transcoding Specification Source Audio properties

287
 Tibigen Digital Repository - REST API

Name Type Description

asset-type-id integer The unique identifier of asset type which will be used to find
source audio file.

8.4.6. Transcoding Specification Source Image

Transcoding specification source image object contains information needed to select file for image
transcoder input.

Example of representation

<image>
    <asset-type-id>3</asset-type-id>
</image>

Table 76. Transcoding Specification Source Image properties

Name Type Description

asset-type-id integer The unique identifier of asset type which will be used to find
source image file.

8.4.7. Transcoding Specification Profile

Transcoding specification profile object contains information which transcoder and which profile will
be used in transcoding process.

Example of representation

<profile transcoder="PROMEDIA_CARBON">
    <id>2</id>
</profile>

Table 77. Transcoding Specification Profile properties

Name Type Description

transcoder string Possible values are: - PROMEDIA_CARBON - the system will

use ProMedia Carbon transcoder for transcoding process.
- FFMPEG - the system will use FFmpeg transcoder for
transcoding process.
- IMAGE_MAGICK - the system will use ImageMagick
transcoder for transcoding process.

288
 Tibigen Digital Repository - REST API

Name Type Description

id string The unique identifier of transcoding profile. If transcoder is

PROMEDIA_CARBON, then it has to be id of ProMedia
Carbon profile. If transcoder is FFMPEG then it has to be id
of FFmpeg profile. If transcoder is IMAGE_MAGICK, then it
has to be id of ImageMagick profile.

8.4.8. Transcoding Specification Target

Transcoding specification target object defines id of asset type of output file/files generated by
transcoding process.

Example of representation

<target>
    <asset-type-id>4</asset-type-id>
</target>

Table 78. Transcoding Specification Target properties

Name Type Description

asset-type-id integer The unique identifier of asset type which will be associated
with generated file.

8.4.9. List transcoding specifications

Get list of representations of transcoding specifications.

Request

GET /transcoding/specifications?page={page}&size={size}

Query parameters

Name Type Description

page integer The number of page of results to return. If not specified, web-service
returns all transcoding specifications.

size integer The size of the page of results. Default value is 10.

Authorization
This request requires authorization with permission view.transcoding.

289
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains Transcoding Specification List
object wrapped in Response object.

8.4.10. Get transcoding specification

Get transcoding specification.

Request

GET /transcoding/specifications/{specification-id}

Path parameters

Name Type Description

specification-id integer A unique identifier of transcoding specification.

Authorization
This request requires authorization with permission view.transcoding.

Response
If successful, the response status code is 200 OK and body contains Transcoding Specification object
wrapped in Response object.

Errors

Error code Status Description

code

TranscodingSpecificationNot 400 Cannot find transcoding specification with given id.

FoundException

8.4.11. Add transcoding specification

Add new transcoding specification.

Request

POST /transcoding/specifications

In the request body, supply a Transcoding Specification object with at least required properties.

290
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission manage.transcoding.

Response
If successful, the response status code is 200 OK and body contains Value object with ID of newly added
transcoding specification wrapped in Response object.

Errors

Error code Status Description

code

InvalidTranscodingSpecificati 400 The target file type id is not specified or is empty.

onTargetAssetTypeException

8.4.12. Update transcoding specification

Update transcoding specification.

Request

PUT /transcoding/specifications/{specification-id}

Path parameters

Name Type Description

specification-id integer A unique identifier of transcoding specification.

In the request body, supply a Transcoding Specification object with updated properties.

Authorization
This request requires authorization with permission manage.transcoding.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

291
 Tibigen Digital Repository - REST API

Error code Status Description

code

InvalidTranscodingSpecificati 400 Target file type id is not specified or is empty.

onTargetAssetTypeException

TranscodingSpecificationNot 404 Cannot find transcoding specification with given id.

FoundException

8.4.13. Delete transcoding specification

Delete transcoding specification.

Request

DELETE /transcoding/specifications/{specification-id}

Path parameters

Name Type Description

specification-id integer A unique identifier of transcoding specification.

Authorization
This request requires authorization with permission manage.transcoding.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

TranscodingSpecificationNot 404 Cannot find transcoding specification with given id.

FoundException

9. Archiving
The system has a module for integration with TSM - Tivoli Storage Manager. This module allows to
archive and restore files from tape library. It also provides basic information about the volumes in
TSM.

292
 Tibigen Digital Repository - REST API

9.1. Archive Policies

Archive policies describe how archive process should operate on items in order to copy theirs files to
magnetic tapes. Archive policies allow to define options like:

• number of copies of files on tapes,

• destination storage pool in Tivoli Storage Manager,

• whether the selected item should be archived alone or with its descendants.

These options can be configured per item type. Thereby, for example item type Feature Film can have
different number of copies than item type Documentary.

Each item type can have multiple archive policies defined, but only one can be active.

9.1.1. Archive Policy

Example of simple representation

<archive-policy id="1" name="Film - 2 copies"/>

Example of detailed representation

<archive-policy id="1"
                name="Film - 2 copies"
                active="true"
                files-from-descendants="false"
                item-type-name="film"
                number-of-copies="2"
                storage-pool-name="FILMSTGP"/>

Table 79. Archive policy properties

Name Type Description

id integer The identifier of this archive policy.

name string The name of this archive policy. Required.

active boolean If true, archive process will be using this archive policy to
archive item. For each item type, only one archive policy can
be active at any given time. Default value is false.

files-from- boolean If true, system will archive files from given item, as well as
descendants files from descendant items. In this way, files from the entire
tree of items will be archived in the same storage pool.
Default value is false.

293
 Tibigen Digital Repository - REST API

Name Type Description

item-type-name string The item type for which the policy will be applied.
Required.

number-of-copies integer Number of archived copies of given files. As a result, the

system will create as many storage pools as it should be
copies. Each storage pool will include all files archived by
this policy. Required.

storage-pool-name string The name of storage pool for archived files. If the name is
empty, then system will generate it automatically, based on
the options selected in archive policy. However, if the name
is not empty, then system will create new pool by this name
or use an existing one. In the case of automatic name
generation, there are two options: - When files-from-
descendants option is true, then the name will consist of
prefix IC, then the 27 first characters ( without dashes ) of
the item UUID, and number of copy, i.e.
IC-F4844531BE3D4B6EB63E3FE21C1 - this is a second copy
for item with UUID which begins with
F4844531BE3D4B6EB63E3FE21C ( without dashes). Files will
be archived from given item and it’s descendant items. -
When files-from-descendants option is false, then the name
will consist of prefix I, then the 27 first characters ( without
dashes ) of the item UUID, and number of copy, i.e.
I-F4844531BE3D4B6EB63E3FE21C0 - this is a first copy for
item with UUID which begins with
F4844531BE3D4B6EB63E3FE21C ( without dashes). Files will
be archived only from given item.

9.1.2. Archive Policy List

A archive policy list is a container of Archive Policy objects.

Example of representation

<archive-policies>
    <archive-policy id="1" name="Film - 2 kopie"/>
</archive-policies>

9.1.3. List archive policies

Get list of representations of archive policies.

Request

294
 Tibigen Digital Repository - REST API

GET /tsm/policies?detailed={detailed}

Query parameters

Name Type Description

detailed boolean If true, returns detailed representation of each archive policy in a list.
Default value is false.

Authorization
This request requires authorization with permission view.tsm.

Response
If successful, the response status code is 200 OK and body contains Archive Policy List object wrapped
in Response object.

9.1.4. Get archive policy

Get archive policy.

Request

GET /tsm/policies/{policy-id}

Path parameters

Name Type Description

policy-id integer A unique identifier of archive policy.

Authorization
This request requires authorization with permission view.tsm.

Response
If successful, the response status code is 200 OK and body contains Archive Policy object wrapped in
Response object.

Errors

295
 Tibigen Digital Repository - REST API

Error code Status Description

code

ArchivePolicyNotFoundExcep 404 Cannot find archive policy with given id.

tion

9.1.5. Add archive policy

Add new archive policy.

Request

POST /tsm/policies

In the request body, supply an Archive Policy object with at least required properties.

Authorization
This request requires authorization with permission manage.tsm.

Response
If successful, the response status code is 200 OK and body contains Value object with ID of newly added
archive policy wrapped in Response object.

Errors

Error code Status Description

code

InvalidArchivePolicyItemTyp 400 Item type is not specified or is empty.

eException

MaxNumberOfCopiesExceede 400 Number of copies exceeded maximum.

dException

InvalidStoragePoolNameExce 400 Storage pool name is invalid.

ption

ItemTypeNotFoundException 404 Item type does not exist in the system.

ArchivePolicyAlreadyExistsE 409 There is another archive policy for the same item type.
xception

9.1.6. Update archive policy

Update archive policy.

296
 Tibigen Digital Repository - REST API

Request

PUT /tsm/policies/{policy-id}

Path parameters

Name Type Description

policy-id integer A unique identifier of archive policy.

In the request body, supply an Archive Policy object with updated properties.

Authorization
This request requires authorization with permission manage.tsm.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

MaxNumberOfCopiesExceede 400 Number of copies exceeded maximum.

dException

InvalidStoragePoolNameExce 400 Storage pool name is invalid.

ption

InvalidArchivePolicyItemTyp 400 Item type is not specified.

eException

ArchivePolicyNotFoundExcep 404 Cannot find archive policy with given id.

tion

ItemTypeNotFoundException 404 Given item type does not exist in TDR.

ArchivePolicyAlreadyExistsE 409 There is another archive policy with the same item type.
xception

9.1.7. Delete archive policy

Delete archive policy.

Request

297
 Tibigen Digital Repository - REST API

DELETE /tsm/policies/{policy-id}

Path parameters

Name Type Description

policy-id integer A unique identifier of archive policy.

Authorization
This request requires authorization with permission manage.tsm.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

ArchivePolicyNotFoundExcep 404 Cannot find archive policy with given id.

tion

9.2. TSM Volumes

Volumes from TSM. If TDR has active integration with TSM, then volumes should be synchronized
automatically by executing process TSM Synchronize Job.

9.2.1. TSM Volume

298
 Tibigen Digital Repository - REST API

Example of representation

<tsm-volumes association-status="SCRATCH"
             device-type="LTO"
             id="136"
             inserted="2015-01-01 00:01:19"
             library-name="MHVTL"
             location-inside-library="&quot;1,024&quot;"
             updated="2015-01-01 00:01:19"
             volume-name="I00001L1"
             library-status="MOUNTABLE_NOT_IN_LIB"
             location-outside-library="Room 01 Drawer 17"
             device-class-name="DISK"
             estimated-capacity="157286400"
             percentage-utilization="0.0"
             fill-status="ONLINE"
             storage-pool-id="3"/>

Table 80. TSM Volume properties

Name Type Description

id integer The identifier of this TSM volume in TDR database.

volume-name string Volume Name from volume TSM object. Required.

storage-pool-id integer Identifier of storage pool in TDR database, linked to this

volume.

inserted datetime The time when TSM volume was created in TDR.

updated datetime The time when TSM volume was updated in TDR.

library-name string Library Name from libvolume TSM object.

library-status string State from media TSM object.

location-inside- string Home Element from libvolume TSM object.

library

location-outside- string Location from media TSM object.

library

association-status string Status from libvolume TSM object.

device-type string Device Type from libvolume TSM object.

device-class-name string Device Class Name from volume TSM object.

estimated-capacity string Estimated Capacity from volume TSM object.

299
 Tibigen Digital Repository - REST API

Name Type Description

percentage- string Pct Util from volume TSM object.

utilization

fill-status string Volume Status from volume TSM object.

9.2.2. TSM Volume List

A TSM volume list is a container of TSM Volume objects.

Example of representation

<tsm-volumes>
  <tsm-volumes association-status="SCRATCH"
               device-type="LTO"
               id="136"
               inserted="2015-01-01 00:01:19"
               library-name="MHVTL"
               location-inside-library="&quot;1,024&quot;"
               updated="2015-01-01 00:01:19"
               volume-name="I00001L1"/>
</tsm-volumes>

9.2.3. List TSM volumes

Get list of representations of TSM volumes.

Request

GET /tsm/volumes?page={page}&size={size}&detailed={detailed}

Query parameters

Name Type Description

page integer The number of page of results to return. If not specified, web-service
returns all TSM volumes.

size integer The size of page of results. Default value is 10.

detailed boolean If true, returns detailed representation of each TSM volume in a list.
Default value is false.

300
 Tibigen Digital Repository - REST API

Authorization
This request requires authorization with permission view.tsm.

Response
If successful, the response status code is 200 OK and body contains TSM Volume List object wrapped in
Response object.

9.2.4. Get TSM volume

Get TSM volume.

Request

GET /tsm/volumes/{id}

Path parameters

Name Type Description

id integer A unique identifier of TSM volume.

Authorization
This request requires authorization with permission view.tsm.

Response
If successful, the response status code is 200 OK and body contains TSM Volume object wrapped in
Response object.

Errors

Error code Status Description

code

ResourceNotFoundException 404 Cannot find volume with given id.

9.2.5. Add TSM volume

Add new representation of TSM volume to TDR. This web-service does not add volume in TSM.

Request

301
 Tibigen Digital Repository - REST API

POST /tsm/volumes

In the request body, supply a TSM Volume object with at least required properties.

Authorization
This request requires authorization with permission manage.tsm.

Response
If successful, the response status code is 200 OK and body contains Value object with ID of newly added
TSM volume wrapped in Response object.

Errors

Error code Status Description

code

InvalidVolumeNameExceptio 400 Given name is not specified or is empty.

n

9.2.6. Update TSM volume

Update TSM volume representation in TDR. This web-service does not update volume in TSM.

Request

PUT /tsm/volumes/{id}

Path parameters

Name Type Description

id integer A unique identifier of TSM volume.

In the request body, supply a TSM Volume object with updated properties.

Authorization
This request requires authorization with permission manage.tsm.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

302
 Tibigen Digital Repository - REST API

Errors

Error code Status Description

code

InvalidVolumeNameExceptio 400 Given name is not specified or is empty.

n

ResourceNotFoundException 404 Cannot find volume with given id.

9.2.7. Delete TSM volume

Delete representation of TSM volume from TDR. This web-service does not delete volume from TSM.

Request

DELETE /tsm/volumes/{id}

Path parameters

Name Type Description

id integer A unique identifier of TSM volume.

Authorization
This request requires authorization with permission manage.tsm.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

ResourceNotFoundException 404 Cannot find volume with given id.

9.3. TSM Storage pools

Storage pools from TSM. If TDR has active integration with TSM, then storage pools should be
synchronized automatically by executing process TSM Synchronize Job.

9.3.1. TSM Storage Pool

303
 Tibigen Digital Repository - REST API

Example of representation

<tsm-storage-pool device-class-name="DISK"
                  estimated-capacity="157286400"
                  high-migration-percentage="90.0"
                  id="3"
                  inserted="2015-02-15 05:45:37"
                  low-migration-percentage="70.0"
                  percentage-migration="0.0"
                  storage-pool-name="SEQ_DISK"
                  updated="2015-01-01 00:01:16"
                  percentage-utilization="0.0"
                  next-storage-pool="4"/>

Table 81. TSM storage pool properties

Name Type Description

id integer The identifier of this TSM storage pool in TDR.

storage-pool-name string Storage Pool Name from stgpool TSM object.

device-class-name string Device Class Name from stgpool TSM object.

estimated-capacity string Estimated Capacity from stgpool TSM object.

percentage- string Pct Util from stgpool TSM object.

utilization

high-migration- string High Mig Pct from stgpool TSM object.

percentage

low-migration- string Low Mig Pct from stgpool TSM object.

percentage

next-storage-pool string Identifier of storage pool in TDR database, which is Next

Storage Pool in stgpool TSM object, for this storage pool.

inserted datetime The time when TSM storage pool was created in TDR.

updated datetime The time when TSM storage pool was updated in TDR.

9.3.2. TSM Storage Pool List

A TSM storage pool list is a container of TSM Storage Pool objects.

304
 Tibigen Digital Repository - REST API

Example of representation

<tsm-storage-pools>
  <tsm-storage-pool id="3"
                    device-class-name="DISK"
                    estimated-capacity="157286400"
                    high-migration-percentage="90.0"
                    inserted="2015-02-15 05:45:37"
                    low-migration-percentage="70.0"
                    percentage-migration="0.0"
                    storage-pool-name="SEQ_DISK"
                    updated="2015-01-01 00:01:16"
                    percentage-utilization="0.0"/>
</tsm-storage-pools>

9.3.3. List TSM storage pools

Get list of representations of TSM storage pools.

Request

GET /tsm/storage-pools?name={name}&page={page}&size={size}&detailed={detailed}

Query parameters

Name Type Description

name string Filter by name of storage pool.

page integer The number of page of results to return. If not specified, web-service
returns all TSM storage pools.

size integer The size of the page of results. Default value is 10.

detailed boolean If true, returns detailed representation of each TSM storage pool in a
list. Default value is false.

Authorization
This request requires authorization with permission view.tsm.

Response
If successful, the response status code is 200 OK and body contains TSM Storage Pool List object
wrapped in Response object.

305
 Tibigen Digital Repository - REST API

9.3.4. Get TSM storage pool

Get TSM storage pool.

Request

GET /tsm/storage-pools/{id}

Path parameters

Name Type Description

id integer A unique identifier of TSM storage pool.

Authorization
This request requires authorization with permission view.tsm.

Response
If successful, the response status code is 200 OK and body contains TSM Storage Pool object wrapped in
Response object.

Errors

Error code Status Description

code

StoragePoolNotFoundExcepti 404 Cannot find TSM storage pool with given id.
on

9.3.5. Add TSM storage pool

Add new TSM storage pool.

Request

POST /tsm/storage-pools

In the request body, supply a TSM Storage Pool object with at least required properties.

Authorization
This request requires authorization with permission manage.tsm.

306
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains Value object with ID of newly added
TSM storage pool wrapped in Response object.

Errors

Error code Status Description

code

InvalidStoragePoolNameExce 400 Given name is not specified or is empty or length of the

ption name is higher than 30 characters.

InvalidStoragePoolUtilization 400 Utilization percentage is invalid % value.

Exception

InvalidStoragePoolMigration 400 Migration percentage is invalid % value.

Exception

InvalidStoragePoolHighMigra 400 High migration percentage is invalid % value.

tionException

InvalidStoragePoolLowMigra 400 Low migration percentage is invalid % value.

tionException

InvalidMaxScratchAllowedEx 400 Maximum number of scratch tapes is invalid.

ception

9.3.6. Update TSM storage pool

Update TSM storage pool.

Request

PUT /tsm/storage-pools/{id}

Path parameters

Name Type Description

id integer A unique identifier of TSM storage pool.

In the request body, supply a TSM Storage Pool object with updated properties.

Authorization
This request requires authorization with permission manage.tsm.

307
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

InvalidStoragePoolNameExce 400 Given name is not specified or is empty or length of the

ption name is higher than 30 characters.

InvalidStoragePoolUtilization 400 Utilization percentage is invalid % value.

Exception

InvalidStoragePoolMigration 400 Migration percentage is invalid % value.

Exception

InvalidStoragePoolHighMigra 400 High migration percentage is invalid % value.

tionException

InvalidStoragePoolLowMigra 400 Low migration percentage is invalid % value.

tionException

InvalidMaxScratchAllowedEx 400 Maximum number of scratch tapes is invalid.

ception

StoragePoolNotFoundExcepti 404 Cannot find TSM storage pool with given id.
on

9.3.7. Delete TSM storage pool

Delete TSM storage pool.

Request

DELETE /tsm/storage-pools/{id}

Path parameters

Name Type Description

id integer A unique identifier of TSM storage pool.

Authorization
This request requires authorization with permission manage.tsm.

308
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

StoragePoolNotEmptyExcepti 400 Cannot delete TSM storage pool with files on it.
on

StoragePoolNotFoundExcepti 404 Cannot find TSM storage pool with given id.
on

9.4. TSM Processes

This section describes intergation with Tivoli Storage Manager in terms of processes. Currently, TDR
allows you to view running processes in TSM installation.

9.4.1. TSM Process

Example of representation

<tsm-process process="Migration"
             process-number="60"
             start-time="2015-02-25 19:32:40"
             status="&quot;Disk Storage Pool SEQ_DISK, Moved Files: 2, Moved Bytes: 93,724,672,
Unreadable Files: 0, Unreadable Bytes: 0. Current Physical File (bytes): 46,862,336 Waiting for
mount of scratch volume (0 seconds). &quot;"/>

Table 82. TSM Process properties

Name Type Description

process string Process Description from process TSM object.

process-number string Process Number from process TSM object.

start-time datetime The time when TSM process started.

status string Status from process TSM object.

9.4.2. TSM Process List

A TSM process list is a container of TSM Process objects.

309
 Tibigen Digital Repository - REST API

Example of representation

<tsm-processes>
  <tsm-process process="Migration"
               process-number="60"
               start-time="2015-02-25 19:32:40"
               status="&quot;Disk Storage Pool SEQ_DISK, Moved Files: 2, Moved Bytes: 93,724,672,
Unreadable Files: 0, Unreadable Bytes: 0. Current Physical File (bytes): 46,862,336 Waiting for
mount of scratch volume (0 seconds). &quot;"/>
</tsm-processes>

9.4.3. List TSM processes

Get list of currently running processes on TSM.

Request

GET /tsm/processes

Authorization
This request requires authorization with permission view.tsm.

Response
If successful, the response status code is 200 OK and body contains TSM Process List object wrapped in
Response object.

10. Data Retention

In TDR it is possible to describes how long files should be stored in system. System will delete files if
they satisfy requirements defined by Retention Policies.

10.1. Retention Policies

Retention policies describe how long files should be stored in system.

10.1.1. Retention Policy

310
 Tibigen Digital Repository - REST API

Example of representation

<retention-policy
    uuid="c798f564-4bba-41fb-9ab8-54b8aa5b8f17"
    period="24"
    type="GLOBAL"
    asset-type-id="1">
        <labels>
            <label lang="EN" value="High res - two years" />
        </labels>
</retention-policy>

Table 83. Retention Policies properties

Name Type Description

uuid uuid The uuid of Retention Policy

period integer Number of months that given asset type’s files should be
stored in TDR.

type string The type of Retention Policy. It can be LOCAL (policies with
this type can be chosen per item and affects its files) or
GLOBAL (policies with this type affects files of defined asset
type).

asset-type-id integer The id of asset type which files should be controlled by

Retention Policy. When not set, Retention Policy will control
all files.

labels Label List A list of labels in languages defined in TDR. TDR requires at
least one label in system default language.

10.1.2. Retention Policies List

A Retention Policies list is a container of Retention Policy objects.

311
 Tibigen Digital Repository - REST API

Example of representation

<retention-policies>
    <retention-policy
        uuid="c798f564-4bba-41fb-9ab8-54b8aa5b8f17"
        period="24"
        type="GLOBAL"
        asset-type-id="1">
            <labels>
                <label lang="EN" value="High res - two years" />
            </labels>
    </retention-policy>
</retention-policies>

10.1.3. List Retention Policies

Get list of representations of Retention Policies.

Request

GET /retention-policies?type={type}&page={page}&size={size}&detailed={detailed}

Query parameters

Name Type Description

type string The type of retention policy. Only retention policies with given type
will be returned. If not set, all retention policies will be returned.

page integer The number of page of results to return. Default value is 0.

size integer The size of the page of results. Default value is 10.

detailed boolean If true returns detailed representation of Retention Policy. Default

value is false.

Authorization
This request requires authorization with permission view.retention-policy.

Response
If successful, the response status code is 200 OK and body contains Retention Policies List object
wrapped in Response object.

312
 Tibigen Digital Repository - REST API

10.1.4. Get Retention Policy

Get Retention Policy.

Request

GET /retention-policies/{uuid}

Path parameters

Name Type Description

uuid uuid A unique identifier of Retention Policy.

Authorization
This request requires authorization with permission view.retention-policy.

Response
If successful, the response status code is 200 OK and body contains Retention Policy object wrapped in
Response object.

Errors

Error code Status Description

code

RetentionPolicyNotFoundExc 404 Cannot find Retention Policy with given uuid.

eption

10.1.5. Add Retention Policy

Add new Retention Policy.

Request

POST /retention-policies

In the request body, supply a Retention Policy object with at least required properties.

Authorization
This request requires authorization with permission manage.retention-policy.

313
 Tibigen Digital Repository - REST API

Response
If successful, the response status code is 200 OK and body contains Value object with UUID on newly
added Retention Policy wrapped in Response object.

Errors

Error code Status Description

code

RetentionPolicyAlreadyExists 409 Retention Policy with given uuid already exists.

Exception

10.1.6. Update Retention Policy

Update Retention Policy.

Request

PUT /retention-policies/{uuid}

Path parameters

Name Type Description

uuid uuid A unique identifier of Retention Policy.

In the request body, supply a Retention Policy object with updated properties.

Authorization
This request requires authorization with permission manage.retention-policy.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

RetentionPolicyNotFoundExc 404 Cannot find Retention Policy with given uuid.

eption

314
 Tibigen Digital Repository - REST API

10.1.7. Delete Retention Policy

Delete Retention Policy.

Request

DELETE /retention-policies/{uuid}

Path parameters

Name Type Description

uuid uuid A unique identifier of Retention Policy.

Authorization
This request requires authorization with permission manage.retention-policy.

Response
If successful, the response status code is 200 OK and body contains empty Response object.

Errors

Error code Status Description

code

RetentionPolicyNotFoundExc 404 Cannot find Retention Policy with given uuid.

eption

11. Single Sign On

TDR can act as a Service Provider (SP) in federations based on Web Single Sign-On (SSO) and Single
Logout (SLO) profiles of SAML 2.0 protocol. It can work with SAML 2.0 Identity Providers (IdP) like
ADFS.

11.1. Single Sign On flow

• Web application open <TDR api>/sso/login page. Proper referrer header is required. It will be saved
in session and used in next steps.

• <TDR api>/sso/login service redirects to IdP login page.

• After successfully authentication IdP redirects to <TDR api>/sso/landing

• TDR checks that authenticated user is allowed to login in TDR (it must have at last one group that
match ldap.groups property).

315
 Tibigen Digital Repository - REST API

◦ For user allowed to login in TDR:

▪ If user with given NameID not exist in TDR database it will be added to it, otherwise it will
be updated.

▪ TDR creates token for user.

◦ For user not allowed to login in TDR:

▪ TDR redirects to referrer of <TDR api>/sso/login service with path <Referrer>/sso_error with
query parameters code with error code and description with error description.

• TDR redirects to referrer of <TDR api>/sso/login service with path <Referrer>/sso and query
parameters token with created user’s token and login with logged in user’s login.

11.2. Single Logout flow

• Web application open <TDR api>/sso/login service.

• On successfully logout TDR returns text/html response with javascript window.close() function
assigned to onLoad event on BODY tag.

• On failed logout TDR throws SingleLogOutFailedException

11.3. Services
11.3.1. SSO Login
Redirects to IdP login page. Saves referrer header value in session.

Request

GET /sso/login

Authorization
This request requires no authorization.

Response
If successful, the response redirects to IdP login form page.

Errors
If referer is not null TDR redirects to <Referrer>/sso_error with query parameters code with error code
and description with error description.

316
 Tibigen Digital Repository - REST API

Error code Status Description

code

NoIDPWasConfiguredExcepti 424 No IDP was configured.

on

AdfsSsoNotAvailableExceptio 424 ADFS SSO turned off by property 'sso.adfs'.

n

11.3.2. SSO Logout

User will be redirected to this service after successful logout.

Request

GET /sso/logout

Authorization
This request requires no authorization.

Response
If successful, the response returns text/html response with javascript window.close() function assigned
to onLoad event on BODY tag.

Errors

Error code Status Description

code

SingleLogOutFailedException 424 Single logout failed.

11.3.3. SSO landing

User will be redirected to this service after successful login.

Request

GET /sso/landing

Authorization
This request requires no authorization.

317
 Tibigen Digital Repository - REST API

Response
If successful, the response redirects to <referrer_header_value_saved_in_/sso/login_request>/sso with
query parameters token and login where token is created authenticated user token and login is
authenticated user login.

Errors
If referer saved in session is not null TDR redirects to <Referrer>/sso_error with query parameters
code with error code and description with error description.

Error code Status Description

code

NoIDPWasConfiguredExcepti 424 No IDP was configured.

on

AdfsSsoNotAvailableExceptio 424 ADFS SSO turned off by property 'sso.adfs'.

n

SsoAuthenticationFailedExce 401 Failed to authenticate during Single Sign On.

ption

ReferrerNotFoundException 404 Referrer address not found.

SsoNotSufficientPermissionE 403 Not sufficient permissions to log in.

xception

11.3.4. SAML services

List of SSO SAML services filters

Table 84. List of SSO SAML services filter

Filter path Description

/saml/login/** Login filter sends login request to IDP.

/saml/logout/** Logout filter leveraging SAML 2.0 Single Logout profile. Upon invocation of the
filter URL it is determined whether global (termination of all participating
sessions) or local (termination of only session running within Spring Security)
logout is requested based on request attribute. In case global logout is in question
a LogoutRequest is sent to the IDP.

/saml/metadata/** The filter expects calls on configured URL and presents user with SAML2
metadata representing this application deployment. In case the application is
configured to automatically generate metadata, the generation occurs upon first
invocation of this filter (first request made to the server).

/saml/SSO/** Filter processes arriving SAML messages by delegating to the WebSSOProfile.

After the SAMLAuthenticationToken is obtained, authentication providers are
asked to authenticate it.

318
 Tibigen Digital Repository - REST API

/saml/SSOHoK/** Filter processes messages sent from IDP as part of the WebSSO Holder-of-Key
profile.

/saml/SingleLogout/ Filter processes arriving SAML Single Logout messages by delegating to the
** LogoutProfile.

319