Overview

The Data Management API (application programming interface) is one of two available AlertFind APIs in AlertFind. To use the APIs, the feature must be enabled in your company's settings which can be requested by contacting Support. In order to utilize these APIs you should understand object-oriented programming and web services. 

Information

The AlertFind Data Management API provides alternative methods for creating and modifying user information. If you maintain the user information in a separate database, the Data Management API can programmatically propagate that information to AlertFind. The API does this by acting as an AlertFind administrator, with all of the administrator permissions defined in your company settings.

The Data Management API enables you to:

• Create users
• Update user information
• Change user status
• Delete users
• Update users' notification device information.
• Update users' personal escalations.
• Assign users to groups.

Designed around a Create/Update/Delete (CRUD) model, with an additional method for enabling and disabling users, the user management API uses nulls in objects to represent data that you do not want to modify.

Classes included in the data management API include:

• AlertFindDataManagement
• DeviceDetails
• EscalationDetails
• EscalationStep
• UserDetails

Authentication

AlertFind uses HTTP basic authentication and the HTTPS protocol for all transactions. If authentication fails, permission is denied and an appropriate message appears.

AlertFindDataManagement

The AlertFindDataManagement class includes the following methods:

• createUser
• updateUser
• deleteUser
• setUserState

createUser

The createUser method creates a new user in AlertFind. For this call to be successful, it must populate all required fields in the user profile.

The syntax of the createUser method is:

public void createUser(

UserDetails user

) throws PermissionDeniedException,

DuplicateUserException,

InvalidArgumentException;

where:

• user provides the details of the user you want to create

updateUser

The updateUser method modifies fields in an existing user's profile. Any fields you leave null are unchanged; therefore you only update the information that requires changing. For example, if devices require no change, leave the devices array null.

You rename the user by specifying a different set of user ids (user names or external keys) in the details from the parameter in the call.

The syntax of the updateUser method is:

public void updateUser(

String userId,

UserDetails user

) throws PermissionDeniedException,

NoSuchUserException,

InvalidArgumentException,

DuplicateUserException;

where:

• userId is the user name/user ID of the user you want to modify
• user provides the changes you want made to the user details

NOTE Updating a Nonexistent User If you try to update a user that does not exist, the method throws a NoSuchUserException. If you use the €œCreate on Update€� web services feature, you can create a new user using this method.

deleteUser

The deleteUser method deletes an existing user from AlertFind. The syntax of the deleteUser method is:

public void deleteUser(

String userId

) throws PermissionDeniedException

NoSuchUserException,

InvalidArgumentException,

DuplicateUserException;

where:

• userID is the user name/user ID of the user you want to delete.

setUserState  

The setUserState method enables or disables an existing user. Disabled users cannot log in to AlertFind or receive notifications.

The syntax of the setUserState method is:

public void setUserState(

String userId,

boolean enabled

) throws PermissionDeniedException,

NoSuchUserException;

where:

• userID is the user name/userid of the user you want to enable or disable.
• enabled is set to true to enable the user; it is set to false to disable a user.

createBroadcastGroup

This method creates a new broadcast group in the system. All fields marked as required must be populated for this call to be successful. The broadcastGroupDetails name uniquely identifies this group if it should need to be modified or deleted later.

The syntax of the createBroadcastGroup method is:

public void createBroadcastGroup(

String group,

) throws PermissionDeniedException,

InvalidArgumentException,

NoSuchGroupException,

NoSuchUserException,

DuplicateGroupException;

where:

• group is the name of the broadcast group you want to create.

updateBroadcastGroup

Use this method to modify fields of an existing broadcast group. The syntax of the updateBroadcastGroup method is:

public void updateBroadcastGroup(

String groupId;

String group;

)throws PermissionDeniedException,

NoSuchUserException,

NoSuchGroupException,

InvalidArgumentException,

DuplicateGroupException;

where:

• groupID is the name of the broadcast group you want to update
• group contains the details to modify

deleteBroadcastGroup

Use this method to delete a broadcast group.

The syntax of the deleteBroadcastGroup method is:

public void deleteBroadcastGroup(

String groupId;

throws PermissionDeniedException,

NoSuchGroupException;

where:

• group ID is the name of the broadcast group you want to delete

addMembersToBroadcastGroup

Use this method to incrementally add members to a broadcast group.

The syntax of the addMembersToBroadcastGroup method is:

public void addMembersToBroadcastGroup(

String groupId;

String members;

throws PermissionDeniedException,

NoSuchGroupException,

InvalidArgumentException,

NoSuchUserException;

where:

• groupId is the name of the group to which you want to add members
• members are the names you want to add to the group

deleteMembersFromBroadcastGroup

This method incrementally removes members from a broadcast group. It is typically used when a set of users or groups change and all that is required is the exclusion of certain members.

The syntax of the deleteMembersFromBroadcastGroup method is:

public void deleteMembersFromBroadcastGroup(

String groupId;

String members;

throws NoSuchGroupException,

InvalidArgumentException,

NoSuchUserException,

PermissionDeniedException;

where:

• groupId is the name of the group from which you want to remove members.
• members are the names you want to remove from the group.

createEscalationGroup

Use this method to create a new escalation group in AlertFind. All required fields must be completed for this call to be successful. The name uniquely identifies the group to be created. If a group with the name you use already exists, an error occurs.

The syntax of the createEscalationGroup method is:

pubic void createEscalationGroup(

String groupId;

throws PermissionDeniedException,

InvalidArgumentException,

NoSuchGroupException,

NoSuchUserException,

DuplicateGroupException;

where:

• groupId is the name of the escalation group you want to create.
• updateEscalationGroup This method modifies fields of an existing escalation group. Fields in the details objects that are left null are not modified. For example, if you do not need to modify members, leave the members array null.

To rename the group, specify the new group name in the details from the parameter call. The syntax of the updateEscalationGroup method is:

public void updateEscalationGroup(

String groupId;

String group;

throws PermissionDeniedException,

NoSuchUserException,

NoSuchGroupException,

InvalidArgumentException,

DuplicateGroupException;

where:

• groupId is the name of the escalation group that you want to update
• group contains the details to be modified

deleteEscalationGroup

This method deletes a specified escalation group from AlertFind.

The syntax of the deleteEscalationGroup method is:

public void deleteEscalationGroup(

String groupId;

throws PermissionDeniedException,

NoSuchGroupException;

where:

• groupId is the name of the escalation group you want to delete

addMembersToEscalationGroup

This method incrementally adds members to an escalation group. The syntax of the addMembersToEscalationGroup method is:

public void addMembersToBroadcastGroup(

string groupId;

String members;

throws PermissionDeniedException,

NoSuchGroupException;

InvalidArgumentException,

NoSuchUserException;

where:

• groupId is the name of the escalation group to which you want to add members
• members are the names you want to add to the group.

CustomFieldDetails

The CustomFieldDetails class defines the name, value pairs used to set a single user's Custom Field. Each device is owned by a single user and has a unique name. Your company settings specify the Custom Field names used for all users.

The syntax of the CustomFieldDetails class is:

class CustomFieldDetails {

String name;

String value;

}

where:

• name is the name of the custom field property
• value is the value to be assigned to the custom field property

To set more than one CustomField for a user, you must create an array of CustomFieldDetails and set the UserDetails.customFields member using the setCustomFields method.

Device Details

The DeviceDetails class defines the name, type, and address information for devices owned by AlertFind users. Each device is owned by a single user and has a unique name. Your company settings specify common device names that exist as defaults for all users.

The syntax of the DeviceDetails class is:

class DeviceDetails {

String name;

String type;

String address;

String description;

Boolean enables;

String properties;

}

where:

• name is the name of the device.
• type is the type of device, such as:
  • phone
  • pager
  • smsphone
  • fax
• address is the address (email, phone number) of the device:
  • For phone devices, this works with the phone number, beginning with the country code (if one is needed).
  • Possible types of phone devices include:
    • phone
    • pager
    • smsphone
    • fax
  • For email devices, this works with a email address string; for example, username@example.com
• description is user-supplied description of the device
• enabled is the device's status
• properties is the array containing the special properties for the device

NOTE Regarding special device properties  You should contact the AlertFind Support Team to identify exactly what should be included in the property field for each device.

EscalationDetails

The EscalationDetails class represents a named list of escalation steps for an AlertFind user. Each escalation is owned by a single user and must match one of the unique escalation labels defined in the company settings.

Syntax of the EscalationDetails class is:

classEscalationDetails {

String name;

EscalationSteps;

}

where:

• name is one of the escalation labels defined in the company settings
• steps is the array EscalationStep

EscalationStep

The EscalationStep class defines the individual steps in an escalation. Each object can be owned by only one escalation.

Syntax of the EscalationStep class is:

class EscalationStep {

String deviceName;

Long timeout;

}

where:

• deviceName is the name of the device to which AlertFind sends the notification in this step of the escalation. The deviceName can be one of the default devices or a custom device defined in the user's profile
• timeout is the time in minutes

UserDetails

The UserDetails class defines the parameters of a user's profile.

Syntax of the UserDetails class is:

class UserDetails {

String BusinessHoursEnd;

String BusinessHoursStart;

String defaultHotlinePhoneNumberLabel;

String description;

DeviceDetails[ ] Devices;

String displayName;

String emailAddress;

Boolean enabled;

EscalationDetails[ ] escalations;

String externalKey;

String Add ivrLabel;

String password; String pin;

String timezone;

String[ ] usernames;

String weekendDays;

CustomFieldDetails[] customFields;

}

where:

• businessHoursEnd can be:
  • Null, which sets the time to the default standard business end time defined in the company settings.
  • A time of day in the format HH:MM where:
• HH is the hour (00-24).
• MM is the minutes, in 15 minute increments (00, 15, 30, 45).
• businessHoursStart can be:
  • Null, which sets the time to the default standard business start time defined in the company settings.
  • A time of day in the format HH:MM where:
• HH is the hour (00-24).
• MM is the minutes, in 15 minute increments (00, 15, 30, 45).
• defaultHotlinePhoneNumberLabel allows assignment of an IVR number to a user.
• description is the description string that should be displayed.
• Devices is an array of device definitions (at least 1 required) defined by the called DeviceDetails class.
• displayName is the user's name.
• emailAddress is the primary email address for the specified user.
• enabled is the status to which you want to set this user. Null defaults to true = enabled.
• escalations is the escalation information array defined by the called EscalationDetails class. If null, the default company settings are used.
• externalKey is the arbitrary external key. If no key is required, set this to null.
• Add ivrLabel allows assignment of an IVR number to a user.
• password is the user's password. When set to null, the default password set in the company settings is used.

NOTE Null Password After you have set the default password to anything other than null you cannot change it back to null.

• pin is the PIN or other employee code (4 to 10 digit number) used by your organization to authorize receipt of authenticated messages. When set to null, the default PIN set in the company settings is used.
• timezone is the time zone of the user's geographical location, specified in the format TimeZone.getTimeZone(String). When set to null the default defined in the company settings is used.

NOTE Format for Time Zone Available time zones are shown in the AlertFind UI. The format is region/city (for example, America/Chicago). These time zones take daylight savings time into consideration.

• usernames is the array of user names associated with this user.
• weekendDays is the set of nonworking days defined using a consecutive string of digits where:
  • 1 = Sunday
  • 2 = Monday
  • 3 = Tuesday
  • 4 = Wednesday
  • 5 = Thursday
  • 6 = Friday
  • 7 = Saturday
• For example, 17 indicates weekend days of Sunday and Saturday.
  • Null uses the default weekend days specified in the company settings.
  • customFields is an array of CustomFieldDetails name-value pairs used to set a user's custom fields. When this field is updated, Smart Teams will begin recalculating user membership 5 minutes after the last update has occurred, and will be postponed 5 minutes more for as long as updates are occurring.

When a custom field is mapped from a string to a date, use this format, which is a variant of ISO-8601. All fields are required, and there can be no spaces between fields.

YYYY-MM-DDThh:mm:ssTZD

where:

YYYY is the four-digit year.

MM is the two-digit month (01=January, and so on).

DD is the two-digit day of month (01 through 31).

hh is the two-digit hour (00 through 23). Do not use AM or PM.

mm is the two-digit minute (00 through 59).

ss is the two-digits second (00 through 59).

TZD is the time zone designator (Z, +hh:mm, or -hh:mm)