SABLE Model Servers Web Service Specifications
Authors:
Patrick Houbaux (Eurostep)
Reference:
 SABLE-MSWS
Status:
 First draft proposal (18th Feb. 2003)
- Last update: 4th March. 2003. -
Reviewers: - Tero Hemio (Eurostep)
Legend:
 : an idea, a proposal, etc ...
: not sure about that, what do you think?

Introduction

These specifications aims to define and to unify the web service methods API exposed by the model servers available for SABLE (in green in the following picture).


The Model Servers Web Service should provide the following functionality:

The purpose of this specification is not to cover all possibilities that a normal SDAI API  can expose but to be pragamatic and minimalize the number of exposed methods for easiness and performance purposes.

Use cases

Session Management Use Cases
The session management set of web service method allows to connect, disconnect from a specific model server, select a project and inside the selected project, select a model.

In this use cases we assume the Project/Model hierarchy to be as the following:
  • Project represent a building project and is a container of models.
  • Models can represent the same building in different format (IFC 2.0, IFC 2x, etc ...), different buildings, different view of the same building (structural shape. concrete part, etc ...), etc ...
Use Case
MSWS-UC1
 Login
Description
 This describes the login procedure from a client application to a model server.
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 none
Flow of Events for Main Scenario
 1- Clients request the login session by sending a user name and password
2- The server sends back "Session Open" or "ERROR"
Alternative Scenarios
 none
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC2
 Select Project
Description
 This describes how the client applications select/activate a project on the model server
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
Flow of Events for Main Scenario
 1- Clients ask for selecting a project to the model server by sending the project name
2- The server sends back "Project selected" or "Project not Found" or "Session not open"
Alternative Scenarios
 none
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC3
 Select Model
Description
 		This describes how the client applications select/activate a model inside the current selected project on the model server
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
Flow of Events for Main Scenario
 1- Clients ask for selecting a model inside a project to the model server by sending the model name
2- The server sends back "Model selected" or "Model not Found" or "Project not selected" or "Session not open"
Alternative Scenarios
 none
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC4
 Logout
Description
 This describes how the client applications close a session from the model server.
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
Flow of Events for Main Scenario
 1- Clients request logout from the current session
2- The server sends back "Session closed"  or "Session not open"
Alternative Scenarios
 none
Postconditions
 none
Special conditions:
 none
Top
Queries Management Use Cases

The queries management set of web service method allows to store, run and delete Partial Model Queries on the server.

Use Case
MSWS-UC5
 Store Partial Model Query
Description
 This describes how to store a partial model query on the model server.
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
- Model Selected
Flow of Events for Main Scenario
 1- Clients send a Partial Model Query to store on the model server with a given name
2- The server analyses the validity of the query
3- The server stores the Partial Model Query
4- The server sends back "Query stored"
Alternative Scenarios
 A- Query format not valid: The query can be not valid in step 2. The server sends back "Query not validated"
B- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
C- Project/Model not selected: In step 1 the project might not be selected. The server sends back "No project/model selected"
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC6
 Execute Stored Partial Model Query
Description
 This describes how clients execute a stored Partial Model Query on the current selected model
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
- Model Selected
Flow of Events for Main Scenario
 1- Clients send the name of the query to run
2- The server sends back the requested Partial Model or "Partial Model Query not found"
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project/Model not selected: In step 1 the project might not be selected. The server sends back "No project/model selected"
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC7
 Get List of Stored Partial Model Queries
Description
 This describes how clients can get the available stored queries on the server for the current  project/model
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
- Model Selected
Flow of Events for Main Scenario
 1- Clients request the list of stored partial model queries
2- The server sends back the list of the stored query's names or "No Stored Partial Model Query"
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project/Model not selected: In step 1 the project might not be selected. The server sends back "No project/model selected"
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC8
 Get Definiton of Stored Partial Model Query
Description
 This describes how clients can get the definition of a Partial Model Query stored on the server associated with the current model.
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
- Model Selected
Flow of Events for Main Scenario
 1- Clients request  the definition of the a Partial model query by giving its name.
2- The server sends back the Partial Model Query Definition or "Partial Model Query not Found"
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project/Model not selected: In step 1 the project might not be selected. The server sends back "No project/model selected"
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC9
 Delete Stored Partial Model Query
Description
 This describes how clients can delete a stored PMQ
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
- Model Selected
Flow of Events for Main Scenario
 1- Clients request to delete a PMQ by giving its name
2- The server sends back "PMQ deleted" or "PMQ not found"
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project/Model not selected: In step 1 the project might not be selected. The server sends back "No project/model selected"
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC10
 Execute Partial Model Query
Description
 This describes how client can send and execute a PMQ
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
- Model Selected
Flow of Events for Main Scenario
 1- Clients request to execute a PMQ by sending the actual PMQ
2- The server analyses the validity of the query
3- The server executes the query
4- The server sends back the requested Partial Model
Alternative Scenarios
 A- Query format not valid: The query can be not valid in step 2. The server sends back "Query not validated"
B- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
C- Project/Model not selected: In step 1 the project might not be selected. The server sends back "No project/model selected"
Postconditions
 none
Special conditions:
 none
Top
Information Access Use Cases

The information requests set of web service method allows to access to the following information:
  • Project meta data information such as the name, description, partners, creater, timestamp of the creation of the project, etc...
  • Model meta data information such as associated project, version of the IFC schema, last modification timestamp, number of objects, etc...
  • The list of projects on the server
  • The list of models on the server in the current selected project in the session
  • The list of the corresponding server ID for a given entity type
  • The corresponding server ID to an IFC Global Unique ID
  • The list of users associated with a project
  • The list of roles associated with a project
Use Case
MSWS-UC11
 Get Project List
Description
 This describes how clients can access to the list of project available on the server
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
Flow of Events for Main Scenario
 1- Clients request the list of available projects on the server
2- The server sends back the list of IDs, names and access right for the current user of the available projects or "No Project Found"
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC12
 Get Project Meta Info
Description

This describes how clients access to a project meta information such as:

  • Name of the project,
  • Description of the project,
  • Users (company names),
  • Creater,
  • Creation Date,
  • ...
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
Flow of Events for Main Scenario
 1- Clients request the meta information of a project by sending its ID
2- The server sends back the meta data information or "Project not found"
Alternative Scenarios

A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Not authorized: the current user might not have the right to access to this information: the server send back "Not Authorized".

Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC13
 Set Project Meta Info
Description

This describes how clients can set a project meta information such as:

  • Name of the project,
  • Description of the project,
  • Users (company names),
  • Creater,
  • Creation Date
  • ...
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions

- Session open
- Project selected
Flow of Events for Main Scenario
 1- Clients send the meta data info to set by sending the name of the meta info and its value
2- The server performs a type checking
3- The server sends back "Meta Information set"
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project not selected: In step 1 the project might not be selected. The server sends back "No project selected"
C- Invalid meta information name: The step 2 can detect an invalid meta info name. The server sends back "Invalid Meta Information Name"
D- Invalid type: the step 2 can detect an invalid type. The server sends back "Invalid Type".
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC14
 Get Models List
Description
 This describes how client get the list of available models in a project
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
Flow of Events for Main Scenario
 1- Clients request the list of models for the current project
2- The server sends back the IDs, names and access rights for the current user of the available models or "No Model Found".
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project not selected: In step 1 the project might not be selected. The server sends back "No project selected"
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC15
 Get Model Meta Info
Description

This describes how clients access to a model meta information such as:

  • Associated project
  • IFC schema version
  • Last modification date
  • Number of objects
  • ...
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
Flow of Events for Main Scenario
 1- Clients request the meta information of a model by sending its ID
2- The server sends back the meta data information or "Model not found"
Alternative Scenarios

A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project not selected: In step 1 the project might not be selected. The server sends back "No project selected"
C- Not authorized: the current user might not have the right to access to this information: the server send back "Not Authorized".

Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC16
 Set Model Meta Info
Description

This describes how clients set the model meta information such as:

  • Associated project
  • IFC schema version
  • Last modification date
  • Number of objects
  • ...
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
- Model Selected
Flow of Events for Main Scenario
 1- Clients send the meta data info to set by sending the name of the meta info and its value
2- The server performs a type checking
3- The server sends back "Meta Information set"
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project not selected: In step 1 the project might not be selected. The server sends back "No project selected"
C- Model not selected: In step 1 the model might not be selected. The server sends back "No Model selected"
D- Invalid meta information name: The step 2 can detect an invalid meta info name. The server sends back "Invalid Meta Information Name"
E- Invalid type: the step 2 can detect an invalid type. The server sends back "Invalid Type".
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC17
 Get Model Statistics
Description

This describes how clients get some statistics information on the current model such as:

  • Total number of instances
  • Number of instances per entity type
  • etc ...
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
- Model Selected
Flow of Events for Main Scenario
 1- Clients request the statistics on the current model
2- The server sends back the statistics on the current model
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project not selected: In step 1 the project might not be selected. The server sends back "No project selected"
C- Model not selected: In step 1 the model might not be selected. The server sends back "No Model selected"
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC18
 Get ID From GUID
Description
 This describes how clients get the "database" ID of an instance from its IFC Global Unique ID in the current model.
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
- Model Selected
Flow of Events for Main Scenario
 1- Clients request the "database" ID of an instance by sending a GUID.
2- The server sends back the corresponding "database" ID or "GUID not Found"
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project not selected: In step 1 the project might not be selected. The server sends back "No project selected"
C- Model not selected: In step 1 the model might not be selected. The server sends back "No Model selected"
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC19
 Get ID List By Type
Description
 This describes how clients get the list of "database" ID for each instances of the given type.
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
- Model Selected
Flow of Events for Main Scenario
 1- Clients request the list of "database" ID of instances by sending an entity type.
2- The server sends back the list of "database" ID corresponding to the given type or "No Instance of this type in the current model"
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project not selected: In step 1 the project might not be selected. The server sends back "No project selected"
C- Model not selected: In step 1 the model might not be selected. The server sends back "No Model selected"
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC20
 Get Project Users
Description
 This describes how clients get the list of users involved in the current project and their corresponding roles.
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
Flow of Events for Main Scenario
 1- Clients request the list of users involved in the current project
2- The server sends back the list of users for the current project or "No users defined for the current project"
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project not selected: In step 1 the project might not be selected. The server sends back "No project selected"
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC21
 Get Project Roles
Description
 This describes how clients get the list of defined roles for the current project.
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
Flow of Events for Main Scenario
 1- Clients request the list of roles defined for the current project
2- The server sends back the list of roles or "No roles defined for the current project"
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project not selected: In step 1 the project might not be selected. The server sends back "No project selected"
Postconditions
 none
Special conditions:
 none
Top
Data Fetching Use cases

The idea on behind this set of use cases is to access to the data at the object level of granularity, which is not too small. When requesting an object, the client application should get this object and all attributes values and references ID to other objects without any differences if they are direct, inverse or derived attribute in the EXPRESS sense.

For example the "Get Object by ID" web service method should return the following information when requesting the instance of IfcWallStandardCase with "database" ID=1051019:
IFCWallStandardCase
 1051019
GlobalId
"3xidg1mF19uxSX4pW1fQsF"
OwnerHistory
1020818
Name
 		"Wall1"
Description
"This is a wall"
ObjectType
ObjectPlacement
 		1051041
Representation
 		1051016
Tag

IsDefinedBy
 		[1051077,1051896]
HasAssociations
 		[1051018]
HasAssignments

Decomposes

IsDecomposedBy
ReferencedBy

ConnectedTo
 		[1051060]
ConnectedFrom
 		[1051158]
ContainedInStructure
[1062121]
ProvidesBoundaries

HasOpenings
[1051046]
FillsVoids


The references to other instances in the same model are represented like 1051041

Use Case
MSWS-UC22
 Get Object by ID
Description
 This describes how clients get an instance of object with the given "database" ID.
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
- Model Selected
Flow of Events for Main Scenario
 1- Clients request an instance of object by sending its "database" ID.
2- The server sends back the object and all its attribute values (references to other instances are given by their "database" ID) or "No instances found with the given ID"
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project not selected: In step 1 the project might not be selected. The server sends back "No project selected"
C- Model not selected: In step 1 the model might not be selected. The server sends back "No Model selected"
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC23
 Get Objects by Type
Description
 This describes how clients get all instances of object of the given entity type in the current model.
Actors
 - SABLE model server Client
- Client Application
- Model server
Preconditions
 - Session open
- Project Selected
- Model Selected
Flow of Events for Main Scenario
 1- Clients request all instances of object by sending an entity type.
2- The server sends back all instances and their corresponding attribute values (references to other instances are given by their "database" ID) or "No instances found of the given entity type"
Alternative Scenarios
 A- Session not open: In step 1 the session can be not open: The server sends back "Session not open"
B- Project not selected: In step 1 the project might not be selected. The server sends back "No project selected"
C- Model not selected: In step 1 the model might not be selected. The server sends back "No Model selected"
Postconditions
 none
Special conditions:
 none

Use Case
MSWS-UC24
 Get Containment Tree
Description

This describes how clients get the containment hierarchy for the current model as a tree containing name of objects and their corresponding "database" ID:

Model
+-Corresponding Project
| +-Site1 <1051041>
| | +-Building1 <