AgileApps Support Wiki

REST API:tenant Resource

From AgileApps Support Wiki

Performs actions on Tenant records via the REST API

Access Permissions

Lock-tiny.gif

Users that have the Manage Tenants and Company Capabilities permission can use this REST API resource. 

Retrieve the metadata for a Tenant

Retrieves metadata for a Tenant via the REST API

Method
GET
URI
https://{yourDomain}/networking/rest/tenant/{tenant_id}
Response
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <tenant>
       <id>1479765335</id>
       <object_id>8c5b349851c041a28d19277a12dee8f0</object_id>
       <document_space/>
       <classification/>
       <trial_days/>
       <deleted/>
       <created_id type="" 
           uri="https://{yourDomain}/networking/rest/record/USER/1" 
           displayValue="">1</created_id>
       <owner_id type="" 
           uri="https://{yourDomain}/networking/rest/record/USER/5" 
           displayValue="Admin">5</owner_id>
       <modified_id type="" 
           uri="https://{yourDomain}/networking/rest/record/USER/5" 
           displayValue="Admin">5</modified_id>
       <number>1742261497</number>
       <name/>
       <search_string/>
       <start_date>2010-11-12T13:14:15Z</start_date>
       <payment_type/>
       <license_blocks/>
       <country>United States</country>
       <next_billing_date/>
       <base_subscriber_plan type="" 
           uri="https://{yourDomain}/networking/rest/record/456zzy789jhk/null" 
           displayValue=""/>
       <trial_account/>
       <accessory_purchase_plan type="" 
           uri="https://{yourDomain}/networking/rest/record/456zzy789jhk/null" 
           displayValue=""/>
       <workflow_owners/>
       <data_space/>
       <date_modified>2010-11-12T13:14:15Z</date_modified>
       <company>Greene Services</company>
       <base_subscriber_option type="" 
           uri="https://{yourDomain}/networking/rest/record/456zzy789jhk/null" 
           displayValue=""/>
       <discount/>
       <workflow_state/>
       <active>1</active>
   </tenant>
   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Create a Tenant

Creates a new Tenant

Method
POST
URI
https://{yourDomain}/networking/rest/tenant

Notepad.png

Note: If you want to create a sub-domain tenant, pass the <service_portal_sub_domain> tag in the payload. For example for a sub-domain name "mydomain", pass the tag as <service_portal_sub_domain>mydomain</service_portal_sub_domain>.

Request
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <tenant>
       <company>BSmith Inc</company>
       <name>BSmith Inc</name>
       <email>bsmith@email.com</email>
       <last_name>Bob</last_name>
       <password>password</password>
       <first_name>Smith</first_name>
       <phone>650-555-1212</phone>
       <number_of_users>1</number_of_users>
       <country>United States</country>
       <date_format>mm/dd/yyyy</date_format>
       <time_zone>12</time_zone>
       <street>1230 Midas Way</street>
       <city>Sunnyvale</city>
       <force_password_to_be_changed>0</force_password_to_be_changed>
   </tenant>

</platform> </syntaxhighlight>

<syntaxhighlight lang="xml" enclose="div">

<appList>4949678694fe4ccd9dcdfd9c32c49521, 

        eodf3997d57d4c7bb57f28d4e58d364f</appList>

</syntaxhighlight>

where:
  • Whitespace between the values is ignored
  • The values are package installation IDs -- the values that appear as the id value in the Installation Link part of the Package page.
  • To get the ServiceDesk application and ServiceDesk tenant capabilities, pass the following flag with the request parameters:
<syntaxhighlight lang="xml" enclose="div">

<isCaseDynamics>1</isCaseDynamics> </syntaxhighlight>

Response
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>      
       <id>...</id>    
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Search Tenants

Method
GET
URI
https://{yourDomain}/networking/rest/tenant?{query_parameters}
Sample Search
?fieldList=name,id&filter=name contains 'smith' & sortby='id'
(Field names are in the Fields section.)
Query Parameters
  • fieldList - A comma-separated list of field names to retrieve
  • The asterisk (*) wildcard specifies all fields
  • {fieldname} specifies an individual field (e.g. name)
(Use the REST API:field Resource to get a complete list of fields.)
  • For a Composite Object, specify {alias}.{fieldname} to select a related-record field, where the alias is defined in the Object Relationships.
  • For a Database View, specify {alias}.{fieldname}, where the object alias is defined in the Database View.
  • alias.* specifies all fields in the aliased object.
  • filter - Filtering criteria to filter the records
  • pageSize - Number of records to retrieve from the result set in order to make a "page".
  • page - Number of the logical page in a database result set. The first page is page "zero" (0).
Page zero is returned by default, so appending &pageSize=1 to your query returns a single record.
  • getTotalRecordCount returns the number of total records.
    Causes the following structure to be returned, where N is the total number of records:
<syntaxhighlight lang="xml" enclose="div">

<platform> 

  <status>
  <packageDeploy>
  ...
  </packageDeploy>
  </status>
  <message>
     0
     <description>Success</description>
  </message>

  <totalRecordCount>N</totalRecordCount>

</platform> </syntaxhighlight>

  • sortBy - Field name for primary sort
    Ex: &sortBy=name
  • sortOrder - Sort order of the primary field, either asc or desc (ascending or descending)
    Ex: &sortOrder=desc
  • sortBy2 - Field name for secondary sort
  • sortOrder2 - Sort order of the second field, either asc or desc (ascending or descending)
For more information, see: Specifying Query Parameters in REST APIs

Update a Tenant

Updates Tenant information

Method
PUT
URI
https://{yourDomain}/networking/rest/tenant/{tenant_id}
Request
<syntaxhighlight lang="xml" enclose="div">

<platform> <tenant> 

   <free>1</free>
   <country>India</country>
   <payment_type>Manual</payment_type>

</tenant> </platform> </syntaxhighlight>

Response

<syntaxhighlight lang="xml" enclose="div"> <platform> 

   <message>
       0
       <description>Success</description>        
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Delete a Tenant

Deletes a Tenant, and all related information

Method
DELETE
URI
https://{yourDomain}/networking/rest/tenant/{tenant_id}
Response
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>        
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Fields

Name Type Attributes Required During Add Description Additional Information
company String Checkmark.gif Company Name
service_portal_sub_domain String Sub-domain Name In Configure Service Settings, if Enable Tenant SubDomains is not enabled under Tenant Configuration, then even if this value is passed during tenant creation, it is not taken into consideration. For more information see, [Prefix for Service Domain].
email email Checkmark.gif Email address of the User
first_name String Checkmark.gif User First Name
last_name String Checkmark.gif User Last Name
password String Checkmark.gif Password
time_zone int Checkmark.gif Time zone ID Time Zone Codes
date_format String Date Format
phone String Checkmark.gif User Phone
number_of_users int Number Of Users
document_space int per User document space
object_id String Read Only tenant object id Default: 8c5b349851c041a28d19277a12dee8f0
number int Read Only Tenant Number
deleted Boolean Read Only Designates if the Tenant is active or not
discount percentage Discount for the tenant
created_id String Read Only
data_space int per user data space
classification String Customer classification
owner_id String Read Only
start_date date Read Only registration date UTC Format
country String Checkmark.gif
city String Checkmark.gif
state String
sendWelcomeEmail Boolean Sends a welcome email when set to 1 Default: 0
force_password_change_on_login Boolean Prompts for password reset on first login when set to 1 Default: 1
street String Checkmark.gif
zip String Checkmark.gif
base_subscriber_plan Lookup Tenant's purchase plan URI attribute contains record URL
base_subscriber_option Lookup Tenant's payment plan URI attribute contains record URL
accessory_purchase_plan Lookup Tenant's plan for purchasing additional usage-resources. URI attribute contains record URL
Retrieved from "https://agileappscloud.info/aawiki-src/index.php?title=REST_API:tenant_Resource&oldid=10448"