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.
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
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.
Setting |
Description |
|
---|---|---|
Basic settings tab |
Process work board ID |
|
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. |
Setting |
Description |
---|---|
System ID |
|
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.
(2) Email elements used for registration of an Item
The following table describes the email content that is registered as 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 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. |
(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
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:
|
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. |
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.
No. |
Element name (default display name) |
Item form element ID |
Item element specification ID |
Whether information can be set |
|
---|---|---|---|---|---|
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 |
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.
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 |
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 |
|
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.
(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.
Result of email-driven Item registration |
Status of files attached to the email |
||
---|---|---|---|
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 |
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.
(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.