This communication procedure takes place if a participant wants to get resource data directly from another participant. Normally all participants communicate only with the ECS and not face to face to each other. For example this could be necessary if you’re sharing a central ECS with other organizations and you are not allowed to give away sensible data out of the control of your organization. Of course therefore the communicating participants have to be in the controlling area of your organization.

Assuming following situation: A Proxy (first participant) wants to send course data to a LMS (second participant). This message holds sensible data, which doesn’t have to leave the controlling area of the organization by law. Both participants were controlled by the organization.

This procedure guarantiee that the appropriate course data will remain on the proxy until the LMS has successfully fetched the data.

              +----------+
              |auths:ECS +----------------------------------+
              +----+-----+   <--                            |
                   |         2.3.1:auth2:=delete(auth.hash) |
                   |                                        |
                   | ^                                      |
                   | | 2.2:auth:=post()                     |
                   |                                        |
                   |   2.3:coursedata:=get(auth.hash)       |
                   |    --->                                |
               +---+--+                    +----------------+--+
               | :LMS +--------------------+ 746354389534:Proxy|
               ++----++                    +----------------+--+
                |    |                                      |
 2:ev:=post() | |    | | 2.1:coursedata_url:=get()          |
              v |    | v                                    |
                |    |                                      |
                |    | | 2.4:delete()                       |
                |    | v                                    |
                |    |                                      |
 +--------------++   |                                      |
 |events/fifo:ECS|   |<<local>>                             |
 +--------------++  ++-------------------+                  |
                |   | cc/courses/345:ECS |                  |
                |   +--------------------+                  |
                |                                           |
                |                                           |
              ^ |                                           |
3:ev2:=post() | |                                           |
                |                                           |
                |      +--------+                           |
                +------+ :Proxy +---------------------------+
                       +--------+     --->
                            |         3.1:delete()
                            |
                            | | 1:create()
                            | v
                            |
                    +-------+------+
                    |cc/courses:ECS|
                    +--------------+

    +-----+
    |     | | 1.1:make_new_create_event(cc/courses/345)
+---++    | v
|:ECS|    |
+---++    | | 2.5[IF no more participant references]:
    |     | v    make_new_no-more-reference_event(cc/courses/345)
    |     |
    +-----+

These are unique ids in the scope of an ECS. They establish a relationship between a participant and a community:

+--------------+ 1        N +-------------+ N        1 +-------------+
| participants +------------+ memberships +------------+ communities |
|    (pid)     |            |    (mid)    |            |    (cid)    |
+--------------+            +-------------+            +-------------+

Therefore a participant can be associated to different communities. Every participant can inquire his membership ids by calling the memberships resource.

A community can be referenced by his community id (cid) or his community name. If you address a community you implicit address all members of the community. This applies also to the sender joining the receiver community if the sender has set his community_selfrouting flag (default off), otherwise the sender will be implicitly excluded from the receiver list. Every participant can inquire his communities memberships by calling the memberships resource.

If you want to POST to a resource you have to provide either a X-EcsReceiverMemberships or X-EcsReceiverCommunities header or both together.

If you want to address a single membership or a dedicated number of memberships you have to set the X-EcsReceiverMemberships header. This header can have a list of values, e.g.

X-EcsReceiverMemberships: 3,6,47

If you want to address a community you have to set the X-EcsReceiverCommunities header. This header can have a list of values, e.g.

X-EcsReceiverCommunities: SWS,23,25

If you GET a resource then the ECS set the X-EcsSender and the X-EcsReceiverCommunities header to show you from whom and where your received message comes. If there is a list of X-EcsReceiverCommunities values than there is also a list of corresponding X-EcsSender values, i.e. the sending participant is member of multiple communities and addressed his message to multiple communities also, e.g.

X-EcsSender: 3,19
X-EcsReceiverCommunities: UnisBW,SUV

This means that this message is addressed to you through two communities (UnisBW, SUV) and the sender has the membership id 3 in UnisBW and 19 in SUV.

Provides a general queue which accumulates the resource tasks: creation, deletion and renewal. Available representations are application/json and application/xml. It’s recommended to use the events queue to supervise all your possible application specific resources. Further you only have to poll the events queue in order to supervise all your application specific resources and this further take down system load.

Remark: If you wisely decide to use the events queue to supervise your application specific resources you have to manage the validity of events queue yourself, i.e. you shouldn’t additionally poll your application specific resources directly, because then you will get stale events in the events queue.

Following a sample representation in JSON:

[
  {
    "status": "created",
    "ressource": "numlab/exercises/7"
  },
  {
    "status": "destroyed",
    "ressource": "numlab/exercises/3"
  }
]

Provides information of the affiliation of the calling participant to the available communities. Available representations are application/json and application/xml.

With the itsyou key the caller of the /sys/memberships resource will be informed which participant in the different communities is assigned to him.

Following a sample representation in JSON:

[
  {
    "community": {
      "name": "cc_courselinks",
      "description": "CampusConnect courselinks."
    },
    "participants": [
      {
        "name": "ILIAS-ECS Client 1",
        "itsyou": true,
        "org": {
          "name": "Leifos",
          "abbr": "LEI"
        },
        "mid": 1,
        "pid": 1,
        "description": "Development participant.",
        "dns": "n/a",
        "email": "meyer@leifos.com"
      },
      {
        "name": "FreeIT.de Testparticipant",
        "itsyou": false,
        "org": {
          "name": "FreeIT Softwaredevelopment.",
          "abbr": "FreeIT"
        },
        "mid": 2,
        "pid": 4,
        "description": "A general test participant.",
        "dns": "n/a",
        "email": "Heiko.Bernloehr@FreeIT.de"
      },
      {
        "name": "ILIAS-ECS Client 2",
        "itsyou": false,
        "org": {
          "name": "Leifos",
          "abbr": "LEI"
        },
        "mid": 3,
        "pid": 7,
        "description": "",
        "dns": "n/a",
        "email": "meyer@leifos.com"
      }
    ]
  }
]

This means authorization through one touch tokens. Provides a mechanism to grant each participant authorization to consume services from any service-providing-participant in an ECS network.

The interface is the same as for application specific resources. If you want to create an authorization token, you have to provide at least a realm (authorization context) or a url (authorization context, DEPRECATED):

curl ... -X POST -d '{"realm":"authorization context string"}' https://.../sys/auths

and you will get back something like this:

{
  "hash": "5a944e72346e6e3102d32ccfecc18862d23e1dc0",
  "sov": "2011-03-08T23:25:27+01:00",
  "eov": "2011-03-08T23:26:27+01:00",
  "url": "authorization context string",
  "realm": "authorization context string",
  "abbr": "LEI",
  "pid": 35
}

You’re allowed to set the sov and/or eov to determine the validity period of the authorization token. If you do not, the validity period is set to one minute starting at current time.

The recommended way to fetch an authorization token when knowing the one touch hash:

curl .... -X DELETE https://.../sys/auths/<one touch hash>

This will return the auths representation (same structure/form as when creating; see above) and delete it server side. If the authorization token is outtimed, i.e. the current time is not between sov and eov, you will get back a return code 409 (conflict) and following descriptional text in the body: Authorization token outtimed.

/<projectnamespace>/<name>
/<projectnamespace>/<name>/details
/<projectnamespace>/<name>/<id>
/<projectnamespace>/<name>/<id>/receivers
/<projectnamespace>/<name>/<id>/details
/<projectnamespace>/<name>/fifo
/<projectnamespace>/<name>/lifo

A message resource receives/saves messages for each participant. The participant can fetch (GET) his messages from the resource. A message resource could hold its messages enduringly (see Section 3.8.5, “Postrouting”), so new participants joining a community after a message has been sent to this community will also receive it.

Resource structure: /<projectnamespace>/<name>/<id>

{
  "receivers": [
    {
      "itsyou": false,
      "mid": 1,
      "cid": 2
      "pid": 19,
    },
    {
      "itsyou": false,
      "mid": 4,
      "cid": 3
      "pid": 29,
    }
  ],
  "senders": [
    {
      "mid": 5
    },
    {
      "mid": 7
    }
  ],
  "url": "courselinks/10",
  "content_type": "application/json"
  "owner": {
    "pid": 3,
    "itsyou": true
  }
}

Resource structure: /<projectnamespace>/<name>

[
  {
    "senders": [ ],
    "receivers": [ ],
    "url": "courselinks/35",
    "content_type": "text/plain",
    "owner": {
      "pid": 3,
      "itsyou": true
    }
  },
  {
    "senders": [
      {
        "mid": 2
      }
    ],
    "receivers": [
      {
        "mid": 19,
        "cid": 2,
        "pid": 19,
        "itsyou": false
      }
    ],
    "url": "courselinks/36",
    "content_type": "text/plain",
    "owner": {
      "pid": 3,
      "itsyou": true
    }
  },
  {
    "senders": [
      {
        "mid": 2
      }
    ],
    "receivers": [
      {
        "mid": 19,
        "cid": 2,
        "pid": 19,
        "itsyou": false
      }
    ],
    "url": "courselinks/37",
    "content_type": "text/plain",
    "owner": {
      "pid": 3,
      "itsyou": true
    }
  }
]

curl .... -X GET https://server/<namespace>/<name>?all=true

The queue resource is modelled as a subresource of a list resource and it can operate either in lifo (last in first out) or fifo (first in first out) mode.

Resource structure: /<projectnamespace>/<name>/fifo or /<projectnamespace>/<name>/lifo

If a resource has set its postroute flag, then all new participants will get postrouted this resource e.g. if you have posted some messages to a community named testcommunity and later joins a new participant to this community, he will get postrouted the former posted messages.

First lets show the topology of a clustered ECS network:

+---------+  +---------+  +---------+
| Partic. |  | Partic. |  | Partic. |
|    A    |  |    B    |  |    C    |
+----+----+  +----+----+  +----+----+
     |            |            |
     |            |            |
+----+------------+------------+----+
|                ECS                |
+-----------------+-----------------+
                  |
                  |
+-----------------+-----------------+
| virtueller Participant (Cluster)  |
+--------+--------+--------+--------+
| Cluster| Cluster| Cluster| Cluster|
| Partic.| Partic.| Partic.| Partic.|
|    1   |    2   |   3    |   n    |
+--------+--------+--------+--------+

In order to explicitely communicate with a cluster participant we have to use a broadcasting mechanism. Every resource could be used as a broadcasting resource. It only depends on how the cluster participants access this resource. They have to do it like this: