Technical implementation of the PMS interface

From Onlinehelp
Jump to navigation Jump to search

The Umantis Applicant management offers two types of interfaces to Prospective Media (PMS) in order to advertise jobs on this job platform Provider (see Interface: umantis to PMS). Here, we differentiate between a static and a generic interface. The difference is that in the generic interface, sending any job advertising text is permitted, whereas the static interface only allows the transmission of job ID, job title, applicant, and advertising link. In addition, a dedicated (SOAP) interface is supported so that jobs that were created in PMS can be published from Umantis Applicant management (see Interface: PMS to umantis).

Setting up the PMS interface

To set up the PMS interface, certain information must be set up in Prospective Media and certain other settings must be configured directly in the Umantis solution.

Settings in Umantis

General Settings

The following settings must be configured in the general settings of Umantis.

  • URL: The request to publish an advertisement is routed to this URL. By default, the following URL is used: https://saturn.prospective.ch/NJCWeb/services/fastinterface.
  • Prospective Media Services customer ID: Similar to the customer ID in Umantis, a customer has a unique ID in Prospective Media. This ID must be stored accordingly in Umantis and is part of the authentication during data communication.
    Note: Please check with Prospective Media regarding the customer ID to be used.
  • Prospective Media XML: For the <u>Generic interface</u> , that data can be defined in an XML structured document which Umantis has to send to PMS for the purpose of publishing an advertisement. Structure and content can be defined according to the job advertisement requirements. The job data are extracted with the help of Umantis variables.
    Note: Work together with Prospective Media to create a new XML, which better meets your needs than the default interface XML.
  • Hierarchy ID [Optional]: If a user is assigned to multiple hierarchies in PMS, the corresponding hierarchy must be specified in PMS in order to create or advertise a job in PMS. Since there is <u>no</u> standard field in Umantis for this hierarchy ID, the mapping must be implemented and queried by a user-defined field at the branch office in Umantis, for example, by [Branch office.user-definedText1].
    Note: If the hierarchy ID is not transmitted explicitly, this is requested by the system with the help of a form by the user.
User-defined Settings

Certain settings must be configured for each user who should be able to make job advertisements from Umantis to PMS.

  • User security key: The security key is required for authentication of the respective user.
    Note: You will receive the login details directly from Prospective Media. The IDs of those users in Umantis who are permitted to publish advertisements on PMS, must also be saved in Prospective Media.

Settings in Prospective Media

The following Umantis-specific settings must be saved in Prospective Media in order to be able to use the interface:

  • User system ID: The umantis ID of those users who are permitted to use the Prospective Media interface (i.e. publish advertisements via Prospective Media ).
  • Customer ID in umantis: Similar to Customer ID for Prospective Media, which is saved in the Umantis settings, the umantis customer ID must be saved in PMS accordingly. In other words, every ID that you can also find in the Umantis URL: https://recruitingapp-[CustomerID].umantis.com


Generic interface: Umantis to PMS

With the generic interface, now any job data can be transmitted to PMS. The information to be transmitted is extracted by with the help of Umantis variables and subsequently structured by XML and sent to a predefined URL.

Note:

The interface sends the data using HTTP POST arguments, whereby there is no length limitation.

URL call up:

The data for the job advertisement is sent to the following URL:

  • https://saturn.prospective.ch/NJCWeb/services/fastinterface (Default URL)
Note:

If required, the default URL can be configured via the settings in Umantis.

XML structure

The information to be transmitted is extracted with the help of Umantis variables and subsequently structured by XML.

Standard documents

The following standard documents and templates can be used to configure the PMS interface:


Mapping Umantis to PMS

The mapping between the job-specific fields in Umantis and the corresponding fields on the PMS side is achieved primarily by the following structuring elements: 

 <Field FieldName="FieldNamePMS"><Value>[VariableName]</Value></Field>

The field "FieldNamePMS" designates the field label on the PMS side, i.e. the field to which the corresponding data from the Umantis variable "[Variable name]" needs to be assigned.


Prescribed standard fields

Certain fields are specified by PMS and must necessarily be part of data transmission: 

 <Field FieldName="kundeStelleOwner"><Value/></Field>
 <Field FieldName="kundeStelleId"><Value>[Stellen.ID]</Value></Field>
 <Field FieldName="kundeStelleTitel"><Value>[Inserat.PublTitel]</Value></Field>
 <Field FieldName="kundeStelleSprache"><Value>[Inserat.SpracheExternalCode]</Value></Field>


  • CustomerJobOwner: Job owner (can be left blank if author is equal to the job owner, i.e. the following structuring is sufficient "<Value/>")
  • CustomerJobID: ID of the job in Umantis
  • CustomerJobTitle: Publication title of the job in Umantis
  • CustomerJobLanguage: Language of the job in Umantis


Optional standard fields

Other fields are, in fact, specified by PMS regarding the names, but they are optional: 

  <Field FieldName="'''bewerberLink'''"><Value>'''[Stellen.BewerbenLink]'''</Value></Field>
  <Field FieldName="'''hierarchieId'''"><Value>'''[Niederlassung.BenutzerdefText1]'''</Value></Field>
  • applicantLink: Direct link (URL) to the job advertisement (e.g. https://recruitingapp-[CustomerID].umantis.com/Vacancies/[PositionID]/Description/[LanguageID])
  • HierarchyId: Hierarchy ID of the branch office in PMS (if set up in PMS). In other words, if a system user in PMS is assigned to multiple hierarchies, the corresponding hierarchy must be specified to create a job. If the hierarchy ID is not transmitted explicitly, this is requested by the system with the help of a form by the user.
    Note: In Umantis there is no standard field for the hierarchy ID of PMS. The mapping must be implemented and queried by a user-defined field at the branch office in Umantis, for example by, [Niederlassung.BenutzerdefText1].


Customer-specific fields

Finally, as an option, it is possible to use customer-specific fields, which are typically based on the following naming convention Field_ID, whereID is customer-specific or project-specific.

Example:

If a field "feld_20" on the Prospective Media page needs to be filled with the external advertisement text 1 (corresponding variable is "[Ausschreibung.Txt_ext1]"), the configuration for the corresponding element would look like this: 

 <Field FieldName="feld_20"><Value>[Ausschreibung.Txt_ext1]</Value></Field>

Sample XML configuration: 

<?xml version="1.0" encoding="UTF-8"?>

<PMS>
  <!-- Mandatory Fields -->
	<Field FieldName="kundeStelleOwner"><Value/></Field>
	<Field FieldName="kundeStelleId"><Value>[Stellen.ID]</Value></Field>
	<Field FieldName="kundeStelleTitel"><Value>[Inserat.PublTitel]</Value></Field>
	<Field FieldName="kundeStelleSprache"><Value>[Inserat.SpracheExternalCode]</Value></Field>

  <!-- Optional Fields - Standard -->
	<Field FieldName="bewerberLink"><Value>[Stellen.BewerbenLink]</Value></Field>
	<Field FieldName="hierarchieId"><Value>[Niederlassung.BenutzerdefText1]</Value></Field>

  <!-- Optional Fields - Customer Specific -->
	<Field FieldName="feld_20"><Value>[Ausschreibung.Txt_ext1]</Value></Field>
	<Field FieldName="feld_40"><Value>[Inserat.PublTitelMLExternal]</Value></Field>
	<Field FieldName="feld_50"><Value>[Ausschreibung.Txt_ext2]</Value></Field>
	<Field FieldName="feld_60"><Value>[Ausschreibung.Txt_ext3]</Value></Field>
	<Field FieldName="feld_100"><Value>[Ausschreibung.Txt_ext5]</Value></Field>
	<Field FieldName="feld_300"><Value>[Stellen.ID]</Value></Field>

</PMS>

Other documents


Static interface: Umantis to PMS

In the static version of the PMS interface, a specified amount of data elements are transmitted. Job advertisement texts and publication options cannot be transmitted to PMS (see Generic PMS interface). In the process, the data is transmitted using URL parameters, as a result of which there is a length restriction on the data to be sent (255 characters).

Note:

Since advertisement texts and publication options cannot be transferred to PMS, corresponding advertisement contents are therefore not maintained in Umantis, but on Prospective Media itself. The job advertisement process works in such a way that the job, in fact, is created in Umantis, but the job advertisement is published via PMS. With the publication activity, a new job is automatically created in the background in Prospective Media and the user automatically arrives in the PMS order entry to the first "job". The login is implicit. In Prospective Media the media is then selected that will ultimately be use to place the job ad online.


Data elements transmitted by Umantis

The following records are sent by default from Umantis to PMS:

  • Job ID
  • Job title
  • Applicant link
  • Advertisement link
  • Job language


URL call up:

The data for the job advertisement is sent to the following URL:

  • http://www.prospective.ch/cfm/fastinterface.cfm (Default URL)
Note:

If required, the default URL can be configured via the settings in Umantis.

URL parameters

The following URL parameters are supported with the static PMS interface:

Parameter name Description
CustomerID* Prospective Media customer ID: Is saved in the general settings of Umantis.
techNode* System user that records the position/order.
This information is used as an authentication key and is made up of the customer ID and the user security key.
In order to be able to write out the position in Prospective Media, in addition to the customer ID, a personal key is also needed which must be defined for each user in his/her settings. Both are assigned by Prospective Media.
CustomerJobID* ID of the job in umantis.
CustomerJobTitle* Title of the job in umantis.
CustomerJobLanguage* Language in which the job is written (in PMS).
applicantLink
directLink
CharacterSet

* = "Mandatory" URL arguments


Other documents


Interface: PMS to Umantis

Ads that were created in Prospective Media can be transmitted back to the Umantis applicant management system using this dedicated SOAP interface.
Data communication from Prospective Media (PMS) to Umantis is realized via a dedicated SOAP interface and supports the following WSDL structure:


WSDL input:
Data that can be transmitted from PMS to Umantis from the SOAP interface.

FieldName DataType
customer string
external_userid string
umantis_userid string
external_positionid string
umantis_positionid string
Digest string
external_title string
short_description string
company_id string
notification_email string
publication_languageid string
publication_templatecode string
publication_online_internet string
publication_online_intranet string
publication_online_internet_main_company string
publication_online_intranet_main_company string
online_application_not_possible string
online_application_without_publ_possible string
publication_meta_data string
publication_texttitle1 string
publication_text1 string
publication_texttitle2 string
publication_text2 string
publication_texttitle3 string
publication_text3 string
publication_texttitle4 string
publication_text4 string
publication_texttitle5 string
publication_text5 string
publication_texttitle6 string
publication_text6 string
publication_texttitle7 string
publication_text7 string
publication_texttitle8 string
publication_text8 string
contact_person string
external_apply_link string
external_apply_link_plain string
external_posid_numeric string
positionids string
count_only_srcID string



WSDL-Output:
The following data from Umantis is sent to PMS in response to the SOAP call.

FieldName DataType
position_id string
status string
application_counters string
customer string
version string
user_id string
loginname string
password string


Note:

  • In addition, the Umantis job market can also be set up as a publication medium, so that the job advertisement texts are imported into the respective positions in Umantis, and the Job advertisement on the homepage is initiated via the publication platform.
  • You can find a general description for the SOAP technology under the following URL: http://de.wikipedia.org/wiki/SOAP


Settings in Umantis

The following settings need to be made before Umantis Applicant management can be used as a job platform provider:

  • URL: The request to publish a job advertisement is routed to this URL (e.g. https://recruitingapp-1067.umantis.com).
  • Branch ID in the third party system: umantis-ID of the branch office at which the job is created in the third party system, and at which the branch office-specific advertisement is to be placed.
  • User ID in the third party system: umantis-ID of the user in third party system via which the advertisement is to run. In the target AM there needs to be a user in whose name the job advertisement is done (the relevant ID can be found in the URL for the user profile).
  • Authentication key for third party system: To verify the interface, the two solutions swap keys. Here you enter the same key that was entered in the target AM in the Company settings/Organization profile in the "Authentication key for publication from third party system" field.
  • Advertisement layout code for third party system job advertisement: In the target system you can automatically activate a particular Advertisement layout for the advertisement. However, this setting is optional or even superfluous if you have previously selected a different advertisement layout for the job. The priority will be for the code for this layout to be sent to this latter setting.

Notes:

  • Make sure that the link for the application form in all advertisements points straight to the AM instance itself.
  • PMS can transmit up to five text fields (title field plus four more fields)
  • A separate job advertisement is recorded and transmitted to Umantis per language.
  • If a job is transmitted into the solution from PMS via "Create job advertisement on umantis", the job will be advertised directly on the job market. This means that the job advertisement may be manually undone, if needed.
  • Each time the interface is triggered, the application link is also sent to the target AM and can be used from the field "Textblock 6" from the job advertisement concerned with the Template variable [Inserat.Text6].


Related subjects

Retrieved from "https://en.onlinehelp.umantis.com/index.php?title=Technical_implementation_of_the_PMS_interface&oldid=8757"