Differences

This shows you the differences between two versions of the page.

Link to this comparison view

subscriber_provisioning_api [2014/07/24 19:25]
ybarajas [Create or Update User]
subscriber_provisioning_api [2014/07/24 19:26] (current)
ybarajas [Create or Update User]
Line 1: Line 1:
 +======Hosted User Provisioning======
  
 +Each API consists of a URL and an optional input Payload XML. You may call the URL through any scripting language.
 +
 +As a first step in using the API, the User ID that is setup (per the Prerequisites section below) must be used to invoke the login API. The login API returns a cookie which must be saved by the script and passed into the subsequent API calls.
 +
 +  * This help page includes information on the following:
 +    * [[subscriber_provisioning_api&#prerequisites|Prerequisites]]
 +    * [[subscriber_provisioning_api&#curl_sample_script|cURL Sample Script]]
 +    * [[subscriber_provisioning_api&#api_field_descriptions|API Field Descriptions]]
 +
 +  * And instructions for executing the following actions with an API:
 +    * [[subscriber_provisioning_api&#create_or_update_user|Create or Update User]]
 +    * [[subscriber_provisioning_api&#suspend_user|Suspend User]]
 +    * [[subscriber_provisioning_api&#retrieve_user|Retrieve User]]
 +
 +
 +=====Prerequisites=====
 +
 +  *  A User ID with access to the Open Mobile Portal and a Hosted End User Admin or Delegated Hosted End User Admin role assigned to it. You can confirm that the User ID has one of these roles by logging into the Open Mobile Portal, navigating to **Account** > **Hosted Users**, and creating, suspending, or updating a user.
 +  * The person writing the script and using this API must be well-versed in scripting and familiar with REST and HTTPS. iPass does not support any scripts written by your organization and provides APIs “as-is.” By using the API, you agree to the Terms of Use (pending). 
 +
 +
 +======cURL Sample Script======
 +
 +The cURL based shell script below provides an example of how to use the login API and the returned cookie in a subsequent call. In this example, the suspend API is invoked. 
 +
 +<code>
 +
 +#!/bin/bash 
 +# The BASEURL in this script points to the portal 
 +BASEURL=https://openmobile.ipass.com 
 + 
 +echo Enter the company ID for which you need to invoke the specific API. 
 +read COMPANY 
 + 
 +echo Enter the username. 
 +read USER 
 + 
 +echo Enter password for user $USER. 
 +read -s PASSWORD 
 + 
 +# Login to the portal as a user who has access to the specific API. 
 +curl -k -c tmpCookies.txt "$BASEURL/moservices/rest/api/login?User-Agent=apiuser 
 +&username=$USER&password=$PASSWORD" 
 +# Pass back the cookie returned by the login while invoking the specific API
 +
 +curl -k --request POST -b tmpCookies.txt -o output.xml "$BASEURL/moservices/rest/api/ipass/$COMPANY/mo/endUser?User-Agent=apiuser&action=suspend&id=endUserId
 +
 +rm tmpCookies.txt
 +
 +</code>
 +
 +======API Field Descriptions======
 +
 +
 +^ Field ^ Description ^ Notes ^
 +|**fname**|First name of the user|Mandatory|
 +|**lname**|Last name of the user.|Mandatory|
 +|**email**|Email address of the user.|Mandatory. Must be a valid email address as this will be used for several confirmations about the authenticity of the user.|
 +|**username**|The username that will be registered in the Authentication service. |Mandatory. The username must contain the domain the company is set up with.|
 +|**password**|The password for this user.|**Mandatory** if company's password is user-specified, but **optional** if company's password policy is system-generated.|
 +|**enablePortalLogin**|If specified, must be set to true or false.| Optional. This tag can be omitted. If omitted, the value will default to false. Setting this field to true allows the user to log in to the Open Mobile Portal (openmobile.ipass.com ) and provides access to the dashboard. Access to other functions on the portal may be given later by assigning roles to the user from the Open Mobile Portal.|
 +|**departmentCode**|Can be used to group users into cost-centers or departments.|Optional.|
 +|**startDate**|The datewhen a user registers and enters our system (or is entered).|Read only.|
 +|**homeCountry**|Country where the user is based.| Optional. Helps benchmark how much a user saves by using Open Mobile versus other roaming services. |
 +|**notifications**|Allows the user to subscribe to emails for activation, suspension, and other notifications.|Optional. If this section is omitted, subscribe defaults to true for both Activation and Suspension emails. Allows the user to subscribe to notifications by setting the attribute “subscribe” to true or false, and the parameter “type” to activate, suspend, or any other type of notification.|
 +=====Create or Update User=====
 +
 +**1. Create or Update URL** 
 +
 +//NOTE: You can create or update a user, depending on whether their username already exists in the database. If you are updating a user, the only mandatory field in the XML payload is the username.// 
 +
 +Use the following sample replacing <companyid> with the Company ID that will be using this API: 
 +
 +<code>
 +openmobile.ipass.com/moservices/rest/api/ipass/<companyid>/mo/endUser?action=createOrUpdate 
 +</code>
 +
 +**2. Input XML**
 +
 +<note important>Please adhere to the way lowercase and uppercase text is displayed below as some values are case-sensitive. </note> 
 +
 +The sample below includes the important fields.
 +
 +
 +<code>
 +
 +<endUser> 
 + <fname>Favorite4</fname> 
 + <lname>Subscriber</lname> 
 + <email>subscriber4@subscriptioncompany.com</email> 
 + <homeCountry>Country</homeCountry> 
 + <username>subscriber4@subcomp.com</username> 
 + <password>password</password> 
 + <enablePortalLogin>false</enablePortalLogin> 
 + <departmentCode>Accounting</departmentCode> 
 + <!-- optional notifications section --> 
 + <notifications> 
 + <notification subscribe="true"><type>Activate</type></notification> 
 + <notification subscribe="true"><type>Suspend</type></notification> 
 + </notifications> 
 +</endUser>
 +
 +</code>
 +
 +
 +
 +**3. Response**
 +
 +The system returns an XML in response.
 +
 +<code>
 +
 +<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
 +<endUser> 
 + <authType>HostedAuth</authType> 
 + <company>companyid</company> 
 + <createdBy>0</createdBy> 
 + <createdTime>2013-12-13T23:01:57.751Z</createdTime> 
 + <email>subscriber4@subscriptioncompany.com</email> 
 + <fname>Favorite4</fname> 
 + <isActive>0</isActive> 
 + <lname>Subscriber</lname> 
 + <modifiedBy>0</modifiedBy> 
 + <modifiedTime>2013-12-13T23:01:57.751Z</modifiedTime> 
 + <username>subscriber4@subcomp.com</username> 
 + <departmentCode>Accounting</departmentCode> 
 + <enablePortalLogin>false</enablePortalLogin> 
 + <endUserId>129170</endUserId> 
 + <endUserStatus>Active</endUserStatus> 
 + <homeCountry>Country</homeCountry> 
 + <startDate>MM/DD/YYYY</startDate> 
 + <notifications> 
 + <notification subscribe="true"><type>Activate</type></notification> 
 + <notification subscribe="true"><type>Suspend</type></notification> 
 + </notifications> 
 +</endUser> 
 + 
 +</code>
 +
 +
 +=====Suspend User=====
 +**1. Suspend URL**
 +
 +Use the following URL, replacing the <companyid> with the Company ID using this API: 
 +
 +<code>
 +openmobile.ipass.com/moservices/rest/api/ipass/<companyid>/mo/endUser?action=suspendNow 
 +</code>
 +
 +**2. Input XML**
 +
 +<code>
 +
 +<?xml version="1.0" encoding="UTF-8"?> 
 +<statusChangeRequest> 
 + <endUserCredential> 
 + <companyId>companyid</companyId> 
 + <username>subscriber4@subcomp.com</username> 
 + <email>subscriber4@subscriptioncompany.com</email> 
 + </endUserCredential> 
 +</statusChangeRequest>
 +
 +</code>
 +
 +**3. Reponse**
 +
 +The system should respond with an XML that looks like this:
 +
 +<code>
 +<?xml version="1.0" encoding="UTF-8"?> 
 +<endUser> 
 + <authType>HostedAuth</authType> 
 + <company>companyid</company> 
 + <createdBy>0</createdBy> 
 + <createdTime>2013-12-13T23:01:57.751Z</createdTime> 
 + <email>subscriber4@subscriptioncompany.com</email> 
 + <fname>Favorite4</fname> 
 + <isActive>0</isActive> 
 + <lname>Subscriber4</lname> 
 + <modifiedBy>38328</modifiedBy> 
 + <modifiedTime>2013-12-13T23:21:36.898Z</modifiedTime> 
 + <username>subscriber4@subcomp.com</username> 
 + <departmentCode>Accounting</departmentCode> 
 + <enablePortalLogin>false</enablePortalLogin> 
 + <endUserId>129170</endUserId> 
 + <endUserStatus>Suspended</endUserStatus> 
 + <homeCountry>Country</homeCountry> 
 + <startDate>MM/DD/YYYY</startDate> 
 + <notifications> 
 + <notification subscribe="true"><type>Activate</type></notification> 
 + <notification subscribe="true"><type>Suspend</type></notification> 
 + </notifications> 
 +</endUser> 
 +
 +</code>
 +
 +<note important>If a suspension template has not been configured, the user will not be notified of their suspension, they will simply not be able to connect anymore. </note>
 +
 +=====Retrieve User=====
 +
 +**1. Retrieve URL**
 +
 +<code>
 +openmobile.ipass.com/moservices/rest/api/ipass/<companyid>/mo/endUser/?action=retrieve&uname=enduserapitest1@company.com 
 +</code>
 +
 +**2. Input XML**
 +
 +There is no input XML field.
 +
 +**3. Response**
 +
 +The system should respond with an XML that looks like this:
 +
 +<code>
 +
 +<?xml version="1.0" encoding="UTF-8"?> 
 +<endUser> 
 + <authType>HostedAuth</authType> 
 + <company>companyid</company> 
 + <createdBy>0</createdBy> 
 + <createdTime>2013-12-13T23:01:58Z</createdTime> 
 + <email>subscriber4@subscriptioncompany.com</email> 
 + <fname>Favorite4</fname> 
 + <isActive>0</isActive> 
 + <lname>Subscriber4</lname> 
 + <modifiedBy>38328</modifiedBy> 
 + <modifiedTime>2013-12-13T23:24:02Z</modifiedTime> 
 + <username>subscriber4@subcomp.com</username> 
 + <departmentCode>Accounting</departmentCode> 
 + <enablePortalLogin>false</enablePortalLogin> 
 + <endUserId>129170</endUserId> 
 + <endUserStatus>Suspended</endUserStatus> 
 + <homeCountry>Country</homeCountry> 
 + <startDate>MM/DD/YYYY</startDate> 
 + <notifications> 
 + <notification subscribe="true"><type>Activate</type></notification> 
 + <notification subscribe="true"><type>Suspend</type></notification> 
 + </notifications> 
 +</endUser>
 +
 +</code>
 +
 +======Note on Future Versions======
 +
 +iPass makes its best efforts to keep the API backward compatible. We will minimize any changes to our APIs to avoid disruptions to scripts based on past versions of the API. 
 +
 +
 +Go to: **[[:start|Portal Home]]** > **[[:api_documentation|REST API Overview]]**
 

©2015 iPass Inc. All rights reserved. Terms of Use