How Can We Help?

External Person XMLExternal Person XML

Overview

This page details the External Person content type. On this page you will find different representations of the data elements contained within this type.

Below is the xsd for the External Person content type that defines the import xml format. Also provided is mapping tables generated based on this XSD as well as an example xml that shows how the fields can be populated.

This is logical broken down into the different elements to help you gain a better understanding of the External Person content type and how to create, read and update these records using the mechanisms provided in Pure.

Note: for the mapping tables all attributes and elements are listed, along with descriptions of the purposes of the field and any data requirements. Attribute are prefaced with an "@" to differentiate from elements, but as shown in the examples this isn't used when generating the xml.

Some elements offer options of which elements to include (such as whether to provide the ID of a person or organisation or name for lookup). These are denoted by reference to "Option Groups" where numbers are used to indicate where multiple elements are part of the same option. See example xmls for demonstrations of how to use these elements.

The External Person content type represents a person from outside your institution. They are recorded in Pure because of the collaborations they have with other researchers at your institution, such as projects they have been investigators on, or outputs they have co-authored. Only the name of an external person is required but the more detailed information that is captured the better quality reports can be generated on the collaborations that occur at your institution.

Below are a series of attachments for your reference:

Simple Example XML - This shows only the mandatory fields that need to be populated
Advanced Example XML - This shows all fields that can be used. Snippets of this file are shown with their related elements below.
XSD (Xml Schema Definition) - This is a definition of what structure the XML must follow. This page has been generated based on the contents of the xsd file, and snippets of the definition are shown with their relevant element below
Editor Example PNG - This image shows the result of loading the advanced example xml into Pure, to allow for easy reference of which fields in Pure point to which elements in the XML. Note that the way the data is presented within your Pure instance may be different due to different configuration
Webservice Example Response - This shows an example response of retrieving the record generated via this xml via the webservice
Pure API Example Response - This shows an example response of retrieving the record generated via this xml via the Pure API. Note as the Pure API allows for creation of records, this format could also be used to create a new record with these details, but some fields would be ignored in that case (such as audit fields like created/modified by and internal Pure identifiers like UUID and Pure ID which wouldn't exist yet). UUIDs for related content (such as organisational units) would need to be updated as well.

Download All

External Persons

externalPersons

A list of externalPerson elements of type externalPerson

Root element of the xml file, containing all of the external person records

XML Example

<externalPersons xmlns="v1.external-person.base-uk.pure.atira.dk"
                         xmlns:cmns="v3.commons.pure.atira.dk">
           <externalPerson id="external_person_id_0003"
                           type="externalperson"
                           managedInPure="false">
              <title><!-- Title of the external person -->
                 <cmns:text country="GB" lang="en">Professor</cmns:text>
              </title>
              <name><!-- First and last name -->
                 <cmns:firstname>John</cmns:firstname>
                 <cmns:lastname>Smith</cmns:lastname>
              </name>
              <!-- The external persons country -->
              <country>gb</country>
              <!-- The external persons gender-->
              <gender>male</gender>
              <!-- Any ids related to the external person, the type need to be present in /dk/atira/pure/externalperson/externalpersonsources classification scheme -->
              <ids>
                 <cmns:id type="scopusauthor">654321</cmns:id>
              </ids>
              <workflow>approved</workflow>
              <externalOrganisations>
                 <externalOrganisation><!-- The type of the external organisation -->
                    <cmns:type>unknown</cmns:type>
                    <!-- The name of the external organisation -->
                    <cmns:name>University of Europe</cmns:name>
                    <!-- The country of the external organisation -->
                    <cmns:country>gb</cmns:country>
                    <!-- If the external organisation can be represented by an ID -->
                    <cmns:externalOrgId>123456</cmns:externalOrgId>
                    <!-- If the external organisation ID has an origin like Scopus in the data -->
                    <cmns:externalOrgSource>Scopus</cmns:externalOrgSource>
                 </externalOrganisation>
              </externalOrganisations>
           </externalPerson>
        </externalPersons>

XSD Definition

<xs:element xmlns:xs="http://www.w3.org/2001/XMLSchema" name="externalPersons">
           <xs:annotation>
              <xs:documentation>
                        Root element of the xml file, containing all of the external person records
                    </xs:documentation>
           </xs:annotation>
           <xs:complexType>
              <xs:sequence>
                 <xs:element ref="externalPerson" minOccurs="0" maxOccurs="unbounded"/>
              </xs:sequence>
              <xs:attribute name="resumptionToken" type="xs:string">
                 <xs:annotation>
                    <xs:documentation>
                                To enable resumption tokens, add an URL to the "XML source data location" in the job configuration with "{resumptionToken}" as a placeholder, for instance "https://example.org/data?resumptionToken={resumptionToken}".
                                The endpoint must handle the resumptionToken in the following manner:
                                If an empty resumptionToken is sent, the endpoint must return all data. If a non-empty resumptionToken is sent, the endpoint must return all data that has changed since the time the resumptionToken was sent.
                            </xs:documentation>
                 </xs:annotation>
              </xs:attribute>
           </xs:complexType>
        </xs:element>

externalPerson

XML Example

<externalPerson xmlns="v1.external-person.base-uk.pure.atira.dk"
                        xmlns:cmns="v3.commons.pure.atira.dk"
                        id="external_person_id_0003"
                        type="externalperson"
                        managedInPure="false">
           <title><!-- Title of the external person -->
              <cmns:text country="GB" lang="en">Professor</cmns:text>
           </title>
           <name><!-- First and last name -->
              <cmns:firstname>John</cmns:firstname>
              <cmns:lastname>Smith</cmns:lastname>
           </name>
           <!-- The external persons country -->
           <country>gb</country>
           <!-- The external persons gender-->
           <gender>male</gender>
           <!-- Any ids related to the external person, the type need to be present in /dk/atira/pure/externalperson/externalpersonsources classification scheme -->
           <ids>
              <cmns:id type="scopusauthor">654321</cmns:id>
           </ids>
           <workflow>approved</workflow>
           <externalOrganisations>
              <externalOrganisation><!-- The type of the external organisation -->
                 <cmns:type>unknown</cmns:type>
                 <!-- The name of the external organisation -->
                 <cmns:name>University of Europe</cmns:name>
                 <!-- The country of the external organisation -->
                 <cmns:country>gb</cmns:country>
                 <!-- If the external organisation can be represented by an ID -->
                 <cmns:externalOrgId>123456</cmns:externalOrgId>
                 <!-- If the external organisation ID has an origin like Scopus in the data -->
                 <cmns:externalOrgSource>Scopus</cmns:externalOrgSource>
              </externalOrganisation>
           </externalOrganisations>
        </externalPerson>

XSD Definition

<xs:complexType xmlns:xs="http://www.w3.org/2001/XMLSchema" name="externalPersonType">
           <xs:all>
              <xs:element name="title" type="commons:localized_string_1024" minOccurs="0">
                 <xs:annotation>
                    <xs:documentation>
                                Title of the person
                            </xs:documentation>
                 </xs:annotation>
              </xs:element>
              <xs:element name="name" type="commons:name" minOccurs="1">
                 <xs:annotation>
                    <xs:documentation>
                                First and last name
                            </xs:documentation>
                 </xs:annotation>
              </xs:element>
              <xs:element name="country" type="commons:classification" minOccurs="0">
                 <xs:annotation>
                    <xs:documentation>
                                Classifications from the scheme: /dk/atira/pure/core/countries. Only use the last part of the
                                uri (token)
                            </xs:documentation>
                 </xs:annotation>
              </xs:element>
              <xs:element name="gender" type="commons:gender" minOccurs="0">
                 <xs:annotation>
                    <xs:documentation>
                                Gender. Accepted values are male, female and unknown
                            </xs:documentation>
                 </xs:annotation>
              </xs:element>
              <xs:element name="externalOrganisations"
                          type="externalOrganisations"
                          minOccurs="0">
                 <xs:annotation>
                    <xs:documentation>
                                List of external organisation the person is affiliated to
                            </xs:documentation>
                 </xs:annotation>
              </xs:element>
              <xs:element name="workflow" type="xs:string" minOccurs="0">
                 <xs:annotation>
                    <xs:documentation>
                                Used to set the workflow state of the external person, options are forApproval, approved.
                            </xs:documentation>
                 </xs:annotation>
              </xs:element>
              <xs:element name="ids" type="commons:ids" minOccurs="0">
                 <xs:annotation>
                    <xs:documentation>
                                The classified ids on the external person. Type must be from the classification scheme /dk/atira/pure/externalperson/externalpersonsources
                            </xs:documentation>
                 </xs:annotation>
              </xs:element>
           </xs:all>
           <xs:attribute type="commons:string_400" name="id" use="required">
              <xs:annotation>
                 <xs:documentation>
                            The external ID of the external person, this must be an unique value
                        </xs:documentation>
              </xs:annotation>
           </xs:attribute>
           <xs:attribute type="commons:classification" name="type" use="required">
              <xs:annotation>
                 <xs:documentation>
                            Classifications from the scheme: /dk/atira/pure/externalperson/externalpersontypes/externalperson/. Only use the last part of
                            the uri (token)
                        </xs:documentation>
              </xs:annotation>
           </xs:attribute>
           <xs:attribute type="xs:boolean" name="managedInPure" use="optional">
              <xs:annotation>
                 <xs:documentation>
                            Indicates whether or not an external person should be managed inside Pure. If set to TRUE, the synchronisation will only import the person and not lock any fields/relations. In subsequent synchronisation runs, the synchronisation will not update the person, unless the MANAGED_IN_PURE state is changed to FALSE. If changed the person will be picked up by the synchronisation and handled as a synchronised content and fields and relations will be locked based on the configuration.
                            The default behaviour for the synchronisation is to consider MANAGED_IN_PURE as FALSE.
                        </xs:documentation>
              </xs:annotation>
           </xs:attribute>
        </xs:complexType>

XML Attribute/Element	Description	Type	Mandatory
@id	The external ID of the external person, this must be an unique value	commons:string_400	Yes
@type	Classifications from the scheme: /dk/atira/pure/externalperson/externalpersontypes/externalperson/. Only use the last part of the uri (token)	commons:classification	Yes
@managedInPure	Indicates whether or not an external person should be managed inside Pure. If set to TRUE, the synchronisation will only import the person and not lock any fields/relations. In subsequent synchronisation runs, the synchronisation will not update the person, unless the MANAGED_IN_PURE state is changed to FALSE. If changed the person will be picked up by the synchronisation and handled as a synchronised content and fields and relations will be locked based on the configuration. The default behaviour for the synchronisation is to consider MANAGED_IN_PURE as FALSE.	xsd:boolean	Yes
title	Title of the person	commons:localized_string_1024	No
name	First and last name	commons:name	Yes
country	Classifications from the scheme: /dk/atira/pure/core/countries. Only use the last part of the uri (token)	commons:classification	No
gender	Gender. Accepted values are male, female and unknown	commons:gender	No
externalOrganisations	List of external organisation the person is affiliated to	externalOrganisations	No
workflow	Used to set the workflow state of the external person, options are forApproval, approved.	xsd:string	No
ids	The classified ids on the external person. Type must be from the classification scheme /dk/atira/pure/externalperson/externalpersonsources	commons:ids	No

External Organisations

externalOrganisations

A list of externalOrganisation elements of type commons:externalOrganisation

XML Example

<externalOrganisations xmlns="v1.external-person.base-uk.pure.atira.dk"
                               xmlns:cmns="v3.commons.pure.atira.dk">
           <externalOrganisation><!-- The type of the external organisation -->
              <cmns:type>unknown</cmns:type>
              <!-- The name of the external organisation -->
              <cmns:name>University of Europe</cmns:name>
              <!-- The country of the external organisation -->
              <cmns:country>gb</cmns:country>
              <!-- If the external organisation can be represented by an ID -->
              <cmns:externalOrgId>123456</cmns:externalOrgId>
              <!-- If the external organisation ID has an origin like Scopus in the data -->
              <cmns:externalOrgSource>Scopus</cmns:externalOrgSource>
           </externalOrganisation>
        </externalOrganisations>

XSD Definition

<xs:complexType xmlns:xs="http://www.w3.org/2001/XMLSchema" name="externalOrganisations">
           <xs:sequence>
              <xs:element name="externalOrganisation"
                          type="commons:externalOrganisation"
                          maxOccurs="unbounded"
                          minOccurs="1">
                 <xs:annotation>
                    <xs:documentation>
                                External Organisations matched by PureID, SourceID, ClassificationID (in that order)
                                If no match is found the system will try to match by name, type and country (all fields, depending on which are supplied).
                                If no match is found either way, the external organisation is automatically created with the supplied information.
                            </xs:documentation>
                 </xs:annotation>
              </xs:element>
           </xs:sequence>
        </xs:complexType>

XML Attribute/Element	Description	Type	Mandatory
externalOrganisation	External Organisations matched by PureID, SourceID, ClassificationID (in that order) If no match is found the system will try to match by name, type and country (all fields, depending on which are supplied). If no match is found either way, the external organisation is automatically created with the supplied information.	commons:externalOrganisation	Yes

Updated at July 27, 2024

How Can We Help?

Search Results

Filter By Category

Contact Us

External Person XMLExternal Person XML

Overview

External Persons

externalPersons

XML Example

XSD Definition

externalPerson

XML Example

XSD Definition

External Organisations

externalOrganisations

XML Example

XSD Definition