Notices

Copyright © OASIS Open © 2017. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see http://www.oasis-open.org/policies-guidelines/trademark for above guidance.


Table of Contents

1. Introduction

This section is non-normative.

1.1 Background and Motivation

Global software delivery is commonplace today. With ever increasing competitiveness, such as faster delivery, competitive cost, and skill availability, it is becoming common for software delivery to be done by collaboration of multiple organizations. Effective collaboration between the multiple organizations require activities to be managed and data to be shared across organizational boundaries. The management of software delivery can be highly challenging due to the diversity of the development process, method, tools and platforms used by organizations participating in the project [SPMC]. As a result, both the information shared and the management used are usually unique to each organization. Typically, manual operations are performed in exchanging proprietary information and in coordinating activities; resulting in inefficient, error-prone and inflexible operations. As the number of organizations involved in software delivery increases, the need for more systematic and open standards-based information sharing and coordination becomes critical. PROMCODE (PROject Management of Contracted Delivery) is an open specification for exchanging project management data across organizational boundaries [PROMCODE13]. PROMCODE leverages OSLC specifications [OSLCCore3] and defines a set of interface specifications as abstraction of data exchanged in many real projects [PROMCODE14].

1.2 Problem and Solution Framework

PROMCODE is intended to provide a common interface to exchange the management data across the organizational boundaries. Figure 1 illustrates a generic model of collaborative software development. A set of organizations, including A, B1, …, Bn, C11, …, C1m, …Cnm, are working together to deliver a software system. We assume two roles between any two organizations working together, that is, acquirer and supplier. The goal of PROMCODE specification is to provide an open standard interface to exchange the management data between acquirer and supplier. Therefore, we only use the role of acquirer and supplier throughout this specification. Here, we assume the schema of management data and its management tool of each organization is different.

Fig. 1 Collaborative Software Development

1.3 PRMCODE Architecture

Figure 2 illustrates an abstract model of the PROMCODE Architecture. The goal of PROMCODE Architecture is to enable to exchange the project management data through the PROMCODE specification between multiple different data models of project management, which are used in multiple different organizations under different management models.

To meet the goal, the PROMCODE specification consists of two layers: PROMCODE Domain Model and PROMCODE Resource as illustrated in Figure 2. The PROMCODE Domain Model is an abstract definition of the structure of the project management data to be exchanged. The Domain Model is derived from common knowledge of project management [PMBOK5] and practice of contracted delivery of software and systems [PROMCODE13], [PROMCODE14].

The PROMCODE Resource defines the data schema of the Domain Model data in terms of RDF resources. The PROMCODE Architecture assumes OSLC Core 3.0 [OSLCCore3] and W3C LDP (Linked Data Platform) [LDP] as the underlying platform. Therefore, the PROMCODE resource is defined based on the OSLC Core 3.0 and W3C LDP.

The PROMCODE client and server are adapters to coordinate the mapping of the organization-specific data model from and to PROMCODE resource, respectively. The interaction between the clients and servers is based on the Resource-Oriented manner [ROA] with HTTP [HTTP11].

For example, Supplier B1 and B2 map their project management data into B1-specific PM Data and B2-Specific PM Data to PROMCODE Resource through their PROMCODE Servers. Acquirer A can collect the project management data of Suppliers B1 and B2 by mapping the PROMCODE Resource of B1 and B2 to A-Specific PM Data. Therefore, PROMCODE Specification can avoid the combinatorial complexity of converting data across the different data models. With PROMCODE specification, Acquirer can collect the project status in real-time with a high degree of traceability [PROMCODE13].

Fig. 2 PROMCODE Architecture

2. Normative and Non-normative

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

3. Terminology

Terminology is based on OSLC Core 3.0 [OSLCCore3], W3C Linked Data Platform [LDP], W3C's Architecture of the World Wide Web [WEBARCH] and Hyper-text Transfer Protocol [HTTP11].

Acquirer
Acquirer is an entity to acquire software and/or system(s).
Supplier
Supplier is an entity to supply software and/or system(s) to be delivered to an Acquirer.
Project
Project is a temporary endeavor undertaken to create unique software and/or system(s) [PMBOK5].
Project Management
Project Management is the application of knowledge, skills, tools, techniques, to project activities to meet project requirements [PMBOK5].
PROMCODE Resource
PROMCODE Resource is an LDP Resource [LDP] to represent project management data.
PROMCODE Service
PROMCODE service is a service to exchange project management data defined by the PROMCODE resource.
PROMCODE Server
PROMCODE Server is an OSLC Server [OSLCCore3], which complies with the LDP Server that also supports the capabilities defined by the PROMCODE specification. See Server [HTTP11] and LDP Server [LDP].
PROMCODE Client
PROMCODE Client is an OSLC Client [OSLCCore3], which complies with the LDP Client that uses the capabilities defined by the PROMCODE specification. See Client [HTTP11] and LDP Client [LDP].

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].

4. PROMCODE Domain Model Specification

This section is non-normative.

4.1 Domain Model

Fig. 3 PROMCODE Domain Model illustrates PROMCODE Domain Model.
Fig. 3 PROMCODE Domain Model

In this figure, if no multiplicity is shown on an association end, it implies a multiplicity of zero to unlimited (0 .. *). The multiplicity of an attribute is also omitted for simplification. While its default is a multiplicity of zero to one (0 .. 1), there are exceptional cases where the multiplicity is exactly 1 in which it will be explicitly described as such in the following part of this section. Each of the following subsections describes each class in the domain model.

4.1.1 ScopeItem

A ScopeItem is an entity that represents a scope of work from the acquirer’s view of a software development contract. It represents a unit of value to be accomplished by the software suppliers in the contract will develop. For example, it may represent a function required, a use case in which the software will be used, a requirement which the acquirer expects, or a screen which will provide some concrete function to the user of the software.

Because a ScopeItem is not an activity, it cannot be started nor ended. Because it is not a produced artifact, it does not represent any measurable entity.

The acquirer can use a set of ScopeItems as managed units to manage a whole scope of development. Both the acquirer and suppliers also use a set of ScopeItems to estimate the scale of development and so the size of each ScopeItem should be estimated. There should be agreement between the acquirer and suppliers on what kind of ScopeItem should be used and on how large each ScopeItem is. Change of some ScopeItem or its estimated size needs another agreement. A ScopeItem can be decomposed into finer grained ScopeItems to be used in detailed management. In that case, a coarse grained ScopeItem may be used to aggregate a set of finer grained ScopeItems.

  • Super Class
    • ManagedItem
  • Attributes
    • plannedSize: Decimal [0 .. 1]
      • An estimated size agreed by both acquirer and supplier. The metric and unit of size should be preliminarily agreed between the acquirer and suppliers. They can be specified as metricOfScopeItemSize and unitOfScopeItemSize of a Project if necessary.
    • actualSize: Decimal [0 .. 1]
      • An actual size agreed by both acquirer and supplier.
  • Links
    • isPartOf: ScopeItem [0 .. 1]
      • An ancestor of this ScopeItem.

4.1.2 WorkItem

A work item describes an activity to be performed in a software development contract. It adds detail to the description of the work that is described by a scope item. These details typically include cost, schedule, and resource requirements. The set of all work items in a project form a work breakdown structure.

A WorkItem is an entity to represent the supplier’s internal activity. For example, it may represent a development phase such as analysis, design, implementation, or test. It may also represent a finer grained activity such as document writing, reviewing, or coding. A WorkItem is a managed unit of activity required to implement a ScopeItem or to produce an Artifact.

Progress of a WorkItem is managed by comparing planned and actual dates on which it is started and ended.

A WorkItem can be decomposed into finer grained WorkItems to be used in detailed management. A coarse grained WorkItem is used to aggregate a set of finer grained WorkItems.

  • Super Class
    • ManagedItem
  • Attributes
    • plannedStartDate: DateTime [0 .. 1]
      • A planned date to start this WorkItem.
    • actualStartDate: DateTime [0 .. 1]
      • An actual date to start this WorkItem.
    • plannedEndDate: DateTime [0 .. 1]
      • A planned date to end this WorkItem.
    • actualEndDate: DateTime [0 .. 1]
      • An actual date to end this WorkItem.
  • Links
    • representedBy: Person [0 .. 1]
      • A person responsible for the progress of this WorkItem who may or may not actually do this WorkItem.
    • isPartOf: WorkItem [0 .. 1]
      • An ancestor of this WorkItem.
    • requiredBy: ScopeItem [0 .. 1]
      • A ScopeItem such that this WorkItem is required to implement it.
    • requiredBy: Artifact [*]
      • Artifacts such that this WorkItem is required to produce them. For example, producing specification documents requires interviewing users, writing the initial version, reviewing, reflecting the review comments, approving, and so on.

4.1.3 Artifact

An artifact is a work product that is produced in a project such as design documents, source code, test report, and so on. An artifact may be physical or digital.

An Artifact is produced for a WorkItem or a ScopeItem.

An Artifact can be measured using some measure, and their measured values may vary at each point of time on a Project. The quality of an Artifact is managed by comparing planned and actual measures.

An Artifact can be decomposed into finer grained Artifacts to be used in detailed management. A coarse grained Artifact may be used to aggregate a set of finer grained Artifacts.

  • Super Class
    • ManagedItem
  • Links
    • isPartOf: Artifact [0 ..1]
      • An ancestor of this Artifact.
    • producedFor: WorkItem [*]
      • WorkItems which require to produce this Artifact.
    • producedFor: ScopeItem [*]
      • ScopeItems which require to produce this Artifact.
    • targets: Measure [*]
      • Measures planned for this Artifact. Before project execution, the acquirer and the supplier determine which type of measure should be used. Once selected, the measures are traced until project completion. One Artifact can target zero or more Measures.

4.1.4 Risk

A risk is a potential problem that must be controlled before it occurs in order to meet the objectives of a project. Failure to control the situation may result in negative consequences for the project, such as a schedule delay.

After a Risk actually occurs, it typically becomes an Issue.

  • Super Class
    • ManagedItem
  • Attributes
    • identifiedDate: DateTime [0 .. 1]
      • An identified date of this Risk.
  • Links
    • identifiedBy: ManagedItem [*]
      • ManagedItems which identify this Risk. A Risk may be identified by one or more ManagedItems.
    • stateOfRisk: State [0 .. 1]
      • A state of this Risk.

4.1.5 Issue

An issue is a situation that must be resolved in order to meet the objectives of a project. Failure to resolve the situation may result in negative consequences for the project, such as a schedule delay.

  • Super Class
    • ManagedItem
  • Attributes
    • raisedDate: DateTime [0 .. 1]
      • A raised date of this Issue.
  • Links
    • raisedBy: ManagedItem [*]
      • ManagedItems which raise this Issue. An issue may be raised by one or more ManagedItems.
    • stateOfIssue: State [0 .. 1]
      • A state of this Issue.

4.1.6 ManagedItem

ManageItem is a super class which abstracts five kinds of managed entities, that is, ScopeItem, WorkItem, Artifact, Risk, and Issue.

  • Attributes
    • Identifier: String [1]
      • An identifier of this ManagedItem.
    • SequenceNumber: Decimal [0 .. 1]
      • A unique number which represents an order of each subclass of this ManagedItem.
    • Title: String [0 .. 1]
      • A name of this ManagedItem.
    • Description: String [0 .. 1]
      • A text which describes of this ManagedItem.

4.1.7 Plan

A plan is a collection, or a snapshot, of managed entities which is agreed between the acquirer and suppliers at project initiation.

A Plan is a ManagedItemCollection which is typically a collection of planned ScopeItems, WorkItems, and Artifacts together with targeting Measures. However, a Plan may collect any type of ManagedItems.

  • Super Class
    • ManagedItemCollection

4.1.8 Report

A report is a collection, or a snapshot, of managed entities which is submitted by a supplier for project monitoring.

A Report is a ManagedItemCollection which is typically a collection of ScopeItems, WorkItems, and Artifacts together with associated Measurements and Measures. However, a Report may collect any type of ManagedItems. It represents the situation of the Project on a specific date.

  • Super Class
    • ManagedItemCollection
  • Links
    • correspondsTo: Plan [0 .. 1]
      • A Plan of this Report. A Report is submitted to the corresponding Plan. If the Pan is changed, the Report is submitted to the new Pan

4.1.9 RiskCollection

A risk collection is a collection, or a snapshot, of risks.

Only Risks can be collected in a RiskCollection. It may collect all Risks of the Project on a specific date, however, it also may collect Risks of some category, such as status, priority, related ScopeItem, and so on.

  • Super Class
    • ManagedItemCollection

4.1.10 IssueCollection

An issue collection is a collection, or a snapshot, of issues.

Only Issues can be collected in an IssueCollection. It may collect all Issues of the Project on a specific date, however, it also may collect Issues of some category, such as status, priority, related ScopeItem, and so on.

  • Super Class
    • ManagedItemCollection

4.1.11 ManagedItemCollection

ManagedItemCollection is a super class which abstracts four kinds of collections of managed entities, that is, Plan, Report, RiskCollection, and IssueCollection. A ManagedItemCollection must belong to a Project.

  • Attributes
    • Identifier: String [1]
      • An identifier of this ManagedItemCollection.
    • Title: String [0 .. 1]
      • A name of this ManagedItemCollection.
    • date: DateTime [0 .. 1]
      • A date on which this ManagedItemCollection collects ManagedItems.
  • Links
    • collects: ManagedItem [*]
      • ManagedItems included in this ManagedItemCollection. A ManagedItemCollection collects any type of ManagedItems such as ScopeItems, WorkItems, Artifacts, Risks, or Issues.
    • belongsTo: Project [1]
      • A Project which this ManagedItemCollection belongs to. A Project has several snapshots until completion. Sometimes a supplier or an acquirer operates several Projects in parallel. The supplier or the acquirer identifies which snapshot should belong to a Project.

4.1.12 Measure

A measure is an observation of some measurable quality aspect of an artifact.

A Measure has a metric such as “number of lines of codes (LOC)”, “number of found bugs”, and so on.

It also has a unit type which designates what is the unit of the numbered value, for example, whether “1” means one line or one kilo lines. A Measure must be either targeted by one Artifact or observed by one Measurement.

  • Attributes
    • title: String [0 .. 1]
      • A name of this Measure.
    • value: Decimal [1]
      • A value of this Measure.
  • Links
    • metric: Metric [0 .. 1]
      • A metric of this Measure.
    • unitOfMeasure: UnitOfMeasure [0 .. 1]
      • A unit type of this Measure.

4.1.13 Measurement

A measurement links between an artifact and actual measures of it. It also represents the date on which the measures are taken.

  • Attributes
    • Date: DateTime [1]
      • A date on which an Artifact is measured.
  • Links
    • observes: Measure [*]
      • Measures measured by this Measurement. One Measurement can measure zero or more Measures.
    • measures: Artifact [1]
      • An Artifact measured by this Measurement.

4.1.14 Project

A project represents the information of the whole project such as the name of the project, the descriptions of the project, and progress of the whole project.

A Project also specifies the Metric and the unit type of size of ScopeItems because they should be unique in a project.

  • Attributes
    • identifier: String [1]
      • An identifier of this Project.
    • title: String [0 .. 1]
      • A name of this Project.
    • description: String [0 .. 1]
      • A text which describes of this Project.
    • plannedStartDate: DateTime [0 .. 1]
      • A planned date to start this Project.
    • actualStartDate: DateTime [0 .. 1]
      • An actual date to start this Project.
    • plannedEndDate: DateTime [0 .. 1]
      • A planned date to end this Project.
    • actualEndDate: DateTime [0 .. 1]
      • An actual date to end this Project.
  • Links
    • metricOfScopeItemSize: Metric [0 .. 1]
      • A metric of size of ScopeItems in this Project.
    • unitOfScopeItemSize: UnitOfMeasure [0 .. 1]
      • A unit type of size of ScopeItems in this Project.

4.2 Samples of Project Models

4.2.1 Applying to Progress Management

Table 1 shows a typical progress management table. The table describes the status of implementing functions defined in the first column. Each function is divided into a collection of subfunctions. Each Subfunction has phases of Analysis, Design, and Coding activities. Note that the real management tables are more complex than shown in in real cases. Function-Sub Function forms a tree structure with several levels. There are more activities required to implement SubFunctions.

Table 1 only shows the essential structure of real management tables.

Table 1 Example of Progress Management Table
Function Sub Function Analysis Design Coding
Start End Start End Start End
A A1 Planned 6/4 6/11 6/12 6/19 6/20 6/27
Actual 6/4 6/10 6/11 6/19 6/20 6/26
A2 Planned 6/4 6/11 6/12 6/19 6/20 6/25
Actual 6/4 6/12 6/13 6/20 6/21 6/26
B B1 Planned 6/4 6/11 6/12 6/19 6/20 6/27
Actual 6/4 6/12 6/13 6/20 6/21 6/28

Fig. 4 Example of Project Model for Progress Management illustrates the corresponding project model. Function and Sub Function are subclasses of ScopeItem, and the Analysis, Design, and Coding activities are subclasses of WorkItem. A Function is decomposed into a collection of SubFunctions which have three kinds of required WorkItems for implementation. This structure indicates that all project management data in Table 1 can be represented as instances of the PROMCODE Domain Model classes of ScopeItem and WorkItem.

Fig. 4 Example of Project Model for Progress Management

4.2.2 Applying Quality Management

Table 2 shows a typical quality management table. Main managed entity is Module which is grouped under Requirement. Each Module is measured using several KPIs including lines of code, number of test cases, and number of defects found.

Table 2 Example of Quality Management Table
Requirement Module Line of Code #Test Case #Defect
Target Actual Target Actual Target Actual
R1 M1-1 2,000 2,130 60 62 5 5
M1-2 1,500 1,450 45 43 3 2
R2 M2-1 2,000 1,980 60 65 5 4
M2-2 1,000 950 30 35 2 2

Fig. 5 Example of Project Model for Quality Management illustrates the corresponding project model. Requirement is a subclass of ScopeItem and Module is a subclass of Artifact. A Requirement is used to group Modules that implement it. The structure indicates that all project management data in Table 2 can be represented as instances of PROMCODE Domain Model classes of ScopeItem, Artifact, and Measure.

Fig. 5 Example of Project Model for Quality Management

5. PROMCODE Service Specification

PROMCODE services are a set of services to exchange project management data defined by the PROMCODE resource definitions described in section 6.

This specification is based on OSLC Core 3.0 [OSLCCore3]. PROMCODE servers and clients MUST be compliant with both the [OSLCCore3] specification and this PROMCODE specification, and SHOULD follow all the guidelines and recommendations in both these specifications.

The following sections describe further restriction or guidance for some requirements in [OSLCCore3].

5.1 Namespaces

In addition to the namespace URIs and namespace prefixes oslc, rdf, dcterms and foaf defined in the [OSLCCore3], PROMCODE defines the namespace URI of http://open-services.net/ns/promcode# with a preferred namespace prefix oslc_promcode. Prefix promcode is used in this specification.

5.2 Service Discovery

There are two approaches described in the OSLC Core Version 3.0 Discovery specification. PROMCODE servers SHOULD support Dynamic Incremental discovery which is utilizing [LDP], and MAY support Static Up-Front discovery approach which is compatible with [OSLCCore2].

5.2.1 Root Resource

PROMCODE servers which support Dynamic Incremental discovery MUST provide a Project Container Resource as a root resource. The Project Container resource MUST be an LDP Basic Container for Project resource.

PROMCODE servers which support Static Up-Front discovery MUST provide ServiceProviderCatalog as a root resource where an oslc:domain property the value http://open-services.net/ns/promcode# .

The root resource can be retrieved at an implementation dependent URI.

5.2.2 PROMCODE LDP Containers

PROMCODE servers which support Dynamic Incremental discovery MUST provide set of LDP containers. The diagram below illustrates the PROMCODE LDP containers and relationships with PROMCODE resources.

Fig. 6 PROMCODE LDP Containers

Black boxes are PROMCODE resources, orange boxes are PROMCODE LDP containers, and lightblue box is an inline resource.

All PROMCODE LDP containers MUST be an LDP Basic Container.

Steps with Dynamic Incremental Discovery proceed as follows. A PROMCODE client sends an http request to a PROMCODE server to access the Project Container, the top-level resource the server manages. After getting a list of Project resources from the Container, it can select the Project resource of interest. Then, the client can determine if each of Container resources to be linked from the Project resource as in Figure 6 (explained in Section 5.4) exists or not. If a Container exists, the resource created by the Container is supported by the server. If not, the resource is not supported. For discovery of Measurement Container, an Artifact resource needs to exist and then, the Container is obtained by following a link from the Artifact resource. Once the existence of each Container is assured, the client can send an http OPTIONS message to the Container to get a list of all the services supported for the resource created by the Container. In this way, a PROMCODE client communicates with a PROMCODE server to get the information on all the resource types the Server supports and all the services supported for each such resource types.

Discovery for OSLC 2.0 is done as described in OSLC Core 2.0 [OSLCCore2].

5.3 Resource Operations

This section describes some notable behaviors for the resource operations.

5.3.1 Create Resources

PROMCODE clients can create a PROMCODE resource through a corresponding PROMCODE LDP container if the server supports the Dynamic Incremental discovery or through a corresponding creation factory if the server supports the Static Up-Front discovery. For example, Plan resource can be created by sending an HTTP POST request to a PlanContainer resource or to an URL of creation factory for Plan resource advertized in Service resource.

To create Measure resources, create an Artifact or Measurement in RDF which has Measures, then submit HTTP POST request.

In a PROMCODE server which supports Dynamic Incremental discovery:

  • PlanContainer, ReportContainer, ScopeItemContainer, WorkItemContainer, ArtifactContainer, RiskContainer, IssueContainer, RiskCollectionContainer, and IssueCollectionContainer resources are created implicitly when a Project resource is created.
  • A MeasurementContainer resource is created implicitly when an Artifact resource is created.

5.3.2 Update Resources

PROMCODE servers MAY support HTTP PUT or HTTP PATCH method to update resources. The detailed behaviors are described in [LDP].

Because Measure is an inline resource, to update a Measure resource in an Artifact resource, update the Artifact resource by using HTTP PUT or PATCH method. To update a Measure resource in a Measurement resource, update the Measurement resource by using HTTP PUT or PATCH method.

5.3.3 Delete Resources

PROMCODE servers MAY support HTTP DELETE method to delete resources. The detailed behaviors are described in [LDP].

Because Measure is an inline resource, deleting an Artifact resource or a Measurement resource results in deleting Measure resources implicitly.

PlanContainer, ReportContainer, ScopeItemContainer, WorkItemContainer, ArtifactContainer, RiskContainer, IssueContainer, RiskCollectionContainer, and IssueCollectionContainer resources are deleted implicitly when the Project resource which has the resources is deleted. A MeasurementContainer resource is deleted implicitly when the Artifact resource which has the MeasurementContainer resource is deleted.

5.4 Query Capabilities

PROMCODE LDP containers MAY include the target URI in a Link header with "http://open-services.net/ns/core#queryCapability" as rel attribute in an HTTP response for a PROMCODE LDP container resource.

Example 1: OSLC Query
Link: <http://example.com/promcode/query>; rel="http://open-services.net/ns/core#queryCapability"; type="oslcQuery" ,
Example 2: SPARQL Query
Link: <http://example.com/promcode/sparql>; rel="http://open-services.net/ns/core#queryCapability"; type="http://www.w3.org/TR/sparql11-query/" 

6. PROMCODE Resource Definitions

Property value types that are not defined in the following sections, are defined in [OSLCCore3]. Descriptions of resources in this chapter assume LDP. For implementation based on OSLC 2.0, resources needed are the subset of all the resources except containers.

6.1 HTTP Requests on PROMCODE Resources

PROMCODE resources are categorized into three kinds: containers when LDP is used, inline resources and top-level resources.

Containers are LDP container resources. Containers MUST accept GET requests which returns the resource with their contents URI as ldp:contains range. Containers MAY accept POST requests to generate new corresponding resource as their contents.

A Measure is an inline resource which can exist inside of an Artifact or a Measurement resource. Thus it only accepts GET request which returns the contents. To provide support of updating Measure resources, PROMCODE servers MAY support PUT or PATCH (or both) on Artifact or Measurement resources.

Top-level resources are represented as references for the range of properties. PROMCODE servers MAY support POST request on corresponding containers to create, PUT/PATCH request on their URL to update, DELETE on their URL to remove them. PROMCODE servers MUST provide GET request support to provide the contents.

PROMCODE servers support following HTTP requests for PROMCODE resources. PROMCODE servers MUST support GET requests and MAY support PUT, POST, PATCH and DELETE requests.

Table 4: HTTP requests for PROMCODE resources
Category Resource type of Http request URI Request type Operation
Container ProjectContainer, PlanContainer,
ReportContainer, RiskCollectionContainer,
IssueCollectionContainer, MeasurementContainer,
ArtifactContainer,ScopeItemContainer,
WorkItemContainer,RiskContainer,
IssueConatiner
GET(MUST) Returns container resource including its ldp:contains contents' URI.
POST Generates resources. However, generating container resources are not supported.
PUT/PATCH Not supported.
DELETE Not supported.
Inline Resource Measure GET(MUST) GET request for Measure resources returns Measure resources as inline resources of an Artifact or a Measurement.
POST Not supported.
PUT/PATCH Not supported. PUT/PATCH request on Artifact or Measurement resource updates these resources including Measure inline resource.
DELETE Not supported. DELETE request on Artifact or Measurement resource deletes these resources including Measure inline resource.
Top-level Resource Project, Artifact, ScopeItem, WorkItem, RiskCollection, IssueCollection, Risk, Issue, Measurement, Plan, Report GET(MUST) Returns the resource.
POST Not Supported.
PUT/PATCH Updates the resource with the request body.
DELETE Deletes the resource.

GET operations of ManagedItemCollection should support a flag generateDocument to return document representation of the collection. This applies to GET operations of Plan, Report, RiskCollection and IssueCollection. When the flag is set to True, GET returns a document that represents the collection regardless of its representation. If the flag is set to false, it returns the representation of the property of the collection defined.

6.2 Resource Shape

6.2.1 Typographical Conventions and Use of RFC Terms

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].

Conventions

In this section, Resource Shape is represented in RDF+Turtle format. The following common URI prefixes are used throughout this section.

Example 3
    @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
    @prefix dcterms: <http://purl.org/dc/terms/> .
    @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
    @prefix oslc: <http://open-services.net/ns/core#> .
    @prefix ext: <http://ww.w3.org/TODO:extendsShapeNameSpace> .
    @prefix ems: <http://open-services.net/ns/ems#> .
    @prefix ldp: <http://www.w3.org/ns/ldp#> .
    @prefix oslc_promcode: <http://open-services.net/ns/promcode#> .

6.2.2 ProjectContainer

A ProjectContainer resource is a container for Project resources. A Project resource can be created by sending an HTTP POST request to a ProjectContainer resource.

6.2.3 Project

A Project represents the information of the whole project such as the name of the project, the descriptions of the project, and progress of the whole project.

6.2.4 ManagedItem

ManageItem is a super class which abstracts five kinds of managed entities, that is, ScopeItem, WorkItem, Artifact, Risk, and Issue.

6.2.5 ScopeItemContainer

A ScopeItemContainer resource is a container for ScopeItem resources. A ScopeItem resource can be created by sending an HTTP POST request to a ScopeItemContainer resource.

6.2.6 ScopeItem

A ScopeItem defines the work to be included in the Project. It defines the boundaries of the Project.

6.2.7 WorkItemContainer

A WorkItemContainer resource is a container for WorkItem resources. A WorkItem resource can be created by sending an HTTP POST request to a WorkItemContainer resource.

6.2.8 WorkItem

A WorkItem describes an activity to be performed in a software development contract. It adds details to the description of the work that is described by a ScopeItem. These details typically include cost, schedule, and resource requirements. The set of all WorkItems in a project forms a work breakdown structure.

A WorkItem is a managed unit of activity required to implement a ScopeItem or to produce an Artifact.

A WorkItem can be decomposed into finer grained WorkItems to be used in detailed management. A coarse grained WorkItem is used to aggregate a set of finer grained WorkItems.

6.2.9 ArtifactContainer

A ArtifactContainer resource is a container for Artifact resources. An Artifact resource can be created by sending an HTTP POST request to a ArtifactContainer resource.

6.2.10 Artifact

An Artifact is a work product that is produced in a project such as design documents, source code, test report, and so on. An Artifact may be physical or digital.

6.2.11 Measure

A Measure is an observation of some measurable quality aspect of an Artifact.

6.2.12 RiskContainer

A RiskContainer resource is a container for Risk resources. A Risk resource can be created by sending an HTTP POST request to a RiskContainer resource.

6.2.13 Risk

Risk is a potential problem that must be controlled before it occurs in order to meet the objectives of the Project. Failure to control the situation may result in negative consequences for the Project, such as a schedule delay.

After a Risk actually occurs, it typically becomes an Issue.

6.2.14 IssueContainer

A IssueContainer resource is a container for Issue resources. An Issue resource can be created by sending an HTTP POST request to a IssueContainer resource.

6.2.15 Issue

An Issue is a situation that must be resolved in order to meet the objectives of a project. Failure to resolve the situation may result in negative consequences for the project, such as a schedule delay.

6.2.16 RiskCollectionContainer

A RiskCollectionContainer resource is a container for RiskCollection resources. A RiskCollection resource can be created by sending an HTTP POST request to a RiskCollectionContainer resource.

6.2.17 ManagedItemCollection

ManagedItemCollection is a super class which abstracts four kinds of collections of managed entities, that is, Plan, Report, RiskCollection, and IssueCollection. A ManagedItemCollection must belong to a Project.

6.2.18 RiskCollection

A RiskCollection is a collection, or a snapshot, of Risks.

Only Risks can be collected in a RiskCollection. Examples are a collection of all Risks of the Project on a specific date, a collection of Risks of some category, such as status, priority, related ScopeItem, and so on.

6.2.19 IssueCollectionContainer

An IssueCollectionContainer resource is a container for an IssueCollection resource. An IssueCollection resource can be created by sending an HTTP POST request to an IssueCollectionContainer resource.

6.2.20 IssueCollection

An IssueCollection is a collection, or a snapshot, of issues.

Only Issues can be collected in an IssueCollection. Examples are a collection of all Issues of the Project on a specific date, a collection of Issues of some category, such as status, priority, related ScopeItem, and so on.

6.2.21 PlanContainer

A PlanContainer resource is a container for Plan resources. A Plan resource can be created by sending an HTTP POST request to a PlanContainer resource.

6.2.22 Plan

A Plan is a ManagedItemCollection which collects ScopeItems, WorkItems, and Artifacts together with the Measures.

6.2.23 ReportContainer

A ReportContainer resource is a container for Report resources. A Report resource can be created by sending an HTTP POST request to a ReportContainer resource.

6.2.24 Report

A Report is a collection, or a snapshot, of managed entities which is submitted by a supplier for project monitoring.

A Report is a ManagedItemCollection which collects ScopeItems, WorkItems, and Artifacts together with associated Measurements and Measures. It represents the situation of the Project on a specific date.

6.2.25 MeasurementContainer

A MeasurementContainer resource is a container for Measurement resources. A Measurement resource can be created by sending an HTTP POST request to a MeasurementContainer resource.

6.2.26 Measurement

A Measurement links between an Artifact and its actual measures. It also represents the date on which the measures are taken.

6.3 Vocabulary

Note: Non-normative note on sequenceNumber

The property sequenceNumber is motivated by the need to visually display a list of some ManagedItems (such as a list of ScopeItems, a list of some WorkItems a list of Issues, and so forth) by a management tool such as spreadsheet during the course of project management. When such a list is displayed, it is natural to require that a list follows some order for consistency and for a better user experience. The property is introduced for that. It is required that sequenceNumber is unique in all the resources of the same resource type of ManagedItem, i.e., ScopItem, WorkItem, Artifact, Issues and Risk. Actual values and how they are assigned are not specified by the standard.

7. Use Cases and Scenarios

This section is non-normative.

This chapter describes use cases and scenarios for the OSLC PROMCODE Interface Specification Version 1.0.

7.1 Use Cases

In this specification, the vocabulary used is based on commonly used terms in many real project management activities in contracted delivery. It is also consistent with global standards such as PMBOK and ISO 21500:2012.

In this chapter and the subsequent chapter, we use the term acquirer and supplier to refer to the project manager responsible for each organization to manage the project.

7.1.1 Scope of Use Cases

Details of use cases depend on many things such as relationships between an acquirer and a supplier, how much information is shared between then, and tools and their environments of an acquirer and a supplier. In this chapter, we will describe typical sequence of activities often seen. The environment we assume here is that there is a PROMOCODE server available that can be accessed by both an acquirer and a supplier. We call this environment shared server environment. Also, each of an acquirer and a supplier uses its own tool to manage their work, and information sharing between them is done by using common PROMCODE server. For simplicity, we assume that the common PROMOCODE server supports all the resources and resource operations described in the PROMCODE specification. This is called PROMCODE full server, as defined in Chapter 9.

Another typical case is an environment where there is no common server available between an acquirer and a supplier, and information sharing is done by sending and receiving messages and documents explicitly. We call this environment non-shared environment. A PROMCODE report server as defined in Chapter 9 can be used in such cases. Depending on the information shared between an acquirer and a supplier, other server such as PROMOCE issue server, also defined in Chapter 9, can be used in a similar fashion.

We assume shared server environment in our description of the use case as mentioned above. For non-shared environment, similar sequence can be used to guide activities of an acquirer and a suppler, and differences on activities will be described in relevant portions of the sequence.

Fig. 7 Scope of Use Cases

The PROMCODE specification is applicable for project planning, execution and control process.

In this section, eight scenarios are described, i.e., project planning, starting, status reporting, schedule problems, quality problems, plan change, issue management and risk management. Each scenario explains how to apply PROMCODE format data to exchange information between an acquirer and a supplier.

7.1.2 Project Planning

Preconditions

Project initiation is already completed. Project plan and target goal are agreed by all the stakeholders. The plan includes project duration, scopes, supporting work items, artifacts and target quality of the artifacts. An acquirer and a supplier also agree on metric and unit size of scopes.

Scenario

  1. An acquirer creates an initial plan.

  2. According to the initial plan, the acquirer generates necessary resources such as Project, Plan, ScopeItem, WorkItem, Artifact and Measure resources with planned value using acquirer's project management tool.

  3. The acquirer's project management tool publishes these resources to the PROMCODE server.

  4. The PROMCODE server accepts PROMCODE resources and generates a URL for each resource.

  5. The acquirer obtains the URL and notifies a supplier of the URL.

In non-shared environment, steps 3-5 will be different. In typical case, sharing is done using Plan and Report. Each of an acquirer and a supplier uses its own report server that can be accessed by its partner. Then, the first step is for the acquirer to create a Plan and publish it on its PROMOCODE report server. Then, the suppler reads it from the acquirer’s plan server and creates the same Plan resource in its own report server. Creating a Plan resource might require creation of other resources such as ScopeItem, WorkItem, Artifact, and Measure that are included in Plan. If the supplier's report server does not support explicit access of these resources, the server ensures that these resources can be included in Plan and Report resources by collaborating with supplier's project management tool.

In the project execution phase, there are four use cases, i.e., project start, status reporting, status aggregation and project closing. As in the case of Project Planning section of 7.1.2, scenario descriptions in the subsequent sections assume the use of common PROMCODE full server shared by the acquirer and the supplier. For non-shared environment, description will be given on the different sequence of actions when relevant.

7.1.3 Project Execution and Control

After starting the project, the tasks assigned to each project members are executed and monitored by their project manager. The project information is summarized according to predefined project measures. Usually, the acquirer's project manager collects all suppliers’ report and reviews it periodically. If a problem is found, the acquirer's project manager plans to fix it. Sometimes, a new project goal is introduced during project execution, and the initial project plan including project scope, work items and artifacts has to be modified. At the end of the project, all target measurers are achieved and the project is closed.

7.1.4 Project Start

Project start scenario is considered as preparation for subsequent scenarios. Systems and data flow of the scenario are described in Project start.

Preconditions

An acquire collects project information from a supplier and summarizes them in the acquirer's project management tool. A supplier may use a different project management tool to collect project information from team members. Each such tool needs to convert project information to PROMCODE resources and should be able to enter PROMCODE resources to the PROMCODE server and to retrieve them from the server.

Before the project starts, an acquirer and a supplier need to establish common understanding and rules to run and manage the project. This includes reporting frequency and timing, and criteria used for raising and managing issues and risks.

Scenario

  1. An acquirer fills in actual starting date of the Project resource in the acquirer's project management tool and submits it to the PROMCODE server.

  2. The PROMCODE server updates the PROMCODE resource.

  3. A supplier retrieves the resource and imports the information to the supplier's project management tool.

  4. The supplier starts running the project using its own project management tool that understands the information.

In non-shared environment, sharing is done by first the acquirer publishing information in its PROMODE report server and the supplier reading the information. Then, the supplier enters the information to its own report server that works with the supplier's project management tool.

7.1.5 Status Reporting

Status reporting scenario is a periodical process during project execution. Systems and data flow of the scenario are described in Status reporting.

Preconditions

The acquirer and the supplier agree on reporting information and its timing. Each time the supplier reports information, a new Report resource is created in the PROMCODE server. The acquire retrieves it to review the information. As in the previous sections, the acquirer and the supplier may use their own propriety project tools for their own management activities.

Scenario

  1. An acquirer creates an initial Report resource which specifies information to be collected by report in the form of collection of ScopeItem resources, Work item resources and Artifact resources. using the acquirer's project management tool and enters it to the PROMCODE server.

  2. The PROMCODE server registers the Report resource and publishes the URL.

  3. The acquirer obtains the URL and notifies the supplier of the URL.

  4. The supplier retrieves Report resource and any related resources, and updates its progress in the supplier's project management tool.

  5. The supplier's project management tool enters the updated resources to the PROMCODE server as its report of the reporting period.

  6. The acquirer's project management tool retrieves the Report resource and related resources from PROMCODE server.

In non-shared environment, this is done as follows. First the acquirer publishing initial Report resource into its own report server. Then, the supplier reads it and stores it into its report server. Then, the supplier creates a Report resource of the reporting period using the initial Report as template and by entering information such as actual date and measures. The acquirer then retrieves the Report from the supplier’s report server.

7.1.6 Review and Actions for Schedule Problems

Review and actions for schedule problems scenario is a typical event-driven activity during project execution. Systems and data flow of the scenario are described in Review and actions for schedule problems.

Preconditions

Status reporting is periodically done from the supplier to the acquirer at pre-agreed timing.

Scenario

  1. Reviews the difference between previous report and current one, and raises a concern if the following is observed.

    • Condition 1: Progress is not sufficient.

    • Condition 2: Risk of not meeting a schedule emerges with the current pace of progress.(May use past data on productivity to project risk.)

  2. The acquirer interacts with the supplier on further update.

    • Reasons for delay

    • Outlook of meeting a schedule

  3. Based on the interaction, the acquirer takes one of the following actions.

    1. No formal action, but continue to monitor the situation.

    2. Take action to address the issue raised by the supplier without plan change. This may include new risk to be identified that results in creation of Risk resource.

    3. Escalate to stakeholders for possible plan change.

  4. If plan change is necessary, it will trigger the activity of plan change. See details in the Plan Change scenario.

7.1.7 Review and Actions for Quality Problems

Review and actions for quality problems scenario is another typical event-driven activity during project execution. Systems and data flow of the scenario are described in Review and actions for quality problems.

Preconditions

Status reporting is periodically executed from suppliers to the acquirer at pre-agreed timing.

Scenario

  1. The acquirer compares the previous report and current report and reviews the difference.

  2. Reviews the difference and raises a concern if the progress is not sufficient and there is a risk of not meeting quality goals.

  3. The acquirer interacts with the supplier on further update.

    1. Reasons of the current problem

    2. Outlook of meeting a goal

    3. Assess the impact to the overall project.

  4. Based on the interaction, the acquirer takes one of the following actions.

    1. Stay with the current plan and monitor the situation.

    2. Escalate to stakeholders for possible plan change.

  5. If plan change is necessary, it will trigger the activity of plan change. See details in the Plan Change scenario.

7.1.8 Plan Change

Plan change scenario may occur if a plan does not appear achievable. Systems and data flow of the scenario are described in Plan change.

Preconditions

All stakeholders of the project agree to change the project plan. Typical reasons include schedule delay, quality concern, and change of requirements.

Scenario

  1. The acquirer decides to change a current plan. The acquirer notifies the supplier of the plan change.

  2. A supplier reviews a new plan. The acquirer interacts with the supplier for the change, and updates it if necessary.

  3. The acquirer and the suppliers agree.

  4. The acquirer creates a new Plan resource and enters it to the PROMCODE server.

  5. A supplier retrieves a new plan information by reading the resource from the PROMCODE server.

7.1.9 Risk Management

Risk is an event that may or may not happen in the future with adverse effect to the project typical regarding its cost, schedule, scope, quality, and customer satisfaction. Systems and data flow of the scenario are described in Risk management.

Preconditions

Risks are examined by reviewing current situation of ScopeItem, WorkItem and Artifacts with their values of properties. The acquirer identifies a collection of risks to be managed for the project.

Scenario

  1. The acquirer evaluates each potential risk, such as cost overrun, schedule delay and shortage of skills for the project.

  2. The acquirer asks a supplier to create a risk by examining information including its qualitative and quantitative aspects for the project.

  3. The supplier creates a Risk resource for each identified risk and registers it to the PROMCODE server.

  4. The supplier notifies the registration of risks to the acquirer.

  5. The acquirer obtains information on each risk registered from the PROMCODE server.

  6. The acquirer reviews each risk and determines what actions are needed. Actions can be to monitor it, to take mitigation actions, or to close it for now. Risks reviewed includes all Risk resources including non-closed Risk resources registered at previous risk review activities.

In non-shared environment, identifying, reporting and managing risks are done by using PROMCODE issue server, a server that supports Risk and Issue. The server may be different from report server, or the same server may support both Plan/Report and Risk/Issue resources. Its use is similar to that of report server, i.e., either one of an acquirer or a supplier creating Risk or Issue resource, and publishing it in its own issue server and the other retrieving it.

7.1.10 Issue Management

In contrast to risk, issue is an event that already took place that require attention and resolution to avoid a problem for the project. Issue management scenario can take place periodically similarly to reporting scenario, or it can take place more on as needed basis during project execution. Systems and data flow of the scenario are described in Issue management.

Preconditions

Issues are raised by examining regarding current situation of ScopeItem, WorkItem and Artifacts. The acquirer determines a collection of issues to be managed for the project.

Scenario

  1. The supplier creates Issue resources and registers them to the PROMCODE server.

  2. The supplier notifies the acquirer of the registration of the issues.

  3. The acquirer obtains information on each published issue from the PROMCODE server.

  4. The acquirer reviews each issue and decides actions. Actions are to resolve the situation described by the issue. Issues reviewed includes all non-closed Issue resources including Issue resources registered at previous issue review activities.

  5. The acquirer closes an issue if no actions and no monitoring are needed for it.

Activities in non-shared environment are similar to those in Risk management.

7.1.11 Project Closing

Project closing scenario closes the project.

Preconditions

All the target of artifact has been achieved. All the risks and issues are resolved.

Scenario

  1. A supplier registers actual end date and actual size of the Project resource to the PROMCODE server.

  2. The supplier notifies the registration of the data to the acquirer.

  3. The acquirer obtains the published actual data from PROMCODE server.

  4. The acquirer preserves the whole project data for future work such as project analysis.

In non-shared environment, steps are done by the supplier publishing information and the acquirer retrieving it using report server.

8. Systems and Data Flow for Scenarios

This section is non-normative.

This chapter describes example data flows among tools and users for each use case described in Chapter 7.

8.1 Roles and Tools

In this chapter, we use the following tools to illustrate the system flow sequences.

PROMCODE Server
A tool which supports OSLC PROMCODE Interface Specification Version 1.0. It provides a Web user interface to access project management data in addition to REST services defined in OSLC PROMCODE Interface Specification Version 1.0. It supports the POST method to create PROMCODE resources.
PROMCODE Server Web UI
Web user interface of PROMCODE Server. It provides user interfaces with the following operations:
PROMCODE Adapter
A tool which accepts spreadsheet files as input from user through its web user interface. It then converts the data in the spreadsheet files and converts them into PROMCODE resources. PROMCODE resources are stored in PROMCODE Server through PROMCODE REST services.
PROMCODE Client for Spreadsheet
A spreadsheet tool which has capabilities to retrieve and submit PROMCODE resources using PROMCODE services.

8.2 Assumption (Precondition)

Example 4: ScopeItemSize
<ems:metric rdf:resource="http://open-services.net/ns/ems/metric#Effort" />
<ems:unitOfMeasure rdf:resource="http://open-services.net/ns/ems/unit#PersonMonth" />
Example 5: Measure for Source Code artifact
<ems:metric rdf:resource="http://open-services.net/ns/ems/metric#Sloc" />
<ems:unitOfMeasure rdf:resource="http://open-services.net/ns/ems/unit#Loc" />
Example 6: Measure Test Case artifact
<ems:metric rdf:resource="http://open-services.net/ns/ems/metric#Defects" />
<ems:unitOfMeasure rdf:resource="http://open-services.net/ns/ems/unit#Defect" />

8.3 Scenarios

8.3.1 Project start

This scenario illustrates how OSLC PROMCODE 1.0 may be used in the process of starting a project. The corresponding use case is described in Project start.

Project start is the first phase in the lifecycle of a project.

8.3.1.1 Scenario

The first step of starting a project is to create a Project resource and a Plan resource in the PROMCODE Server through the PROMCODE Server Web UI.

  1. Acquirer inputs the following information in the PROMCDE Server Web UI and clicks the button "Create Project with Plan".

    • project name : "projX"

    • plan name : "planX"

    • metric and unit of size of ScopeItem: "Function Point"

  2. PROMCODE Server Web UI submits an HTTP GET request to the PROMCODE Sever and retrieves the Project Container resource. ProjectContainer is already created by default in the beginning.

Example 7: Request - retrieving a Project Container
GET /pm/ HTTP/1.1
Host: example.org
Accept: text/turtle
Example 8: Response - retrieving a Project Container
HTTP/1.1 200 OK 
Content-Type: text/turtle; charset=UTF-8
Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type", <http://www.w3.org/ns/ldp#Resource>; rel="type"
Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH
Accept-Post: text/turtle, application/ld+json
Content-Length: 250
ETag: W/'123456789'
    
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
    
<http://example.org/pm/> a ldp:Container, ldp:BasicContainer .
  1. PROMCODE Server Web UI creates a content of Project resource for projX in RDF (e.g. Turtle format) from the information which is set at step1.

  2. PROMCODE Server Web UI submits an HTTP POST request that includes the content of the projX resource to the Project Container. plannedSize and description are optional properties so they don't need to be filled at this time.

Example 9: Request - creating a Project resource
POST /pm/ HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<>
  a promcode:Project ;
  dcterms:identifier "100" ;
  dcterms:title "projX" ;
  promcode:metrixOfScopeItemSize <http://open-services.net/ns/ems/metric#Effort> ;
  promcode:unitOfScopeItemSize <http://open-services.net/ns/ems/unit#PersonMonth> .
  1. PROMCODE Server creates the projX resource and returns the URL to the PROMCODE Server Web UI.
Example 10: Response - creating a Project resource
HTTP/1.1 201 Created
Location: http://example.com/pm/projects/100
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Length: 0 
  1. PROMCODE Server Web UI submits an HTTP GET request to the PROMCODE Server and retrieves the projX resource, and extracts the ManagedItem Container.
Example 11: Request - container retrieval after resource created
GET /pm/projects/100 HTTP/1.1
Host: example.org
Accept: text/turtle
Example 12: Response - container retrieval after resource created
HTTP/1.1 200 OK 
Content-Type: text/turtle; charset=UTF-8
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Allow: OPTIONS,HEAD,GET,PUT,PATCH,DELETE
Accept-Post: text/turtle, application/ld+json
Content-Length: 250
ETag: W/'123456789'

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/projects/100>
  a promcode:Project ;
  dcterms:identifier "100" ;
  dcterms:title "projX" ;
  promcode:metrixOfScopeItemSize <http://open-services.net/ns/ems/metric#Effort> ;
  promcode:unitOfScopeItemSize <http://open-services.net/ns/ems/unit#PersonMonth> ;
  promcode:planContainer <http://example.com/pm/projects/100/planContainer> ;
  promcode:reportContainer <http://example.com/pm/projects/100/reportContainer> ;
  promcode:scopeItemContainer <http://example.com/pm/projects/100/scopeItemContainer> ;
  promcode:workItemContainer <http://example.com/pm/projects/100/workItemContainer> ;
  promcode:artifactContainer <http://example.com/pm/projects/100/artifactContainer> ;
  promcode:riskContainer <http://example.com/pm/projects/100/riskContainer> ;
  promcode:issueContainer <http://example.com/pm/projects/100/issueContainer> ;
  promcode:riskCollectionContainer <http://example.com/pm/projects/100/riskCollectionContainer> ;
  promcode:issueCollectionContainer <http://example.com/pm/projects/100/issueCollectionContainer> .
  1. PROMCODE Server Web UI creates a content of Plan resource for planX in RDF from the information which is set at step1.

  2. PROMCODE Server Web UI submits an HTTP POST request that includes the content of the planX resource to the Plan Container.

Example 13: Request - creating a Plan resource
POST /pm/projects/100/planContainer HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<>
  a promcode:Plan ;
  dcterms:title "planX" ;
  promcode:belongsTo <http://example.com/pm/projects/100> .
  1. PROMCODE Server creates the planX resource, and returns the URL to Acquirer through its Web UI.
Example 14: Response - creating a Plan resource
HTTP/1.1 201 Created
Location: http://example.com/pm/plans/200
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Length: 0 

The next step is to fill scope items for the plan.

  1. Acquirer creates a spreadsheet file which contains all scope items for projX.
Fig. 8 data.xls
  1. Acquirer sends the planX URL and the data.xls to PROMCODE Adapter through its Web UI.

  2. PROMCODE Adapter submits an HTTP GET request to the PROMCODE Server and retrieves the planX resource and the associated projX resource. PROMCODE Adapter then extracts the ManagedItem Container URL.

Example 15: Request - retrieving the planX
GET /pm/plans/200 HTTP/1.1
Host: example.org
Accept: text/turtle
Example 16: Response - retrieving the planX
HTTP/1.1 200 OK 
Content-Type: text/turtle; charset=UTF-8
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Allow: OPTIONS,HEAD,GET,PUT,PATCH,DELETE
Accept-Post: text/turtle, application/ld+json
Content-Length: 250
ETag: W/'123456789'

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/plans/200>
  a promcode:Plan ;
  dcterms:identifier "200" ;
  dcterms:title "planX" ;
  promcode:belongsTo <http://example.com/pm/projects/100> .
Example 17: Request - retrieving the projX
GET /pm/projects/100 HTTP/1.1
Host: example.org
Accept: text/turtle
Example 18: Response - retrieving the projX
HTTP/1.1 200 OK 
Content-Type: text/turtle; charset=UTF-8
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Allow: OPTIONS,HEAD,GET,PUT,PATCH,DELETE
Accept-Post: text/turtle, application/ld+json
Content-Length: 250
ETag: W/'123456789'

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/projects/100>
  a promcode:Project ;
  dcterms:identifier "100" ;
  dcterms:title "projX" ;
  promcode:metrixOfScopeItemSize <http://open-services.net/ns/ems/metric#Effort> ;
  promcode:unitOfScopeItemSize <http://open-services.net/ns/ems/unit#PersonMonth> ;
  promcode:planContainer <http://example.com/pm/projects/100/planContainer> ;
  promcode:reportContainer <http://example.com/pm/projects/100/reportContainer> ;
  promcode:scopeItemContainer <http://example.com/pm/projects/100/scopeItemContainer> ;
  promcode:workItemContainer <http://example.com/pm/projects/100/workItemContainer> ;
  promcode:artifactContainer <http://example.com/pm/projects/100/artifactContainer> ;
  promcode:riskContainer <http://example.com/pm/projects/100/riskContainer> ;
  promcode:issueContainer <http://example.com/pm/projects/100/issueContainer> ;
  promcode:riskCollectionContainer <http://example.com/pm/projects/100/riskCollectionContainer> ;
  promcode:issueCollectionContainer <http://example.com/pm/projects/100/issueCollectionContainer> .
  1. PROMCODE Adapter parses the data.xls and converts the contents to ScopeItem, WorkItem, Artifact resources in RDF. PROMCODE Adapter also creates a content of the Measure resource as a sub-resource of the Artifact in RDF.

  2. PROMCODE Adapter submits a set of HTTP POST requests to the ManagedItem Container to create ScopeItem, WorkItem, Artifact resources. PROMCODE Server creates new ScopeItem, WorkItem, Artifact resources, and returns the URLs to PROMCODE Adapter.

Example 19: Request - creating a ScopeItem resource
POST /pm/projects/100/scopeItemContainer HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<>
  a promcode:ScopeItem ;
  dcterms:title "Make Reservation UI" ;
  promcode:plannedSize "20" .
Example 20: Response - creating a ScopeItem resource
HTTP/1.1 201 Created
Location: http://example.com/pm/scopeitems/1010
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Length: 0 
Example 21: Request - creating an Artifact resource and Measure resources for the Artifact
POST /pm/projects/100/artifactContainer HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<>
  a promcode:Artifact ;
  dcterms:title "Make Reservation UI Source Code" ;
  promcode:producedFor <http://example.com/pm/scopeitem/1010> .
  promcode:targets <#measure_1>, <#measure_2> .
  
<#measure_1>
  a promcode:Measure ;
  dcterms:title "Code size (kloc)" ;
  promcode:value "10" ;
  promcode:metricOfMeasure <http://open-services.net/ns/ems/metric#Sloc> ;
  promcode:unitOfMeasure <http://open-services.net/ns/ems/unit#Loc> .

<#measure_2>
  a promcode:Measure ;
  dcterms:title "Number of defects" ;
  promcode:value "10" ;
  promcode:metricOfMeasure <http://open-services.net/ns/ems/metric#Defects> ;
  promcode:unitOfMeasure <http://open-services.net/ns/ems/unit#Defect> .
  
Example 22: Response - creating an Artifact resource and Measure resources for the Artifact
HTTP/1.1 201 Created
Location: http://example.com/pm/artifacts/2010
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Length: 0 
Example 23: Request - creating a WorkItem resource
POST /pm/projects/100/workItemContainer HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<>
  a promcode:WorkItem ;
  dcterms:identifier "3010" ;
  dcterms:title "Implement Make Reservation UI" ;
  promcode:plannedStartDate "2015-01-05T09:00:00Z" ;
  promcode:plannedEndDate "2015-03-31T18:00:00Z" ;
  promcode:requiredBy <http://example.com/pm/artifacts/2010> .
Example 24: Response - creating a WorkItem resource
HTTP/1.1 201 Created
Location: http://example.com/pm/workitems/3010
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Length: 0 
  1. PROMCODE Adapter adds ScopeItem, Artifact, and WorkItem resources as collects property of the Plan resource so that supplier can retrieve all related information for the planX.

  2. PROMCODE Adapter submits an HTTP PUT request to update the planX.

Example 25: Request - updating the planX
PUT /pm/plans/200 HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/plans/200>
  a promcode:Plan ;
  dcterms:identifier "200" ;
  dcterms:title "planX" ;
  promcode:belongsTo <http://example.com/pm/projects/100> ;
  promcode:collects <http://example.com/pm/scopeitems/1010>, <http://example.com/pm/scopeitems/1011>, 
                <http://example.com/pm/artifacts/2010>, <http://example.com/pm/artifacts/2011>,
                <http://example.com/pm/workitems/3010>, <http://example.com/pm/scopeitems/3011> .
Example 26: Response - updating the planX
HTTP/1.1 204 No Content 
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type" 
  1. PROMCODE Adapter’s Web UI displays list of SopeItem resources.

Acquirer sends an e-mail to Supplier to notify URL of planX and ask the supplier to review it.

When Supplier receives the notification from Acquirer, Supplier reviews the planX using PROMCODE Client for Spreadsheet.

  1. Supplier sets the planX URL to PROMCODE Client for Spreadsheet.

  2. PROMCODE Client for Spreadsheet submits an HTTP GET request to the PROMCODE Server and retrieves planX resource.

Example 27: Request - retrieving the planX
GET /pm/plans/200 HTTP/1.1
Host: example.org
Accept: text/turtle
Example 28: Response - retrieving the planX
HTTP/1.1 200 OK 
Content-Type: text/turtle; charset=UTF-8
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Allow: OPTIONS,HEAD,GET,PUT,PATCH,DELETE
Accept-Post: text/turtle, application/ld+json
Content-Length: 250
ETag: W/'123456789'

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/plans/200>
  a promcode:Plan ;
  dcterms:identifier "200" ;
  dcterms:title "planX" ;
  promcode:belongsTo <http://example.com/pm/projects/100> ;
  promcode:collects <http://example.com/pm/scopeitems/1010>, <http://example.com/pm/scopeitems/1011>,
                <http://example.com/pm/artifacts/2010>, <http://example.com/pm/artifacts/2011>,
                <http://example.com/pm/workitems/3010>, <http://example.com/pm/scopeitems/3011> .
  1. PROMCODE Client for Spreadsheet submits an HTTP GET request to the PROMCODE Server and retrieves Scope Item resources for planX and display the Scope Item resources on the spreadsheet.
Example 29: Request - retrieving a ScopeItem
GET /pm/scopeitems/1010 HTTP/1.1
Host: example.org
Accept: text/turtle
Example 30: Response - retrieving a ScopeItem
HTTP/1.1 200 OK 
Content-Type: text/turtle; charset=UTF-8
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Allow: OPTIONS,HEAD,GET,PUT,PATCH,DELETE
Accept-Post: text/turtle, application/ld+json
Content-Length: 250
ETag: W/'123456789'

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/scopeitems/1010>
  a promcode:ScopeItem ;
  dcterms:title "Make Reservation UI" ;
  promcode:plannedSize "20" .
  1. Supplier reviews the scope items on the spreadsheet.
8.3.1.2 Summary Sequence Diagram

The following sequence diagram summarizes Project Start scenario:

Fig. 9 Project start with PROMCODE with a spreadsheet file

8.3.2 Status reporting

This scenario illustrates how OSLC PROMCODE 1.0 can be used in the process of status reporting. The corresponding use case is described in Status reporting.

Status reporting is a middle phase during project execution.

8.3.2.1 Scenario

First, Acquirer gets the plan planX and ScopeItem, WorkItem and Artifact resources that are associated with planX.

  1. Acquirer inputs the planX URL to the PROMCODE Client for Spreadsheet.

  2. PROMCODE Client for Spreadsheet submits an HTTP GET request to the PROMCODE Server and retrieves the planX resource and associated projX resouce.

  3. PROMCODE Client for Spreadsheet parses the planX resource and gets URLs of associated resources, such as ScopeItem, WorkItem and Artifact resources.

  4. PROMCODE Client for Spreadsheet then submits an GET request to the PROMCODE Server and retrieves the ScopeItem, WorkItem, Artifact and Measurement resources.

  5. PROMCODE Client for Spreadsheet parses the resources and converts them to human readable format to display the resources.

Next, Acquirer selects resources which should be in a Report, and put them into the Report resource.

  1. Acquirer selects resources in the PROMCODE Client for Spreadsheet.

  2. Acquirer clicks the button "Create Report" on the PROMCODE Client for Spreadsheet.

  3. PROMCODE Client for Spreadsheet creates a content of the Report resource for reportX in RDF.

  4. PROMCODE Client for Spreadsheet extracts Report Container URL from the projX resource, and submits an HTTP POST request that includes the content of the Report resource to the Report Container.

Example 31: Request - creating a Report resource
POST /pm/projects/100/reportContainer HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<>
  a promcode:Report ;
  dcterms:title "reportX" ;
  dcterms:date "2015-03-15T18:00:00Z" ;
  promcode:belongsTo <http://example.com/pm/projects/100> ;
  promcode:collects <http://example.com/pm/scopeitems/1010>, <http://example.com/pm/scopeitems/1011>,
                <http://example.com/pm/artifacts/2010>, <http://example.com/pm/artifacts/2011>,
                <http://example.com/pm/workitems/3010>, <http://example.com/pm/scopeitems/3011> .
  
  1. PROMCODE Server returns the URL of reportX.
Example 32: Response - creating a Report resource
HTTP/1.1 201 Created
Location: http://example.com/pm/reports/300
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Length: 0 
  1. PROMCODE Client for Spreadsheet displays the URL of reportX so that Acquirer can get the URL.

  2. Now the Report resource reportX is created and it’s ready to be updated by the supplier. Acquirer notifies the URL of reportX to Supplier.

Next, Supplier updates the ScopeItem, WorkItem, Artifact, and creates Measurement and Measure resources, based on the current status of the project.

  1. Acquirer enters the reportX URL to PROMCODE Client for Spreadsheet.

  2. PROMCODE Client for Spreadsheet submits an HTTP GET request to the PROMCODE Server and retrieves the reportX resource and associated projX resource.

  3. PROMCODE Client for Spreadsheet parses the reportX resource and lists associated resources, such as ScopeItem, WorkItem and Artifact resources.

  4. PROMCODE Client for Spreadsheet then submits an HTTP GET request to the PROMCODE Server and retrieves the ScopeItem, WorkItem, Artifact and Measurement resources.

  5. PROMCODE Client for Spreadsheet parses the resources and converts them to human readable format to display the resources.

  6. Supplier updates the resources on the PROMCODE Client for Spreadsheet

Next, Supplier publishes the updated resources to the PROMCODE Server.

  1. Supplier click the button "Publish Report" on the PROMCODE Client for Spreadsheet.

  2. PROMCODE Client for Spreadsheet creates a content of Measurement resource in RDF, based on the updates by Supplier. PROMCODE Client for Spreadsheet also creates a content of Measure resource as inline resource of the Measurement in RDF.

  3. PROMCODE Client for Spreadsheet extracts Measurement Container for each Artifact resource, and submits HTTP POST request that includes the content of Measurement resource to the Measurement Container.

Example 33: Listing of an Artifact
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/artifacts/2010>
  a promcode:Artifact ;
  dcterms:title "Make Reservation UI Source Code" ;
  promcode:measurementContainer <http://example.com/pm/artifacts/2010/measurementContainer> ;
  promcode:producedFor <http://example.com/pm/scopeitem/1010> .
  promcode:targets <#measure_1>, <#measure_2> .
  
<#measure_1>
  a promcode:Measure ;
  dcterms:title "Code size (kloc)" ;
  promcode:value "10" ;
  promcode:metricOfMeasure <http://open-services.net/ns/ems/metric#Sloc> ;
  promcode:unitOfMeasure <http://open-services.net/ns/ems/unit#Loc> .

<#measure_2>
  a promcode:Measure ;
  dcterms:title "Number of defects" ;
  promcode:value "10" ;
  promcode:metricOfMeasure <http://open-services.net/ns/ems/metric#Defects> ;
  promcode:unitOfMeasure <http://open-services.net/ns/ems/unit#Defect> .
Example 34: Request - creating a Measurement resource with Measure resources for an Artifact
POST /pm/artifacts/2010/measurementContainer HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<>
  a promcode:Measurement ;
  dcterms:date "2015-03-15T18:00:00Z" ;
  promcode:measures <http://example.com/pm/artifacts/2010> ;
  promcode:observes <#measure_1> .
  
<#measure_1>
  a promcode:Measure ;
  dcterms:title "Code size (kloc)" ;
  promcode:value "15" ;
  promcode:metricOfMeasure <http://open-services.net/ns/ems/metric#Sloc> ;
  promcode:unitOfMeasure <http://open-services.net/ns/ems/unit#Loc> .
Example 35: Response - creating a Measurement resource with Measure resources for an Artifact
HTTP/1.1 201 Created
Location: http://example.com/pm/measurements/5010
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Length: 0 
  1. PROMCODE Client for Spreadsheet submits an HTTP PUT request to the PROMCODE Server and updates ScopeItem and WorkItem resources in reportX.

Listing of resources

Example 36: ScopeItem resource
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/scopeitems/1010>
  a promcode:ScopeItem ;
  dcterms:identifier "1010" ;
  dcterms:title "Reservation System" ;
  promcode:plannedSize "20" ;
  promcode:actualSize "25" .
Example 37: WorkItem resource
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/workitems/3010>
  a promcode:WorkItem ;
  dcterms:identifier "3010" ;
  dcterms:title "Implement Reservation System" ;
  promcode:plannedStartDate "2015-01-05T09:00:00Z" ;
  promcode:actualStartDate "2015-01-05T09:00:00Z" ;
  promcode:plannedEndDate "2015-03-31T18:00:00Z" ;
  promcode:requiredBy <http://example.com/pm/artifacts/2010> .
  1. Supplier sends an e-mail which contains the URL of reportX

Upon the notification, Acquirer starts review of the status of the project.

  1. Acquirer gets the URL of reportX from the e-mail, then set it to the PROMCODE Client for Spreadsheet.

  2. PROMCODE Client for Spreadsheet submits an HTTP GET request to the PROMCODE Server and retrieve the reportX resource.

  3. PROMCODE Client for Spreadsheet parses the reportX resources and lists associated resources, such as ScopeItem, WorkItem and Artifact resources.

  4. PROMCODE Client for Spreadsheet then submits an HTTP GET request to the PROMCODE Server and retrieve the ScopeItem, WorkItem and Artifact, and Measurement resources.

  5. PROMCODE Client for Spreadsheet parses the resources and converts them to human readable format. PROMCODE Client for Spreadsheet displays the resources.

  6. Acquirer reviews the resources.

8.3.2.2 Summary Sequence Diagram

The following sequence diagram summarizes Status reporting scenario:

Fig. 10 Status Reporting

8.3.3 Review and actions for schedule problems

The corresponding use case is described in Review and actions for schedule problems. This use case doesn't have any interaction with systems. The scenario continues to the Risk Management scenario.

8.3.4 Review and actions for quality problems

The corresponding use case is described in Review and actions for quality problems This use case doesn't have any interaction with systems. The scenario continues to the Risk Management scenario.

8.3.5 Risk Management

This scenario illustrates how OSLC PROMCODE 1.0 can be used in the process of risk management. The corresponding use case is described in Risk management

8.3.5.1 Scenario

First Acquirer evaluates the reportX and finds possible risks.

  1. Acquirer sets the URL of reportX to PROMCODE Client for Spreadsheet

  2. PROMCODE Client for Spreadsheet submits an HTTP GET request to the PROMCODE Server to retrieve reportX resource and associated projX resource.

  3. PROMCODE Client for Spreadsheet parses the reportX resource and list associated resources, such as ScopeItem, WorkItem, Artifact, Measurement and Measure.

  4. PROMCODE Client for Spreadsheet displays the resources on the sheet.

  5. Acquirer then reviews the resources and finds possible risks.

Next, Acquirer registers a RiskCollection resource that is a placeholder of risks.

  1. Acquirer clicks the "Create RiskCollection" button on the PROMCODE Server Web UI.

  2. PROMCODE Server Web UI extracts RiskCollection Container from the projX resource.

  3. PROMCODE Server Web UI creates a content of the RiskCollection resource for riskCollectionX in RDF, and submits an HTTP POST request that includes the content of the RiskCollection resource to the RiskCollection Container.

Example 38: Request - creating a RiskCollection resource
POST /pm/projects/100/riskCollectionContainer HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<>
  a promcode:RiskCollection ;
  dcterms:title "riskCollectionX" ;
  promcode:belongsTo <http://example.com/pm/projects/100> .
  1. PROMCODE Server returns the URL of riskCollectionX resource to the PROMCODE Server Web UI.
Example 39: Response - creating a RiskCollection resource
HTTP/1.1 201 Created
Location:http://example.com/pm/riskcollections/800
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Length: 0 
  1. PROMCODE Server Web UI displays the URL of riskCollectionX.

Acquirer notifies the URL of riskCollectionX to Supplier, and ask to register possible risks.

  1. Acquirer sends an e-mail which contains the URL of riskCollectionX

Supplier identifies possible risks during project execution, then supplier registers a Risk for riskCollectionX.

  1. Supplier sets the URL of riskCollectionX to the PROMCODE Server Web UI.

  2. Supplier click the "File Risk" button on the PROMCODE Server Web UI.

  3. PROMCODE Server Web UI creates a content of Risk resource for riskX in RDF.

  4. PROMCODE Server Web UI extracts ManagedItem Container from projX resource, and submits an HTTP POST request that includes riskX resource to the ManagedItem Container.

Example 40: Request - creating a Risk resource
POST /pm/projects/100/riskContainer HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<>
  a promcode:Risk ;
  dcterms:title "Work load for Make Reservation UI may exceed estimation" ;
  promcode:raisedDate "2015-03-15T20:00:00Z" ;
  promcode:identifiedFor <http://example.com/pm/scopeitem/1010> ;
  promcode:stateOfRisk <http://example.com/project/status#open> .
  1. PROMCODE Server returns the URL of riskX to the PROMCODE Server Web UI.
Example 41: Response - creating a Risk resource
HTTP/1.1 201 Created
Location:http://example.com/pm/risks/8000
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Length: 0 
  1. PROMCODE Server Web UI submits an HTTP PUT request to the PROMCODE Server to update the riskCollectionX to have the riskX.
Example 42: Request - updating a RiskCollection resource
PUT http://example.com/pm/riskcollections/800 HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/riskcollections/800>
  a promcode:RiskCollection ;
  dcterms:identifier "800" ;
  dcterms:title "riskCollectionX" ;
  promcode:belongsTo <http://example.com/pm/projects/100> ;
  promcode:collects <http://example.com/pm/risks/8000> .
Example 43: Response - updating a RiskCollection resource
HTTP/1.1 204 No Content 
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type" 
  1. PROMCODE Server Web UI displays the URL of riskX.

  2. Supplier notifies Acquirer that riskCollectionX is updated.

Acquirer reviews risks in the riskCollectionX and creates a new issue for the riskX.

  1. Acquirer set the URL of riskCollectionX to get the resource to the PROMCODDE Server Web UI.

  2. PROMCODE Server Web UI submits an HTTP GET request to the PROMCODE Server, and retrieves the riskCollectionX.

  3. PROMCODE Server returns riskCollectionX resource to the PROMCODE Server Web UI.

  4. PROMCODE Server Web UI displays the riskCollectionX.

  5. Acquirer selects riskX on the PROMCODDE Server Web UI.

  6. PROMCODE Server Web UI submits an HTTP GET request to the PROMCODE Server, and retrieves the riskX.

  7. PROMCODE Server returns riskX resource to the PROMCODE Server Web UI.

  8. PROMCODE Server Web UI displays the riskX.

  9. Acquire reviews the riskX.

  10. Go to Issue Management scenario to create a new issue if necessary.

Acquirer then closes the riskX.

  1. Acquirer clicks the "Close Risk" button on the PROMCODE Server Web UI, if the riskX is no longer needed.

  2. PROMCODE Server Web UI submits an HTTP PUT request to the PROMCODE Server to change the statusOfRisk property of the riskX.

Example 44: Listing of Risk resource
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/risks/8000>
  a promcode:Risk ;
  dcterms:identifier "8000" ;
  dcterms:title "Work load for Make Reservation may exceed estimation" ;
  promcode:raisedDate "2015-03-15T20:00:00Z" ;
  promcode:identifiedFor <http://example.com/pm/scopeitem/1010> ;
  promcode:stateOfRisk <http://example.com/project/status#closed> .
  1. PROMCODE Server returns the closed riskX resource to the PROMCODE Server Web UI.

  2. PROMCODE Server Web UI displays the closed riskX.

8.3.5.2 Summary Sequence Diagram

The following sequence diagram summarizes Risk Management scenario:

Fig. 11 Risk Management

8.3.6 Issue Management

This scenario illustrates how OSLC PROMCODE 1.0 may be used in the process of issue management. The corresponding use case is described in Issue management

8.3.7 Scenario

First, Acquirer registers an IssueCollection resource that is a placeholder of issues.

  1. Acquirer clicks the "Create IssueCollection" button on the PROMCODE Server Web UI.

  2. PROMCODE Server Web UI creates a content of IssueCollection resource for issueCollectionX in RDF.

  3. PROMCODE Server Web UI extracts IssueCollection Container from the projX resource, and submits an HTTP POST request that includes issueCollectionX resource to the IssueCollection Container.

Example 45: Request - creating an IssueCollection resource
POST /pm/projects/100/issueCollectionContainer HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<>
  a promcode:IssueCollection ;
  dcterms:title "issueCollectionX" ;
  promcode:belongsTo <http://example.com/pm/projects/100> .
  1. PROMCODE Server returns the URL of issueCollectionX resource to the PROMCODE Server Web UI.
Example 46: Response - creating an IssueCollection resource
HTTP/1.1 201 Created
Location:http://example.com/pm/issuecollections/710
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Length: 0 
  1. PROMCODE Server Web UI displays the URL of issueCollectionX.

Acquirer notifies the URL of issueCollectionX to Supplier.

  1. Acquirer sends an e-mail which contains the URL of issueCollectionX

Supplier already identifies possible issues during the project execution, then registers an Issue for issueCollectionX.

  1. Supplier sets the URL of issueCollectionX to the PROMCODE Server Web UI.

  2. Supplier clicks the "File Issue" button on the PROMCODE Server Web UI.

  3. PROMCODE Server Web UI creates a content of Issue resource for issueX in RDF.

  4. PROMCODE Server Web UI extracts ManagedItem Container from the projX resource, and submits an HTTP POST request that includes the issueX resource to the ManagedItem Container.

Example 47: Request - creating an Issue resource
POST /pm/projects/100/issueContainer HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<>
  a promcode:Issue ;
  dcterms:title "Estimation for Make Reservation UI needs to be updated" ;
  promcode:raisedDate "2015-03-16T17:00:00Z" ;
  promcode:raisedFor <http://example.com/pm/scopeitem/1010> ;
  promcode:stateOfIssue <http://example.com/project/status#open> .
  1. PROMCODE Server returns the URL of issueX to the PROMCODE Server Web UI.
Example 48: Response - creating an Issue resource
HTTP/1.1 201 Created
Location:http://example.com/pm/issues/7010
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Length: 0 
  1. PROMCODE Server Web UI submits an HTTP PUT request to the PROMCODE Server to update the issueCollectionX to have the issueX.
Example 49: Request - updating an IssueCollection resource
PUT http://example.com/pm/issuecollections/710 HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/issuecollections/710>
  a promcode:IssueCollection ;
  dcterms:identifier "710" ;
  dcterms:title "issueCollectionX" ;
  promcode:belongsTo <http://example.com/pm/projects/100> ;
  promcode:collects <http://example.com/pm/issues/7010> .
Example 50: Response - updating an IssueCollection resource
HTTP/1.1 204 No Content 
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type" 
  1. PROMCODE Server Web UI displays the URL of issueX.

  2. Supplier notifies Acquirer that issueCollectionX is updated.

Acquirer reviews issues in the issueCollectionX and change plan.

  1. Acquirer sets the URL of issueCollectionX to get the resource to the PROMCODDE Server Web UI.

  2. PROMCODE Server Web UI submits an HTTP GET request to the PROMCODE Server, and retrieves the issueCollectionX.

  3. PROMCODE Server returns issueCollectionX resource to the PROMCODE Server Web UI.

  4. PROMCODE Server Web UI displays the issueCollectionX.

  5. Acquirer selects issueX on the PROMCODDE Server Web UI.

  6. PROMCODE Server Web UI submits an HTTP GET request to the PROMCODE Server, and retrieves the issueX.

  7. PROMCODE Server returns issueX resource to the PROMCODE Server Web UI.

  8. PROMCODE Server Web UI displays the issueX.

  9. Acquire reviews the issueX.

  10. Go to Plan Change scenario to change the plan if necessary.

Acquirer then closes the issueX

  1. Acquirer clicks the "Close Issue" button on the PROMCODE Server Web UI.

  2. PROMCODE Server Web UI changes the statusOfIssue property of the issueX to "Closed", and submits an HTTP PUT request to the PROMCODE Server.

Example 51: Listing of Issue resource
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/issues/7010>
  a promcode:Issue ;
  dcterms:identifier "7010" ;
  dcterms:title "Estimation for Make Reservation UI needs to be updated" ;
  promcode:raisedDate "2015-03-16T17:00:00Z" ;
  promcode:raisedFor <http://example.com/pm/scopeitem/1010> ;
  promcode:stateOfIssue <http://example.com/project/status#closed> .
  1. PROMCODE Server returns the closed issueX resource to the PROMCODE Server Web UI.

  2. PROMCODE Server Web UI displays the closed issueX.

8.3.7.1 Summary Sequence Diagram

The following sequence diagram summarizes Issue Management scenario:

Fig. 12 Issue Management

8.3.8 Plan Change

This scenario illustrates how OSLC PROMCODE 1.0 may be used in the process of Plan Change scenario described in chapter 6.3.2.5

8.3.8.1 Scenario

First, Acquirer gets the plan planX and the ScopeItem, WorkItem and Artifact resources that are associated with planX.

  1. Acquirer inputs the planX URL to PROMCODE Client for Spreadsheet.

  2. PROMCODE Client for Spreadsheet submits an HTTP GET request to the PROMCODE Server and retrieves the planX resource and associated projX resource.

  3. PROMCODE Client for Spreadsheet parses the planX resource and lists associated resources, such as ScopeItem, WorkItem and Artifact resources.

  4. PROMCODE Client for Spreadsheet then submits an HTTP GET request to the PROMCODE Server and retrieve the ScopeItem, WorkItem, Artifact and Measurement resources.

  5. PROMCODE Client for Spreadsheet parses the resources and converts them to human readable format to display the resources.

Next, Acquirer updates the ScopeItem, WorkItem, Artifact and Measure resources for the changes of plan.

  1. Acquirer updates the resources on PROMCODE Client for Spreadsheet

Next, Acquirer publishes the plan to the PROMCODE Server.

  1. Acquirer clicks the button "Update Plan" on the PROMCODE Client for Spreadsheet.

  2. PROMCODE Client for Spreadsheet submits an HTTP PUT request to the PROMCODE Server and updates ScopeItem resources in planX.

Example 52: Listing of ScopeItem resource
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/scopeitems/1010>
  a promcode:ScopeItem ;
  dcterms:identifier "1010" ;
  dcterms:title "Reservation System" ;
  promcode:plannedSize "25" ;
  promcode:actualSize "25" .
  1. PROMCODE Client for Spreadsheet creates a content of the Measure resource in RDF as a sub-resource of the Artifact resource.
  2. PROMCODE Client for Spreadsheet submit HTTP PUT request to the PROMCODE Server to update Artifact resource with new target value for Code size.
Example 53: Request - updating a Measure in the Artifact resource
PUT /pm/artifacts/2010 HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<http://example.com/pm/artifacts/2010>
  a promcode:Artifact ;
  dcterms:identifier "2010" ;
  dcterms:title "Make Reservation UI Source Code" ;
  promcode:producedFor <http://example.com/pm/scopeitem/1010> .
  promcode:targets <#measure_1>, <#measure_2> .

<#measure_1>
  a promcode:Measure ;
  dcterms:title "Code size (kloc)" ;
  promcode:value "15" ;
  promcode:metricOfMeasure <http://open-services.net/ns/ems/metric#Sloc> ;
  promcode:unitOfMeasure <http://open-services.net/ns/ems/unit#Loc> .
<#measure_2>
  a promcode:Measure ;
  dcterms:title "Number of defects" ;
  promcode:value "10" ;
  promcode:metricOfMeasure <http://open-services.net/ns/ems/metric#Defects> ;
  promcode:unitOfMeasure <http://open-services.net/ns/ems/unit#Defect> .
Example 54: Response - updating a Measure in the Artifact resource
HTTP/1.1 204 No Content 
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type" 
  1. PROMCODE Client for Spreadsheet creates a content of the Plan resource for planX-2 in RDF.

  2. PROMCODE Client for Spreadsheet extracts Plan Container from the projX resource, and submits an HTTP POST request that includes the planX-2 resource to the Plan Container.

Example 55: Request - creating an updated plan resource
POST /pm/projects/100/planContainer HTTP/1.1
Host: example.org
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Type: text/turtle

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix promcode: <http://open-services.net/ns/promcode#> .

<>
  a promcode:Plan ;
  dcterms:title "planX-2" ;
  promcode:belongsTo <http://example.com/pm/projects/100> ;
  promcode:collects <http://example.com/pm/scopeitems/1010>, <http://example.com/pm/scopeitems/1011>, 
                <http://example.com/pm/artifacts/2010>, <http://example.com/pm/artifacts/2011>,
                <http://example.com/pm/workitems/3010>, <http://example.com/pm/scopeitems/3011> .
  1. PROMCODE Server returns the URL of planX-2.
Example 56: Response - creating an updated plan resource
HTTP/1.1 201 Created
Location: http://example.com/pm/plans/201
Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
Content-Length: 0 
  1. PROMCODE Client for Spreadsheet displays the URL of planX-2 so that Acquirer can get the URL.

Now the Plan resource planX-2 is created and it’s ready to review by Supplier. Acquirer notifies the URL of planX-2 to Supplier.

  1. Acquirer sends an e-mail which contains the URL of planX-2.

Upon the notification, Supplier starts review of the change of the plan.

  1. Supplier gets the URL of planX-2 from the e-mail, then sets it to the PROMCODE Client for Spreadsheet.

  2. PROMCODE Client for Spreadsheet submits an HTTP GET request to the PROMCODE Server and retrieves the planX-2 resource.

  3. PROMCODE Client for Spreadsheet parses the planX-2 resources and lists associated resources, such as ScopeItem, WorkItem and Artifact resources.

  4. PROMCODE Client for Spreadsheet then submits an HTTP GET request to the PROMCODE Server and retrieves the ScopeItem, WorkItem and Artifact resources.

  5. PROMCODE Client for Spreadsheet parses the resources and converts them to human readable format. PROMCODE Client for Spreadsheet displays the resources.

  6. Supplier reviews the resources.

  7. Supplier notifies the result of review to Acquirer.

If necessary, Acquirer update the plan again by walking through the scenario again.

8.3.8.2 Summary Sequence Diagram

The following sequence diagram summarizes Plan Change scenario:

Fig. 13 Plan Change

9. Conformance

9.1 Conformance Targets

The PROMCODE specification defines conformance for PROMCODE Server implementations and PROMCOE Client Implementations

9.2 PROMCODE Server

The set of resources defined in Chapter 5 and 6 contains resources that represent comprehensive range of activities in project management. In practice, it is not uncommon that some subset of resources is used in project management. To address the situation, Conformance level is introduced.

A PROMCODE server is a basic server if it satisfies the following.:

A PROMOCODE server is a full server if it is a basic server and implements all the resources except container resources and their must level operations defined in Chapters 5 and 6. If the server uses LDP, it must also implement all the container resources and their operations in Chapters 5 and 6.

Three subsets of resources are used often in many project management activities, the set of ScopeItem, WorkItem and Artifacts, Plan and Report, and Issue and Risk. Therefore, the following servers are also defined.

A PROMOCODE server is a standard resource server, or standard server for short, if it is a basic server that implements at least ScopeItem, WorkItem and Artifacts. A PROMOCODE server is a plan and report server, or report server for short if it is a basic server that implements at least Plan and Report resources. A PROMCODE server is an issue and risk server or issue server for short if it is a basic server that implements at least Issue and Risk resources.

9.3 PROMCODE Client

A PROMCODE Client conforms this specification if it satisfies the following:

It implements all of must level client side resource operations as defined in Chapter 6 for the resources used by the client. These operations are used for obtaining resources from PROMCODE Servers

Appendix A. Change History

This section is non-normative.

Below is a summary of some of the changes in this draft.

Appendix B. Acknowledgments

This section is non-normative.

The editor and authors would like to thank the members of the PROMCODE Consortium for their constructive discussions during the development of the specification.

Appendix C. References

C.1 Normative references

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

C.2 Informative references

[HTTP11]
R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. June 2014. Proposed Standard. URL: https://tools.ietf.org/html/rfc7230
[LDP]
Steve Speicher; John Arwe; Ashok Malhotra. Linked Data Platform 1.0. 26 February 2015. W3C Recommendation. URL: https://www.w3.org/TR/ldp/
[OSLCCore2]
Dave Johnson; Steve Speicher. Open Services for Lifecycle Collaboration Core Specification Version 2.0. URL: http://open-services.net/bin/view/Main/OslcCoreSpecification
[OSLCCore3]
Jim Amsden; Martin Sarabura. OSLC Core 3.0. URL: http://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/trunk/specs/oslc-core.html
[PMBOK5]
A Guide to Project Management Body of Knowledge, 5th ed.. URL: http://www.pmi.org/
[PROMCODE13]
PROMCODE (PROject Management of COntracted Delivery), Interface Specification, Version 1. URL: http://www.promcode.org/
[PROMCODE14]
M. Aoyama; K. Yabuta; T. Kamimura; S. Inomata; T. Chiba; T. Niwa; K Sakata. A Resource-Oriented Services Platform for Managing Software Supply Chains and its Experience. URL: http://ieeexplore.ieee.org/xpl/login.jsp?tp=&arnumber=6928949&url=http%3A%2F%2Fieeexplore.ieee.org%2Fxpls%2Fabs_all.jsp%3Farnumber%3D6928949
[ROA]
Roy T. Fielding; Richard N. Taylor. Principled Design of the Modern Web Architecture.
[SPMC]
G. Ruhe; C. Wohlin (eds.). Software Project Management in a Changing World.
[WEBARCH]
Ian Jacobs; Norman Walsh. Architecture of the World Wide Web, Volume One. 15 December 2004. W3C Recommendation. URL: https://www.w3.org/TR/webarch/