Standard Type Basics
Generally speaking, a data dictionary is the complete reference for the data model and services of a given Taleo Product. The data model consists of entities with fields and relations between other entities. Entities represent the information stored in the application. The services expose callable methods that allow you to access the data model entities from a client application.
To allow you to query, add, update, or delete data, all entity fields and relations are mapped into Taleo specific datatypes, hereafter called Standard Types.
The API exposes two categories of services: export and import services.
Taleo products expose one single export service, called FindService: this one uses Export Standard Types to allow you to query
data. All other services use Import Standard Types to allow
you to add, edit, or delete data. As opposed to the export service,
which is available for all products, import services are specific
to each product: Please refer to the data dictionary of each Taleo
product for an exhaustive list of its available Web services.
Import Standard Types
The following sections describes the standard types used by Web services that can add, edit, or delete data, as opposed to the Export service that can only query data.
The first section describes the mapping between Entity fields, as described in the Taleo product data dictionary and the Standard Types used by the API.
The next sections describe each of these standard types, providing usage samples using XML (SOAP messages). The code snippets presented here are partial only, and aim to demonstrate the usage of each standard type.
Entity Fields Definition vs. Import Standard Types Mapping
Each Entity Field is defined in the data dictionary (Field Details section) with the following import-relevant attributes:
-
Create: The field can be set when not yet already set.
-
Update: The field can be updated when already set.
-
Search: The field can be set or updated using a lookup query (specifying a search value).
-
Multilingual: The field can be set to multiple value, one per language.
The API considers all field values as String, no matter the type specified in the data model, and uses different Import Standard Types to handle the field attributes:
|
Import Standard Type (used to build import requests) |
Attributes |
|---|---|
| String |
Create Update |
| SearchableStringField |
Create Update Search |
| SearchableSearchOnlyField |
Search |
| SearchableMultilingualStringField |
Create Update Search Multilingual |
| SearchableMultilingualSearchOnlyField |
Search Multilingual |
If neither create, update, and search are checked for a given entity field in the data dictionary, the field cannot be imported or updated. If only search is checked, the field is either mapped to a SearchableMultilingualSearchOnlyField if the field is multilingual, or to a SearchableSearchOnlyField otherwise. This means the field is available for lookup but cannot be set to a non-existing value (you have to lookup the value to set it to the entity field). If create or update are checked but not search, then you can set a new value (or update one if update is checked), but cannot use an existing value (no lookup available). In this case, no matter the field type, the field is mapped to a simple String (cannot be multilingual). Finally, if create or update are checked, and search is also checked, the field is either mapped to a SearchableMultilingualStringField if the field is multilingual, or a SearchableStringField otherwise.
String
This type is a
standard xs:string field, as specified in the Schema W3C
reference (http://www.w3.org/TR/xmlschema-2/#string).
It is used when no lookup is available for the field. This means you will not be able to use this field to search for a specific entity, and setting a value to this field will replace any existing value for the field, if any was previously set.
Sample #1: Set a Candidate prefix
The Entity Candidate contains a
Field Prefix that corresponds to a String field.
XML
<Candidate>
<Prefix>Mr</Prefix>
</Candidate>SearchableStringField
This type is a Taleo object that allows to search for a specific value and optionally to replace it with another value. It holds three search criteria and the new value to set:
-
searchType: The value can be "none" (do not use search feature), "search" (search for the searchValue attribute value but do not try to replace the value) or "searchAndValue", (search and replace the value with the field value).
-
searchValue: The value of the field to search for.
-
searchTarget: The value can be "." (entity to edit is the one containing the field), ".." (entity to edit is the parent of the one containing the field), "../.." (entity to edit is the grandparent of the one containing the field), etc.
-
stringValue: The value of the field (field will be edited with this value).
Sample #1: Create a candidate and set LastName and FirstName
The
Candidate entity contains the LastName
and FirstName fields that both correspond to
SearchableStringFields. The following example will create a candidate and
set the candidate's email address, firstname, and lastname.
XML
<Candidate>
<EmailAddress>jsmith@abc.com</EmailAddress>
<FirstName>John</FirstName>
<LastName>Smith</LastName>
</Candidate>Sample #2: Update LastName of existing candidate, searching by candidate's EmailAddress
The Candidate entity contains the
EmailAddress and LastName fields that both correspond
to SearchableStringFields. The following example will look for the candidate
based on the e-mail address and update the candidate's lastname (leaving the
candidate's email address and firstname as-is).
XML
<Candidate>
<EmailAddress searchType="search" searchValue="jsmith@abc.com"/>
<LastName>Brown</LastName>
</Candidate>Sample #3: Update EmailAddress of existing candidate, searching by candidate's email address
In certain cases, the value used to determine the entity may also have to be updated; the syntax of the instruction would then be as follows (compare with previous samples):
XML
<Candidate>
<EmailAddress searchType="searchAndValue" searchValue="jsmith@abc.com">jbrown@abc.com</EmailAddress>
</Candidate> Sample #4: Create a candidate and have that candidate apply on a specific requisition
When importing entities, most relations are lookups and the
related entity is only linked to the main entity. This is the case for the
Applications relation of the Candidate entity or
the Requisition relation of the
PreselectionApplication. To determine the related entity, we
re-use the same search attributes, but in a different context. The following sample
describes how to specify that John Smith applied on a specific Job Requisition (here
Req001).
XML
<Candidate>
<EmailAddress>jsmith@abc.com</EmailAddress>
<FirstName>John</FirstName>
<LastName>Smith</LastName>
<Applications>
<PreselectionApplication>
<Requisition>
<Requisition>
<ContestNumber searchType="search" searchValue="Req001"/>
</Requisition>
</Requisition>
</PreselectionApplication>
</Applications>
</Candidate>Sample #5: Update the application of a candidate having applied on a specific requisition
If we now want to set the date of entry for John Smith for the
"Req001" job, we need to update the proper Application entity. To
do so, we must find it among all his other possible applications. Since there is no
identifier in the Application entity itself, we must use the
Requisition ContestNumber field to find the application. This is
possible by specifying a searchTarget among the search attributes.
XML
<Candidate>
<EmailAddress>jsmith@abc.com</EmailAddress>
<FirstName>John</FirstName>
<LastName>Smith</LastName>
<Applications>
<PreselectionApplication>
<DateOfEntry>2006-06-01T14:15:00-04:00</DateOfEntry>
<Requisition>
<Requisition>
<ContestNumber searchType="search" searchValue="Req001" searchTarget=".."/>
</Requisition>
</Requisition>
</PreselectionApplication>
</Applications>
</Candidate>SearchableSearchOnlyField
This type is almost identical to the SearchableStringField, with the exception that you cannot update the value of the field being searched. The only allowed searchType value is therefore "search".
Sample #1: Update a candidate and set the US dollar as default currency for this candidate
The Candidate entity
contains the Currency relation, whose referenced object contains a
ISO4217Code field that corresponds to a
SearchableSearchOnlyField. The following example will define the US
dollar (whose ISO-4217 code is 840) as the default currency used by John
Smith.
XML
<Candidate>
<EmailAddress searchType="search" searchValue="jsmith@abc.com"/>
<Currency>
<ISO4217Code searchType="search" searchValue="840"/>
</Currency>
</Candidate>SearchableMultilingualStringField
This type is a Taleo object very similar to the SearchableStringField type, but that further allows multilingual values. Multilingual values are provided individually by locale, each in a dedicated value object.
Sample #1: Set the current job title for a candidate
The Candidate entity contains a
CurrentJob relation, whose referenced object contains a
CurrentJobJobTitle field that corresponds to a
SearchableMultilingualStringField. The following example will define
software developer John Smith's current job title in different languages (English,
French and German).
XML
<Candidate>
<EmailAddress searchType="search" searchValue="jsmith@abc.com"/>
<CurrentJob>
<CurrentJob>
<CurrentJobJobTitle>
<value locale="en">Software Developer</value>
<value locale="fr">Développeur logiciel</value>
<value locale="de">Software-Entwickler</value>
</CurrentJobJobTitle>
</CurrentJob>
</CurrentJob>
</Candidate>Sample #2: Mark an application state for a candidate as new
The
Candidate entity contains an Applications relation, whose
referenced object itself contains an ApplicationState relation,
whose referenced object contains a Description field that
corresponds to a SearchableMultilingualStringField. The following example
will link the "new" application state to the preselection application of the
candidate instead of creating any new application state object, by using a lookup on
the English description value.
XML
<Candidate>
<EmailAddress searchType="search" searchValue="jsmith@abc.com"/>
<Applications>
<PreselectionApplication>
<ApplicationState>
<ApplicationState>
<Description>
<value searchType="search" searchValue="New" locale="en" />
</Description>
</ApplicationState>
</ApplicationState>
</PreselectionApplication>
</Applications>
</Candidate>SearchableMultilingualSearchOnlyField
This type is a Taleo object
very similar to the SearchableSearchOnlyField type, but that further allows
multilingual values. Multilingual values are provided individually by locale, each
in a dedicated value object.
Sample #1: Set the current currency symbol for a candidate
The Candidate entity contains
a Currency relation, whose referenced object contains a
Symbol field that corresponds to a
SearchableMultilingualSearchOnlyField. The following example will set the
currency to be used for the candidate to the US dollar.
XML
<Candidate>
<Currency>
<Currency>
<Symbol>
<Value locale="en" searchType="search" searchValue="$" />
</Symbol>
</Currency>
</Currency>
</Candidate>Operations On Parameters With Base Type Elements
The Taleo data model is composed of base and specialized elements. They define a logical hierarchical representation of the Taleo entities. A concrete example of this is:
In this example, you have an operation that requires a MeetingAttendee entity as a parameter. This entity is composed of an Attendee entity. The Attendee entity is an abstraction of the meeting expected participants. The three possible types of attendees are CandidateAttendee, UnregistredAttendee and UserAttendee. The Taleo WSDL is constructed to support the passage of one of these three entities as the MeetingAttendee parameter instead of the Attendee.
Sample #1: Using the requisition merge operation with an entity that is using UDF
XML
<merge xmlns="http://www.taleo.com/ws/art750/2006/12">
<requisition>
<ContestNumber searchValue="INT-REQ-SRC-122354" searchTarget="." searchType="searchAndValue">INT-REQ-SRC-122354</ContestNumber>
<JobInformation>
<JobInformation>
<UDFs>
<UDF name="TST_5f22_5f00_5f30">
<UDSElement>
<Description>
<value searchValue="Cost Center 2.10" locale="en" searchTarget="." searchType="searchAndValue">Cost Center 2.10</value>
</Description>
</UDSElement>
</UDF>
</UDFs>
</JobInformation>
</JobInformation>
</requisition>
</merge>Export Standard Types
The following sections describe the standard types used by the FindService Web service that allows client applications to query data.
The first section provides an overview of Selection Query language (SQ-XML) that allows to build efficient data queries against the Taleo data model. For a complete reference of this language, refer to the Selection Query Language, SQ-XML section.
The next section describes the mapping between Entity fields, as described in the Taleo product data dictionary, and the standard types used by the API. As opposed to the standard import types, you will use these types to handle the response to queries sent to the FindService Web service.
The last sections describe each of these standard types, providing usage samples using XML (SOAP messages). The code snippets presented here are partial only and aim to demonstrate the usage of each Standard Type.
Building Export Queries Using Selection Query (SQ-XML)
Use the Selection
Query language (SQ-XML) to construct simple but powerful queries for
the sqxmlquery parameter in the findEntities and findPartialEntities calls of the FindService. Similar to the SELECT command in SQL, SQ-XML allows you to specify
the source object (such as Account), a list of fields to retrieve,
and conditions for selecting rows in the source object.
A meta model differs mainly from a relational data model in terms of the relationships created between its entities. As such, the Selection Query language differs from the SQL language mainly in the same manner. Since ultimately the Selection Query engine will translate all SQ-XML expressions into SQL statements to be executed against the physical model, Selection Query expressions are really very close to their SQL counterparts. Resources accustomed to creating SQL extraction scripts should easily grasp the workings of the Selection Query format. For SQL neophytes, the SQ-XML offers a simpler alternative for working with extraction instructions. This section will present the "equivalent" SQL statement of the described SQ-XML documents. Please note that this is done ONLY for reference purposes. In almost all cases, the application entities and fields do NOT have the same name as the underlying physical elements. We purposely use the application model terms to clearly distinguish between examples and the SQL statements that would be actually generated by the export service.
Overview
Building an export instruction is much more involved than in the case of the import feature. This section presents a simple example using the Recruiting 7.5 data model. The export instruction basically needs to specify what type of entity is exported, which entities are to be selected, and what fields are to be extracted. Assuming we want to extract all requisitions that are currently open and posted in Taleo Enterprise Edition 7.5 product, the instruction would look like the following:
<ns:query alias="Find Open and Posted Requisitions" projectedClass="Requisition">
<ns:projections>
<ns:projection>
<ns:field path="ContestNumber"/>
</ns:projection>
<ns:projection>
<ns:field path="JobInformation,Title"/>
</ns:projection>
</ns:projections>
<ns:filterings>
<ns:filtering>
<ns:includedIn>
<ns:field path="State,Number"/>
<ns:list>
<ns:long>3<!--state=open--></ns:long>
<ns:long>13<!--state=posted--></ns:long>
</ns:list>
</ns:includedIn>
</ns:filtering>
</ns:filterings>
<ns:sortings>
<ns:sorting>
<ns:field path="ContestNumber"/>
</ns:sorting>
</ns:sortings>
</ns:query>The next sections cover the 4 most important parts of a SQ-XML query:
Basics—The entity type to be extracted
Projections—The fields to be extracted
Filterings—The conditions applying to the query (reducing the scope of entities to be extracted)
Sortings—The order which to sort the extracted results
Basics
An SQ-XML document typically starts
with a query element. There are two required attributes to the query
element: projectedClass and alias. The former represents the base entity from which the extraction
will be built. The latter is a unique name throughout the expression
that identifies the query.
A basic query starts like this:
<query alias="BasicQuery" projectedClass="User"/>SQL Equivalent: FROM User
Projections
The first main elements of a query are the projections that represent what information is to be extracted for the selected entities. The projection elements can be defined as any value understood by the Selection Query language. The simplest case is to use a field of the projected class.
<query alias="SimpleProjection" projectedClass="User">
<projections>
<projection>
<field path="UserName"/>
</projection>
</projections>
</query>SQL Equivalent: SELECT
UserName FROM User
It is possible to assign an alias to a projection; this serves two purposes. First, when a function is used, the Selection Query cannot deduce a default alias. Hence, it is required to explicitly specify one. Second, when sub queries are involved, sometimes aliases are required to distinguish projections. This is because the default alias is the entity field name; so if both the main query and a sub-query project the Email field, then one of them will need an alias.
<query alias="ProjectionWithAlias" projectedClass="User">
<projections>
<projection alias="Login">
<field path="UserName"/>
</projection>
</projections>
</query>SQL Equivalent: SELECT
UserName AS Login FROM User
The real strength of the Selection Query language comes from the application model relations. When such relations exist for the target data, then projecting it becomes straightforward. For example, by selecting the Department relation of the User entity (which is one-to-one according to the schema), you can access all of the Department entity fields. When the path expression only specifies the relation, then it is the entity key that is projected.
<query alias="ProjectionWithRelations" projectedClass="User">
<projections>
<projection>
<field path="UserName"/>
</projection>
<projection>
<field path="Department"/>
</projection>
<projection>
<field path="Department,Name"/>
</projection>
</projections>
</query>SQL Equivalent: SELECT
UserName, DepartmentNo, Department.Name FROM User, Department WHERE
User.DepartmentNo=Department.No
When navigating a relation, you also have access to all the relations of the related entity. In the example below, since the Recruiter relation of the Department entity points to a User entity, then all the fields of that entity are again available.
<query alias="ProjectionWithDeepRelations" projectedClass="User">
<projections>
<projection>
<field path="UserName"/>
</projection>
<projection>
<field path="Department,Recruiter,UserName"/>
</projection>
</projections>
</query>SQL Equivalent: SELECT
UserName, Recruiter.UserName FROM User, Department, Recruiter WHERE
User.DepartmentNo=Department.No AND Department.RecruiterNo = Recruiter.No
Filtering elements
The next query element includes the filters that represent what entities are to be selected.
The filtering elements are grouped in sequence within the filterings element, although the sequence itself is not relevant. The various filtering elements are implicitly linked by an AND logical operator. The filtering elements can be defined as any filter understood by the Selection Query language; these are either logical operators or actual conditions. The simplest case is to use a standard equality condition. The equal is a binary operator and as such accepts two value child elements. One simple possibility is to use a field and a fixed value. We saw fields in the projection sections; the fixed values are of the normal types: numeric, string, etc.
<query alias="EqualityFilter" projectedClass="User">
<projections>
<projection>
<field path="UserName"/>
</projection>
</projections>
<filterings>
<filtering>
<equal>
<field path="FirstName"/>
<string>John</string>
</equal>
</filtering>
</filterings>
</query>SQL Equivalent: SELECT
UserName FROM User WHERE FirstName='John'
In the previous example, the SQ-XML is slightly more complex than the SQL equivalent. However, once again, the power of the expression language resides in the application model relations that allow a simple modification to filter on other relationships such as the Department name.
<query alias="RelationFilter" projectedClass="User">
<projections>
<projection>
<field path="UserName"/>
</projection>
</projections>
<filterings>
<filtering>
<equal>
<field path="Department,Name"/>
<string>Finance</string>
</equal>
</filtering>
</filterings>
</query>SQL Equivalent: SELECT
UserName FROM User, Department WHERE User.DepartmentNo = Department.No
AND Department.Name='Finance'
Applying a single logical condition can be done directly with the proper element.
<query alias="AndFilter" projectedClass="User">
<projections>
<projection>
<field path="UserName"/>
</projection>
</projections>
<filterings>
<filtering>
<and>
<equal>
<field path="FirstName"/>
<string>John</string>
</equal>
<equal>
<field path="LastName"/>
<string>Doe</string>
</equal>
</and>
</filtering>
</filterings>
</query>SQL Equivalent: SELECT
UserName FROM User WHERE FirstName='John' AND LastName = 'Doe'
However, applying several logical conditions must be done in an embedded manner, as most logical operator elements are binary (that is, accept only two child elements).
<query alias="MultipleAndFilters" projectedClass="User">
<projections>
<projection>
<field path="UserName"/>
</projection>
</projections>
<filterings>
<filtering>
<and>
<and>
<equal>
<field path="FirstName"/>
<string>John</string>
</equal>
<equal>
<field path="LastName"/>
<string>Doe</string>
</equal>
</and>
<equal>
<field path="MiddleInitial"/>
<string>R</string>
</equal>
</and>
</filtering>
</filterings>
</query>SQL Equivalent: SELECT
UserName FROM User WHERE FirstName='John' AND LastName='Doe' AND MiddleInitial='R'
Sorting elements
The last main query element is the sorting instructions that represent in what order the selected entities will be shown.
The sorting elements are grouped in sequence within the sortings element. The sequence determines what sorting instructions are applied first. The sorting elements accept any value as child elements, but the main usage is with fields of the projected entity. The sorting elements also accept an ascending attribute that determines the orientation of the particular ordering. Just like in SQL, this attribute defaults to true.
<query alias="Sorting" projectedClass="User">
<projections>
<projection>
<field path="UserName"/>
</projection>
</projections>
<sortings>
<sorting>
<field path="LastName"/>
</sorting>
<sorting ascending="false">
<field path="FirstName"/>
</sorting>
</sortings>
</query>SQL Equivalent: SELECT
UserName FROM User ORDER BY LastName ASC, FirstName DESC
Entity Fields vs. Standard Types Mapping
Each Entity Field is annotated in the data dictionary (Field Details section) with the following attributes:
Export: The field can be exported.
Multilingual: The field can be set to multiple values, one per language.
The API considers all field values as String, no matter the type specified in the data model, and use different Export Standard Types to handle the field attributes:
| Export Standard Type (used to handle export responses) |
Attributes |
|---|---|
| String | Export |
| MultilingualStringField | Export Multilingual |
If the checkbox for export is cleared for a given entity field in the data dictionary, this means the field cannot be exported. If the field can be exported, the field is either mapped to a MultilingualStringField if the field is multilingual, or to a String otherwise, no matter the field type (i.e. Boolean, Integer, Float, DateTime).
String
This type is a standard xs:string field, as specified in the Schema W3C reference (http://www.w3.org/TR/xmlschema-2/#string).
Because the API considers any field type as a String, you may be required
to cast the received value to the proper type in your code (see sample).
Sample #1: Retrieve the requisition identifier of an exported Requisition
The Entity Requisition contains
the Field ContestNumber and HasBeenApproved that both correspond to a String field. This sample focuses on the
result handling (we assume the export query was successfully done
by the Web service). It reads the first exported requisition contest
number (requisition identifier) and whether this one was approved
or not.
XML
<ns1:findPartialEntitiesResponse xmlns:ns1="http://www.taleo.com/ws/integration/toolkit/2005/07">
<Entities pageIndex="1" pageCount="1" pagingSize="200" entityCount="1"
xmlns:e="http://www.taleo.com/ws/art750/2006/12"
xmlns="http://www.taleo.com/ws/integration/toolkit/2005/07">
<e:Entity xsi:type="e:Requisition">
<e:ContestNumber>Req001</e:ContestNumber>
<e:HasBeenApproved>false</e:HasBeenApproved>
</e:Entity>
</Entities>
</ns1:findPartialEntitiesResponse>MultilingualStringField
This type is a Taleo object very similar to the String type, but further allows to retrieve multilingual exported values.
Multilingual values are provided individually by locale, each in a
dedicated value object.
Sample #1: Retrieve the current job title of a Candidate
The Candidate entity contains a CurrentJob relation, whose referenced
object contains a CurrentJobJobTitle field that corresponds
to a MultilingualStringField. This sample focuses on the results
handling (we assume the export query was successfully done by
the Web service). It reads the current job from the first exported
Candidate number and outputs the job title for all available languages
(here English, French, and German).
XML
<ns1:findPartialEntitiesResponse xmlns:ns1="http://www.taleo.com/ws/integration/toolkit/2005/07">
<Entities pageIndex="1" pageCount="1" pagingSize="200" entityCount="1"
xmlns:e="http://www.taleo.com/ws/art750/2006/12"
xmlns="http://www.taleo.com/ws/integration/toolkit/2005/07">
<e:Entity xsi:type="e:Candidate">
<e:CurrentJob>
<e:CurrentJob>
<e:CurrentJobJobTitle>
<e:value locale="en">Software Developer</e:value>
<e:value locale="fr">Developeur logiciel</e:value>
<e:value locale="de">Software-Entwickler</e:value>
</e:CurrentJobJobTitle>
</e:CurrentJob>
</e:CurrentJob>
</e:Entity>
</Entities>
</ns1:findPartialEntitiesResponse>