OSLC query parameters
The OSLC query parameters provide options for how OSLC resources are queried. For example, the oslc.orderBy parameter defines the order of query results. The OSLC HTTP query parameters that are supported are oslc.properties, oslc.where, oslc.orderBy, oslc.select, oslc.pageSize, and pageno.
If a property is not in the General section of a form, you must specify the section name for the property, in the format sectionname#fieldname. For example, triDetails#triTaskTypeCL.
oslc.properties parameter
The oslc.properties query parameter specifies the list of properties for an OSLC resource. The properties can be from the resource itself or from a linked resource. It is used to get a partial representation of the resource. The oslc.properties parameter is not applicable to collection resources. A collection resource is an OSLC resource that has other OSLC resources as members.
Example: Requesting attributes
The following request example specifies that the values for the shortTitle and isTask attributes are returned in the results:http://yourserver/oslc/so/WorkTask/
337?oslc.properties=oslc:shortTitle,spi:isTask
Example: Requesting attributes from linked resources
The following request specifies that the value for the name of the customer organization is returned in the results:http://yourserver/oslc/so/WorkTask/
13353622?oslc.properties=*,spi:triCustomerOrgTX{spi:triNameTX}
This request produces the following results:{
spi:triNameTX: "WorkTask"
spi:triStatusCL: "Draft"
spi:triIdTX: "1027019"
-spi:triCustomerOrgTX: {
spi:triNameTX: "Company 01"
rdf:about: "http://yourserver/oslc/so/OrganizationRS/12877121"
}
rdf:about: "http://yourserver/oslc/so/triWorkTaskRS/13353622"
-trira:action: [10]
0: "triDelete"
1: "triInvalidUploadHidden"
2: "triIssue"
3: "triBaseline"
4: "triApplyTemplate"
5: "triCopy"
6: "triPlanHidden"
7: "triSave"
8: "triSaveAndClose"
9: "triTemporaryTemplate"
-prefixes: {
oslc: "http://open-services.net/ns/core#"
rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
trira: "http://jazz.net/ns/tririga#"
dcterms: "http://purl.org/dc/terms/"
}
}
oslc.where parameter
The oslc.where parameter specifies the WHERE clause for filtering the result set of a query. For example, you want to see a list of work task OSLC resources that were created within a time range and that are approved by management. You can filter by linked resources by using the oslc.where parameter. For example, you might want to filter people according to the name of the manager that the people report to.
Symbol | Description |
---|---|
= | Equality
Note that if you manually type the URI with this % symbol as part of the search, you must encode the symbol as follows: "%25value" |
!= | Inequality |
< | Less than |
> | Greater than |
<= | Less than or equal to |
>= | Greater than or equal to |
Requirements for the oslc.where parameter
Dates are expressed in ISO 8601 format. For Date and Time field types, milliseconds show if the field has a nonzero millisecond value.
The OSLC specification
supports and as the Boolean operator between Boolean
expressions. The Boolean operator or is not supported.
In the following example, the literal value for status is in quotation
marks as the status property has a data type of string. The quantity
value does not have quotation marks because it is a decimal data type.
Integers and Boolean values also do not require quotation marks. For
example, spi:status="Closed" and spi:quantity>10.5 and spi:active=true
where
spi:active has a Boolean data type.
The OSLC specification
supports or implicitly within a single property by using
the in operator. For example, to see all work tasks that
are in either Issued or Active status, use the query spi:status
in ["Issued","Active"]
Example: Searching for work tasks that were created within a time range and are approved
The following clause lists work task resources that were created within a specific time range:
spi:status="Approved" and dcterms:created>"2003-07-07T09:50:00-04:00"
and dcterms:created<="2004-07-07T09:50:00-04:00"
.
Using the oslc.orderBy parameter to specify the sort order
The oslc.orderBy parameter defines how the results of a query are ordered. For example, a list of work tasks can be ordered by date or by ID.
To arrange work tasks with the creation date in ascending order and the estimated duration in descending order, use the following oslc.orderBy parameter:+dcterms:created,-spi:estimatedDuration
.
The +
indicates an ascending sort order and the - indicates
a descending sort order. The values are separated by commas. The following oslc.orderBy parameter
is not valid because there is no default sort order in OSLC query
syntax: dcterms:created,-spi:estimatedDuration
. There
must be an explicit + or - with
the property name. The oslc.orderBy parameter
also supports nested properties, for example, dcterms:creator{+foaf:name}
.
In a real URL, +
and -
do not work.
You must use %2B and %2D in the URL instead.Example: Sorting based on linked resources
You can use the fields of linked resources as the order criteria, to sort the parent records and the linked resources inside of parent records.
For example, there might be two main objects that are named M1 and M2. M1 has two linked resources that are named L1 and L3 and M2 has the linked resources L2 and L4. If you sort the main objects in ascending order, without taking the linked resources into consideration, the results are M1, M2. If you sort the main objects in descending order, the results are M2, M1. However, because there are multiple linked resources for the objects, when you sort in ascending or descending order, the linked resources are also sorted. L1 and L3 are sorted within M1, L2 and L4 are sorted within M2.oslc.select parameter
The oslc.select parameter requests a partial resource representation of collection member resources. The oslc.select parameter always applies to a collection resource. You specify the list of properties to include in the request. The properties that you select can be from the resource itself or from a linked resource.Example: Partial resource request
The oslc.select parameter provides a comma-separated list of qualified property names. The oslc.prefix parameter is not supported.The following request is an example of a partial resource request:
oslc.select=oslc:shortTitle,dcterms:creator
Example: Properties from referenced resources
With the oslc.select parameter, you can select properties from referenced resources. To retrieve information such as the name of the creator, you specify the SELECT statement as
oslc.select=
oslc:shortTitle,dcterms:creator{foaf:name}
.
The foaf:Person
resource is the name of the person that is specified in the creator
property value. To get all properties from the resource, you can use oslc.select=*
.
The same syntax can be applied to the oslc.properties parameter
when you search for an OSLC resource.
Example: Properties from linked resources
With the oslc.select parameter, you can select properties from linked resources. To retrieve information such as the value for the name of the customer organization, you specify the SELECT statement ashttp://yourserver/oslc/spq/WorkTaskQC
?oslc.select=*,spi:triCustomerOrgTX{spi:triNameTX}
&oslc.where=spi:triCustomerOrgTX!="null"
This SELECT
statement gives the following response:{
-rdf:members: [1]
-0: {
spi:triNameTX: "WorkTask"
spi:triStatusCL: "Draft"
spi:triIdTX: "1027019"
-spi:triCustomerOrgTX: {
spi:triNameTX: "Company 01"
rdf:about: "http://yourserver/oslc/so/Organization/12877121"
}
rdf:about: "http://yourserver/oslc/so/WorkTask/13353622"
-trira:action: [10]
0: "triDelete"
1: "triInvalidUploadHidden"
2: "triIssue"
3: "triBaseline"
4: "triApplyTemplate"
5: "triCopy"
6: "triPlanHidden"
7: "triSave"
8: "triSaveAndClose"
9: "triTemporaryTemplate"
}
rdf:about: "http://yourserver/oslc/spq/WorkTask"
-prefixes: {
oslc: "http://open-services.net/ns/core#"
rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
spi: "http://jazz.net/ns/tririga#"
dcterms: "http://purl.org/dc/terms/"
}
}
oslc.pageSize parameter
The oslc.pageSize parameter specifies the number of results the server is to return per page. For example,oslc.pageSize=20
causes the query to
return 20 results per page.pageno parameter
The pageno parameter specifies the page that the server is to return. For example,pageno=3
causes
the query to return only the data for the third page.