Data Management API

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 the information to AlertFind. The API does this by acting as an AlertFind administrator, with all 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, or delete 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. Fields are by default null unless explicitly set to a value.

Classes included in the Data Management API include:

• AlertFindDataManagementService
• CustomFieldDetails
• 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.

AlertFindDataManagementService

The AlertFindDataManagementService class includes the following methods:

• createUser
• setUserState
• createBroadcastGroup
• updateBroadcastGroup
• deleteBroadcastGroup
• addMembersToBroadcastGroup
• deleteMembersFromBroadcastGroup
• createEscalationGroup
• updateEscalationGroup
• deleteEscalationGroup
• addMembersToEscalationGroup
• deleteMembersFromEscalationGroup
• updateUser
• deleteUser

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.

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 or user ID 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 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

           InvalidArgumentException;

where groupId 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 group;

    throws PermissionDeniedException,

           InvalidArgumentException,

           NoSuchGroupException,

           NoSuchUserException,

           DuplicateGroupException;

where group 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,

           InvalidArgumentException;

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.

updateUser

The updateUser method takes a user ID and a UserDetails object and updates an existing user's data. User ID must be one of the usernames of an existing user - it's a login ID the user uses to log into the AlertFind system. If no existing user in the system has the given ID, this method throws NoSuchUserException, unless Create on Update option is set in this customer's web services configuration. If Create on update is set, this method tries to create a new user for this customer using the given data.

UserDetails is a representation of the users in our system and contains the fields that will be updated for this user. By setting values to different fields like emailAddress, usernames, devices, timezone, displayName, description etc., and many others in this object, users in the system can be updated. By setting only the fields (in UserDetails) you want to change in the user and ignoring other fields (that is, they are null), you can make selective updates to the user.

There are two kinds of fields in user data (and correspondingly in UserDetails):

• Scalar fields (for example, displayName, description, and emailAddress) that have only one data element.
• Array fields (for example, devices, escalationRules, and usernames) that can have zero, or one or more elements (for example, a user can have four different usernames that he/she can use to log in).

Non-null fields in UserDetails are used to completely rewrite corresponding fields of the user. While this works as expected with scalar fields, the way it works with array fields may be unexpected. Array fields are also completely rewritten to the new value in the request. For example, you may expect that a usernames field with an array of one new username should be added to the existing list of usernames, but its actual effect may be that the user will be left with only one username. The user's original usernames are deleted and only a specific username remains. That is, this API completely rewrites the values even for array fields.

With respect to updating user devices, devices field is an array of DeviceDetails objects where, each object contains information to create or update one device. Similar to the UserDetails object, any field ignored (value set to null) is left unchanged in the device, with an exception of address and type fields. type field must be set for each device entry, else it leads to an exception. If the address field is set to an empty string or null, the device is left unchanged, even if other fields are set.

The syntax of the updateUser method is:

public void updateUser(

    string userId,

    string user

) throws PermissionDeniedException,

         NoSuchUserException,

         InvalidArgumentException,

         DuplicateUserException;

where:

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

For more information on the definition of users, see the UserDetails class.

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;      

where:

• userId is the user name or user ID of the user you want to delete.

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 enabled;

    string properties;

}

where:

• name is the name of the device.
• type is the type of device and is a required field. Possible device types are:
• phone
• pager
• sms
• 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
• sms
• fax
• For email devices, this works with a email address string; for example, jdoe@genericorp.com
• Address can be set to empty string or null to make the API ignore this device. This is used to keep the user device(s) unchanged.
• 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.

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:

class EscalationDetails {

    string name;

    EscalationStep[ ] steps;

}

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;

    anyType[ ] deviceIdsToNotUpdate

    DeviceDetails[ ] devices;

    string displayName;

    string emailAddress;

    boolean enabled;

    EscalationDetails[ ] escalations;

    string externalKey;

    string 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.
• deviceIdsToNotUpdate is an array of device IDs, which should not be updated.
• description is the description string that should be displayed.
• Devices is an array of device definitions defined by the called DeviceDetails class. If Devices is unset (that is, it is null), then the user's devices are not updated by this call. However, if Devices is not null and if any of the existing devices are missing from this array, then those missing devices are deleted. To update only some devices and ignore the rest, include all devices in the Devices array and set addresses to blank or null for those devices you want to ignore.
• 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.
• 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.

• 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.

• 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 five 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:ssTZDwhere:
• 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), or the TZD format described here: http://java.sun.com/j2se/1.4.2/docs/api/java/util/TimeZone.html.