5Setting Properties

About the Set Property Method

One of the delivery channels for a scenario step is Set Property. When you select this method, the message scenario can update all company-defined properties, except file properties.

The set_property method can update the following entities:
  • Activity

  • Inventory

  • Resource

  • User

The property values should use an internal format. In particular, use the index values for enumeration properties rather than their translations. In the Subject field, specify a label for the property you are assigning. Do not use a pr_ or prnum_ prefix for the label.

The set_property method supports the following predefined list of activity fields. Additional predefined fields are not available.
  • appt_number

  • customer_number

  • customer_name

  • cell (or “sms”)

  • address

  • city

  • state

  • zip

  • email

  • phone

  • points

  • time_slot

  • service_window (hh:mm; hh:mm)

  • sla_window_start

  • sla_window_end

  • action (Only the cancel_activity and unschedule_activity action are supported. See the following sections for more details.)

Cancel Activity Actions

The set_property method supports canceling a pending activity with the cancel_activity action. If the activity is non-scheduled, it is moved to the current resource’s day and then canceled. Note that the message should contain “cancel” in the subject, and the name of the action to be performed should be stored in the message body. Also note that the cancel_activity action does not support the notdone and deleted actions depending on the activity and route status. After processing, the message is assigned one of the following statuses and its corresponding description.

Table Status ‘Delivered’

Status Description
Status delivered
Description
Notes The action is performed successfully.

Table Status ‘Failed’

Status Description
Status failed
Description INVALID_RESOURCE_TYPE
Notes This action is not supported for this type of resource. For example, the resource or its type is reconfigured, and activities can no longer be assigned to it.

Table Status ‘Failed’

Status Description
Status failed
Description NO_PERMISSION
Notes This user has no access to the specified resource or activity.

Table Status ‘Failed’

Status Description
Status failed
Description RESOURCE_NOT_FOUND
Notes The system is unable to find the resource the message refers to.

Table Status ‘Failed’

Status Description
Status failed
Description ACTIVITY_NOT_FOUND
Notes The system is unable to find the activity the message refers to.

Table Status ‘Failed’

Status Description
Status failed
Description INACTIVE_RESOURCE
Notes The resource is inactive.

Table Status ‘Failed’

Status Description
Status failed
Description NON_WORKING_DAY
Notes The resource has a non-working day. For example, this error can appear for a not-scheduled activity that cannot be moved to the resource’s current day because it is a non-working day for that resource.

Table Status ‘Failed’

Status Description
Status failed
Description ACTION_ON_PAST
Notes The activity is located in the route for a day in the past that cannot be changed.

Table Status ‘Failed’

Status Description
Status failed
Description MISCONFIGURED_CALENDAR
Notes The system is unable to determine if the resource is working because its calendar is not configured. For example, this error can appear for a not-scheduled activity.

Table Status ‘Failed’

Status Description
Status failed
Description MISCONFIGURED_TIME_ZONE
Notes The system is unable to determine a current time for the resource because its time zone is not configured. For example, this error can appear for a not-scheduled activity.

Table Status ‘Failed’

Status Description
Status failed
Description INVALID_ACTIVITY_STATUS
Notes This action is not supported for an activity with such status. Only pending activities can be canceled.

Table Status ‘Failed’

Status Description
Status failed
Description NON_MOVABLE_ACTIVITY
Notes This type of activity cannot be moved to another resource or a day. For example, this error can appear for a not-scheduled activity.

Table Status ‘Failed’

Status Description
Status failed
Description RESCHEDULE_IS_NOT_ALLOWED
Notes This type of activities cannot be rescheduled to another day. For example, this error can appear for a not-scheduled activity.

Table Status ‘Failed’

Status Description
Status failed
Description NOT_SCHEDULED_IS_NOT_ALLOWED
Notes This type of activities cannot be not-scheduled. For example, this error can appear for a not-scheduled activity.

Table Status ‘Failed’

Status Description
Status failed
Description DEACTIVATED_ROUTE
Notes The route is deactivated. For example, this error can appear for a not-scheduled activity if it cannot be moved to the resource’s route for the current day because this route is deactivated.

Unschedule Activity Actions

The set_property method supports making a pending activity not-scheduled with the unschedule_activity action. Note that the message should contain “unschedule” in the subject, and the name of the action to be performed should be stored in the message body. After processing, the message is assigned one of the following statuses and its corresponding description.

Table Status ‘delivered’

Status Description
Status delivered
Description
Notes The action is performed successfully.

Table Status ‘Failed’

Status Description
Status failed
Description INVALID_RESOURCE_TYPE
Notes This action is not supported for this type of resource. For example, the resource or its type are reconfigured and activities cannot be assigned to it anymore.

Table Status ‘Failed’

Status Description
Status failed
Description NO_PERMISSION
Notes This user does not have access to the specified resource or activity.

Table Status ‘Failed’

Status Description
Status failed
Description RESOURCE_NOT_FOUND
Notes The system is unable to find the resource the message refers to.

Table Status ‘Failed’

Status Description
Status failed
Description ACTIVITY_NOT_FOUND
Notes The system is unable to find the activity the message refers to.

Table Status ‘Failed’

Status Description
Status failed
Description INACTIVE_RESOURCE
Notes The resource is inactive.

Table Status ‘Failed’

Status Description
Status failed
Description ACTION_ON_PAST
Notes The activity is located in a route for a day in the past that cannot be changed.

Table Status ‘Failed’

Status Description
Status failed
Description INVALID_ACTIVITY_STATUS
Notes This action is not supported for an activity with such status. Only pending activities can be unscheduled.

Table Status ‘Failed’

Status Failed
Status failed
Description INVALID_ACTIVITY_STATUS
Notes This action is not supported for an activity with such status. Only pending activities can be unscheduled.

Table Status ‘Failed’

Status Description
Status failed
Description INVALID_ACTIVITY_TYPE
Notes This action is not supported for this type of activity. Only regular and reopened activities can be unscheduled.

Table Status ‘Failed’

Status Description
Status failed
Description NON_MOVABLE_ACTIVITY
Notes This type of activity cannot be moved to another resource or day. For example, this error can appear for a not-scheduled activity.

Table Status ‘Failed’

Status Description
Status failed
Description RESCHEDULE_IS_NOT_ALLOWED
Notes This type of activity cannot be rescheduled to another day. For example, this error can appear for a not-scheduled activity.

Table Status ‘Failed’

Status Description
Status failed
Description NOT_SCHEDULED_IS_NOT_ALLOWED
Notes This type of activity cannot be not-scheduled. For example, this error can appear for a not-scheduled activity.

Setting Properties Using Agent Message Status

Using functionality similar to the set property method, agents can update properties and perform actions without additional scenario steps. All activity and inventory statuses and the predefined set of activity fields can be updated, and activities can be canceled and unscheduled.

This functionality allows:
  • Updating properties based on processing the result of a PAS scenario message and controlling further scenario flow based on these properties

  • Setting the ICOMS result property directly from the ICOMS agent without additional Set Property scenario steps

  • Canceling an activity based on customer selection

The fields to be assigned and the corresponding values are passed in the data field. The #params? string is used as the delimiter between data itself and the passed parameters. The format of the parameter line is similar to URL. The & character is used as the delimiter between different parameters.
data = OK#params?cconfirmed=1&phone=12345678912
data = #params?icoms_eta_status=1
data = DONE#params?pas_requires_feedback=1
data = #params?action=cancel_activity&notes=Rescheduled
Names and values of the parameters are encoded as the URL parameters. So, if the URL property needs to be assigned to http://localhost/v41/wwwroot/?param1=value1&param2=value2, the resulting data value should be as follows:
data = OK#params?CANCEL_REASON=0&URL=http%3A%2F%2Flocalhost%2Fv41%2Fwwwroot%2F%3Fparam1%3Dvalue1%26param2%3Dvalue2

The encoding requires that all non-ASCII and non-alphanumeric characters (with some exceptions) must be represented as hexadecimal values with leading '%'. Exceptions: the '.', ',', '-', '_' characters should be provided as is, and the ' ' (space) symbol is replaced with the '+' (plus).

The total length of the data field is restricted to 255 characters. If a submitted data value exceeds that limit, it can be processed correctly, but it will be truncated.

Status Descriptions for Set_Property Method

Messages processed by the set_property method are assigned a status.

Set Property action details for cancel_activity

In order to invoke an action in the set_property method, the subject field of the message should contain the action word. The name of the action to be performed should be in the body field.

The cancel_activity action cancels a pending activity. If the activity is not scheduled, it is moved to the current resource’s day and then canceled.
Note: This action does not support the notdone and deleted actions depending on activity and route status.

After processing, the message is assigned one of the following statuses.

Table Status ‘Delivered’

Status Description
Status delivered
Description ALREADY_SET
Data
Comments The property is not changed. It is already assigned to the given value.

Table Status ‘Delivered’

Status Description
Status delivered
Description INSERTED
Data
Comments An empty property is assigned to the given value.

Table Status ‘Delivered’

Status Description
Status delivered
Description DELETED
Data
Comments An existing property is assigned to empty.

Table Status ‘Delivered’

Status Description
Status delivered
Description UPDATED
Data
Comments An existing property value is changed.

Table Status ‘Failed’

Status Description
Status failed
Description WRONG_CONFIGURATION
Data Unknown label
Comments The given label of a property/field is not found in the dictionary.

Table Status ‘Failed’

Status Description
Status failed
Description WRONG_CONFIGURATION
Data Not supported entity
Comments An attempt to update a property for an entity that is not supported.

Table Status ‘Failed’

Status Description
Status failed
Description WRONG_CONFIGURATION
Data Not supported field
Comments The given field cannot be updated using this method.

Table Status ‘Failed’

Status Description
Status failed
Description WRONG_CONFIGURATION
Data Parent entity mismatch
Comments The message has no relation to the requested entity.

Table Status ‘Failed’

Status Description
Status failed
Description WRONG_CONFIGURATION
Data Unknown ID of the parent object
Comments The system is unable to find an object by ID retrieved from the message.

Table Status ‘Failed’

Status Description
Status failed
Description WRONG_CONFIGURATION
Data Invalid integer value
Comments The given value of an integer property cannot be converted to signed int32.

Table Status ‘Failed’

Status Description
Status failed
Description WRONG_CONFIGURATION
Data Invalid lookup value
Comments The given value of a lookup property cannot be found in the list of items for this property.

Table Status ‘Failed’

Status Description
Status failed
Description WRONG_CONFIGURATION
Data Invalid value
Comments Surveys: The system is unable to validate the value of a Checkbox or Radiogroup property.

Table Status ‘Failed’

Status Description
Status failed
Description WRONG_CONFIGURATION
Data Missing survey take
Comments Surveys: The system is unable to find a corresponding survey take record the message refers to.

Table Status ‘Failed’

Status Description
Status failed
Description INTERNAL_ERROR
Data Unknown result code
Comments A result of the property update is not handled properly.