Difference between revisions of "Sugar Network/Resources"

From Sugar Labs
Jump to navigation Jump to search
 
(29 intermediate revisions by 2 users not shown)
Line 5: Line 5:
 
| [[File:Sugar-Network-diagram.png|200px|thumb|Sugar Network objects]]
 
| [[File:Sugar-Network-diagram.png|200px|thumb|Sugar Network objects]]
 
|}
 
|}
 +
 +
<div id="resource-types"></div>
 +
 +
'''Property types'''
 +
 +
Generally, Sugar Network objects' property types correspond to JSON types. The only exceptions mentioned in the following list:
 +
 +
* ''enum'', is an enumerated type when a value is a string from the predefined list of constants;
 +
* ''markdown'', is a string formatted in the [[Wikipedia:Markdown|Markdown]] syntax;
 +
* ''blob'', is a file represented by string value which is a [[Wikipedia:Sha1|SHA-1]] digest of file's content; the file itself can be obtained from the {{Code|'''GET''' /blobs/''DIGEST''}} request;
 +
* ''aggregated'', is a list of JSON objects which has [[Sugar_Network/API#Aggregated_properties|special API]] to treat its items; each aggregated item has a unique identifier; items might be created not only by the object's authors.
  
 
<div id="resource-author"></div>
 
<div id="resource-author"></div>
Line 10: Line 21:
 
'''Resource.author'''
 
'''Resource.author'''
  
−
A list of authors working on the corresponding resource. List items are dictionaries with the following keys:
+
A dictionary of authors working on the corresponding resource. Keys are Sugar Network ''User'' guids, or, if particular author is not registered in the Sugar Network, full user names. Values are dictionaries with the following keys:
  
−
* ''guid''<br>Author's guid in the Sugar Network; might be omitted if a particular author is not registered in the Sugar Network;
+
* ''name''<br>Full author's name;
 +
* ''role''<br>An integer which is a bit-wise ORed value of the following constants:
 +
** ''0x1'', author is registered in the Sugar Network (and ''guid'' key is set);
 +
** ''0x10000'', author is the original author of the corresponding resource; if it is not set, user is only a maintainer, e.g., an uploader of a book which has its original authors;
 +
* ''avatar''<br>An url to author's avatar.
  
−
* ''name''<br>Full author's name;
+
<div id="resource-status"></div>
 +
 
 +
'''Resource.status'''
  
−
* ''role''<br>An integer which is a bit-wise ORed value of the following constants:
+
This is a system level property which can be set only by node editors. It is a list of "badges" editors set depending on the object quality. Currently supported statuses are:
−
** ''1'', author is registered in the Sugar Network (and ''guid'' key is set);
 
−
** ''2'', author is the original author of the corresponding resource; if it is not set, user is only a maintainer, e.g., an uploader of a book which has its original authors.
 
  
−
<div id="resource-layer"></div>
+
* ''featured'', the object is popped up by node editors.
  
−
'''Resource.layer'''
+
<div id="resource-pins"></div>
  
−
: This is an attempt to generalize the idea of [http://groups.google.com/group/sugar-network/browse_thread/thread/4cad05ec801f364c user/resource levels] with the idea that objects should not be removed from the Network immediately (only hidden, and permanently removed by Network administrators). So, every resource is associated with a layer, i.e., it might be visible for observers only if they requested this layer and have permissions to see it.
+
'''Resource.pins'''
  
−
: For now, only the following list of layers is implemented, but the layer concept might be reused for [http://groups.google.com/group/sugar-network/msg/f5a1b4d78494a5d3 teachers related workflows] later:
+
This property makes sense only for objects provided from a [[Sugar_Network/API#Client_proxy|local proxy]]. The property is intended to store local user's preferences or statuses remote object has in local environment. Currently supported values are:
  
−
:* ''public'', object is visible for everyone;
+
* ''favorite'', set if a user has ''"stared"'' the object;
−
:* ''deleted'' Network objects' layer will be changed to {{Code|deleted}} after removing objects by users.
+
* ''checkin'', applied to Context objects only, set if a user has ''"pinned"'' the context to keep its most recent version permanently in the local system;
 +
* ''stale'', applied to Context objects only, set if previously checked-in Context might have more fresh releases on the node; it is not possible to filter Contexts by this value;
 +
* ''inprogress'', applied to Context objects only, set if the Context is in the process of downloading content from the node; it is being temporally set before launching the Context or checking it in; it is not possible to filter Contexts by this value.
  
 
<div id="context-type"></div>
 
<div id="context-type"></div>
Line 35: Line 52:
 
'''Context.type'''
 
'''Context.type'''
  
−
: Context types:
+
* ''activity'', Sugar application;
−
:* ''activity'', Sugar activity;
+
* ''book'', books in various forms;
−
:* ''book'', books in various forms;
+
* ''group'', a social group of related activities;
−
:* ''group'', offline discussion groups;
+
* ''talks'', sub-type to mix-in offline discussion forum;
−
:* ''package'', GNU/Linux package metadata.
+
* ''project'', sub-type to mix-in issue tracker and polling functionality.
−
 
 
−
<div id="implementation-license"></div>
 
−
 
 
−
'''Implementation.license'''
 
  
−
: Short license names. The licenses should conform with the [[Activity Library]] licensing [[Activity_Library/Editors/Policy/Licensing|policy]].
+
Context type specifies how context, and all related resources, can be used. For example, ''activity'' type assumes activity bundles uploaded to the ''Context.releases'' property, or, [[#post-type|Post.type]] depends on Context type it was created for.
  
−
<div id="implementation-stability"></div>
+
<div id="context-releases"></div>
  
−
'''Implementation.stability'''
+
'''Context.releases'''
  
−
: Stability level of the Implementation. Values conform to Sugar Network [[Sugar_Network/Recipe_Specification#Software_stability_levels|recipe specification]].
+
Contexts with ''activity'' or ''book'' types might have releases, i.e., activity or book versions that users can download. The ''releases'' property is aggregated where each item describes one particular version. There is no need in working with the ''releases'' property directly, there are high-level API commands to [[Sugar_Network/API#Upload_releases|upload]] and [[Sugar_Network/API#Retrieving_releases|download]] releases.
  
−
<div id="implementation-requires"></div>
+
<div id="post-type"></div>
  
−
'''Implementation.requires'''
+
'''Post.type'''
  
−
: A list of dependencies the ''Implementation'' requires to be installed in the system. The property is being auto populated from a [[Sugar_Network/Recipe_Specification#Dependencies|spec file]] from the uploaded ''Implementation'' bundle. This field exists only to simplify users driven queries, the real dependency checking bases on [[Sugar_Network/Recipe_Specification#Dependencies|spec files]].
+
Choose Post types according to Context [[#context-type|types]] the Post belongs to.
  
−
<div id="notification-type"></div>
+
* ''topic'', general purpose discussion; ''talks'' Contexts;
 +
* ''artefact'', object generated by Context application; ''activity'' Contexts;
 +
* ''issue'', problem with the Context; ''project'' Contexts;
 +
* ''poll'', a poll within the Context; ''project'' Contexts;
 +
* ''post'', a comment for a parent Post object; Context type independent.
  
−
'''Notification.type'''
+
<div id="post-topic"></div>
  
−
:* ''create'', object was created;
+
'''Post.topic'''
−
:* ''update'', object's properties were modified;
 
−
:* ''delete'', object was deleted (hidden);
 
−
:* ''vote'', object was voted/unvoted.
 
  
−
<div id="feedback-type"></div>
+
Only ''post'' type Post objects belong to a parent Post which guid should be specified in the ''topic'' property. The system design assumes only a two-level Posts hierarchy.
  
−
'''Feedback.type'''
+
<div id="post-topic"></div>
  
−
:* ''question''
+
'''Post.resolution'''
−
:* ''idea''
 
−
:* ''problem''
 
  
−
<div id="artifact-type"></div>
+
Post types ''issue'' and ''poll'' topics might have a resolution to expose the current status. The only way to change topic resolution is creating a dependent post with resolution property set.
  
−
'''Artifact.type'''
+
Resolutions for ''issue'' Post objects:
 +
* ''unconfirmed'', newly created issue;
 +
* ''new'', confirmed issue;
 +
* ''needinfo'', posted information about the issue is insufficient, more details needed;
 +
* ''resolved'', the issue is resolved, closed;
 +
* ''unrelated'', the issue does not related to the Context, closed;
 +
* ''obsolete'', the issue is already solved in recent Context releases, closed;
 +
* ''duplicate'', the issue is a duplicate, closed.
  
−
:* ''instance'', Sugar activity instance object.
+
Resolutions for ''poll'' Post objects:
 +
* ''open'', the poll is open for votes;
 +
* ''closed'', the poll is closed for votes.

Latest revision as of 01:59, 4 September 2014

The following diagram shows the full list of objects implemented by the Sugar Network API.

Sugar Network objects

Property types

Generally, Sugar Network objects' property types correspond to JSON types. The only exceptions mentioned in the following list:

  • enum, is an enumerated type when a value is a string from the predefined list of constants;
  • markdown, is a string formatted in the Markdown syntax;
  • blob, is a file represented by string value which is a SHA-1 digest of file's content; the file itself can be obtained from the GET /blobs/DIGEST request;
  • aggregated, is a list of JSON objects which has special API to treat its items; each aggregated item has a unique identifier; items might be created not only by the object's authors.

Resource.author

A dictionary of authors working on the corresponding resource. Keys are Sugar Network User guids, or, if particular author is not registered in the Sugar Network, full user names. Values are dictionaries with the following keys:

  • name
    Full author's name;
  • role
    An integer which is a bit-wise ORed value of the following constants:
    • 0x1, author is registered in the Sugar Network (and guid key is set);
    • 0x10000, author is the original author of the corresponding resource; if it is not set, user is only a maintainer, e.g., an uploader of a book which has its original authors;
  • avatar
    An url to author's avatar.

Resource.status

This is a system level property which can be set only by node editors. It is a list of "badges" editors set depending on the object quality. Currently supported statuses are:

  • featured, the object is popped up by node editors.

Resource.pins

This property makes sense only for objects provided from a local proxy. The property is intended to store local user's preferences or statuses remote object has in local environment. Currently supported values are:

  • favorite, set if a user has "stared" the object;
  • checkin, applied to Context objects only, set if a user has "pinned" the context to keep its most recent version permanently in the local system;
  • stale, applied to Context objects only, set if previously checked-in Context might have more fresh releases on the node; it is not possible to filter Contexts by this value;
  • inprogress, applied to Context objects only, set if the Context is in the process of downloading content from the node; it is being temporally set before launching the Context or checking it in; it is not possible to filter Contexts by this value.

Context.type

  • activity, Sugar application;
  • book, books in various forms;
  • group, a social group of related activities;
  • talks, sub-type to mix-in offline discussion forum;
  • project, sub-type to mix-in issue tracker and polling functionality.

Context type specifies how context, and all related resources, can be used. For example, activity type assumes activity bundles uploaded to the Context.releases property, or, Post.type depends on Context type it was created for.

Context.releases

Contexts with activity or book types might have releases, i.e., activity or book versions that users can download. The releases property is aggregated where each item describes one particular version. There is no need in working with the releases property directly, there are high-level API commands to upload and download releases.

Post.type

Choose Post types according to Context types the Post belongs to.

  • topic, general purpose discussion; talks Contexts;
  • artefact, object generated by Context application; activity Contexts;
  • issue, problem with the Context; project Contexts;
  • poll, a poll within the Context; project Contexts;
  • post, a comment for a parent Post object; Context type independent.

Post.topic

Only post type Post objects belong to a parent Post which guid should be specified in the topic property. The system design assumes only a two-level Posts hierarchy.

Post.resolution

Post types issue and poll topics might have a resolution to expose the current status. The only way to change topic resolution is creating a dependent post with resolution property set.

Resolutions for issue Post objects:

  • unconfirmed, newly created issue;
  • new, confirmed issue;
  • needinfo, posted information about the issue is insufficient, more details needed;
  • resolved, the issue is resolved, closed;
  • unrelated, the issue does not related to the Context, closed;
  • obsolete, the issue is already solved in recent Context releases, closed;
  • duplicate, the issue is a duplicate, closed.

Resolutions for poll Post objects:

  • open, the poll is open for votes;
  • closed, the poll is closed for votes.
Retrieved from "https://wiki.sugarlabs.org/index.php?title=Sugar_Network/Resources&oldid=93342"