Syntax of fields in the UpdateConnector

The fields you deliver in the XML must meet various conditions. Several information sources are available for completing the UpdateConnector. The main information source is the XSD schema. The XSD schema determines:

• The format of the XML that you need to deliver.
• The field properties of each field, such as field type, maximum length, mandatory or optional, etc.

In Profit, extra validations typically apply. These are checks that were not included in the XSD schema. These are the validations that are also run if you add data manually. These checks are not in the XSD schema, but if an UpdateConnector adds, changes or deletes data, then these checks are in fact performed.

Example:

Field: date of birth.

In the XSD schema, you only see that you must provide a date.

In Profit, however, an extra check applies: a date of birth must always be in the past. We recommend that you first test operations in Profit. This gives you a clear picture of the functionality and the checks.

Syntax of fields

The section below describes various field types. Any value you provide must be valid for the field type. A date, for example, always has a fixed format. Codes can have a maximum length.

Mandatory and optional fields

All mandatory fields are indicated with an exclamation point.

These fields are mandatory when you run an INSERT (add a new record). Many UpdateConnectors can also be used to change data, in which case only key fields (codes or numbers) are mandatory.

References to other tables (foreign keys)

In Profit, you must select a value from a table for certain fields. You cannot enter values that are not in the table. This also applies in the UpdateConnector: if you provide an illegal value when you run an UpdateConnector, an error message appears.

The reference to the table is after the field. Look in Profit to see the allowed values, for example by adding a new record to a test environment manually. Naturally, it is important to create a new test environment regularly so you can test with current data.

Reference: Verwijzing naar: Profit field <table> => table name

In this example the 'EmId (Medewerker)' field refers to the 'AfasKnEmployee' table. The code that you provide in this field must occur in Profit. The code has a maximum length of 15 characters.

Note:

In certain tables, the records have both an internal and an external code. The external code is the code that you use in Profit and is also the code that you must deliver using the UpdateConnector. The internal code is used in the database and is generally not relevant for the use of Profit or the UpdateConnector. In cases of exceptions, this is noted.

Allowed field values

For some fields, the allowed values are indicated. Other values are not allowed.

Reference: Toegestane veldwaarden

The example below comes from a different UpdateConnector, not from 'HrAbsence'.

Field type 'Boolean' (Yes/No field)

Allowed values:

• 1 (Yes/selected/true)
• 0 (No/not selected/false)

  

Field type 'String' (Text)

These fields are for names, descriptions, etc. A maximum field length may apply.

Field type 'Date' (Date)

Required syntax: yyyy-mm-dd.

Example:

Date: 3 April 2017

Syntax in the XML: 2017-04-03

Field type 'DateTime' (Date and time)

Fields for a date and time, such as the start and end dates of a leave entry.

Required syntax: yyyy-mm-ddThh:mm:ss

Example:

Date: 22-10-2017; time 13:40

Syntax in the XML: 2017-10-22T13:40:00

Field type: Time

Required syntax: hh:mm:ss

Example:

Time: half past nine (AM).

Syntax in the XML: 09:30:00

Amounts, quantities, numbers, etc.

Be mindful of the maximum length and check whether decimals are allowed. Special conditions may apply to counters, auto numbering, etc. Certain codes may consist of, for instance, a combination of letters and numbers.

Clear a field

Ensure that the fields in the XML are delivered in the same order as indicated in the definitions.

Set fields to zero or clear them

You can never clear a field or set a field to zero by supplying an empty field in the XML. That is because if a field is empty, the UpdateConnector will not update the field at all.

• Numerical fields

  You can set a numerical field to zero by delivering the value 0 in the XML.

  Example:

  <PrFc>0</PrFc>

You can only do this for fields which are allowed to have the value zero. They are numerical fields which are not mandatory, but if you complete them, then the value delivered must fall within a particular range. For these fields, you can clear the fields (using the method below for strings) or deliver an allowed value.

• Strings

  Use the following method to clear a string field (such as a description). You can only clear optional fields.

  xsi:nil="true"

  Example:

  <PrVn xsi:nil="true"/>

  <PrVn xsi:nil="true"></PrVn>

• Yes/No fields

  These fields (in the interface, these are check boxes) always have a value. You cannot clear them. If you do not deliver this value, Profit assigns the preferred value. The preferred value can vary according to the field.

Reserved characters

Take reserved characters into account in the XML. The main ones are given below.

Note:

This topic is only intended for XML. For JSON, view this topic.

You can use the following codes to format the contents of a string:

Upper-case letters with accents (diacritical marks):

Lower-case letters with accents (diacritical marks):

Return code when using INSERT

When creating a new data element using the below UpdateConnectors, the response includes the code of the new data.

Example of a response with one code:

<?xml version="1.0"?>

<results><FbDirectInvoice><OrNu>70000183</OrNu></FbDirectInvoice></results>

Example of a response with multiple codes:

<?xml version="1.0"?>

<results><FbDeliveryNote><OrNu>70000156</OrNu></FbDeliveryNote></results>

<?xml version="1.0"?>

<results><FbDeliveryNote><OrNu>70000182</OrNu></FbDeliveryNote></results>