Creating a Task to Import Events from an XML File

This topic explains how to create an integration task to import events from XML files. This allows events listed in the XML files to be automatically registered in the Workflow module. If you are using a SaaS environment, please get in touch with the Support team to configure the process to import files.

The XML files may have specific structures for their headers, sections, content ID tags, and other elements. Different terminology may also be used to refer to the same properties. For example, the name of the event in the XML file may be found in the "Event Name" field, whereas in the system the field is called "Title". For the information to be imported correctly, the terms that appear in these files must be mapped to the corresponding fields in the system.

It may also be that a certain property of an event is not included in the XML file, which may be problematic when the task is executed. If the field is optional in the system, there will be no error if it is left blank or is non-existent in the XML file. However, if a required field is not included in the XML file, an error will occur when the integration task is executed. To avoid this problem, a default value must be defined for each required field that is left blank or omitted in the XML files. Note that the XML file will ignore the configurations of custom attributes set as required in the Objects and Attributes section of this module, meaning that these required fields might be left blank.

Another feature that can be used in this mapping is the conversion of numbers, as it may be that in the file different scales are used than those used in the system. For example, in the file the event urgency is scored on a scale from 1 to 10, whereas the system uses a scale from 1 to 5. In this case, rules must be created to convert these values. Values 1 and 2 can be converted to 1, values 3 and 4 can be converted to 2, and so on.

Listed below are all the fields that must be mapped to register an event from an XML file.

Variable	Description	Required?	Limit/Format
source	Identifies where the events were imported from.	Yes	100 characters
id	Unique identifier for the event.	No	N characters
title	Event title.	Yes	2,500 characters
type	Event type.	Yes	All default and custom event types, except for Risk and Compliance events.
description	Event description.	Yes	5,500 characters
urgency	Event urgency.	Yes	1 - 5
severity	Event severity.	Yes	1 - 5
relevance	Event relevance.	Yes	1 - 5
coordinator	Event coordinator.	Yes	Name of a person registered in the system.
responsible	Person responsible for the event, by default defined in the mapping.	Yes	Name of a person registered in the system.
involved	People or groups involved in the event.	No	Name of a person or group registered in the system.
reviewer 1	First reviewer for the event.	No	Name of a person or group registered in the system.
reviewer 2	Second reviewer for the event.	No	Name of a person or group registered in the system.
reviewer 3	Third reviewer for the event.	No	Name of a person or group registered in the system.
value	Value associated with the event.	No	Integer or decimal number. For example: 123.56.
deadline	Deadline for the event.	No	Date in the mm/dd/yyyy format.
createdOn	Date the event was created.	No	Date in the mm/dd/yyyy format.
expectedStartDate	Expected start date for the event.	No	Date in the mm/dd/yyyy hh:mm tt format.
expectedEndDate	Expected end date for the event.	No	Date in the mm/dd/yyyy hh:mm tt format.
startDate	Start date for the event.	No	Date in the mm/dd/yyyy hh:mm tt format.
endDate	End date for the event.	No	Date in the mm/dd/yyyy hh:mm tt format.
location/latitude	Latitude of where the event is located.	No	-90 to +90
location/longitude	Longitude of where the event is located.	No	-180 to +180
location/description	Description of where the event is located.	No	1,000 characters

When defining a person for one of the roles that accepts people, the combination of their names and e-mail addresses can be used to ensure a person is uniquely identified.

Example 1:

XML file:

<responsible email="joe.smith@domain.com">Joe Smith</responsible>

Mapping:

<responsible field="responsible" email="responsible/@email"/>

Example 2:

XML file:

<responsible >Joe Smith</responsible>

<email>joe.smith@domain.com</email>

Mapping:

<responsible field="responsible" email="email"/>

To write these mappings, you must inform the node in which the details of each event is located. This configuration is made through the basePath by writing the absolute Xpath for the respective path in the XML file. From this point on, the fields must be mapped through the Xpath related to this basePath. The basePath can be grouped by event type, allowing distinct behavior for different event types in a single integration task. If there are more complex conditions not met by separating event types, separate integration tasks can be created to categorize this information.

The following features are also available:

• Define date and time format. For example:

The list of accepted formats can be accessed at http://msdn.microsoft.com/en-us/library/8kb3ddd4.aspx.

• Conversion/mapping of values to match the values accepted by the system. For example:

</mappings>

</relevance>

• Converting content into a hash md5. In the example, this resource is used for the ID field, as not all programs provide unique identifiers for each event.

• Defining default values for fields not included in the report.

• Limit the size of a certain field to respect the system limits. If the limit is left undefined, an error will occur every time a file with content exceeding the allowed limit is imported. If the "truncate" parameter is not used, it will be considered "false".

• Define mappings for custom and default types of events.

</mappings>

</type>

• Define mappings for custom attributes, where the following custom attribute types are supported: Date/Time (Date, Date/Time, and Time), E-mail, Link, List of Options (Single Selection and Multiple Selection), Number, Paragraph, and Text.

Note that the values from the file must be compatible with the values accepted by the attribute. Otherwise, no events will be imported and an error message will be displayed in the history of the integration task. Thus, maximum and minimum values, the number of decimal places, and any regular expression masks created for attributes must be respected. The variable name of the attribute should be used when creating the mappings.

</customAttributes>

• Define mappings of properties through the Xpath.

XML file:

<tag name="username">John Smith</tag>

</TicketProperties>

Mapping:

It is important to note that the information from the XML files will only be imported if the path to the repository containing the files to be processed is provided. If a file that has already been processed by the system is in the same directory as new files, it will only be imported once.

If the directory specified contains a number of unprocessed XML files, they will all be imported. For this reason, it is helpful to specify the order in which they will be imported to ensure the latest information is imported last. When configuring the integration task, you can set the order in which the files will be imported to be by date or by name.

Keep in mind that the default values set for event attributes in the Objects and Attributes section of the Administration module are not respected in integration tasks to import events through an XML file.