System Operations

System Account Operations

The web service operations described in this section require System Account privileges. A System Account is a special user account with administrator privileges in the Arrayent Cloud. System Accounts can:

• Create, edit and delete customer accounts
• Configure settings for email, SMS and push notification alerts
• Configure email templates for registration, activation and password recovery emails
• Monitor and control any device and their alerts (see user operations)

General System Operations

systemLogin

Log in to the Arrayent Cloud as a System Account.

Usage

There are two types of user accounts in the Arrayent Cloud: Customer Accounts and System Accounts. Customer Accounts are used to monitor and control individual devices. System Accounts are used to perform administrative tasks, such as configure the cloud, create/delete Customer Accounts, and associate devices to Customer Accounts. systemLogin logs you in to the Arrayent Cloud as a System Account. When you perform the request you provide your System Account username and password as arguments. These credentials are created by Arrayent and distributed to you when your cloud environment is initially set up. If the provided username and password are valid, the Arrayent Cloud will return a security token in the response to your systemLoginrequest. This token serves as your proof of authentication for subsequent requests. For every subsequent web service request you want to make which requires System Account privileges (e.g. createNewUser, getUserByName), you will need to provide this security token as an argument. The security token is valid for 15 minutes. It is refreshed for another 15 minutes every time that you successfully complete a request. The token can be refreshed indefinitely. Protect your System Account credentials! Do not give them to any team members unless necessary. Never hard code them into a mobile application, or the front end component of a web application.

Preconditions

• System Account username and password are valid. Arrayent provides these credentials to you when your cloud environment is initially set up.

Postconditions

Success

• The Arrayent Cloud returns a security token. Provide this token as an argument for every subsequent web service request that you want to make which requires System Account privileges.The security token is valid for 15 minutes. It expires after 15 minutes of inactivity. The security token is refreshed for another 15 minutes every time you successfully complete a request with the token.

Error Code 101: Invalid login name or password The username or password that you provided in the request is invalid.

• Check for typos in the username or password.
• Make sure that you are making the request on the correct environment. E.g. you accidentally provided your development environment System Account credentials on your staging environment.

Parameters

Response

Examples

HTTP

Request:

https://example.arrayent.com:8081/zdk/services/zamapi/systemLogin?
name=sys&password=098gakjga345664687

Response:

<ns1:systemLoginResponse>
 <appId>901</appId>
 <securityToken>8s7rm7ch</securityToken>
</ns1:systemLoginResponse>

Invalid username or password:

<ns1:requestFault>
 <errorCode>101</errorCode>
 <errorMsg>Invalid login name or password.</errorMsg>
</ns1:requestFault>

Python

import requests  # docs.python-requests.org
import xml.etree.ElementTree as element_tree

def print_error(operation_name, xml_root):
    print('{0} failed! Printing error message...'.format(operation_name))
    for element in xml_root:
        print('{0}: {1}'.format(element.tag, element.text))

class System(object):
    def __init__(self, username, password, url):
        self.username = username
        self.password = password
        self.url = url

    def log_in(self):
        try:
            endpoint = '{0}systemLogin'.format(self.url)
            args = {
                'name': self.username,
                'password': self.password,
            }
            response = requests.get(endpoint, params=args)
            root = element_tree.fromstring(response.text)
            self.token = root.find('securityToken').text
            self.app_id = root.find('appId').text
        except AttributeError:
            print_error('systemLogin', root)
            exit()

username = "devkit2165"
password = "password1234"
url = "https://devkit-api.arrayent.com:8081/zdk/services/zamapi/"

system = System(username, password, url)
system.log_in()
print('Security Token: {0}, App ID: {1}'.format(system.token, system.app_id))

User Management Operations

createNewUser

Creates a new Customer Account.

Usage

When an end user signs up to use your service, one of the first things they need to do is create a user account. Your app takes these credentials and uses createNewUser to create a Customer Account on the Arrayent Cloud for this particular user. Username requirements: usernames should be between 6 and 100 characters in length. Letters, numbers, period and underscore may be used. Usernames are case-sensitive. E.g. the usernames FORD.PREFECT, ford.prefect, and Ford.Prefect are all unique and valid. Passwords should be selected by the user. If initial passwords are system-generated then the user must be instructed to change their password upon initial login. Passwords should always be encrypted before being sent to the Arrayent Cloud. Password requirements: Minimum 8 characters, maximum 60 characters (inclusive). Password must contain characters from three of the following four groups: lowercase letters, uppercase letters, numbers, and non-alphanumeric characters in the set (#!$&@). At least 6 of those characters may occur only once in the password.

Postconditions

Success A new customer account has been created in the Arrayent Cloud. The new customer account can now log in to the Arrayent Cloud using userLogin. Error Code 108: Name has already been used in database. A customer account with the username that you provided already exists in the Arrayent Cloud. Usernames must be unique.

Parameters

Response

Examples

HTTP

Request:

https://example.arrayent.com:8081/zdk/services/zamapi/createNewUser?
sysSecToken=8990215490sgfadfg928359082930&name=jane%40email.com&
password=d73b04b0e696b0945283defa3eee4538

Response:

<ns1:createNewUserResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <userId>3759</userId>
</ns1:createNewUserResponse>

Error Code 108: Name has already been used in database:

<ns1:requestFault xmlns:ns1="http://arrayent.com/zamapi/">
 <errorCode>108</errorCode>
 <errorMsg>Name has already been used in database</errorMsg>
</ns1:requestFault>

Error code 108 indicates that an existing customer account is already using the username you provided.

Python

import requests  # docs.python-requests.org
import xml.etree.ElementTree as element_tree

def print_error(operation_name, xml_root):
    print('{0} failed! Printing error message...'.format(operation_name))
    for element in xml_root:
        print('{0}: {1}'.format(element.tag, element.text))

class System(object):
    def __init__(self, username, password, url):
        self.username = username
        self.password = password
        self.url = url

    def log_in(self):
        try:
            endpoint = '{0}systemLogin'.format(self.url)
            args = {
                'name': self.username,
                'password': self.password,
            }
            response = requests.get(endpoint, params=args)
            root = element_tree.fromstring(response.text)
            self.token = root.find('securityToken').text
            self.app_id = root.find('appId').text
        except AttributeError:
            print_error('systemLogin', root)
            exit()

    def create_customer_account(self, username, password):
        try:
            endpoint = '{0}createNewUser'.format(self.url)
            args = {
                'sysSecToken': self.token,
                'name': username,
                'password': password,
            }
            response = requests.get(endpoint, params=args)
            root = element_tree.fromstring(response.text)
            return root.find('userId').text
        except AttributeError:
            print_error('createNewUser', root)
            exit()

username = "devkit2165"
password = "password1234"
url = "https://devkit-api.arrayent.com:8081/zdk/services/zamapi/"
new_user_name = "john@email.com"
new_user_password = "Password5678"

system = System(username, password, url)
system.log_in()
user_id = system.create_customer_account(new_user_name, new_user_password)
print('New customer account successfully created.')
print('User ID: {0}'.format(user_id))

getUserByName

Given a username, retrieves the unique user ID for that user account.

Parameters

Response

Examples

https://example.arrayent.com:8081/zdk/services/zamapi/getUserByName?
sysSecToken=9028359408asdf98adfg38230984grf&name=ford.prefect

<ns1:getUserByNameResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <userID>3759</userID>
</ns1:getUserByNameResponse>

getUserCount

Returns the number of Customer Accounts for a specified application ID.

Parameters

Response

Examples

HTTP

https://example.arrayent.com:8081/zdk/services/zamapi/getUserCount?
sysSecToken=8804-1884249319&appID=2165&userType=all

<ns1:userIntegerResponse
xmlns:ns1="http://arrayent.com/zamapi/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ns1:UserIntegerResponseType">
 <isCancelled>false</isCancelled>
 <isError>false</isError>
 <isDone>true</isDone>
 <response>176532</response>
</ns1:userIntegerResponse>

getUserFromDeviceId

Given a Device ID, retrieves the User ID of the user who owns that device.

Parameters

Response

Examples

https://example.arrayent.com:8081/zdk/services/zamapi/getUserFromDeviceId?
sysSecToken=000-123456789&deviceID=1234

<ns1:userFromDeviceIdResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <userId>819</userId>
</ns1:userFromDeviceIdResponse>

addEmailTemplate

Creates or updates the email template that is sent to Customer Accounts in specific scenarios, such as after self registration (with a code), after a password reset request, or after account activation as a welcome message.

Usage

When uploading an email template in a language other than English, you must POST the HTTP request and escape the foreign language characters. Foreign characters must be represented in extended ASCII code format. See http://www.ascii-code.com/ The email template should include a <meta> tag that specifies UTF-8. E.g.:

<meta http-equiv=Content-Type content="text/html; charset=utf-8">

Preconditions

• The Arrayent Cloud has been configured to send email notifications.

Limitations

• Attachments are not supported.
• Uploading of images is not supported. To insert images into your email template host them on a public location or content distribution network (CDN) and link to the image URL.

Parameters

Response

Examples

https://example.arrayent.com:8081/zdk/services/zamapi/addEmailTemplate?
secToken=31QRdx96&applicationId=1234&notificationStage=WELCOME&
locale=en&fromEmail=welcome%40acme.com&fromName=Acme,%20Inc.&
subject=Welcome&content=Welcome,%20*|USERNAME|*!

A return code of 0 indicates that the email template has been successfully created or updated.

<ns1:addEmailTemplate xmlns:ns1="http://arrayent.com/zamapi/">
 <retCode>0</retCode>
</ns1:addEmailTemplate>

readMobilePhoneConfiguration

Returns the list of mobileAppInfos that have been associated with the appId given for the operatingSystem given.

Parameters

Response

Each mobileAppInfo element will contain the following elements.

updateApplicationConfiguration

Registers device identifier information for a mobile device (an iOS or Android smartphone or tablet) and an associated mobile app, so that the Arrayent Cloud can send push notifications to the mobile app on the mobile device. Note that mobileAppName is optional and that if not used, the original single mobile application per Arrayent Connect Cloud environment will be employed. One of the main purposes of this API is for multiple push notification certificate support. Use system account and this API to upload multiple certificates to the cloud environment. Uploading a certificate only needs to be done once in order to install it on an Arrayent Cloud environment.

Parameters

Response

Device Operations

getDeviceCount

Given a single Device Type, returns the number of devices of that type that exist in the Arrayent Cloud.

Usage

getDeviceCount only counts devices which have been added to user accounts. If you have a large number of devices deployed in the field but not added to any user accounts, these devices will not be included in the getDeviceCount results.

Parameters

Response

Examples

HTTP

https://example.arrayent.com:8081/zdk/services/zamapi/getDeviceCount?
sysSecToken=8804-462427092&deviceType=Test&appID=2165

<ns1:deviceIntegerResponse
xmlns:ns1="http://arrayent.com/zamapi/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="ns1:DeviceIntegerResponseType">
 <isCancelled>false</isCancelled>
 <isError>false</isError>
 <isDone>true</isDone>
 <response>1</response>
</ns1:deviceIntegerResponse>

selectDevicesByType

Given a Device Type, returns a paginated list of all devices of that type.

Parameters

Response

Each entry element contains the following data:

Examples

HTTP

https://example.arrayent.com:8081/zdk/services/zamapi/selectDevicesByType?
sysSecToken=8804-1667714393&appID=2165&deviceType=Test&pageNumber=1&pageSize=10

<ns1:deviceInfoPage xmlns:ns1="http://arrayent.com/zamapi/">
 <entry>
 <devId>184554197</devId>
 <devName>1234500474</devName>
 <typeId>1515</typeId>
 <sleepMode>SHORT</sleepMode>
 <appID>2165</appID>
 <userID>11817</userID>
 </entry>
</ns1:deviceInfoPage>

Note that the response only contains one entry because there was only one device registered for this particular example. If there had been more than 10 devices of this type, then the result would have listed 10 entries (because the request specified to return 10 entries per page). The System Account user could retrieve the next set of entries by calling the following request:

https://example.arrayent.com:8081/zdk/services/zamapi/selectDevicesByType?
sysSecToken=8804-1667714393&appID=2165&deviceType=Test&pageNumber=2&pageSize=10

The key difference here is the argument pageNumber=2.