This section describes the common operation parameters handled by the IPS Web Service API.
For a complete description of each operation parameter, see Operation parameters.
Handles reference IPS objects returned by certain API operations. You can also pass handles as parameters to subsequent operation calls. Handles are string data types (
Handles are intended for use during a single application session only. Furthermore, you should make handles persistent because their format can change between IPS releases. When you write interactive applications, you implement session timeouts and discard all handles between sessions, particularly after an IPS upgrade. When you write non-interactive applications, call the appropriate operations to retrieve handles each time the application is run. The following Java/Axis2 code samples show incorrect and correct code execution:
Incorrect Handle Code
This code sample is incorrect because it contains a hard-coded value (555) for the company handle.
SearchAssetsParam searchParam = new SearchAssetsParam(); searchParam.setCompanyHandle("555");// INCORRECT searchParam.setFolder("myFolder"); SearchAssetsReturn retVal = ipsApi.searchAssets(searchParam, authHeader);
Correct Handle Code
This code sample is correct because it calls
getCompanyInfo to return valid handle. It does not rely on a hard-coded value. Use this method-or other IPS API equivalent-to return the required handle.
GetCompanyInfoParam companyInfoParam = new GetCompanyInfoParam(); companyInfoParam.setCompanyName("My Company"); GetCompanyInfoReturn companyInfoReturn = ipsApi.getCompanyInfo(companyInfoParam, authHeader); String companyHandle = companyInfoReturn.getCompanyInfo().getCompanyHandle(); SearchAssetsParam searchParam = new SearchAssetsParam(); searchParam.setCompanyHandle(companyHandle); //CORRECT searchParam.setFolder("myFolder"); SearchAssetsReturn retVal = ipsApi.searchAssets(searchParam, authHeader);
Most operations require you to set a company context by passing in a
companyHandle parameter. The company handle is a pointer returned by certain operations such as
userHandle parameter is an optional parameter for operations that target a specific user. By default, these operations target the calling user (the user whose credentials are passed in for authentication). However, admin users with the proper permissions can specify a different user. For example, the
setPassword operation normally sets the password of the authenticated user, but an admin can use the
userHandle parameter to set the password for a different user.
For operations that require a company context (using the
companyHandle parameter), both the authenticated and target users must be members of the specified company. For operations that do not require a company context, the authenticated and target users must both be members of at least one common company.
The following operations can retrieve user handles:
accessUserHandle and accessGroupHandle
By default, operations that require access permissions (read, write, delete) operate in the permission context of the calling user. Certain operations allow you to modify this context with the
accessGroupHandle parameter. The
accessUserHandle parameter allows an admin to impersonate another user. The
accessGroupHandle parameter allows the caller to operate in the context of a specific user group.
responseFieldArray and excludeFieldArray
Some operations allow the caller to restrict which fields are included in the response. Limiting fields can help reduce the time and memory required to process the request and reduce the size of the response data. The caller can request a specific list of fields by passing a
responseFieldArray parameter, or with an enumerated a list of excluded fields via the
excludeFieldArray specify fields by using a node path separated by
/. For example, to specify that
searchAssets returns only the name, last modified date, and metadata for each asset refer to the following:
<responseFieldArray> <items>assetArray/items/name</items> <items>assetArray/items/lastModified</items> <items>assetArray/items/metadataArray</items> </responseFieldArray>
Similarly, to return all fields (except for permissions):
<excludeFieldArray> <items>assetArray/items/permissions</items> </excludeFieldArray>
Note that the node paths are relative to the return node root. If you specify a complex type field without any of its sub-elements (for example,
assetArray/items/imageInfo), then all of its sub-elements are included. If you specify one or more sub-elements in a complex type field (for example,
assetArray/items/imageInfo/originalPath), then only those sub-elements are included.
If you do not include
excludeFieldArray in a request, all fields are returned.
Since IPS 4.0, the IPS API supports setting the locale context of an operation by passing the
authHeader locale parameter. If the locale parameter is not present, the HTTP header
Accept-Language is used. If this header is also not present, the default locale for the IPS server is used.
Certain operations also take explicit locale parameters, which may be different than the operation locale context. For example, the
submitJob operation takes a
locale parameter that sets the locale used for job logging and email notification.
Locale parameters use the format
Where the language code is a lower-case, two-letter code specified by ISO-639 and the optional country code is an upper-case, two-letter code specified by ISO-3266. For example, the locale string for US English is