S-RAMP Guide

The OASIS S-RAMP (SOA Repository Artifact Model and Protocol) specification is intended to provide a common data model and protocol for interacting with a repository of (primarily) SOA artifacts. The goal of the specification is to foster interoperability between repository implementations by standardizing on a data model and API.

This guide will discuss both the OASIS standard and the Overlord open source implementation.

The S-RAMP specification includes a foundation document and an Atom based protocol binding document. The foundation document describes core concepts and will be the focus of the first part of this guide. The Atom binding document describes an Atom based API that implementations should provide.

An S-RAMP repository primarily stores artifacts. An artifact is comprised of the following meta-data:

Relationships

All artifacts in S-RAMP contain a set of core properties such as name, description, creation date, etc. Many of these properties are automatically set by the server when the artifact is added and/or updated. Others, such as description, can be set by clients.

However, most importantly every artifact has an Artifact Model and an Artifact Type. These two properties determine what kind of artifact it is (more on artifact types later, in the Data Models section of this Guide).

Additionally, some artifact types contain additional core properties. For example, the Document artifact type includes additional core properties of contentType and contentSize, while the XsdDocument artifact type includes the targetNamespace property.

An artifact may have additional properties set on it by clients. These custom properties are simply arbitrary name/value pairs. The only restriction is that a custom property may not have the same name as a Core Property.

Another type of meta-data found on S-RAMP artifacts are classifiers. Classifiers are a lot like keywords or tags except that they are hierarchical. Every artifact has a collection of classifiers configured by the client, where each classifier must be a node in an ontology previously uploaded to the repository (presumably by an admin).

An ontology is simply a hierarchy of tags (defined as a subset of the OWL Lite format). This approach allows the repository to be configured with a pre-defined set of hierarchical tags (classifiers) that can be associated with an artifact.

An example is helpful in this case. First, a repository administrator would define and upload an ontology:

World
  |-> North America
     |-> United States
         |-> Alabama
         |-> Alaska
     |-> Mexico
     |-> Canada
  |-> South America
  |-> Australia

Once this ontology has been added to the repository, then clients can add, for example, #Alaska or #Canada as classifiers on artifacts. This provides a way to "tag" artifacts in interesting and meaningful ways, and provides a useful means of querying (more on that later).

For more information about ontologies and classifiers, have a look at Section 3 of the S-RAMP Foundation document.

The final bit of meta-data that can be found on an artifact are relationships An S-RAMP relationship is a uni-directional link between a source artifact and a target artifact. Artifacts can have arbitrary, client-defined relationships. Every relationship has a name and a target artifact. For example, a client might define a relationship named "documentedBy" between a wsdl artifact and a text or PDF artifact, indicating that the latter provides documentation for the former.

The S-RAMP application is written in Java. To get started make sure your system has the following:

You can click on Browse Artifacts and see a list of files related to the S-RAMP default workflows. Alternatively you can fire up the s-ramp shell in the bin directory of the distribution:

./s-ramp.sh
**********************************************************************
           _____       ______  ___ ___  ________
          /  ___|      | ___ \/ _ \|  \/  | ___ \
          \ `--. ______| |_/ / /_\ \ .  . | |_/ /
           `--. \______|    /|  _  | |\/| |  __/
          /\__/ /      | |\ \| | | | |  | | |
          \____/       \_| \_\_| |_|_|  |_|_|

  JBoss S-RAMP Kurt Stam and Eric Wittmann, Licensed under the
  Apache License, V2.0, Copyright 2012
**********************************************************************
s-ramp>

To connect the shell to the server type connect and hit the tab key. It should auto-complete to say s-ramp:connect http://localhost:8080/s-ramp-server and when hitting the return key the cursor should go from red to green. To browse the artifacts in the repository run the following query:

s-ramp> s-ramp:query /s-ramp
Querying the S-RAMP repository:
	/s-ramp
Atom Feed (9 entries)
  Idx                    Type Name
  ---                    ---- ----
    1           ImageDocument user-properties.png
    2                Document overlord.demo.CheckDeployment-taskform.flt
    3         BrmsPkgDocument SRAMPPackage.pkg
    4           ImageDocument overlord.demo.SimpleReleaseProcess-image.png
    5           ImageDocument run-build-install.png
    6                Document overlord.demo.SimpleReleaseProcess-taskform.flt
    7           ImageDocument audio-input-microphone-3.png
    8            BpmnDocument overlord.demo.SimpleReleaseProcess.bpmn
    9            TextDocument HttpClientWorkDefinitions.wid

In later chapters will go into more detail, but if this all worked you can be sure that your installation is in good working order.

The S-RAMP core model defines some basic artifact types including Document and XmlDocument. These basic types allow clients to add simple files to the repository as artifacts.

The XSD model defines a single document style artifact, XsdDocument, and a number of derived artifact types. When an XSD document is added to the repository, the server will additionally "index" the artifact by automatically creating a number of derived artifacts of the following types from the XSD content.

The WSDL model defines a single document style artifact, WsdlDocument, and a number of derived artifact types. Similarly to the XsdDocument type, when a WSDL dcument is added to the repository, the server will automatically derive additional artifacts (listed below) from the content of the WSDL file.

For further details about the WSDL Model, please see the S-RAMP specification’s foundation document, section 2.4.2.

This data model is present to represent the primary components of a WS-Policy document.

The SOA model exists to provide a link to the work done by the Open Group SOA Ontology group. All of the artifacts in this model are non-document artifacts which are directly instantiated by clients.

The Service Implementation model adds SOA service implementation artifact types underneath the (already mentioned) SOA Data Model.

Clients can define their own (implicit) data models by using the "ext" model space defined by the S-RAMP specification. This allows clients to add documents with custom artifact types. For example, a client can add an artifact to /s-ramp/ext/PdfDocument. This provides a way for clients to define their own data models with their own properties and relationships. Note however that the server will not have a definition of the model - it is up to the client to properly conform to their own implicit model. Custom properties and user-defined relationships allow clients to richly define their own models.

As an example, a client might define the following Data Model for a J2EE web application domain:

The S-RAMP specification does not dictate the format of the Atom REST endpoints. Instead, the client is expected to query a service document endpoint and inspect it to find the various relevant endpoints. The specification does present a notional format, but implementations are not required to follow it. This Guide will give examples based on this notional format. But it bears repeating that for any given server implementation, a client should first query the Atom service document at the following endpoint:

GET /s-ramp/servicedocument

The resulting service document will contain a set of workspaces representing the artifact collections supported by the server, along with endpoints indicating how to manipulate them.

However, the Atom Binding document does outline the inputs, outputs, and REST verbs that must be used for each of the supported operations. In general, the Atom API data models are used to wrap custom S-RAMP specific XML structures. Atom Entry documents are used when dealing with individual artifacts, while Atom Feed documents are used when dealing with lists of documents.

There are two basic types of artifacts from the protocol standpoint: document style artifacts (those artifacts that are based on files/binary content) and logical (direct instantiation) artifacts. In the case of a document-style artifact, the client must POST the binary content to the correct Atom Endpoint. In the case of a direct artifact (no document content) the client must POST an Atom Entry containing an S-RAMP artifact XML entity to the appropriate endpoint. The server will respond with an Atom Entry containing the full meta data of the newly created artifact (if successful).

Notional REST Endpoint

POST /s-ramp/{model}/{type}

A client can update the meta data (properties, classifiers, relationships) by performing a PUT request to the artifact’s endpoint. The artifact’s endpoint can be found either by querying for the artifact or as part of the returned Atom Entry returned when the artifact was created.

Notional REST Endpoint

PUT /s-ramp/{model}/{type}/{uuid}

Not surprisingly, an artifact can be deleted by a client by performing a DELETE request to the artifact’s endpoint.

Notional REST Endpoint

DELETE /s-ramp/{model}/{type}/{uuid}

Performing an S-RAMP query is a matter of issueing a GET or POST to the S-RAMP query endpoint. In addition, full feeds are available for all Artifact Models and Artifact Types. In both cases, the response is an Atom Feed where each Entry provides summary information about an artifact in the respository. To retrieve full details about a given entry in the feed (custom properties, classifiers, relationships), the client must issue an additional GET. Only a subset of the core properties, such as name and description, are mapped to the Atom Entry in a feed.

In order to retrieve the full meta data for an artifact, the client must issue a GET request to the appropriate artifact endpoint. This is necessary after a query or feed, when only the summary information is available. The summary information found in a feed or query response contains the UUID of the artifact, as well as a URL to the endpoint needed to retrieve the full artifact details.

Notional REST Endpoint

GET /s-ramp/{model}/{type}/{uuid}

A powerful additional feature of the S-RAMP API is the batch processing function. The batch processing endpoint allows the client to POST an S-RAMP package, which can contain multiple Atom Entries and binary files. The package allows a client to add, update, and delete multiple artifacts in a single batch. The format of an S-RAMP package archive is described further in the S-RAMP Atom Binding document (Section 2.3.5.2.2.1 - no I’m not kidding, that’s really the section).

TBD

TBD

TBD

  /s-ramp/servicedocument

Retrieves the service document.

The service document contains a workspace for each of the S-RAMP data models supported by the server.

Example Response

HTTP/1.1 200 OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<app:service xmlns:atom="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app">
    <app:workspace>
        <atom:title>Core Model</atom:title>
        <app:collection href="http://example.org/s-ramp/core">
            <atom:title>Core Model Objects</atom:title>
            <app:accept>application/zip</app:accept>
            <app:categories fixed="yes">
                <atom:category label="Document" scheme="urn:x-s-ramp:v1:type" term="Document"/>
                <atom:category label="XML Document" scheme="urn:x-s-ramp:v1:type" term="XmlDocument"/>
            </app:categories>
        </app:collection>
        <app:collection href="http://example.org/s-ramp/core/Document">
            <atom:title>Documents</atom:title>
            <app:accept>application/octet-stream</app:accept>
            <app:categories fixed="yes">
                <atom:category label="Document" scheme="urn:x-s-ramp:v1:type" term="Document"/>
            </app:categories>
        </app:collection>
        <app:collection href="http://example.org/s-ramp/core/XmlDocument">
            <atom:title>XML Documents</atom:title>
            <app:accept>application/xml</app:accept>
            <app:categories fixed="yes">
                <atom:category label="XML Document" scheme="urn:x-s-ramp:v1:type" term="XmlDocument"/>
            </app:categories>
        </app:collection>
    </app:workspace>
</app:service>

Publishes a new artifact into the repository.

There are three ways this endpoint can be invoked, depending on the type of artifact being published:

  /s-ramp/{model}/{type}/{uuid}

Updates an artifact’s meta data.

This endpoint is used to update a single artifact’s meta data, including core properties, custom properties, classifiers, and relationships. Typically the client should first retrieve the artifact (e.g. by invoking the Get Artifact endpoint), make changes to the artifact, then issue a PUT request to the Update Artifact endpoint.

Example Request

PUT /s-ramp/core/Document/098da465-2eae-49b7-8857-eb447f03ac02 HTTP/1.1

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<atom:entry xmlns:s-ramp="http://docs.oasis-open.org/s-ramp/ns/s-ramp-v1.0" xmlns:xlink="http://www.w3.org/1999/xlink"
  xmlns:atom="http://www.w3.org/2005/Atom">
  <atom:title>pom.xml</atom:title>
  <atom:updated>2013-05-15T08:12:01.985-04:00</atom:updated>
  <atom:id>098da465-2eae-49b7-8857-eb447f03ac02</atom:id>
  <atom:published>2013-05-15T08:12:01.985-04:00</atom:published>
  <atom:author>
    <atom:name>ewittman</atom:name>
  </atom:author>
  <atom:summary>Sample description of my document.</atom:summary>
  <s-ramp:artifact>
    <s-ramp:Document contentType="text/plain" contentSize="4748" artifactType="Document"
      name="myfile.txt" description="Sample description of my document." createdBy="ewittman"
      uuid="098da465-2eae-49b7-8857-eb447f03ac02" createdTimestamp="2013-05-15T08:12:01.985-04:00"
      lastModifiedTimestamp="2013-05-15T08:12:01.985-04:00" lastModifiedBy="ewittman">
      <s-ramp:property>
        <s-ramp:propertyName>foo</s-ramp:propertyName>
        <s-ramp:propertyValue>bar</s-ramp:propertyValue>
      </s-ramp:property>
    </s-ramp:Document>
  </s-ramp:artifact>
</atom:entry>

To connect the shell to the server type connect and hit the tab key. It should auto-complete to say s-ramp:connect http://localhost:8080/s-ramp-server and when hitting the return key the cursor should go from red to green. Of course you will need to update the server and port information if your S-RAMP repository runs elsewhere.

To browse the artifacts in the repository run the following query:

s-ramp> s-ramp:query /s-ramp
Querying the S-RAMP repository:
    /s-ramp
Atom Feed (9 entries)
  Idx                    Type Name
  ---                    ---- ----
    1           ImageDocument user-properties.png
    2                Document overlord.demo.CheckDeployment-taskform.flt
    3         BrmsPkgDocument SRAMPPackage.pkg
    4           ImageDocument overlord.demo.SimpleReleaseProcess-image.png
    5           ImageDocument run-build-install.png
    6                Document overlord.demo.SimpleReleaseProcess-taskform.flt
    7           ImageDocument audio-input-microphone-3.png
    8            BpmnDocument overlord.demo.SimpleReleaseProcess.bpmn
    9            TextDocument HttpClientWorkDefinitions.wid

To obtain the metaData of overlord.demo.SimpleReleaseProcess.bpmn, which is number 8 in the list, issue

s-ramp> s-ramp:getMetaData feed:8
Meta Data for: 31b3acbc-cda8-4856-9e34-d3e645283035
--------------
  -- Core S-RAMP Info --
  Type: BpmnDocument
  Model: ext
  UUID: 31b3acbc-cda8-4856-9e34-d3e645283035
  Name: overlord.demo.SimpleReleaseProcess.bpmn
  Derived: false
  Created By: <anonymous>
  Created On: 2013-03-08T14:00:37.036-05:00
  Modified By: <anonymous>
  Modified On: 2013-03-18T14:58:46.328-04:00
s-ramp>

TBD - reference to generic section on XPath2 query syntax

S-RAMP supports an XPath2 Syntax for querying. For example to obtain all WSDL models in the repository use

s-ramp> s-ramp:query /s-ramp/wsdl/WsdlDocument
Querying the S-RAMP repository:
    /s-ramp/wsdl/WsdlDocument
Atom Feed (1 entries)
  Idx                    Type Name
  ---                    ---- ----
    1            WsdlDocument OrderService.wsdl
s-ramp>

When this WSDL file was uploaded derived information was extracted from it and stored a WSDL model. TO see the various data structures it derived simply hit the tab on s-ramp:query /s-ramp/wsdl

s-ramp> s-ramp:query /s-ramp/wsdl/
Binding                  BindingOperation         BindingOperationFault    BindingOperationInput    BindingOperationOutput
Fault                    Message                  Operation                OperationInput           OperationOutput
Part                     Port                     PortType                 WsdlDocument             WsdlExtension
WsdlService
s-ramp>

Note that derived data is read only, and cannot be updated by the user.

To obtain all Operations in this WSDL use

s-ramp:query /s-ramp/wsdl/Operation
Querying the S-RAMP repository:
    /s-ramp/wsdl/Operation
Atom Feed (1 entries)
  Idx                    Type Name
  ---                    ---- ----
    1               Operation submitOrder
s-ramp>

You can narrow this query down even more by adding that the name needs to start with submit

s-ramp:query "/s-ramp/wsdl/Operation[xp2:matches(@name, 'submit.*')]"
Querying the S-RAMP repository:
    /s-ramp/wsdl/Operation[xp2:matches(@name, 'submit.*')]
Atom Feed (1 entries)
  Idx                    Type Name
  ---                    ---- ----
    1               Operation submitOrder
s-ramp>

don’t forget to use the surrounding quotes, and a . after submit as required by XPath2.

To obtain all the artifacts that were derived from an artifact you can use

/s-ramp[relatedDocument[@uuid = '<uuid>'

In this case we use the uuid of a wsdl and get all the artifacts derived from the wsdl

s-ramp:query "/s-ramp[relatedDocument[@uuid = '15a94308-a088-4a03-ad83-e60239af74e4']]"
Querying the S-RAMP repository:
	/s-ramp[relatedDocument[@uuid = '15a94308-a088-4a03-ad83-e60239af74e4']]
Atom Feed (16 entries)
  Idx                    Type Name
  ---                    ---- ----
    1          OperationInput submitOrder
    2             WsdlService OrderService
    3             SoapAddress soap:address
    4   BindingOperationInput wsdl:input
    5             SoapBinding soap:binding
    6                    Part parameters
    7                 Binding OrderServiceBinding
    8  BindingOperationOutput wsdl:output
    9                 Message submitOrderResponse
   10         OperationOutput submitOrderResponse
   11        BindingOperation submitOrder
   12                 Message submitOrder
   13               Operation submitOrder
   14                    Port OrderServicePort
   15                    Part parameters
   16                PortType OrderService

To get a list of all artifacts that were extracted from another archive use

s-ramp:query "/s-ramp[expandedFromDocument[@uuid = '<uuid>']

let’s say we uploaded a jar file containing switchyard artifacts, with uddi 67c6f2d3-0f10-4f0d-ada6-d85f92f02a33:

s-ramp:query "/s-ramp[expandedFromDocument[@uuid = '67c6f2d3-0f10-4f0d-ada6-d85f92f02a33']]"
Querying the S-RAMP repository:
	/s-ramp[expandedFromDocument[@uuid = '67c6f2d3-0f10-4f0d-ada6-d85f92f02a33']]
Atom Feed (3 entries)
  Idx                    Type Name
  ---                    ---- ----
    1             XmlDocument switchyard.xml
    2             XmlDocument beans.xml
    3             XmlDocument faces-config.xml

TBD

TBD

TBD

To support SOA Governance management a governance application monitors a S-RAMP compliant repository for certain events. These events can then be used to kickoff governance workflows.

TBD

Organizations define policies and processes to managing artifacts. These policies and processes will be different for each organization. We therefore enlisted the help of a BPMN workflow engine. This should give users the needed flexibility to implement their specific workflow. We ship a number of best practices workflow that users can copy and or modify to their needs.