Import specification for XML files

📄 About the specification

👉 Applies to: administrators and developers who build an automatic import to Expense. You get user credentials and a token from Expense, see the end of the article.

🧩 How the file is built

The file consists of a file header followed by the objects to import.

<?xml version="1.0" encoding="utf-8"?> <DataImport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://api.dicomkontera.se/Schemas/Dicom.Expense.Import.1.3.xsd">   <FileHeader>…</FileHeader>   <!-- import data --> </DataImport>

File header

<FileHeader fileType="DataImport" fileId="{guid}">   <Token>{secretToken}</Token>   <DeliveryId>{VAT-number}</DeliveryId>   <CompanyName>{companyName}</CompanyName>   <SchemaVersion>dicom_expense_1.3</SchemaVersion>   <DateGenerated>2015-08-14T06:01:23</DateGenerated>   <Sender senderId="EXMPLAB">Example Company AB</Sender> </FileHeader>

🔑 Basic rules

Sync keys

All objects except relations need a unique key, for example a GUID or the primary key in your system. The key is used to find the right object at the next import.

• ✅ Keep the same key at every import
• ⚠️ If the key changes, a new object is created in Expense
• ⚠️ Never reuse a key for another object
• 🚫 Do not use the email address as a key, since it can be reused by someone else later

👉 The keys in the examples below, for example P23, should be replaced with your own.

fullSync

Objects created manually in Expense are never affected. The exception is persons: Expense tries to match a person who is not synced through the email address.

Special characters

Put text that can contain the characters less than, greater than and & in a CDATA tag:

<![CDATA[Text that needs protecting]]>

📊 Objects that can be imported

Internal accounts

internalAccountPrimaryKey is the numeric key for the internal account in Expense, for example Project or Department. internalAccountDataId is your own unique key for each value.

<InternalAccountsData fullSync="false">   <InternalAccountData internalAccountDataId="IAD1" internalAccountPrimaryKey="1" state="active">     <InternalAccountDataCaption>Project 1</InternalAccountDataCaption>     <InternalAccountDataCode>PRO-0001</InternalAccountDataCode>   </InternalAccountData> </InternalAccountsData>

Person roles

personRoleId is your own unique key for each person role.

<PersonRoles fullSync="false">   <PersonRole personRoleId="PR1" state="active">     <PersonRoleName>Person role one</PersonRoleName>     <Description><![CDATA[Description for person role one]]></Description>   </PersonRole> </PersonRoles>

Persons

personId is your own unique key for each person. If there is no person with that id, Expense looks for a non-synced person with the same email address before a new one is created. EmployeeNumber, EmployeeCode and SsoTokens are optional.

SsoTokens are used for single sign-on (SAML). The idp attribute is provided by Acubiz AB, and nameId is the user's id in the SAML response. Set state="inactive" to turn off a token.

<Persons fullSync="false">   <Person personId="P23" state="active">     <FirstName>Kalle</FirstName>     <LastName>Andersson</LastName>     <EmployeeNumber>007</EmployeeNumber>     <EmployeeCode>KAAN</EmployeeCode>     <EmailAddress>kalle@examplecompany.se</EmailAddress>     <AddressLine1>Personvägen 17</AddressLine1>     <AddressLine2>Apt 1101</AddressLine2>     <PostalCode>123 45</PostalCode>     <City>Stockholm</City>     <Country>Sweden</Country>     <SSN>12345678910</SSN>     <SsoTokens>       <Saml idp="DIMuG53auwH" nameId="vO56196zbc28ac7eRRd3df1wb1" state="active" />     </SsoTokens>   </Person> </Persons>

Chart of accounts

number is the account number. vat is the VAT code and is optional. If it is left out, the VAT is chosen manually, and a VAT code that does not exist is created. The tag adds or updates accounts but never deletes any.

<ChartOfAccounts>   <Account number="5410" vat="25">     <AccountName><![CDATA[Consumable equipment]]></AccountName>     <SortOrder>…</SortOrder>     <Description />   </Account> </ChartOfAccounts>

Working hours (only with the travel time compensation module)

Sets the working hours per weekday for a person from fromDate. toDate is only used for temporary schedules. recurrenceFactor and recurrenceOffset are used to alternate hours between weeks. The tag adds or updates but never deletes.

<WorkingWeeks>   <WorkingWeek fromDate="2015-08-03" personId="P23">     <Monday fromTime="08:00:00" toTime="17:00:00" recurrenceFactor="2" recurrenceOffset="0" />     <Monday fromTime="08:00:00" toTime="12:00:00" recurrenceFactor="2" recurrenceOffset="1" />     <Tuesday fromTime="08:00:00" toTime="17:00:00" />     <!-- … -->   </WorkingWeek> </WorkingWeeks>

Salary (only with the travel time compensation module)

Sets the person's salary from fromDate. amount is the full amount including benefits and bonus. salaryType is monthly or hourly. The tag adds or updates but never deletes.

<AllowableAmounts>   <Salary fromDate="2015-06-01" amount="27500" personId="P23" salaryType="monthly" /> </AllowableAmounts>

🔗 Relations

All relations are in the Relations tag:

<Relations fullSync="true">   <!-- relations --> </Relations>

<InternalAccountData_PersonRole internalAccountDataId="IAD123" personRoleId="PR3" state="active" /> <ChartOfAccount_PersonRole chartOfAccountNumber="4020" personRoleId="PR3" state="active" /> <Person_PersonRole personId="P23" personRoleId="PR2" state="active" /> <ChartOfAccount_Person chartOfAccountNumber="4020" personId="P23" state="active" /> <InternalAccountData_Person internalAccountDataId="IAD123" personId="P23" state="inactive" /> <Person_AttestPerson personId="P23" attestPersonId="P1" state="active" /> <Person_Reviewer personId="P23" reviewerPersonId="P1" state="active" /> <Person_InternalAccountDataDefault internalAccountDataId="IAD123" personId="P23" locked="false" />

📤 Upload the file

1. Send the file with a regular POST to https://api.dicomkontera.se/File/Import.
2. Authenticate with HTTP Basic Authentication.
3. Name the file companyname.xml. A file called test.txt is ignored and can be used to test the connection.

Example with cURL:

curl -u username:password --form upload=@test.txt https://api.dicomkontera.se/File/Import

⚠️ Do not use the -k flag, which makes cURL ignore certificate errors.

🔐 User credentials and settings

To get a username, password and token, or to set up the import, contact Expense Support.

📋 Version history

❓ Frequently asked questions (FAQ)

What happens if we change a key?
Expense sees it as a new object and creates a new entry. So keep the same key at every import.

Are accounts deleted if they are missing in the file?
No. Chart of accounts, working hours and salary are only added or updated. For objects with fullSync="true", previously imported objects that are missing in the file are deactivated.

Is anything we created manually in Expense affected?
No, only objects that have been imported before. The exception is persons, who can be matched through the email address.

How do we test the connection?
Upload a file called test.txt. It is ignored by the import.

✅ Summary

• 📄 The XML file is encoded in UTF-8 and follows schema version 1.3
• 🔑 Each object needs a unique key that never changes
• 🔄 fullSync controls whether missing objects are deactivated
• 📤 The file is uploaded with POST and Basic Authentication

🔗 Related articles

• • Integrations and export formats in Expense
  • Fetch internal accounts from your API (JSON)
  • Custom import: automatic import of staff and account data
  • Person roles – restrict access to accounts