dms.XMLImport

This job enables inserting or updating an object depending on the result of a previous search.

1. Input Parameters

Name Type Required Description

Flags

INT

Yes

general options for the job (see Flags)

Options

STRING

Yes

semicolon-separated job options (e.g. ARCHIVABLE=1;CHECKACCESS=0) (see Parameter Options)

XML

BASE64

Yes

contains object description in XML format (see DMSData XML Format and the parameter XML) with the extension of the <SearchFields> tag for search fields.

JobUserGUID

STRING

Yes

determines the user context (see the parameter JobUserGUID)

[Action0]

STRING

No

Action to perform when no hits (see action table below)

[Action1]

STRING

No

Action to perform when one hit (see action table below)

[ActionM]

STRING

No

Action to perform when multiple hits (see action table below)

2. Input Files

Name Description

[FileList]

Path and name of the documents to be inserted

3. Output Parameters

Name Type Dependency Description

ObjectID

INT

—

new object ID, if job successful, otherwise -1

ObjectType

INT

—

type of the object, otherwise -1

Hits

INT

—

number of hits from the search

Action

STRING

—

performed action. Possible values: UPDATE, INSERT, NONE, ERROR

4. Output Files

Name Description

[FileList]

Path and name of the XML file with errors (see Flags)

5. Return Value

(INT): 0 = Job successful, otherwise error code
Complete list of error codes

6. Action Table

Search Result (Hit Count) Parameter Name Possible Parameter Value Explanation

0

Action0

INSERT (Default)
NONE
ERROR

Insert (see dms.XMLInsert)
Do nothing
Generate error message

1

Action1

NONE
UPDATE (Default)
INSERT

Do nothing
Update object (see dms.XMLUpdate)
Insert at location of found object (see dms.XMLInsert)

>1

ActionM

NONE
UPDATE
INSERT
ERROR (Default)

Do nothing
Update only first object (see dms.XMLUpdate)
Insert at location of first found object (see dms.XMLInsert)
Generate error message
If the object location is specified or restricted, this location is used both for the search and for insertion. The search can also be used to determine the location. If no location is specified and no object is found, inserting a cabinet or document is not possible. In this case, an error message is generated. If no search fields are specified, the object is inserted.
dms.XMLImport internally branches into the INSERT or UPDATE path and triggers there the same database side effects and follow-up jobs as the underlying job (see Follow-Up Processing and Events).
Example: Change phone number of contact person
<?xml version="1.0" encoding="UTF-8"?>
<DMSData>
  <Archive internal_name="addresses">
    <ObjectType internal_name="addresses">
      <Object>
        <Search>
          <Fields>
            <Field internal_name="contact_person">Schaumer</Field>
            <Field internal_name="first_name">Harald</Field>
          </Fields>
        </Search>
        <Fields>
          <Field internal_name="phone">0815-12345</Field>
        </Fields>
      </Object>
    </ObjectType>
  </Archive>
</DMSData>

7. Follow-Up Processing and Events

A successful call triggers the server-internal follow-up job std.IndexDataChanged and thereby produces a history entry in osobjhist. The Action depends on the branch taken:

  • Insert branch: Action = 2 (object created)

  • Update branch: Action = 3 (index data changed), provided the XML contains at least one <Field>

The server does not compare the submitted values against the stored ones — a value submitted unchanged counts as a write operation and triggers the follow-up job. For the complete overview see Triggering by the DMS XML Jobs.

A server event that is to react to the change is bound to that follow-up job, not to dms.XMLImport (see Intercepting Index Data Changes).