JSDoc: Tutorial: 2. File API

The SAP HANA REST Application Programming Interface (REST API) includes a file API that enables you to browse and manipulate files and directories via HTTP. The File API included in the SAP HANA REST API uses the basic HTTP methods GET, PUT, and POST to send requests, and JSON is used as the default representation format. For more information about the original Orion File API, on which the File API is based, see http://wiki.eclipse.org/Orion/Server_API/File_API.

The information in this section describes how to use the File API in the context of SAP HANA. The file API supports all API methods except setting file contents from different HTTP input.

Contents

1 Actions on Files
2 Actions on Directories
3 Creating Files and Directories
4 Copying, Moving, and Deleting Files
5 Mass Transfer
6 Technical Aspects
7 Change Tracking
- 7.1 Default Handling
- 7.2 Explicit Handling

Actions on files

Get File Contents

Retrieve the contents of a file (http://wiki.eclipse.org/Orion/Server_API/File_API#Getting_file_contents). You can also retrieve the contents of a particular version of the file by setting a parameter Version in SapBackPack (also an URL-parameter version is supported) or check the ETag of the current version of the file (using the "If-Match" parameter). The file API supports a conditional "If-None-Match", too. Note that providing a header for the "If-None-Match" results in the return code 304 (Not Modified) if the file was already requested in the current session and the file was not changed since the last request.

If you specify a value for the parameter Workspace in SapBackPack , the file API returns the most recent inactive version of the file in the given workspace, if it exists. If no inactive version of the requested file exists in the specified workspace, then an active version of the file is retrieved. The default workspace is "" (empty string).

An active version of a file can be obtained by providing a parameter Active=true in the SapBackPack, which has a lower priority then the parameter Version.

One can also obtain the content of an active deleted file by providing a parameter ProcessDeleted=true in SapBackPack.

Example Request


GET /sap/hana/xs/dt/base/file/MyProj/myfile.txt

Orion-Version: 1.0

If-Match: "358768768767"

SapBackPack: "{'Workspace': 'ABC', 'Version': 12}"

NOTE: In the request illustrated in the example above, the parameters Version, If-Match, and SapBackPack are optional.

Example Response


HTTP/1.1 200 OK

Content-Type: text/plain

Content-Length: 22



This is the contents

Get File Metadata

Retrieve metadata of a file (http://wiki.eclipse.org/Orion/Server_API/File_API#Getting_file_metadata). It is possible to retrieve the complete history of a file either by using SapBackPack.History = true or S apBackPack.Versions = true . However, note that SapBackPack.Versions also retrieves the current active version. If a version of a file was deleted, the parameter IsDeletion=true is added to the corresponding version in the history list. By default, no information about the file history or versions is retrieved.

You can check the ETag of the current version of the file (If-Match); a conditional If-None-Match is also supported. Providing an If-None-Match header results in the return code 304 (Not Modified) if the file was already requested in the current session and the file has not been changed since the request.

Currently all file attributes (except SapBackPack ) are provided as constants, which cannot be modified. For example, Executable is always set to = false . Only the attributes provided by " SapBackPack " can be meaningfully used.

For active files, the additional attributes " ActivatedAt " and " ActivatedBy " enable you to find out who activated a file and when. For inactive files, you can use the attribute " LastModifiedAt " to display when the requested file was last changed.

Using the parameter Workspace in the SapBackPack returns an inactive version of the file in the given Repository workspace, if an inactive version of the file exists. If an inactive version of the requested file does not exist, then an active version of the requested file is retrieved. The default workspace is "" (empty string).

Metadata for an active version of a file can be obtained by providing a parameter Active=true in the SapBackPack, which has a lower priority then the parameter Version.

One can also obtain the metadata of an active deleted file by providing a parameter ProcessDeleted=true in SapBackPack.

Example Request


GET /sap/hana/xs/dt/base/file/MyProj/myfile.txt?parts=meta

Orion-Version: 1.0

SapBackPack: "{'History': 'false', 'Version': 12}"

If-Match: "35987989879"

NOTE: In the request illustrated in the example above, the parameters version, If-Match, and SapBackPack are optional.

Example Response


HTTP/1.1 200 OK

Content-Type: application/json

Content-Length: 132

ETag: "35987989879"



{

"Name": "myfile.txt",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfile.txt",

"RunLocation": "/MyProj/myfile.txt",

"ETag": "35987989879",

"Directory": false,

"LocalTimeStamp": 01234345009837,



"Attributes": {

"ReadOnly": false,

"Executable": false,

"SapBackPack" : {'Activated' : true}

}



"SapBackPack": {

"Version":60,

"ActivatedAt":1397644007537,

"ActivatedBy":"User"

}

}

Get File Metadata and Contents

Both metadata and file contents are retrieved in a single request (http://wiki.eclipse.org/Orion/Server_API/File_API#Getting_file_metadata_and_contents).

You can use the file API to retrieve the metadata of a specific version of a file by setting a parameter Version in SapBackPack (also an URL-parameter version is supported) . You can also check the ETag of the current version of the file (If-Match); a conditional If-None-Match is also supported. Providing an If-None-Match header results in the return code 304 (Not Modified) if the file was already requested in the current session and the file has not been changed since the request.

Using the parameter Workspace in the SapBackPack returns an inactive version of the file in the given Repository workspace, if an inactive version of the file exists. If an inactive version of the requested file does not exist, then an active version of the requested file is retrieved. The default workspace is "" (empty string).

Example Request


GET /sap/hana/xs/dt/base/file/MyProj/myfile.txt?parts=meta,body&version=12

Orion-Version: 1.0

If-Match: "35987989879"

NOTE: In the request illustrated in the example above, the parameters version, and If-Match are optional.

Example Response


HTTP/1.1 200 OK

Content-Length: 1325

ETag: "35987989879"

Content-Type: multipart/form-data; boundary=FE09F2EF893DC0EBF883370B32F7D71C0

--FE09F2EF893DC0EBF883370B32F7D71C0

Content-Type: application/json

Content-Length: 132



{

"Name": "myfile.txt",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfile.txt",

"RunLocation": "/MyProj/myfile.txt",

"ETag": "35987989879",

"Directory": false,

"LocalTimeStamp": 01234345009837,

"Attributes": {  "ReadOnly": false, "Executable": false,  "SapBackPack" : {'Activated' : true}  }

"SapBackPack": {  "Version":60,  "ActivatedAt":1397644007537,  "ActivatedBy":"User"  } }

}

--FE09F2EF893DC0EBF883370B32F7D71C0

Content-Type: text/plain; charset=utf-8

Content-Length: 20



This is the contents

--FE09F2EF893DC0EBF883370B32F7D71C0--

Set File Contents

Replace the contents of an existing file (http://wiki.eclipse.org/Orion/Server_API/File_API#Setting_file_contents). The parameter Activate in SapBackPack enables you to specify if the requested file should be activated. By default, the file is activated. You can specify the activation mode by adding the attribute ActivationMode to the SapBackPack header. For more information about activation modes, see the Activation Mode section below. You can also use the optional If-Match parameter to check the ETag of the active version of the file.

As an extension of the Orion specification, you can create files can using the PUT method. File creation using POST is also supported. In addition, any packages specified in the request path that do not exist in the target repository can be created by the PUT request, for example, by including the parameter CreatePkg=true in the SapBackPack attribute.

If you need to add an inactive version of a file to the Repository, you can specify the name of the target workspace by using the parameter Workspace in SapBackPack. In no workspace name is specified in the request, a the default workspace "" (empty string) is used.

Also an inactive writing in a historical version of a file is supported by providing a parameter Version in the SapBackPack.

Example Request


PUT /sap/hana/xs/dt/base/file/MyProj/myfile.txt

Orion-Version: 1.0

X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"

If-Match: "35"

Content-Type: text/plain

SapBackPack: {'Activate': true}

This is the new contents

NOTE: In the request illustrated in the example above, the parameters SapBackPack and If-Match are optional.

Example Response


HTTP/1.1 200 OK Content-Type: application/json Content-Length: 132

ETag: "35987989879"



{

"Name": "myfile.txt",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfile.txt",

"RunLocation": "/MyProj/myfile.txt",

"ETag": "35987989879",

"Directory": false,

"LocalTimeStamp": "01234345009837",

"Charset": "UTF-8",

"ContentType": "text/plain",



"Attributes": {

"ReadOnly": false,

"Executable": false,

"SapBackPack" : {'Activated' : true}

}



"SapBackPack": {

"Version":60,

"ActivatedAt":1397644007537,

"ActivatedBy":"User"

}

}

Set File Contents with Different HTTP Input

Not Implemented

Changing file metadata

Update a file's metadata (http://wiki.eclipse.org/Orion/Server_API/File_API#Changing_file_metadata). Currently all file attributes (except SapBackPack) are provided as constants that cannot be modified; for example, Executable is always set to false. Only the attributes provided by SapBackPack can be meaningfully used to set a specific value. For example, to activate a file, use the parameter Activated=true in the attribute SapBackPack. It is not possible to deactivate a file.

You can also use the optional If-Match parameter to check the ETag of the active version of the file.

When changing other attributes included with SapBackPack, the return code is 204 (as described in the Orion specification). An activation operation returns 200 and the CheckResult describing the result of the activation (see the CheckResult section below).

You can also use the parameter Activate in the SapBackPack header to specify if the file should be activated as part of the request. Note that the Activate parameter set in the SapBackPack header has a higher priority than the identically named parameter Activated set with SapBackPack in the request body. Setting the activation mode to 5 performs a check that establishes if it is the possible to activate the file. For more information about file activation, see the section about Activation modes below).

Instead of activation one can also do a regeneration of a file by providing the parameter Regenerate=true in the SapBackPack. The regeneration can be applied, for example, if the dependencies of an activated file have been updated. The parameter Regenerate has a higher priority then the parameter Activate.

Example Request


PUT /sap/hana/xs/dt/base/file/MyProj/myfile.txt?parts=meta

Orion-Version: 1.0

X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"

If-Match: "35" (optional)

Content-Type: application/json



{

"Attributes": {

"SapBackPack" : {'Activated': true},

"ReadOnly": false (ignored)

}

}

Example Response


HTTP/1.1 200 OK

Content-Type: application/json



{

"timestamp":1395917427292,

"object":{"tenant":"","package":"MyProj","name":"myfile","stype":"txt","type":0},

"location":"",

"error_code":0,

"error_msg":"no error",

"severity":0

}

Change Metadata and Contents

Update a file's metadata and file contents in a single request (http://wiki.eclipse.org/Orion/Server_API/File_API#Changing_metadata_and_contents).

Currently all file attributes (except SapBackPack) are provided as constants that cannot be modified; for example, Executable is always set to =false. Only the attributes provided by SapBackPack can be meaningfully used to set a specific value. For example, to activate a file, use the parameter Activated=true in the attribute SapBackPack. By default, the file is activated. It is not possible to deactivate a file.

You can also use the optional If-Match parameter to check the ETag of the active version of the file

If you need to add an inactive version of a file to the Repository, you can specify the name of the target workspace by using the parameter Workspace in SapBackPack. In no workspace name is specified in the request, the default workspace "" (empty string) is used.

You can also use the parameter Activate in the SapBackPack header to specify that the file should be activated as part of the request. Note that the Activate parameter set in the SapBackPack header has a higher priority than the identically named parameter Activated set with SapBackPack in the request body.

Example Request


PUT /sap/hana/xs/dt/base/file/MyProj/myfile.txt?parts=meta,body

Orion-Version: 1.0

X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"

If-Match: "3545612373" (optional)

Content-Type: multipart/related; boundary="XSBOUNDARY"



XSBOUNDARY



Content-Type: application/json

{

"Name": "myfile.txt",

"Attributes": {

"SapBackPack" : {'Activated': true},

"ReadOnly": false (ignored)

}

}

XSBOUNDARY
 


Content-Type: text/plain

This is the new contents

XSBOUNDARY

Example Response

HTTP/1.1 200 OK

Content-Type: application/json

Content-Length: 132

ETag: "3545612373"



{

"Name": "myfile.txt",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfile.txt",

"RunLocation": "/MyProj/myfile.txt",

"ETag": "3545612373",

"Directory": false,

"LocalTimeStamp": 01234345009837,

"Charset": "UTF-8",

"Attributes": {

"ReadOnly": false,

"Executable": false,

"SapBackPack" : {'Activated' : true}



}

}

Actions on directories

Get Directory Metadata

Retrieve metadata of a directory (http://wiki.eclipse.org/Orion/Server_API/File_API#Getting_directory_metadata). Currently all directory attributes are provided as constants, which cannot be modified.

If available, the following information is provided in the response body wrapped in the SapBackBack: Source system, delivery unit, vendor, attribute structural package.

Example Request


GET /sap/hana/xs/dt/base/file/MyProj/myfolder/

Orion-Version: 1.0

Example Response


HTTP/1.1 200 OK

Content-Type: application/json

Content-Length: 232



{

"Name": "myfolder",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder",

"ContentLocation": "/MyProj/myfolder",

"ChildrenLocation": "MyProj/myfolder?depth=1",

"LocalTimeStamp": 01234345009837,

"Directory": true

"Attributes": {

"ReadOnly": false,

"Executable": false

}

}

Change Directory Metadata

Change directory metadata (http://wiki.eclipse.org/Orion/Server_API/File_API#Changing_directory_metadata).

The following list of parameters can be provided with the SapBackBack in order to change directory metadata.

Parameter	Example value
DeliveryUnit	"TEST_DU"
Vendor	"sap.com"
SrcSystem	"ABC"
TenantID	"tenant_id"
SrcTenant	"ABC"
Description	"This is a description"
Responsible	"SampleName"
OriginalLanguage	"en_US"
Structural	false
TextCollection	"collection"
TextStatus	"status"
TextTerminologyDomain	"domain"
HintsForTranslation	"hints"

By default the package metadata will be propagated recursively to all sub-packages. In order to avoid this behavior one can provide the parameter Recursive=false in the SapBackPack.

Example Request


PUT /sap/hana/xs/dt/base/file/MyProj/myfolder

Content-Type: application/json

X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"

"SapBackPack" : "{'DeliveryUnit': 'TEST_DU', 'Vendor': 'test'}"

{

"Attributes": {

"ReadOnly": true -- ignored

}

}

Example Response


HTTP/1.1 204 OK

List Directory Contents

List a contents of a directory (http://wiki.eclipse.org/Orion/Server_API/File_API#Listing_directory_contents).

Use the parameter Workspace with SapBackPack returns inactive versions of the specified files, if any exist in the given workspace. If not inactive files exist in the specified workspace, an active version of the file is returned. If no workspace is specified, an inactive version of the file is retrieved if any inactive files exist in the default workspace. If no inactive versions of the specified file exist in the default workspace, then an active version of the file is retrieved.

For obtaining all files from a package recursively one can provide "infinity" or -1 as a depth value. For security reasons the depth is limited by 1000.

Example Request


GET /sap/hana/xs/dt/base/file/MyProj/myfolder?depth=1

Example Response


HTTP/1.1 200 OK

Content-Type: application/json

Content-Length: 132



{

"Name": "myfolder",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder",

"ContentLocation": "/MyProj/myfolder",

"LocalTimeStamp": 01234345009837,

"Directory": true

"Attributes": {

"ReadOnly": false,

"Executable": false

},

"Children": [

{

"Name": "myfile.txt",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder/myfile.txt",

"RunLocation": "/MyProj/myfolder/myfile.txt",

"Directory": false

}

]

}

Creating Files and Directories

General notes on using the POST method can be found at http://wiki.eclipse.org/Orion/Server_API/File_API#Notes_on_POST_method.

Create a Directory

Create a new directory in the given parent directory (http://wiki.eclipse.org/Orion/Server_API/File_API#Creating_a_directory).

If a parent directory is assigned to a delivery unit, then the created directory will be automatically assigned to the same delivery unit. In order to prevent this behavior one can provide an additional parameter Inherit=false with SapBackPack.

Example Request


POST /sap/hana/xs/dt/base/file/MyProj/

Content-Type: application/json

X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"

Slug: myfolder

 

{

"Name": "myfolder",

"Directory": "true"

}

Example Response


HTTP/1.1 201 OK

 

{

"Name": "myfolder",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder",

"ContentLocation": "/MyProj/myfolder",

"ETag": "35fd43td3",

"LocalTimeStamp": 01234345009837,

"Directory": true

"Attributes": {

"ReadOnly": false,

"Executable": false

}

}

Create an empty file

Create a new (empty) file in the given parent directory (http://wiki.eclipse.org/Orion/Server_API/File_API#Creating_an_empty_file). For creating a file the option "X-Create-Options: no-overwrite" is supported.

If creating an inactive version of the file a parameter Workspace in the SapBackPack can be provided for writing the file in the given workspace. Otherwise the default workspace "" (empty string) will be used.

Example Request


POST /sap/hana/xs/dt/base/file/MyProj/

Orion-Version: 1.0

X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"

Slug: myfile.txt

SapBackPack: "{'Activate': true}"

Example Response


HTTP/1.1 201 Created

Location: "/sap/hana/xs/dt/base/file/MyProj/myfile.txt",

RunLocation: "/MyProj/myfile.txt",

ETag: "3514352721"

Content-Type: application/json

 

{

"Name": "myfile.txt",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfile.txt",

"RunLocation": "/MyProj/myfile.txt",

"LocalTimeStamp": 01234345009837,

"Directory": false

"Attributes": {

"ReadOnly": false,

"Executable": false,

"SapBackPack" : {'Activated' : true}

}

}

Create a File with Contents

Creating a file and providing contents is not supported in a single POST request, but in the extended version of the REST API this can be done using a PUT request (see Setting file content).

Copy, Move, and Delete

General notes on using the POST method can be found at http://wiki.eclipse.org/Orion/Server_API/File_API#Notes_on_POST_method.

Following X-Create-Options are supported:

copy
move
copy, no-overwrite − order does not matter
move, no-overwrite − order does not matter

Delete a File or Directory

Delete a file or a directory (http://wiki.eclipse.org/Orion/Server_API/File_API#Deleting_a_file_or_directory). Optionally an ETag of the active version of the file can be checked (if_match).

By deleting a file providing a parameter Revert=true in the SapBackPack means that the version of the file (in the given workspace) will be reverted to the current active version. By deleting packages providing a parameter Revert=true in the SapBackPack means reverting all files in the package (in the given workspace).

There is a known issue by deleting packages containing files in different Workspaces. One approach is to revert all such files first. The alternative solution is to use a parameter ForceDelete=true in the SapBackPack.

Also an inactive delete of a historical version of a file is possible by providing a parameter Version in the SapBackPack.

Example Request


DELETE /sap/hana/xs/dt/base/file/MyProj/myfile.txt

Orion-Version = 1.0

X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"

If-Match: "35" (optional)

Example Response


HTTP/1.1 204 OK

Delete a Workspace

Providing parameters ProcessWorkspace=true and Workspace in the SapBackPack by deleting results in deleting a workspace. All inactive files (in the given workspace) will be either reverted to the current active version or deleted.

Example Request


DELETE /sap/hana/xs/dt/base/file/MyProj/myfile.txt

Orion-Version = 1.0

X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"

SapBackPack: "{'Workspace': 'ABC', 'ProcessWorkspace': true}"

Example Response


HTTP/1.1 204 OK

Copy a File or Directory

Copy a file or a directory into the new location (http://wiki.eclipse.org/Orion/Server_API/File_API#Copying_a_file_or_directory). When copying a file, the activation status remains the same. Optionally an ETag of the active version of the file can be checked (if_match).

Providing a parameter Activate in oSapBackPack describes if the copied file should be activated or not. By default only files that are active in the source workspace are activated after the copy operation completes.

To copy inactive files from a specific workspace, you can include the parameter Workspace in the SapBackPack request attribute. Note that the target inactive files will be stored in the specified workspace. If no workspace parameter is used to specify the workspace, the inactive files from the default workspace "" (empty string) are stored in the default workspace.

Example Request


POST /sap/hana/xs/dt/base/file/MyProj/

Orion-Version = 1.0

X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"

If-Match: "3512345" (optional)

Content-Type: application/json

Slug: destination.txt

X-Create-Options: copy

 

{

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder/source.txt"

}

Example Response


HTTP/1.1 201 Created

Location: "/sap/hana/xs/dt/base/file/MyProj/myfolder/destination.txt",

RunLocation: "/MyProj/myfolder/destination.txt"

ETag: "3512345"

Content-Type: application/json

 

{

"Name": "destination.txt",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder/destination.txt",

"RunLocation": "/MyProj/myfolder/destination.txt",

"ETag": "3512345",

"LocalTimeStamp": 01234345009837,

"Directory": false,

"Attributes": {

"ReadOnly": false,

"Executable": true,

"SapBackPack" : {'Activated' : true}

}

}

Move a File or Directory

Move a file or a directory into the new location (http://wiki.eclipse.org/Orion/Server_API/File_API#Copying_a_file_or_directory). When moving files, the activation statuses remain the same. Optionally an ETag of the active version of the file can be checked (if-match).

Providing a parameter Activate in oSapBackPack describes if the copied file should be activated or not. By default only those files that are active in the source are activated after the move operation completes.

To move inactive file from a specific workspace, you can use the parameter Workspace in the request attribute SapBackPack. Note that the target inactive files will be stored in the specified workspace. If no workspace parameter is specified, the inactive files from the default workspace "" (empty string) are stored in the default workspace.

Example Request


POST /sap/hana/xs/dt/base/file/MyProj/

Orion-Version = 1.0

X-CSRF-Token: "65ABA3082325A3408FBE71C87929102B"

If-Match: "3512345" (optional)

Content-Type: application/json

Slug: destination.txt

X-Create-Options: move

 

{

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder/source.txt",

}

Example Response


HTTP/1.1 201 Created

Location: "/sap/hana/xs/dt/base/file/MyProj/myfolder/destination.txt",

RunLocation: "/MyProj/myfolder/destination.txt",

ETag: "3512345"

Content-Type: application/json

 

{

"Name": "destination.txt",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder/destination.txt",

"RunLocation": "/MyProj/myfolder/destination.txt",

"ETag": "3512345",

"LocalTimeStamp": 01234345009837,

"Directory": false

"Attributes": {

"ReadOnly": false,

"Executable": true,

"SapBackPack" : {'Activated' : true}

}

}

Mass Transfer

Mass transfer enables you to apply GET and PUT operations to multiple files in a single HTTP request. Note that this feature is not a part of the Orion specification; it was developed to optimize the performance of GET and PUT requests when dealing with a large amount of files.

Mass Get Files from List

There are different ways of specifying the file paths. One way is to point the request's URL to the root of the file repository, as illustrated in the request example below. In this case, you must specify the complete path from the root of the repository for each file. Another possibility is to point the request's URL to a specified sub-package in the Repository, which then be considered as the root package for the files to be retrieved in the request.

When requesting the files' meta-information (as illustrated in the example below), the request has an additional parameter "parts=meta", and the response contains a list of file metadata formatted as a JSON string. If the request does not contain the parameter "parts=meta", then a multipart response is returned. The first entity contains a JSON-string describing the metadata, and the other entities describe the file contents in the order like listed in the meta-information.

By default, the current version of the file (active or inactive) is returned. An inactive version of a file in a specific workspace can be retrieved by adding the attribute Workspace to the SapBackPack-header. If the requested inactive file does not exist in the specified workspace, the current active version will be provided. The default workspace is "" (empty string). A specific version of the file can be requested by using the attribute Version to the SapBackPack-header. Note that if any file from the list does not exist in the specified workspace, the 404 (Not found) error will be returned.

Example Request


GET /sap/hana/xs/dt/base/file?parts=meta

Orion-Version = 1.0

SapBackPack: '{"MassTransfer":true, "MassTransferData": [{"Pkg":"MyProj/myfolder","Name":"destination1.txt","Dir":false}, ...]}'

Example Response


HTTP/1.1 200 OK

Content-Type: application/json

 

[

{

"Name": "destination1.txt",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder/destination1.txt",

"RunLocation": "/MyProj/myfolder/destination1.txt",

"ETag": "351234567",

"LocalTimeStamp": 01234345009837,

"Directory": false

"Attributes": { "ReadOnly": false, "Executable": true, "SapBackPack" : {'Activated' : true}}

},

{

"Name": "destination2.txt",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder/destination2.txt",

"RunLocation": "/MyProj/myfolder/destination2.txt",

"ETag": 251237891,

"LocalTimeStamp": 01234345009837,

"Directory": false,

"Attributes": { "ReadOnly": false, "Executable": true, "SapBackPack" : {'Activated' : true} }

}

]

Mass Get Files from Package

Obtains all files from all sub-packages in the specified package (recursively). You can use the parameter providePkg with the SapBackPack attribute to retrieve metadata for the sub-packages.

To request the metadata (as illustrated in the example below) use the parameter parts=meta in the URL; the response contains a list of file metadata in the form of a JSON string. If the request does not contain the parameter parts=meta, the multipart response is returned. The first entity contains a JSON-string describing the metadata; the other entities represent the file contents in the order specified in the meta-information.

By default. the current version of the file (active or inactive) is returned. An inactive version of the file in the specified workspace can be retrieved by including the attribute Workspace to the SapBackPack-header. If the requested inactive file does not exist, the current active version of the requested file is retrieved. The default workspace is "" (empty string).

Example Request


GET /sap/hana/xs/dt/base/file/MyProj/myfolder?parts=meta

Orion-Version = 1.0

SapBackPack: '{"MassTransfer":true}'

Example Response


HTTP/1.1 200 OK

Content-Type: application/json

 

[

{

"Name": "destination1.txt",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder/destination1.txt",

"RunLocation": "/MyProj/myfolder/destination1.txt",

"ETag": "351234567",

"LocalTimeStamp": 01234345009837,

"Directory": false

"Attributes": { "ReadOnly": false, "Executable": true, "SapBackPack" : {'Activated' : true}}

},

{

"Name": "destination2.txt",

"Location": "/sap/hana/xs/dt/base/file/MyProj/myfolder/destination2.txt",

"RunLocation": "/MyProj/myfolder/destination2.txt",

"ETag": "251345891",

"LocalTimeStamp": 01234345009837,

"Directory": false,

"Attributes": { "ReadOnly": false, "Executable": true, "SapBackPack" : {'Activated' : true} }

}

]

Get Files from Workspace

Retrieve all files from a provided repository workspace (Not an ORION workspace).

Example Request


GET /sap/hana/xs/dt/base/file/

SapBackPack: "{'Workspace': 'ABC', ProcessWorkspace: true}"

Example Response


HTTP/1.1 200 OK

 

 

[

{

"Name":"test1.txt",

"Directory":false,

"Attributes":{

"SapBackPack":{"Activated":false, "Workspace":"ABC"}},

...

},

{

"Name":"test2",

"Directory":false,

"Attributes":{"SapBackPack":{"Activated":false, "Workspace":"ABC"}},

...

}

]

Mass Put File Metadata from List

There are different ways of specifying the file paths in the request URL. One way is to point the request's URL to the root of the file repository, as illustrated in the example below. In this case, you must specify the complete path (from repository root) for each file. Another way to specify the file path is to point the request URL to a sub-package in the repository, which can then be considered as the root package for the files specified in the request.

Currently, only activation (changing the meta-information) is allowed, which requires the additional parameter parts=meta.

You can activate an inactive version of a file in the specified workspace by adding the attribute Workspace to the SapBackPack-header and providing the name of the target workspace. If the workspace attribute is not provided, the default workspace "" (empty string) is used.

Instead of an activation one can also apply a regeneration command to the files by providing the parameter Regenerate=true in the SapBackPack. The regeneration can be applied, for example, if the dependencies of an activated file have been changed. The parameter Regenerate has a higher priority then the parameter Activate.

If any file from the requested list does not exist in the specified workspace, the 404 (Not found) error is returned.

Example Request


PUT /sap/hana/xs/dt/base/file?parts=meta

Orion-Version = 1.0

X-CSRF-Token: securityToken

SapBackPack: '{"MassTransfer":true, "Activate":true, "ActivationMode":0, "MassTransferData": [{"Pkg":"PATH1","Name":"NAME1","Dir":false}, ...]}'

Example Response


HTTP/1.1 200 OK

Content-Type: application/json

 

 

{

"timestamp":1395917427292,

"object":[

{"tenant":"","package":"PATH1","name":"NAME1","stype":"EXT1","type":0},

{"tenant":"","package":"PATH2","name":"NAME2","stype":"EXT2","type":307}

],

"location":"",

"error_code":0,

"error_msg":"no error",

"severity":0

}

Mass Put File Metadata from Package

This request enables one to activate all inactive files from all sub-packages for a given package (recursively).

Currently only the activation (changing the meta-information) is allowed. In the request an additional parameter "parts=meta" should be provided.

Inactive files in the specific workspace ca be activated by adding an attribute Workspace to the SapBackPack-header. If the workspace attribute is not provided, then the default workspace "" (empty string) is used.

Example Request


PUT /sap/hana/xs/dt/base/file/PATH?parts=meta

Orion-Version = 1.0

 

X-CSRF-Token: securityToken

SapBackPack: '{"MassTransfer":true, "Activate":true, "ActivationMode":0}'

Example Response


HTTP/1.1 200 OK

Content-Type: application/json

 

 

{

"timestamp":1395917427292,

"object:[

{"tenant":"","package":"PATH","name":"NAME1","stype":"EXT1","type":0},

{"tenant":"","package":"PATH2","name":"NAME2","stype":"EXT2","type":307}

],

"location":"",

"error_code":0,

"error_msg":"no error",

"severity":0

}

Mass Delete Files from List

This request enables you to delete a list of files in a single request.

You can also use the parameter Activate in the SapBackPack header to specify if the deletion of files should be activated.

If any file from the requested list does not exist in the specified workspace, an error is returned.

Example Request


DELETE /sap/hana/xs/dt/base/file

Orion-Version = 1.0

X-CSRF-Token: securityToken

SapBackPack: '{"MassTransfer":true, "Activate":true, "ActivationMode":0, "MassTransferData": [{"Pkg":"PATH1","Name":"NAME1","Dir":false}, ...]}'

Example Response


HTTP/1.1 204 OK

Mass Delete Files from Package

For deleting a package with all sub-packages (recursively) see 4.1 Delete a File or Directory.

Technical Aspects

ETag

According to the Orion documentation, an ETag is an opaque token representing a unique state of a specified file or directory (http://wiki.eclipse.org/Orion/Server_API/File_API#JSON_representations). The standard recommends that any file changes are always accompanied by the ETag of the resource. An Etag is provided by the means of the If-Match header. In the context of the SAP HANA Repository, a parameter exists that can provide the last modification time; this parameter can be used instead of the generic ETag (as provided by the original Orion implementation). In the following example, the content of the file will be only written if the current file was modified at the corresponding time, which is specified in Coordinated Universal Time (UTC).


PUT /sap/hana/xs/dt/base/file/PATH/file.txt

Orion-Version: 1,

Content-Type: "text/plain",

If-Match: "1397646457439",

X-CSRF-Token: securityToken

  

Content

Activation Mode

When activating a file, you can use an activation mode to define how the specified file is activated. According to the SAP HANA XS Repository documentation, the following modes are available:

Activation mode	Description
ACTIVATION_CASCADE_ONE_PHASE	Commit any changes only if the specified objects are OK and, in addition, any affected objects are still OK
ACTIVATION_IGNORANT	If the specified objects are OK, they are activated; affected objects are not considered for the activation
ACTIVATION_FORCE	Deprecated; do not use this activation mode
ACTIVATION_CASCADE_TWO_PHASES	If the specified objects are OK, they are activated; any affected objects are revalidated in a separate transaction
ACTIVATION_IMPORT_MODE	Always commit, even if there are errors in activated objects and/or any objects affected by the activation
ACTIVATION_CHECK_ONLY	Internal use only; the "outer" method is checkObjects(). No changes are allowed; so everything is reverted at the end.

Activation mode can be set by adding the attribute ActivationMode to the SapBackPack-header. The ActivationMode attribute can have an integer value from 0 to 5. The default value is 0.

For example, use value 5 if you just want to run an activation check but not perform any actual activation.

Timestamp

Timestamps as well as attributes like ActivatedAt or LastModifiedAt are specified in milliseconds since 1970 in the Coordinated Universal Time (UTC).

CheckResult

The File API uses the CheckResult structure described below. The CheckResult is provided each time the file is activated or in the event of a dynamic error. An error is considered to be "dynamic" if the reason is not in the syntactical part of the call.

Below are two examples of CheckResult: one for a successful activation and one for a failed activation.


{

"timestamp":1395917427292,

"object":{"tenant":"","package":"MyProj","name":"myfile","stype":"txt","type":0},

"location":"",

"error_code":0,

"error_msg":"no error",

"severity":0

}

{

"Operations":{"Write":true,"Activate":false},

"timestamp":1395936172353,

"object":{"tenant":"","package":"MyProj","name":"bad","stype":"js"},

"location":"line 1 position 11 in MyProj/bad.xsjs",

"error_code":40117,

"error_msg":"SyntaxError: missing ( before formal parameters (line 1 position 11 in MyProj/bad.xsjs)",

"severity\":3

}

Change Tracking

Change tracking enables you to activate selectively the latest approved versions of objects. This section describes how the File API behaves, if the change-tracking option is currently active in the specified SAP HANA system.

Default Handling

If an object (or a set of objects) is activated using the default change-tracking handling (for example, without setting SapBackPack.ChangeTrackingMode or by setting it to 0), a dynamic change list is created, and the file(s) are activated using the generated change list. After activation, a so-called change contribution is automatically approved, and the change list released. From the developer perspective, the change-tracking mechanism is not visible.

Explicit Handling

In the explicit handling of change tracking the user is allowed to activate files, which are already assigned to a change list. Files can also be activated using an explicitly provided change list ID.

In the example below the files 'PATH/file1.txt' and 'PATH/file2.txt' are assigned to the change list "ABC//12345". All other files will be activated using the change list "ABC//11111".

Example Request


PUT /sap/hana/xs/dt/base/file/PATH?parts=meta

Orion-Version = 1.0

 

X-CSRF-Token: securityToken

SapBackPack: '{"MassTransfer":true, "Activate":true, "ChangeId": "ABC//11111", "ChangeIdList": [{"Path": "PATH/file1.txt", "ChangeId" = "ABC//12345"},  {"Path": "PATH/file2.txt", "ChangeId" = "ABC//12345"}]}'

Example Response


HTTP/1.1 200 OK

Content-Type: application/json

 

...