Product Documentation

Provisioning a Single Application - addRequest

Feb 06, 2011

Use the addRequest operation to add credentials to an application for a user.

An addRequest operation requests that a new object (the credential) be added to the specified container object (the user's data store). A containerID (user's fully qualified domain name (FQDN)) must be specified and the psoID (credential GUID) for the newly created object is returned. The data of the request are the specifics of the credential to be created.

If the application definition assigned to the new credential is a member of a password sharing group, then all of the credentials associated with members of that group are updated to use the new password.

Syntax

<addRequest requestID='optional-client-generated-ID' 
targetID='CPM Provisioning 1.0' returnData='identifier' 
executionMode='synchronous'> 
<ctxs:authentication-token xmlns:ctxs='http://citrix.com/Provision'>AuthToken   
</ctxs:authentication-token> 
     <containerID ID='userFQDN'/> 
     <data> 
          <ctxs:credential xmlns:ctxs='http://citrix.com/Provision'> 
               <ctxs:name>Credential name</ctxs:name> 
               <ctxs:provision-description>Admin Text</ctxs:provision-description> 
               <ctxs:description>Credential description</ctxs:description> 
               <ctxs:application> 
                    <ctxs:id>appdefGuid</ctxs:id> 
                    <ctxs:group join='true' use-new-password='true'>Domain</ctxs:group> 
                    <ctxs:fields> 
                         <ctxs:userID>salima</ctxs:userID> 
                         <ctxs:password>pass123</ctxs:password> 
                         <ctxs:custom-field index='1'>domain</ctxs:custom-field> 
                         <ctxs:custom-field index='2'>database</ctxs:custom-field> 
                    </ctxs:fields> 
               </ctxs:application> 
          </ctxs:credential> 
      </data> 
 </addRequest> 

Parameters

requestID (mandatory) This is the client-generated ID that associates the return values with this request.
targetID (mandatory) This is the ID of the Provisioning Module, identified with the targetID 'CPM Provisioning 1.0.'
returnData (mandatory)

data — details of a secondary credential

identifier — list of credentials for a user

name — not supported in Single Sign-on

everything — application definitions available to the specified user

executionMode (mandatory) Single Sign-on supports synchronous execution mode.
authentication-token (mandatory) The authentication-token element is mandatory, but is not used at this time. .
containerID (mandatory) The containerID provides the FQDN of the user who owns the credential.
data (mandatory) Data is the description of the data being modified. This is the credential element and may include any child elements of the credential and application elements.
ctxs:credential (mandatory) The credential element is used to describe a single secondary credential. The name and description children of the credential element are optional. If not provided, the plug-in uses the name and description from the application definition.
ctxs:application (mandatory) The application element is used both to describe an application definition and to describe details of a credential. The application element must correspond to one previously obtained from a lookupApplicationsRequest operation.

Syntax for Return Values (addResponse)

 <addResponse status='success' requestID='client-generated-ID' > 
    <pso> 
          <psoID ID='credential-GUID'> 
               <containerID ID='userFQDN'/> 
          </psoID> 
          <data/> 
    </pso> 
</addResponse>

Parameters for Return Values (addResponse)

status (mandatory) Possible values: Success, Failure, Pending
requestID (mandatory) This is the client-generated ID that associates these return values with the associated request.
pso (mandatory) The data of the pso is a credential as described in ctxs:credential.
psoID (mandatory) The psoID is a unique identifier for each end user; PSOID is the credential's GUID returned by the lookupResponse.
containerID (mandatory) The containerID provides the FQDN of the user who owns the credential.
data (mandatory) Data is the description of the data being modified. This is the credential element and may include any child elements of the credential and application elements.

Group Element Attributes

The join and use-new-password attributes of the group element control how the new credential affects the existing group members. If the application group has not been configured to share passwords, the group element is ignored.

Join value Use-new-password value Effect
False False The new credential is disassociated from the existing credentials in the group. There is no effect on the existing group.
False True The new credential is disassociated from the existing credentials in the group. There is no effect on the existing group.
True False The new credential is joined to the existing group. The password of the new credential is set to the password shared by the existing group members. If there are no existing group members, the password value is used.
True True The new credential is joined to the existing group. The password included in the command is used for the new credential and also assigned to all of the existing group members.

The credential GUID returned as the psoID in the response is the same one that will be listed in the lookupResponse operation and may also be used to identify this secondary credential in a modifyRequest or deleteRequest operations.