OSID - osid.tracking.IssueMessagingSession Service Interface Definition

Interface	osid.tracking.IssueMessagingSession
Implements	`osid.OsidSession`
Used By	`osid.tracking.TrackingManager`
Used By	`osid.tracking.TrackingProxyManager`
Description	This session creates comments on issues and sends messages to customers. A comment is a direct log entry that may not be visible to the customer. A message is sent by some means to the customer and recorded in the log. In both cases, `LogEntryForms` are used to specify the content of the message or comment with an IssueAction of `COMMENTED` or `MESSAGE_SENT`.
Method	getFrontOfficeId
Description	Gets the `FrontOffice` `Id` associated with this session.
Return	`osid.id.Id`		the `FrontOffice Id` associated with this session
Compliance	`mandatory`		This method must be implemented.
Method	getFrontOffice
Description	Gets the `FrontOffice` associated with this session.
Return	`osid.tracking.FrontOffice`		the front office
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canComment
Description	Tests if this user can comment on Issues. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a `LogEntry` will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may opt not to offer comment operations to an unauthorized user.
Return	`boolean`		`false` if commenting is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canCreateLogEntryCommentWithRecordTypes
Description	Tests if this user can create a single `LogEntry` using the desired record types. While `TrackingManager.getLogEntryRecordTypes()` can be used to examine which records are supported, this method tests which record(s) are required for creating a specific `LogEntry`. Providing an empty array tests if a `LogEntry` can be created with no records.
Parameters	`osid.type.Type[]`	`logEntryRecordTypes`	array of log entry record types
Return	`boolean`		`true` if `LogEntry` creation using the specified record `Types` is supported, `false` otherwise
Errors	NULL_ARGUMENT		`logEntryRecordTypes` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	getLogEntryFormForCommenting
Description	Gets the log entry form for creating commenting on issues. A new form should be requested for each create transaction.
Parameters	`osid.type.Type[]`	`logEntryRecordTypes`	array of log entry record types
Return	`osid.tracking.LogEntryForm`		the log entry form
Errors	NULL_ARGUMENT		`logEntryRecordTypes` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		unable to get form for requested record types
Compliance	`mandatory`		This method must be implemented.
Method	comment
Description	Comments on an issue.
Parameters	`osid.id.Id`	`issueId`	the `Id` of the issue
Parameters	`osid.tracking.LogEntryForm`	`logEntryForm`	the form for this `LogEntry`
Return	`osid.tracking.LogEntry`		the new `LogEntry`
Errors	INVALID_ARGUMENT		one or more of the form elements is invalid
	NOT_FOUND		`issueId` is not found
	NULL_ARGUMENT		`issueId` or `logEntryForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`logEntryForm` is not of this service
Compliance	`mandatory`		This method must be implemented.
Method	canUpdateComments
Description	Tests if this user can update comments. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a comment will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may opt not to offer update operations to an unauthorized user.
Return	`boolean`		`false` if comment modification is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canUpdateComment
Description	Tests if this user can update a specified `LogEntry`. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating the `LogEntry` will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may opt not to offer an update operation to an unauthorized user for this log entry.
Parameters	`osid.id.Id`	`logEntryId`	the `Id` of the comment entry
Return	`boolean`		`false` if log entry modification is not authorized, `true` otherwise
Errors	NULL_ARGUMENT		`logEntryId` is `null`
Compliance	`mandatory`		This method must be implemented.
Provider Notes	If the `logEntryId` is not found, then it is acceptable to return false to indicate the lack of an update available.
Method	getLogEntryFormForCommentUpdate
Description	Gets the log entry form for updating an existing comment. A new log entry form should be requested for each update transaction.
Parameters	`osid.id.Id`	`Id`	the `Id` of the `LogEntry`
Return	`osid.tracking.LogEntryForm`		the log entry form
Errors	NOT_FOUND		`logEntryId` is not found
	NULL_ARGUMENT		`logEntryId` is `null`
	OPERATION_FAILED		unable to complete request
Compliance	`mandatory`		This method must be implemented.
Method	updateComment
Description	Updates an existing log entry.
Parameters	`osid.tracking.LogEntryForm`	`logEntryForm`	the form containing the elements to be updated
Errors	ILLEGAL_STATE		`logEntryForm` already used in an update transaction
	INVALID_ARGUMENT		the form contains an invalid value
	NULL_ARGUMENT		`logEntryForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`logEntryForm` did not originate from `getCommentFormForUpdate()`
Compliance	`mandatory`		This method must be implemented.
Method	canDeleteComments
Description	Tests if this user can delete comments. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a comment will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may opt not to offer delete operations to an unauthorized user.
Return	`boolean`		`false` if comment deletion is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canDeleteComment
Description	Tests if this user can delete a specified comment. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting the comment will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may opt not to offer an delete operation to an unauthorized user for this log entry.
Parameters	`osid.id.Id`	`logEntryId`	the `Id` of the comment
Return	`boolean`		`false` if deletion of this `LogEntry` is not authorized, `true` otherwise
Errors	NULL_ARGUMENT		`logEntryId` is `null`
Compliance	`mandatory`		This method must be implemented.
Provider Notes	If the `logEntryId` is not found, then it is acceptable to return false to indicate the lack of an delete available.
Method	deleteComment
Description	Deletes a comment.
Parameters	`osid.id.Id`	`logEntryId`	the `Id` of the comment to remove
Errors	NOT_FOUND		`logEntryId` not found
	NULL_ARGUMENT		`logEntryId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	deleteComments
Description	Deletes all comments in this `FrontOffice`.
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	deleteCommentsByDate
Description	Deletes all comments within the given date range inclusive in this `FrontOffice`.
Parameters	`osid.calendaring.DateTime`	`from`	start date
Parameters	`osid.calendaring.DateTime`	`to`	end date
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NULL_ARGUMENT		`from` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	deleteCommentsForQueue
Description	Deletes all comments in a `Queue`.
Parameters	`osid.id.Id`	`queueId`	the `Id` of a `Queue`
Errors	NOT_FOUND		`queueId` not found
	NULL_ARGUMENT		`queueId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	deleteCommentsByDateForQueue
Description	Deletes all comments within the given date range inclusive in this `Queue`.
Parameters	`osid.id.Id`	`queueId`	the `Id` of a `Queue`
	`osid.calendaring.DateTime`	`from`	start date
	`osid.calendaring.DateTime`	`to`	end date
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NOT_FOUND		`queueId` not found
	NULL_ARGUMENT		`queueId, from` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	deleteCommentsForIssue
Description	Deletes all comments in an `Issue`.
Parameters	`osid.id.Id`	`issueId`	the `Id` of an `Issue`
Errors	NOT_FOUND		`issueId` not found
	NULL_ARGUMENT		`issueId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	deleteCommentsByDateForIssue
Description	Deletes all comments within the given date range inclusive in this `Issue`.
Parameters	`osid.id.Id`	`issueId`	the `Id` of an `Issue`
	`osid.calendaring.DateTime`	`from`	start date
	`osid.calendaring.DateTime`	`to`	end date
Errors	INVALID_ARGUMENT		`from` is greater than `to`
	NOT_FOUND		`issueId` not found
	NULL_ARGUMENT		`issueId, from` or `to` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canSendMessages
Description	Tests if this user can send customer messages. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a `LogEntry` will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may opt not to offer comment operations to an unauthorized user.
Return	`boolean`		`false` if messaging is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canCreateLogEntryMessageWithRecordTypes
Description	Tests if this user can create a single `LogEntry` using the desired record types. While `TrackingManager.getLogEntryRecordTypes()` can be used to examine which records are supported, this method tests which record(s) are required for creating a specific `LogEntry`. Providing an empty array tests if a `LogEntry` can be created with no records.
Parameters	`osid.type.Type[]`	`logEntryRecordTypes`	array of log entry record types
Return	`boolean`		`true` if `LogEntry` creation using the specified record `Types` is supported, `false` otherwise
Errors	NULL_ARGUMENT		`logEntryRecordTypes` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	getLogEntryFormForMessaging
Description	Gets the log entry form for creating messages to customers. A new form should be requested for each create transaction.
Parameters	`osid.type.Type[]`	`logEntryRecordTypes`	array of log entry record types
Return	`osid.tracking.LogEntryForm`		the log entry form
Errors	NULL_ARGUMENT		`logEntryRecordTypes` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		unable to get form for requested record types
Compliance	`mandatory`		This method must be implemented.
Method	sendMessage
Description	Send a customer a message and records it in the issue log.
Parameters	`osid.id.Id`	`issueId`	the `Id` of the issue
Parameters	`osid.tracking.LogEntryForm`	`logEntryForm`	the form for this `LogEntry`
Return	`osid.tracking.LogEntry`		the new `LogEntry`
Errors	INVALID_ARGUMENT		one or more of the form elements is invalid
	NOT_FOUND		`issueId` is not found
	NULL_ARGUMENT		`issueId` or `logEntryForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`logEntryForm` is not of this service
Compliance	`mandatory`		This method must be implemented.