travel: xml based profile synchronization travel service guide - … · 2020. 6. 8. · concur...

Travel: XML Based Profile Synchronization

Travel Service Guide

Last Revised: June 8, 2020

Applies to Concur Travel:

Professional/Premium edition

TMC Partners Direct Customers

Standard edition

TMC Partners Direct Customers

Travel: XML Based Profile Synchronization Travel Service Guide i Last Revised: June 8, 2020

© 2004 - 2021 SAP Concur All rights reserved.

Contents

XML Based Profile Synchronization ..............................................................................1

Section 1: IMPORTANT – About This Guide .................................................................. 1

Section 2: Overview ................................................................................................. 1

Section 3: NOTICE ................................................................................................... 1

Section 4: How It Works ........................................................................................... 2 Post New/Updated Profile Data ............................................................................ 2 Request New/Updated Profile Data (Via Post) ........................................................ 3 Profile Processing Methodology ............................................................................ 4 Option to Have Accepted Profiles Set the Updated Timestamp But Not Synced Timestamp ....................................................................................................... 5

Section 5: XML Schema and Mapping ......................................................................... 5

Section 6: Predefined Entities in XML .......................................................................... 6 Available Fields ................................................................................................. 6

Section 7: Profile Sync Validation & Troubleshooting .................................................. 19

Section 8: Configuration ......................................................................................... 20 Configuration by Concur Travel ......................................................................... 20 Configuration by the TMC ................................................................................. 21

Section 9: FAQ ...................................................................................................... 25

Section 10: Appendix A – Sample XML Post VBS Script ............................................ 27 xmlpost.vbs .................................................................................................... 27

ii Travel: XML Based Profile Synchronization Travel Service Guide Last Revised: June 8, 2020


Revision History Date Revision Notes/Comments

April 14, 2021 Updated the copyright year; no other changes; cover date not updated

June 8, 2020 Clarified the password description in XML Sync Authorization topic under the

Configuration by the TMC section

June 2, 2020 Updated the password description in XML Sync Authorization topic under the Configuration by the TMC section

February 14, 2020 Updated the copyright; no other changes; cover date not updated

June 20, 2019 Removed "Concur" from the cover; no other changes; cover date not updated

March 10, 2019 Updated the copyright; no other changes; cover date not updated

January 3, 2018 Updated the copyright; no other changes; cover date not updated

February 3, 2017 Moved to a deprecated state

December 18, 2014 Changed: http://www.concursolutions.com/ns/TravelProfileType.xsd

To: https://www.concursolutions.com/ns/TravelProfileType.xsd

December 8, 2014 Full review with R&D code validation for accuracy.

July 24, 2014 Added clarifying information to "Configuration by the TMC" step 4

May 20, 2014 General updates; initial publication in the new format

August 2012 Last update in the old format

Travel: XML Based Profile Synchronization Travel Service Guide 1 Last Revised: June 8, 2020


XML Based Profile Synchronization

Section 1: IMPORTANT – About This Guide

Be aware of the following:

• Infinite variables: Certain scenarios have an infinite number of variables or

extremely unusual circumstances, like rare cancellation or refund situations. So, not all scenarios can be presented in this guide. Also, certain processes may be influenced by third- or fourth-party providers. In some cases, you must contact the provider directly.

• User interface, fees, rates, schedules: When other providers change their

user interface (for example, web site) or their fees/rates/schedules, they are under no obligation to make SAP Concur aware of those changes. If a screen sample in this guide is outdated because of a change made by a provider, we

will update that screen sample when we become aware of the change and at our earliest convenience.

• Permissions: A company's admin may or may not have the correct

permissions to manage the feature described in this guide. If an admin needs to manage this feature and does not have the proper permissions, they should contact the company's SAP Concur administrator.

Also, the admin should be aware that some of the tasks described in this guide

cannot be completed by the company. In this case, the client must contact their TMC (if a TMC provides their support) or SAP Concur (if SAP Concur provides their support).

Section 2: Overview

This document provides a summary of the profile synchronization approach between Concur Travel and an external profile management system hosted by a travel agency or corporate customer. SAP Concur provides a method for synchronizing profile information using a batch XML data transfer via HTTPS. This process can be used to create new traveler profiles and/or update existing traveler profiles in Concur Travel.

An external profile tool can send updates to Concur Travel and can also request updates from Concur Travel. Customers/TMCs have the option to have this synchronization process work both ways or one way. This will vary depending on the

type of site implemented – Concur Travel-only or Travel integrated with Expense.

Access to travel preference data found in Concur Travel can also be restricted to allow users to make updates only in the external profile tool.

Section 3: NOTICE

As of June 2017, support is no longer provided for XML Profile Sync to synchronize profile data with Concur Travel.

2 Travel: XML Based Profile Synchronization Travel Service Guide Last Revised: June 8, 2020


Section 4: How It Works

The method for synchronizing profile information allows an agency or corporate customer to:

• Send new profiles or profile changes to Concur Travel (XML post via HTTPS) from a replication client on the outside of SAP Concur's firewall – and –

• Receive new Concur profiles or profile changes (XML request via HTTPS)

Post New/Updated Profile Data

A replication client running at the agency/customer site obtains new or updated profile information from the external database and posts the new or updated profiles to a URL in a standard XML format. Both the URL and XML format are provided by Concur Travel.

NOTE: The agency/customer should schedule posts periodically based on user volume.

Each batch can contain a maximum of 50 changed profiles. Multiple batches should be run to accommodate more than 50 new or updated profiles per scheduled post.

Concur Travel accepts the XML post via an .ASP proxy page that then transfers the profile data to Microsoft .NET web service, which manages the profile additions or updates in the Concur database.

Once an XML post (acceptProfiles_request.xml) is made by the replication client to

Concur Travel’s ASP (https://app2.outtask.com/twsproxy/acceptProfiles.asp), it returns one of the following XML responses (refer to Appendix A for sample XML):

AcceptProfiles responses:

• Error while formulating login id:

• Error while formulating password

• POST is the only method supported

• Secure HTTP is required to use this service

• Profiles node not found

• The limit of 50 profiles per request was exceeded.

• ClientName node not found

• ClientUserID node not found

• ClientUserID value not found.

• ClientPassword value not found

• Client node not found.

• INVALID_SEARCH_ID



• REQUEST_ERROR (this typically means wrong sync password or XML profile

sync isn't set up)

• SUCCESS

Accept profiles successful response:

<?xml version="1.0" encoding="UTF-8"?> <TransactionStatus TransactionDateTime="2/12/2010 2:19:05 PM">

<ProfilesReceived>2</ProfilesReceived> <ProfilesProcessed>2</ProfilesProcessed> <Errors> <Error>

<ErrorCode>0</ErrorCode> <ErrorText>SUCCESS</ErrorText> <ErrorDescription/> </Error>

</Errors> </TransactionStatus>

Request New/Updated Profile Data (Via Post)

The replication client running at the agency/customer site requests new or updated profiles from a URL in a standard XML format. Both the URL and XML are provided by Concur Travel.

NOTE: The agency/customer should schedule requests periodically based on user volume.

Each batch can contain a maximum of 50 new profiles or profiles updates. Multiple batches should be run to accommodate more than 50 new or updated profiles per scheduled request.

Concur Travel receives the XML request via an .ASP proxy page that then retrieves the profile data via SOAP from the Microsoft .NET web server, which manages any new profile additions or profile updates in the Concur Travel database.

Concur Travel stores two date/time stamps to determine the profile data that should be returned with the incoming XML request:

• TRAVEL_PROFILE_LAST_UPDATED: The last time a user update was done (this field is not populated when a user is added, only on updates).

• TRAVEL_PROFILE_LAST_SYNC: The last time an automated sync was done.

There are four instances where a profile is updated:

• User saving profile or profile edited in Concur XA

• Update via (legacy) Concur Travel HR feed

• Integrated Travel and Expense: update via Concur Travel’s Employee Import

and synced from Expense (for example, 300/350 record types)



• Travel only: Update via Concur Travel’s Employee Import directly (for

example, 310/350 record types)

Once an XML request (returnProfiles_request.xml) is made by the replication client to Concur Travel’s ASP (https://app2.outtask.com/twsproxy/returnProfiles.asp), Concur Travel returns one of the following XML responses (reference the toolkit and appendix A for sample XML):

ReturnProfiles responses:

• Secure HTTP is required to use this service

• POST is the only method supported

• Profiles node not found

• ClientName node not found

• ClientUserID node not found

• ClientUserID value not found

• ClientPassword value not found

• ClientName too long:

• ClientUserID too long:

• Security error

• Invalid ClientName, ClientUserID or ClientPassword

• SUCCESS

Example of profile request:

<ProfileRequest TransactionDateTime="10/7/2002 6:14:53 PM"> <Client> <ClientName>outtask</ClientName> <ClientUserID>outtask</ClientUserID> <ClientPassword>outtask</ClientPassword> <ExtendedOutput>True</ExtendedOutput> ** </Client> <RequestID>0</RequestID> <MaxRecords>50</MaxRecords> <UseNamespace>0</UseNamespace> </ProfileRequest>

** ExtendedOutput is an optional element. If the agency/customer includes it, we will include additional identifying information in the response.

Profile Processing Methodology

Note the following:

• The batch process occurs on a scheduled basis, once a day.

• Each post and request (via post) operation will process a maximum of 50 new profiles or profile updates.



• The post and request (via post) operations are not run in parallel.

Option to Have Accepted Profiles Set the Updated Timestamp But Not Synced Timestamp

XML Profile Sync currently updates the TRAVEL_PROFILE_LAST_SYNC date in Concur Travel’s preferences table when the agency/customer receives a modified profile

from Concur and when the agency/customer sends a modified profile to Concur Travel. This action is based on the Automatically Populate Profile Last Updated Date (recommended for customers who have the Concur Travel profile hidden) field in the XML Sync Authorization section of the travel configuration page.

If the agency/customer has not done a recent call to get modified profiles sending changes to Concur Travel, they might not be notified of changes that users have made to their own profiles. This is because Concur Travel will mark the profile synced when the agency/customer sends Concur Travel a change, even if there was a previous change ready to be synced. Disabling this new option will change that behavior.

XML Profile Sync currently does not set the TRAVEL_PROFILE_LAST_UPDATED date when the agency/customer sends Concur Travel modifications to a profile. This option also changes that behavior.

These two changes together mean that when selected, profiles changed by the agency/customer through XML Profile Sync return when the agency/customer requests all modified profiles (refer to the configuration information in this guide).

Section 5: XML Schema and Mapping

Below is a link to the XML Schema and an explanation of the XML tags in the

acceptProfiles_request.xml file:

• TravelProfile.xsd is a link to the XML Schema.

https://www.concursolutions.com/ns/TravelProfile.xsd

• TravelProfileType.xsd is the link to an explanation of the XML data.

https://www.concursolutions.com/ns/TravelProfileType.xsd

Note the following:

• If an XML tag is not present, the Concur Travel database field is not altered.

• If an XML tag has no value, the Concur Travel database field is set to NULL.

• ProfileType.SearchID.SearchIDValue is mandatory for all user profiles.

• As best practice, ProfileType.General.RuleClass should also be included for all user profiles. If none is provided, we use the company's default rule class.

• The following tags are required to create a user:

ProfileType.General.FirstName

https://www.concursolutions.com/ns/TravelProfile.xsd

https://www.concursolutions.com/ns/TravelProfileType.xsd



ProfileType.General.LastName

ProfileType.General.CompanyEmployeeID

NOTE: CompanyEmployeeID is required if the customer uses integrated Concur Travel & Expense or if the default Profile Sync Id is based on Employee ID.

ProfileType.EmailAddresses.EmailAddress

NOTE: EmailAddress is required if Login ID is based on email address. Type "Business" is also required if Login ID is based on email address.

Section 6: Predefined Entities in XML

The XML specification defines five "predefined entities" representing special characters, and requires that all XML processors honor them. The table below lists the five XML predefined entities. To render the character, the format &name; is used; for example, & renders as &. If the profile data contains any of the

characters listed below, the agency/customer must use the XML format in order to render them correctly.

Name Character Description XML Format

quot " double quotation mark "

amp & ampersand &

apos ' apostrophe (= apostrophe-quote)

'

lt < less-than sign <

gt > greater-than sign >

Available Fields

XML Tag

Corresponding

Field in Concur Profile or XML

Sync Administrative Pages

Comment

<Profiles

TransactionDateTime="2002-08-06T16:00:12 GMT">

N/A



XML Tag

Corresponding



Comment

<ClientName>DeterminedByCusto

mer/TMC</ClientName> Company Code Customer and Concur

Implementation team determine value. The Value is specific to each

corporate customer Concur site. This value must be unique and cannot be used on multiple sites.

<ClientUserID>

DeterminedByCustomer/TMC</</ClientUserID>

User Field Determined by TMC and customer.

This value does not have to be unique by site.

<ClientPassword> DeterminedByCustomer/TMC</</

ClientPassword>

Password This value is randomly generated when the new password button is

selected by the TMC within the Profile Sync Configuration section.

<Profile Status="Active"

PersonCode="" PersonDBC="" LoginID="">

N/A,

PersonCode (Custom Field)*, PersonDBC

(Custom Field)*

Status should be set to "Active".

If applicable to agency: PersonCode and PersonDBC, otherwise should be left empty.

The LoginID is used in requests only, and can be used to retrieve a

login ID from Concur to be used in the agency system and GDS as a

CliqUserID. This value is critical.

<"General">

<NamePrefix>MR</NamePrefix> Title Predefined localized list

<FirstName>John</FirstName> First Name 60 character limit per field

*Read Only fields <MiddleName>Robert</MiddleNa

me> Middle Name

<LastName>Smith</LastName> Last Name

< <NameSuffix>Jr.</NameSuffix>

Suffix Accepted Values:

• Jr

• Sr

• I

• II

• III

• IV

• V

• VI

<PreferredName>Willie T</PreferredName>

Nickname 60 character limit



XML Tag

Corresponding



Comment

<NoMiddleNameFlag>false</NoMi

ddleNameFlag> Middle Name Values of true or false. If middle

name included, also send "false" for NoMiddleName, we'll ignore false

and make it true in the database.

<Gender>Male</Gender> Gender Male or Female

<NameOnTicket/>

Company

Employee Name

<BirthDate>YYYY-MM-DD</BirthDate>

Date of Birth (mm/dd/yyyy)

<JobTitle>The Boss</JobTitle>

Employee

Position/Title 60 character limit

<JobDivision>Travel</JobDivision>

Org. Unit/Division

Value provided must be setup in Org Unit Admin prior to sync

<RuleClass>Default

Class</RuleClass> Rule Class Value highly recommended in all

cases, and required if using divisional view.

<CostCenter>1111-2222</CostCenter>

Cost Center 25 character limit

<CompanyEmployeeID>1234</Co

mpanyEmployeeID> Employee ID Strongly recommended, and

required for customers integrated with Concur Expense or if default

Profile Sync Id value is set to EmployeeId.

48 character limit

*Read-only when field maintained via an employee load

<TravelCRSName>SMITH/JOHN</

TravelCRSName> Par/Level 2 Star

<MedicalAlerts>Diabetic</MedicalAlerts>

Medical Alerts 30 character limit – no special validation unless synchronizing to the GDS, then a filter can be

applied.

<LanguagePref>EN-US</LanguagePref>

Default Language

2-5 character limit depending on the supported language of Concur,

not case sensitive.

If Concur cannot process this language preference for a user for

any reason, en-us is the defaulted language.



XML Tag

Corresponding



Comment

<SearchIDValue>123321</Search

IDValue>

XML Profile Sync

ID

UNIQUE IDENTIFIER FOR CONCUR

USER PROFILE. THIS VALUE MUST BE POPULATED.

60 character max

The search ID may contain any

characters that are supported in an email address. However, if using the search id as part of the login id,

the SearchId cannot contain any special characters other than underscore (_), hyphen or dash( -),

period (.), and at symbol (@). See Configuration by the TMC section of

this guide for more information.

If using GDS profile sync, use a filter in the PNR finishing template

to accurately configure this.

NOTE: There is no validation within

Concur Travel that this value is unique. The agency/customer must

ensure whether user is created through XML Sync, User Admin UI, or Employee Feed into Concur, that

this value is unique to the individual user. For existing profiles the tag value must match what is already in

Concur Travel.

<SearchIDPassword Update="true"/>

Password Optional password that can be provided for new users. This option

is not recommended as the password is sent in the XML – SAP Concur recommends using one of

the random password settings in the configuration. If a password is sent, it will overwrite the

configuration settings for this customer.

Update attribute optional value must either be true or false. If set

to true, the password will change on subsequent updates.

<EmergencyContactName>Jane Smith</EmergencyContactName>

Emergency Contact Name

First name separated with a space, then the last name.

255 character limit

<EmergencyContactRelationship> Spouse</EmergencyContactRelati

onship>

Emergency Contact

Relationship

Predefined localized list: spouse, wife, husband, brother, parent,

father, mother, sister



XML Tag

Corresponding



Comment

<EmergencyContactTelephone

Type="DayTime">

Emergency

Contact Phone,

Alternate Phone

Types available respective to fields

listed: DayTime and Alternate.

<EmergencyContactTelephoneCountryCode>001</EmergencyContac

tTelephoneCountryCode>

<EmergencyContactTelephoneArea

CityCode>314</EmergencyContactTelephoneAreaCityCode>

<EmergencyContactTelephoneNum

ber>5858855</EmergencyContactTelephoneNumber>

<EmergencyContactTelephoneExtension/>

<Telephone Type="Work"> Work Phone,

Work Fax, 2nd Work

Phone/Remote Office, Home Phone, Pager,

Other Phone

Types available respective to fields

listed: Home, Work, Cell, Fax, Pager, and Other. If Work is

specified twice, then second instance will populate 2nd Work Phone/Remote Office.

<TelephoneCountryCode>001</Te

lephoneCountryCode>

<TelephoneAreaCityCode>314</TelephoneAreaCityCode>

<TelephoneNumber>5258588</Te

lephoneNumber>

<TelephoneExtension/> Work Extension

<TelephoneContactName/> N/A This value cannot be sent to Concur

Travel, but it will provide it in the case of Manager Contact Name or

Travel Arranger Contact Name.

<Address Type="Work"> Designates Work Address & Home Address sections

Address Types: Home, Work – All others are not stored

<Line1>1 Washington

Ave</Line1> Street (line 1)

<Line2/> Street (line 2)

<Line3/> Street (line 3)

<City>St Louis</City> City

<StateProvince>MO</StateProvince>

State/Province/Region

<CountryCode>US</CountryCode

> Country 2-letter ISO country code



XML Tag

Corresponding



Comment

<ZipCode>63043</ZipCode> Postal Code

<CreditCard

DisplayName="Corporate Card">

Display Name

(e.g., My Corporate Card)

<CreditCardVendor>AX</CreditCa

rdVendor> Card Type Accepted types:

• Unknown: Unknown

• American Express: AX

• Diners Club: DC

• Discover: DS

• MasterCard: CA

• Visa: VI

• Carte Blanche: CB

• Enroute: ER

• Universal Air Travel: TP

• JCB: JC

• American Airlines: AA

• Delta Equity: DL

• Northwest Airlines: NW

• TWA Getaway: TW

• United Travel Card: UC

• United Credit Card: UA

• Euro Card: EC

• Canadian Airlines: CP

• Alaska Air Barter: AS

• Purchase Order: PO

• Award Credit: AWRDCR

• Debit: DB

• China Union Pay: UP

<CreditCardAccountNo>41111111

11111111</CreditCardAccountNo>

Credit Card

Number

<CreditCardExpDate>YYYY-

MM</CreditCardExpDate> Expiration Date

<NameOnCard>John Smith</NameOnCard>

Your name as it appears on this card



XML Tag

Corresponding



Comment

<Usage Type="BusinessAir"

PrimaryIndicatorFlag="true" />

Use this card as

the default card for: Plane

Tickets,

Rail Tickets, Car Rentals, Hotel

Reservations

Credit Card Usage Types supported:

BusinessAir, BusinessRail BusinessCar, BusinessHotel,

PersonalAir, PersonalCar, PersonalHotel, PersonalRail.

Primary Indicator Flag attribute:

true, false

NOTE: Although types are defined

for all cards added in the XML, Concur Travel only stores cards with the PrimaryIndicatorFlag="true"

The UI has a card option for Taxi which is not supported in the XML.

<BillingAddress><StreetAddress>

123 My St</StreetAddress><City> Alexandria</City><

StateProvince>VA</StateProvince><Country>US</Country><

ZipCode>22314</ZipCode>

Billing Address:

Street, City, State, Country, Zip/Postal Code

<NationalIDNumber>277888272</NationalIDNumber>

National ID Number

<NationalIDIssuingCountry>US</NationalIDIssuingCountry>

National ID Country

Valid two-letter ISO country code (US, GB, etc.)

<NationalIDExpiration>2020-01-

01</NationalIDExpiration>

National ID

Expiration (mm/dd/yyyy)

<DriversLicenseNumber>T237888

222</DriversLicenseNumber>

Driver License

Number

<DriversLicenseIssuingCountry>U

S</DriversLicenseIssuingCountry>

Driver License

Country

Valid two-letter ISO country code

(US, GB, etc.)

<DriversLicenseIssuingState>VA</DriversLicenseIssuingState>

Driver License State

Valid two-letter state code

<DriversLicenseExpiration>01-15-

2013</DriversLicenseExpiration>

Driver License


<HasNoPassport>false</HasNoPas

sport>

I do not have a

passport

This value will be set as true if any

passports are passed in.

<PassportNumber>12345</Passp

ortNumber> Passport Number



XML Tag

Corresponding



Comment

<NameOnPassport>John

Smith</NameOnPassport>

No

corresponding profile field

<PassportExpDate>2008-06-

06</PassportExpDate>

Passport


<PassportIssueDate>2001-01-01</PassportIssueDate>

Passport Date Issued

(mm/dd/yyyy)

<PassportIssuePlace>London</PassportIssuePlace>

Passport Place Issued (City, State / Country)

<PassportCitizenship>GB</Passpo

rtCitizenship>

Passport

Nationality

Valid two-letter ISO country code

(US, GB, etc.)

<PassportIssuingCountry>GB</PassportIssuingCountry>

Passport Place Issued (City,

State / Country)

<VisaNumber>2344</VisaNumber

> Visa Number

<VisaExpDate>2005-06-06</VisaExpDate>

Visa Expiration (MM/DD/YYYY)

<VisaType>SE</VisaType> Visa Type

<VisaCitizenship>GB</VisaCitizen

ship> Visa Nationality

<VisaPlaceIssued>SE</VisaPlaceIssued>

No corresponding profile field

<VisaTravelDestination>US</Visa

TravelDestination> VISA Nationality Valid two-letter country ISO code

required

<VisaDateIssued>2010-21-08</VisaDateIssued>

No corresponding

profile field

<VisaCountryIssued></VisaCountryIssued>

No corresponding profile field

<EmailAddressValue>business@m

ail.com</EmailAddressValue> Email 1-5



XML Tag

Corresponding



Comment

<EmailAddress Type="Business"> EmailAddress Types: Business and

Personal, Business2 (Displays as "Contact?" = No).

Other1 and Other2 are also accepted if the user has Open Booking permissions. If Supervsr is

provided, it will assign the person who that email address belongs to

as the Manager of user of the profile being synced.

EmailAddress Types not stored:

Supervsr, TrvlArr

<AAARate>true</AAARate>

AAA/CAA True or false

<AARPRate>true</AARPRate>

Senior/AARP True or false

<GovtRate>true</GovtRate>

Government True or false

<MilitaryRate>true</MilitaryRate>

Military True or false

<Air />

<AirSmokingCode/> True or false

<AirMembershipChain>AA</AirMembershipChain>

Carrier There is no limit to the number of frequent flyer memberships

<AirMembershipLevel>Senator</A

irMembershipLevel>

I have Senator

Status

Lufthansa's Senator Status can be

included with the frequent travel number for Lufthansa. The <AirMembershipLevel> node, which

was previously unused, will now serve this purpose.

If you include SENATOR as the <AirMembershipLevel> for a Lufthansa frequent traveler number,

we will note it in the user's profile. We will also include this line in profiles we return when the user

has Senator Status (we will leave this node out when null).

Please note that although this node has been in our XML schema for

quite some time, this is the first use of the fields in our output.



XML Tag

Corresponding



Comment

<AirMembershipAccountNo>12221

11</AirMembershipAccountNo>

Frequent

Traveler/Driver/ Guest Number

<AirMembershipPreferredFlag>tru

e</AirMembershipPreferredFlag>

Search this

vendor True or false

<AirMembershipExpirationDate> Applies to Deutsche Bahn rail only

<AirMembershipDefaultFlag>false

</AirMembershipDefaultFlag>

Make default for

all……

Default for the airline alliance

programs

<InterRowPositionCode>Window</InterRowPositionCode>

Seat Accepted values:

• Aisle

• AisleAcross

• Center

• Window

• NOPREF

<SectionPositionCode>Forward</

SectionPositionCode>

Air/Rail

Preference Section

Rail only (Bulkhead, Forward, Tail,

Wing, Exit, Rear, Rear/Tail, NOPREF)

<MealCode>FPML</MealCode> Special Meals

<HomeAirport>IAD</HomeAirport

>

Preferred

Departure Airport

<DHSRedressNumber>233522</DHSRedressNumber>

DHS Redress No

<DHSKnownTravelerNumber>123

45</DHSKnownTravelerNumber>

TSA Pre Check

Known Traveler Number

<AirOther>Need extra air sickness bags</AirOther>

Other Air Travel Preferences

<Car />

<CarSmokingCode/> Smoking

Preference True or false

<CarGPS>true</CarGPS> GPS True or false



XML Tag

Corresponding



Comment

<CarOption>CBAR</CarOption> Car Type Accepted Types:

• Economy

• Compact

• Intermediate

• Standard

• Full-size

• Luxury

• Premium

<CarMembershipChain>AL</CarMembershipChain>

Car Rental Company

<CarMembershipAccountNo>2334

44</CarMembershipAccountNo>

Frequent


<CarMembershipPreferredFlag>true</CarMembershipPreferredFlag>

Search this vendor

<CarOther>Prefer red cars with

sunroof</CarOther>

Other Car

Preferences

<CarSkiRack>false</CarSkiRack> Ski Rack True or false

<Hotel />

<SmokingCode>false</SmokingCode>

Smoking Preference

True or false

<Remark>KING BED

PREFERED</Remark> Looks for the following words within

the values sent to store in the database:

• "disability"

• "king"

• "double"

• "twin"

Concur does not recommend using

this field. Recommended field to capture room preference is

RoomType.

<HotelMembershipChain>AM</Hot

elMembershipChain> Hotel

<AccountNo>23344</AccountNo> Frequent Traveler/Driver/

Guest Number



XML Tag

Corresponding



Comment

<PreferredFlag>true</PreferredFla

g>

Search this

vendor

<RoomType>King</RoomType> Room Type Acceptable values:

• King

• Queen

• Double

• Single

• Twin

• Disability

<HotelOther>Need south facing room</HotelOther>

Other Hotel Preferences

<PreferFoamPillows /> True or false

<PreferCrib /> True or false

<PreferRollawayBed /> True or false

<PreferGym /> True or false

<PreferPool /> True or false

<PreferRestaurant /> True or false

<PreferWheelchairAccess /> True or false

<PreferAccessForBlind /> True or false

<PreferRoomService /> True or false

<PreferEarlyCheckIn /> True or false

<AdvantageMemberships/> There are presently three examples of Advantage Memberships: Air

France, Lufthansa, and Deutsche Bahn.

The Vendor, VendorType, CardNumber should always be provided.

The Program Code corresponds to our code table in Concur Travel.

<VendorCode>AF</VendorCode> Carrier

<VendorType>Air</VendorType>

<CardNumber>1234567</CardNu

mber>

Frequent




XML Tag

Corresponding



Comment

<DiscountPercentage>0</Discoun

tPercentage> BahnCard Type Only used for Deutsche Bahn -

ignored if provided for other Advantage Memberships

<ClassOfService/>

<DestinationCode/>

<DestinationStationCode />

<OptionCode />

<OriginCode />

<OriginStationCode />

<ProgramCode>AFABT</Program

Code> Required, except for Deutsche Bahn

<ExpirationDate>2016-02-

28</ExpirationDate> Expiration Date

<ClientQuestion1>AA1234</ClientQuestion1>

Tags used for custom fields. ClientQuestion numbering/order

should be discussed with the Concur Implementation Team. Maximum of 50 client questions with no

character max.

Custom fields created during

implementation

<UnusedTickets/> Unused tickets will display in the profile, during air searches, and stored in Company Administration >

Unused Tickets.

<ValidCarrier>AA</ValidCarrier> Carrier Required field

<DocumentNo>0017098389895 </DocumentNo>

Ticket Number, TranPlatingNbr,

TranControlNbr

Required field

<PNRLocator>ABC123</PNRLocat

or> Record Locator

<IssueDate></IssueDate> N/A Stored in the database

<GrossFare>274.65</GrossFare> Total Fare

<Tax>35.00</Tax> Taxes

<Fees>8.00</Fees> Fees

<CurrencyCode>USD</CurrencyCode>

Currency Code



XML Tag

Corresponding



Comment

<TicketType>1</TicketType> N/A Stored in the database; purpose

under investigation.

<TicketCreateDate>MM/DD/YYYY</TicketCreateDate>

Purchase Date

<ManualNote></ManualNote> Notes/Remarks

<FirstTravelDate>MM/DD/YYYY</F

irstTravelDate> N/A Stored in the database; purpose

under investigation.

<ExpirationDate>MM/DD/YYYY</E

xpirationDate> Expiration Date

<NumberOfPassengers></NumberOfPassengers>

N/A Stored in the database; purpose under investigation.

<Role/>

<Role Type="Manager"

PrimaryIndicatorFlag="true">

Manager or

Arranger

This allows manager or arranger

association to traveler. Role Types: Manager, Arranger PrimaryIndicatorFlag should always

be set to 'true'.

*A manager can be different

between travel and expense via the 300/350 record.

<RolePersonSearchID>12345</RolePersonSearchID>

This is the <SearchIDValue> of the traveler's manager or arranger

<RolePersonFirstName>John</Rol

ePersonFirstName>

These values are provided on

output but are not used for requests.

<RolePersonLastName>Smith</Ro

lePersonLastName>

These values are provided on

output but are not used for requests.

Section 7: Profile Sync Validation & Troubleshooting

Concur Travel logs all XML Profile Sync requests and responses in the GDS logs. The category is XMLProfileSync. The agency/customer can search:

• RequestType of "ReturnProfiles" to view the profiles Concur Travel has returned.

• RequestType of "AcceptProfiles" to view the profiles Concur Travel has received.



The same log entry contains both the request and the response from XML Profile Sync.

The agency/customer can use the Search within results field to look for a particular user (the user's ProfileSyncID will appear in the associated request).

To locate a particular company's requests and responses, the agency/customer can search for the Client ID they use to sync (each company has a Client ID, a Client UserID and a Password that they include in the XML requests).

Concur Travel has re-used the Database name field in the search form. In the example below, the Client's ID is TestCompany. You can see both ReturnProfiles and AcceptProfiles requests in the output.

Section 8: Configuration

Users with the Profile Sync Administrator permission can access the XML Sync Authorization section of the company travel configuration page. This section of the

travel configuration page is used by TMCs to configure the XML synchronization for their individual customer sites.

Configuration by Concur Travel

Concur Travel automatically assigns the Profile Sync Administrator permission to the default user when one of the XML Sync check boxes is selected on the Online

Order Form.

Before the TMC can configure, Concur Travel will:

1. Verify the Profile Sync User Permission is associated to the login ID.

2. Navigate to the Profile Sync Configuration link and select the "unrestricted sync" option.



Configuration by the TMC

Then the TMC can follow these steps to configure XML sync.

1. Click Administration > Travel System Admin and access the desired client travel configuration.

NOTE: A unique XML Sync setup is required when using multiple travel

agencies and/or the Divisional Admin View functionality.

2. Scroll down to the XML Sync Authorization section.

3. Complete the fields as appropriate:

Field Description

Company Code Enter a unique id.

This value must be unique across all Concur Travel clients

Preferred naming best practice: Concur Company ID (CID)

NOTES:

• During entry if the value is not unique, no error is

generated.

• There is an error when testing the sync

Login Type Select one of

these:

• None –

Customer cannot add new users:

Allows XML sync to update users,

but not to add new users. NOTE: Integrated Concur Travel & Expense

customers must use this setting, as profiles must be created in Expense and synced to Travel. Adding a profile via XML Sync for an integrated customer would mean the

profile would never be available for Expense.



Field Description

• Search ID: Creates the login ID from the SearchID

element in the XML (aka XML Profile Sync ID). The SearchID must contain the @ symbol.

• Search ID + Login Suffix: Creates the login ID from the value in the SearchID field in the XML plus the value in the Login Suffix/Validation field on the travel configuration

page

• FirstName.LastName + Login Suffix: Creates the login

from the name fields in the XML plus the value in the Login Suffix/Validation field on the travel configuration page

• FirstName.LastInitial + Login Suffix: the same as above, except uses first letter of the last name instead of the full last name

• FirstName.LastName + "@"+ ClientQuestion2 + ".com": Creates the login ID from the fields listed – first

and last name fields in the XML, then the @ symbol, then the value sent in the ClientQuestion2 element in the XML, then .com

• Email 1: Creates the login ID from the value in the first EmailAddress element in the XML

• Email1 – domain + Login Suffix: Creates the login from the value in the first EmailAddress element, but removes the @ symbol and everything following and replaces it with

the value in the Login Suffix/Validation field on the travel configuration page

User Enter a standard value; it does not have to be unique.

Login Suffix/

Validation

This field is available only if the option selected in the Login

Type list includes Login Suffix.

Password The external profile management system password to access Concur Travel. If editing this section, the Password value will not be shown. The password is not required to save changes. If

you enter a new password value, it will override the existing password.



Field Description

Password Type This is the password the

user will utilize if accessing Concur Travel

via the login screen.

Select one of these:

• (none) NOTE: If you create a new user via XML sync without specifying a password in the XML, the system will attempt

to use this setting to generate the password. In effect, you have not selected a Password Type value so the system will

return an error.

• 3-character password value + long random password

• Fixed password in Value (not recommended)

• Password is Login Id

• Short Random Password

• FirstName + Last Initial

NOTE: When the client is an integrated Concur Travel &

Expense customer and new users are not created via XML Sync, the above setting will not be utilized.

PersonCode Optional field

PersonCode and PersonDBC should contain the name of the custom fields that should map to those fields in the XML sync.

Password Prefix/Value

Optional field

PersonDBC Optional field

PersonCode and PersonDBC should contain the name of the custom fields that should map to those fields in the XML sync.

ClientQuestions Enter custom user field names in the following manner:

• ClientQuestion1-50 = User Field > Custom Field Name (exact match)

• Each ClientQuestion must be separated with a comma (no spaces)

Sync to GDS Sync Option

This option is available if profiles that are added / updated to Concur Travel via XML sync should also sync to the GDS via the

Concur Travel Profile template.

The TMC must set up a profile template for the travel

configuration, and configure the profiles to sync to the GDS.

Concur Travel can enter the sync option from the Template

Configuration tab from the profile template (most typically Concur to GDS) that determines which fields should sync to the GDS.

The default for this option is OFF/disabled (no GDS profile sync).



Field Description

Send New Users

on Changes Retrieve

This option is available for integrated customers using a Concur

Employee Import (300 or 310 and 350 records).

Users added to the system via the automated feed, who have

both the Travel Profile Last Updated and Travel Profile Last Sync date blank will be added to the sync to XML when

requested.

If this option is not enabled, Concur Travel will only send profiles that have been updated in Concur.

The default for this option is OFF/disabled.

Limit Sync to Profiles for This

Config

When a company has multiple travel configurations, one Profile Sync configuration can be used to post and request all changes

for the company. However, if a customer has different methods for profiles in different travel configurations, this option can be used to only return profiles for the selected configuration when

the TMC sends a request.

If this option is not enabled, the system will continue the

previous default behavior, and will return all modified profiles for the entire company.

The default for this option is OFF/disabled.

NOTE: Profiles posted to Concur Travel can still be sent to any travel configuration in the site – the feature above only applies

to requests for changes. For customers who work with multiple TMCs and use the Concur Divisional Admin feature (which

allows each TMC to only have access to their information), each travel configuration must have its own unique XML sync setup. This applies even if one TMC sends/requests

changes for multiple countries.

Automatically Populate Profile Last Updated Date

(recommended for customers who

have the Concur profile hidden)

This option allows the agency/customer to mark profiles as saved in Concur Travel when individual users do not have access to their Concur Travel profiles. This option can be used

in place of sending travel_profile_last_updated.

Use work/home address as the

default for credit cards

If there is no work address, then the home address will default.

ONLY VISIBLE

TO CONCUR: Update Last Synced date for a

user when you send Concur Travel & Expense profile

changes for that user through XML

Profile Sync (this has always been the default

behavior)

When enabled (checked), Concur Travel uses the default

behavior for XML sync and sets the last synched date at the current date and time when a profile update is sent to Concur Travel.

When disabled (not checked), Concur Travel sets the last updated date to the current date and time, which ensures that

the next time a request is sent to Concur Travel for XML profiles, the full profile is returned. This setting is recommended for customers who send partial updates from an

external profile tool to Concur Travel. This setting should be discussed with your Concur Travel project manager.



4. Navigate to the GDS/Profile Synchronization section of the travel configuration page.

The Select the default value for XML Sync ID option sets the XML sync ID for all users belonging to that travel configuration. The selected value defaults the XML Profile Sync ID field on the traveler profile, but can also be populated with the 350 record. Select from the following and click Apply Changes (this operation must be done separately from other travel configuration updates, as it may take a long time to complete):

Login ID

Employee ID

NOTE: If this setting is used for a customer who also uses a 350 record, it will override any value sent via the 350 record. For example, if the 350

record specifies login ID as the XML Profile Sync ID, but this setting specifies Employee ID, then Employee ID will be used as the XML Profile Sync ID.

If new profiles will be posted, the following applies:

• XML posts must occur before noon or after 5 PM on weekdays or any time on the weekend.

• By default, customers get only non-business hours access unless specifically authorized.

Section 9: FAQ

Q. When we update a profile via user import or some other method, will it update the travel_profile_last_updated field?

A. The last updated field is updated to the current date and time when a user saves their profile, when an admin updates a user through the user administration interface, or when a user is updated via any of Concur Travel’s data import processes. The field is also updated upon synchronization from Expense. Should the site have the configuration option to automatically add this information, it will also be present. Refer to the configuration section for more information.



Q. What is the value that should be passed for the TRAVEL_PROFILE_LAST_UPDATED tag?

A. TRUE or 1 for a positive response; 0 or FALSE for a negative response. If the agency/customer is creating a user and wants to set this value as updated, it can be configured via the Automatically Populate Profile Last Updated option in the profile sync configuration.

NOTE: This option is only for old client sites that are not using the automation setting in the configuration section.

Q. Does the TRAVEL_PROFILE_LAST_SYNC reference sync via XML Profile Sync, not the GDS sync?

A. Yes, this field is used for tracking XML profile sync only.

Q. What do we accept in the XML for No Middle Name field?

A. We accept true or false. If the agency/customer has included a middle name and also sends false for NoMiddleName, Concur Travel will ignore false

and make it true in the database.

Q. What does "Log Time" mean in the GDS Log file?

A. We list "Log Time" as a comment at the bottom of each XML GDS log file

exported to assist with troubleshooting.

Q. Is it possible to set profile deactivations for a future date using XML profile synch?

A. No. XML profile synch only supports same-day deactivations using the Profile Status tag.



Section 10: Appendix A – Sample XML Post VBS Script

This is a generic script that can be used to post XML to a server. It uses the Microsoft XML parser (min version 3) and Windows Script Host. It is called like this:

cscript xmlpost.vbs yourFile.xml https://app2.outtask.com/twsproxy/acceptProfiles.asp

xmlpost.vbs

' posts an xml file to a given URL

' <script language="VBScript">

If WScript.Arguments.Length <> 2 Then

WScript.stdout.WriteLine "Please provide the name of an XML data file and a url on the command line."

WScript.Quit(1)

else

call SendFile()

End If

sub SendFile()

dim xmlhttp

set xmlhttp = wscript.createobject("MSXML2.ServerXMLHTTP")

dim url, fnm, fso

fnm = wscript.arguments(0)

url = wscript.arguments(1)

set fso = wscript.createobject("Scripting.FileSystemObject")

xmlhttp.open "POST", url, false



xmlhttp.send(fso.OpenTextFile(fnm).ReadAll())

WScript.stdout.WriteLine xmlhttp.Status & ": " & xmlhttp.responseText

set xmlhttp = nothing

set fso = nothing

end sub

travel: xml based profile synchronization travel service guide - … · 2020. 6. 8. · concur...

Documents