Kernel::System::ITSMChange::ITSMWorkOrder - workorder lib
All functions for workorders in ITSMChangeManagement.
new()
create an object
use Kernel::Config;
use Kernel::System::Encode;
use Kernel::System::Log;
use Kernel::System::DB;
use Kernel::System::Main;
use Kernel::System::Time;
use Kernel::System::Group;
use Kernel::System::User;
use Kernel::System::ITSMChange::ITSMWorkOrder;
my $ConfigObject = Kernel::Config->new();
my $EncodeObject = Kernel::System::Encode->new(
ConfigObject => $ConfigObject,
);
my $LogObject = Kernel::System::Log->new(
ConfigObject => $ConfigObject,
EncodeObject => $EncodeObject,
);
my $MainObject = Kernel::System::Main->new(
ConfigObject => $ConfigObject,
EncodeObject => $EncodeObject,
LogObject => $LogObject,
);
my $TimeObject = Kernel::System::Time->new(
ConfigObject => $ConfigObject,
LogObject => $LogObject,
);
my $DBObject = Kernel::System::DB->new(
ConfigObject => $ConfigObject,
EncodeObject => $EncodeObject,
LogObject => $LogObject,
MainObject => $MainObject,
);
my $GroupObject = Kernel::System::Group->new(
ConfigObject => $ConfigObject,
EncodeObject => $EncodeObject,
LogObject => $LogObject,
DBObject => $DBObject,
MainObject => $MainObject,
);
my $UserObject = Kernel::System::User->new(
ConfigObject => $ConfigObject,
EncodeObject => $EncodeObject,
LogObject => $LogObject,
DBObject => $DBObject,
TimeObject => $TimeObject,
MainObject => $MainObject,
);
my $WorkOrderObject = Kernel::System::ITSMChange::ITSMWorkOrder->new(
ConfigObject => $ConfigObject,
EncodeObject => $EncodeObject,
LogObject => $LogObject,
DBObject => $DBObject,
TimeObject => $TimeObject,
MainObject => $MainObject,
);
WorkOrderAdd()
Add a new workorder. Internally first a minimal workorder is created, then WorkOrderUpdate() is called for setting the remaining arguments.
my $WorkOrderID = $WorkOrderObject->WorkOrderAdd(
ChangeID => 123,
UserID => 1,
);
or
my $WorkOrderID = $WorkOrderObject->WorkOrderAdd(
ChangeID => 123,
WorkOrderTitle => 'Replacement of mail server', # (optional)
Instruction => 'Install the the new server', # (optional)
Report => 'Installed new server without problems', # (optional)
WorkOrderStateID => 157, # (optional) or WorkOrderState => 'ready'
WorkOrderState => 'ready', # (optional) or WorkOrderStateID => 157
WorkOrderTypeID => 161, # (optional) or WorkOrderType => 'pir'
WorkOrderType => 'ready', # (optional) or WorkOrderTypeID => 161
WorkOrderAgentID => 8, # (optional)
PlannedStartTime => '2009-10-12 00:00:01', # (optional)
PlannedEndTime => '2009-10-15 15:00:00', # (optional)
ActualStartTime => '2009-10-14 00:00:01', # (optional)
ActualEndTime => '2009-01-20 00:00:01', # (optional)
PlannedEffort => 123, # (optional)
WorkOrderFreeKey1 => 'Sun', # (optional) workorder freekey fields from 1 to ITSMWorkOrder::FreeText::MaxNumber
WorkOrderFreeText1 => 'Earth', # (optional) workorder freetext fields from 1 to ITSMWorkOrder::FreeText::MaxNumber
UserID => 1,
);
WorkOrderUpdate()
Update a workorder.
Leading and trailing whitespace is removed from WorkOrderTitle.
Passing undefined values is generally not allowed. An exception
are the parameters PlannedStartTime, PlannedEndTime, ActualStartTime, and ActualEndTime.
There passing undef indicates that the workorder time should be cleared.
Another exception is the WorkOrderAgentID. Pass undef for removing the workorder agent.
my $Success = $WorkOrderObject->WorkOrderUpdate(
WorkOrderID => 4,
WorkOrderNumber => 5, # (optional)
WorkOrderTitle => 'Replacement of mail server', # (optional)
Instruction => 'Install the the new server', # (optional)
Report => 'Installed new server without problems', # (optional)
WorkOrderStateID => 157, # (optional) or WorkOrderState => 'ready'
WorkOrderState => 'ready', # (optional) or WorkOrderStateID => 157
WorkOrderTypeID => 161, # (optional) or WorkOrderType => 'pir'
WorkOrderType => 'pir', # (optional) or WorkOrderStateID => 161
WorkOrderAgentID => 8, # (optional) can be undef for removing the workorder agent
PlannedStartTime => '2009-10-12 00:00:01', # (optional) 'undef' indicates clearing
PlannedEndTime => '2009-10-15 15:00:00', # (optional) 'undef' indicates clearing
ActualStartTime => '2009-10-14 00:00:01', # (optional) 'undef' indicates clearing
ActualEndTime => '2009-01-20 00:00:01', # (optional) 'undef' indicates clearing
PlannedEffort => 123, # (optional)
AccountedTime => 13, # (optional) the value is added to the value in the database
WorkOrderFreeKey1 => 'Sun', # (optional) workorder freekey fields from 1 to ITSMWorkOrder::FreeText::MaxNumber
WorkOrderFreeText1 => 'Earth', # (optional) workorder freetext fields from 1 to ITSMWorkOrder::FreeText::MaxNumber
NoNumberCalc => 1, # (optional) default 0, if 1 it prevents a recalculation of the workorder numbers
BypassStateMachine => 1, # (optional) default 0, if 1 the state machine will be bypassed
UserID => 1,
);
Constraints:
xxxStartTime has to be before xxxEndTime. If just one of the parameter pair is passed
the other time is retrieved from database.
The WorkOrderStateID is checked against the state machine.
WorkOrderGet()
Return a WorkOrder as hash reference.
When the workorder does not exist, a false value is returned.
The optional option LogNo turns off logging when the workorder does not exist.
my $WorkOrderRef = $WorkOrderObject->WorkOrderGet(
WorkOrderID => 123,
UserID => 1,
LogNo => 1, # optional, turns off logging when the workorder does not exist
);
The returned hash reference contains following elements:
$WorkOrder{WorkOrderID}
$WorkOrder{ChangeID}
$WorkOrder{WorkOrderNumber}
$WorkOrder{WorkOrderTitle}
$WorkOrder{Instruction}
$WorkOrder{InstructionPlain}
$WorkOrder{Report}
$WorkOrder{ReportPlain}
$WorkOrder{WorkOrderStateID}
$WorkOrder{WorkOrderState} # fetched from the general catalog
$WorkOrder{WorkOrderStateSignal} # fetched from SysConfig
$WorkOrder{WorkOrderTypeID}
$WorkOrder{WorkOrderType} # fetched from the general catalog
$WorkOrder{WorkOrderAgentID}
$WorkOrder{PlannedStartTime}
$WorkOrder{PlannedEndTime}
$WorkOrder{ActualStartTime}
$WorkOrder{ActualEndTime}
$WorkOrder{AccountedTime}
$WorkOrder{PlannedEffort}
$WorkOrder{WorkOrderFreeKey1} # workorder freekey fields from 1 to ITSMWorkOrder::FreeText::MaxNumber
$WorkOrder{WorkOrderFreeText1} # workorder freetext fields from 1 to ITSMWorkOrder::FreeText::MaxNumber
$WorkOrder{CreateTime}
$WorkOrder{CreateBy}
$WorkOrder{ChangeTime}
$WorkOrder{ChangeBy}
WorkOrderList()
Return a list of all workorder ids of the given change as array reference. The workorder ids are ordered by workorder number.
my $WorkOrderIDsRef = $WorkOrderObject->WorkOrderList(
ChangeID => 5,
UserID => 1,
);
WorkOrderSearch()
Returns either a list, as an arrayref, or a count of found workorder ids.
The count of results is returned when the parameter Result = 'COUNT'> is passed.
The search criteria are logically AND connected. When a list is passed as criterium, the individual members are OR connected. When an undef or a reference to an empty array is passed, then the search criterium is ignored.
my $WorkOrderIDsRef = $WorkOrderObject->WorkOrderSearch(
ChangeIDs => [ 123, 122 ] # (optional)
WorkOrderNumber => 12, # (optional)
WorkOrderTitle => 'Replacement of mail server', # (optional)
Instruction => 'Install the the new server', # (optional)
Report => 'Installed new server without problems', # (optional)
# search in workorder freetext and freekey fields
WorkOrderFreeKey1 => 'Sun', # (optional) workorder freekey fields from 1 to ITSMWorkOrder::FreeText::MaxNumber
WorkOrderFreeText1 => 'Earth', # (optional) workorder freetext fields from 1 to ITSMWorkOrder::FreeText::MaxNumber
WorkOrderStateIDs => [ 11, 12 ], # (optional)
WorkOrderStates => [ 'closed', 'canceled' ], # (optional)
WorkOrderTypeIDs => [ 21, 22 ], # (optional)
WorkOrderTypes => [ 'approval', 'workorder' ], # (optional)
WorkOrderAgentIDs => [ 1, 2, 3 ], # (optional)
CreateBy => [ 5, 2, 3 ], # (optional)
ChangeBy => [ 3, 2, 1 ], # (optional)
# search in text fields of change object
ChangeNumber => 'Number of change', # (optional)
ChangeTitle => 'Title of change', # (optional)
ChangeDescription => 'Description of change', # (optional)
ChangeJustification => 'Justification of change', # (optional)
# workorders with planned start time after ...
PlannedStartTimeNewerDate => '2006-01-09 00:00:01', # (optional)
# workorders with planned start time before then ....
PlannedStartTimeOlderDate => '2006-01-19 23:59:59', # (optional)
# workorders with planned end time after ...
PlannedEndTimeNewerDate => '2006-01-09 00:00:01', # (optional)
# workorders with planned end time before then ....
PlannedEndTimeOlderDate => '2006-01-19 23:59:59', # (optional)
# workorders with actual start time after ...
ActualStartTimeNewerDate => '2006-01-09 00:00:01', # (optional)
# workorders with actual start time before then ....
ActualStartTimeOlderDate => '2006-01-19 23:59:59', # (optional)
# workorders with actual end time after ...
ActualEndTimeNewerDate => '2006-01-09 00:00:01', # (optional)
# workorders with actual end time before then ....
ActualEndTimeOlderDate => '2006-01-19 23:59:59', # (optional)
# workorders with created time after ...
CreateTimeNewerDate => '2006-01-09 00:00:01', # (optional)
# workorders with created time before then ....
CreateTimeOlderDate => '2006-01-19 23:59:59', # (optional)
# workorders with changed time after ...
ChangeTimeNewerDate => '2006-01-09 00:00:01', # (optional)
# workorders with changed time before then ....
ChangeTimeOlderDate => '2006-01-19 23:59:59', # (optional)
OrderBy => [ 'ChangeID', 'WorkOrderNumber' ], # (optional)
# ignored when the result type is 'COUNT'
# default: [ 'WorkOrderID' ],
# (WorkOrderID, ChangeID, WorkOrderNumber, WorkOrderTitle
# WorkOrderStateID, WorkOrderTypeID, WorkOrderAgentID,
# PlannedStartTime, PlannedEndTime,
# ActualStartTime, ActualEndTime,
# CreateTime, CreateBy, ChangeTime, ChangeBy)
# Additional information for OrderBy:
# The OrderByDirection can be specified for each OrderBy attribute.
# The pairing is made by the array indices.
OrderByDirection => [ 'Down', 'Up' ], # (optional)
# ignored when the result type is 'COUNT'
# default: [ 'Down' ]
# (Down | Up)
UsingWildcards => 1, # (optional)
# (0 | 1) default 1
Result => 'ARRAY' || 'COUNT', # (optional)
# default: ARRAY, returns an array of workorder ids
# COUNT returns a scalar with the number of found workorders
Limit => 100, # (optional)
# ignored when the result type is 'COUNT'
MirrorDB => 1, # (optional)
# (0 | 1) default 0
# if set to 1 and ITSMChange::ChangeSearch::MirrorDB
# is activated and a mirror db is configured in
# Core::MirrorDB::DSN the workorder search will then use
# the mirror db
UserID => 1,
);
WorkOrderDelete()
Delete a workorder.
This function removes all links and attachments to the workorder with the passed workorder id. After that the workorder is removed.
my $Success = $WorkOrderObject->WorkOrderDelete(
WorkOrderID => 123,
NoNumberCalc => 1, # (optional) default 0, if 1 it prevents a recalculation of the workorder numbers
UserID => 1,
);
WorkOrderChangeTimeGet()
Returns a list of PlannedStartTime | PlannedEndTime | ActualStartTime | ActualEndTime of a change, which would be the respective time of the earliest starting workorder (for start times) or the latest ending workorder (for end times).
For PlannedStartTime | PlannedEndTime | ActualEndTime an empty string is returned if any of the workorders of a change has the respective time not defined.
The ActualStartTime is defined when any of the workorders of a change has a defined ActualStartTime.
Return
$Time{PlannedStartTime}
$Time{PlannedEndTime}
$Time{ActualStartTime}
$Time{ActualEndTime}
my $TimeRef = $WorkOrderObject->WorkOrderChangeTimeGet(
ChangeID => 123,
UserID => 1,
# ---------------------------------------------------- #
# TODO: (decide this later!)
Maybe add this new attribute:
# These are WorkOrderTypes (Types, not States!)
# which would be excluded from the calculation
# of the change start time.
ExcludeWorkOrderTypes => [ 'approval', 'pir' ], # (optional)
# ---------------------------------------------------- #
);
WorkOrderStateLookup()
This method does a lookup for a workorder state. If a workorder state id is given, it returns the name of the workorder state. If a workorder state name is given, the appropriate id is returned.
my $WorkOrderState = $WorkOrderObject->WorkOrderStateLookup(
WorkOrderStateID => 157,
);
my $WorkOrderStateID = $WorkOrderObject->WorkOrderStateLookup(
WorkOrderState => 'ready',
);
WorkOrderPossibleStatesGet()
This method returns a list of possible workorder states.
If WorkOrderID is omitted, the complete list of workorder states is returned.
If WorkOrderID is given, the list of possible states for the given
workorder is returned.
my $WorkOrderStateList = $WorkOrderObject->WorkOrderPossibleStatesGet(
WorkOrderID => 123, # (optional)
UserID => 1,
);
The return value is a reference to an array of hashrefs. The element 'Key' is then the StateID and the element 'Value' is the name of the state. The array elements are sorted by state id.
my $WorkOrderStateList = [
{
Key => 156,
Value => 'accepted',
},
{
Key => 157,
Value => 'in progress',
},
];
WorkOrderTypeLookup()
This method does a lookup for a workorder type. If a workorder type id is given, it returns the name of the workorder type. If a workorder type name is given, the appropriate id is returned.
my $WorkOrderType = $WorkOrderObject->WorkOrderTypeLookup(
WorkOrderTypeID => 157,
);
my $WorkOrderTypeID = $WorkOrderObject->WorkOrderTypeLookup(
WorkOrderType => 'ready',
);
WorkOrderTypeList()
This method returns a list of all workorder types.
my $WorkOrderTypeList = $WorkOrderObject->WorkOrderTypeList(
UserID => 1,
Default => 1, # optional - the default type is selected type (default: 0)
SelectedID => 123, # optional - this id is selected
);
The return value is a reference to an array of hashrefs. The Element 'Key' is then the TypeID and die Element 'Value' is the name of the type. The array elements are sorted by type id.
my $WorkOrderTypeList = [
{
Key => 171,
Value => 'workorder',
},
{
Key => 172,
Value => 'backout',
},
];
Permission()
Returns whether the agent UserID has permissions of the type Type
on the workorder WorkOrderID. The parameters are passed on to
the permission modules that were registered in the permission registry.
The standard permission registry is ITSMWorkOrder::Permission, but
that can be overridden with the parameter PermissionRegistry.
The registered permission modules are run in the alphabetical order of their registry keys. Overall permission is granted when a permission module, which has the attribute 'Granted' set, grants permission. Overall permission is denied when a permission module, which has the attribute 'Required' set, denies permission. Overall permission is also denied when when all permission module were asked without coming to an conclusion.
Approval is indicated by the return value 1. Denial is indicated by returning an empty list.
The optional option LogNo turns off logging when access was denied.
This is useful when the method is used for checking whether a link or an action should be shown.
my $Access = $WorkOrderObject->Permission(
UserID => 123,
Type => 'ro', # 'ro' and 'rw' are supported
Action => 'AgentITSMWorkOrderReport', # optional
WorkOrderID => 4444,
PermissionRegistry => 'ITSMWorkOrder::TakePermission',
# optional with default 'ITSMWorkOrder::Permission'
LogNo => 1, # optional, turns off logging when access is denied
);
WorkOrderStateIDsCheck()
Check whether all of the given workorder state ids are valid. The method is public as it is used in Kernel::System::ITSMChange::ChangeSearch.
my $Ok = $WorkOrderObject->WorkOrderStateIDsCheck(
WorkOrderStateIDs => [ 25 ],
);
WorkOrderAttachmentAdd()
Add an attachment to the given change.
my $Success = $WorkOrderObject->WorkOrderAttachmentAdd(
ChangeID => 123,
WorkOrderID => 456, # the WorkOrderID becomes part of the file path
Filename => 'filename',
Content => 'content',
ContentType => 'text/plain',
UserID => 1,
);
WorkOrderAttachmentDelete()
Delete the given file from the virtual filesystem.
my $Success = $WorkOrderObject->WorkOrderAttachmentDelete(
ChangeID => 12345,
WorkOrderID => 5123,
Filename => 'Projectplan.pdf', # identifies the attachment (together with the WorkOrderID)
UserID => 1,
);
WorkOrderAttachmentGet()
This method returns information about one specific attachment.
my $Attachment = $WorkOrderObject->WorkOrderAttachmentGet(
WorkOrderID => 4,
Filename => 'test.txt',
);
returns
$Attachment = {
Preferences => {
AllPreferences => 'test',
},
Filename => 'test.txt',
Content => 'hallo',
ContentType => 'text/plain',
Filesize => '123 KBytes',
Type => 'attachment',
};
WorkOrderAttachmentList()
Returns an array with all attachments of the given workorder.
my @Attachments = $WorkOrderObject->WorkOrderAttachmentList(
WorkOrderID => 123,
);
returns
@Attachments = (
'filename.txt',
'other_file.pdf',
);
WorkOrderAttachmentExists()
Checks if a file with a given filename exists.
my $Exists = $WorkOrderObject->WorkOrderAttachmentExists(
Filename => 'test.txt',
WorkOrderID => 123,
UserID => 1,
);
WorkOrderChangeEffortsGet()
returns the combined efforts of the workorders for the given change
my $ChangeEfforts = $WorkOrderObject->WorkOrderChangeEffortsGet(
ChangeID => 123,
UserID => 1,
);
WorkOrderGetConfiguredFreeTextFields()
Returns an array with the numbers of all configured workorder freekey and freetext fields
my @ConfiguredWorkOrderFreeTextFields = $WorkOrderObject->WorkOrderGetConfiguredFreeTextFields();
This software is part of the OTRS project (http://otrs.org/).
This software comes with ABSOLUTELY NO WARRANTY. For details, see the enclosed file COPYING for license information (AGPL). If you did not receive this file, see http://www.gnu.org/licenses/agpl.txt.