Objects

findObjects

Search for objects matching various input criteria

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Type	String	The type of objects searched for. Check getSpecialTypes
ExactSearchFields	FieldValue[]	Array of fields and search criteria. Use for category fields and boolean fields only. Check getFieldDefs
GeneralSearchFields	String[]	Fields that should be used for free text search. Use fields that are searchable. Check getFieldDefs
GeneralSearchString	String	Search string to use on GeneralSearchFields
Active	Boolean	If the search should only return active objects
Reserved	Boolean	If the search should only return objects the user has sufficient permissions to reserve
SortOrder	String	The sorting order for the objects matching the query. Check getObjectStortOrders
ReturnFields	String[]	The fields to include on the objects matching the query. To get a list of applicable fields for the type use getAllFields. Only fields that are listable can be used. This can be determined by examining the fields with getFieldDefs. The first return field must also be sortable if the objects are sorted by the return fields.
BeginIndex	Int	Index of the first object to return (for pagination)
NumberOfObjects	Int	Maximum number of objects to return (capped at 1000 per query, use BeginIndex to paginate over the objects). Check getLimitations

Returns

Return	Type	Description
Objects	Object[]	Array of all objects matching the query, with the fields specified in ReturnFields
TotalNumOfObjects	Int	Total number of objects matching the query

Example

Request

<tns:type>room</tns:type>
<tns:exactsearchfields>
  <field>
    <extid>room.type</extid>
    <value>Lecture</value>
  </field>
</tns:exactsearchfields>
<tns:generalsearchfields>
  <field>room.name</field>
</tns:generalsearchfields>
<tns:generalsearchstring>b</tns:generalsearchstring>
<tns:active>false</tns:active>
<tns:reserved>true</tns:reserved>
<tns:sortorder>MODIFIED_DESCENDING</tns:sortorder>
<tns:returnfields>
  <field>room.name</field>
  <field>room.number_of_seats</field>
  <field>room.type</field>
</tns:returnfields>
<tns:beginindex>0</tns:beginindex>
<tns:numberofobjects>1000</tns:numberofobjects>

findObjectsExtended

Extended object search function. Note that the parameters may behave a bit differently than for findObjects.

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Type	String	The type of the objects to search for Check getSpecialTypes
ExactSearchFields	FieldValue[]	Array of fields and search criteria. Only for use with category fields and boolean fields only. Check getFieldDefs
GeneralSearchFields	String[]	Fields that should be used for free text search. Use fields that are searchable. Check getFieldDefs
GeneralSearchString	String	Search string together with GeneralSearchFields
Active	Boolean	Skip or leave empty for both active and inactive objects, true for active objects only or false for inactive objects only
Virtual	Boolean	Skip or leave empty for both virtual and non-virtual objects, true for virtual objects only or false for non-virtual objects only
Abstract	Boolean	Skip or leave empty for both abstract and non-abstract objects, true for abstract objects only or false for non-abstract objects only
Reservable	Boolean	Skip or false for all readable objects or true for all objects that can be reserved
SortOrder	String	The sorting order for the objects matching the query. Check getObjectStortOrders
ReturnFields	String[]	The fields to include on the objects matching the query. To get a list of applicable fields for the type use getAllFields. Only fields that are listable can be used. This can be determined by examining the fields with getFieldDefs. The first return field must also be sortable if the objects are sorted by the return fields.
RelatedObjectTypes	String[]	Get related objects with the selected types. If the search is made for course related types could for instance be teacher
OptionalRelatedObjectTypes	String[]	Get optional related objects with the selected types. If the search is made for class, optional related types could for instance be course
BeginModified	iCalTimeString	Find objects modified from, including this time stamp. See also Time Stamps
EndModified	iCalTimeString	Find objects modified to, excluding this time stamp. See also BeginModified
Objects	String[]	If set only the objects with the specified external ids will be returned
BeginIndex	Int	Index of the first object to return starting at 0 (for pagination)
NumberOfObjects	Int	Maximum number of objects to return (capped at 1000 per query, use BeginIndex to paginate over the objects). Check getLimitations

Returns

Return	Type	Description
Objects	Object[]	Array of all objects matching the query, with the fields specified in ReturnFields
TotalNumOfObjects	Int	Total number of objects matching the query

Example

Request

<tns:type>course</tns:type>
<tns:exactsearchfields>
    <field>
        <extid>course.subject</extid>
        <value>Economics</value>
    </field>
</tns:exactsearchfields>
<tns:generalsearchfields></tns:generalsearchfields>
<tns:generalsearchstring></tns:generalsearchstring>
<tns:active>true</tns:active>
<tns:abstract>false</tns:abstract>
<tns:virtual>false</tns:virtual>
<tns:sortorder>RETURNFIELDS_ASCENDING</tns:sortorder>
<tns:returnfields>
    <field>course.id</field>
</tns:returnfields>
<tns:relatedobjecttypes>
    <type>teacher</type>
</tns:relatedobjecttypes>
<tns:beginmodified>20210101T000000</tns:beginmodified>
<tns:endmodified>20210201T000000</tns:endmodified>
<tns:beginindex>0</tns:beginindex>
<tns:numberofobjects>1000</tns:numberofobjects>

getObjects

Get objects from external ids

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Objects	String[]	Array of external ids of the objects

Returns

Return	Type	Description
Objects	Object[]	Array of all requested objects

Example

Request

<tns:objects>
  <object>238584c4-1833-48bd-b7be-2c15529bbb62</object>
</tns:objects>

getObjectsWithFieldValues

Get objects based on field values

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Type	String	The type of object searched for
Field	String	The field to base the search on
Uniquefieldvalues	String[]	Array of accepted field values

Returns

Return	Type	Description
Objects	Object[]	Array of all objects matching the query

Example

Request

<tns:type>staff</tns:type>
<tns:field>staff.shortname</tns:field>
<tns:uniquefieldvalues>JS</tns:uniquefieldvalues>
<tns:uniquefieldvalues>GH</tns:uniquefieldvalues>

inactivateObjects

Inactivate objects of a certain type and modified before a certain timestamp

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Type	String	The type of object to inactivate
ModifiedBefore	String	MilleniumDateTime string

Returns

Return	Type	Description
Objects	Object[]	Array of all inactivated objects

Example

Request

<tns:types>course</tns:types>
<tns:modifiedbefore>20190801T000000</tns:modifiedbefore>

getObjectSortOrders

Inactivate objects of a certain type and modified before a certain timestamp

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key

Returns

Return	Type	Description
SortOrders	String[]	Available sort orders for objects

Example

Request

newObject

Get the data structure for what a new object of a specified type should look like

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Types	String[]	Types of the object the data structure template is being requested for

Returns

Return	Type	Description
Object	Object	Data structure template for a new object of the requested types

Example

Request

<tns:types>
  <type>course</type>
</tns:types>

validateObjects

Get the data structure for what a new object of a specified type should look like

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Objects	Object[]	Array of objects to be validated
Mode	String	Validation mode, "Replace", "Add", "Update" or "Ignore" are valid values. If omitted, "Replace" will be used

Returns

Return	Type	Description
Status	Status[]	Array of validation status per object. A status of 0 indicates the object passed validation

Example

Request

<tns:objects>
    <object>
        <extid>d2afc6a3-6028-4b2e-969b-a4daabacbf84</extid>
        <fields>
            <field>
                <extid>room.name</extid>
                <value>Pacific</value>
            </field>
            <field>
                <extid>room.type</extid>
                <value>Mötesrum</value>
            </field>
            <field>
                <extid>room.equipment</extid>
                <value>Whiteboard</value>
            </field>
            <field>
                <extid>room.number_of_seats</extid>
                <value>8</value>
            </field>
            <field>
                <extid>general.description</extid>
                <value>Stora rummet vid ingången</value>
            </field>
            <field>
                <extid>room.map</extid>
                <value>https://drive.google.com/a/timeedit.com/file/d/19SHPlmVYkSFajzjJib0DRFGGIze6S5eI/view?usp=sharing</value>
            </field>
        </fields>
        <created>20181217T131707</created>
        <modified>20190318T083511</modified>
        <createdby>
            <loginname>admin</loginname>
            <authserver>timeedit</authserver>
        </createdby>
        <modifiedby>
            <loginname>admin</loginname>
            <authserver>timeedit</authserver>
        </modifiedby>
        <organizations>
            <organization>admin</organization>
        </organizations>
        <types>
            <type>room</type>
            <type>ongoing_work</type>
            <type>ongoing_rooms</type>
        </types>
        <active>true</active>
        <virtual>false</virtual>
        <isAbstract>false</isAbstract>
    </object>
</tns:objects>
<tns:mode>update</tns:mode>

importObjects

Import objects to the database.

Object import modes

When importing objects, the attribute mode can be specified at several points in the XML description of the object. The mode attribute enables fine-grained control over how TimeEdit adds, overwrites or ignores imported information should the object already exist.

Locations

The mode attribute can be specified on the object tag itself and on the types, the fields, members, the related and the organizations lists. Individual fields may also have a mode attribute specified.
Modes are inherited through the object. Thus, the mode on the object itself is the default and is used whenever another mode has not been specified.
The default mode, used when an object does not specify otherwise, is replace. However, the API calls for importing and validating objects also permit specifying a global mode as a parameter. If provided, this mode will be applied to all objects which do not specify a different mode themselves.

Values

The four basic mode values are add, update, replace and ignore.

Ignore means that the element will not be imported if the object exists and already contains such an element. For example, if three members are listed in the XML and the mode is set to "ignore" these three members will not be imported if the object already exists and has any members set.

Add simply adds the information from the XML to any existing object. The three member objects would be added to the existing object alongside any already set members.

Replace, similarly, simply replaces whatever objects may appear in any existing object. So, after importing the above mentioned three members the object would have those three members and no others, regardless of which members the object may have had prior to the import.

Update, technically works as a mixture between the other three modes. Everything except fields is treated as if the specified mode was add, while fields will be treated as if replace was specified. Also, fields not specified will be treated as if ignore was specified, and thus remain unchanged.

For members and related, a list of types may be specified instead of add, update, replace or ignore. The types are specified using their external ID, multiple types are separated by a semicolon. Unless the mode is exactly add, update, replace or ignore, it will be interpreted as a list of one or more types. Specifying a type indicates that only objects of this type should be modified while others are ignored. Thus, an import can specify that it only changes an object's list of related rooms by specifying mode="Room" on the related tag. The object's related rooms will be set to the ones listed in the XML document, while any other related objects will be left untouched.
All fields not specified will be added without values. It is worth noting that if replace is specified on the fields list, any fields not listed in the XML document will be replaced with empty values (thus having any already set value removed).

More information

For more information on possible values see also

getAvailabilityRelationKinds

getObjectColors

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Objects	Object[]	Array of objects to import
Mode	String	Import mode, Replace, Add, Update or Ignore are valid values. If omitted, Replace will be used

Returns

Return	Type	Description
Status	Status[]	Array of import status per object. A status of 0 indicates the object was imported successfully

Example

Request

<tns:objects>
    <object mode="replace">
        <extid>class_science_2</extid>
        <fields mode="replace">
            <field mode="replace">
                <extid>class.name</extid>
                <value>Science 2</value>
            </field>
            <field mode="replace">
                <extid>class.year</extid>
                <value>2019</value>
            </field>
            <field mode="replace">
                <extid>group.frequency</extid>
                <value>Annual</value>
            </field>
            <field mode="replace">
                <extid>class.email</extid>
                <value>[email protected]</value>
                <value>[email protected]</value>
            </field>
            <field mode="ignore">
                <extid>general.description</extid>
                <value>This class is a group that occur annually</value>
            </field>
        </fields>
        <organizations mode="add">
            <organization>some_department</organization>
            <organization>some_other_department</organization>
        </organizations>
        <members mode="student">
          <object>student_1234567890</object>
          <object>student_2480248024</object>
        </members>
        <types mode="add">
            <type>class</type>
            <type>group</type>
        </types>
        <related mode="replace">
          <object>course_ABC123</object>
          <object>course_DEF456</object>
          <objects>
            <object>teacher_1234567890</object>
            <object>activity_lecture</object>
          </objects>
          <objects>
            <object>teacher_1234567891</object>
            <object>activity_seminar</object>
          </objects>
        </related>
        <optionalrelated mode="replace">
          <object>course_ABC123</object>
        </optionalrelated>
        <availabilityrelated kind="Classgroups" mode="ignore">
          <object>classgroup_1234567890</object>
        </availabilityrelated>
        <active>true</active>
        <virtual>false</virtual>
        <isAbstract>false</isAbstract>
        <color>Green striped</color>
    </object>
</tns:objects>
<tns:mode>update</tns:mode>

exportObjects

Export objects (e.g., for syncing object data with other systems or 3rd party applications)

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Objects	String[]	Array of external ids for objects to export
IncludeRelationTimes	Bool	Include time information for members and relational objects in the export

Returns

Return	Type	Description
Objects	Object[]	Complete export of the requested objects

Example

Request

<tns:objects>
  <object>3d379d07-5269-45d3-9b77-18d15de75650</object>
  <object>fa55f47c-a67b-4742-9c8a-099df5d1782d</object>
</tns:objects>
<tns:includerelationtimes>false</tns:includerelationtimes>

deleteObjects

Delete specific objects. If an object can't be deleted, for example because the object is reserved, there is an option to inactivate the object. Note that the functions tries to delete the object, but if this fails for some reason, it may try to inactivate the object instead depending on the parameters

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Objects	String[]	Array of external ids for objects to delete or inactivate
Inactivate	Bool	If an object can't be deleted, setting this option to true, will try to inactivate the object

Returns

Return	Type	Description
Status	Status[]	The result of the deletion, one for each object

Example

Request

<tns:objects>
  <object>c1e3b417-9535-47fa-9a4a-076b2d7f2dea</object>
  <object>281fc32a-c64f-4580-bf9c-eb7afee7a36f</object>
</tns:objects>
<tns:inactivate>false</tns:inactivate>

getAvailabilityRelationKinds

Get the different availability relations used when importing objects.

The values of this function can be used as attribute mode on the tag availabilityrelated.

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key

Returns

Return	Type	Description
AvailabilityRelationKinds	AvailabilityRelationKind[]	List of availability relation types

Example

Request

getObjectColors

Get the available object colors that can be used when importing objects.

The result of this function are the colors that can be used as values for the tag color in importObjects and exportObjects. Colors are represented by a string with the name of the color. The empty string represents objects with no color. Note that the names of colors reoccur with different patterns.

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key

Returns

Return	Type	Description
colors	color[]	List of available object colors

Example

Function response from July 31, 2020

<colors>
    <color>Green</color>
    <color>Yellow</color>
    <color>Blue</color>
    <color>Purple</color>
    <color>Mint green</color>
    <color>Orange</color>
    <color>Red</color>
    <color>Light blue</color>
    <color>Dark yellow</color>
    <color>Pink</color>
    <color>Lime green</color>
    <color>Army green</color>
    <color>Wine red</color>
    <color>Acid green</color>
    <color>Orchid purple</color>
    <color>Brown</color>
    <color>Green striped</color>
    <color>Yellow striped</color>
    <color>Blue striped</color>
    <color>Purple striped</color>
    <color>Mint green striped</color>
    <color>Orange striped</color>
    <color>Red striped</color>
    <color>Light blue striped</color>
    <color>Dark yellow striped</color>
    <color>Pink striped</color>
    <color>Lime green striped</color>
    <color>Army green striped</color>
    <color>Wine red striped</color>
    <color>Acid green striped</color>
    <color>Orchid purple striped</color>
    <color>Brown striped</color>
</colors>

findObjectFields

Get which object fields an object can have depending on the object type

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
Types	String[]	The types of the object in question

Returns

Return	Type	Description
Fields	Field[]	List of fields that may exist on the object in question

Example

Request

findFreeObjects

Find objects that are not occupied at a certain date and time and can be reserved by the current user

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
begintime	iCalTimeString	The begin time where objects are to be free. Check getCurrentDateTime
endtime	iCalTimeString	The end time where objects are to be free
type	String	The type of the object to find
exactsearchfields	FieldSearch[]	Categories that the objects should have
generalsearchfields	Field[]	Other fields that the objects should match together with generalsearchstring
generalsearchstring	String	The search value for generalsearchfields
numberofobjects	Int	The maximum number of objects to return, default value is 10
sortorder	String	How the objects should be sorted, see also getObjectSortOrders
returnfields	Field[]	The fields to return for the object
reservationsituation	String	The reservation mode to use when finding free time, see also getReservationSituations

Returns

Return	Type	Description
Objects	Object[]	Objects that are free the specified time

Example

Request

findFreeObjectsOtherUser

Find objects that are not occupied at a certain date and time and can be reserved by another user

Parameters

Parameter	Type	Description
Login	LoginObject	Standard login object with username, password, and application key
begintime	iCalTimeString	The begin time where objects are to be free. Check getCurrentDateTime
endtime	iCalTimeString	The end time where objects are to be free
type	String	The type of the object to find
exactsearchfields	FieldSearch[]	Categories that the objects should have
generalsearchfields	Field[]	Other fields that the objects should match together with generalsearchstring
generalsearchstring	String	The search value for generalsearchfields
numberofobjects	Int	The maximum number of objects to return, default value is 10
sortorder	String	How the objects should be sorted, see also getObjectSortOrders
returnfields	Field[]	The fields to return for the object
reservationsituation	String	The reservation mode to use when finding free time, see also getReservationSituations
user	String	The user that is to able to reserve the objects

Returns

Return	Type	Description
Objects	Object[]	Objects that are free the specified time

Example

Request