Provisioning Status |
Atria UI Status (colour) |
Atria API Status |
Not provisioned |
Grey |
NotProvisioned |
Provisioning requested |
Yellow |
Requested |
Provisioning in progress |
Orange |
InProgress |
Provisioned |
Green |
Provisioned |
Provisioning failed |
Red |
Failed |
Pending Changes |
Blue |
Pending |
<?xml version="1.0" encoding="utf-8" ?> <response version="1.0" /> |
The following XML defines the request structure:
<?xml version="1.0" encoding="utf-8"?> <request version="1.0" action="x"> …entity… </request> |
The layout of requests follows a similar pattern for every action. Here’s an example to get a customer:
<?xml version="1.0" encoding="utf-8"?> |
The action attribute on the request tag determines the action that is executed. Since we want detailed information, we set it to GET. The name tag in the customer tag expects the customer short name.
Error code |
Description |
400 |
Invalid Request (Action specified was invalid, or the request format was invalid): Resending the request will always fail. |
401 |
Unauthorized Access: The credentials used do not have the authorization to perform the action. |
500 |
Request could not be processed: Resending the request may work at some time in the future. |
There are three main response types: Find, Get, and Set / Delete.
<?xml version="1.0" encoding="utf-8" ?> <response version="1.0"> <customer> . . </customer> </response> |
If the action returns the following response, it means the requested customer information is not found. A possible reason may be that the customer is not in the system.
<?xml version="1.0" encoding="utf-8" ?> <response version="1.0" /> |
The Get action returns all information it can about the entities you specify in the request.
<?xml version="1.0" encoding="utf-8" ?> <response version="1.0"> <customer> . . </customer> </response> |
If all the specified entities cannot be found, then the action returns an error message stating what could not be found.
<?xml version="1.0" encoding="utf-8" ?> <response version="1.0"> <error> <id>###</id> <message>Customer ‘BAC’ not found.</message> </error> </response> |
A successful Set or Delete command returns the following response:
<?xml version="1.0" encoding="utf-8"?> <response version="1.0"> <request> <id>14452</id> </request> </response> |
If the following response is returned, then you need to refer to the error message to find out why the requested action could not be completed.
<?xml version="1.0" encoding="utf-8"?> <response version="1.0"> <error> <id>###</id> <message>Text of error message</message> </error> </response> |
Step 1: Check whether or not the customer name you want to use is already taken by another customer. For this, use the Find command.
<?xml version="1.0" encoding="utf-8"?> <request version="1.0" action="FIND"> <customer> <fullname>Basic API Customer</fullname> </customer> </request> |
The Action attribute on the Request tag is set to FIND. Since we want to know whether or not the customer’s Fullname attribute exists, we put it inside the Customer tag. If the customer’s Fullname attribute doesn't exist the following response is returned:
<?xml version="1.0" encoding="utf-8" ?> <response version="1.0" /> |
<?xml version="1.0" encoding="utf-8" ?> <response version="1.0"> <customer> <name>BAC</name> <id>325</id> <fullname>Basic API Customer</fullname> .... </customer> </response> |
<?xml version="1.0" encoding="utf-8" ?> <request version="1.0" action="FIND"> <customer /> </request> |
<?xml version="1.0" encoding="utf-8"?> <request version="1.0" action="SET"> <customer> <fullname>Basic API Customer</fullname> <contactname>Admin</contactname> <contactemail>Admin@csm.local</contactemail> <primarydomain>csm.local</primarydomain> <parent> <fullname>Citrix Service Provider</fullname> </parent> </customer> </request> |
A response like this is returned for a successful request.
<?xml version="1.0" encoding="utf-8"?> <response version="1.0"> <request> <id>14452</id> </request> </response> |
If you leave one of the required fields empty, an error like this is returned.
Bad Request 6 Unable to create customer. A new customer must specify the name, fullname, contactname, contactemail and primarydomain. |
You don’t have to specify a Name tag because ATRIA automatically generates the short code (short name) for the customer. However, if you want the customer to have a specific code, you can specify it here.
<?xml version="1.0" encoding="utf-8"?> <request version="1.0" action="SET"> <customer> <name>BAC</name> <user> <name>User1</name> </user> </customer> </request> |
If you want to find all the users for a customer, use this request:
<?xml version="1.0" encoding="utf-8"?> <request version="1.0" action="FIND"> <customer> <fullname>Basic API Customer</fullname> <user /> </customer> </request> |
<?xml version="1.0" encoding="utf-8"?> <request action="SET" version="1.0"> <customer> <name>BAC</name> <service> <name>HE</name> <version>2010</version> <userpackage> <fullname>Ex10 Basic</fullname> <enabled>True</enabled> </userpackage> <package> <name>Basic</name> <enabled>True</enabled> </package> </service> </customer> </request> |
The syntax to provision a user with a service is very similar to provisioning a customer with a service.
<?xml version="1.0" encoding="utf-8"?> <request version="1.0" action="SET"> <customer> <name>BAC</name> <user> <name>User1</name> <service> <name>HE</name> <userpackage> <fullname>Ex10 Basic</fullname> </userpackage> </service> </user> </customer> </request> |
De-provisioning a service is very simple as you only have to specify the minimum requirements for the API to find the service.
<?xml version="1.0" encoding="utf-8"?> <request version="1.0" action="SET"> <customer> <name>BAC</name> <user> <name>User1</name> <service> <name>HE</name> <status>NotProvisioned</status> </service> </user> </customer> </request> |
<?xml version="1.0" encoding="utf-8"?> <request version="1.0" action="SET"> <customer> <name>BAC</name> <service> <name>HE</name> <status>Notprovisioned</status> </service> </customer> </request> |
<?xml version="1.0" encoding="utf-8"?> <request version="1.0" action="SET"> <customer> <name>BAC</name> <status>Notprovisioned</status> </customer> </request> |
<?xml version="1.0" encoding="utf-8"?> <request version="1.0" action="DELETE"> <customer> <name>BAC</name> <user> <name>User1</name> </user> </customer> </request> |
The Action attribute on the Request tag is set to DELETE as we want to delete the user. As you can see, the same details are required for deleting the user as for de-provisioning, except you do not need to specify the Status tag.
If you have been following all the examples up to this point, you should have one customer with one user in your environment. So, when you run the Delete User script, you will get the following error message:
<message>Unable to delete the last user from the customer</message>
ATRIA requires at least one user to exist for each customer. So, if the customer has only one user, ATRIA will not allow you to delete it. Before you test this script, create another user.
<?xml version="1.0" encoding="utf-8"?> <request version="1.0" action="DELETE"> <customer> <name>BAC</name> </customer> </request> |
For this example, we know the name of a customer and want to change a property of the File Sharing service. We send a FIND request to find all services for the customer:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="FIND">
<customer>
<fullname>ATest Customer</fullname>
<service/>
</customer>
</request>
<?xml version="1.0" encoding="utf-8"?>
<response version="1.0">
<customer>
<name>ATest</name>
<id>498</id>
<fullname>ATest Customer</fullname>
<billingid />
<primarydomain>atest.local</primarydomain>
<status>Provisioned</status>
…
<service>
<name>FSS</name>
<fullname>File Sharing</fullname>
<location>csm.Local</location>
<status>Provisioned</status>
</service>
…
</customer>
</response>
We update the request to include the service name from our last response and change the action to GET:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<customer>
<fullname>ATest Customer</fullname>
<service>
<name>FSS</name>
</service>
</customer>
</request>
The request returns detailed information about both the customer and the service:
<?xml version="1.0" encoding="utf-8"?>
<response version="1.0">
<customer>
<name>ATest</name>
<id>498</id>
<fullname>ATest Customer</fullname>
…
<service>
<name>FSS</name>
<fullname>File Sharing</fullname>
<location>csm.Local</location>
<userlimit>Unlimited</userlimit>
<isbilled>True</isbilled>
<status>Provisioned</status>
<approvalpending>False</approvalpending>
<userplan>
<name>FULL</name>
<fullname>Full</fullname>
<userlimit>Unlimited</userlimit>
<used>False</used>
<enabled>True</enabled>
</userplan>
<userplan>
<name>READ</name>
<fullname>Read</fullname>
<userlimit>Unlimited</userlimit>
<used>False</used>
<enabled>True</enabled>
</userplan>
<userplan>
<name>LIST</name>
<fullname>List</fullname>
<userlimit>Unlimited</userlimit>
<used>False</used>
<enabled>True</enabled>
</userplan>
<package>
<name>FULL</name>
<fullname>FULL</fullname>
<enabled>True</enabled>
</package>
</service>
</customer>
</response>
Change the response tag into a request tag and add the SET action attribute:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="SET">
<customer>
<name>ATest</name>
<id>498</id>
<fullname>ATest Customer</fullname>
…
</request>
Remove any settings that you don’t want to change. In this example, we only want to change the user limit:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="SET">
<customer>
<name>ATest</name>
<service>
<name>FSS</name>
<userlimit>Unlimited</userlimit>
</service>
</customer>
</request>
Update the user limit to 5 and send the request:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="SET">
<customer>
<name>ATest</name>
<service>
<name>FSS</name>
<userlimit>5</userlimit>
</service>
</customer>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<customer>
<name>ATest</name>
<properties detail="true"/>
</customer>
</request>
For users, you can use the Properties tag and the Additionalproperties tag. The Additionalproperties tag represents the users’ Active Directory properties. Only use the Detail attribute if required.
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<customer>
<name>ATest</name>
<user>
<name>test_ATest</name>
<properties detail="true"/>
<additionalproperties/>
</user>
</customer>
</request>
For customer and user services, there is an optional Filter attribute that can be used to show hidden properties. Only use the Detail attribute if required.
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<customer>
<name>ATest</name>
<service>
<name>FSS</name>
<properties detail="true" filter="all"/>
</service>
</customer>
</request>
The Properties tag can also be used for customer and user plans, with the optional Filter attribute. Only use the Detail attribute if required.
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<customer>
<name>ATest</name>
<service>
<name>FSS</name>
<userplan>
<name>FULL</name>
<properties detail="true" filter="all"/>
</userplan>
</service>
</customer>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<customer>
<name>ATest</name>
<user>
<name>test_ATest</name>
<service>
<name>FSS</name>
<userplan>
<name>FULL</name>
<properties detail="true" filter="all"/>
</userplan>
</service>
</user>
</customer>
</request>
##################################
# Sample API Request in PowerShell
##################################
# API Request to find the CSP Customer
# Note: Be careful when using @" "@ Here-String PowerShell construction format to create the request.
# Extra spacing could cause "bad request" to be returned. However, Here-String makes this request much more readable.
$apiRequest = @"
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="FIND">
<customer>
<name>CSP</name>
</customer>
</request>
"@
# URL to the CortexAPI
$apiUrl = "http://cortexweb/cortexapi/default.aspx"
# Initialize the client
$client = New-Object System.Net.WebClient
$client.Credentials = New-Object System.Net.NetworkCredential("cspadmin_csp","<YourPassword>")
$client.UploadString($apiUrl,$apiRequest)
<?xml version="1.0" encoding="utf-8"?>
<response version="1.0">
<customer>
<name>CSP</name>
<id>1</id>
<fullname>Cortex Service Provider</fullname>
<billingid />
<primarydomain>csp.local</primarydomain>
<status>Provisioned</status>
</customer>
</response>
'################################
'# Sample API Request in VBScript
'################################
' API Request to find all customers
On Error Resume Next
Dim Request, Response
Const Url = "http://cortexweb/cortexapi/default.aspx"
Const Username = "cspadmin_csp"
Const Password = "<YourPassword>"
Request = "<?xml version=""1.0"" encoding=""utf-8""?>" & _
"<request action=""FIND"" version=""1.0"">" & _
" <customer/>" & _
"</request>"
Err.Clear
Set Response = SendRequest(Url, Username, Password, Request)
If Err.Number<>0 Then
WScript.Echo "Failed [0x" & Hex(Err.Number) & "] " & Trim(Err.Description)
Else
If Response.Status = 200 Then
WScript.Echo "OK"
Else
WScript.Echo "Failed [" & Response.Status & "] " & Response.StatusText
Set ResponseNode = Response.responseXML.DocumentElement
WScript.Echo ">>" & ResponseNode.SelectSingleNode("/response/error/message").Text
End If
WScript.Echo
WScript.Echo Response.responseText
End If
Private Function SendRequest(ByVal Url, ByVal Username, ByVal Password, ByVal Request)
Dim XmlHttp
Set XmlHttp = CreateObject("MSXML2.XmlHttp")
XmlHttp.Open "POST", Url, False, Username, Password
XmlHttp.SetRequestHeader "Content-Type", "text/xml"
XmlHttp.Send Request
Set SendRequest = XmlHttp
End Function
<?xml version="1.0" encoding="utf-8"?>
<request action="FIND" trace="true" version="1.0">
<customer>
<name>CSP</name>
<user />
</customer>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request action="FIND" trace="false" version="1.0">
<customer>
<name>CSP</name>
<service />
</customer>
</request>
To find all of the services or userplans (including those that are not provisioned) that are available to a user, use this request:
<?xml version="1.0" encoding="utf-8"?>
<request action="FIND" trace="false" version="1.0">
<customer>
<name>CSP</name>
<user>
<name>cspadmin_CSP</name>
<service />
</user>
</customer>
</request>
To find information about all the services a customer was provisioned, use this request:
<?xml version="1.0" encoding="utf-8"?> <request action="FIND" version="1.0"> <customer> <name>BAC</name> <service /> </customer> </request> |
To see all the services a reseller can resell, use this request:
<?xml version="1.0" encoding="utf-8"?>
<request action="GET" version="1.0">
<customer>
<name>AA</name>
<service>
<name>Reseller</name>
</service>
</customer>
</request>
You can also use this with multiple locations. The Fullname setting will be different, but the Name setting will always be "Reseller."
Instead of sending the same request multiple times to provision users, you can chain the items into one request which can be done as many times as you require. This is useful for multiple users, services, and service settings.
<?xml version="1.0" encoding="utf-8"?> <request version="1.0" action="SET"> <customer> <name>BAC</name> <user> <name>User3</name> </user> <user> <name>User4</name> </user> </customer> </request> |
In this example, we are provisioning two users. By closing and opening the User tag, both users will be provisioned under customer BAC.
This example is really helpful for provisioning multiple user plans in the Hosted Exchange Example.
<?xml version="1.0" encoding="utf-8"?> <request action="SET" version="1.0"> <customer> <name>BAC</name> <service> <name>HE</name> <version>2010</version> <userpackage> <fullname>Ex10 Basic</fullname> <enabled>True</enabled> </userpackage> <userpackage> <fullname>Ex10 Full</fullname> <enabled>True</enabled> </userpackage> <package> <name>Basic</name> <enabled>True</enabled> </package> </service> </customer> </request> |
<?xml version="1.0" encoding="utf-8"?> <request version="1.0" action="SET"> <customer> <fullname>Basic API Customer</fullname> <contactname>Admin</contactname> <contactemail>Admin@csm.local</contactemail> <primarydomain>csm.local</primarydomain> <parent> <fullname>Citrix Service Provider</fullname> </parent> <service> <name>HE</name> <version>2010</version> <userpackage> <fullname>Ex10 Basic</fullname> <enabled>True</enabled> </userpackage> <package> <name>Basic</name> <enabled>True</enabled> </package> </service> </customer> </request> |
The easiest way to create an API request is to use the Get command. Using this command with a customer returns the requested information in a format that you can cut and paste into a Set action and use again. To reuse the information, you change the Response tag to “request,” change the request action to “SET,” and modify or add any other settings according to the information you want to create or update.
<?xml version="1.0" encoding="utf-8"?> <request action='GET' version='1.0'> <customer> <name>BAC</name> </customer> </request> |
The following sections show how to use the Get and Set actions to work with extra properties or information. Altering some of these properties should be done with caution as several of them set system configurations and should never be altered.
<?xml version="1.0" encoding="utf-8"?> <request action="GET" version="1.0"> <customer> <name>BAC</name> <service> <name>HE</name> </service> </customer> </request> |
To view information about the instances of the CRM 2011, SharePoint 2010, Microsoft SQL Server Hosting, or Windows Web Hosting services, use this request:
<?xml version="1.0" encoding="utf-8"?> <request action="GET" version="1.0"> <customer> <name>BAC</name> <service> <name>Sharepoint2010</name> <instances /> </service> </customer> </request> |
With the identity tag you can get information about the requesting user.
The requesting user is the user whose credentials were used to authenticate the API request. To get information about the requesting user, send the following request:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<identity/>
</request>
The request returns something like this:
<?xml version="1.0" encoding="utf-8"?>
<response version="1.0">
<identity>
<customer>
<name>CSP</name>
<id>1</id>
<fullname>Cortex Service Provider</fullname>
<billingid />
<primarydomain>csp.local</primarydomain>
<user>
<name>cspadmin_CSP</name>
<id>1</id>
<fullname>CSPAdmin</fullname>
<upn>cspadmin@csp.local</upn>
<location>Unassigned</location>
<department>Unassigned</department>
</user>
</customer>
</identity>
</response>
The Global tag returns version information about the API and the database:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<global/>
</request>
The request returns something like this:
<?xml version="1.0" encoding="utf-8"?>
<response version="1.0">
<global>
<version>
<api>11.0.0.0</api>
<database>11.0.0.0</database>
</version>
</global>
</response>
The Location tag allows you to manage ATRIA locations. You can FIND, GET, SET, and DELETE locations.
To get a list of locations:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="FIND">
<location/>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="FIND">
<location>
<service/>
</location>
</request>
You can also specify a service name or a service fullname to get a specific service:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="FIND">
<location>
<service>
<name>HE</name>
</service>
</location>
</request>
To get detailed information about a location:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<location>
<name>csm.Local</name>
</location>
</request>
This request gets the properties available for a customer in the specified location:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<location>
<name>csm.Local</name>
<customer>
<customerproperties/>
</customer>
</location>
</request>
This request gets the Active Directory properties for a user in the specified location:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<location>
<name>csm.Local</name>
<user>
<additionalproperties/>
</user>
</location>
</request>
To get a request with its ID:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<request>
<id>14882</id>
</request>
</request>
To get all children requests with the request’s parent ID:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<request>
<parentid>14882</parentid>
</request>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<request>
<id>14882</id>
<log/>
</request>
</request>
To get the times of various stages of request processing:
<?xml version="1.0" encoding="utf-8"?>
<request version="1.0" action="GET">
<request>
<id>14882</id>
<times/>
</request>
</request>
Although ATRIA has a comprehensive Data Warehouse with its own API, you might need the results of a simple query or stored procedure. That’s where this simple report feature is useful.
You can use the ATRIA API to run simple report queries on the ATRIA database and return the results in XML or tab delimited (TSV) format. To generate these queries, perform the following actions:
The following request returns all reports that are configured in the dbo.ReportQueries table:
<?xml version="1.0" encoding="utf-8"?>
<request action="FIND" version="1.0">
<report />
</request>
Tag |
Description |
<name> |
The name of the report. |
<parameter name=”[ParameterName]”> |
The report ‘s parameter name . A value should be entered for the parameter tag. |
<timeout> |
Sets a timeout period in milliiseconds. The value 0 indicates no timeout. |
<column> |
Returns the data for the specified column only. |
The format that the API will return the data can be defined by using one of the following options:
Format |
Description |
<dataformat columnnames=”[True]”>xml</dataformat> |
Report is generated in XML. If columnnames is set to True, the column names appear in the returned tags. |
<dataformat header=”[True]”>tsv</dataformat> |
Report is generated in TSV format. If header is set to True, the column names appear at the top of the report. |
The following API query returns all customers where the customer name begins with “C.” The report will be in XML format with the column names appearing in the returned tags.
<?xml version="1.0" encoding="utf-8"?>
<request action="GET" version="1.0">
<report>
<name>Customers with Stored Procedure</name><!-- Name of the Report -->
<parameter name=”Name”>C%</parameter>
<dataformat columnnames=”true”>xml</dataformat>
</report>
</request>
The API returns the data as:
<?xml version="1.0" encoding="utf-8"?>
<response version="1.0">
<report>
<name>Customers with Stored Procedure</name>
<description />
<result>
<column type="int">CustomerID</column>
<column type="int">LocationID</column>
<column type="nvarchar">Name</column>
<column type="nvarchar">Label</column>
<column type="nvarchar">BillingID</column>
<column type="nvarchar">PrimaryDomain</column>
<column type="int">StatusID</column>
<row>
<CustomerID>3</CustomerID>
<LocationID>1</LocationID>
<Name>CS</Name>
<Label>Citrix Systems</Label>
<BillingID />
<PrimaryDomain>citrix.com</PrimaryDomain>
<StatusID>1</StatusID>
</row>
<row>
<CustomerID>1</CustomerID>
<LocationID>1</LocationID>
<Name>CSP</Name>
<Label>Cortex service Provider</Label>
<BillingID />
<PrimaryDomain>csp.local</PrimaryDomain>
<StatusID>1</StatusID>
</row>
</result>
</report>
</response>
The following API query returns the details for customer code “CSP.” The report will be in TSV.format with the column names shown. There is no timeout set for the report query.
<?xml version="1.0" encoding="utf-8"?>
<request action="GET" version="1.0">
<report>
<name>Customers with Query</name>
<timeout>0</timeout>
<parameter name="Name">CSP</parameter>
<dataformat header="true">tsv</dataformat>
</report>
</request>
<?xml version="1.0" encoding="utf-8" ?>
<response version="1.0">
<report>
<name>Customers with Query</name>
<description />
<result>
<column type="int">CustomerID</column>
<column type="nvarchar">Name</column>
<column type="nvarchar">Label</column>
<column type="nvarchar">Location</column>
<column type="nvarchar">ContactName</column>
<column type="nvarchar">ContactEMail</column>
<column type="nvarchar">Description</column>
<column type="datetime">Created</column>
<column type="nvarchar">PhoneNumber</column>
<column type="nvarchar">FaxNumber</column>
<column type="int">MinPWLength</column>
<column type="int">BannerPWDays</column>
<column type="int">ModifiedBy</column>
<column type="datetime">DateDisabled</column>
<column type="datetime">DateDeleted</column>
<column type="nvarchar">BrandName</column>
<column type="nvarchar">OU_Name</column>
<column type="int">ObjectID</column>
<column type="nvarchar">BillingID</column>
<column type="int">ImpersonatingUserID</column>
<column type="nvarchar">BrandType</column>
<column type="int">ParentID</column>
<data>
<![CDATA[
CustomerID Name Label Location ContactName ContactEMail Description Created PhoneNumber FaxNumber MinPWLength BannerPWDays ModifiedBy DateDisabled DateDeleted BrandName OU_Name ObjectID BillingID ImpersonatingUserID BrandType ParentID
1 CSP Cortex service Provider CSP Admin cspadmin@csp.local 7/29/2012 8:36:22 PM 0 0 0 Default customers 36543 0 DNS
]]>
</data>
</result>
</report>
</response>
<?xml version="1.0" encoding="utf-8" ?>
<request action="GET" version="1.0" trace="true">
<customer>
<name>CSP</name>
<service>
<name>CRM2011</name>
<instances>
<instance>
<name>Site01</name>
</instance>
</instances>
</service>
</customer>
</request>
To query all of the instances for that customer’s service:
<?xml version="1.0" encoding="utf-8" ?>
<request action="GET" version="1.0" trace="true">
<customer>
<name>CSP</name>
<service>
<name>CRM2011</name>
<instances />
</service>
</customer>
</request>
<?xml version="1.0" encoding="utf-8" ?>
<request action="GET" version="1.0" trace="true">
<customer>
<name>CSP</name>
<user>
<name>user01_CSP</name>
<service>
<name>CRM2011</name>
<instances>
<instance>
<name>Site01</name>
</instance>
</instances>
</service>
</user>
</customer>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request action="GET" trace="true" version="1.0">
<customer>
<name>FTC</name>
<service>
<name>FSS</name>
<properties filter="all" />
</service>
</customer>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request action="GET" trace="true" version="1.0">
<customer>
<name>XTC</name>
<service>
<name>HostedAppsAndDesktops</name>
</service>
</customer>
</request>
Users provisioned with the Hosted Apps and Desktops service can have multiple user plans.
<?xml version="1.0" encoding="utf-8"?>
<request action="GET" trace="false" version="1.0">
<customer>
<name>XTC</name>
<user>
<name>barryh_XTC</name>
<service>
<name>HostedAppsAndDesktops</name>
</service>
</user>
</customer>
</request>
Mail Archiving is fairly straightforward. To see all the properties, use a filter, as shown.
<?xml version="1.0" encoding="utf-8"?>
<request action="GET" version="1.0">
<customer>
<name> TestCust01</name>
<service>
<name>MARCH</name>
<properties filter="all" />
</service>
</customer>
</request>
<?xml version="1.0" encoding="utf-8" ?>
<request action="GET" version="1.0">
<customer>
<name>crc</name>
<service>
<name>MySQL</name>
<resourceconfiguration />
</service>
</customer>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request action="GET" version="1.0">
<customer>
<name>CSP</name>
<service>
<name>SharePoint2010</name>
<resourceconfiguration />
</service>
</customer>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request action="GET" trace="true" version="1.0">
<customer>
<name>CSP</name>
<service>
<name>Sharepoint2010</name>
<properties filter="all" />
<instances />
</service>
</customer>
</request>
An example of how to query the SharePoint 2010 sites that were provisioned to a customer named "CSP."
<?xml version="1.0" encoding="utf-8"?>
<request action="GET" trace="true" version="1.0">
<customer>
<name>CSP</name>
<service>
<name>Sharepoint2010</name>
<properties filter="all" />
<instances />
</service>
</customer>
</request>
An example of how to query the SharePoint sites that were provisioned to user "FTC_u1_CSP" of a customer named "CSP."
<?xml version="1.0" encoding="utf-8"?>
<request action="FIND" version="1.0">
<customer>
<name>CSP</name>
<user>
<name>FTC_u1_CSP</name>
<service>
<name>Sharepoint2010</name>
<instances />
</service>
</user>
</customer>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request action="SET" trace="true" version="1.0">
<customer>
<name>ZCSP</name>
<service>
<name>FSS</name>
<status>Provisioned</status>
<properties>
<property>
<name>FileShareServer</name>
<value>CSPFILEHOST01</value>
</property>
</properties>
<package>
<name>Basic</name>
<enabled>True</enabled>
</package>
</service>
</customer>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request action="SET" trace="true" version="1.0">
<customer>
<name>XTC</name>
<service>
<name>HostedAppsandDesktops</name>
<package>
<name>SharedsiteWebInterfacemode</name>
<enabled>True</enabled>
</package>
<userplan>
<name>DESKTOPS</name>
<enabled>True</enabled>
</userplan>
</service>
</customer>
</request>
The Hosted Apps and Desktops service allows you to provision multiple user plans to a user. The following example provisions the "Office Apps" and "Desktops" user plans to the user.
<?xml version="1.0" encoding="utf-8"?>
<request action="SET" trace="true" version="1.0">
<customer>
<name>XTC</name>
<user>
<name>user1_xtc</name>
<service>
<name>HostedAppsandDesktops</name>
<userplan>
<name>DESKTOPS</name>
</userplan>
<userplan>
<name>OFFICEAPPS</name>
</userplan>
</service>
</user>
</customer>
</request>
<?xml version="1.0" encoding="utf-8" ?>
<request action="GET" version="1.0">
<customer>
<fullname>Justice League Unlimited</fullname>
<service>
<name>HE</name>
<distributiongroups />
</service>
</customer>
</request>
<?xml version="1.0" encoding="utf-8" ?>
<request action="GET" version="1.0">
<customer>
<fullname>Justice League Unlimited</fullname>
<service>
<name>HE</name>
<distributiongroups>
<displaynamefilter>M</displaynamefilter>
<emailfilter>M</emailfilter>
<pageindex>1</pageindex>
<pagesize>1000</pagesize>
</distributiongroups>
</service>
</customer>
</request>
Distribution group members are not returned by default to include members in the list, you can use the following syntax:
<?xml version="1.0" encoding="utf-8" ?>
<request action="GET" trace="true" version="1.0">
<customer>
<name></name>
<service>
<name>HE</name>
<distributiongroups>
<distributiongroup>
<members />
<sendrestrictionacceptedmembers />
<sendrestrictionrejectedmembers />
<sendasmembers />
</distributiongroup>
</distributiongroups>
</service>
</customer>
</request>
<?xml version="1.0" encoding="utf-8" ?>
<request action="GET" trace="true" version="1.0">
<customer>
<name></name>
<service>
<name>HE</name>
<distributiongroups>
<distributiongroup>
<syncobjectid>S-1-5-21-1816066181-3380177551-1806815814-1235</syncobjectid>
<members>
<member>
<syncobjectid>B5EF275A-D953-4FBC-9E89-B72AC0470278</syncobjectid>
</member>
</members>
<sendrestrictionacceptedmembers />
<sendrestrictionrejectedmembers />
<sendasmembers />
</distributiongroup>
</distributiongroups>
</service>
</customer>
</request>
<?xml version="1.0" encoding="utf-8" ?>
<request action="GET" trace="true" version="1.0">
<customer>
<name></name>
<service>
<name>HE</name>
<distributiongroups>
<displaynamefilter></displaynamefilter>
<emailfilter></emailfilter>
<pageindex></pageindex>
<pagesize></pagesize>
</distributiongroups>
</service>
</customer>
</request>
<?xml version="1.0" encoding="utf-8" ?>
<request action="GET" version="1.0">
<customer>
<fullname>Justice League Unlimited</fullname>
<user>
<name>Donald_E2010</name>
<service>
<name>HE</name>
<distributiongroups />
</service>
</user>
</customer>
</request>
<?xml version="1.0" encoding="utf-8" ?>
<request action="SET" version="1.0">
<customer>
<fullname>Justice League Unlimited</fullname>
<user>
<name>Batman_JLU</name>
<service>
<name>HE</name>
<distributiongroups>
<distributiongroup>
<path>CN=Heroes,OU=Distribution Groups,OU=Justice League Unlimited(JLU),OU=Customers,DC=dev,DC=local</path>
<selected>true</selected>
</distributiongroup>
<distributiongroup>
<displayname>Enemies</displayname>
<selected>false</selected>
</distributiongroup>
</distributiongroups>
</service>
</user>
</customer>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request action="SET" trace="true" version="1.0">
<customer>
<name></name>
<service>
<name>HE</name>
<distributiongroups>
<distributiongroup>
<displayname></displayname>
<syncobjectid></syncobjectid>
<enabled></enabled>
<path></path>
<email></email>
<emailalias></emailalias>
<mailtip></mailtip>
<grouptype></grouptype>
<hidefromaddresslists></hidefromaddresslists>
<requiresenderauthentication></requiresenderauthentication>
<memberjoinrestriction></memberjoinrestriction>
<memberdepartrestriction></memberdepartrestriction>
<sendmoderationnotifications></sendmoderationnotifications>
<emailaddresses>
<emailaddress></emailaddress>
</emailaddresses>
<owners>
<owners>
<displayname></displayname>
<syncobjectid></syncobjectid>
<path></path>
<email></email>
</owners>
</owners>
<members>
<member>
<displayname></displayname>
<syncobjectid></syncobjectid>
<path></path>
<email></email>
<enabled></enabled>
</member>
</members>
<sendasmembers>
<sendasmember>
<displayname></displayname>
<syncobjectid></syncobjectid>
<path></path>
<email></email>
<enabled></enabled>
</sendasmember>
</sendasmembers>
<sendrestrictionacceptedmembers>
<sendrestrictionacceptedmember>
<displayname></displayname>
<syncobjectid></syncobjectid>
<path></path>
<email></email>
<enabled></enabled>
</sendrestrictionacceptedmember>
</sendrestrictionacceptedmembers>
<sendrestrictionrejectedmembers>
<sendrestrictionrejectedmember>
<displayname></displayname>
<syncobjectid></syncobjectid>
<path></path>
<email></email>
<enabled></enabled>
</sendrestrictionrejectedmember>
</sendrestrictionrejectedmembers>
</distributiongroup>
</distributiongroups>
</service>
</customer>
</request>
Tag |
Tag Options |
<grouptypes> |
|
<memberjoinrestriction> |
|
<memberdepartrestriction> |
|
<sendmoderationnotification> |
|
<hidefromaddresslists> |
|
<requiresenderauthentication> |
|
To retrieve a list of contacts, use a GET request. This request requires the customer name and service name, as well as the <contacts /> tag which includes the list of contacts in the response.
<?xml version="1.0" encoding="utf-8" ?>
<request action="GET" trace="true" version="1.0">
<customer>
<name></name>
<service>
<name>HE</name>
<contacts />
</service>
</customer>
</request>
You can provide additional tags to filter by display name or the sync object identifier, and to retrieve a specified page size and index.
<?xml version="1.0" encoding="utf-8" ?>
<request action="GET" trace="true" version="1.0">
<customer>
<name></name>
<service>
<name>HE</name>
<contacts>
<displaynamefilter></displaynamefilter>
<syncfilter></syncfilter>
<pageindex></pageindex>
<pagesize></pagesize>
</contacts>
</service>
</customer>
</request>
To add or modify a contact, a SET request is used. This request requires the customer and service name, as well as the <contacts> tag with the <contact> tag containing the contact details. You can specify the <syncobjectid> tag to indicate that the contact has been synced from a remote domain.
<?xml version="1.0" encoding="utf-8"?>
<request action="SET" trace="true" version="1.0">
<customer>
<name></name>
<service>
<name>HE</name>
<contacts>
<contact>
<displayname></displayname>
<syncobjectid></syncobjectid>
<enabled></enabled>
<path></path>
<email></email>
<emailalias></emailalias>
<firstname></firstname>
<lastname></lastname>
<initials></initials>
<jobtitle></jobtitle>
<companyname></companyname>
<businessphone></businessphone>
<businessfax></businessfax>
<homephone></homephone>
<mobile></mobile>
<webpage></webpage>
<street></street>
<city></city>
<state></state>
<country></country>
<postcode></postcode>
<hidefromaddresslists></hidefromaddresslists>
</contact>
</contacts>
</service>
</customer>
</request>
To create a new user with a specific password:
<?xml version="1.0" encoding="utf-8" ?>
<request action="SET" version="1.0">
<customer>
<name>CSP</name>
<user>
<name>User1_CSP</name>
<password>
<password>Hello123</password>
<changeatnextlogon>true</changeatnextlogon>
<expires>NEVER</expires>
</password>
</user>
</customer>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request action="SET" trace="true" version="1.0">
<customer>
<name>ZCSP</name>
<status>NotProvisioned</status>
</customer>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request action="SET" trace="true" version="1.0">
<customer>
<name>ZCSP</name>
<status>Provisioned</status>
</customer>
</request>
To disable a customer named "ZCSP," send the following request:
<?xml version="1.0" encoding="utf-8"?>
<request action="SET" trace="true" version="1.0">
<customer>
<name>ZCSP</name>
<enabled>false</enabled>
</customer>
</request>
<?xml version="1.0" encoding="utf-8"?>
<request action="SET" trace="true" version="1.0">
<customer>
<name>ZCSP</name>
<enabled>true</enabled>
</customer>
</request>
This section describes how to configure workflow approval subscription for a customer. Sample requests are included to manage the "Workflow Managers" and "Workflow Groups" providers.
Customer subscriptions can only be managed for enabled approval providers via the API.
A user must have the Update role permission to view and manage approval providers for a customer.
<?xml version="1.0" encoding="utf-8"?>
<request action="GET" version="1.0">
<customer>
<name>CSP</name>
<approvalproviders />
</customer>
</request>
Use the GET request from the example above to create a SET request to manage approval providers.