The AppArmor Subscribers API is a SOAP-based web service that allows programmatic access to user profiles and their subscriptions to the available mechanism groups. The API can be used by qualified developers to create integrations between third party systems and the AppArmor platform.
Please note that the API must be used by a qualified developer. AppArmor does not provide software development training, nor does our team know the details of implementing the API in all programming environments. Our support team is able to provide general support and troubleshooting help for the API, but they will be unable to assist with the unique implementation details of your systems. For these reasons, the API should only be used when no other alternative is available, as it is generally best to use the core AppArmor functionality whenever possible.
API Key
Access to the API requires a unique “API Key” provided by AppArmor. The API Key is a randomized 40-character string of text that is used as a parameter to all API requests. Please contact AppArmor Support, or your AppArmor representative for information about licensing and obtaining an API Key.
Service Definition
Each client has a unique hostname associated with their AppArmor Dashboard account. The Subscribers API is accessed by appending the path “/API/Subscribers/Subscribers.asmx” to the Dashboard url. For instance, if your AppArmor Dashboard URL is clientname.apparmor.com, then the API can be accessed at the following URL:
https://clientname.apparmor.com/API/Subscribers/Subscribers.asmx
Visiting the service definition URL in a browser will display a list of the available functions along with detailed documentation for each.
WSDL
Many programming environments support consuming WSDL to create a “proxy class”. This process greatly simplified implementation of the API because the proxy class allows easy single line interactions with the API, rather than needing to manually compose XML requests, and manually parse XML responses. The WSDL metadata can be accessed by appending “?WSDL” to the Service Definition URL:
https://clientname.apparmor.com/API/Subscribers/Subscribers.asmx?WSDL
General User Flow
Generally speaking, the API is used to create a “user profile” interface that allows users to update their profile, and adjust subscriptions. Developers will typically implement the API following the following type of flow:
User signs in
User profile is retrieved using GetUser(), GetUserByEmail(), or GetUserBySSOID()
The user profile is formatted and displayed on-screen
Changes to the user profile fields are created by calling the UpdateField() function
Changes to subscriptions are created using CreateSubscription() or DeleteSubscription()
Once changes are complete, the user profile is retrieved again using GetUser(), GetUserByEmail(), or GetUserBySSOID() and displayed on-screen.
Our API was designed with primitive values as inputs and outputs to simplify implementation. The only exception is the User object returned by GetUser(), GetUserByEmail(), or GetUserBySSOID(). This was done by design to limit the “chatty-ness” of the API requests, and avoid the developer from having to construct complex objects as inputs.
Dashboard Configuration
Before implementing the API, we strongly encourage completing the Dashboard Configuration of your system. Specifically, it is very important that:
All necessary “User Fields” are created in advance as those are required to store the user profile and contact information.
All the mechanism groups for Email, SMS Text Messages, and Voice Call are created in advance as they are needed to create subscriptions.
If changes are made to the User Fields or mechanism groups, then your API integration will need to be updated.
User Fields
User fields are created and managed by signing into your AppArmor Dashboard, then click “Communications” → “Users” → “Manage User Fields”. Use this page to create appropriate user profile fields to store information about your users.
Be sure to make a note of the list of “Variable Names” listed on the page. These will be needed as inputs to the API functions.
If a field is to be used as part of a subscription, be sure to flag it’s “capabilities” appropriately as either Email, Voice, SMS, or Voice and SMS. Without appropriate capabilities selected, the field cannot be used for a subscription to a mechanism group.
Mechanism Groups
Mechanism groups act as subscription options for the user. Through the API, you are able to subscribe the user’s contact information fields. It is important that the mechanism groups for Email, Voice and SMS are created in advance because the “Group Code” values are needed as inputs to the API. Mechanism Groups can be created by signing into the AppArmor Dashboard and going to “Communications” → “Alerting Mechanisms” → Choose either “Email”, “SMS”, or “Voice” → “Groups” tab.
Retrieving a User Profile
There are three functions available through the API to retrieve a user profile, each with a different identifier:
GetUser() - Requires an AppArmor “UserID” input parameter
GetUserByEmail() - Requires the user’s login email address as input parameter
GetUserBySSOID() - Requires the user’s single-sign-on (SSO) identifier as input parameter
The AppArmor “UserID” is a hashed alphanumeric identifier that is included as part of the User object that is returned from a successful request to the above functions. Interactions with the other API functions will require the “UserID” as a parameter, so be sure to keep this value once retrieved.
A sample XML User object is below:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<GetUserByEmailResponse xmlns="https://apparmor.com/API/">
<GetUserByEmailResult>
<UserID>X1X2X3X5X6X7</UserID>
<Username>user@email.com</Username>
<FirstName>Jane</FirstName>
<LastName>Smith</LastName>
<SSOID>jsmith</SSOID>
<Fields>
<Field>
<Name>First Name</Name>
<VariableName>firstname</VariableName>
<Type>TEXT</Type>
<Capabilities>NONE</Capabilities>
<Required>true</Required>
<ValidationExpression />
<Subscriptions />
<Value>Jane</Value>
<ModifiedDate>2020-06-03T13:13:59</ModifiedDate>
</Field>
<Field>
<Name>Last Name</Name>
<VariableName>lastname</VariableName>
<Type>TEXT</Type>
<Capabilities>NONE</Capabilities>
<Required>true</Required>
<ValidationExpression />
<Subscriptions />
<Value>Smith</Value>
<ModifiedDate>2020-06-03T13:13:59</ModifiedDate>
</Field>
<Field>
<Name>Alternate Email</Name>
<VariableName>alternateemail</VariableName>
<Type>TEXT</Type>
<Capabilities>EMAIL</Capabilities>
<Required>true</Required>
<ValidationExpression>^\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*$</ValidationExpression>
<Subscriptions>
<Subscription>
<SubscriptionID>46R24EP8ZYEG</SubscriptionID>
<Type>EMAIL</Type>
<GroupCode>everyone</GroupCode>
<ModifiedDate>2020-06-02T15:59:01</ModifiedDate>
</Subscription>
<Subscription>
<SubscriptionID>12HDF68KJDH1</SubscriptionID>
<Type>EMAIL</Type>
<GroupCode>faculty</GroupCode>
<ModifiedDate>2020-06-02T15:59:01</ModifiedDate>
</Subscription>
</Subscriptions>
<Value>user@altemail.com</Value>
<ModifiedDate>2020-06-03T13:14:00</ModifiedDate>
</Field>
<Field>
<Name>Mobile Phone</Name>
<VariableName>mobilephone</VariableName>
<Type>TEXT</Type>
<Capabilities>VOICEANDSMS</Capabilities>
<Required>true</Required>
<ValidationExpression>\(?\d{3}\)?-? *\d{3}-? *-?\d{4}</ValidationExpression>
<Subscriptions>
<Subscription>
<SubscriptionID>56R24EP8ZYEG</SubscriptionID>
<Type>VOICE</Type>
<GroupCode>everyone</GroupCode>
<ModifiedDate>2020-06-02T15:59:01</ModifiedDate>
</Subscription>
<Subscription>
<SubscriptionID>18HDF68KJDH1</SubscriptionID>
<Type>SMS</Type>
<GroupCode>everyone</GroupCode>
<ModifiedDate>2020-06-02T15:59:01</ModifiedDate>
</Subscription>
</Subscriptions>
<Value>647-992-7919</Value>
<ModifiedDate>2020-06-03T13:14:00</ModifiedDate>
</Field>
<Field>
<Name>Home Phone</Name>
<VariableName>homephone</VariableName>
<Type>TEXT</Type>
<Capabilities>VOICE</Capabilities>
<Required>true</Required>
<ValidationExpression>\(?\d{3}\)?-? *\d{3}-? *-?\d{4}</ValidationExpression>
<Subscriptions />
<Value>647-992-7919</Value>
<ModifiedDate>2020-06-03T13:14:00</ModifiedDate>
</Field>
<Field>
<Name>Allergies</Name>
<VariableName>allergies</VariableName>
<Type>TEXT</Type>
<Capabilities>NONE</Capabilities>
<Required>false</Required>
<ValidationExpression />
<Subscriptions />
<Value>Peanuts</Value>
<ModifiedDate>2020-06-03T13:14:00</ModifiedDate>
</Field>
</Fields>
</GetUserByEmailResult>
</GetUserByEmailResponse>
</soap:Body>
</soap:Envelope>
Updating User Field Values
User fields are used to store information about users. When a change is required to a user field value, the UpdateField() function should be used. Parameters to this function include the “UserID” which is obtained from the user object, the variablename, and the new value.
Changes to a user field value will also automatically update any subscriptions to use the new value.
Adding a Subscription
When adding a subscription, the CreateSubscription() function will be used. The function requires the UserID obtained from the User object, the VariableName of the field that contains the contact information (e.g. email address, voice phone number, or SMS phone number) and the GroupCode of the mechanism group that the user should be subscribed to.
SendSMS and SendEmail Functions
The SendSMS() and SendEmail() functions allow validation that an email address or phone number is owned by the user. These functions can be used to send a verification code to the user. The implementation of the verification code functionality is left up to the developer using the API.
Other Functions
The remaining functions in the API are relatively straight forward. You are encouraged to view the documentation in the Service Definition for details of those functions.
Exceptions
When an error occurs, and exception object is returned. The exceptions for each function are listed in the Service Definition. Below is a sample XML Exception showing a “User not found” response:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<soap:Fault>
<soap:Code>
<soap:Value>soap:Receiver</soap:Value>
</soap:Code>
<soap:Reason>
<soap:Text xml:lang="en">Server was unable to process request. ---> User not found</soap:Text>
</soap:Reason>
<soap:Detail />
</soap:Fault>
</soap:Body>
</soap:Envelope>
The developer is expected to handle exceptions with their implementation of the API.