Skip to end of metadata
Go to start of metadata

Brief Description

Describes an entity for an organization or any contextually-meaningful organizational unit. Organizations may be structured so that there are organizational units (also departments, subdivisions) within an Organization. For example, there may be a Conservation Department within a museum; or museums and organized research units (ORUs) within a university. An organization may be modeled in multiple hierarchies, e.g., structural vs. financial within a larger institution, and also in various membership relations (e.g., an organization of regional museums). For a full description, visit the Service Description and Assumptions page.

Assumptions

  • Organizations group hierarchically, e.g., departments into divisions, divisions into museums, museums into an umbrella institution.
  • Organizations may participate in more than one hierarchy. E.g., a given museum may be structurally defined as part of a university department, but be financially part of a collection of research units. It may also be part of a consortium of affiliated museums. We want to represent multi-hierarchy, and may need to name the different hierarchies.
For a complete list of assumptions, visit the Service Description and Assumptions page.

References

Vocabulary and Authority Overview
Organization Service Description and Assumptions
Organization Service Entity Diagrams
Name Authority Schema and Name Authority Schema - Limited for Release 0.8

REST-based API

The Organization Service offers a REST-based Application Programming Interface (API) to CRUD (create, read, update, and delete) operations on individual OrganizationAuthority instances, and on the associated Organization instances. These follow the Common model for CollectionSpace REST services.

Note that the Organization instances are not directly "addressible"; they can only be accessed via the parent OrganizationAuthority.

OrganizationAuthority CRUD+L services

Create an OrganizationAuthority

Creates a new OrganizationAuthority record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that OrganizationAuthority record. Follows standard Create model. See the documentation of the OrganizationAuthority schema, below. Example:

Read an OrganizationAuthority

Reads an existing OrganizationAuthority record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the OrganizationAuthority schema, below. Example:

Update an OrganizationAuthority

Updates an existing OrganizationAuthority record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the OrganizationAuthority schema, below. Example:

Delete an OrganizationAuthority

Deletes an existing OrganizationAuthority record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:

List OrganizationAuthority instances

Lists existing OrganizationAuthority records, with summary information for each. Follows standard List model, with pagination support. See the documentation of the OrganizationAuthority-List schema, below.

List supports query parameters for customizing list results, such as pagination controls, query filters, and sorting options. For example:

List also supports query parameters for searching for matching records, including keyword search. For example:

OrganizationAuthority REST payload schemas

Icon

The schemas below are abbreviated, and are thus illustrative. For a full list of the fields that may potentially be present in payloads when creating, updating, or reading individual OrganizationAuthority records, please see the most recent OrganizationAuthority schema.

OrganizationAuthority instance schema

Create and Update should use the following schema. The value of vocabType must be "OrgAuthority".

Read will return the above, plus additional fields (uri and csid) for access:

OrganizationAuthority-List schema

List (and variants) will return the following schema.

Organization CRUD+L services

Organization instances are only accessible via the owning OrganizationAuthority. The sub-resource is accessed with "items" (for consistency across all vocabulary-like services). In the examples below, the {org-auth-id} parameter represents an identifier (such as a CSID value or Short Identifier) of an existing OrganizationAuthority instance.

Create an Organization in an OrganizationAuthority

Creates a new Organization record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that Organization record. Follows standard Create model. See the documentation of the Organization schema, below. Example:

You may also POST a part called

and any new relations there will be created. For example, this POST will add a relationship. Note that you must know beforehand the CSIDs of related terms. These are shown here as the values 33380624-7f46-4e7a-962c and 22280624-7f46-4e7a-962c. These are the CSIDs of two other Organization records, which must exist before this call. The special variable ${itemCSID} will be expanded to the CSID of the newly created Person.

NOTE: if you wish to delete related items,
simply send relations-common-list as an empty element.
This is shown in a comment here:
http://wiki.collectionspace.org/display/collectionspace/Person+Service+REST+APIs?focusedCommentId=72220749&#comment-72220749

Read an Organization in an OrganizationAuthority

Reads an existing Organization record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the Organization schema, below. Example:

There are additional query parameters to get the relations for this item.
Query Parameters are defined and explained here, with examples: Authority REST API for Hierarchies

Update an Organization in an OrganizationAuthority

Updates an existing Organization record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the Organization schema, below. Example:

You may also PUT a part called

<ns3:relations-common-list>
and any new relations there will be created. Relations to the updated item which are missing from the relations list in the PUT will be deleted from persistence. No target records are deleted, just the relations records that point to target records. e.g. POST to authority with Organization "Sub-Org", with relations-common-list that has an entry for ${itemCSID} hasBroader "Parent-Org" creates a relations record that references both Sub-Org and Parent-Org. When a PUT is made that does not have the relation for Parent-Org, then Sub-Org has no relations, so the relations record for Sub-Org==>hasBroader==>Parent-Org is deleted, but both "Sub-Org" and "Parent-Org" Person records remain.

Delete an Organization in an OrganizationAuthority

Deletes an existing Organization record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:

List Organization instances in an OrganizationAuthority

Lists existing Organization records, with summary information for each. Follows standard List model, with pagination support. See the documentation of the Organization-List schema, below.

List supports query parameters for customizing list results, such as pagination controls, query filters, and sorting options. For example:

List also supports query parameters for searching for matching records, including:

  • keyword search
  • partial term matching search, for term completion
  • term status filtering, to exclude (filter out) records matching one or more statuses

For example:

Organization REST payload schemas

Icon

The schemas below are abbreviated, and are thus illustrative. For a full list of the fields that may potentially be present in payloads when creating, updating, or reading individual Organization records, please see the most recent Organization schema (i.e. for an individual Organization term within a OrganizationAuthority or vocabulary).

Organization instance schema

Create and Update should use the following schema.

Icon

On create, the value of inAuthority must match the identifier of the parent OrganizationAuthority, and will not be modified once the instance is created.

You can view the full set of validation constraints on the data you submit when creating or updating Organization instance records, in the most recent CollectionSpace code, via this Java source code file.

Read will return the above, plus additional fields (uri and csid) for access:

Related Organization term records

As of v1.7, Authorities return list items of related terms in a new part. NOTE the new section called

Here is a payload for a POST or PUT to /cspace-services/orgauthorities/{csid}/items/{person-csid}

NOTE: the special variable ${itemCSID} will be expanded to the CSID generated for the current AuthorityItem. (For Java use, please use the constant in CommonAPI.AuthorityItemCSID_REPLACE )
So if you POST to orgauthorities and you include relations-common-list, then the item is the organization you posted, so it gets created first, then in all the relations listed in relations-common-list, they refer to that item.

The elements are documented in the Relations service REST APIs:
http://wiki.collectionspace.org/display/collectionspace/Relationship+Service+RESTful+APIs

Organization-List schema

List (and variants) will return a schema similar to the following example:

Contact CRUD+L services

Each Organization may have one or more instances of Contacts.

Contacts are only accessible via the owning Organization. The sub-resource is accessed with "contacts". In the examples below, the {org-auth-id} parameter represents an identifier (such as a CSID value or Short Identifier) of an existing OrgAuthority instance, and the {organization-id} represents an identifier (such as a CSID value or Short Identifier) of an existing Organization item.

Create a Contact for an Organization

Creates a new Contact record for an Organization. Assigns a unique, service-specified CollectionSpace ID (CSID) to that Contact record. Follows standard Create model. See the documentation of the Contact schema, below. Example:

Read a Contact for an Organization

Reads an existing Contact record for a Organization, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the Contact schema, below. Example:

Update a Contact for an Organization

Updates an existing Contact record for an Organization, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the Contact schema, below. Example:

Delete a Contact for an Organization

Deletes an existing Contact record for an Organization, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:

List Contacts for an Organization

Lists existing Contact records for an Organization, with summary information for each. Follows standard List model. See the documentation of the Contact-List schema, below.

List supports query parameters for customizing list results, such as pagination controls, query filters, and sorting options. For example:

List also supports query parameters for searching for matching records, including keyword search. For example:

Contact REST payload schemas

Icon

The schemas below are severely abbreviated, and are thus illustrative. For a full list of the fields that may potentially be present in payloads when creating, updating, or reading individual Contact sub-resource records, please see the Contact record schema for release 0.8.

Contact Instance schema

Create and Update should use the following schema.

Read will return the above, as well. The example below shows the full set of attributes returned on the root element:

Contact List schema

List (and variants) will return the following schema.