ChangeMessageAttributes

Purpose

Use ChangeMessageAttributes to set or change the attributes of a message in workspace to attributes specified by the caller.

Description

This action can implement a caller’s request to deliver a message on a future date, redefine the urgency and security levels of a message, or receive acknowledgment that a message was received. The Message : Receipt acknowledgment status system variable (SV161) contains a value that indicates whether or not message acknowledgment was requested and, if requested, whether the message was received or rejected (deleted without being listened to). ChangeMessageAttributes can also tie a message to a transaction.

To use ChangeMessageAttributes to change the attributes of a message, the state must precede any SendVoiceMessage state that sends the existing message to a mailbox. You cannot change the attributes of a message after you have sent it.

Parameters

The parameters for ChangeMessageAttributes identify the new attributes for the message. The action can only change one attribute at a time.

The parameters differ, depending on what attribute is being changed:

• When a message is Future Dated, the parameters are:

  Month

  Defines the month in which the caller wants the message delivered. This is a numeric value in the range 01–12.

  Day

  Defines the day of the month that the caller wants the message delivered. This is a numeric value in the range 01–31.

  Year

  Defines the year in which the caller wants the message delivered. This can be either a two-digit (YY) value or a four-digit (YYYY) value. When a two-digit value is specified, it represents the last two digits of the four-digit (YYYY) value, for example, 98 means 1998, and 02 means 2002.

  Note: The year must be the current year or next year.

  Hour

  Defines the hour of the day at which the caller wants the message delivered. This is a numeric value in the range 00–23.

  Minute

  Defines the minute of the hour at which the caller wants the message delivered. This is a numeric value in the range 00–59.

  Note:

  1. The current date, on which validity checks are based, can be affected by the value of SV545 (System : Subscriber Timezone) if the initiating subscriber is in a different timezone.
  2. Valid dates are in a 3-year range, so, for messages sent at any time in 1997, the valid date range is 1 January 1996 to 31 December 1998 inclusive.
  3. If any of the above variables contain information that defines a valid date that has already past, the message is delivered immediately.
• When the Security Level is being changed, the parameter is:

  Attr Data

  Specifies the new security level information.

  Valid values are:

  0

  Not private

  1

  Private

• When the Urgency Level is being changed, the parameter is:

  Attr Data

  Specifies the new urgency level information.

  Valid values are:

  10

  Emergency

  20

  Urgent

  30

  Normal

• When Receipt Acknowledgment is being changed, the parameter is:

  Attr Data

  Specifies the new acknowledgment information.

  Valid values are:

  0

  Acknowledgment of receipt not requested

  1

  Acknowledgment of receipt requested

  4

  The message is not placed on the sender’s outgoing messages list, so the sender cannot subsequently choose to delete the message before a recipient has checked their messages. No acknowledgment of receipt is requested

  5

  The message is not placed on the sender’s outgoing messages list (as 4 above) but an acknowledgment of receipt is requested.

• When Transaction Message ID is selected, the parameter is:

  Attr Data

  Specifies the identification of the transaction to which the message is tied. The ID can be up to 16 characters.

Possible results

ChangeMessageAttributes can have one of the following results:

Succeeded

The change action succeeded. The default attribute has been changed for the message.

Failed

The change action failed because no message was in the workplace.

Invalid Date Parameter

The variables that define the date either contain a date that is outside the valid range, or do not contain a date at all (the parameter value was invalid).

Valid dates are in a 3-year range, so, for messages sent at any time in 1997, the valid date range is 1 January 1996 to 31 December 1998 inclusive.

ASCII syntax

When using an ASCII editor, code this action with these parameters in the following order:

1. "FUTURE_DATED"
2. month
3. day
4. year
5. hour
6. minute

Or:

1. "SECURITY_LEVEL"
   • or "URGENCY_LEVEL"
   • or "RECEIPT_ACKNOWLEDGE"
   • or "TRANSACTION_MESSAGE_ID"
2. Variable or constant

For example:

label: "Check Edges"
	ChangeMessageAttributes("FUTURE_DATED", in1_n, in2_n, in4_s, loc4_s, loc2_n)
	  edge EDGE_CHANGE_ATTRIB_COMPLETED:		completed
	  edge EDGE_CHANGE_ATTRIB_FAILED:			failed
	  edge EDGE_CHANGE_ATTRIB_INVALID_VALUE:   invalid_value
	;
	ChangeMessageAttributes("SECURITY_LEVEL", loc3_s);
	ChangeMessageAttributes("URGENCY_LEVEL", loc3_s);
	ChangeMessageAttributes("RECEIPT_ACKNOWLEDGE", loc3_s);
	ChangeMessageAttributes("TRANSACTION_MESSAGE_ID", loc3_s);

The parameters and edges are described above under "Parameters" and "Possible results". For more information, see Testing a state table using the debugger.