Customer Endpoint

1. Create Customer

 createCustomer (String username, String emailAddress, String firstname, String lastname, HashMap fieldValues)

Parameters

  • username Username for this new account
  • emailAddress Email Address for this user
  • firstname First Name for this user
  • lastname Last Name for this user
  • fieldValues HashMap of field values to populate this new account with

Description

Use this function to create a new Customer in HEAT LiveTime. Enter into the function, a unique Username, Email Address, First Name and Last Name for the Customer.

All four arguments are required (username, emailAddress, firstname and lastname). Omitting any of these will result in a failure message explaining the cause.

If the Create Account option is enabled in the application’s setup, this function does not require the User to be logged in.

The function returns a HashMap containing two fields: ‘success’ and ‘message’. The value returned in the ‘success’ field will be a string representation of a boolean (‘true’ or ‘false’) indicating whether or not the Customer creation attempt was successful.

If the Customer has been created successfully, (i.e. the ‘success’ field is ‘true’), the value returned in the message field will be a String representation of the new Customer’s ID number.

Note the returned customer number for subsequent web service requests.

2. Find Customer

 findCustomer (String emailAddress)
 findCustomer (String firstname, String lastname)
 findCustomer (String emailAddress, String firstname, String lastname)
 findCustomer (String username, String emailAddress, String firstname, String lastname,HashMap customFields)
 [/colored_box]

Parameters

  • username Username for this search. The Username can be either an LDAP Username or a System Username, when using the HEAT LiveTime built-in authentication.
  • emailAddress Email Address for this search
  • firstname First Name of user to search for
  • lastname Last Name of user to search for
  • customFields HashMap of field values to locate this customer

Description

Use any of these functions to search for a Customer.

The function returns a HashMap which contains another HashMap for each entry. The key of the first map is the Customer ID of the returned user, the HashMap for that entry contains four string fields representing the Customer’s Last Name, Org Unit, Primary E-mail Address and First Name. A null is permitted when using multiple parameter based functions.

Example

function findUser($username,$email,$first,$last) {
    global $objClient;
    global $baseService;

    //switch to the customer api
    $objClient->SoapClient($baseService . "Customer?wsdl", array('trace' => true));

    echo "Searching for " . $username . $email . $first . $last . "\n";

    # Call findCustomer, using an email address and echo out response
    # username, email, first, last
    $results = $objClient->findCustomer($username,$email,$first,$last);

    $success = $results['success'];
    if ($success=="false") {
        echo $results['message'] . "\n";
        return;
    }

    # if we have results lets show them
    # returns an array of arrays
    foreach(array_values($results) as $ess) {
        print_r($ess);
    }
}

3. Delete Customer

 deleteCustomerById (String customerId)
 deleteCustomerByUsername (String username)

Parameters

  • customerId The unique Customer ID of the account
  • username The unique Username of the account

Description

Use these functions to delete a Customer. The Customer ID or username is required and the account will be locked out if the request is successful.

Either function returns a HashMap containing the success flag and a message if the request was unsuccessful.

4. Undelete Customer

undeleteCustomerById (String customerId)
undeleteCustomerByUsername (String username)

Parameters

  • customerId The unique Customer ID of the account
  • username The unique Username of the account

Description

Use these functions to undelete a customer. The Customer ID or username is required and the account will be re- activated if the request is successful.

This function returns a HashMap containing the success flag and a message if the request was unsuccessful.

5. Get Customer Fields

getFieldsForCustomer (String customerId)

Parameters

  • customerId The unique Customer ID of the account

Description

This is essentially a ‘get customer details’ function, which returns the Customer details to the logged in user, based on the supplied Customer ID. The returned HashMap contains a dozen fields that the system knows about the user (assuming they have been populated). First Name, Last Name, Username and contact information are all returned, as are the custom fields.

Note that phone2 refers to the mobile/cell phone number in the HEAT LiveTime user interface, and phone3 refers to the fax number as defined in the GUI.

Custom Fields are defined in the administration area of HEAT LiveTime. When retrieving these fields, they will be returned with the label defined in the custom field, but when calling update methods, these must be passed using the underlying variable name, being custom1 through custom5.

6. Get Countries

 getCountries () (since 6.0.1)

Description

Use this function to return a list of all the Countries. The function returns a HashMap which contains another HashMap for each entry. The key of the first map is the Country ID of the returned Country, the Map for that entry contains two string fields representing the Country Name and Top Level Domain (TLD).

7. Get States For a Country

 getStatesForCountry (String countryId)

Parameters

  • countryId The unique Country ID.

Description

Use this function to search for states or provinces of a Country. Country ID is required. Returns a HashMap containing the State ID and the State Name for each State of the searching Country.

8. Find Country

 findCountry (String countryName, String tld) (since 6.0.1)

Parameters

  • countryName The unique Country Name to use for the search.
  • tld The unique Top Level Domain to use for the search.

Description

Use this function to search for a Country, based on either the Country Name or Top Level Domain. Returns a HashMap containing another HashMap for the Country. The key of the first map is the Country ID of the returned Country, the Map for that entry contains two string fields representing the Country Name and Top Level Domain.

9. Update Customer

 updateCustomerById (String customerId, HashMap values)
 updateCustomerByUsername (String username, HashMap values)

Parameters

  • customerId The unique Customer ID of the account.
  • username The unique Username of this account.
  • values A HashMap of values to set for this Customer.

Description

These methods allows logged in users to update Customer information. The fields returned from the ‘get’ equivalent (firstname, lastname, email, address, city, state, etc) can all be inserted into the HashMap that is sent to HEAT LiveTime to set new values for those fields.

The returned HashMap will contain success and message values.

The values HashMap is a map of Strings to Strings. Valid keys for Customer web services are the same as those returned in the getFieldsForCustomer method, specifically: firstName, lastName, userName, password, email, orgUnit, address, addressTwo, city, state, country, postalCode, phone, phone2, phone3, webAccess, aliases, emailNotify.

All values should be strings, webAccess and emailNotify should be a 1 or a 0 expressed as a String, and aliases can be a comma-separated list.

10. Update Location

 updateLocation (String latitude, String longitude) (since 6.1.1)

Parameters

  • latitude The geographical latitude coordinate of the logged in account.
  • longitude The geographical longitude coordinate of the logged in account.

Description

This method allows logged in users to update their geographical coordinates by specifying latitude and longitude values.

11. Get Geo Location

 getGeoLocation (String customerId) (since 6.1.4)

Parameters

  • customerId The unique Customer ID of the account.

Description

This method retrieves the geo location for the given Customer ID.