forked from kbase/workspace_deluxe
-
Notifications
You must be signed in to change notification settings - Fork 1
/
workspace.spec
2152 lines (1825 loc) · 73.3 KB
/
workspace.spec
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
The Workspace Service (WSS) is primarily a language independent remote storage
and retrieval system for KBase typed objects (TO) defined with the KBase
Interface Description Language (KIDL). It has the following primary features:
- Immutable storage of TOs with
- user defined metadata
- data provenance
- Versioning of TOs
- Referencing from TO to TO
- Typechecking of all saved objects against a KIDL specification
- Collecting typed objects into a workspace
- Sharing workspaces with specific KBase users or the world
- Freezing and publishing workspaces
*/
module Workspace {
/* A boolean. 0 = false, other = true. */
typedef int boolean;
/* The unique, permanent numerical ID of a workspace. */
typedef int ws_id;
/* A string used as a name for a workspace.
Any string consisting of alphanumeric characters and "_", ".", or "-"
that is not an integer is acceptable. The name may optionally be
prefixed with the workspace owner's user name and a colon, e.g.
kbasetest:my_workspace.
*/
typedef string ws_name;
/* Represents the permissions a user or users have to a workspace:
'a' - administrator. All operations allowed.
'w' - read/write.
'r' - read.
'n' - no permissions.
*/
typedef string permission;
/* Login name of a KBase user account. */
typedef string username;
/*
A time in the format YYYY-MM-DDThh:mm:ssZ, where Z is either the
character Z (representing the UTC timezone) or the difference
in time to UTC in the format +/-HHMM, eg:
2012-12-17T23:24:06-0500 (EST time)
2013-04-03T08:56:32+0000 (UTC time)
2013-04-03T08:56:32Z (UTC time)
*/
typedef string timestamp;
/* A Unix epoch (the time since 00:00:00 1/1/1970 UTC) in milliseconds. */
typedef int epoch;
/* A type string.
Specifies the type and its version in a single string in the format
[module].[typename]-[major].[minor]:
module - a string. The module name of the typespec containing the type.
typename - a string. The name of the type as assigned by the typedef
statement.
major - an integer. The major version of the type. A change in the
major version implies the type has changed in a non-backwards
compatible way.
minor - an integer. The minor version of the type. A change in the
minor version implies that the type has changed in a way that is
backwards compatible with previous type definitions.
In many cases, the major and minor versions are optional, and if not
provided the most recent version will be used.
Example: MyModule.MyType-3.1
*/
typedef string type_string;
/* An id type (e.g. from a typespec @id annotation: @id [idtype]) */
typedef string id_type;
/* An id extracted from an object. */
typedef string extracted_id;
/* User provided metadata about an object.
Arbitrary key-value pairs provided by the user.
*/
typedef mapping<string, string> usermeta;
/* The lock status of a workspace.
One of 'unlocked', 'locked', or 'published'.
*/
typedef string lock_status;
/* A workspace identifier.
Select a workspace by one, and only one, of the numerical id or name.
ws_id id - the numerical ID of the workspace.
ws_name workspace - the name of the workspace.
*/
typedef structure {
ws_name workspace;
ws_id id;
} WorkspaceIdentity;
/* Meta data associated with a workspace. Provided for backwards
compatibility. To be replaced by workspace_info.
ws_name id - name of the workspace
username owner - name of the user who owns (who created) this workspace
timestamp moddate - date when the workspace was last modified
int objects - the approximate number of objects currently stored in
the workspace.
permission user_permission - permissions for the currently logged in
user for the workspace
permission global_permission - default permissions for the workspace
for all KBase users
ws_id num_id - numerical ID of the workspace
@deprecated Workspace.workspace_info
*/
typedef tuple<ws_name id, username owner, timestamp moddate,
int objects, permission user_permission, permission global_permission,
ws_id num_id> workspace_metadata;
/* Information about a workspace.
ws_id id - the numerical ID of the workspace.
ws_name workspace - name of the workspace.
username owner - name of the user who owns (e.g. created) this workspace.
timestamp moddate - date when the workspace was last modified.
int max_objid - the maximum object ID appearing in this workspace.
Since cloning a workspace preserves object IDs, this number may be
greater than the number of objects in a newly cloned workspace.
permission user_permission - permissions for the authenticated user of
this workspace.
permission globalread - whether this workspace is globally readable.
lock_status lockstat - the status of the workspace lock.
usermeta metadata - arbitrary user-supplied metadata about
the workspace.
*/
typedef tuple<ws_id id, ws_name workspace, username owner, timestamp moddate,
int max_objid, permission user_permission, permission globalread,
lock_status lockstat, usermeta metadata> workspace_info;
/* The unique, permanent numerical ID of an object. */
typedef int obj_id;
/* A string used as a name for an object.
Any string consisting of alphanumeric characters and the characters
|._- that is not an integer is acceptable.
*/
typedef string obj_name;
/* An object version.
The version of the object, starting at 1.
*/
typedef int obj_ver;
/* A string that uniquely identifies an object in the workspace service.
The format is [ws_name or id]/[obj_name or id]/[obj_ver].
For example, MyFirstWorkspace/MyFirstObject/3 would identify the third version
of an object called MyFirstObject in the workspace called
MyFirstWorkspace. 42/Panic/1 would identify the first version of
the object name Panic in workspace with id 42. Towel/1/6 would
identify the 6th version of the object with id 1 in the Towel
workspace.If the version number is omitted, the latest version of
the object is assumed.
*/
typedef string obj_ref;
/* An object identifier.
Select an object by either:
One, and only one, of the numerical id or name of the workspace.
ws_id wsid - the numerical ID of the workspace.
ws_name workspace - the name of the workspace.
AND
One, and only one, of the numerical id or name of the object.
obj_id objid- the numerical ID of the object.
obj_name name - name of the object.
OPTIONALLY
obj_ver ver - the version of the object.
OR an object reference string:
obj_ref ref - an object reference string.
*/
typedef structure {
ws_name workspace;
ws_id wsid;
obj_name name;
obj_id objid;
obj_ver ver;
obj_ref ref;
} ObjectIdentity;
/* A chain of objects with references to one another.
An object reference chain consists of a list of objects where the nth
object possesses a reference, either in the object itself or in the
object provenance, to the n+1th object.
*/
typedef list<ObjectIdentity> ref_chain;
/* A chain of objects with references to one another as a string.
A single string that is semantically identical to ref_chain above.
Represents a path from one workspace object to another through an
arbitrarily number of intermediate objects where each object has a
dependency or provenance reference to the next object. Each entry is
an obj_ref as defined earlier. Entries are separated by semicolons.
Whitespace is ignored.
Examples:
3/5/6; kbaseuser:myworkspace/myobject; 5/myobject/2
aworkspace/6
*/
typedef string ref_string;
/* A path into an object.
Identify a sub portion of an object by providing the path, delimited by
a slash (/), to that portion of the object. Thus the path may not have
slashes in the structure or mapping keys. Examples:
/foo/bar/3 - specifies the bar key of the foo mapping and the 3rd
entry of the array if bar maps to an array or the value mapped to
the string "3" if bar maps to a map.
/foo/bar/[*]/baz - specifies the baz field of all the objects in the
list mapped by the bar key in the map foo.
/foo/asterisk/baz - specifies the baz field of all the objects in the
values of the foo mapping. Swap 'asterisk' for * in the path.
In case you need to use '/' or '~' in path items use JSON Pointer
notation defined here: http://tools.ietf.org/html/rfc6901
*/
typedef string object_path;
/* DEPRECATED
An object subset identifier.
Select a subset of an object by:
EITHER
One, and only one, of the numerical id or name of the workspace.
ws_id wsid - the numerical ID of the workspace.
ws_name workspace - name of the workspace.
AND
One, and only one, of the numerical id or name of the object.
obj_id objid- the numerical ID of the object.
obj_name name - name of the object.
OPTIONALLY
obj_ver ver - the version of the object.
OR an object reference string:
obj_ref ref - an object reference string.
AND a subset specification:
list<object_path> included - the portions of the object to include
in the object subset.
boolean strict_maps - if true, throw an exception if the subset
specification traverses a non-existant map key (default false)
boolean strict_arrays - if true, throw an exception if the subset
specification exceeds the size of an array (default true)
@deprecated Workspace.ObjectSpecification
*/
typedef structure {
ws_name workspace;
ws_id wsid;
obj_name name;
obj_id objid;
obj_ver ver;
obj_ref ref;
list<object_path> included;
boolean strict_maps;
boolean strict_arrays;
} SubObjectIdentity;
/* An Object Specification (OS). Inherits from ObjectIdentity (OI).
Specifies which object, and which parts of that object, to retrieve
from the Workspace Service.
The fields wsid, workspace, objid, name, and ver are identical to
the OI fields.
The ref field's behavior is extended from OI. It maintains its
previous behavior, but now also can act as a reference string. See
reference following below for more information.
REFERENCE FOLLOWING:
Reference following guarantees that a user that has access to an
object can always see a) objects that are referenced inside the object
and b) objects that are referenced in the object's provenance. This
ensures that the user has visibility into the entire provenance of the
object and the object's object dependencies (e.g. references).
The user must have at least read access to the object specified in this
SO, but need not have access to any further objects in the reference
chain, and those objects may be deleted.
Optional reference following fields:
Note that only one of the following fields may be specified.
ref_chain obj_path - a path to the desired object from the object
specified in this OS. In other words, the object specified in this
OS is assumed to be accessible to the user, and the objects in
the object path represent a chain of references to the desired
object at the end of the object path. If the references are all
valid, the desired object will be returned.
- OR -
list<obj_ref> obj_ref_path - shorthand for the obj_path.
- OR -
ref_chain to_obj_path - identical to obj_path, except that the path
is TO the object specified in this OS, rather than from the object.
In other words the object specified by wsid/objid/ref etc. is the
end of the path, and to_obj_path is the rest of the path. The user
must have access to the first object in the to_obj_path.
- OR -
list<obj_ref> to_obj_ref_path - shorthand for the to_obj_path.
- OR -
ref_string ref - A string representing a reference path from
one object to another. Unlike the previous reference following
options, the ref_string represents the ENTIRE path from the source
object to the target object. As with the OI object, the ref field
may contain a single reference.
- OR -
boolean find_refence_path - This is the last, slowest, and most expensive resort
for getting a referenced object - do not use this method unless the
path to the object is unavailable by any other means. Setting the
find_refence_path parameter to true means that the workspace service will
search through the object reference graph from the object specified
in this OS to find an object that 1) the user can access, and 2)
has an unbroken reference path to the target object. If the search
succeeds, the object will be returned as normal. Note that the search
will automatically fail after a certain (but much larger than necessary
for the vast majority of cases) number of objects are traversed.
OBJECT SUBSETS:
When selecting a subset of an array in an object, the returned
array is compressed to the size of the subset, but the ordering of
the array is maintained. For example, if the array stored at the
'feature' key of a Genome object has 4000 entries, and the object paths
provided are:
/feature/7
/feature/3015
/feature/700
The returned feature array will be of length three and the entries will
consist, in order, of the 7th, 700th, and 3015th entries of the
original array.
Optional object subset fields:
list<object_path> included - the portions of the object to include
in the object subset.
boolean strict_maps - if true, throw an exception if the subset
specification traverses a non-existent map key (default false)
boolean strict_arrays - if true, throw an exception if the subset
specification exceeds the size of an array (default true)
*/
typedef structure {
ws_name workspace;
ws_id wsid;
obj_name name;
obj_id objid;
obj_ver ver;
ref_string ref;
ref_chain obj_path;
list<obj_ref> obj_ref_path;
ref_chain to_obj_path;
list<obj_ref> to_obj_ref_path;
boolean find_reference_path;
list<object_path> included;
boolean strict_maps;
boolean strict_arrays;
} ObjectSpecification;
/* Meta data associated with an object stored in a workspace. Provided for
backwards compatibility.
obj_name id - name of the object.
type_string type - type of the object.
timestamp moddate - date when the object was saved
obj_ver instance - the version of the object
string command - Deprecated. Always returns the empty string.
username lastmodifier - name of the user who last saved the object,
including copying the object
username owner - Deprecated. Same as lastmodifier.
ws_name workspace - name of the workspace in which the object is
stored
string ref - Deprecated. Always returns the empty string.
string chsum - the md5 checksum of the object.
usermeta metadata - arbitrary user-supplied metadata about
the object.
obj_id objid - the numerical id of the object.
@deprecated object_info
*/
typedef tuple<obj_name id, type_string type, timestamp moddate,
int instance, string command, username lastmodifier, username owner,
ws_name workspace, string ref, string chsum, usermeta metadata,
obj_id objid> object_metadata;
/* Information about an object, including user provided metadata.
obj_id objid - the numerical id of the object.
obj_name name - the name of the object.
type_string type - the type of the object.
timestamp save_date - the save date of the object.
obj_ver ver - the version of the object.
username saved_by - the user that saved or copied the object.
ws_id wsid - the workspace containing the object.
ws_name workspace - the workspace containing the object.
string chsum - the md5 checksum of the object.
int size - the size of the object in bytes.
usermeta meta - arbitrary user-supplied metadata about
the object.
*/
typedef tuple<obj_id objid, obj_name name, type_string type,
timestamp save_date, int version, username saved_by,
ws_id wsid, ws_name workspace, string chsum, int size, usermeta meta>
object_info;
/* Information about an object as a struct rather than a tuple.
This allows adding fields in a backward compatible way in the future.
Includes more fields than object_info.
obj_id objid - the numerical id of the object.
obj_name name - the name of the object.
type_string type - the type of the object.
timestamp save_date - the save date of the object.
obj_ver ver - the version of the object.
username saved_by - the user that saved or copied the object.
ws_id wsid - the workspace containing the object.
ws_name workspace - the workspace containing the object.
string chsum - the md5 checksum of the object.
int size - the size of the object in bytes.
usermeta meta - arbitrary user-supplied metadata about the object.
usermeta adminmeta - service administrator metadata set on an object. Unlike most
other object fields, admin metadata is mutable.
list<obj_ref> path - the path to the object.
*/
typedef structure {
obj_id objid;
obj_name name;
type_string type;
timestamp save_date;
int version;
username saved_by;
ws_id wsid;
ws_name workspace;
string chsum;
int size;
usermeta meta;
usermeta adminmeta;
list<obj_ref> path;
} ObjectInfo;
/* An external data unit. A piece of data from a source outside the
Workspace.
On input, only one of the resource_release_date or
resource_release_epoch may be supplied. Both are supplied on output.
All fields are optional, but at least one field must be present.
string resource_name - the name of the resource, for example JGI.
string resource_url - the url of the resource, for example
http://genome.jgi.doe.gov
string resource_version - version of the resource
timestamp resource_release_date - the release date of the resource
epoch resource_release_epoch - the release date of the resource
string data_url - the url of the data, for example
http://genome.jgi.doe.gov/pages/dynamicOrganismDownload.jsf?
organism=BlaspURHD0036
string data_id - the id of the data, for example
7625.2.79179.AGTTCC.adnq.fastq.gz
string description - a free text description of the data.
*/
typedef structure {
string resource_name;
string resource_url;
string resource_version;
timestamp resource_release_date;
epoch resource_release_epoch;
string data_url;
string data_id;
string description;
} ExternalDataUnit;
/* Information about a subaction that is invoked by a provenance action.
A provenance action (PA) may invoke subactions (SA), e.g. calling a
separate piece of code, a service, or a script. In most cases these
calls are the same from PA to PA and so do not need to be listed in
the provenance since providing information about the PA alone provides
reproducibility.
In some cases, however, SAs may change over time, such that invoking
the same PA with the same parameters may produce different results.
For example, if a PA calls a remote server, that server may be updated
between a PA invoked on day T and another PA invoked on day T+1.
The SubAction structure allows for specifying information about SAs
that may dynamically change from PA invocation to PA invocation.
All fields are optional but at least one field must be present.
string name - the name of the SA.
string ver - the version of SA.
string code_url - a url pointing to the SA's codebase.
string commit - a version control commit ID for the SA.
string endpoint_url - a url pointing to the access point for the SA -
a server url, for instance.
*/
typedef structure {
string name;
string ver;
string code_url;
string commit;
string endpoint_url;
} SubAction;
/* A provenance action.
A provenance action (PA) is an action taken while transforming one data
object to another. There may be several PAs taken in series. A PA is
typically running a script, running an api command, etc. All of the
following fields are optional, but more information provided equates to
better data provenance.
If a provenance action has no fields defined at all, it is silently dropped from
the list.
resolved_ws_objects should never be set by the user; it is set by the
workspace service when returning data.
On input, only one of the time or epoch may be supplied. Both are
supplied on output.
The maximum size of the entire provenance object, including all actions,
is 1MB.
timestamp time - the time the action was started
epoch epoch - the time the action was started.
string caller - the name or id of the invoker of this provenance
action. In most cases, this will be the same for all PAs.
string service - the name of the service that performed this action.
string service_ver - the version of the service that performed this action.
string method - the method of the service that performed this action.
list<UnspecifiedObject> method_params - the parameters of the method
that performed this action. If an object in the parameters is a
workspace object, also put the object reference in the
input_ws_object list.
string script - the name of the script that performed this action.
string script_ver - the version of the script that performed this action.
string script_command_line - the command line provided to the script
that performed this action. If workspace objects were provided in
the command line, also put the object reference in the
input_ws_object list.
list<ref_string> input_ws_objects - the workspace objects that
were used as input to this action; typically these will also be
present as parts of the method_params or the script_command_line
arguments. A reference path into the object graph may be supplied.
list<obj_ref> resolved_ws_objects - the workspace objects ids from
input_ws_objects resolved to permanent workspace object references
by the workspace service.
list<string> intermediate_incoming - if the previous action produced
output that 1) was not stored in a referrable way, and 2) is
used as input for this action, provide it with an arbitrary and
unique ID here, in the order of the input arguments to this action.
These IDs can be used in the method_params argument.
list<string> intermediate_outgoing - if this action produced output
that 1) was not stored in a referrable way, and 2) is
used as input for the next action, provide it with an arbitrary and
unique ID here, in the order of the output values from this action.
These IDs can be used in the intermediate_incoming argument in the
next action.
list<ExternalDataUnit> external_data - data external to the workspace
that was either imported to the workspace or used to create a
workspace object.
list<SubAction> subactions - the subactions taken as a part of this
action.
mapping<string, string> custom - user definable custom provenance
fields and their values.
string description - a free text description of this action.
*/
typedef structure {
timestamp time;
epoch epoch;
string caller;
string service;
string service_ver;
string method;
list<UnspecifiedObject> method_params;
string script;
string script_ver;
string script_command_line;
list<ref_string> input_ws_objects;
list<obj_ref> resolved_ws_objects;
list<string> intermediate_incoming;
list<string> intermediate_outgoing;
list<ExternalDataUnit> external_data;
list<SubAction> subactions;
mapping<string, string> custom;
string description;
} ProvenanceAction;
/*
Returns the version of the workspace service.
*/
funcdef ver() returns(string ver) authentication none;
/* Input parameters for the "create_workspace" function.
Required arguments:
ws_name workspace - name of the workspace to be created.
Optional arguments:
permission globalread - 'r' to set the new workspace globally readable,
default 'n'.
string description - A free-text description of the new workspace, 1000
characters max. Longer strings will be mercilessly and brutally
truncated.
usermeta meta - arbitrary user-supplied metadata for the workspace.
*/
typedef structure {
ws_name workspace;
permission globalread;
string description;
usermeta meta;
} CreateWorkspaceParams;
/*
Creates a new workspace.
*/
funcdef create_workspace(CreateWorkspaceParams params) returns
(workspace_info info) authentication required;
/* Input parameters for the "alter_workspace_metadata" function.
Required arguments:
WorkspaceIdentity wsi - the workspace to be altered
One or both of the following arguments are required:
usermeta new - metadata to assign to the workspace. Duplicate keys will
be overwritten.
list<string> remove - these keys will be removed from the workspace
metadata key/value pairs.
*/
typedef structure {
WorkspaceIdentity wsi;
usermeta new;
list<string> remove;
} AlterWorkspaceMetadataParams;
/*
Change the metadata associated with a workspace.
*/
funcdef alter_workspace_metadata(AlterWorkspaceMetadataParams params)
returns() authentication required;
/* Input parameters for the "clone_workspace" function.
Note that deleted objects are not cloned, although hidden objects are
and remain hidden in the new workspace.
Required arguments:
WorkspaceIdentity wsi - the workspace to be cloned.
ws_name workspace - name of the workspace to be cloned into. This must
be a non-existant workspace name.
Optional arguments:
permission globalread - 'r' to set the new workspace globally readable,
default 'n'.
string description - A free-text description of the new workspace, 1000
characters max. Longer strings will be mercilessly and brutally
truncated.
usermeta meta - arbitrary user-supplied metadata for the workspace.
list<ObjectIdentity> exclude - exclude the specified objects from the
cloned workspace. Either an object ID or a object name must be
specified in each ObjectIdentity - any supplied reference strings,
workspace names or IDs, and versions are ignored.
*/
typedef structure {
WorkspaceIdentity wsi;
ws_name workspace;
permission globalread;
string description;
usermeta meta;
list<ObjectIdentity> exclude;
} CloneWorkspaceParams;
/*
Clones a workspace.
*/
funcdef clone_workspace(CloneWorkspaceParams params) returns
(workspace_info info) authentication required;
/* Lock a workspace, preventing further changes.
WARNING: Locking a workspace is permanent. A workspace, once locked,
cannot be unlocked.
The only changes allowed for a locked workspace are changing user
based permissions or making a private workspace globally readable,
thus permanently publishing the workspace. A locked, globally readable
workspace cannot be made private.
*/
funcdef lock_workspace(WorkspaceIdentity wsi) returns(workspace_info info)
authentication required;
/* DEPRECATED
Input parameters for the "get_workspacemeta" function. Provided for
backwards compatibility.
One, and only one of:
ws_name workspace - name of the workspace.
ws_id id - the numerical ID of the workspace.
Optional arguments:
string auth - the authentication token of the KBase account accessing
the workspace. Overrides the client provided authorization
credentials if they exist.
@deprecated Workspace.WorkspaceIdentity
*/
typedef structure {
ws_name workspace;
ws_id id;
string auth;
} get_workspacemeta_params;
/*
Retrieves the metadata associated with the specified workspace.
Provided for backwards compatibility.
@deprecated Workspace.get_workspace_info
*/
funcdef get_workspacemeta(get_workspacemeta_params params)
returns(workspace_metadata metadata) authentication optional;
/*
Get information associated with a workspace.
*/
funcdef get_workspace_info(WorkspaceIdentity wsi)
returns (workspace_info info) authentication optional;
/*
Get a workspace's description.
*/
funcdef get_workspace_description(WorkspaceIdentity wsi)
returns (string description) authentication optional;
/* Input parameters for the "set_permissions" function.
One, and only one, of the following is required:
ws_id id - the numerical ID of the workspace.
ws_name workspace - the name of the workspace.
Required arguments:
permission new_permission - the permission to assign to the users.
list<username> users - the users whose permissions will be altered.
*/
typedef structure {
ws_name workspace;
ws_id id;
permission new_permission;
list<username> users;
} SetPermissionsParams;
/*
Set permissions for a workspace.
*/
funcdef set_permissions(SetPermissionsParams params) returns()
authentication required;
/* Input parameters for the "set_global_permission" function.
One, and only one, of the following is required:
ws_id id - the numerical ID of the workspace.
ws_name workspace - the name of the workspace.
Required arguments:
permission new_permission - the permission to assign to all users,
either 'n' or 'r'. 'r' means that all users will be able to read
the workspace; otherwise users must have specific permission to
access the workspace.
*/
typedef structure {
ws_name workspace;
ws_id id;
permission new_permission;
} SetGlobalPermissionsParams;
/*
Set the global permission for a workspace.
*/
funcdef set_global_permission(SetGlobalPermissionsParams params) returns()
authentication required;
/* Input parameters for the "set_workspace_description" function.
One, and only one, of the following is required:
ws_id id - the numerical ID of the workspace.
ws_name workspace - the name of the workspace.
Optional arguments:
string description - A free-text description of the workspace, 1000
characters max. Longer strings will be mercilessly and brutally
truncated. If omitted, the description is set to null.
*/
typedef structure {
ws_name workspace;
ws_id id;
string description;
} SetWorkspaceDescriptionParams;
/*
Set the description for a workspace.
*/
funcdef set_workspace_description(SetWorkspaceDescriptionParams params)
returns() authentication required;
/* Input parameters for the "get_permissions_mass" function.
workspaces - the workspaces for which to return the permissions,
maximum 1000.
*/
typedef structure {
list<WorkspaceIdentity> workspaces;
} GetPermissionsMassParams;
/* A set of workspace permissions.
perms - the list of permissions for each requested workspace
*/
typedef structure {
list<mapping<username, permission>> perms;
} WorkspacePermissions;
/*
Get permissions for multiple workspaces.
*/
funcdef get_permissions_mass(GetPermissionsMassParams mass)
returns(WorkspacePermissions perms) authentication optional;
/*
Get permissions for a workspace.
@deprecated get_permissions_mass
*/
funcdef get_permissions(WorkspaceIdentity wsi) returns
(mapping<username, permission> perms) authentication optional;
/* Input parameters for the "save_object" function. Provided for backwards
compatibility.
Required arguments:
type_string type - type of the object to be saved
ws_name workspace - name of the workspace where the object is to be
saved
obj_name id - name behind which the object will be saved in the
workspace
UnspecifiedObject data - data to be saved in the workspace
Optional arguments:
usermeta metadata - arbitrary user-supplied metadata for the object,
not to exceed 16kb; if the object type specifies automatic
metadata extraction with the 'meta ws' annotation, and your
metadata name conflicts, then your metadata will be silently
overwritten.
string auth - the authentication token of the KBase account accessing
the workspace. Overrides the client provided authorization
credentials if they exist.
@deprecated
*/
typedef structure {
obj_name id;
type_string type;
UnspecifiedObject data;
ws_name workspace;
mapping<string,string> metadata;
string auth;
} save_object_params;
/*
Saves the input object data and metadata into the selected workspace,
returning the object_metadata of the saved object. Provided
for backwards compatibility.
@deprecated Workspace.save_objects
*/
funcdef save_object(save_object_params params)
returns(object_metadata metadata) authentication optional;
/* An object and associated data required for saving.
Required arguments:
type_string type - the type of the object. Omit the version information
to use the latest version.
UnspecifiedObject data - the object data.
One, and only one, of:
obj_name name - the name of the object.
obj_id objid - the id of the object to save over.
Optional arguments:
usermeta meta - arbitrary user-supplied metadata for the object,
not to exceed 16kb; if the object type specifies automatic
metadata extraction with the 'meta ws' annotation, and your
metadata name conflicts, then your metadata will be silently
overwritten.
list<ProvenanceAction> provenance - provenance data for the object.
boolean hidden - true if this object should not be listed when listing
workspace objects.
*/
typedef structure {
type_string type;
UnspecifiedObject data;
obj_name name;
obj_id objid;
usermeta meta;
list<ProvenanceAction> provenance;
boolean hidden;
} ObjectSaveData;
/* Input parameters for the "save_objects" function.
One, and only one, of the following is required:
ws_id id - the numerical ID of the workspace.
ws_name workspace - the name of the workspace.
Required arguments:
list<ObjectSaveData> objects - the objects to save.
*/
typedef structure {
ws_name workspace;
ws_id id;
list<ObjectSaveData> objects;
} SaveObjectsParams;
/*
Save objects to the workspace. Saving over a deleted object undeletes
it.
*/
funcdef save_objects(SaveObjectsParams params)
returns (list<object_info> info) authentication required;
/* Input parameters for the "get_object" function. Provided for backwards
compatibility.
Required arguments:
ws_name workspace - Name of the workspace containing the object to be
retrieved
obj_name id - Name of the object to be retrieved
Optional arguments:
int instance - Version of the object to be retrieved, enabling
retrieval of any previous version of an object
string auth - the authentication token of the KBase account accessing
the object. Overrides the client provided authorization
credentials if they exist.
@deprecated Workspace.ObjectIdentity
*/
typedef structure {
obj_name id;
ws_name workspace;
int instance;
string auth;
} get_object_params;
/* Output generated by the "get_object" function. Provided for backwards
compatibility.
UnspecifiedObject data - The object's data.
object_metadata metadata - Metadata for object retrieved/
@deprecated Workspaces.ObjectData
*/
typedef structure {
UnspecifiedObject data;
object_metadata metadata;
} get_object_output;
/*
Retrieves the specified object from the specified workspace.
Both the object data and metadata are returned.
Provided for backwards compatibility.
@deprecated Workspace.get_objects
*/
funcdef get_object(get_object_params params)
returns (get_object_output output) authentication optional;
/* DEPRECATED