Note this article is no longer updated. Please view the Postman API Collection for the latest updates. 

This article provides user documentation for the Symplectic Elements API and provides your technical staff with the ability to fully integrate staff research data in either direction with any of the systems at your institution. Please review the Requests and Responses article for additional information.

The API consists of a set of resources addressable by their URIs, and for each resource a set of operations that can be performed on the resource.

Each operation is described by the URI of the resource on which to operate, the HTTP method (GET, DELETE, PUT or POST) and a request content XML document (in the case of POST or PUT). Please note that all request content XML must be specified in the API XML namespace.

e.g.

• GET /users

• POST /suggestions/relationships/8

Where an operation requires request content, such as the POST operation above, the definition of the content XML element can be found in the API XML Schema Document supplied with this documentation.

The response to a successful API operation is indicated by the expected HTTP response status code. In this case the expected API-namespaced content of any ATOM feed document in the response body is also returned.

An unsuccessful operation is any operation that does not return one of the expected HTTP success response status codes, and in this case an ATOM error feed is also returned (see the section earlier on Error Responses) if the API began executing application-level code.

Where a URI contains a path element wrapped by braces, it represents a parameter name. Substitute a value directly in to the path of the URI in place of the braced expression. Such a parameter is required and must be URI-encoded.

Where a URI accepts query parameters, they are clearly labelled as either required or optional. Regardless, the order of the parameters does not matter. The parameter values are indicated by curly braces. You should substitute in your desired value in place of the braced place holders and suitably URI encode your values. For example, if your value includes spaces, you must use the URI space reference encoding of “%20”.

Many operations offer the same parameters with their usage. Some of these parameters are covered here for convenience.

When using this parameter, use of any other parameters except any available detail and per-page parameters is an error.

Where available, use this parameter to access a known list of data items with one single query. The format of the ids parameter is a comma-separated list of ids appropriate to the type of data being requested.

For example: /relationships?ids=1,45,67

The above query would return a feed containing three relationships: the relationships with IDs 1, 45 and 67, in that order.

If any of the data entities do not exist, the results set will not contain them. The order in which the results are returned is the same as the order in which you list the IDs. You can list as many IDs as will not cause your generated URL to be an invalidly large URL.

Please note for a paginated resource, the response is paginated as per normal. If you list more IDs that there are items per page of response, you must paginate through the response to retrieve all of the returned objects.

This parameter acts as a continuation token and is used to retrieve the next page of results. This parameter is generated for paginated resources via the API and users should not create or modify this parameter

See the section on Pagination for a discussion of how to navigate through paginated results.

This query parameter determines how many results are returned in each page of the response. If omitted, the value "25" is assumed and the API will return 25 items per page of results.

See the section on Pagination for a discussion of how to navigate through paginated results.

This query parameter determines the detail level of the response. If omitted, an operation-specific value of either "ref" of "full" is assumed and the operation will return either references or full details respectively.

See the section on Response Detail Level for a discussion of the detail levels of API responses.

This query parameter is used to restrict to objects and relationships modified since the supplied moment in time. If omitted, this restriction is not applied. Objects and relationships created since the specified moment are considered modified, and are included in the results set.

The value of this parameter should be in XML Schema dateTime format, which is inspired by the ISO 8601 standard. Always specify the time-zone. Always specify a time of day down to the second.

Acceptable examples include:

• 2008-06-01T21:36:19.677+01:00

• 2008-03-01T13:00:00Z

• 1999-01-01T00:00:00+00:00

Remember to encode your value for use in a URI. For example:

https://localhost:8091/publications-api/publications?modified-since=2008-03-01T13%3A00%3A00Z

Where you see the place holder {cat} or {cats}, you must substitute one of the following singular (or plural) category names as appropriate.

The base URI provides an otherwise undocumented front page to the API that can be used to immediately get you up and running by providing you with some links representing sample queries in the system. It is not considered a part of the API and so its response is not documented either here or in the schema document and its content is liable to change at short notice.

This resource represents the objects of a given category, and can be used to search amongst them. For example, /publications represents all publications, and /users all users.

Use this operation to search for users, publications etc..

?ids={idList} Optional: defaults to null

&query={query} Optional: defaults to null

&authority={authority} Optional: defaults to null

&username={username} Optional: defaults to null

&proprietary-id={proprietaryID} Optional: defaults to null

&ra-unit-id={ra-unit-id} Optional: defaults to null

&groups={groups} Optional: defaults to null

&group-membership={explicit | implicit} Optional: defaults to implicit

&ever-approved={everApproved} Optional: defaults to null

&created-since={createdSince} Optional: defaults to null

&modified-since={modifiedSince} Optional: defaults to null

&affected-since={affectedSince} Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

&detail={detail} Optional: defaults to ref

&types={types} Optional: defaults to null

The following URL lists all publications associated with one of your departments: /publications?groups=12

The query parameter is used to restrict the response to only those objects matching the query string. If omitted, this restriction is not applied.

The circumstances under which a query string matches an object is a fairly complicated calculation that depends on the category of object being tested and the relationships the object has with others, so that a sensible results set is returned.

/users?query=blood AND flow

The above search will return all users who work in the area of "blood flow" (the criterion for which is calculated partly by whether a user is the author of any publications matching the query "blood flow", etc.), whereas the following query will return all publications directly matching the query "blood flow".

/publications?query=blood AND flow

The following query will return publications of the type journal-article or artefact:

/publications?query=type="journal-article" OR type="artefact"

This parameter can only be used with the /users resource.

This query parameter is used to restrict to users authenticated by the authenticating-authority with the specified ID. If omitted, this restriction is not applied.

The authenticating authority for a user is the system in your institution that is responsible for authenticating the user and is determined by your institution. Use this parameter to distinguish between two users with the same username who “belong” to different authentication systems in your institution. You must contact your Elements system administrator to get the IDs of the relevant authentication authorities in your institution. Note that if the administrator has configured a user to be authenticated by the Elements System itself (i.e. their password is stored in the Elements System and managed by the administrator), then their authenticating authority ID is always the string “Internal”.

This parameter can only be used with the /users resource.

This query parameter is used to restrict to users to those with the given username. If omitted, this restriction is not applied.

The username is used by the user to log in to the Elements System and is provided by your institution.

This parameter can only be used with the /users resource.

This query parameter is used to restrict to users with the given proprietary ID. If omitted, this restriction is not applied.

The proprietary ID of a user is a unique ID given to the user by your institution. Note that at most one user can be returned if this parameter is supplied.

This parameter can only be used with the /users resource.

This query parameter is used to restrict to users in a given research assessment unit. If omitted, this restriction is not applied.

The format of the parameter value is a single integer ID value. See the /ra-units resource for the IDs of the research assessment units defined by your institution.

To use this parameter, your API account requires RA rights. See the /my-account resource to view your current rights. Use of the parameter without RA rights will cause an "unauthorised access" error.

This query parameter is used to restrict to /users in any one of a collection of user-groups and other /{cats} directly related to any user in the specified collection of groups. If omitted, this restriction is not applied.

The format of the parameter value is a comma-delimited list of group ID values, with no spaces. See the /groups resource for the IDs of the groups defined by your institution.

For example, to return all users who are in either of groups 1 and 5 the following URI should be used:

/users?groups=1,5

To return all publications related to the users in group 12:

/publications?groups=12

This query parameter is used in conjunction with the groups parameter. If present, restrict to /users in any one of a collection of user-groups and other /{cats} directly related to any user either explicitly or implicitly in the specified collection of groups. If omitted, this restriction is not applied. Defaults to implicit membership.

For example, to return all users who are explicitly in group 4 the following URI should be used:

/users?groups=4&group-membership=explicit

The group-membership parameter was introduced in Elements v4.12 and is only available in v4.9 API endpoints and above.

This query parameter allows you to filter your results according to whether an object has ever been classed as approved research data by your institution. The definition of approved research data is:

• Any user

• Any object imported through the API

• Any object with at least one relationship to another object

There are practical reasons why you might with to restrict to data for which ever-approved=true. For instance, if you are implementing a data synchronisation to another system, you may wish to skip all publications that have never been approved by a user. Such publications are often just false positive search results that have arrived from external data sources.

This query parameter is used to restrict to objects modified since the supplied moment in time. If omitted, this restriction is not applied. Objects created since the specified moment are considered modified, and are included in the results set.

The value of this parameter should be in XML Schema dateTime format, which is inspired by the ISO 8601 standard. Always specify the time-zone. Always specify a time of day down to the second.

Acceptable examples include:

• 2008-06-01T21:36:19.677+01:00

• 2008-03-01T13:00:00Z

• 1999-01-01T00:00:00+00:00

Remember to encode your value for use in a URI. For example:

https://localhost:8091/publications-api/publications?modified-since=2008-03-01T13%3A00%3A00Z

This query parameter is used to restrict to objects affected since the supplied moment in time. If omitted, this restriction is not applied. Objects created since the specified moment are considered affected, and are included in the results set. The affected since date differs from modified since in that, in addition to the events that cause modification, changes to linked objects also result in an object being included. See the modified since parameter for details of how to use the parameter.

This query parameter is used to restrict to objects created since the supplied moment in time. If omitted, this restriction is not applied.  See the modified since parameter for details of how to use the parameter.

This parameter is used to restrict results to items of a given object type.

For example, to return all publications of type book or journal-article the following URI should be used:

/publications?types=book,journal-article

The types parameter was introduced in Elements v5.0 and is only available in v4.9 API endpoints and above.

This resource represents an individual object in the Elements system. Any valid identifier {id} in the Object Identifier Format can be used.

When using the resource to get an object, the object is described by an object element.

Use this operation to retrieve a user, publication etc.

?detail={detail} Optional: defaults to full

Supports ETag and Last-Modified headers.

The {id} part of the URL identifies which object is to be viewed using the Object Identifier Format. Examples include:

/users/8

/users/username-jdjones

/users/pid-00412

/publications/1

/publications/source-wos,pid-WOS:000084595500286

Always remember to URL-encode the value of any strings you use.

Introduced in Elements v5.1.1

Use this operation to modify object level labels on an existing object. Expects an update-object XML element in the request body.

The ability to modify reporting added in Elements v5.5.

Required headers

Content-Type: text/xml

?detail={detail} Optional: defaults to full

&validate={validate} Optional: defaults to false

These resources represent relationships of an individual object to those in another category. Any valid identifier {id} in the Object Identifier Format can be used.

Use this operation to list or search amongst all publications related to a particular user, or all projects related to a particular publication, etc.

?types={types} Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

&detail={detail} Optional: defaults to ref

&modified-since={modifiedSince} Optional: defaults to null

The following operation lists the full details of all publication-authorship relationships involving the user with username "jdjones":

GET /users/username-jdjones/publications?types=8&detail=full

See the GET /relationships operation for descriptions of the usage of parameters in common with this operation.

These resources represent the relationships of an individual object. Any valid identifier {id} in the Object Identifier Format can be used.

Use this operation to list or search amongst all objects related to a particular user, or all objects related to a particular publication, etc.

?also-involving={object-identifier} Optional: default to null

&types={types} Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

&detail={detail} Optional: defaults to ref

&modified-since={modifiedSince} Optional: defaults to null

The following URL lists the full object details of all objects related to the user with username "jdjones":

/users/username-jdjones/relationships?detail=full

See the GET /relationships operation for descriptions of the usage of parameters in common with this operation.

This resource represents an individual record within an object in the Elements system, as identified by the proprietary identifier given to it by the data source from which it came.

When using the resource to get a record, the whole object to which the record belongs is in fact returned, and it is returned as an

Use this operation to retrieve a record imported from an external data source when you know the record’s external identifier.

{source} Required: either the string name or integer ID of the external data source can be supplied

{proprietary-id} Required: the identifier of the record as assigned by the external data source

?detail={detail} Optional: defaults to full

Supports ETag and Last-Modified headers

GET /publication/records/arxiv/abs%2F1203.4219 will return the arXiv record with arXiv identifier abs/1203.4219. Always remember to URL-encode the value of any strings you use as parameters.

Note that you can identify the data source by its ID or by its name. See the API XML schema for more information about data sources.

This operation does not return an element as you might expect. Rather it returns an object element, describing the whole object to which the record belongs. In fact, this resource acts as an alias for the resource representing the object containing the record.

Use this operation to create a new record or update an existing record.

Content-Type: text/xml

?validate={validate} Optional: defaults to false

&detail={detail} Optional: defaults to full

&update-reporting-dates={true | false} Optional: defaults to false. When true, update the reporting dates of the object using the import record data. This parameter was introduced in Elements v5.0 and is only available in v4.9 API endpoints and above.

&update-object-type={true | false} Optional: defaults to false. When true, the object to which the record belongs will have it's type updated to the type-name or type-id provided in the xml. For example, updating a book to a book chapter. This parameter was introduced in Elements v5.3 and is only available in v4.9 API endpoints and above.

Use this operation to modify field values on an existing record.

Content-Type: text/xml

?validate={validate} Optional: defaults to false

&detail={detail} Optional: defaults to full

&update-reporting-dates={true | false} Optional: defaults to false. When true, update the reporting dates of the object using the import record data. This parameter was introduced in Elements v5.0 and is only available in v4.9 API endpoints and above.

&update-object-type={true | false} Optional: defaults to false. When true, the object to which the record belongs will have it's type updated to the type-name or type-id provided in the xml. For example, updating a book to a book chapter. This parameter was introduced in Elements v5.3 and is only available in v4.9 API endpoints and above.

Use this operation to delete a record. If an existing record is removed, a HTTP 204 (No Content) response is made.

This resource represents the collections of external data sources configured for the specified data category (except for users).

For example, /publication/sources represents the configured publication data sources and will list, amongst others, information about the Web of Science, PubMed and Scopus, as well as the "manual-entry" data source.

Users are not included in this set of resources, since their data model is slightly different from those of the other categories.

Use this operation to get the details of all data sources for a category of data.

GET /publication/sources

This resource represents the declined relationship suggestions involving a particular object. Any valid identifier {id} in the Object Identifier Format can be used.

Use this operation to find all declined relationship suggestions involving a particular object.

{id} Required: Object Identifier Format

?types={types} Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

&detail={detail} Optional: defaults to ref

&modified-since={modifiedSince} Optional: defaults to null

The following operation lists the full relationship suggestion and related object details of all declined relationship suggestions involving user 8:

GET /users/8/suggestions/relationships/declined?detail=full

See the GET /suggestions/relationships/declined operation for descriptions of the usage of parameters in common with this operation.

This resource represents the declined relationship suggestions involving a particular object, where the other object is restricted to a particular category. Any valid identifier {id} in the Object Identifier Format can be used.

Use this operation to find all declined publication/activity/etc relationship suggestions involving a particular object.

{id} Required: Object Identifier Format

?types={types} Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

&detail={detail} Optional: defaults to ref

&modified-since={modifiedSince} Optional: defaults to null

The following operation lists the full relationship suggestion and related publication details of all declined publication relationship suggestions involving user 8:

GET /users/8/suggestions/relationships/declined/publications?detail=full

See the GET /suggestions/relationships/declined operation for descriptions of the usage of parameters in common with this operation.

This resource represents the pending relationship suggestions involving a particular object. Any valid identifier {id} in the Object Identifier Format can be used.

Use this operation to find all pending relationship suggestions involving a particular object.

{id} Required: Object Identifier Format

?types={types} Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

&detail={detail} Optional: defaults to ref

&modified-since={modifiedSince} Optional: defaults to null

The following operation lists the full relationship suggestion and related object details of all pending relationship suggestions involving user 8:

GET /users/8/suggestions/relationships/pending?detail=full

See the GET /suggestions/relationships/pending operation for descriptions of the usage of parameters in common with this operation.

This resource represents the pending relationship suggestions involving a particular object, where the other object is restricted to a particular category. Any valid identifier {id} in the Object Identifier Format can be used.

Use this operation to find all pending publication/activity/etc relationship suggestions involving a particular object.

{id} Required: Object Identifier Format

?types={types} Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

&detail={detail} Optional: defaults to ref

&modified-since={modifiedSince} Optional: defaults to null

The following operation lists the full relationship suggestion and related publication details of all pending publication relationship suggestions involving user 8:

GET /users/8/suggestions/relationships/pending/publications?detail=full

See the GET /suggestions/relationships/pending operation for descriptions of the usage of parameters in common with this operation.

This resource above represents the collection of types of object for the given category.

For example, Users are not included in this set of resources, since their data model is slightly different from those of the other categories.

Use this operation to get information about all configured object types for a given category.

GET /publication/types will return all configured publication types and will include, amongst others, information about the journal article, software, and conference proceeding types of publications.

This resource represents all deleted objects of the given category.

Use this operation to find out which objects of a given category have been deleted. You might use the results of this operation to reflect deletions in a system that caches Elements research data.

?deleted-since={deletedSince} Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

The following operation lists all publications deleted since a given moment in time:

GET /deleted/publications?deleted-since=2009-10-25T13%3A34%3A00Z

This resource represents a deleted object.

Use this operation to find out information about a deleted object, such as when it was deleted.

The following operation lists the details of the deletion of publication 85:

GET /deleted/publications/85

See the schema for more information about the data returned for deleted objects.

This resource represents all files stored in Elements DB. For example, user photos and impact evidence. Not to be confused with repository files, which are not stored in Elements.

Operation: GET

Use this operation to retrieve information about files. HR access level required to retrieve user photos.

An atom feed of file-info elements will be returned. See the schema for more information about the data.

?after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

This resource represents a file stored in the Elements database.

Use this operation to retrieve a file.

GET /files/3

This resource represents all the administrative user groups defined within Elements.

Use this operation to list all the user groups defined in the system.

This resource represents all of the Annual Collections defined in the system.

Use this operation to find all Annual Collections in the system.

This resource represents an Annual Collection defined in the system. Any valid Collection {year} in the format yyyy can be used. The resource does not exist if no Collection for the specified year has been created.

Use this operation to find a single Annual Collection.

Example

The following operation gets the Annual Collection for 2012:

GET /herdc/returns/2012

This resource represents groups defined for a given Annual Collection. Any valid Collection {year} can be used.

Use this operation to find all groups for an Annual Collection.

The following operation gets the Annual Collection groups for year 2012:

GET /herdc/returns/2012/groups

This resource represents nominations for an Annual Collection defined in the system. Any valid Collection {year} can be used.

Use this operation to find all nominations for an Annual Collection.

?status={status} Optional: defaults to null

&category={category} Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

&detail={detail} Optional: defaults to ref

The following operation gets the Annual Collection nominations in full detail for year 2012 with status accepted and category 157:

GET /herdc/returns/2012/nominations?status=accepted&category=157?detail=full

The following operation returns all nominations for the 2012 Annual Collection:

GET /herdc/returns/2012/nominations

Use this parameter to restrict the returned nominations to those whose status matches the supplied value. See the API schema document for possible values of nomination status.

For example:

/herdc/returns/2012/nominations?status=declined

The above query would return a feed containing all declined nominations for the 2012 Annual Collection.

Use this parameter to restrict the returned nominations to those of a given Annual Collection category. See the parent /herdc/returns/{year} resource for details of the configured categories for the relevant Collection. Such categories are identified numerically.

For example:

/herdc/returns/2012/nominations?category=157

The above query would return a feed containing all “category 157” nominations for the 2012 Annual Collection. Your administrator will previously have defined category 157 of the 2012 Annual Collection to mean, perhaps, “journals”.

Use this operation to nominate a publication for an Annual Collection. The publication must have its Reporting Date in the Collection year.

See the Examples section for a walk-through of the request data you must supply when using this operation.

Content-Type: text/xml

?validate={validate} Optional: defaults to false

HTTP 201 (Created) is returned if a new nomination was created, and the "Location" header is set to the URL of the created nomination. A representation of the nomination is returned in the response content.

HTTP 200 (OK) is returned if a publication has already been nominated. A representation of the nomination is returned in the response content.

This resource represents a single Annual Collection nomination defined in the system. Use any valid Collection {year} and nomination {id}. Alternatively, you can use a publication object identifier instead of nomination ID to get a nomination for a specified publication.

More info about the object identifier format can be found in the Requests and Responses article.

Use this operation to view a single HERDC nomination.

The following operation returns the nomination with ID 29 belonging to the 2012 Annual Collection:

GET /herdc/returns/2012/nominations/29

The following operation returns the nomination for a publication with ID 1566:

GET /herdc/returns/2012/nominations/publication(1566)

Use this operation to update an Annual Collection nomination status.

See the Examples section for a walk-through of the request data you must supply when using this operation.

Content-Type: text/xml

?validate={validate} Optional: defaults to false

HTTP 200 (OK) is returned if the nomination status has been updated. A representation of the nomination is returned in the response content.

This resource represents all label schemes configured in the system

GET /label-schemes

This resource represents a label scheme configured in the system including label ontology.

The following operation returns the Fields of Research label scheme. 

GET /label-schemes/for

This resource represents the details of the currently authenticated API account.

Use this operation to see the details of the currently authenticated API account. The response includes your account username, and details of

• whether your account has access to sensitive HR data

• whether your account has access to staff research assessment data

• whether your account is able to modify data in the Elements database

See the section on API account rights for more information about what these rights represent.

Note: if you are accessing the API via an unsecured endpoint, this page will display the details of an anonymous account, which is shown to have been granted none of the available rights.  However, as will be noted on the page itself, all account-based rights checks are bypassed on an unsecured endpoint.

This resource represents the entire collection of relationships between objects in the system, and can be used to search for and update relationship data. One example is to search for all publications authored by a particular user.

When searching for relationships you may find it more convenient to use the GET /{cats}/{id}/relationships or GET /{cats}/{id}/{cats2} resources.

Use this operation to list all relationships in the system, or search for relationships involving a given object or between a given pair of objects. You can also restrict by relationship type (such as publication authorship).

?ids={idList} Optional: defaults to null

&involving={object-identifier} Optional: defaults to null

&also-involving={object-identifier} Optional: defaults to null

&types={types} Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

&detail={detail} Optional: defaults to ref

&modified-since={modifiedSince} Optional: defaults to null

The following operation lists the full publication details of all publications authored by the user with username "jdjones":

GET /relationships?involving=user(username-jdjones)&types=8&detail=full

Note that this search can also be achieved with the operation GET /users/username-jdjones/publications?types=8.

Restricts the relationships returned to those involving the specified object. To specify the object, use the Object Identifier Format.

If using this parameter, you must also use the involving parameter.

Further restricts the relationships returned to those also involving the specified second object. To specify the second object, use the Object Identifier Format. If you specify the same object as is specified with the "involving" parameter, only self-referencing relationships are returned.

The types parameter can be used to restrict the response to relationships that are of any of the listed types. If omitted, this restriction is not applied.

The format of the types parameter is a comma-delimited list of relationship type IDs (integers) with all white space trimmed.

For example, an operation to return all publications authored or edited by the user with ID 5 is:

/relationships?involving=user(5)&types=8,9

The available relationship types and their IDs can be looked-up using the GET /relationship/types operation.

This query parameter determines the detail level of the objects returned inside the relationship elements.

Use this operation to import (create or update as appropriate) a relationship between a given user and the parent object of a given record.

This operation provides you with a very similar ability to import data as is automatically achieved through synchronisation with the various online bibliographic data sources. See the Examples section for an overview of how to implement a complete data feed into the system, including relationship imports.

The operation is idempotent, and can therefore be used to either create new or update previously imported relationships. Use this operation for example to inform the Elements System of which previously imported publications are authored by which users of the system, or which users are the primary investigators of previously imported grants.

See the Examples section for a walk-through of the request data you must supply when using this operation.

Content-Type: text/xml

?validate={validate} Optional: defaults to false

&detail={detail} Optional: defaults to full

HTTP 201 (Created) is returned if a new relationship was created, and the "Location" header is set to the URL of the created relationship.

HTTP 200 (OK) is returned if an existing relationship was updated as a result of the operation, and a representation of the relationship is returned in the response content.

This resource represents the entire collection of deleted relationships between objects in the system, and can be used to search for deleted relationship data.

Use this operation to list all deleted relationships in the system.

?deleted-since Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

&deleted-since={deletedSince} Optional: defaults to null

The following operation lists the all deleted relationships since a given data:

GET /relationships/deleted?deleted-since=2008-03-01T13%3A00%3A00Z

This resource represents a single relationship between two objects in the system (such as the authorship of a publication by a user).

Use this operation to retrieve the details of a relationship between to objects, and optionally full details of the objects themselves.

?detail={detail} Optional: defaults to full

At full detail level, the relationship will contain the full details of both objects involved in the relationship.

Use this operation to delete a relationship from the system. Once a relationship is deleted, it is gone forever, so use this operation with extreme care.

It is often more appropriate to decline a relationship than it is to delete it. To decline a relationship, see the POST  /relationships/{id} operation. Declining a relationship has the advantage of letting the system remember that the relationship should not be reoffered to users of the system as a suggestion.

You could use this operation to correct previously uploaded relationships that were uploaded in error, though you should treat any deletion of data as a last resort, take appropriate steps to back up your database before deleting any data, and conduct a thorough review of data integrity after running any deletions. Always work closely with your system administrator when deleting data.

It is almost always better to manually manage problem data items than to write programs to delete them via this API.

A successful response will be returned whether or not the identified relationship existed at the time the operation was executed, in line with standard REST practice.

Use this operation to decline a relationship.

If the relationship type is supported by the Symplectic Elements suggestion framework, the relationship is atomically deleted and replaced by a declined relationship suggestion. Otherwise an argument fault error response is returned.

See the results of the GET /relationship/types operation for information about which relationship types are supported by the Elements suggestion framework. Such relationships include publication authorship.

The system will remember the declined suggestion and will not automatically reoffer the relationship to users of the system as a suggestion.

Content-Type: text/xml

HTTP 303 (See other) is returned if the relationship was deleted and a new declined suggestion was created, and the "Location" header is set to the URL of the newly created declined relationship suggestion.

HTTP 204( No content) is returned if the relationship was simply deleted.

Use this operation to reoffer a relationship as a pending relationship suggestion.

If the relationship is of a relationship type that is supported by the Symplectic Elements suggestion framework, the relationship is atomically deleted and replaced by a pending relationship suggestion. Otherwise an argument fault error response is returned.

See the results of the GET /relationship/types operation for information about which relationship types are supported by the Elements suggestion framework. Such relationships include publication authorship.

Content-Type: text/xml

HTTP 303 (See other) is returned if the relationship was deleted and a new pending suggestion was created, and the "Location" header is set to the URL of the newly created pending relationship suggestion.

This resource makes available the full details of all relationship types currently defined in the system.

The id value of a relationship types you are interested in can then be used by you as a search criterium when for example searching the database using the GET /relationships operation.

For example, your client system may represent the web pages of your institution. You may wish to cache the list of publications authored by the staff in your institution, for which you would need to know which relationship represents "publication authorship". Use this resource to look up which relationship type this is before your program your client.

Use this operation to return the list of all relationship types in the system.

This resource represents all declined relationship suggestions.

Use this operation to list or search amongst all declined relationship suggestions.

?ids={idList} Optional: defaults to null

&types={types} Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

&detail={detail} Optional: defaults to ref

&modified-since={modifiedSince} Optional: defaults to null

The following operation lists the full relationship suggestion and related object details of all declined publication authorship suggestions in the system:

GET /users/8/suggestions/relationships/declined?types=8&detail=full

This resource represents the entire collection of deleted declined relationship suggestions between objects in the system.

Use this operation to list all deleted declined relationship suggestions in the system.

?deleted-since Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

&deleted-since={deletedSince} Optional: defaults to null

GET /suggestions/relationships/declined/deleted?deleted-since=2008-03-01T13%3A00%3A00Z

This resource represents all pending relationship suggestions.

Use this operation to list or search amongst all pending relationship suggestions.

?ids={idList} Optional: defaults to null

&types={types} Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

&detail={detail} Optional: defaults to ref

&modified-since={modifiedSince} Optional: defaults to null

The following operation lists the full relationship suggestion and related object details of all pending publication authorship suggestions in the system:

GET /users/8/suggestions/relationships/pending?types=8&detail=full

This resource represents the entire collection of deleted pending relationship suggestions between objects in the system.

Use this operation to list all deleted pending relationship suggestions in the system.

?deleted-since Optional: defaults to null

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

&deleted-since={deletedSince} Optional: defaults to null

GET /suggestions/relationships/pending/deleted?deleted-since=2008-03-01T13%3A00%3A00Z

This resource represents a single pending or declined relationship suggestion between two objects in the system (such as the authorship of a publication by a user).

Use this operation to retrieve the details of a relationship suggestion between to objects, and optionally full details of the objects themselves.

?detail={detail} defaults to full

At full detail level, the relationship suggestion will contain the full details of both objects involved in the relationship.

Use this operation to delete a pending or declined relationship suggestion from the system.

It is often more appropriate to decline a pending relationship suggestion than it is to delete it. To decline a relationship suggestion, see the POST  /suggestions/relationships/{id} operation. Declining a pending relationship suggestion has the advantage of letting the system remember that the relationship should not be reoffered to users of the system.

A successful response will be returned whether or not the identified relationship suggestion existed at the time the operation was executed, in line with standard REST practice.

Use this operation to accept a pending or declined relationship suggestion. The relationship suggestion is deleted and replaced by an actual relationship. The HTTP 303 (See other) redirect response points to the resource representing the newly created relationship. Send XML content <accept/>.  

Content-Type: text/xml

Use this operation to decline a pending relationship suggestion.

The pending relationship suggestion is transitioned to a declined relationship suggestion. The system will remember the declined suggestion and will not automatically reoffer the relationship to users of the system as a pending suggestion. Send XML content <decline/>. 

Content-Type: text/xml

Use this operation to reoffer a declined relationship suggestion.The declined relationship suggestion is transitioned to a pending relationship suggestion.Send XML content <reoffer/>. 

Content-Type: text/xml

This resource represents the collection of all entries in the system user feed table. See the HR Feed Guide for more information about the user feed functionality in the Elements System.

Use this operation to see all of the entries in the user feed table. See the section on "Implementing a user feed" for more information.

?after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

Some institutions prefer to treat the user feed as if it were split into separate partitions, each of which is updated in bulk by a separate client feed system and accessed by its partition ID (or feed-id). This resource represents such a partition of the user feed and its bulk update operations.

Use this resource to view the contents of a user feed partition, to clear a partition, or to import new entries into a partition.

A logically infinite number of user feed partitions "exists", and so any value for {partition-id} can be supplied. For a value not previously seen, the user feed partition is considered to be empty rather than non-existent.

Use this operation to view the user feed entries in a user feed partition. See the section on "Implementing a user feed" for more information.

Use this operation to delete all user feed entries within a user feed partition. See the section on Implementing a user feed for more information.

Use this operation in combination with DELETE /user-feeds/{partition-id} to implement a bulk partition based user feed to the Elements system.

The operation allows you to feed the Elements System in bulk with new user entries. See the section on Implementing a user feed for more information.

Content-Type: text/xml

?validate={validate} Optional: defaults to false

This resource represents the entries in the user feed for an individual user. Use this resource’s operations to see the status of a user in the user feed, or to add, update or remove users from the user feed one at a time

Use this operation to see the status of a user in the user feed, or to add, update or remove users from the user feed one at a time.

This operation will return one entry for each user feed entry in the user feed for the indicated user.

Although it is not ever desirable for there to be more than one user feed entry for any particular user in the user feed, it is possible for you to end up achieving this if you have not configured your user feed data properly. For this reason, this operation can return more than one user-feed-entry element.

?after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

Use this operation to delete all user feed entries for the indicated user. Even if no user feed entries exist for the user, a successful response is returned.

Use this operation to import (create or update) a user feed entry in the user feed.

If no user feed entries yet exist for the user, this operation will add the supplied user feed entry to the user feed.

If one or more user feed entries already exist for the user, the user feed is updated to contain just the supplied single user feed entry for this user, effectively deleting all existing entries for this user and replacing them with the new entry.

Content-Type: text/xml

?validate={validate} Optional: defaults to false

HTTP 201 (Created) if the user did not previously exist in the user feed, and a "Location" header set to the URL of the created user feed entry.

HTTP 200 (OK) if the user was already in the user feed, and has had their entry (entries) replaced by the provided data.

This resource represents the identifier associations of all users in the system. 

Use this operation to retrieve the identifiers.

?identifier-scheme={scheme} Optional. e.g. arxiv, orcid, or researcherid. See identifer-scheme in schema for complete list of identifiers. 

&status={status} Optional: defaults to null. Use to filter to either claimed, pending, or declined identifiers.

&after-id={id} Generated for pagination functionality

&per-page={perPage} Optional: defaults to 25

The following operation gets the claimed orcid identifier associations:

GET /user/identifiers?identifier-scheme=orcid&status=claimed

Use this operation to bulk import (create or update as appropriate) up to 25 associations between Elements Users and identifiers.
In the request body, callers are able to specify a set of user identifier associations for import, each consisting of a user (general object identifier format),
an identifier scheme and an identifier value. Multiple identifiers may be specified for a single user, and the same identifier may be specified for multiple users.
User identifier associations imported via this operation will be used to auto-claim publications (rather than suggest) for the users they are associated with.

Required headers
Content-Type: text/xml
Parameters
?validate={validate} Optional: defaults to false

Successful responses
HTTP 200 (OK) is returned if the request resulted in creation of any new user identifier associations or if any existing associations were updated. For each user affected by the creates/updates, a full list of the user's identifier associations will be return in the response content. Warnings (detailing the relevant failed user identifier association imports) will be added to the response if the import failed for a proper subset of the import set.

This resource represents the identifier associations of the user with the given ID. 

Use this operation to retrieve the user's identifiers.

?identifier-scheme={scheme} Optional. e.g. arxiv, orcid, or researcherid. See identifer-scheme in schema for complete list of identifiers. 

&status={status} Optional: defaults to null. Use to filter to either claimed, pending, or declined identifiers.

The following operation gets the claimed orcid identifier associations for the user with ID 512:

GET /users/512/identifiers?identifier-scheme=orcid&status=claimed

This resource represents the photo of the user with the given ID and returns a photo file in jpg, gif, or png format. Not all users may have a photo. For users without a photo, a standard “Resource not found” error response is made (including an HTTP 404 “Not found” status code).

Use this operation to retrieve the photo of a user.

?type={photo-type} Optional: defaults to profile photo. Valid types are: profile, thumbnail, original

The following operation gets the user photo for the user with ID 512:

GET /users/512/photo

Available in Elements v4.10.

Use this operation to delete a user photo. For users without a photo, a standard “Resource not found” error response is made (including an HTTP 404 “Not found” status code). If an existing photo was removed, a HTTP 204 (No Content) response is made.

Available in Elements v4.10.

Use this operation to import a user photo. Valid formats are: jpg, gif, png

HTTP 201 (Created) if the user did not previously have a photo, and a photo has been imported.

HTTP 204 (No Content) if the user already had a photo, and has had their photo replaced by the provided data.