Python Agent API Reference

Defines the address line attributes that the target will support

Signature: addressattrs(cinfo)

Return Value:

Remarks:

The agent.addAddressAttr callback should be used in this operation to define the address attributes for the target, refer to agent.addAddressAttr callback for full details. The callback can only be used in scripted agents that are defined with a .con file. The values specified for the address attributes, will be available to be used in other operations inside of the "settings" dictionary object.

Establishes a connection to the target system

Signature: connect(cinfo)

Parameters:

Return Value:

Remarks:

This function will be called before other operations to establish a connection for use in the subsequent operations.

Terminates the connection to the target system

Signature: disconnect(cinfo)

Return Value:

Defines additional operations the connector supports

Signature: platforminfo(cinfo)

Return Value:

Remarks:

The agent.addSupportedOp callback can be used in this operation to define additional operations the connector will support. This functionality is primarily used in scenarios where the connector is wrapping a different connector. See the agent.addAddressAttr callback page for full details.

Returns the version of the target system. Also used to validate a connection to the target system when using the "Test Connect" button during target configuration

Signature: serverinfo(cinfo)

Return Value:

Remarks:

The agent.serverInfo callback should be used to return the version information for the target system. See the agent.serverInfo callback page for full details.

Lists computer objects from the target system.

Signature: listcomputers(cinfo, resourceType)

Parameters:

Return Value:

Remarks:

The agent.addComputer callback should be used to return the computer objects. Refer to agent.addComputer callback for full details

Lists groups from the target system.

Signature: listgroups(cinfo, wantMembers)

Parameters:

Return Value:

Remarks:

The agent.addGroup callback callback should be used to return the groups listed during this operation. Refer to agent.addGroup callback for full details.

Indicates if members will be listed while listing users or while listing groups

Signature: listmembersmethod()

Return Value:

Remarks:

Generally when creating custom Python integrations member information will be listed with the listgroups operation. For certain targets the membership information is provided alongside the user information instead of the group information, this function indicates during which operation memberships should be listed.

If this function is not implemented it will be assumed members will be listed during group listing.

Lists objects that rely on user credentials, which should be updated when the user's password is changed

Signature: listsubscribers(cinfo, resourceType)

Parameters:

Return Value:

Remarks:

The agent.addSubscriber callback should be used to return the subscriber objects. Refer to agent.addSubscriber callback for full details.

Lists users from the target system

Signature: listusers(cinfo, wantGroups, wantAttributes)

Parameters:

Return Value:

Remarks:

The agent.addAccount callback should be used to return the accounts listed during this operation. Refer to agent.addAccount callback for full details.

For listing attributes if wantAttributes is false, no attributes should be listed. If wantAttributes is true the attributes specified in cinfo['listattributes'] should be listed. If cinfo['listattributes'] is empty and wantAttributes is true all attributes should be listed.

Validates if a password is valid for a specified account, without incrementing the password lockout count.

Signature: adminverify(cinfo)

Parameters:

Return Value:

Remarks:

If this operation is not defined the verify operation will automatically be called instead

Verifies the old password for an account, if successful the password is then changed to a new value.

Signature: change(cinfo)

Parameters:

Return Value:

Expires the password for an account

Signature: def expirepw(cinfo)

Parameters:

Return Value:

Checks if the password is expired on an account

Signature: def ispwexpired(cinfo)

Parameters:

Return Value:

Remarks:

The agent.isPwExpired callback should be used to return the status of the password. See the agent.isPwExpired callback page for full details.

Sets the password for an account to a new value. This function will also unlock the account and unexpire the password.

Parameters:

Return Value:

Sets the password for an account to a new value. This function will also expire the new password.

Signature: def resetexpirepw(cinfo)

Parameters:

Return Value:

Unexpire the password for an account.

Signature: def unexpirepw(cinfo)

Parameters:

Return Value:

Validates if a password is valid for a specified account

Signature: verify(cinfo)

Parameters:

Return Value:

Validates if a password is valid for a specified account, resetting the password if it is not. This function will also unlock the account and unexpire the password if required.

Signature: verifyreset(cinfo)

Parameters:

Return Value:

Remarks:

If this operation is not defined other operations will be automatically called instead. The priority for fallback operations is:

Creates a new user.

Signature: create(cinfo)

Parameters:

Return Value:

Remarks:

The agent.stableId, agent.longId, agent.shortId and agent.addAccountAttr callbacks should be used to return information on the created user. See the callback section for full details on the individual callbacks.

The template account should be used for attributes with the "COPY" or "REPLACE" actions to be able to determine what value should be set for the attribute. For full details on attributes see the attributes definitions section.

Deletes a user.

Signature: delete(cinfo)

Parameters:

Return Value:

Moves a user to a different context

Signature: movecontext(cinfo)

Parameters:

Return Value:

Renames a user.

Signature: rename(cinfo)

Parameters:

Return Value:

Updates the attributes of a user.

Signature: update(cinfo)

Parameters:

Return Value:

Remarks:

The agent.stableId, agent.longId, agent.shortId and agent.addAccountAttr callbacks should be used to return information on the updated user. See the callback section for full details on the individual callbacks.

Queries attributes for a single user.

Signature: userattributes(cinfo)

Parameters:

Return Value:

Remarks:

The agent.addAccountAttr callback should be used to return information on the user. See the callback section for full details on the individual callbacks.

Disables an account.

Signature: def disable(cinfo)

Parameters:

Return Value:

Remarks:

If the account is already disabled before doing any modifications, the function should return ACSuccess.

Enables an account.

Signature: def enable(cinfo)

Parameters:

Return Value:

Remarks:

If the account is already enabled before doing any modifications, the function should return ACSuccess.

Expires an account

Signature: def expireacct(cinfo)

Parameters:

Return Value:

Remarks:

If the account is already expired before doing any modifications, the function should return ACSuccess.

Check if an account is expired.

Signature: def isenabled(cinfo)

Parameters:

Return Value:

Remarks:

The agent.isEnabled callback should be used to return the status of the account. See the agent.isEnabled callback page for full details.

Checks if an account is expired.

Signature: def isacctexpired(cinfo)

Parameters:

Return Value:

Remarks:

The agent.isAcctExpired callback should be used to return the status of the account. See the agent.isAcctExpired callback page for full details.

Checks if an account is locked.

Signature: def islocked(cinfo)

Parameters:

Return Value:

Remarks:

The agent.isLocked callback should be used to return the status of the account. See the agent.isLocked callback page for full details.

Locks an account.

Signature: def lock(cinfo)

Parameters:

Return Value:

Remarks:

If the account is already locked before doing any modifications, the function should return ACSuccess.

Unexpires an account.

Signature: def unexpireacct(cinfo)

Parameters:

Return Value:

Remarks:

If the account is already not expired before doing any modifications, the function should return ACSuccess.

Unlocks an account.

Signature: def unlock(cinfo)

Parameters:

Return Value:

Remarks:

If the account is already unlocked before doing any modifications, the function should return ACSuccess.

Creates a new group.

Signature: def groupcreate(cinfo)

Parameters:

Return Value:

Remarks:

The agent.stableId, agent.longId, agent.shortId and the agent.addGroupAttr callbacks should be used to return information on the newly created group. See the callback section for full details on the individual callbacks.

Deletes a group.

Signature: def groupdelete(cinfo)

Parameters:

Return Value:

Adds a group to a group.

Signature: def groupgroupadd(cinfo)

Parameters:

Return Value:

Removes a group from a group.

Signature: def groupgroupdelete(cinfo)

Parameters:

Return Value:

Adds a user to a group as a group owner.

Signature: def groupowneradd(cinfo)

Parameters:

Return Value:

Removes an owner from a group.

Signature: def groupownerdelete(cinfo)

Parameters:

Return Value:

Adds a user to a group.

Signature: def groupuseradd(cinfo)

Parameters:

Return Value:

Removes a user from a group.

Signature: def groupuserdelete(cinfo)

Parameters:

Return Value:

Updates the attributes on a group.

Signature: def groupupdate(cinfo)

Parameters:

Return Value:

Remarks:

The agent.stableId, agent.longId, agent.shortId and the agent.addGroupAttr callbacks should be used to return information on the updated group. See the callback section for full details on the individual callbacks.

Creates a network resource.

Signature: def nrcreate(cinfo)

Parameters:

Return Value:

Deletes a network resource.

Signature: def nrdelete(cinfo)

Parameters:

Return Value:

Moves a network resource.

Signature: def nrmove(cinfo)

Parameters:

Return Value:

Updates a network resource.

Signature: def nrupdate(cinfo)

Parameters:

cinfo['resourceaddress'] - Address for the network resource to be updated

cinfo['resourcetype'] - Type of network resource to be updated

cinfo['attributes'] - Attributes to be set on the network resource

Return Value:

ACSuccess 0

ACUnknownError 1

Advanced authentication operation for use with token or disk encryption systems.

Signature: def challengeresponse(cinfo)

Parameters:

Return Value:

Remarks:

Depending on the use case for the operation, either for token authentication or for disk encryption, both the expected input and output will vary for this operation.

For disk encryption targets generally a challenge string will be provided which will be validated by the target system to receive a response string, which should be output and provided to the end user to unlock the encrypted disk.

For token authentication targets one or more challenge response operations are passed to the target system to authenticate conditions. The challenge string contains the state across the multiple operations while the response is the string to validate. The next challenge state and response should be returned until all conditions are validated.

The agent.addChallenge and agent.addResponse callbacks should be used to return information from this operation. See the callback section for full details on the individual callbacks.

Performs a custom operation.

Signature: custom_<functionName>(cinfo)

Return Value:

Remarks:

This operation lets you define your own operations that should be run. The definition of this function will vary as you can define your own operations. The format of your function definition should be "custom_" followed by whatever your custom function name is, so for example something like custom_hello_world(cinfo).

To invoke these custom defined operations, the agent should be called with "custom" as the operation and the "customop" input set to the value of the custom function name that should be invoked. For example, to call a custom_hello_world(cinfo) function the "customop" input should be set to the value "hello_world".

Due to the nature of this operation a hard-coded list of expected parameters that would be used or return values that might be returned cannot be defined, as they will vary depending on your custom definition.

The agent.addCustomAttrs and the agent.listAttribute callbacks should be used to return information from this operation. See the callback section for full details on the individual callbacks.

Runs a specified command

Signature: def runcommand(cinfo)

Parameters:

Return Value:

Remarks:

The agent.commandOutput should be used to return the command's output from the agent. See the callback section for full details on the callback.

Updates the password on a subscriber resource.

Signature: def updateresource(cinfo)

Parameters:

Return Value:

Remarks:

If a restart should be done as part of the operation, the position parameter indicates if it should be done before or after the password update. It's value will either be "pre" for before the update, or "post" if it should be done after.

See explanation of agent codes .

A dictionary object containing dictionaries for each attribute that is specified when creating or updating users. Each individual attribute dictionary will have 5 keys:

Remarks:

Depending on the value of the "ACTION" field different things should be done for the attribute being set.They are:

A dictionary object containing attributes and their value(s).

For each entry in the dictionary the key is the attribute's name, while the value is either a singular string value or a list of string values if the attribute is multi-valued.

For example:

attrsDict = {'attr1': 'value1', 'attr2': ['value2-1','value2-2']}

A dictionary object containing the inputs for the operations. It's contents are:

A dictionary object containing the groups an account is a member of.

For each entry in the dictionary the key is the group's stable id, while the value is a dictionary object with 2 keys:

An example is

groupsDict = {'stableid': {GAttrLongID: 'group1', GAttrSecurityDomain: 'domain1'}, 'stableid2': {GAttrLongID: 'group2'}}

A dictionary object containing the owners of a group

For each entry in the dictionary the key is the owner's stable id, while the value is a dictionary object with 3 keys:

An example is

ownersDict = {'user1': {GAttrLongID: 'user1', GAttrSecurityDomain: 'domain1', KeyType: 'account'}}

A dictionary object containing the members of a group

For each entry in the dictionary the key is the member's stable id, while the value is a dictionary object with 3 keys:

An example is:

membersDict = {'user1': {GAttrLongID: 'user1', GAttrSecurityDomain: 'domain1', KeyType: 'account'}}