com.sap.cds.repackaged.audit.api.AuditLogMessage Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of cds-feature-auditlog-v2 Show documentation
Handler to send auditlog messages to AuditLog Service V2
There is a newer version: 3.2.0
Show newest version
package com.sap.cds.repackaged.audit.api;

import java.time.Instant;

import com.sap.cds.repackaged.audit.api.exception.AuditLogNotAvailableException;
import com.sap.cds.repackaged.audit.api.exception.AuditLogWriteException;

public interface AuditLogMessage {
	/**
	 * Persists the already created and populated with relevant data audit message.
	 *
	 * @throws AuditLogWriteException        In case a problem occurs while persisting the audit message.
	 * @throws AuditLogNotAvailableException If the audit log server is not available.
	 */
	void log() throws AuditLogNotAvailableException, AuditLogWriteException;

	/**
	 * Sets the user that triggered the audit event. 

	 * [NOTE] When using the standard plan of the auditlog service you should specify the user yourself
	 * [NOTE] When using the oauth2 plan of the auditlog service you should write setUser("$USER") and the user will be set automatically on server side
	 *
	 * @param user The value should be the user name when using the standard service plan
	 *  The value should be "$USER" when using the oauth2 service plan
	 */
	void setUser(String user);

	/**
	 * Sets the identity provider name for the user that triggered the audit event.
	 * [NOTE] When using standard plan of the auditlog service you should specify the identity provider (IdP) name yourself. 

	 * When using oauth2 plan of the auditlog service you should write setIdentityProvider("$IDP") and the IdP name will be set automatically on server side.
	 *
	 * @param identityProvider The identity provider where the user is defined.
	 */
	void setIdentityProvider(String identityProvider);

	/**
	 * Sets the tenant that triggered the audit event. 

	 * [NOTE] When using the standard plan of the auditlog service you should specify the tenant yourself - setTenant("tenant-guid-here"). 
	 * [NOTE] When using the oauth2 plan of the auditlog service this method should be used to set the tenant of the message to the PROVIDER tenant
	 * You should write setTenant("$PROVIDER") if you want to log the message for the provider and the tenant will be set automatically on server side. 
	 * If you want to log the message for the subscriber, please use the {@link #setTenant(String tenant, String subscriberTokenIssuer) setTenant(tenant, subscriberTokenIssuer)} method
	 *
	 * @param tenant The value should be the tenant guid when using the standard service plan
	 *  The value should be "$PROVIDER" when using the oauth2 service plan
	 */
	void setTenant(String tenant);

	/**
	 * This method should be used to set the tenant of the message to the SUBSCRIBER tenant ONLY when using the oauth2 service plan of the auditlog service. 

	 * [NOTE] You should write setTenant("$SUBSCRIBER", subscriberTokenIssuer) if you want to log the message for the subscriber and the tenant will be set automatically on server side
	 *
	 * @param tenant The value should be "$SUBSCRIBER".
	 * @param subscriberTokenIssuer The token issuer for the subscriber tenant. E.g.: https://subdomain.authentication.stagingaws.hanavlab.ondemand.com 
	 * The subscriber token issuer should be the token issuer of a real subscribed tenant
	 * The subscriber token issuer should not contain "/oauth/token" as it is automatically added by the XSUAA
	 */
	@Deprecated
	void setTenant(String tenant, String subscriberTokenIssuer);

	/**
	 * Set the tenant of the message to the SUBSCRIBER tenant when using the oauth2 service plan and automatically builds the subscriber token issuer based on the provided subaccount subdomain.
	 * Sets the tenant field to "$SUBSCRIBER"
	 * Sets subscriber token issuer depending on the credential type used. E.g:
	 * "subdomain.authentication.stagingaws.hanavlab.ondemand.com" for client credentials
	 * "subdomain.authentication.cert.stagingaws.hanavlab.ondemand.com" for X509 mTLS
	 * [IMPORTANT] This method replaces setTenant(tenant, subscriberTokenIssuer) and should be used ONLY when writing messages for the SUBSCRIBER tenant.
	 * @param subdomain The subdomain of the subscriber tenant. The subscriber subdomain should be the subdomain of a real subscribed tenant
	 */

	void setTenantBySubscriberSubdomain(String subdomain);

	/**
	 * Set custom specific data.
	 *
	 * @param key Key of custom field
	 * @param value Custom string or json. The value should be represented in a Jackson serializable/deserializable manner.
	 */
	void addCustomDetails(String key, Object value);

	/**
	 * @deprecated Use com.sap.cds.repackaged.audit.api.AuditLogMessage.setEventTime instead
	 * @param time
	 */
	@Deprecated
	void setTime(Instant time);

	/**
	 * @deprecated The UUID is always automatically generated by the service and can't be changed.
	 * @param uuid
	 */
	@Deprecated
	void setUuid(String uuid);

	/**
	 * Set the time of the event which is being logged.
	 *
	 * @param time The time of the event
	 */
	void setEventTime(Instant time);
}