exportSecurityAudit

Supported in API v20 +

Category	Data retrieval
Description	Returns a report of all security events in a specified time range, filterable by event type. Security events include unsuccessful login attempts, password changes, account lockout, account creation, and other security related information. If no time range is requested, all events from the last 24 hours return. Security events recorded by the audit log are based on NIST 800-53. Adaptive Planning only keeps 30 days of security audit data.
Permissions Required To Invoke	Administrator
Parameters Required On Request	Credentials

This method's request contains a credentials tag to identify and authorize the calling user, and an include tag identifying the actor and time range to retrieve security events for. Once verified, the method returns an XML document describing all security events in the specified time range, filterable by event type.

Request Format


<?xml version='1.0' encoding='UTF-8'?>
<call method="exportSecurityAudit" callerName="a string that identifies your client application">
 <credentials login="sampleuser@company.com" password="my_pwd"/>
 <include actor="stevec@greenco.com" dateTimeFrom="2019-07-30 00:00:00" dateTimeTo="2019-07-30 11:59:59"/>
</call>

credentials element
Tag Name		credentials
Description		All API calls must contain a single credentials element to identify the user invoking the API. The API call is then performed as this user (any audit trail or history of actions in the system will show that this user performed the action), and therefore the user must have the required permissions to perform the action in order for the API call to succeed.
Attributes of the Element
Attribute Name	Required?	Value	Example
login	Y	The login name of the user invoking the API method. This user must have the required permissions to invoke the method.	sampleuser@company.com
password	Y	The password of the user invoking the API method.	my_password
Contents of the Element
none

include element
Tag Name		include
Description
Attributes of the Element
Attribute Name	Required?	Value	Example
actor	N	The username whose security events you want to retrieve. Returns events for all users when actor is not included.	stevec@greenco.com
dateTimeFrom	N	The start of the time range in ISO-8601 compatible format ( YYYY-MM-DDTHH:MM:SS ) in UTC for the security events you want to retrieve.	2019-07-30 00:00:00
dateTimeTo	N	The end of the time range in ISO-8601 compatible format ( YYYY-MM-DDTHH:MM:SS ) in UTC for the security events you want to retrieve.	2019-07-30 11:59:59
Contents of the Element
none

Response Format


<?xml version='1.0' encoding='UTF-8'?>
<response success="true">
 <output>
     <audit>
        <event timestamp="2019-07-30 01:59:48.7781" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" />
        <event timestamp="2019-07-30 01:59:48.9822" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" />
        <event timestamp="2019-07-30 02:01:29.115" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" />
        <event timestamp="2019-07-30 02:02:03.0594" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" />
        <event timestamp="2019-07-30 02:06:35.8937" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" />
        <event timestamp="2019-07-30 02:06:36.0589" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" />
        <event timestamp="2019-07-30 02:06:36.1219" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" />
        <event timestamp="2019-07-30 02:06:59.8724" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" />
        <event timestamp="2019-07-30 02:07:36.5505" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" />
        <event timestamp="2019-07-30 02:07:37.8862" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" />
        <event timestamp="2019-07-30 02:08:06.7037" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" />
        <event timestamp="2019-07-30 02:08:10.4557" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" />
        <event timestamp="2019-07-30 02:08:14.8878" action="SUC" actor="475245454E434F000000000001000004" version="20" interface="" object="User - 475245454E434F000000000001000004" outcome="0" context="" />
     </audit>  
 </output>
</response>

response element
Tag Name		response
Attributes of the Element
Attribute Name	Required?	Value	Example
success	Y	Either true or false, indicating whether the API call was successful or not. Even successful calls may contain warning messages in their response.	true
obsolete	N	If present on the response tag and set to true, this attribute indicates that the version of the method or API which is being invoked has become obsolete and is officially deprecated by Adaptive Planning . While it continues to function at this time, it may cease functioning in a short while. Typically, this attribute is not present.	false
Contents of the Element
A single optional messages element, and exactly one required output element.

output element
Tag Name	output
Attributes of the Element
(none)
Contents of the Element
A single audit element. This output wrapper is standard on all API responses and encloses the valid output of any successful API call.

audit element
Tag Name		audit
Description		A collection of security events.
Attributes of the Element
(none)
Contents of the Element
One or more event elements.

event element
Tag Name		event
Description		A security event.
Attributes of the Element
Attribute Name	Required?	Value	Example
timestamp	Y	The timestamp in ISO-8601 compatible format ( YYYY-MM-DDTHH:MM:SS.sssZ ) in UTC of the event	2019-07-30 01:59:48.7781
action	Y	The action that triggered the audit event: 'CRE' Account creation 'DIS' Account disabled 'LOK' Account lockout 'UOK' Account unlock 'USC' Unsuccessful login 'SUC' Successful login 'ULO' User logout 'PWC' User password change 'TER' Session termination due to exceptions 'EXP' Session expiration 'CRD' Credential changes 'AUT' Changes to authentication configuration	SUC
actor	Y	GUID of the actor (service, user, system user) that initiated the operation triggering the event (NULL if no particular user can be assigned). You can retrieve current usernames by GUID in the results of an exportUsers call.	475245454E434F000000000001000004
version	Y	The version of the software used to perform the action.	21
interface	N	The interface (API, UI, or URI) triggering the audit event.	API
object	N	The system object triggering the audit event.	User - 475245454E434F000000000001000004
outcome	Y	The success or failure of the action. 0 indicates success, 1 indicates failure.	0
context	N	System specific information about the audit event.
Contents of the Element
(none)