3.5.3 Creating an Item by sending an email

This subsection describes how to register an Item in JP1/Service Support by sending an email. The following figure shows an overview of this process.

Figure 3‒24: Overview of registering an Item by sending an email

The following describes the steps in the figure:

A user sends an email.

An enterprise system user sends an email that explains a desired Item to a specific address.

Only users who have previously been set in the Email definition file can send such an email. The Email definition file also contains information such as the destination address and the email server. For details about this file, see Email definition file (jp1imss_mail_setting.conf) in Chapter 13. Definition Files.
The system executes the email-driven Item registration command.

The Item management server executes the email-driven Item registration command. The JP1/Service Support - Task Service can execute this command at regular intervals. For details about the email-driven Item registration command, see jssitementrybymail (registers emails as Items) in Chapter 12. Commands.
The command registers the accumulated Items.

The emails that have been accumulated on the email server are registered on the Item management server by an email-driven Item registration command.

The emails accumulated on the email server are deleted after they are registered on the Item management server. If email-driven registration of an Item fails, the header and text of the relevant email are output to the following folder as a temporary email save file:

JP1/SS-path\log\command\jssitementrybymail_mail_tmp_file
The responder handles the registered Items.

The incident specialist views the content of the Item registered by the jssitementrybymail command, and processes the Item. The content registered by the jssitementrybymail command depends on the operation mode. For details, see (2) Email elements used for registration of an Item.

The incident specialist reads the text of the emails that have been saved as attached files for the registered Items, and then handles the Items. The incident specialist designated for an Item depends on the process work board of that Item. The user set as Person in charge of the registered item from email for the process work board is automatically assigned as the incident specialist. This setting can be specified in the New process work board window or the Edit the process work board window. For details, see 9.15.1 Setting an environment for registering Items by email.

Organization of this subsection

(1) Overview of the temporary receipt process work board and master system
(2) Email elements used for registration of an Item
(3) Contents of an Item registered via an email
(4) Conditions in which an email is deleted from the email server
(5) Notes on email-driven Item registration

(1) Overview of the temporary receipt process work board and master system

The temporary receipt process work board is the default process work board in which Items created via email will be registered. If the ID of a specific process work board is specified in the subject of an email, the corresponding Item will be registered in the specified process work board. Items are registered in the temporary receipt process work board for all emails without a process work board ID specified in the subject. The temporary receipt process work board is displayed in the List of process work boards in the main window (Item list).

The master system is the target system in which the temporary receipt process work board is registered.

The temporary receipt process work board and master system can be created by using either the setup command or by using the command for creating a master system and temporary reception process work board, which is provided specifically for that purpose.

For details about the setup command, see jsssetup.bat (sets up JP1/Service Support) in Chapter 12. Commands.

For details about the command for creating a master system and temporary reception process work board, see jsscreatesysandpwb (creates the master system and the temporary receipt process work board) in Chapter 12. Commands.

The following tables lists and describes the settings that can be specified during creation of the temporary receipt process work board and master system.

Table 3‒25: Settings that can be specified during creation of the temporary receipt process work board
Setting		Description
Basic settings tab	Process work board ID	If the setup command is used, the following string is set: `jp1TemporaryReceiptProcessWorkBoard` If the command for creating a master system and temporary reception process work board is used, the string specified as the command's argument is set.
	System^#	A master system is set.
	Process^#	Incident management is set. If the process display name has been customized, the process display name set for Incident management is set for Process.
	Item form	The process standard item form is used check box is selected.
	State	Operating is set.
	Process work board administrator	JP1 administrator is set.
	Settings for pre-deadline email notification	The Notify by email before the deadline check box is not selected.
	JP1 event configuration	The Issue JP1 event check box is not selected.
	Person in charge of the registered item from email	JP1 administrator is set.
	View permissions for individual Items	The Set reference permissions for individual Items check box is not selected.
	Settings for the recall item function	Enable the recall item function check box is selected.
	Comment	The following string is set: `Temporary` `receipt` `of` `process` `work board` `for` `the` `item` `function` `using` `email`
Settings - Automatic item input tab		The Property file for automatic Item-defaults input setting is being used check box is selected.
Threshold setting tab		The Item accumulation property file is being used check box is selected.

#: The settings other than System and Process can be edited by using the Edit the process work board window.

Table 3‒26: Settings that can be specified during creation of the master system
Setting	Description
System ID	If the setup command is used, the following string is set: `jp1TemporaryReceiptSystem` If the command for creating a master system and temporary reception process work board is used, the string specified as the command's argument is set.
System name	Master system is set.
Comment	The following string is set: `Master` `system` `for` `the` `item` `function` `using` `email`

You can edit or delete the temporary receipt process work board in the same way as for other process work boards. Similarly, you can edit or delete the master system in the same way as for other target systems.

To Page Top

(2) Email elements used for registration of an Item

The following table describes the email content that is registered as an Item.

Table 3‒27: Email elements used for registration of an Item
Email element	Description
Subject	The subject of an email sent by the user becomes the title of the Item to be created^#. The registration-destination process work board can also be specified in the subject. To specify the destination process work board, add `#process-work-board-ID#` at the beginning of the title. If a registration-destination process work board is specified, the title of the Item is the subject of the email from which the process work board ID is eliminated. If the sent email does not have any subject, `No` `Subject` is set as the title of the Item^#.
Text	The Item registration status depends on the operation mode for Item registration. You must set the operation mode for Item registration beforehand in the email definition file. For details, see Email definition file (jp1imss_mail_setting.conf) in Chapter 13. Definition Files. The following describes the operation modes for Item registration and Item registration status: Attached-file mode The text of an email is saved in a text file that is attached to the created Item. Therefore, attachment must be permitted in the Item forms that are used for the temporary receipt process work board and other process work boards in which Items might be registered. Single-element mode The text of an email is registered by setting it into one element of an Item. You must define the element to set the text of an email beforehand in the email definition file. For details, see Email definition file (jp1imss_mail_setting.conf) in Chapter 13. Definition Files. By default, the text is set as `Overview` of the Item. If the text of the email cannot be registered as an element of the Item, the text of the email is saved in a text file that is attached to the Item. Therefore, attachment must be permitted in the Item forms that are used for the temporary receipt process work board. Multi-element mode The text of an email is written in the XML format, and the text is registered by setting the information enclosed by the start and end tags into the corresponding elements of the Item. The text of the email is saved in a text file that is attached to the Item. Therefore, attachment must be permitted in the Item forms that are used for the temporary receipt process work board.
Attached files	For security reasons, files must not be attached to any emails that are sent for registering Items. Files attached to such emails are not added to the Item management database. These files are saved in the attachment management folder on the Item management server.
Source address	The source address of an email is set as the specified ID of the Item element in which the source address of an email defined in the email definition file is to be set. For details about the email definition file, see Email definition file (jp1imss_mail_setting.conf) in Chapter 13. Definition Files.

#: When the operation mode is the multi-element mode and the text of the email contains title information, the title information of the text of the email can be set.

To Page Top

(3) Contents of an Item registered via an email

When an Item is registered via an email, some contents of the Item are registered as common contents regardless of the operation mode for Item registration, whereas other contents are registered differently depending on the operation mode.

(a) Common registration contents

Table 3‒28: Common contents of the Item registered via an email
Item settings	Description
Title	The subject of the email is used as the title of the Item. Note that if the ID of the registration-destination process work board was specified in the subject, the ID specification (`#process-work-board-ID#`) is removed.
Item ID	The lowest available Item ID is automatically assigned when the Item is registered.
Update date and time	The date and time that the Item was registered on the Item management server is automatically set.
System	A master system is set. If the registration-destination process work board was specified in the subject of the email, the target system of that process work board is set.
Process	Incident management is set. If the registration-destination process work board was specified in the subject of the email, the process of that process work board is set. If the process display name has been customized, the process display name set in Incident management is set.
Person in charge	The Person in charge of the registered item from email setting of the registration-destination process work board is specified. Note that the person set as Person in charge of the registered item from email is permitted to: View any Items registered on the destination process work board Edit any Items registered on the destination process work board when their status is Received (status ID: JIMSD_STAT_INQUIRY)
Status	Received (status ID: JIMSD_STAT_INQUIRY) is set.
Inter-process ID	The lowest available inter-process ID is automatically assigned when the Item is registered.
Registration date and time	The date and time that the Item was registered on the Item management server is automatically set.
Registrant	The Person in charge of the registered item from email set in the registration-destination process work board is set.
Any one of extended user information 01 to 05^#	If the option to set view permissions for individual Items is enabled for the target process work board, the user specified in the Person in charge of the registered item from email parameter for the target process work board is automatically set.

#: When view permissions are set for individual Items, this element is the extended user information you selected as the basis for assigning those view permissions. Values are not assigned to extended user information 01 to 05 if view permissions are not set for individual Items. For details on element selection when setting view permissions for individual Items, see 9.13 Setting an environment in which view permissions are set for individual Items.

In addition to the above settings, settings whose values are automatically input might be specified. Automatic input settings can be specified in the Settings - Automatic item input tab of the New process work board window or the Edit the process work board window.

(b) Registration contents varied by the operation mode

The operation mode for Item registration must be defined by hptl_jp1_imss_mail_operation_mode in the email definition file. For details, see Email definition file (jp1imss_mail_setting.conf) in Chapter 13. Definition Files.

Attached-file mode

When the operation mode for Item registration is the attached-file mode, the whole text of the email is registered in an attached file.

Single-element mode

When the operation mode for Item registration is the single-element mode, the whole text of the email is registered in the Item element specification IDs specified in the email definition file. For the Item element specification IDs that can be specified, see Table 3-29 Item form element IDs corresponding to Item element specification IDs. If the text of the email cannot be registered in the Item element specification IDs defined in the mail definition file, the text of the email is saved in a text file attached to the Item. In such a case, the value specified for hptl_jp1_imss_mail_format_error_string in the email definition file is added to the title of the Item. For details about the email definition file, see Email definition file (jp1imss_mail_setting.conf) in Chapter 13. Definition Files.

Multi-element mode

When the operation mode for Item registration is the multi-element mode, the text of the email must be written in the XML format. Write the elements to be registered in the Item in the following format:

<Item-element-specification-ID>info.-to-set-in-the-Item-element</Item-element-specification-ID>

You can use all characters, including space, linefeed, and tab, when writing text in the XML format. You must, however, write the following escape sequences to register characters such as & (ampersand), < (smaller than), > (larger than), ' (single quotation mark), or " (double quotation mark) as the information to set in the Item element:

Escape sequence for &: &
Escape sequence for <: <
Escape sequence for >: >
Escape sequence for ': '
Escape sequence for ": "

If the text of an email includes multiple identical Item element specification IDs, The information set in the first Item element specification ID is registered. If, however, the first Item element specification ID is invalid in terms of notation, the information set in the second Item element specification ID is registered.

If the same Item element specification ID is specified in both of the email definition file and the text of an email, information is registered in the following order of priority:

Value of the Item element specification ID specified in the email definition file
Information to set in the Item element indicated by the Item element specification ID specified in the text of the email
Subject of the sent email^#

#: If the Item element specification ID TITLE is specified neither in the email definition file nor in the text of the email, the subject of the sent email is registered as the title of the Item.

Note that, if one of the following errors occurs in an element, information is not set in the element. Then, to indicate the occurrence of the error, one of the values described below is set in the title of the Item.

A syntax error, for example, omission of the start tag

In this case, the Item is registered with "KNAB22124-W Some information was lost when the item was registered." set in the title.
An error other than syntax errors

The value specified for hptl_jp1_imss_mail_format_error_string in the email definition file is added to the title of the Item. For details about the email definition file, see Email definition file (jp1imss_mail_setting.conf) in Chapter 13. Definition Files.

The text of the email and error messages are saved in text files attached to the Item. Reference the attached files, and set necessary information in Item elements.

The following table lists the Item form IDs corresponding to the Item element specification IDs that can be set in the sent email.

Table 3‒29: Item form element IDs corresponding to Item element specification IDs
No.	Element name (default display name)	Item form element ID	Item element specification ID	Whether information can be set
No.	Element name (default display name)	Item form element ID	Item element specification ID	Single-element mode	Multi-element mode
1	Title	JIMSD_FORM_TITLE	TITLE	N	Y
2	Severity	JIMSD_FORM_SEVERITYCODE	SEVERITYCODE	N	Y
3	Reason for severity	JIMSD_FORM_SEVERITYREASON	SEVERITYREASON	N	Y
4	Impact level	JIMSD_FORM_IMPACTCODE	IMPACTCODE	N	Y
5	Reason for impact level	JIMSD_FORM_IMPACTREASON	IMPACTREASON	N	Y
6	Priority^#1	JIMSD_FORM_PRIORITYCODE	PRIORITYCODE	N	Y
7	Reason for priority	JIMSD_FORM_PRIORITYREASON	PRIORITYREASON	N	Y
8	Item type	JIMSD_FORM_ITEMCATEGORYCODE	ITEMCATEGORYCODE	N	Y
9	Problem domain	JIMSD_FORM_ISSUECATEGORYCODE	ISSUECATEGORYCODE	N	Y
10	Scale of change	JIMSD_FORM_CHANGESCALECODE	CHANGESCALECODE	N	Y
11	Release type	JIMSD_FORM_RELEASETYPECODE	RELEASETYPECODE	N	Y
12	Result	JIMSD_FORM_RESULTCODE	RESULTCODE	N	Y
13	Occurrence date and time^#1	JIMSD_FORM_ACCRUALDATE	ACCRUALDATE	N	Y
14	Occurred type	JIMSD_FORM_PHENOMENONCODE	PHENOMENONCODE	N	Y
15	Solution category code	JIMSD_FORM_SOLUTIONCODE	SOLUTIONCODE	N	Y
16	Deadline^#1	JIMSD_FORM_DEADLINE	DEADLINE	N	Y
17	Start date and time^#1	JIMSD_FORM_STARTDATE	STARTDATE	N	Y
18	End date and time	JIMSD_FORM_COMPDATE	COMPDATE	N	Y
19	Customer name	JIMSD_FORM_CUSTOMERNAME	CUSTOMERNAME	N	Y
20	Inquirer's name	JIMSD_FORM_INQUIRYNAME	INQUIRYNAME	N	Y
21	Cost (planned)	JIMSD_FORM_ESTIMATEDCOST	ESTIMATEDCOST	N	Y
22	Cost (actual)	JIMSD_FORM_ACTUALCOST	ACTUALCOST	N	Y
23	Impact service	JIMSD_FORM_EFFECTSERVICE	EFFECTSERVICE	Y	Y
24	Problem component and version	JIMSD_FORM_FAILURELOCATION	FAILURELOCATION	Y	Y
25	Overview	JIMSD_FORM_SUMMARY	SUMMARY	Y	Y
26	Workaround type	JIMSD_FORM_AVOIDANCECODE	AVOIDANCECODE	N	Y
27	Workaround	JIMSD_FORM_AVOIDANCE	AVOIDANCE	Y	Y
28	Work status	JIMSD_FORM_SITUATION	SITUATION	Y	Y
29	How to avoid the problem in the future	JIMSD_FORM_MEASURES	MEASURES	Y	Y
30	Cause	JIMSD_FORM_CAUSECODE	CAUSECODE	N	Y
31	Fundamental cause	JIMSD_FORM_ROOTCAUSE	ROOTCAUSE	Y	Y
32	Solution	JIMSD_FORM_SOLUTION	SOLUTION	Y	Y
33	Schedule and main steps	JIMSD_FORM_SCHEDULE	SCHEDULE	Y	Y
34	Impact assessment for change	JIMSD_FORM_IMPACTEVAL	IMPACTEVAL	Y	Y
35	Discussions result	JIMSD_FORM_DELIBERATIONRST	DELIBERATIONRST	Y	Y
36	Free memo column	JIMSD_FORM_FREEDESCRIPTION	FREEDESCRIPTION	Y	Y
37	Product name	JIMSD_FORM_JP1PRODUCTNAME	JP1PRODUCTNAME	N	Y
38	Jobnet name	JIMSD_FORM_JP1JOBNETNAME	JP1JOBNETNAME	N	Y
39	Job name	JIMSD_FORM_JP1JOBNAME	JP1JOBNAME	N	Y
40	SNMP source	JIMSD_FORM_JP1SNMPSRC	JP1SNMPSRC	N	Y
41	Monitored node name	JIMSD_FORM_JP1NODENAME	JP1NODENAME	N	Y
42	Alarm name	JIMSD_FORM_JP1ALARMNAME	JP1ALARMNAME	N	Y
43	Serial number^#2	JIMSD_FORM_IMEVENTNO	IMEVENTNO	N	Y
44	JP1/IM - Manager host name^#2	JIMSD_FORM_IMHOSTNAME	IMHOSTNAME	N	Y
45	Added item: text	JIMSD_FORM_USERTEXT01 to JIMSD_FORM_USERTEXT05	USERTEXT01 to USERTEXT05	Δ	Y
46		JIMSD_FORM_USERTEXT06 to JIMSD_FORM_USERTEXT15	USERTEXT06 to USERTEXT15	Δ	Y
47		JIMSD_FORM_USERTEXT16 to JIMSD_FORM_USERTEXT20	USERTEXT16 to USERTEXT20	Δ	Y
48	Added item: numerical data	JIMSD_FORM_USERINT01 to JIMSD_FORM_USERINT0105	USERINT01 to USERINT05	N	Y
49	Added item: code	JIMSD_FORM_USERCODE01 to JIMSD_FORM_USERCODE0105	USERCODE01 to USERCODE05	N	Y
50	Added item: date and time	JIMSD_FORM_USERTIME01 to JIMSD_FORM_USERTIME05	USERTIME01 to USERTIME05	N	Y

Legend:

Y: Information can be set.

N: Information cannot be set.

Δ: Information can be set when the data type is textarea.

#1

Even if automatic setting functions are enabled, the value set in the sent email has priority.

#2

Even if the element is not used in the Item form, the value set in the sent email is registered.

For details about individual elements, see the content of the Item information CSV described in jssitemexportEx (exports extended Item information) in Chapter 12. Commands. For the characters and the number of bytes available for individual elements, see the description of the Item information CSV file in File for extended Item information entries (Optional) in Chapter 13. Definition Files. Note, however, that the characters that can be set might be different depending on the type of element. For details about the types of elements, see Definition status in the Item form definition file in Item form definition file (Optional) in Chapter 13. Definition Files. The following table describes the differences of characters that can be set.

Table 3‒30: Differences of characters that can be set
No.	Category	Type	Differences of characters that can be set
1	Character string	`text`	Using a control character does not cause an error. A control character is substituted by a 1-byte space.
2	Character string	`textarea`	Using a control character does not cause an error. When the control character is a linefeed code, nothing occurs. When the control character is other than a linefeed code, the control character is substituted by a 1-byte space.
3	Date and time	`datetime`	Date and time can be set as a character string in the `yyyy/mm/dd/hh:mm` format. Using a control character does not cause an error. The control character is ignored. The range of specifiable values is `1970/01/02` `00:00` to `2107/01/01` `23:59`.
4	Code	`code`	Using a control character does not cause an error. The control character is ignored.
5	Integer	`number`

The elements that are set are checked for format. If a format error is found in an element, the element is registered as an Item element, but the information in the sent email is not set in the element.

To Page Top

(4) Conditions in which an email is deleted from the email server

After an email that requests Item registration is sent to the email server, when an Item is registered on the Item management server, the email is deleted from the email server. Note, however, that the system might sometimes fail, for some reason, to output a temporary email save file or to save attached files in the attachment management folder. In such cases, the relevant email is not deleted from the email server. The following table shows the conditions under which an email is deleted or is not deleted.

Table 3‒31: Conditions under which an email is deleted or is not deleted
Result of email-driven Item registration	Status of files attached to the email
Result of email-driven Item registration	No files are attached	Attached files are saved in the attachment management folder	Attached files are not saved in the attachment management folder
Registration succeeded.	Y	Y	N
Registration failed, but a temporary email save file was output.	Y	Y	N
Registration failed, and a temporary email save file was not output.	N	N	N

Legend:

Y: The email is deleted.

N: The email is not deleted.

If an email fails to be deleted although conditions for its deletion exist, manually delete the email.

Emails sent from users that are not registered in the email definition file are deleted from the email server.

To Page Top

(5) Notes on email-driven Item registration

To prevent text corruption in an Item being registered, do not use any platform-dependent characters or any of the following characters in the subject and text of the email: ~, \, , , ?, , , ,
Do not request creation of an Item using encrypted email. If you do so, text in the Item might be corrupted or registration of the Item might fail.
If the registration-destination process work board specified in the email subject does not exist, the Item will be registered on the temporary receipt process work board.
If the registration-destination process work board specified in the email subject is not in the Operating state, the Item will be registered on the temporary receipt process work board.
If the Item form of the registration-destination process work board prohibits file attachment, the Item will be registered on the temporary receipt process work board. However, if the Item form of the temporary receipt process work board also prohibits file attachment, the Item will not be registered.

Before you register Items, make sure that the Item form of the destination process work board permits file attachment. For details about Item form customization, see 9.9 Customizing Item forms.
When the operation mode for Item registration is the multi-element mode, we recommend that you prepare a template for email beforehand and register Items by entering necessary information in the template. For details, see 5.6.1 Considering the method of registering Items by email.

To Page Top