Kernel::System::ITSMChange - change lib
All functions for changes 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::ITSMChange;
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 $ChangeObject = Kernel::System::ITSMChange->new(
ConfigObject => $ConfigObject,
EncodeObject => $EncodeObject,
LogObject => $LogObject,
DBObject => $DBObject,
TimeObject => $TimeObject,
MainObject => $MainObject,
);
ChangeAdd()
Add a new change. The UserId is the only required parameter. Internally first a minimal change is created, then ChangeUpdate() is called.
my $ChangeID = $ChangeObject->ChangeAdd(
UserID => 1,
);
or
my $ChangeID = $ChangeObject->ChangeAdd(
ChangeTitle => 'Replacement of mail server', # (optional)
Description => 'New mail server is faster', # (optional)
Justification => 'Old mail server too slow', # (optional)
ChangeStateID => 4, # (optional) or ChangeState => 'accepted'
ChangeState => 'accepted', # (optional) or ChangeStateID => 4
ChangeManagerID => 5, # (optional)
ChangeBuilderID => 6, # (optional)
CategoryID => 7, # (optional) or Category => '3 normal'
Category => '3 normal', # (optional) or CategoryID => 4
ImpactID => 8, # (optional) or Impact => '4 high'
Impact => '4 high', # (optional) or ImpactID => 5
PriorityID => 9, # (optional) or Priority => '5 very high'
Priority => '5 very high', # (optional) or PriorityID => 6
CABAgents => [ 1, 2, 4 ], # UserIDs # (optional)
CABCustomers => [ 'tt', 'mm' ], # CustomerUserIDs # (optional)
RequestedTime => '2006-01-19 23:59:59', # (optional)
ChangeFreeKey1 => 'Sun', # (optional) change freekey fields from 1 to ITSMChange::FreeText::MaxNumber
ChangeFreeText1 => 'Earth', # (optional) change freetext fields from 1 to ITSMChange::FreeText::MaxNumber
UserID => 1,
);
ChangeUpdate()
Update a change.
Leading and trailing whitespace is removed from ChangeTitle.
Passing undefined values is generally not allowed.
An exception is the parameter RequestedTime, where the undefined value
indicates that requested time of the change should be cleared.
my $Success = $ChangeObject->ChangeUpdate(
ChangeID => 123,
ChangeTitle => 'Replacement of slow mail server', # (optional)
Description => 'New mail server is faster', # (optional)
Justification => 'Old mail server too slow', # (optional)
ChangeStateID => 4, # (optional) or ChangeState => 'accepted'
ChangeState => 'accepted', # (optional) or ChangeStateID => 4
ChangeManagerID => 5, # (optional)
ChangeBuilderID => 6, # (optional)
CategoryID => 7, # (optional) or Category => '3 normal'
Category => '3 normal', # (optional) or CategoryID => 4
ImpactID => 8, # (optional) or Impact => '4 high'
Impact => '4 high', # (optional) or ImpactID => 5
PriorityID => 9, # (optional) or Priority => '5 very high'
Priority => '5 very high', # (optional) or PriorityID => 6
CABAgents => [ 1, 2, 4 ], # (optional) UserIDs
CABCustomers => [ 'tt', 'mm' ], # (optional) CustomerUserIDs
RequestedTime => '2006-01-19 23:59:59', # (optional) or 'undef', which clears the time
ChangeFreeKey1 => 'Sun', # (optional) change freekey fields from 1 to ITSMChange::FreeText::MaxNumber
ChangeFreeText1 => 'Earth', # (optional) change freetext fields from 1 to ITSMChange::FreeText::MaxNumber
BypassStateMachine => 1, # (optional) default 0, if 1 the state machine will be bypassed
UserID => 1,
);
ChangeGet()
Return a change as a hash reference.
When the workorder does not exist, a false value is returned.
The optional option LogNo turns off logging when the change does not exist.
my $Change = $ChangeObject->ChangeGet(
ChangeID => 123,
UserID => 1,
LogNo => 1, # optional, turns off logging when the change does not exist
);
The returned hash reference contains the following elements:
$Change{ChangeID}
$Change{ChangeNumber}
$Change{ChangeStateID}
$Change{ChangeState} # fetched from the general catalog
$Change{ChangeStateSignal} # fetched from SysConfig
$Change{ChangeTitle}
$Change{Description}
$Change{DescriptionPlain}
$Change{Justification}
$Change{JustificationPlain}
$Change{ChangeManagerID}
$Change{ChangeBuilderID}
$Change{CategoryID}
$Change{Category}
$Change{ImpactID}
$Change{Impact}
$Change{PriorityID}
$Change{Priority}
$Change{WorkOrderIDs} # array reference with WorkOrderIDs, sorted by WorkOrderNumber
$Change{WorkOrderCount} # number of workorders
$Change{CABAgents} # array reference with CAB Agent UserIDs
$Change{CABCustomers} # array reference with CAB CustomerUserIDs
$Change{PlannedStartTime} # determined from the workorders
$Change{PlannedEndTime} # determined from the workorders
$Change{ActualStartTime} # determined from the workorders
$Change{ActualEndTime} # determined from the workorders
$Change{PlannedEffort} # determined from the workorders
$Change{AccountedTime} # determined from the workorders
$Change{RequestedTime}
$Change{ChangeFreeKey1} # change freekey fields from 1 to ITSMChange::FreeText::MaxNumber
$Change{ChangeFreeText1} # change freetext fields from 1 to ITSMChange::FreeText::MaxNumber
$Change{CreateTime}
$Change{CreateBy}
$Change{ChangeTime}
$Change{ChangeBy}
ChangeCABUpdate()
Add or update the CAB of a change. One or both of CABAgents and CABCustomers must be passed. Passing a reference to an empty array deletes the part of the CAB (CABAgents or CABCustomers) When agents or customers are passed multiple times, they will be inserted only once.
my $Success = $ChangeObject->ChangeCABUpdate(
ChangeID => 123,
CABAgents => [ 1, 2, 4 ], # UserIDs (optional)
CABCustomers => [ 'tt', 'mm' ], # CustomerUserIDs (optional)
UserID => 1,
);
ChangeCABGet()
Return the CAB of a change as a hashref, where the values are arrayrefs. The returned array references are sorted.
my $ChangeCAB = $ChangeObject->ChangeCABGet(
ChangeID => 123,
UserID => 1,
);
Returns:
$ChangeCAB = {
CABAgents => [ 1, 2, 4 ],
CABCustomers => [ 'aa', 'bb' ],
}
ChangeCABDelete()
Delete the CAB of a change.
my $Success = $ChangeObject->ChangeCABDelete(
ChangeID => 123,
UserID => 1,
);
ChangeLookup()
Return the change id when the change number is passed. Return the change number when the change id is passed. When no change id or change number is found, then the undefined value is returned.
my $ChangeID = $ChangeObject->ChangeLookup(
ChangeNumber => '2009091742000465',
);
my $ChangeNumber = $ChangeObject->ChangeLookup(
ChangeID => 42,
);
ChangeList()
Return a change id list of all changes as an array reference.
my $ChangeIDsRef = $ChangeObject->ChangeList(
UserID => 1,
);
ChangeSearch()
Returns either a list, as an arrayref, or a count of found change 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 $ChangeIDsRef = $ChangeObject->ChangeSearch(
ChangeNumber => '2009100112345778', # (optional)
ChangeTitle => 'Replacement of slow mail server', # (optional)
Description => 'New mail server is faster', # (optional)
Justification => 'Old mail server too slow', # (optional)
# array parameters are used with logical OR operator
ChangeStateIDs => [ 11, 12, 13 ], # (optional)
ChangeStates => [ 'requested', 'failed' ], # (optional)
ChangeManagerIDs => [ 1, 2, 3 ], # (optional)
ChangeBuilderIDs => [ 5, 7, 4 ], # (optional)
CreateBy => [ 5, 2, 3 ], # (optional)
ChangeBy => [ 3, 2, 1 ], # (optional)
WorkOrderAgentIDs => [ 6, 2 ], # (optional)
CABAgents => [ 9, 13 ], # (optional)
CABCustomers => [ 'tt', 'xx' ], # (optional)
Categories => [ '1 very low', '2 low' ], # (optional)
CategoryIDs => [ 135, 173 ], # (optional)
Impacts => [ '1 very low', '2 low' ], # (optional)
ImpactIDs => [ 136, 174 ], # (optional)
Priorities => [ '1 very low', '2 low' ], # (optional)
PriorityIDs => [ 137, 175 ], # (optional)
# search in change freetext and freekey fields
ChangeFreeKey1 => 'Sun', # (optional) change freekey fields from 1 to ITSMChange::FreeText::MaxNumber
ChangeFreeText1 => 'Earth', # (optional) change freetext fields from 1 to ITSMChange::FreeText::MaxNumber
# search in workorder freetext and freekey fields
WorkOrderFreeKey1 => 'Moon', # (optional) workorder freekey fields from 1 to ITSMWorkOrder::FreeText::MaxNumber
WorkOrderFreeText1 => 'Mars', # (optional) workorder freetext fields from 1 to ITSMWorkOrder::FreeText::MaxNumber
# search in text fields of workorder object
WorkOrderTitle => 'Boot Mailserver', # (optional)
WorkOrderInstruction => 'Press the button.', # (optional)
WorkOrderReport => 'Mailserver has booted.', # (optional)
# search in workorder (array params)
WorkOrderStates => [ 'accepted', 'ready' ], # (optional)
WorkOrderStateIDs => [ 1, 2, 3 ], # (optional)
# changes with planned start time after ...
PlannedStartTimeNewerDate => '2006-01-09 00:00:01', # (optional)
# changes with planned start time before then ....
PlannedStartTimeOlderDate => '2006-01-19 23:59:59', # (optional)
# changes with planned end time after ...
PlannedEndTimeNewerDate => '2006-01-09 00:00:01', # (optional)
# changes with planned end time before then ....
PlannedEndTimeOlderDate => '2006-01-19 23:59:59', # (optional)
# changes with actual start time after ...
ActualStartTimeNewerDate => '2006-01-09 00:00:01', # (optional)
# changes with actual start time before then ....
ActualStartTimeOlderDate => '2006-01-19 23:59:59', # (optional)
# changes with actual end time after ...
ActualEndTimeNewerDate => '2006-01-09 00:00:01', # (optional)
# changes with actual end time before then ....
ActualEndTimeOlderDate => '2006-01-19 23:59:59', # (optional)
# changes with created time after ...
CreateTimeNewerDate => '2006-01-09 00:00:01', # (optional)
# changes with created time before then ....
CreateTimeOlderDate => '2006-01-19 23:59:59', # (optional)
# changes with changed time after ...
ChangeTimeNewerDate => '2006-01-09 00:00:01', # (optional)
# changes with changed time before then ....
ChangeTimeOlderDate => '2006-01-19 23:59:59', # (optional)
# changes with requested time after ...
RequestedTimeNewerDate => '2006-01-09 00:00:01', # (optional)
# changes with requested time before then ....
RequestedTimeOlderDate => '2006-01-19 23:59:59', # (optional)
OrderBy => [ 'ChangeID', 'ChangeManagerID' ], # (optional)
# ignored when the result type is 'COUNT'
# default: [ 'ChangeID' ]
# (ChangeID, ChangeNumber, ChangeTitle, ChangeStateID,
# ChangeManagerID, ChangeBuilderID,
# CategoryID, ImpactID, PriorityID
# PlannedStartTime, PlannedEndTime,
# ActualStartTime, ActualEndTime, RequestedTime,
# 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 change ids
# COUNT returns a scalar with the number of found changes
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 change search will then use
# the mirror db
UserID => 1,
);
ChangeDelete()
Delete a change.
This function first removes all links and attachments to the given change.
Then it gets a list of all workorders of the change and
calls WorkorderDelete() for each workorder, which will delete
all links and all attachments to the workorders.
Then it deletes the CAB.
After that the change is removed.
The history of this change will be deleted during the handling of the
triggered ChangeDeletePost-event.
my $Success = $ChangeObject->ChangeDelete(
ChangeID => 123,
UserID => 1,
);
ChangeStateLookup()
This method does a lookup for a change state. If a change state id is given, it returns the name of the change state. If a change state name is given, the appropriate id is returned.
my $ChangeState = $ChangeObject->ChangeStateLookup(
ChangeStateID => 1234,
);
my $ChangeStateID = $ChangeObject->ChangeStateLookup(
ChangeState => 'accepted',
);
ChangePossibleStatesGet()
This method returns a list of possible change states. If ChangeID is omitted, the complete list of change states is returned. If ChangeID is given, the list of possible change states for this change is returned.
my $ChangeStateList = $ChangeObject->ChangePossibleStatesGet(
ChangeID => 123, # (optional)
UserID => 1,
);
The return value is a reference to an array of hashrefs. The element 'Key' is then the ChangeStateID and the element 'Value' is the name of the state. The array elements are sorted by state id.
my $ChangeStateList = [
{
Key => 156,
Value => 'approved',
},
{
Key => 157,
Value => 'in progress',
},
];
ChangePossibleCIPGet()
This method returns a list of possible categories, impacts or priorities.
my $CIPList = $ChangeObject->ChangePossibleCIPGet(
Type => 'Category', # Category|Impact|Priority
UserID => 1,
);
The return value is a reference to an array of hashrefs. The Element 'Key' is then the ID and the element 'Value' is the name of the category, impact or priority. The array elements are sorted by id in ascending order.
my $CIPList = [
{
Key => 156,
Value => '1 very low',
},
{
Key => 157,
Value => '2 low',
},
];
ChangeCIPLookup()
This method does a lookup for a change category, impact or priority. If a change CIP-ID is given, it returns the name of the CIP. If a change CIP name is given, the appropriate ID is returned.
my $Name = $ChangeObject->ChangeCIPLookup(
ID => 1234,
Type => 'Priority',
);
my $ID = $ChangeObject->ChangeCIPLookup(
CIP => '1 very low',
Type => 'Category',
);
Permission()
Returns whether the agent UserID has permissions of the type Type
on the change ChangeID. The parameters are passed on to
the permission modules that were registered in the permission registry.
The standard permission registry is ITSMChange::Permission, but
that can be overridden with the parameter PermissionRegistry.
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 = $ChangeObject->Permission(
UserID => 123,
Type => 'ro', # 'ro' and 'rw' are supported
Action => 'AgentITSMChangeEdit', # optional
ChangeID => 3333, # optional, do not pass for 'ChangeAdd'
PermissionRegistry => 'ITSMChange::Permission',
# optional with default 'ITSMChange::Permission'
LogNo => 1, # optional, turns off logging when access is denied
);
ChangeAttachmentAdd()
Add an attachment to the given change.
my $Success = $ChangeObject->ChangeAttachmentAdd(
ChangeID => 123, # the ChangeID becomes part of the file path
Filename => 'filename',
Content => 'content',
ContentType => 'text/plain',
UserID => 1,
);
ChangeAttachmentDelete()
Delete the given file from the virtual filesystem.
my $Success = $ChangeObject->ChangeAttachmentDelete(
ChangeID => 123, # used in event handling, e.g. for logging the history
Filename => 'Projectplan.pdf', # identifies the attachment (together with the ChangeID)
UserID => 1,
);
ChangeAttachmentGet()
This method returns information about one specific attachment.
my $Attachment = $ChangeObject->ChangeAttachmentGet(
ChangeID => 4,
Filename => 'test.txt',
);
returns
{
Preferences => {
AllPreferences => 'test',
},
Filename => 'test.txt',
Content => 'hallo',
ContentType => 'text/plain',
Filesize => '123 KBytes',
Type => 'attachment',
}
ChangeAttachmentList()
Returns an array with all attachments of the given change.
my @Attachments = $ChangeObject->ChangeAttachmentList(
ChangeID => 123,
);
returns
@Attachments = (
'filename.txt',
'other_file.pdf',
);
ChangeAttachmentExists()
Checks if a file with a given filename exists.
my $Exists = $ChangeObject->ChangeAttachmentExists(
Filename => 'test.txt',
ChangeID => 123,
UserID => 1,
);
ChangeGetConfiguredFreeTextFields()
Returns an array with the numbers of all configured change freekey and freetext fields
my @ConfiguredChangeFreeTextFields = $ChangeObject->ChangeGetConfiguredFreeTextFields();
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.